@agent-native/core 0.92.12 → 0.94.0

package/docs/content/actions.mdx

@@ -11,7 +11,7 @@ Actions are the single source of truth for anything your app does. Define an act
 - **Typesafe React hooks** — `useActionQuery("name")` and `useActionMutation("name")` on the frontend, types inferred from the schema.
 - **Imperative client calls** — `callAction("name", params)` when a hook does not fit.
 - **Framework transport** — auto-mounted by the framework behind those hooks and available to external HTTP clients.
-- **An MCP tool** — exposed to Claude, ChatGPT custom MCP apps, Claude Desktop/Code, Cursor, Codex, and any other MCP client.
+- **An MCP tool** — exposed to Claude, ChatGPT custom MCP apps, Claude Desktop/Code, Cursor, Codex, and any other MCP host.
 - **An A2A tool** — called by other agent-native apps over A2A.
 - **A CLI command** — `pnpm action <name>` for scripting and dev loops.
 
@@ -146,23 +146,23 @@ around actions, not a required prerequisite for the action itself.
   filename="actions/reply-to-email.ts"
   language="ts"
   code={
-    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nexport default defineAction({\n  description: "Reply to an email thread in the user\'s voice.",\n  schema: z.object({\n    emailId: z.string().describe("The id of the email to reply to."),\n    body: z.string().describe("The reply body, in markdown."),\n  }),\n  run: async ({ emailId, body }) => {\n    await db.insert(replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});'
+    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n  description: "Reply to an email thread in the user\'s voice.",\n  schema: z.object({\n    emailId: z.string().describe("The id of the email to reply to."),\n    body: z.string().describe("The reply body, in markdown."),\n  }),\n  run: async ({ emailId, body }) => {\n    const db = getDb();\n    await db.insert(schema.replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});'
   }
   annotations={[
     {
-      lines: "5",
+      lines: "7",
       label: "Tool surface",
       note: "`description` is what the agent reads to decide when to call this. The per-field `.describe()` calls flow into the JSON Schema too.",
     },
     {
-      lines: "6-9",
+      lines: "8-11",
       label: "Typed contract",
       note: "One schema validates input from **every** surface and is converted to JSON Schema for the model. Invalid inputs never reach `run`.",
     },
     {
-      lines: "10-13",
+      lines: "12-16",
       label: "One implementation",
-      note: "The `run` body is the single source of truth — the UI button and the agent tool both execute exactly this.",
+      note: "The `run` body is the single source of truth — the UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts` — see [Database](/docs/database).",
     },
   ]}
 />
@@ -392,23 +392,9 @@ For list and read actions, use `accessFilter` to scope the query to the current
 
 ### Human-in-the-loop approval {#needs-approval}
 
-A handful of actions are too consequential to let the agent run autonomously — sending an email, charging a card, deleting an account. For those, set `needsApproval` to pause the loop and require a human to approve the specific call before `run()` executes:
+A handful of actions are too consequential to let the agent run autonomously — sending an email, charging a card, deleting an account. Set `needsApproval: true` (or a predicate `(args, ctx) => boolean | Promise<boolean>`) on `defineAction` and the loop pauses before `run()`, requiring a human to approve that specific call. The default is **off**, and almost every action should stay that way.
 
-```ts
-export default defineAction({
-  description: "Send an email via Gmail.",
-  schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
-  needsApproval: true, // pause; a human must approve this specific send
-  run: async (args) => {
-    /* ...actually send... */
-  },
-});
-```
-
-`needsApproval` also accepts a predicate `(args, ctx) => boolean | Promise<boolean>` to gate conditionally (e.g. only external recipients, only above a threshold); it **fails closed**, so a throw counts as "approval required". When the gate is truthy and unapproved, the loop stops the turn and the side effect never fires until a human approves in the chat UI.
-
-> [!WARNING]
-> Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full flow.
+See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full end-to-end flow.
 
 ### Audit logging {#audit}
 
@@ -554,7 +540,7 @@ export default defineAction({
 });
 ```
 
-Keep `link` as the fallback for CLI and non-UI MCP clients; it is also the embed's launch target. The embed bridge — the signed embed-start session, transplant vs. controlled-frame rendering, the `ui/*` host bridge, CSP, and height clamping — is owned by [External Agents](/docs/external-agents#mcp-app-bridge).
+Keep `link` as the fallback for CLI and non-UI MCP hosts; it is also the embed's launch target. The embed bridge — the signed embed-start session, transplant vs. controlled-frame rendering, the `ui/*` host bridge, CSP, and height clamping — is owned by [External Agents](/docs/external-agents#mcp-app-bridge).
 
 ## Standard actions {#standard-actions}
 

package/docs/content/agent-mentions.mdx

@@ -176,11 +176,26 @@ Remote A2A agents still use JSON manifests:
 }
 ```
 
----
+## Referencing files {#referencing-files}
+
+The `@` popover is not limited to agents. You can also reference:
+
+- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
+- **Workspace resources** — reference files defined in the Workspace tab. These can be data files, configuration, or any other structured content.
+
+Selecting a file or resource resolves it into the agent's context when the message is sent, the same way an agent mention does.
+
+Skills use a separate trigger: type `/` instead of `@` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task — see [Skills Guide](/docs/skills-guide) for the full authoring format.
+
+## Sub-agent selection {#sub-agent-selection}
+
+The main agent can also use custom agents when spawning sub-agents with `agent-teams` (action: "spawn").
+
+Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.
 
 ## For developers: extending mentions {#extending-mentions}
 
-Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface:
+Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface: a `label` (the section heading shown in the `@` popover) plus a `search(query, event?)` function that returns up to a handful of `MentionProviderItem` matches (`id`, `label`, `description?`, `refType`, `refId?`, `refPath?`, `metadata?`).
 
 <AnnotatedCode
   id="doc-block-159gm13"
@@ -188,28 +203,23 @@ Templates can register custom mention providers to add domain-specific mentionab
   filename="server/mentions/contacts.ts"
   language="ts"
   code={
-    'import type { MentionProvider } from "@agent-native/core/server";\n\nconst contactsProvider: MentionProvider = {\n  id: "contacts",\n  label: "Contacts",\n\n  // Search for mentionable items\n  async search(query: string) {\n    const contacts = await db.query.contacts.findMany({\n      where: like(contacts.name, `%${query}%`),\n      limit: 10,\n    });\n    return contacts.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      type: "contact",\n    }));\n  },\n\n  // Resolve a mention into context for the agent\n  async resolve(id: string) {\n    const contact = await db.query.contacts.findFirst({\n      where: eq(contacts.id, id),\n    });\n    return {\n      type: "context",\n      text: `Contact: ${contact.name} (${contact.email})`,\n    };\n  },\n};'
+    'import type { MentionProvider } from "@agent-native/core/server";\nimport { like } from "drizzle-orm";\nimport { getDb, schema } from "../db/index.js";\n\nconst contactsProvider: MentionProvider = {\n  label: "Contacts",\n\n  // Runs as the user types after `@`. Return up to a handful of matches.\n  async search(query) {\n    const db = getDb();\n    const matches = await db\n      .select()\n      .from(schema.contacts)\n      .where(like(schema.contacts.name, `%${query}%`))\n      .limit(10);\n    return matches.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      refType: "contact",\n      refId: c.id,\n    }));\n  },\n};'
   }
   annotations={[
     {
-      lines: "4-5",
-      label: "Identity",
-      note: "`id` namespaces the provider; `label` is the section heading shown in the `@` popover.",
+      lines: "5",
+      label: "label",
+      note: "The section heading shown in the `@` popover for this provider's matches.",
     },
     {
-      lines: "8-9",
+      lines: "8-18",
       label: "search",
-      note: "Runs as the user types after `@`. Return up to a handful of matches as `{ id, label, description, type }`.",
-    },
-    {
-      lines: "23-24",
-      label: "resolve",
-      note: 'Called when the message is sent. Turns a picked id into `{ type: "context", text }` that is injected into the agent\'s context.',
+      note: "Runs as the user types after `@`. Return matches as `MentionProviderItem`s — `id`, `label`, `description`, `refType`, `refId`.",
     },
   ]}
 />
 
-Register providers in the agent-chat plugin configuration:
+Register providers in the agent-chat plugin configuration, keyed by provider id:
 
 ```ts
 // server/plugins/agent-chat.ts
@@ -222,20 +232,12 @@ export default createAgentChatPlugin({
 });
 ```
 
-Custom mention providers appear alongside the built-in agent and file providers in the mention popover.
-
-## Referencing files {#referencing-files}
-
-The `@` popover is not limited to agents. You can also reference:
-
-- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
-- **Workspace resources** — reference files defined in the Workspace tab. These can be data files, configuration, or any other structured content.
-- **Skills** — type `/` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task.
+Custom mention providers appear alongside the built-in agent and file providers in the mention popover. When the message is sent, a picked item is added to the agent's context as a compact reference line (`[contact] Jane Doe (id: ...)`), not a fully resolved document — put enough into `label`/`description` for the agent to act, or give it an action to look up the full record by `refId`.
 
-All reference types follow the same pattern: select from the popover, and the referenced content is resolved and injected into the agent's context when the message is sent.
-
-## Sub-agent selection {#sub-agent-selection}
+## What's next {#whats-next}
 
-The main agent can also use custom agents when spawning sub-agents with `agent-teams` (action: "spawn").
-
-Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.
+- [**Using Your Agent**](/docs/using-your-agent) — where mentions fit in the day-to-day loop with the agent
+- [**A2A Protocol**](/docs/a2a-protocol) — how connected-agent mentions are resolved over the wire
+- [**Agent Teams**](/docs/agent-teams) — spawn sub-agents and pass the `agent` profile parameter
+- [**Skills Guide**](/docs/skills-guide) — author the skills referenced with `/`
+- [**Workspace**](/docs/workspace#custom-agents) — the full custom-agent profile format

package/docs/content/agent-native-toolkit.mdx

@@ -93,12 +93,10 @@ coherent kit instead of exposing package boundaries in the app.
 
 ## Foundation Pieces {#foundation-pieces}
 
-- [UI Primitives](/docs/toolkit-ui) cover shared shadcn-style primitives under
-  `@agent-native/toolkit/ui/*`.
-- [App Adapters](/docs/toolkit-app-adapters) show how apps wrap Toolkit pieces
-  through local `@/components/*` adapters.
-- [Shell & Hooks](/docs/toolkit-shell-hooks) cover header actions, mobile hooks,
-  toasts, and small app-shell helpers.
+- [UI Primitives](/docs/toolkit-ui) covers the shared shadcn-style primitives
+  under `@agent-native/toolkit/ui/*`, the local app-adapter pattern every
+  template wraps them in, and the shared shell hooks (header actions, mobile
+  detection, toasts).
 - [Component API](/docs/components) remains the lower-level reference for the
   public React exports.
 
@@ -108,3 +106,14 @@ Use a toolkit when the behavior repeats across apps and users expect it to feel
 standard: sharing, settings, teams, comments, history, and agent progress should
 not be slightly different in every template. Keep domain-specific data,
 workflows, labels, and visual styling in the app.
+
+## What's next
+
+- [**Toolkit UI Primitives**](/docs/toolkit-ui) — the shared primitives, app
+  adapters, and shell hooks every kit builds on.
+- [**Sharing Kit**](/docs/toolkit-sharing) — a good first kit to adopt: ownable
+  resources, share dialogs, and visibility.
+- [**Creating Templates**](/docs/creating-templates) — build a template end to
+  end and see where kits fit alongside your own domain model.
+- [**Component API**](/docs/components) — the generated reference for every
+  public React export, including kit components.

package/docs/content/agent-surfaces.mdx

@@ -139,8 +139,7 @@ pnpm install
 
 Then define the durable operation:
 
-```ts
-// actions/summarize-week.ts
+```ts filename="actions/summarize-week.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -502,14 +501,11 @@ Keep the contract small: define durable operations as actions, return explicit
 widget results when chat needs rich UI, and add full screens only when users
 need to browse, compare, configure, or collaborate over persistent objects.
 
-## Related docs {#related-docs}
-
-- [Actions](/docs/actions) — define the operation once.
-- [Native Chat UI](/docs/native-chat-ui) — render typed action results in chat.
-- [Generative UI](/docs/generative-ui) — generate transient or persisted sandboxed UI inline in chat.
-- [Drop-in Agent](/docs/drop-in-agent) — mount chat, sidebar, or panel surfaces.
-- [Component API](/docs/components) — lower-level React chat/composer pieces.
-- [Embedding SDK](/docs/embedding-sdk) — add Agent-Native to an existing app.
-- [Automation-First Apps](/docs/pure-agent-apps) — no-browser apps for jobs, queues, scripts, and external agents.
-- [External Agents](/docs/external-agents) — connect MCP-compatible hosts to an app.
-- [A2A Protocol](/docs/a2a-protocol) — call agents from other agents.
+## What's next {#related-docs}
+
+- [**Actions**](/docs/actions) — define the operation once; every surface above calls the same one
+- [**Native Chat UI**](/docs/native-chat-ui) — render typed action results as tables, charts, and cards in chat
+- [**Generative UI**](/docs/generative-ui) — generate transient or persisted sandboxed UI inline in chat
+- [**Automation-First Apps**](/docs/pure-agent-apps) — the full no-browser pattern for jobs, queues, scripts, and external agents
+- [**External Agents**](/docs/external-agents) — connect MCP-compatible hosts to an app
+- [**A2A Protocol**](/docs/a2a-protocol) — call agents from other agent-native apps

package/docs/content/agent-teams.mdx

@@ -239,6 +239,7 @@ interface AgentTask {
   summary: string; // full summary once completed
   currentStep: string; // latest step label (updated while running)
   createdAt: number;
+  delegationDepth?: number; // 1 for a direct sub-agent, 2 for a sub-agent of that sub-agent, etc.
   // Additional fields: parentThreadId, name, updatedAt, startedAt,
   // completedAt, runId, error
 }

package/docs/content/authentication.mdx

@@ -15,7 +15,7 @@ Auth is configured automatically via `autoMountAuth(app)` in the auth server plu
 - **Remote MCP OAuth:** Standard OAuth 2.1 for MCP hosts such as Claude Code and ChatGPT connectors.
 - **Custom:** Bring your own auth via `getSession` callback.
 
-<Diagram id="doc-block-f8rmmq" title="Three ways in, one session" summary="Browser visitors, programmatic MCP clients, and custom providers all resolve to the same AuthSession that downstream scoping reads.">
+<Diagram id="doc-block-f8rmmq" title="Three ways in, one session" summary="Browser visitors, MCP hosts, and custom providers all resolve to the same AuthSession that downstream scoping reads.">
 
 ```html
 <div class="auth-modes">
@@ -293,8 +293,7 @@ Access tokens are signed with `A2A_SECRET` when set, otherwise `BETTER_AUTH_SECR
 
 Pass a custom `getSession` callback to use any auth provider (Clerk, Auth0, Firebase, etc.):
 
-```ts
-// server/plugins/auth.ts
+```ts filename="server/plugins/auth.ts"
 import { createAuthPlugin } from "@agent-native/core/server";
 
 export default createAuthPlugin({
@@ -443,3 +442,11 @@ The default `/_agent-native/google/auth-url` route does this automatically — o
 | `ACCESS_TOKEN`                          | Static bearer fallback for MCP/connect clients; not browser auth                                                                             |
 | `ACCESS_TOKENS`                         | Comma-separated static bearer fallbacks for MCP/connect clients; not browser auth                                                            |
 | `A2A_SECRET`                            | Shared secret for JWT-signed A2A cross-app identity verification and, when present, MCP OAuth access-token signing                           |
+
+## What's next
+
+- [**Multi-Tenancy**](/docs/multi-tenancy) — the org-management surface built on top of `session.orgId`
+- [**Security — Data Scoping**](/docs/security#data-scoping) — the `session.orgId → AGENT_ORG_ID → SQL` pipeline and access guards
+- [**Cross-App SSO**](/docs/cross-app-sso) — sharing sign-in across first-party hosted apps that each have their own auth database
+- [**Sharing**](/docs/sharing) — sharing individual resources between authenticated users and orgs
+- [**MCP Protocol**](/docs/mcp-protocol) — the MCP surface that Remote MCP OAuth authenticates into

package/docs/content/automation-connectors.mdx

@@ -0,0 +1,123 @@
+---
+title: "Workflow Connectors"
+description: "Invoke pre-configured external workflow systems like n8n and Zapier by a stable workflow ID, and accept their authenticated callbacks — without treating them as chat channels or generic provider APIs."
+---
+
+# Workflow Connectors
+
+Reach for workflow connectors when you already have an automation platform — n8n, Zapier, or a similar workflow system — that should run a specific, pre-configured job on request, and hand a result back safely. An action passes a workflow ID and structured input; the workflow runs; the result (or a callback later) comes back through an authenticated, size-bounded path. Neither side ever sees a raw secret or an arbitrary URL.
+
+This is deliberately narrower than a general-purpose HTTP client or a chat integration. Agent Native's automation connector runtime supports exactly two directions:
+
+- Invoke a **configured external workflow** from an action.
+- Receive an **authenticated callback** from a configured workflow.
+
+An app assigns each workflow a stable ID, a connector ID, input/output schemas, response behavior, credentials, timeout/retry limits, idempotency behavior, and capability flags. Agents pass the workflow ID and structured input; they never supply arbitrary target URLs or secret values.
+
+<Callout tone="info">
+
+**Not a messaging channel, not a generic provider API.** For "ask the agent to run a scheduled or event-triggered prompt," see [Automations](/docs/automations) — that's `web-request` calling an ad-hoc URL the agent or a user configured. For "talk to the agent from Slack/email," see [Messaging](/docs/messaging). Workflow connectors are for the third case: a pre-configured, schema-typed connection to an external workflow system your team already runs.
+
+</Callout>
+
+## Worked example: notify Slack via n8n {#worked-example}
+
+An app that wants to hand a "notify sales" job to an n8n workflow defines it once, then invokes it by ID — never by URL:
+
+```ts filename="server/plugins/automation-connectors.ts"
+import {
+  createAutomationRuntime,
+  createInvokeAutomationWorkflowAction,
+} from "@agent-native/core/automation";
+
+const automation = createAutomationRuntime({
+  workflows: [
+    {
+      id: "notify-sales-slack",
+      connectorId: "n8n",
+      name: "Notify #sales on qualified lead",
+      inputSchema: {
+        type: "object",
+        properties: {
+          leadEmail: { type: "string" },
+          company: { type: "string" },
+        },
+        required: ["leadEmail"],
+      },
+      response: { mode: "asynchronous" },
+      capabilities: {
+        invokesExternalWorkflow: true,
+        receivesCallback: false,
+        supportsIdempotency: false,
+        supportsSynchronousResponse: false,
+        supportsAsynchronousResponse: true,
+        mayCauseExternalSideEffects: true,
+      },
+      outbound: {
+        baseUrl: "https://n8n.example.com",
+        path: "/webhook/notify-sales",
+        method: "POST",
+        headers: { Authorization: "Bearer ${keys.N8N_WEBHOOK_TOKEN}" },
+        timeoutMs: 10_000,
+      },
+    },
+  ],
+  resolveSecret: async (ref, context) => {
+    // Resolve a scoped vault/credential reference here. Never return it to UI.
+    return null;
+  },
+  claimInboundEvent: async ({ workflow, eventId }) => {
+    // Insert a unique SQL row and return false on a duplicate event.
+    return true;
+  },
+  enqueueInboundEvent: async ({ workflow, eventId, payload }) => {
+    // Reuse the app's established durable queue; do not run an agent here.
+  },
+});
+
+export default createInvokeAutomationWorkflowAction(automation);
+```
+
+The agent calls this action with `{ workflowId: "notify-sales-slack", input: { leadEmail: "jane@acme.com" } }` — it never sees `https://n8n.example.com/webhook/notify-sales` or the bearer token. `outbound.baseUrl` + `outbound.path` are static, app-owned config; the runtime rejects any attempt to call a different origin.
+
+Mount callback handlers only under `/_agent-native/automations/`; all normal app operations remain actions. Keep the callback route minimal: authenticate, claim idempotency, enqueue, and acknowledge — never run an agent loop inside the webhook request itself.
+
+The client calls a registered action with `invokeConfiguredAutomationWorkflow()` from `@agent-native/core/client`; it does not hand-write a browser `fetch`.
+
+## Safety model {#safety-model}
+
+Outbound workflow definitions use a static HTTPS base URL and static path. The runtime restricts requests to the configured origin, rejects private-network targets and redirects, resolves `${keys.NAME}` server-side, bounds request and response sizes, applies a timeout, retries only transient failures, and redacts resolved values from responses and errors.
+
+Workflow callbacks authenticate with either a shared secret, an HMAC-SHA256 signature, or an app-owned provider verifier. Callbacks that start agent work must provide:
+
+1. A durable, SQL-backed idempotency claim keyed by the provider event ID.
+2. A durable queue handoff that runs in a fresh execution.
+
+The callback returns an acknowledgement quickly. Never run an agent loop inside a webhook request or rely on an in-memory deduplication map. This is the same queue-and-processor pattern [Messaging](/docs/messaging) uses for inbound platform webhooks — link rather than restate if you're already familiar with that page.
+
+## n8n {#n8n}
+
+n8n is runtime-backed through configured Webhook workflows. Agent Native does **not** host or provision n8n.
+
+Configure an n8n Webhook node with an explicit URL and one of n8n's supported authentication modes (Header, Basic, or JWT), then register that static URL/origin and the matching Agent Native secret reference. n8n supports immediate responses, final-node responses, and responses via a Respond to Webhook node; model the selected behavior as asynchronous or synchronous in the workflow definition.
+
+For callbacks from n8n into Agent Native, configure an Agent Native callback URL and a shared-secret or HMAC adapter. Include a stable event ID header whenever n8n can retry delivery.
+
+See the [n8n Webhook documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/).
+
+## Zapier {#zapier}
+
+Zapier is currently **blueprint-only** in the integration catalog. There is no generic Zapier workflow execution API in this runtime, and Zapier must not be presented as a chat channel or a provider-api preset.
+
+Zapier REST Hook triggers are an app-integration contract: an app implements subscribe and unsubscribe endpoints, stores Zapier's unique target URL, and delivers events to that URL. A static inbound webhook is not a public Zapier REST Hook integration.
+
+Zapier MCP is a separately configured remote MCP connection with a Zapier account and its own authorization flow. It is not interchangeable with an Agent Native workflow callback credential.
+
+See [Zapier REST Hook triggers](https://docs.zapier.com/integrations/build/hook-trigger) and [Zapier MCP](https://docs.zapier.com/mcp/home).
+
+## What's next {#whats-next}
+
+- [**Automations**](/docs/automations#web-request) — the ad-hoc `web-request` tool for one-off outbound HTTP, the lighter-weight sibling to a configured connector
+- [**Messaging**](/docs/messaging) — reaching the agent from Slack, email, Telegram, and WhatsApp, the queue-and-processor pattern this page's callbacks reuse
+- [**Actions**](/docs/actions) — `defineAction`, `needsApproval`, and the action surface `createInvokeAutomationWorkflowAction` builds on
+- [**Security**](/docs/security) — `${keys.NAME}` secret substitution and the credential-scoping model this runtime relies on

package/docs/content/automations.mdx

@@ -140,7 +140,9 @@ Integrations register events at module load time. The bus validates payloads aga
 
 Call `manage-automations` with `action=list-events` from the agent to see all registered events with descriptions and payload schemas for the current template.
 
-### Emitting custom events {#emitting-events}
+### Emitting custom events (for developers) {#emitting-events}
+
+The rest of this page is written for the person asking the agent to create automations. Registering a new event type is a code-level change a template developer makes so users and the agent have something to trigger on.
 
 Register an event type in a server plugin, then emit it from actions or webhook handlers:
 
@@ -185,7 +187,12 @@ Conditions are natural-language strings evaluated by Claude Haiku against the ev
 - **Empty or missing condition** = unconditional (always fires).
 - Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache.
 - Payload is truncated to 4000 characters before sending to Haiku.
-- On API failure, the condition evaluates to `false` (safe default — the automation is skipped).
+
+<Callout tone="info">
+
+On API failure, the condition evaluates to `false` (safe default — the automation is skipped rather than run on an unverified condition).
+
+</Callout>
 
 Examples of conditions:
 
@@ -197,6 +204,12 @@ Examples of conditions:
 
 Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NAME}` placeholders in the URL, headers, and body:
 
+<Callout tone="info">
+
+**Ad-hoc HTTP vs configured workflow systems.** `web-request` calls whatever URL an ad-hoc key resolves to — good for a one-off webhook the agent or a user wires up. If you need a pre-configured, schema-typed connection to an external workflow system like n8n or Zapier — with idempotent callbacks and static allowed origins instead of arbitrary URLs — see [Workflow Connectors](/docs/automation-connectors) instead.
+
+</Callout>
+
 ```
 POST to ${keys.SLACK_WEBHOOK}
 
@@ -359,7 +372,7 @@ Confirm an automation's wiring and condition without waiting for a real provider
 Ask the plan agent: _"When someone adds a human comment on a plan, POST a
 notification to my webhook."_
 
-```yaml
+```yaml filename="jobs/notify-on-plan-comment.md"
 ---
 triggerType: event
 event: plan.commented
@@ -383,5 +396,6 @@ for the full `plan.commented` payload reference and all four plan events.
 
 - [**Recurring Jobs**](/docs/recurring-jobs) — schedule-triggered automations reuse the same scheduler
 - [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
+- [**Workflow Connectors**](/docs/automation-connectors) — pre-configured n8n/Zapier-style workflow invocation, for when ad-hoc `web-request` isn't a strict enough contract
 - [**Security**](/docs/security) — input validation and secret handling
 - [**Visual Plans — Events**](/docs/template-plan#events) — plan events reference and automation recipes

package/docs/content/blueprint-installer.mdx

@@ -5,8 +5,12 @@ description: "agent-native add prints a curated Markdown integration recipe to s
 
 # Blueprint Installer
 
-> **Who is this for:** host authors and integrators adding a provider, channel,
-> sandbox backend, or action to a repo by piping a recipe into their coding agent.
+<Callout id="doc-block-bpin1who" tone="info">
+
+**Who is this for:** host authors and integrators adding a provider, channel,
+sandbox backend, or action to a repo by piping a recipe into their coding agent.
+
+</Callout>
 
 `agent-native add` is **not** a dumb scaffolder that writes files for you. It emits a curated Markdown _integration blueprint_ to stdout. You pipe that blueprint into your own coding agent (Claude Code, Codex, …), which applies the changes against the live repo with full context.
 
@@ -111,8 +115,11 @@ Write each blueprint as an instruction set for a coding agent with no other cont
 4. **Framework rules to honor** — actions-first, no hardcoded secrets, scope ownable data, add a changeset for publishable-package source.
 5. **Verify** — typecheck, a focused `*.spec.ts`, and an end-to-end check.
 
-> [!TIP]
-> A new curated blueprint under an existing kind needs no code — but if you create a brand-new kind directory, that kind shows up in `--list` automatically too.
+<Callout id="doc-block-bpin1tip" tone="info">
+
+A new curated blueprint under an existing kind needs no code — but if you create a brand-new kind directory, that kind shows up in `--list` automatically too.
+
+</Callout>
 
 ## What's next
 

package/docs/content/cli-adapters.mdx

@@ -5,10 +5,14 @@ description: "Give the agent structured access to any CLI tool (gh, ffmpeg, stri
 
 # CLI Adapters
 
-> **Where this fits:** CLI adapters are one of two adapter seams in the
-> framework. The canonical guide is [Adapters](/docs/sandbox-adapters), which
-> covers both this seam and the `run-code` sandbox seam — including the shared
-> edge/serverless constraint. This page is the quick reference for the CLI side.
+<Callout id="doc-block-clia1fit" tone="info">
+
+**Where this fits:** CLI adapters are one of two adapter seams in the
+framework. The canonical guide is [Adapters](/docs/sandbox-adapters), which
+covers both this seam and the `run-code` sandbox seam — including the shared
+edge/serverless constraint. This page is the quick reference for the CLI side.
+
+</Callout>
 
 A CLI adapter wraps a single command-line tool (`gh`, `ffmpeg`, `stripe`, `aws`) so the agent can discover it, check whether it's installed, and run it with a consistent stdout/stderr/exit-code result. Without this seam, every script reinvents how to invoke a CLI and parse its output.
 
@@ -128,8 +132,7 @@ const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
 
 Wrap a CLI call in `defineAction` to expose it on the action surface — `defineAction` is required when the code runs inside the server action surface; use an adapter directly in a `scripts/` file otherwise. Never call `process.exit` in an action; throw an error instead.
 
-```ts
-// actions/list-prs.ts
+```ts filename="actions/list-prs.ts"
 import { defineAction } from "@agent-native/core/action";
 import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
 import { z } from "zod";

package/docs/content/client.mdx

@@ -11,6 +11,14 @@ These client/React APIs are exported from both `@agent-native/core` and `@agent-
 
 For file-based routing — adding pages, dynamic params, and navigation — see [Routing](/docs/routing).
 
+On this page: [data hooks](#fetching-mutating), [sendToAgentChat](#sendtoagentchat),
+[agent chat context state](#agent-chat-context-state),
+[openAgentSettings](#openagentsettings), [askUserQuestion](#ask-user-question),
+[MCP App host bridge](#mcp-app-host-bridge),
+[dynamic suggestions](#dynamic-suggestions),
+[useAgentChatGenerating](#useagentchatgenerating), [useDbSync](#usedbsync),
+[change versions](#use-change-version), and [cn](#cn).
+
 ## Fetching and Mutating Data {#fetching-mutating}
 
 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)).
@@ -467,3 +475,11 @@ import { cn } from "@agent-native/core/client";
   className
 )} />
 ```
+
+## What's next
+
+- [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
+- [**Routing**](/docs/routing) — file-based pages, dynamic params, and navigation
+- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` and change versions keep the UI current
+- [**Context Awareness**](/docs/context-awareness) — the `navigation`/`selection` state dynamic suggestions read
+- [**Generative UI**](/docs/generative-ui) — building richer inline chat controls beyond `askUserQuestion`

package/docs/content/cloneable-saas.mdx

@@ -1,13 +1,15 @@
 ---
-title: "Apps"
+title: "Templates"
 description: "Fork a working SaaS product and make it yours — agent included."
 ---
 
-# Apps
+# Templates
 
-Want to ship your own AI-powered analytics tool? Mail client? Forms builder? Pick an example app, and you've got a working SaaS in minutes — agent, database, auth, and deploy pipeline already wired up.
+Want to ship your own AI-powered analytics tool? Mail client? Forms builder? Pick a template, and you've got a working SaaS in minutes — agent, database, auth, and deploy pipeline already wired up.
 
-Most starter templates give you a blank scaffold and a long TODO list. Agent-native flips that. Each example app is a **complete, SaaS-grade product** — already runnable on day one, already shippable, and entirely yours to customize, brand, and deploy. Think of them as cloneable SaaS, not starter kits: you're forking a finished product, not staring at boilerplate.
+Most starter templates give you a blank scaffold and a long TODO list. Agent-native flips that. Each template is a **complete, SaaS-grade product** — already runnable on day one, already shippable, and entirely yours to customize, brand, and deploy. Think of them as cloneable SaaS, not starter kits: you're forking a finished product, not staring at boilerplate.
+
+Building a workflow with no browser UI at all — a Slack bot, a nightly report, a webhook responder? See [Automation-First Apps](/docs/pure-agent-apps) instead; the templates on this page all ship a full browser UI alongside the agent.
 
 ## Example apps {#catalog}
 
@@ -16,16 +18,16 @@ Each one is a real app you could use today, and the launching pad for your own v
 | App                                       | What it is                                                                                                     |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | [**Chat**](/docs/template-chat)           | Minimal chat-first app with durable threads, actions, auth, and a clean path to custom UI or your own backend. |
-| [**Mail**](/docs/template-mail)           | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.      |
-| [**Calendar**](/docs/template-calendar)   | An agent-native Google Calendar. Events, sync, public booking links, agent-driven scheduling.                  |
-| [**Content**](/docs/template-content)     | Open-source Obsidian for MDX. Local Markdown/MDX, Tiptap editor, Notion sync, real-time multi-user collab.     |
+| [**Mail**](/docs/template-mail)           | Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.                                  |
+| [**Calendar**](/docs/template-calendar)   | Events, sync, public booking links, agent-driven scheduling.                                                   |
+| [**Content**](/docs/template-content)     | Local Markdown/MDX editing with a Tiptap editor, Notion sync, and real-time multi-user collab.                 |
 | [**Brain**](/docs/template-brain)         | Clean company chat backed by cited institutional memory, approved sources, review gates, and citations.        |
 | [**Assets**](/docs/template-assets)       | Digital asset manager for brand libraries, uploads, references, and on-brand image/video generation.           |
-| [**Slides**](/docs/template-slides)       | An agent-native Google Slides. React-based decks the agent generates and edits directly.                       |
-| [**Analytics**](/docs/template-analytics) | An agent-native Amplitude/Mixpanel. Connect data sources, prompt for charts, pin to dashboards.                |
+| [**Slides**](/docs/template-slides)       | React-based decks the agent generates and edits directly.                                                      |
+| [**Analytics**](/docs/template-analytics) | Connect data sources, prompt for charts, pin to dashboards.                                                    |
 | [**Clips**](/docs/template-clips)         | Async screen + camera recording with transcription, chapters, and AI summaries.                                |
 | [**Design**](/docs/template-design)       | Agent-native HTML prototyping studio for interactive Alpine/Tailwind designs.                                  |
-| [**Forms**](/docs/template-forms)         | An agent-native Typeform. Build, share, collect, and route submissions to Slack, Sheets, webhooks, or Discord. |
+| [**Forms**](/docs/template-forms)         | Build, share, collect, and route submissions to Slack, Sheets, webhooks, or Discord.                           |
 | [**Plan**](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations.                                         |
 | [**Dispatch**](/docs/template-dispatch)   | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.            |
 
@@ -165,8 +167,9 @@ You don't have to. Every example app is also available as a hosted app on `agent
 
 Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
 
-## Building on this
+## What's next
 
+- [**Automation-First Apps**](/docs/pure-agent-apps) — the complementary archetype for workflows with no browser UI
 - [**Getting Started**](/docs/getting-started) — create a chat-first app, add an action, render a structured result, and grow into a page
 - [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each app
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several apps into one workspace that shares auth, brand, and agent