@agent-native/core 0.63.2 → 0.63.4

package/docs/content/client.md

@@ -15,6 +15,13 @@ For file-based routing — adding pages, dynamic params, and navigation — see
 
 The primary way to read and write app data from the browser is through the action hooks. Never hand-write `fetch` calls to `/_agent-native/*` routes — use the named helpers instead (see [Actions](/docs/actions)).
 
+```an-diagram title="The browser data loop" summary="Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."
+{
+  "html": "<div class=\"diagram-client\"><div class=\"diagram-col\"><div class=\"diagram-node\">useActionQuery<br><small class=\"diagram-muted\">cached read</small></div><div class=\"diagram-node\">useActionMutation<br><small class=\"diagram-muted\">write + invalidate</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-box\" data-rough>Actions<br><small class=\"diagram-muted\">/_agent-native/actions/*</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">useDbSync &rarr; refetch on change</div></div>",
+  "css": ".diagram-client{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-client .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-client .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 ```tsx
 import {
   useActionQuery,
@@ -354,6 +361,13 @@ function DashboardView({ id }) {
 - **UI-Initiated mutations:** When you execute an action from the UI using `useActionMutation`, the mutation immediately fires a local event with `source: "action"` on success. This triggers an **instant, optimistic refetch** of all query keys depending on that action, avoiding visual delay.
 - **Background or Agent Mutations:** When the AI agent, a webhook, or a background worker mutates data, the update is broadcast to the client. The client's `useDbSync` captures this either instantly over SSE (Server-Sent Events) or falls back to the **2-second polling tick**. The query key version then bumps, triggering a background refetch.
 
+```an-diagram title="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">This tab</span><strong>useActionMutation</strong><small class=\"diagram-muted\">fires source: \"action\" on success &rarr; instant local refetch</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Agent · webhook · other tab</span><strong>Remote write</strong><small class=\"diagram-muted\">SSE push, or the ~2s polling tick as fallback &rarr; version bumps &rarr; background refetch</small></div></div></div>",
+  "css": ".diagram-latency .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-latency .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px}"
+}
+```
+
 ## cn(...inputs) {#cn}
 
 Utility for merging class names (clsx + tailwind-merge):

package/docs/content/cloneable-saas.md

@@ -51,6 +51,13 @@ This isn't a theoretical claim. The framework's author runs his actual inbox on
 
 The path from "I want my own SaaS" to "I have my own SaaS" is short:
 
+```an-diagram title="Fork and customize" summary="Pick a finished product, brand it, evolve it in plain English, and ship it to your own domain."
+{
+  "html": "<div class=\"diagram-fork\"><div class=\"diagram-card\"><span class=\"diagram-pill\">1</span><strong>Pick</strong><small class=\"diagram-muted\">a complete template</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2</span><strong>Brand</strong><small class=\"diagram-muted\">name, colors, logo, copy</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">3</span><strong>Customize</strong><small class=\"diagram-muted\">ask the agent &#8635;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">4</span><strong>Ship</strong><small class=\"diagram-muted\">your own domain</small></div></div>",
+  "css": ".diagram-fork{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-fork .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px}.diagram-fork .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 1. **Pick a template.** Use the CLI picker, or browse the docs and pick one to start from.
 2. **Brand it.** Change the name, colors, logo, and copy. Most templates expose this in a single config file.
 3. **Customize it.** Ask the agent to add the column you need, change how the inbox groups, connect to your internal API, add a new view. The agent edits the code; you review the diff.
@@ -67,6 +74,13 @@ A traditional fork-the-codebase model breaks down at scale: every user maintaini
 
 The result: Claude-Code-level flexibility for each user, with normal SaaS deployment economics.
 
+```an-diagram title="Why per-user forks scale" summary="Two ideas keep the fork-and-customize model practical: the agent does the maintenance, and per-user customization lives in SQL — not in per-user code."
+{
+  "html": "<div class=\"diagram-why\"><div class=\"diagram-panel\" data-rough><strong>Shared codebase</strong><small class=\"diagram-muted\">one app, deployed once</small><div class=\"diagram-pill accent\">agent does the maintenance</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>Per-user layer in SQL</strong><small class=\"diagram-muted\">skills · memory · instructions · MCP · sub-agents</small><div class=\"diagram-pill ok\">no per-user code</div></div></div>",
+  "css": ".diagram-why{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-why .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 18px;min-width:240px;flex:1}.diagram-why .diagram-arrow{font-size:24px;line-height:1}"
+}
+```
+
 ## Don't want to fork? {#hosted}
 
 You don't have to. Every template is also available as a hosted app on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; fork only when you want to change something the hosted version doesn't expose.

package/docs/content/code-agents-ui.md

@@ -25,6 +25,13 @@ There are three layers:
 - **Desktop**: the left-sidebar Code tab adds native terminal launch, app webviews, and desktop deep links while using the same run model.
 - **Shared UI**: `@agent-native/code-agents-ui` renders the reusable React surface.
 
+```an-diagram title="Three layers over one run store" summary="CLI, Desktop, and the shared UI are different surfaces over the same file-backed run store and executor; hosts adapt it via the CodeAgentsHost contract."
+{
+  "html": "<div class=\"diagram-layers\"><div class=\"diagram-row\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">CLI</span><small class=\"diagram-muted\">start · resume · status · stop</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Desktop</span><small class=\"diagram-muted\">native terminal · webviews · deep links</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Shared UI</span><small class=\"diagram-muted\">@agent-native/code-agents-ui</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill\">CodeAgentsHost</span><small class=\"diagram-muted\">host contract</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>File-backed run store + executor<br><small class=\"diagram-muted\">@agent-native/core/code-agents</small></div></div>",
+  "css": ".diagram-layers{display:flex;flex-direction:column;gap:10px;align-items:center}.diagram-layers .diagram-row{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.diagram-layers .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-layers .diagram-arrow{font-size:22px;line-height:1}.diagram-layers .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
 The current split is intentionally converging: the standard agent sidebar and Agent Teams run on the core `run-manager` lifecycle, while Agent-Native Code uses local long-running sessions backed by the file-based Code run store and the shared background-run controller vocabulary.
 
 The shared UI is host-driven. It does not know whether it is running in Electron, a browser template, or a future hosted shell. Hosts provide a `CodeAgentsHost` implementation.
@@ -366,8 +373,28 @@ The connection is outbound-only from Desktop:
 5. Mobile reads `hosts`, `runs`, and `transcript` from Dispatch; it never talks
    directly to the desktop.
 
+```an-diagram title="Remote Dispatch is outbound-only" summary="Mobile never talks to the desktop directly. Desktop long-polls Dispatch, claims commands, drives the local run store, and mirrors results back."
+{
+  "html": "<div class=\"diagram-remote\"><div class=\"diagram-node\" data-rough>Mobile / Telegram<br><small class=\"diagram-muted\">/code · sessions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Dispatch relay<br><small class=\"diagram-muted\">hosts · runs · transcript</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-node\" data-rough>Desktop<br><small class=\"diagram-muted\">long-polls · claims · drives run store</small></div></div>",
+  "css": ".diagram-remote{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-remote .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 The canonical remote relay endpoints are:
 
+```an-api title="Desktop claims queued work"
+{
+  "method": "POST",
+  "path": "/_agent-native/integrations/remote/poll",
+  "summary": "Desktop long-polls the relay to claim enqueued commands",
+  "description": "Outbound-only from a paired Desktop host. Desktop authenticates with its device token and claims work that mobile or Telegram enqueued.",
+  "auth": "Desktop device token",
+  "responses": [
+    { "status": "200", "description": "Claimed commands for this host (may be empty after the long-poll window)." }
+  ]
+}
+```
+
 | Method     | Route                                                    | Caller          | Purpose                                     |
 | ---------- | -------------------------------------------------------- | --------------- | ------------------------------------------- |
 | `POST`     | `/_agent-native/integrations/remote/register`            | Desktop session | Pair a desktop host and return a token once |

package/docs/content/components.md

@@ -25,6 +25,13 @@ Avoid importing UI components from the bare `@agent-native/core` package. Use
 `@agent-native/core/client` or a focused `@agent-native/core/client/*` subpath
 so bundlers choose the browser-safe entry.
 
+```an-diagram title="Drop down a layer, not out of the framework" summary="Each layer keeps the same runtime — actions, thread state, and SQL-backed sync — while giving you more control over the chrome."
+{
+  "html": "<div class=\"diagram-layers\"><div class=\"diagram-card layer\"><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><small class=\"diagram-muted\">Whole sidebar around your app. The 80% case.</small></div><div class=\"diagram-card layer l2\"><span class=\"diagram-pill\">&lt;AgentPanel&gt; &middot; &lt;AgentChatSurface&gt;</span><small class=\"diagram-muted\">The panel or a chat page in your own layout.</small></div><div class=\"diagram-card layer l3\"><span class=\"diagram-pill\">&lt;AssistantChat&gt; + runtime</span><small class=\"diagram-muted\">Own the chrome; optionally pass a BYO AgentChatRuntime.</small></div><div class=\"diagram-card layer l4\"><span class=\"diagram-pill\">&lt;PromptComposer&gt; &middot; &lt;AgentConversation&gt;</span><small class=\"diagram-muted\">Composer and transcript primitives only.</small></div><div class=\"diagram-rail\" data-rough>Same runtime: actions &middot; thread state &middot; SQL-backed sync</div></div>",
+  "css": ".diagram-layers{display:flex;flex-direction:column;gap:10px}.diagram-layers .layer{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-layers .l2{margin-inline-start:24px}.diagram-layers .l3{margin-inline-start:48px}.diagram-layers .l4{margin-inline-start:72px}.diagram-layers .diagram-rail{margin-top:6px;padding:10px 14px;text-align:center}"
+}
+```
+
 ## Agent And Chat UI {#agent-chat-ui}
 
 | API                                  | Import path                                   | Use when                                                                                         |
@@ -171,6 +178,13 @@ collaborative document hooks.
 | `useCollaborativeMap()` / `useCollaborativeArray()` | Experiment with structured Y.Map/Y.Array state when rich-text body collab is the wrong fit. |
 | `dedupeCollabUsersByEmail()`                        | Build a custom avatar stack without duplicate tabs for the same user.                       |
 
+```an-diagram title="Presence: humans and the agent share one awareness layer" summary="useCollaborativeDoc owns the awareness instance; client hooks publish cursors and selections; server helpers let an agent action appear as a live participant."
+{
+  "html": "<div class=\"diagram-presence\"><div class=\"diagram-col\"><div class=\"diagram-node\">Humans<br><small class=\"diagram-muted\">usePresence &middot; cursors, selection</small></div><div class=\"diagram-node diagram-accent\">Agent action<br><small class=\"diagram-muted\">agentUpdateSelection()</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">useCollaborativeDoc</span><small class=\"diagram-muted\">awareness layer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;PresenceBar&gt; &middot; &lt;LiveCursorOverlay&gt;<br><small class=\"diagram-muted\">render everyone, agent included</small></div></div>",
+  "css": ".diagram-presence{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-presence .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-presence .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-presence .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 Server-side agent actions that want to appear as a live participant use the
 lower-level `@agent-native/core/collab` agent presence helpers:
 
@@ -324,6 +338,13 @@ If you truly need raw text-in/text-out, keep it server-side and use
 `completeText()` from `@agent-native/core/server`. Wrap user-facing usage in an
 action so the UI and agent share the same capability.
 
+```an-callout
+{
+  "tone": "warning",
+  "body": "`completeText()` is the escape hatch, not the default. Reach for it only for true text-in/text-out (a label, a one-line rewrite). Anything needing tools, state, auditability, or steering belongs in an action plus `sendToAgentChat({ background: true })`."
+}
+```
+
 ```ts
 import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";

package/docs/content/context-awareness.md

@@ -24,6 +24,13 @@ Six patterns solve this:
 5. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
 6. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
 
+```an-diagram title="How the agent sees what you see" summary="The UI writes lightweight state keys; view-screen hydrates them into real records; the agent can write navigate back to move the UI."
+{
+  "html": "<div class=\"diagram-ctx\"><div class=\"diagram-card col\"><span class=\"diagram-pill\">UI writes</span><div class=\"diagram-node\">navigation<br><small class=\"diagram-muted\">view, open ids</small></div><div class=\"diagram-node\">__url__<br><small class=\"diagram-muted\">shareable filters</small></div><div class=\"diagram-node\">selection<br><small class=\"diagram-muted\">rows, blocks, shapes</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">view-screen</span><small class=\"diagram-muted\">reads state &middot; fetches records</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Agent acts<br><small class=\"diagram-muted\">on the real object</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box diagram-accent\">navigate<br><small class=\"diagram-muted\">agent moves the UI</small></div></div>",
+  "css": ".diagram-ctx{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-ctx .col{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-ctx .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-ctx .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 ## Context layers {#context-layers}
 
 Use different context channels for different jobs:
@@ -184,58 +191,29 @@ Use `pending-selection-context` for one-shot "act on this exact highlighted text
 
 Every template should have a `view-screen` action. It reads navigation and selection state, fetches the relevant data, and returns a snapshot of what the user sees. This is the agent's eyes.
 
-```ts
-// actions/view-screen.ts
-import { defineAction } from "@agent-native/core/action";
-import { readAppState } from "@agent-native/core/application-state";
-import { eq, inArray } from "drizzle-orm";
-import { z } from "zod";
-import { getDb, schema } from "../server/db/index.js";
-
-export default defineAction({
-  description:
-    "See what the user is currently looking at on screen. Reads navigation and selection state and fetches matching data.",
-  schema: z.object({}),
-  http: false,
-  run: async () => {
-    const navigation = (await readAppState("navigation")) as any;
-    const selection = (await readAppState("selection")) as any;
-    const screen: Record<string, unknown> = {};
-    if (navigation) screen.navigation = navigation;
-    if (selection) screen.selection = selection;
-
-    const db = getDb();
-
-    // Fetch data based on what the user is viewing
-    if (navigation?.view === "inbox") {
-      screen.emailList = await db
-        .select()
-        .from(schema.emails)
-        .where(eq(schema.emails.label, navigation.label));
-    }
-    if (navigation?.threadId) {
-      screen.thread = await db
-        .select()
-        .from(schema.threads)
-        .where(eq(schema.threads.id, navigation.threadId));
-    }
-    if (selection?.kind === "email.messages") {
-      screen.selectedMessages = await db
-        .select()
-        .from(schema.emails)
-        .where(inArray(schema.emails.id, selection.messageIds));
-    }
-
-    if (Object.keys(screen).length === 0) {
-      return "No application state found. Is the app running?";
-    }
-    return screen;
-  },
-});
+```an-annotated-code title="view-screen — the agent's eyes"
+{
+  "filename": "actions/view-screen.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { readAppState } from \"@agent-native/core/application-state\";\nimport { eq, inArray } from \"drizzle-orm\";\nimport { z } from \"zod\";\nimport { getDb, schema } from \"../server/db/index.js\";\n\nexport default defineAction({\n  description:\n    \"See what the user is currently looking at on screen.\",\n  schema: z.object({}),\n  http: false,\n  run: async () => {\n    const navigation = (await readAppState(\"navigation\")) as any;\n    const selection = (await readAppState(\"selection\")) as any;\n    const screen: Record<string, unknown> = {};\n    if (navigation) screen.navigation = navigation;\n    if (selection) screen.selection = selection;\n\n    const db = getDb();\n\n    // Fetch data based on what the user is viewing\n    if (navigation?.view === \"inbox\") {\n      screen.emailList = await db\n        .select()\n        .from(schema.emails)\n        .where(eq(schema.emails.label, navigation.label));\n    }\n    if (navigation?.threadId) {\n      screen.thread = await db\n        .select()\n        .from(schema.threads)\n        .where(eq(schema.threads.id, navigation.threadId));\n    }\n    if (selection?.kind === \"email.messages\") {\n      screen.selectedMessages = await db\n        .select()\n        .from(schema.emails)\n        .where(inArray(schema.emails.id, selection.messageIds));\n    }\n\n    if (Object.keys(screen).length === 0) {\n      return \"No application state found. Is the app running?\";\n    }\n    return screen;\n  },\n});",
+  "annotations": [
+    { "lines": "10-11", "label": "Tool surface", "note": "The agent reads this description to know it can call `view-screen` to see the current UI." },
+    { "lines": "13", "label": "http: false", "note": "Internal action — not exposed over HTTP. The agent and `pnpm action` call it, not the browser." },
+    { "lines": "15-16", "label": "Read state", "note": "Pulls the lightweight `navigation` and `selection` keys the UI wrote." },
+    { "lines": "23-37", "label": "Hydrate", "note": "Turns those IDs into **fresh** records straight from SQL, so the agent verifies the live object before acting." }
+  ]
+}
 ```
 
 The agent should call `pnpm action view-screen` before acting on the current UI. This is a hard convention across all templates. When adding new features, update `view-screen` to return data for the new view and any new selection shape.
 
+```an-callout
+{
+  "tone": "info",
+  "body": "**Keep `navigation` and `selection` small.** Store IDs plus short labels, not whole records. `view-screen` fetches the source of truth on demand, so stale or bulky state never reaches the agent."
+}
+```
+
 ## Prompt handoff with `sendToAgentChat()` {#send-to-agent-chat}
 
 Sometimes context should not just sit in app state. A user clicks a button, drops a comment pin, selects an item and chooses "Ask agent", or presses an AI command in a toolbar. That click is an instruction. In browser UI, hand it to the agent with `sendToAgentChat()`.
@@ -386,3 +364,10 @@ How it works:
 - The server stores the source on each event
 - When processing sync events, the UI filters out events matching its own `ignoreSource` value -- so it doesn't refetch data it just wrote
 - Events from agents, other tabs, and actions still come through normally
+
+```an-diagram title="Source tagging stops self-refetch jitter" summary="A tab ignores sync events stamped with its own TAB_ID, but still reacts to agent and other-tab writes."
+{
+  "html": "<div class=\"diagram-jitter\"><div class=\"diagram-node\">This tab writes<br><small class=\"diagram-muted\">X-Request-Source: TAB_ID</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Server stores source<br>on the event</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill warn\">source == TAB_ID &rarr; ignored</div><small class=\"diagram-muted\">no refetch, no flicker</small><div class=\"diagram-pill ok\">agent / other tab &rarr; applied</div><small class=\"diagram-muted\">UI updates live</small></div></div>",
+  "css": ".diagram-jitter{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jitter .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-jitter .diagram-arrow{font-size:22px;line-height:1}"
+}
+```

package/docs/content/creating-templates.md

@@ -39,37 +39,41 @@ If you are not building a reusable UI template yet, use the headless on-ramp in
 
 Every template follows the same broad layout:
 
-```text
-my-template/
-  app/
-    root.tsx              # HTML shell and providers
-    routes/               # React Router file routes
-    components/           # Template UI
-    hooks/                # UI state and data hooks
-
-  actions/
-    *.ts                  # defineAction operations
-
-  server/
-    db/schema.ts          # Drizzle schema
-    plugins/db.ts         # additive migrations
-    plugins/*.ts          # startup integrations
-    routes/api/*.ts       # custom routes only when actions are not enough
-
-  shared/
-    types.ts              # shared client/server types
-
-  .agents/skills/
-    <skill>/SKILL.md      # agent guidance for complex workflows
-
-  AGENTS.md               # template-specific agent instructions
-  package.json
-  react-router.config.ts
-  vite.config.ts
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
 ```
 
 Do not add a `data/` directory for application state. Durable app data belongs in SQL, and the UI reads it through actions or typed server handlers.
 
+The four areas of every template wire together through one shared action surface and one SQL database — the agent and the UI are equal partners over the same operations:
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
 ## Model Data In SQL {#data-models}
 
 Define domain tables with the framework Drizzle helpers so schemas stay portable across SQLite, Postgres, D1, Turso, Supabase, Neon, and other supported backends:
@@ -137,31 +141,18 @@ Use the [Database](/docs/database) and [Security](/docs/security) docs before ad
 
 Actions are the single source of truth for app behavior. The agent calls them as tools, the frontend calls them through hooks, and other apps can reach them through MCP/A2A.
 
-```ts
-// actions/create-project.ts
-import { defineAction } from "@agent-native/core/action";
-import { getDb } from "../server/db/index.js"; // getDb is created per app via createGetDb(schema) in server/db/index.ts
-import { nanoid } from "nanoid";
-import { z } from "zod";
-import * as schema from "../server/db/schema";
-
-export default defineAction({
-  description: "Create a project.",
-  schema: z.object({
-    title: z.string().min(1).describe("Project title"),
-  }),
-  run: async ({ title }, ctx) => {
-    const db = getDb();
-    const id = nanoid();
-    await db.insert(schema.projects).values({
-      id,
-      title,
-      ownerEmail: ctx.userEmail,
-      orgId: ctx.orgId,
-    });
-    return { id, title };
-  },
-});
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "Typed contract", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
 ```
 
 Use `http: { method: "GET" }` or `readOnly: true` for read-only actions. Use `parallelSafe: true` only for mutating actions that are safe to run concurrently with same-turn tool calls. Use `toolCallable: false` for high-blast-radius actions that should not run from sandboxed tools.

package/docs/content/cross-app-sso.md

@@ -26,6 +26,13 @@ This makes the rollout safe even though it logs people out. **Logout is expected
 
 The flow is a standard authorize → signed-token → callback redirect, with email as the only thing that crosses the trust boundary.
 
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 1. **App → Dispatch (authorize).** The app sends the user to the identity authority:
 
    ```
@@ -35,6 +42,24 @@ The flow is a standard authorize → signed-token → callback redirect, with em
        &state=<csrf-state>
    ```
 
+   ```an-api title="Identity authorize endpoint"
+   {
+     "method": "GET",
+     "path": "/_agent-native/identity/authorize",
+     "summary": "Dispatch (identity authority) authenticates the human and redirects back with a signed identity token",
+     "auth": "Dispatch session (interactive login if none)",
+     "params": [
+       { "name": "app", "in": "query", "type": "string", "required": true, "description": "The requesting app identifier." },
+       { "name": "redirect_uri", "in": "query", "type": "string", "required": true, "description": "App callback URL. Validated against a strict allowlist (`*.agent-native.com` or localhost by default)." },
+       { "name": "state", "in": "query", "type": "string", "required": true, "description": "CSRF state echoed back on the redirect." }
+     ],
+     "responses": [
+       { "status": "302", "description": "Redirects to `redirect_uri` carrying a short-lived `A2A_SECRET`-signed identity JWT (`scope: \"identity\"`, `exp` ≤ 2 minutes) plus the original `state`." },
+       { "status": "400", "description": "`redirect_uri` failed allowlist validation (cross-origin, scheme-relative `//host`, or unlisted suffix)." }
+     ]
+   }
+   ```
+
 2. **Dispatch authenticates the human.** If the user already has a Dispatch session, this is transparent. If not, Dispatch shows its own normal login (email/password, Google, etc. — see [Authentication](/docs/authentication)). Dispatch is just a regular agent-native app here; it is not running a special auth mode.
 
 3. **Dispatch → App (signed identity token).** Dispatch validates `redirect_uri` against a strict allowlist and 302-redirects back to the app's `redirect_uri` carrying a short-lived **`A2A_SECRET`-signed identity JWT**. The token's claims are intentionally minimal:
@@ -75,6 +100,22 @@ The whole model rests on a few deliberately small guarantees:
 - **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path.
 - **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert.
 
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+The just-in-time link is a single decision keyed entirely on the verified email:
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 ## Self-hosting {#self-hosting}
 
 Any Dispatch deployment can serve as the identity hub — you are not limited to `dispatch.agent-native.com`. Set `AGENT_NATIVE_IDENTITY_HUB_URL` on each client app to point at your Dispatch instance:

package/docs/content/database.md

@@ -7,6 +7,13 @@ description: "Connect a portable SQL database to your agent-native app and write
 
 Agent-native apps use [Drizzle ORM](https://orm.drizzle.team) and support portable SQL backends. For anything beyond local development, connect a persistent SQL database — Postgres, libSQL/Turso, or another Drizzle-compatible backend — by setting `DATABASE_URL`. When that variable is unset, the app falls back to a zero-config local SQLite file so you can start developing immediately.
 
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
 ## Local default: SQLite file {#default-sqlite}
 
 When `DATABASE_URL` is not set, the app creates a SQLite database at `data/app.db`. This is the zero-config default for local development — no setup required. It is meant for development only; for production, set `DATABASE_URL` to a persistent SQL database.
@@ -80,6 +87,29 @@ export const tasks = table("tasks", {
 | `real`    | Float column — `real` on SQLite, `double precision` on Postgres |
 | `now`     | Dialect-agnostic current timestamp for `.default(now())`        |
 
+The `tasks` table above defines the same columns on every backend:
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
 Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly. Always use `@agent-native/core/db/schema`.
 
 Tables that store user-facing data must include an `owner_email` column so the framework's SQL-level scoping can filter rows to the authenticated user — see [Security](/docs/security#data-scoping). Tables that also support sharing with other users or orgs should spread `...ownableColumns()` instead, which adds `owner_email`, `org_id`, and `visibility` in one call — see [Sharing](/docs/sharing#building).
@@ -132,27 +162,17 @@ All database schema updates must be **strictly additive**.
 
 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:
 
-```ts
-import { runMigrations } from "@agent-native/core/db";
-
-export default runMigrations(
-  [
-    {
-      version: 1,
-      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,
-    },
-    {
-      // Dialect-gated: runs only on the matching backend. Omit the other key
-      // to make it a no-op on that dialect.
-      version: 2,
-      sql: {
-        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,
-        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only
-      },
-    },
-  ],
-  { table: "my_app_migrations" },
-);
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
 ```
 
 ## Environment Variables {#environment-variables}

package/docs/content/deployment.md

@@ -28,6 +28,13 @@ npx @agent-native/core@latest deploy
 
 Each app is built with `APP_BASE_PATH=/<name>` and `VITE_APP_BASE_PATH=/<name>`, then packaged for the target Nitro preset. Cloudflare Pages is the default preset and uses a generated dispatcher worker at `dist/_worker.js`; Netlify uses one function per app in `.netlify/functions-internal/<app>-server` plus generated redirects; Vercel writes a workspace-level `.vercel/output` using the Build Output API.
 
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
 Same-origin deploy gives you two big wins for free:
 
 - **Shared login session** — log into any app, every app is logged in.
@@ -63,16 +70,26 @@ Per-app independent deploy is still supported — just `cd apps/<name> && npx @a
 
 When you run `npx @agent-native/core@latest build`, Nitro builds both the client SPA and the server API into `.output/`:
 
-```text
-.output/
-  public/          # Built SPA (static assets)
-  server/
-    index.mjs      # Server entry point
-    chunks/         # Server code chunks
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
 ```
 
 The output is self-contained — copy `.output/` to any environment and run it.
 
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
 ## Setting the Preset {#setting-the-preset}
 
 By default, Nitro builds for Node.js. To target a different platform, set the preset in your `vite.config.ts`: