@agent-native/core 0.148.0 → 0.148.1

package/dist/client/blocks/library/diagram.js

@@ -41,7 +41,7 @@ import { RoughOverlay, toggleWireframeStyle, useIsDark, useWireframeStyle, } fro
 /* HTML/SVG diagram path                                                       */
 /* -------------------------------------------------------------------------- */
 /** The rough-overlay selector for diagram bordered boxes (mirrors the plan). */
-const DIAGRAM_ROUGH_SELECTOR = "[data-rough],.diagram-panel,.diagram-node,.diagram-box,.diagram-pill,.diagram-card,[class*='card'],[class*='box'],[class*='panel'],[class*='pill'],[class*='chip'],[class*='badge'],hr";
+const DIAGRAM_ROUGH_SELECTOR = "[data-rough],.diagram-panel,.diagram-node,.diagram-box,.diagram-pill,.diagram-card,.diagram-arrow[data-arrow],[class*='card'],[class*='box'],[class*='panel'],[class*='pill'],[class*='chip'],[class*='badge'],hr";
 function HtmlDiagram({ data, ctx, compact, }) {
     const ref = useRef(null);
     const isDark = useIsDark();

package/dist/client/blocks/library/sanitize-html.js

@@ -30,6 +30,28 @@ const URL_ATTRS = new Set([
     "ping",
 ]);
 const SAFE_SCHEMES = new Set(["http:", "https:", "mailto:", "tel:", "ftp:"]);
+const DIAGRAM_ARROW_DIRECTIONS = new Set([
+    "right",
+    "left",
+    "up",
+    "down",
+    "both",
+    "refresh",
+]);
+const DIAGRAM_ARROW_ENTITY_TEXT = {
+    "→": "→",
+    "←": "←",
+    "↑": "↑",
+    "↓": "↓",
+    "↔": "↔",
+    "←": "←",
+    "↑": "↑",
+    "→": "→",
+    "↓": "↓",
+    "↔": "↔",
+    "➡": "➡",
+    "↻": "↻",
+};
 const WHITESPACE = /\s+/g;
 const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
 const SAFE_DATA_IMAGE = /^data:image\/(png|jpe?g|gif|webp);/i;
@@ -109,6 +131,47 @@ function stripWireframeThemeClasses(value) {
         .filter((className) => !isWireframeThemeClass(className))
         .join(" ");
 }
+function diagramArrowDirection(value) {
+    const normalized = value
+        .replace(/&(?:r|l|u|d|h)arr;|&#(?:8592|8593|8594|8595|8596|8635|10145);/gi, (entity) => DIAGRAM_ARROW_ENTITY_TEXT[entity.toLowerCase()] ?? entity)
+        .replace(/\uFE0F/g, "")
+        .trim();
+    if (DIAGRAM_ARROW_DIRECTIONS.has(normalized))
+        return normalized;
+    if (/[↔⇄⇆⇔]/u.test(normalized))
+        return "both";
+    if (/[←⬅⇐]/u.test(normalized))
+        return "left";
+    if (/[↑⬆⇑]/u.test(normalized))
+        return "up";
+    if (/[↓⬇⇓]/u.test(normalized))
+        return "down";
+    if (/[↻↺⟳⟲]/u.test(normalized))
+        return "refresh";
+    if (/[→➡➜➔➝➞➟➠⇢⇒]/u.test(normalized))
+        return "right";
+    return undefined;
+}
+function normalizeDiagramArrows(root) {
+    root.querySelectorAll(".diagram-arrow").forEach((node) => {
+        const explicit = node.getAttribute("data-arrow");
+        const direction = DIAGRAM_ARROW_DIRECTIONS.has(explicit ?? "")
+            ? explicit
+            : diagramArrowDirection(node.textContent ?? "");
+        if (!direction)
+            return;
+        node.setAttribute("data-arrow", direction);
+        node.replaceChildren();
+    });
+}
+function normalizeFallbackDiagramArrows(html) {
+    return html.replace(/(<(?:div|span)\b[^>]*\bclass\s*=\s*(?:"[^"]*\bdiagram-arrow\b[^"]*"|'[^']*\bdiagram-arrow\b[^']*')[^>]*>)([\s\S]*?)(<\/(?:div|span)>)/gi, (_match, open, body, close) => {
+        const direction = diagramArrowDirection(body);
+        if (!direction)
+            return `${open}${body}${close}`;
+        return `${open.replace(/>$/, ` data-arrow="${direction}">`)}${close}`;
+    });
+}
 /** Conservative no-DOM fallback for any non-browser code path (SSR). */
 function fallbackStrip(html, options) {
     // Drop the whole url attribute if its value (whitespace/control-stripped)
@@ -147,13 +210,14 @@ export function sanitizeDiagramHtml(html) {
     if (!html)
         return "";
     if (typeof DOMParser === "undefined" || typeof document === "undefined") {
-        return fallbackStrip(html)
+        return normalizeFallbackDiagramArrows(fallbackStrip(html)
             .replace(/<\/?\s*(?:math|foreignObject|foreignobject)\b[^>]*>/gi, "")
-            .replace(/\s(?:@[\w:.-]+|x-on:[\w:.-]+|:on[\w:.-]+|x-bind:on[\w:.-]+|:style|x-bind:style)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, "");
+            .replace(/\s(?:@[\w:.-]+|x-on:[\w:.-]+|:on[\w:.-]+|x-bind:on[\w:.-]+|:style|x-bind:style)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, ""));
     }
     const doc = new DOMParser().parseFromString(html, "text/html");
     doc.querySelectorAll(DIAGRAM_BLOCKED_TAGS).forEach((el) => el.remove());
     sanitizeElementAttributes(doc.body, { stripRuntimeDirectives: true });
+    normalizeDiagramArrows(doc.body);
     return doc.body.innerHTML;
 }
 export function sanitizeWireframeCss(css) {

package/dist/client/blocks/library/wireframe-kit.js

@@ -745,6 +745,18 @@ function elementStroke(node, fallback) {
     if (explicit)
         return explicit;
     const cs = getComputedStyle(node);
+    if (node.classList.contains("diagram-arrow")) {
+        const color = cs.color;
+        const normalizedColor = color.replace(/\s+/g, "").toLowerCase();
+        const isTransparent = normalizedColor === "transparent" ||
+            normalizedColor.endsWith("/0)") ||
+            (normalizedColor.startsWith("rgb") &&
+                normalizedColor.split(",").length === 4 &&
+                normalizedColor.endsWith(",0)"));
+        if (color && !isTransparent) {
+            return color;
+        }
+    }
     for (const side of [
         "borderTopColor",
         "borderLeftColor",
@@ -831,6 +843,56 @@ function build(scope, opts) {
         strokeWidth: sw,
         preserveVertices: true,
     });
+    const drawRoughArrow = (direction, x, y, w, h, stroke, sw, seedBase) => {
+        let lineIndex = 0;
+        const drawLine = (x1, y1, x2, y2) => {
+            push(gen.line(x1, y1, x2, y2, makeOpts(stroke, sw, seedFrom(seedBase, "line", lineIndex++))), stroke, sw);
+        };
+        const drawDirectional = (fromX, fromY, toX, toY) => {
+            const angle = Math.atan2(toY - fromY, toX - fromX);
+            const length = Math.hypot(toX - fromX, toY - fromY);
+            const head = Math.min(7, Math.max(4, length * 0.28));
+            const shaftEndX = toX - Math.cos(angle) * head;
+            const shaftEndY = toY - Math.sin(angle) * head;
+            drawLine(fromX, fromY, shaftEndX, shaftEndY);
+            const spread = Math.PI / 6;
+            drawLine(toX, toY, toX - Math.cos(angle - spread) * head, toY - Math.sin(angle - spread) * head);
+            drawLine(toX, toY, toX - Math.cos(angle + spread) * head, toY - Math.sin(angle + spread) * head);
+        };
+        const centerX = x + w / 2;
+        const centerY = y + h / 2;
+        const pad = Math.min(3, w / 5, h / 5);
+        const horizontalFrom = x + pad;
+        const horizontalTo = x + w - pad;
+        const verticalFrom = y + pad;
+        const verticalTo = y + h - pad;
+        if (direction === "refresh") {
+            const diameter = Math.max(8, Math.min(w, h) - pad * 2);
+            const start = -Math.PI * 0.8;
+            const stop = Math.PI * 1.15;
+            push(gen.arc(centerX, centerY, diameter, diameter, start, stop, false, makeOpts(stroke, sw, seedFrom(seedBase, "arc"))), stroke, sw);
+            drawDirectional(x + w - pad - 5, y + pad + 1, x + w - pad, y + pad + 1);
+            return;
+        }
+        if (direction === "down") {
+            drawDirectional(centerX, verticalFrom, centerX, verticalTo);
+            return;
+        }
+        if (direction === "up") {
+            drawDirectional(centerX, verticalTo, centerX, verticalFrom);
+            return;
+        }
+        if (direction === "left") {
+            drawDirectional(horizontalTo, centerY, horizontalFrom, centerY);
+            return;
+        }
+        if (direction === "both") {
+            drawDirectional(horizontalFrom, centerY, horizontalTo, centerY);
+            drawDirectional(horizontalTo, centerY, horizontalFrom, centerY);
+            return;
+        }
+        drawDirectional(horizontalFrom, centerY, horizontalTo, centerY);
+    };
     if (opts.drawFrame && hasDrawableRoughBounds(layoutW, layoutH, 2)) {
         const sw = 2;
         push(gen.path(roundedRectPath(2, 2, layoutW - 4, layoutH - 4, opts.frameRadius), {
@@ -858,6 +920,13 @@ function build(scope, opts) {
             : rawStroke;
         const sw = Number(readVar(node, "--rough-w")) || 1.4;
         const seed = seedFrom(kind, Math.round(x), Math.round(y), Math.round(w), Math.round(h), index++);
+        const arrow = node.classList.contains("diagram-arrow")
+            ? node.getAttribute("data-arrow")
+            : null;
+        if (arrow) {
+            drawRoughArrow(arrow, x, y, w, h, stroke, sw, seedFrom("arrow", seed));
+            return;
+        }
         const o = makeOpts(stroke, sw, seed);
         let drawable;
         if (kind === "ellipse") {

package/dist/client/chat-first/apps-rail.d.ts

@@ -1,2 +1,2 @@
 import type { ChatFirstAppRailProps } from "./types.js";
-export declare function ChatFirstAppsRail({ apps, activeAppId, loading, error, collapsed, layout: controlledLayout, onLayoutChange, onLayoutError, onRetry, onOpenApp, onCreateApp, createAppTrigger, renderIcon, copy, }: ChatFirstAppRailProps): import("react").JSX.Element;
+export declare function ChatFirstAppsRail({ apps, activeAppId, loading, error, collapsed, layout: controlledLayout, onLayoutChange, onLayoutError, onRetry, onOpenApp, onOpenAllApps, onCreateApp, createAppTrigger, renderIcon, copy, }: ChatFirstAppRailProps): import("react").JSX.Element;

package/dist/client/chat-first/apps-rail.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger, Skeleton, Tooltip, TooltipContent, TooltipTrigger, } from "@agent-native/toolkit/ui";
-import { IconChevronDown, IconChevronUp, IconPin, IconPlus, } from "@tabler/icons-react";
+import { IconApps, IconChevronDown, IconChevronUp, IconPin, IconPlus, } from "@tabler/icons-react";
 import { useMemo, useState } from "react";
 import { orderChatFirstAppIds, readChatFirstAppLayout, writeChatFirstAppLayout, } from "../chat-first.js";
 import { cn } from "../utils.js";
@@ -36,7 +36,7 @@ function AppRows({ apps, activeAppId, layout, onDragStart, onDrop, onDragEnd, on
                                     }), "aria-pressed": pinned, title: pinned ? copy("removePinned") : copy("pinTop"), onClick: () => onTogglePinned(app.id), children: _jsx(IconPin, { size: 13, strokeWidth: pinned ? 2.2 : 1.6, "aria-hidden": "true" }) }), _jsx("span", { className: "sr-only", children: `${index + 1} of ${orderedApps.length}` })] }) }), _jsxs(ContextMenuContent, { children: [_jsxs(ContextMenuItem, { onSelect: () => onTogglePinned(app.id), children: [_jsx(IconPin, { size: 14, "aria-hidden": "true" }), pinned ? copy("removePinned") : copy("pinTop")] }), _jsx(ContextMenuSeparator, {}), _jsxs(ContextMenuItem, { disabled: index === 0, onSelect: () => onMove(app.id, -1), children: [_jsx(IconChevronUp, { size: 14, "aria-hidden": "true" }), copy("moveUp")] }), _jsxs(ContextMenuItem, { disabled: index === orderedApps.length - 1, onSelect: () => onMove(app.id, 1), children: [_jsx(IconChevronDown, { size: 14, "aria-hidden": "true" }), copy("moveDown")] })] })] }, app.id));
         }) }));
 }
-export function ChatFirstAppsRail({ apps, activeAppId, loading = false, error, collapsed = false, layout: controlledLayout, onLayoutChange, onLayoutError, onRetry, onOpenApp, onCreateApp, createAppTrigger, renderIcon, copy = defaultChatFirstCopy, }) {
+export function ChatFirstAppsRail({ apps, activeAppId, loading = false, error, collapsed = false, layout: controlledLayout, onLayoutChange, onLayoutError, onRetry, onOpenApp, onOpenAllApps, onCreateApp, createAppTrigger, renderIcon, copy = defaultChatFirstCopy, }) {
     const [localLayout, setLocalLayout] = useState(() => readChatFirstAppLayout());
     const layout = controlledLayout ?? localLayout;
     const [draggedAppId, setDraggedAppId] = useState(null);
@@ -97,7 +97,7 @@ export function ChatFirstAppsRail({ apps, activeAppId, loading = false, error, c
                     ? [0, 1, 2].map((index) => (_jsx(Skeleton, { className: "size-9 rounded-md" }, index)))
                     : visibleApps.map((app) => (_jsx("button", { type: "button", "data-chat-first-app": true, "data-app-id": app.id, className: cn("flex size-9 items-center justify-center rounded-md transition-colors", activeAppId === app.id
                             ? "bg-sidebar-accent text-sidebar-accent-foreground"
-                            : "text-sidebar-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"), onClick: () => onOpenApp(app), "aria-label": copy("openApp", { name: app.name }), title: app.name, children: renderIcon(app) }, app.id))), error ? (_jsx("span", { className: "size-1.5 rounded-full bg-destructive", title: error, "aria-label": error })) : null] }));
+                            : "text-sidebar-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"), onClick: () => onOpenApp(app), "aria-label": copy("openApp", { name: app.name }), title: app.name, children: renderIcon(app) }, app.id))), onOpenAllApps ? (_jsx("button", { type: "button", "data-chat-first-all-apps": true, className: "flex size-9 items-center justify-center rounded-md text-sidebar-foreground/70 transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground", onClick: onOpenAllApps, "aria-label": copy("allApps"), title: copy("allApps"), children: _jsx(IconApps, { size: 16, "aria-hidden": "true" }) })) : null, error ? (_jsx("span", { className: "size-1.5 rounded-full bg-destructive", title: error, "aria-label": error })) : null] }));
     }
-    return (_jsxs("section", { "data-chat-first-apps-rail": true, className: "mt-3 px-2 pb-2 pt-2", "aria-label": copy("workspaceApps"), children: [_jsxs("div", { className: "mb-1 flex items-center gap-1.5 px-1 text-[11px] font-medium text-sidebar-foreground/50", children: [_jsx("span", { children: copy("workspaceApps") }), _jsx("span", { className: "ml-auto", children: createTrigger })] }), loading && apps.length === 0 ? (_jsx("div", { className: "space-y-0.5 px-1", children: [0, 1, 2].map((index) => (_jsx(Skeleton, { className: "h-7 w-full rounded-md" }, index))) })) : apps.length === 0 ? (_jsxs("div", { className: "px-1", children: [_jsx("p", { className: "text-xs text-sidebar-foreground/55", children: copy("noWorkspaceApps") }), createAppTrigger ? (createTrigger) : onCreateApp ? (_jsxs("button", { type: "button", className: "mt-1 inline-flex h-6 items-center gap-1.5 rounded-md border border-sidebar-border px-2 text-xs text-sidebar-foreground/75 hover:bg-sidebar-accent hover:text-sidebar-foreground", onClick: onCreateApp, children: [_jsx(IconPlus, { size: 13, "aria-hidden": "true" }), copy("createApp")] })) : (createTrigger)] })) : (_jsx(AppRows, { apps: visibleApps, activeAppId: activeAppId, layout: layout, onDragStart: setDraggedAppId, onDrop: reorderApps, onDragEnd: () => setDraggedAppId(null), onOpenApp: onOpenApp, onTogglePinned: togglePinned, onMove: moveApp, renderIcon: renderIcon, copy: copy })), hasMoreApps || showAllApps ? (_jsxs("button", { type: "button", className: "mt-0.5 flex h-6 w-full items-center gap-2 rounded-md px-2 text-xs text-sidebar-foreground/50 hover:bg-sidebar-accent hover:text-sidebar-foreground", onClick: () => setShowAllApps((value) => !value), children: [showAllApps ? (_jsx(IconChevronUp, { size: 14, "aria-hidden": "true" })) : (_jsx(IconChevronDown, { size: 14, "aria-hidden": "true" })), showAllApps ? copy("showLess") : copy("showMore")] })) : null, error ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs("button", { type: "button", className: "mt-1 flex items-center gap-1 px-1 text-[10px] text-destructive/80", onClick: onRetry, "aria-label": error, children: [_jsx("span", { className: "size-1.5 rounded-full bg-destructive" }), onRetry ? copy("retry") : copy("appsLoadError")] }) }), _jsx(TooltipContent, { side: "right", children: error })] })) : null] }));
+    return (_jsxs("section", { "data-chat-first-apps-rail": true, className: "mt-3 px-2 pb-2 pt-2", "aria-label": copy("workspaceApps"), children: [_jsxs("div", { className: "mb-1 flex items-center gap-1.5 px-1 text-[11px] font-medium text-sidebar-foreground/50", children: [_jsx("span", { children: copy("workspaceApps") }), _jsx("span", { className: "ml-auto", children: createTrigger })] }), loading && apps.length === 0 ? (_jsx("div", { className: "space-y-0.5 px-1", children: [0, 1, 2].map((index) => (_jsx(Skeleton, { className: "h-7 w-full rounded-md" }, index))) })) : apps.length === 0 ? (_jsxs("div", { className: "px-1", children: [_jsx("p", { className: "text-xs text-sidebar-foreground/55", children: copy("noWorkspaceApps") }), createAppTrigger ? (createTrigger) : onCreateApp ? (_jsxs("button", { type: "button", className: "mt-1 inline-flex h-6 items-center gap-1.5 rounded-md border border-sidebar-border px-2 text-xs text-sidebar-foreground/75 hover:bg-sidebar-accent hover:text-sidebar-foreground", onClick: onCreateApp, children: [_jsx(IconPlus, { size: 13, "aria-hidden": "true" }), copy("createApp")] })) : (createTrigger)] })) : (_jsx(AppRows, { apps: visibleApps, activeAppId: activeAppId, layout: layout, onDragStart: setDraggedAppId, onDrop: reorderApps, onDragEnd: () => setDraggedAppId(null), onOpenApp: onOpenApp, onTogglePinned: togglePinned, onMove: moveApp, renderIcon: renderIcon, copy: copy })), hasMoreApps || showAllApps ? (_jsxs("button", { type: "button", className: "mt-0.5 flex h-6 w-full items-center gap-2 rounded-md px-2 text-xs text-sidebar-foreground/50 hover:bg-sidebar-accent hover:text-sidebar-foreground", onClick: () => setShowAllApps((value) => !value), children: [showAllApps ? (_jsx(IconChevronUp, { size: 14, "aria-hidden": "true" })) : (_jsx(IconChevronDown, { size: 14, "aria-hidden": "true" })), showAllApps ? copy("showLess") : copy("showMore")] })) : null, onOpenAllApps ? (_jsx("div", { className: "mt-1 border-t border-sidebar-border/60 pt-1", children: _jsxs("button", { type: "button", "data-chat-first-all-apps": true, className: "flex h-7 w-full items-center gap-2 rounded-md px-2 text-xs text-sidebar-foreground/55 hover:bg-sidebar-accent hover:text-sidebar-foreground", onClick: onOpenAllApps, children: [_jsx(IconApps, { size: 14, "aria-hidden": "true" }), _jsx("span", { children: copy("allApps") })] }) })) : null, error ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs("button", { type: "button", className: "mt-1 flex items-center gap-1 px-1 text-[10px] text-destructive/80", onClick: onRetry, "aria-label": error, children: [_jsx("span", { className: "size-1.5 rounded-full bg-destructive" }), onRetry ? copy("retry") : copy("appsLoadError")] }) }), _jsx(TooltipContent, { side: "right", children: error })] })) : null] }));
 }

package/dist/client/chat-first/copy.js

@@ -2,6 +2,7 @@ const DEFAULT_COPY = {
     newChat: "New chat",
     search: "Search",
     workspaceApps: "Apps",
+    allApps: "All apps",
     integrations: "Integrations",
     scheduled: "Scheduled",
     createWorkspaceApp: "Create app",

package/dist/client/chat-first/types.d.ts

@@ -44,6 +44,7 @@ export interface ChatFirstAppRailProps {
     onLayoutError?: (reason: "unavailable" | "write-failed") => void;
     onRetry?: () => void;
     onOpenApp: (app: ChatFirstAppItem) => void;
+    onOpenAllApps?: () => void;
     onCreateApp?: () => void;
     createAppTrigger?: ReactNode;
     renderIcon: (app: ChatFirstAppItem) => ReactNode;

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,23 +41,23 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    ok?: undefined;
     error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
     error?: undefined;
     summary?: undefined;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/styles/blocks.css

@@ -1333,6 +1333,138 @@
   direction: inherit;
 }
 
+/* Diagram arrows are geometry, not text glyphs. The clean path draws these
+   shapes with CSS; sketchy mode replaces them with the rough.js paths below. */
+.plan-diagram-frame :is(.diagram-arrow[data-arrow]) {
+  position: relative;
+  display: inline-block;
+  flex: 0 0 28px;
+  width: 28px;
+  height: 24px;
+  min-width: 28px;
+  font-size: 0 !important;
+  line-height: 1;
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow]::before,
+.plan-diagram-frame .diagram-arrow[data-arrow]::after {
+  position: absolute;
+  display: block;
+  content: "";
+  pointer-events: none;
+}
+
+.plan-diagram-frame
+  :is(
+    .diagram-arrow[data-arrow="right"],
+    .diagram-arrow[data-arrow="left"]
+  )::before {
+  top: calc(50% - 0.75px);
+  left: 3px;
+  width: 22px;
+  height: 1.5px;
+  background: currentColor;
+}
+
+.plan-diagram-frame
+  :is(
+    .diagram-arrow[data-arrow="up"],
+    .diagram-arrow[data-arrow="down"]
+  )::before {
+  top: 2px;
+  left: calc(50% - 0.75px);
+  width: 1.5px;
+  height: 20px;
+  background: currentColor;
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="right"]::after,
+.plan-diagram-frame .diagram-arrow[data-arrow="left"]::after,
+.plan-diagram-frame .diagram-arrow[data-arrow="up"]::after,
+.plan-diagram-frame .diagram-arrow[data-arrow="down"]::after {
+  width: 7px;
+  height: 7px;
+  border-top: 1.5px solid currentColor;
+  border-right: 1.5px solid currentColor;
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="right"]::after {
+  top: calc(50% - 4px);
+  right: 2px;
+  transform: rotate(45deg);
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="left"]::after {
+  top: calc(50% - 4px);
+  left: 2px;
+  transform: rotate(225deg);
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="up"]::after {
+  top: 0;
+  left: calc(50% - 4px);
+  transform: rotate(-45deg);
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="down"]::after {
+  bottom: 0;
+  left: calc(50% - 4px);
+  transform: rotate(135deg);
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="both"]::before {
+  top: calc(50% - 0.75px);
+  left: 3px;
+  width: 22px;
+  height: 1.5px;
+  background: currentColor;
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="both"]::after {
+  inset: 3px;
+  background: currentColor;
+  clip-path: polygon(
+    0 50%,
+    22% 0,
+    22% 38%,
+    78% 38%,
+    78% 0,
+    100% 50%,
+    78% 100%,
+    78% 62%,
+    22% 62%,
+    22% 100%
+  );
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="refresh"]::before {
+  top: 3px;
+  left: 5px;
+  width: 16px;
+  height: 16px;
+  border: 1.5px solid currentColor;
+  border-left-color: transparent;
+  border-radius: 50%;
+}
+
+.plan-diagram-frame .diagram-arrow[data-arrow="refresh"]::after {
+  top: 1px;
+  right: 2px;
+  width: 0;
+  height: 0;
+  border-right: 4px solid transparent;
+  border-bottom: 7px solid currentColor;
+  border-left: 4px solid transparent;
+  transform: rotate(35deg);
+}
+
+.plan-diagram-frame[data-style="sketchy"][data-rough-ready]
+  .diagram-arrow[data-arrow]::before,
+.plan-diagram-frame[data-style="sketchy"][data-rough-ready]
+  .diagram-arrow[data-arrow]::after {
+  opacity: 0;
+}
+
 .plan-diagram-frame[data-frame="show"] .plan-diagram-frame-content {
   padding: 0;
 }

package/docs/content/actions.mdx

@@ -391,12 +391,15 @@ export default defineAction({
   description: "Create a lead in the CRM.",
   schema: z.object({ name: z.string(), company: z.string() }),
   run: async ({ name, company }, ctx) => {
+    if (!ctx?.userEmail) {
+      throw new Error("An authenticated user is required.");
+    }
     const db = getDb();
     await db.insert(schema.leads).values({
       id: crypto.randomUUID(),
       name,
       company,
-      ownerEmail: ctx?.userEmail ?? "system",
+      ownerEmail: ctx.userEmail,
     });
     return { ok: true };
   },

package/docs/content/agent-surfaces.mdx

@@ -10,7 +10,7 @@ A **surface** is the way users (or other systems) interact with your app: a chat
 
 ## How surfaces relate to each other
 
-The four main product shapes sit on a spectrum from most interactive to fully headless. What makes them composable is that the foundation stays the same throughout: the same actions, the same SQL database, and the same agent loop power every shape. Adding a new surface doesn't mean rewriting what's underneath — you're just adding a new way to reach the same operations.
+The four main product shapes sit on a spectrum from most interactive to fully headless. What makes them composable is that they share the same actions and SQL-backed app state. Use the framework agent loop when a surface needs an agent. Adding a new surface doesn't mean rewriting what's underneath — you're adding a new way to reach the same operations.
 
 <Diagram id="doc-block-hvdxgh" title="The surface spectrum" summary={"One action surface, four product shapes, each adding UI without changing the operation underneath."}>
 
@@ -37,7 +37,9 @@ The four main product shapes sit on a spectrum from most interactive to fully he
   </div>
 </div>
 <div class="diagram-base" data-rough>
-  <span class="diagram-muted">same actions · same SQL · same agent loop</span>
+  <span class="diagram-muted"
+    >same actions · SQL-backed state · agent loop where used</span
+  >
 </div>
 ```
 
@@ -192,7 +194,7 @@ Full apps add product UI around the same action and agent contract:
 
 ### SQL state
 
-App data, navigation, settings, and chat history are all durable. The agent reads and writes the same rows the UI does.
+App data, navigation, settings, and chat history are durable in SQL. The agent reads and writes the same rows the UI does.
 
 ### Context awareness
 
@@ -200,7 +202,7 @@ The agent knows the current route, selection, and focused object, so "edit this"
 
 ### Live sync
 
-Agent changes update the UI in real time, and UI changes update the agent's context. No polling, no refresh.
+Agent changes update the UI through live sync, and UI changes update the agent's context. The framework uses SSE with polling fallback, so users do not need to refresh manually.
 
 ### Deep links
 
@@ -224,9 +226,9 @@ want a complete product shape.
 
 Every Agent-Native app eventually needs a place where users can configure their agent: set standing instructions, review what it's done, connect MCP servers, manage automations, and control access. Building that UI from scratch is a lot of work. Agent-Native ships a pre-built full-page component, `AgentTabsPage`, that covers all of it across twelve tabs.
 
-Mount it at `/agent` in your app. Current templates pair that route with an app-navigation entry and pass `agentPageHref="/agent"` to `AgentSidebar`, so the sidebar's Resources and Settings modes can link to the full page without duplicating those flows.
+Mount it at `/settings/agent` in your app. Current templates use this as the canonical route and pass `agentPageHref="/settings/agent"` to `AgentSidebar`. `/agent` is kept as a legacy redirect.
 
-```tsx filename="app/routes/agent.tsx"
+```tsx filename="app/routes/settings.agent.tsx"
 import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
 export default function AgentRoute() {
   return <AgentTabsPage />;

package/docs/content/automations.mdx

@@ -214,7 +214,7 @@ emit(
     customerEmail: "jane@example.com",
     total: 49.99,
   },
-  { owner: "steve@builder.io" },
+  { owner: "user@example.com" },
 );
 ```
 

package/docs/content/database.mdx

@@ -267,7 +267,12 @@ All database schema updates must be **strictly additive**.
 
 ### Safe Migration Path
 
-Instead of pushing directly, schema changes should be applied via SQL migrations executed at application startup. Implement additive migrations within a server plugin (e.g., `server/plugins/db.ts`) by invoking the framework's `runMigrations()` helper:
+Instead of pushing directly, schema changes should be applied via additive SQL
+migrations. For local development, implement them in a server plugin (e.g.
+`server/plugins/db.ts`) by invoking the framework's `runMigrations()` helper.
+For production or serverless deployments, run migrations in a release or deploy
+step instead of on the first request. The Chat template provides
+`pnpm migrate:production` for this.
 
 <AnnotatedCode
   id="doc-block-zaaj7e"

package/docs/content/docs-components.mdx

@@ -105,7 +105,7 @@ pnpm install
 pnpm dev
 ```
 
-Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+Open the local URL shown by the dev server. The app is ready when **VITE ready** appears in the terminal.
 
 ### Sign in
 
@@ -130,7 +130,7 @@ pnpm install
 pnpm dev
 ```
 
-Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+Open the local URL shown by the dev server. The app is ready when **VITE ready** appears in the terminal.
 
 ### Sign in
 
@@ -215,13 +215,13 @@ Use `Notice` when a `Callout` would be too easy to skim past — something the r
 
 <Banner
   tone="warning"
-  body="This page describes the v9 API. See [Migrating to v10](/docs/migrating-v10) for what changed."
+  body="This page describes a beta API. Check the release notes before using it."
 />
 
 ```mdx
 <Banner
   tone="warning"
-  body="This page describes the v9 API. See [Migrating to v10](/docs/migrating-v10) for what changed."
+  body="This page describes a beta API. Check the release notes before using it."
 />
 ```
 
@@ -377,13 +377,17 @@ Use a fenced code block with the `mermaid` language tag. Mermaid supports flowch
       note: "New action — callable from agent, UI, and CLI",
     },
     { path: "actions/list-text-analyses.ts", change: "added" },
-    { path: "app/routes/analyses.tsx", change: "modified" },
+    { path: "app/routes/analyses.tsx", change: "added" },
     {
-      path: "app/config/nav.ts",
-      change: "modified",
-      note: "Add the new route to the sidebar nav",
+      path: "server/db/schema.ts",
+      change: "added",
+      note: "Define the app-owned table",
+    },
+    {
+      path: "server/plugins/db.ts",
+      change: "added",
+      note: "Run additive migrations",
     },
-    { path: "db/migrations/001_analyses.sql" },
   ]}
 />
 
@@ -397,13 +401,17 @@ Use a fenced code block with the `mermaid` language tag. Mermaid supports flowch
       note: "New action — callable from agent, UI, and CLI",
     },
     { path: "actions/list-text-analyses.ts", change: "added" },
-    { path: "app/routes/analyses.tsx", change: "modified" },
+    { path: "app/routes/analyses.tsx", change: "added" },
     {
-      path: "app/config/nav.ts",
-      change: "modified",
-      note: "Add the new route to the sidebar nav",
+      path: "server/db/schema.ts",
+      change: "added",
+      note: "Define the app-owned table",
+    },
+    {
+      path: "server/plugins/db.ts",
+      change: "added",
+      note: "Run additive migrations",
     },
-    { path: "db/migrations/001_analyses.sql" },
   ]}
 />
 ```

package/docs/content/drop-in-agent.mdx

@@ -170,7 +170,7 @@ export default function AgentRoute() {
 }
 ```
 
-`<AgentPanel>` gives you the raw tabs (Chat / CLI / Resources) without the sidebar wrapper, the collapse button, or any state persistence. Put it wherever you want; you handle the layout.
+`<AgentPanel>` gives you the raw tabs (Chat / CLI / Resources) without the sidebar wrapper or the collapse button. Put it wherever you want; you control the surrounding layout.
 
 ### Selected props
 

package/docs/content/getting-started-actions.mdx

@@ -72,7 +72,7 @@ export default defineAction({
 });
 ```
 
-Run it from the terminal:
+Run this from the app directory:
 
 ```bash
 pnpm action analyze-text --text "Hello world. How are you today?"
@@ -82,9 +82,10 @@ Or ask the agent in chat:
 
 > Run the analyze-text action on "Hello world. How are you today?"
 
-The built-in `data-chart` renderer turns the structured result into a chart in
-the transcript. There is no renderer file or `app/root.tsx` import to add. For
-custom native components, see [Native Chat UI](/docs/native-chat-ui).
+When the agent runs this action in chat, the built-in `data-chart` renderer
+turns the structured result into a chart in the transcript. There is no renderer
+file or `app/root.tsx` import to add. For custom native components, see
+[Native Chat UI](/docs/native-chat-ui).
 
 ## Continue
 

package/docs/content/getting-started-pages.mdx

@@ -6,14 +6,15 @@ description: "Build a React route that calls your action and displays its result
 # Add a Page
 
 This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions)
-you created `analyze-text`. Here you'll call that same action from a route. No
-database is needed yet: Chat already includes the SQL runtime for when you need
-to persist domain data.
+you created `analyze-text`. Here you'll call that same action from a route. This
+example does not need a new database table. Chat already stores chat history in
+SQL; add your own tables when you need to persist domain data.
 
 ## Create the route {#add-a-page}
 
-Route files in `app/routes/` are picked up automatically. Create
-`app/routes/text-analyses.tsx`; it will be available at
+The dev server reads route files when it starts. Create
+`app/routes/text-analyses.tsx`, then restart `pnpm dev` if it is already
+running. The route will be available at
 `http://localhost:8080/text-analyses`.
 
 ```tsx filename="app/routes/text-analyses.tsx"
@@ -58,7 +59,7 @@ export default function TextAnalysesRoute() {
 ```
 
 `useActionQuery` calls the same read-only action the agent uses. The page does
-not need a custom API route, a second data layer, or SQL yet.
+not need a custom API route, a second data layer, or a new SQL table.
 
 Open `http://localhost:8080/text-analyses`, or ask the agent:
 

package/docs/content/getting-started.mdx

@@ -6,9 +6,9 @@ description: "Create a Chat app and configure an agent, then extend it with an a
 # Getting Started
 
 Agent-Native apps give the agent and the UI the same [actions](/docs/actions),
-SQL data, and application state. This is the hands-on path: start with chat,
-then add an action and a page. SQL is already configured in Chat and becomes an
-optional next step when results need to persist.
+SQL data, and application state. This path starts with Chat, which already
+creates the framework tables it needs and stores chat history in local SQLite by
+default. Add your own tables only when your app needs to persist domain data.
 
 <Steps>
 
@@ -65,4 +65,5 @@ Once the agent responds, continue with [Add an Action](/docs/getting-started-act
 
 - [What Is Agent-Native?](/docs/what-is-agent-native): the architecture behind this path.
 - [Chat Template](/docs/template-chat): what the starter app includes.
+- [Database](/docs/database): add app-owned tables when your app needs domain data.
 - [FAQ](/docs/faq): answers about models, hosting, and templates.

package/docs/content/notifications.mdx

@@ -14,7 +14,7 @@ import { notify } from "@agent-native/core/notifications";
 
 await notify(
   { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
-  { owner: "steve@builder.io" },
+  { owner: "user@example.com" },
 );
 ```
 
@@ -238,14 +238,14 @@ import {
   deleteNotification,
 } from "@agent-native/core/notifications";
 
-const rows = await listNotifications("steve@builder.io", {
+const rows = await listNotifications("user@example.com", {
   unreadOnly: true,
   limit: 50,
 });
-const unread = await countUnread("steve@builder.io");
-await markNotificationRead(rows[0].id, "steve@builder.io");
-await markAllNotificationsRead("steve@builder.io");
-await deleteNotification(rows[0].id, "steve@builder.io");
+const unread = await countUnread("user@example.com");
+await markNotificationRead(rows[0].id, "user@example.com");
+await markAllNotificationsRead("user@example.com");
+await deleteNotification(rows[0].id, "user@example.com");
 ```
 
 Each function is owner-scoped — no cross-user reads, no cross-user writes.

package/docs/content/progress.mdx

@@ -15,7 +15,7 @@ import {
 } from "@agent-native/core/progress";
 
 const run = await startRun({
-  owner: "steve@builder.io",
+  owner: "user@example.com",
   title: "Triage 128 unread emails",
   step: "Fetching inbox",
 });
@@ -100,7 +100,7 @@ Create a run. Returns the full `AgentRun` with a generated id.
 
 ```ts
 const run = await startRun({
-  owner: "steve@builder.io",
+  owner: "user@example.com",
   title: "Ingest 1M rows",
   step: "Opening CSV",
   metadata: { jobId: "abc123", artifactPath: "s3://..." },
@@ -140,9 +140,9 @@ Also emits `run.progress.updated` with the terminal status.
 ```ts
 import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
 
-const active = await listRuns("steve@builder.io", { activeOnly: true });
-const run = await getRun("run-id", "steve@builder.io");
-await deleteRun("run-id", "steve@builder.io");
+const active = await listRuns("user@example.com", { activeOnly: true });
+const run = await getRun("run-id", "user@example.com");
+await deleteRun("run-id", "user@example.com");
 ```
 
 ## HTTP API {#http}

package/docs/content/routing.mdx

@@ -82,7 +82,9 @@ export default function SettingsPage() {
 }
 ```
 
-That's it — React Router picks it up automatically, no registration needed.
+That's it — React Router picks it up automatically after the route table is
+rebuilt. If `pnpm dev` is already running, restart it after adding the file. No
+registration is needed.
 
 ## Dynamic params {#dynamic-params}
 

package/docs/content/server-database.mdx

@@ -5,7 +5,7 @@ description: "Connect a portable SQL database to your agent-native app: schema h
 
 # Database
 
-Every agent-native app stores its state in SQL. The UI and the agent both read and write the same tables through the same actions, using the same [Drizzle ORM](https://orm.drizzle.team) client. When either side changes data, the other sees it through the polling layer.
+Every agent-native app stores its state in SQL. The UI and the agent both read and write the same tables through the same actions, using the same [Drizzle ORM](https://orm.drizzle.team) client. Live sync uses SSE with polling fallback, so changes appear in the other surface without a manual refresh.
 
 <Diagram id="doc-block-9mtx2f" title="How data flows to the database" summary="The UI and the agent both reach the database through the same Actions layer. Both callers use the same getDb() client and the same SQL tables. There is no separate backend for each.">
 
@@ -110,7 +110,7 @@ An app that uses the database needs three files:
 
 - `server/db/schema.ts`: table definitions
 - `server/db/index.ts`: the typed DB client singleton
-- `server/plugins/db.ts`: migrations that run at startup
+- `server/plugins/db.ts`: app-owned migrations for local startup
 
 ### 1. Define your schema {#schema}
 
@@ -208,7 +208,8 @@ Import `getDb` from this template-local path in actions and routes. Do not impor
 
 ### 3. Write migrations {#migrations}
 
-Schema changes are applied at startup via a Nitro plugin in `server/plugins/db.ts`. Use `runMigrations` from `@agent-native/core/db`:
+For local development, schema changes can run through a Nitro plugin in
+`server/plugins/db.ts`. Use `runMigrations` from `@agent-native/core/db`:
 
 <AnnotatedCode
   id="doc-block-7qwlpz"
@@ -242,7 +243,15 @@ Schema changes are applied at startup via a Nitro plugin in `server/plugins/db.t
   ]}
 />
 
-`runMigrations` runs each entry in order once, then records the version so it is skipped on future restarts. Entries are idempotent. The plugin is safe to call on every boot.
+`runMigrations` runs each pending entry in order once, records it as applied, and
+skips it on later runs. Give new entries a stable `name`; named migrations are
+tracked independently of their version number.
+
+<Callout tone="warning">
+  For production or serverless deployments, run migrations in a release or
+  deploy step instead of on the first request. The Chat template provides `pnpm
+  migrate:production` for this.
+</Callout>
 
 <Callout tone="warning">
   Give every new migration a stable `name` (e.g. `{ version: 4, name:

package/docs/content/server-overview.mdx

@@ -85,7 +85,7 @@ The `server/` directory is the infrastructure layer of an agent-native app. It h
 
 ## 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.
+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: apply app-owned 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">
 
@@ -194,19 +194,19 @@ Browser requests, the agent loop, and external API clients all route through the
 
 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 |
+| 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)**       | Startup plugins for auth and agent-chat, plus optional app-owned database migrations |
+| **[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.
+- **Plugins**: code registered at server startup and loaded once. Framework helpers initialize auth and the agent-chat mount; optional app-owned database migrations may still be running when the first request arrives. 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).
@@ -230,5 +230,5 @@ Use custom `/api/*` routes only when you need a route-shaped protocol or binary/
 - [**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
+- [**Plugins**](/docs/server-plugins): startup plugins for auth, the agent, and optional app-owned migrations
 - [**Routes**](/docs/server-routes): file-based routes, request context, and the SSR catch-all

package/docs/content/server-plugins.mdx

@@ -5,7 +5,7 @@ description: "Startup plugins in server/plugins/ — what they are, the two plug
 
 # 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.
+Plugins are startup hooks. Nitro loads each file in `server/plugins/` once when the server initializes. They are the right place for one-time setup: configuring auth, mounting the agent loop, running database migrations, or registering other initialization code. Framework helpers coordinate their async setup; custom plugin work may still be in flight when the first request arrives.
 
 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.
 
@@ -21,7 +21,7 @@ Apps that need custom database tables add a third:
 
 ```text
 server/plugins/
-  db.ts          -> run migrations on startup
+  db.ts          -> register app-owned migrations for local startup
 ```
 
 ## Auth Plugin {#auth-plugin}
@@ -80,7 +80,7 @@ screen when context matters.`,
 
 ## 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`:
+If your app defines custom database tables, add `server/plugins/db.ts` to register schema migrations for local startup. It uses `runMigrations` from `@agent-native/core/db`:
 
 ```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
@@ -110,6 +110,12 @@ Each entry needs a `version` number and a `sql` string. Give it a stable `name`
   TABLE ... DROP COLUMN`, `DELETE FROM`) in startup plugins.
 </Callout>
 
+<Callout tone="warning">
+  For production or serverless deployments, run migrations in a release or
+  deploy step instead of on the first request. The Chat template provides `pnpm
+  migrate:production` for this.
+</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`:
@@ -142,6 +148,6 @@ If you add custom plugins, prefix their filenames to control invocation order, b
 
 - [**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
+- [**Routes**](/docs/server-routes): custom file routes and when to use them
 - [**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

@@ -77,7 +77,12 @@ export default defineEventHandler(async (event) => {
   }
 
   const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
-  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+  const signatureBytes = Buffer.from(signature, "utf8");
+  const expectedBytes = Buffer.from(expected, "utf8");
+  if (
+    signatureBytes.length !== expectedBytes.length ||
+    !timingSafeEqual(signatureBytes, expectedBytes)
+  ) {
     throw createError({ statusCode: 401, statusMessage: "Invalid signature" });
   }
 
@@ -189,6 +194,6 @@ Every SSR response is an impersonal, public shell cached at the CDN. Never read
 ## 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
+- [**Plugins**](/docs/server-plugins): startup plugins and their initialization behavior
 - [**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/docs/content/tracking.mdx

@@ -15,7 +15,7 @@ import { track } from "@agent-native/core/tracking";
 track(
   "order.completed",
   { total: 49.99, items: 3 },
-  { userId: "steve@builder.io" },
+  { userId: "user@example.com" },
 );
 ```
 
@@ -126,7 +126,7 @@ import { track } from "@agent-native/core/tracking";
 track(
   "meal.logged",
   { mealName: "Salad", calories: 350 },
-  { userId: "steve@builder.io" },
+  { userId: "user@example.com" },
 );
 ```
 
@@ -150,7 +150,7 @@ Identify a user with traits. Forwarded to providers that support it (PostHog, Mi
 ```ts
 import { identify } from "@agent-native/core/tracking";
 
-identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+identify("user@example.com", { plan: "pro", company: "Builder.io" });
 ```
 
 Need a custom backend, the provider-registry API, or the batching/singleton internals? See [Advanced: custom providers & internals](#advanced) at the end.
@@ -391,5 +391,5 @@ The framework also tracks `builder connect clicked` from Connect Builder CTAs, a
 ## What's next
 
 - [**Actions**](/docs/actions) — where most tracking calls originate
-- [**Server Plugins**](/docs/server#server-plugins) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
+- [**Server Plugins**](/docs/server-plugins) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
 - [**Security — Secrets Management**](/docs/security#secrets) — manage API keys for tracking providers

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

@@ -39,7 +39,7 @@ The UI updates in real time as the agent opens views, edits drafts, and runs rep
 
 ### Steer it like a teammate
 
-Give feedback, queue tasks, audit what it did, edit its instructions. It remembers, and it improves.
+Give feedback, queue tasks, audit what it did, and edit its instructions.
 
 </Cards>
 
@@ -93,7 +93,7 @@ graph TD
   DB --> AG_OUT
 ```
 
-The diagram above shows what this looks like at runtime: both the user and the agent submit actions to the same layer, which writes to the same database and broadcasts updates back to both surfaces. When the agent creates a draft email, it appears in your inbox immediately. When you click Send, the agent knows it was sent. See [Key Concepts](/docs/key-concepts) for the full architecture.
+The diagram above shows what this looks like at runtime: both the user and the agent submit actions to the same layer, which writes to the same database and sends updates back to both surfaces. When the agent creates a draft email, it appears in your inbox immediately. When you click Send, the agent knows it was sent. See [Key Concepts](/docs/key-concepts) for the full architecture.
 
 ## Why agents need a UI — and apps need an agent {#why-both}
 
@@ -211,7 +211,7 @@ Browse [agent-native.com/templates](/templates) and pick the one closest to what
 
 ### Use it immediately
 
-Every template deploys as a hosted app (e.g. `mail.agent-native.com`). Try it before you touch any code.
+Many first-party templates are available as hosted apps (e.g. `mail.agent-native.com`). Try one before you touch any code.
 
 ### Clone and customize
 
@@ -235,7 +235,7 @@ Agent-native apps can talk to each other. From inside the mail app, you can tag
 
 ### [Getting Started](/docs/getting-started)
 
-Build a working chat app in under five minutes, then add actions, a database, and a page.
+Build a working chat app in under five minutes, then add an action and a page. Add your own database tables when you need to persist domain data.
 
 ### [Key Concepts](/docs/key-concepts)
 

package/package.json

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