@agent-native/core 0.157.4 → 0.157.5

package/docs/content/actions-other-surfaces.mdx

@@ -0,0 +1,167 @@
+---
+title: "Other Surfaces"
+description: "Everything that calls an action beyond the UI hooks: native chat UI widget results, the CLI, A2A, MCP, and the two standard actions every template ships."
+---
+
+# Other Surfaces
+
+The UI-hook surface is covered on [Data & Sync](/docs/client-data): `useActionQuery()`, `useActionMutation()`, and `callAction()`. This page covers everything else that can call, or be driven by, an action.
+
+## Rendering native chat UI {#native-chat-ui}
+
+Actions can return structured widget data that the in-app chat renders
+natively. This is the first-party chat path for reusable tables, charts, setup
+summaries, and insight cards. Use [Generative UI](/docs/generative-ui) when the
+agent needs to generate arbitrary interactive controls inside the in-app chat,
+and use [MCP Apps](/docs/mcp-apps) for inline UI in external MCP hosts.
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_CHART_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataChartWidgetResult,
+  dataChartWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Summarize response trends.",
+  readOnly: true,
+  outputSchema: dataChartWidgetResultSchema,
+  chatUI: { renderer: ACTION_CHAT_UI_DATA_CHART_RENDERER },
+  run: async () =>
+    createDataChartWidgetResult({
+      title: "Response trends",
+      chartSeries: {
+        type: "line",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 12 },
+          { day: "Tue", responses: 18 },
+        ],
+      },
+    }),
+});
+```
+
+The built-in discriminants are `"data-table"`, `"data-chart"`, and
+`"data-insights"`, with server-safe builders and schemas in
+`@agent-native/core/data-widgets`. Use `data-chart` for chart-only answers,
+`data-table` for SQL/list results, and `data-insights` only when a combined
+summary/chart/table card is the right output. See
+[Native Chat UI](/docs/native-chat-ui) for the full result contract, or
+[BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) if you're
+wiring a custom agent runtime instead of the built-in chat loop. See
+[Agent Surfaces](/docs/agent-surfaces) for how the same action can stay
+automation-friendly, render in chat, or grow into a full screen.
+
+## Calling it from the CLI {#cli}
+
+Every action is runnable via `pnpm action`:
+
+```bash
+pnpm action reply-to-email '{"emailId":"thread-123","body":"Thanks!"}'
+```
+
+JSON input is the preferred shape for agents and complex objects. Flags work
+the same way for simple manual runs and existing scripts:
+
+```bash
+pnpm action reply-to-email --emailId thread-123 --body "Thanks!"
+```
+
+This is useful for agent-dev loops, scripts, and cron jobs.
+
+## Calling it from another agent (A2A) {#a2a}
+
+If your app is an [A2A](/docs/a2a-protocol) peer, other agent-native apps discover your actions automatically and can call them by name. Same-origin deploys skip JWT signing. Cross-origin deploys use a shared `A2A_SECRET` instead.
+
+## Exposing it over MCP {#mcp}
+
+With MCP enabled, your actions show up in the framework's MCP server at `/mcp`. Every caller gets a compact catalog by default (app-facing builtins plus the template-declared app actions), and `tool-search` is always present so any other tool stays reachable on demand. The full action surface is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`), and [`publicAgent.expose`](/docs/actions-access-control#public-agent) opts a safe read/ingest tool onto the public surface. See [MCP Protocol](/docs/mcp-protocol) for catalog tiers, auth, and the `mcpApp` resource details.
+
+For UI-capable MCP hosts, an action can declare an optional MCP Apps resource via the `mcpApp` field (plus a matching `link`) so capable hosts render the result inline. When `link` and `mcpApp` should point at the same route, `embedRoute()` builds both from one pure path builder:
+
+```ts
+import { embedRoute } from "@agent-native/core";
+
+export default defineAction({
+  description: "Create an email draft for review.",
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => ({ body }),
+  ...embedRoute({
+    title: "Review draft",
+    openLabel: "Open in Mail",
+    path: ({ result }) => ({
+      label: "Open draft in Mail",
+      url: "/_agent-native/open?app=mail&view=inbox",
+    }),
+  }),
+});
+```
+
+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}
+
+Every template should include these two for [context awareness](/docs/context-awareness).
+
+### view-screen {#view-screen}
+
+Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent calls this when it needs a fresh look at the screen.
+
+```ts
+// actions/view-screen.ts
+import { defineAction } from "@agent-native/core/action";
+import { readAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Read the current screen state for context.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const navigation = await readAppState("navigation");
+    const screen: Record<string, unknown> = { navigation };
+
+    if (navigation?.view === "inbox") {
+      screen.emailList = await listEmailsForLabel(navigation.label);
+    }
+
+    return screen;
+  },
+});
+```
+
+### navigate {#navigate}
+
+Writes a one-shot navigation command to application state. The UI reads it, navigates, and deletes the entry.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the user to a view.",
+  schema: z.object({
+    view: z.string(),
+    threadId: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+## What's next
+
+- [**Data & Sync**](/docs/client-data) — `useActionQuery`, `useActionMutation`, and `callAction` from the UI
+- [**Overview**](/docs/actions-overview) — what an action is and the hello-world walkthrough
+- [**Context Awareness**](/docs/context-awareness) — the `view-screen` + `navigate` pattern in depth
+- [**A2A Protocol**](/docs/a2a-protocol) — how other agents discover and call your actions
+- [**MCP Protocol**](/docs/mcp-protocol) — catalog tiers, auth, and `mcpApp` resources
+- [**Generative UI**](/docs/generative-ui) — rendering transient or persisted generated UI inline in chat
+- [**Native Chat UI**](/docs/native-chat-ui) — the full widget result contract

package/docs/content/actions-overview.mdx

@@ -0,0 +1,214 @@
+---
+title: "Overview"
+description: "Actions are the single source of truth for anything your app does. Define one with defineAction() and it fans out to an agent tool, UI hooks, HTTP, an MCP tool, an A2A tool, and a CLI command."
+---
+
+# Overview
+
+Actions are the single source of truth for anything your app does. Define one with `defineAction()` and drop it in `actions/`. Every surface below picks it up automatically. You write the logic once. No surface gets its own copy, and none can drift out of sync with the others.
+
+<Cards columns={2}>
+
+### :robot: [Agent Tool](/docs/agent-surfaces)
+
+The agent reads the description and schema as a callable tool. Ask for it in chat, like "reply to this ticket" or "summarize this thread."
+
+### :components: [UI Hooks](/docs/client-data)
+
+`useActionQuery()`, `useActionMutation()`, and `callAction()` call the same action from React. A click and a chat message run the exact same operation.
+
+### :server: [Framework Transport](/docs/http-api)
+
+Auto-mounted at `/_agent-native/actions/<name>` on startup. The UI hooks call this route under the hood, and an external HTTP client can call it directly too.
+
+### :plug: [MCP Tool](/docs/actions-other-surfaces#mcp)
+
+Shows up as a tool to any MCP host: Claude, Claude Desktop, Cursor, Codex. Use it when a different AI client should drive your app.
+
+### :network: [A2A Tool](/docs/actions-other-surfaces#a2a)
+
+Other agent-native apps discover and call it over A2A. Use it when a second app in your workspace needs this one to act on its behalf.
+
+### :terminal: [CLI Command](/docs/actions-other-surfaces#cli)
+
+`pnpm action <name>` runs it from a terminal. Use it for scripts, cron jobs, and quick manual tests.
+
+</Cards>
+
+Most apps build a separate API layer between the frontend and the database, one that only the browser can call. An agent that wants the same capability needs its own, separate integration, written and maintained again. Agent-native apps skip that split. The UI and the agent call the exact same action, so there is only one implementation to write, and only one place for a bug to hide.
+
+<Diagram id="doc-block-actions-overview-2" title="Traditional frontend vs. Agent Native" summary="A traditional frontend calls its own API layer, which only it can reach. In Agent Native, app/ and the agent both call the same actions, so every capability built here is agent-callable for free.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Traditional</div>
+    <div class="diagram-node">app/ (React frontend)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API layer</strong>
+      <small class="diagram-muted">only the frontend calls it</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React frontend)</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">equal partners, same operations</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+If the UI and the agent both need to do something, reach for an action instead of a custom route. For the rare case where a route-shaped protocol is the right call, visit [Prefer Actions For App Operations](/docs/server-overview#actions-first).
+
+## Where Actions Fit {#role}
+
+`app/` (visit [Client Overview](/docs/client-overview#role)) and the agent both resolve to the same actions and the same SQL database. There is no separate "app backend" this layer talks to that the agent can't also reach. Building a feature means defining an operation here and getting a UI, an agent tool, and every other surface for it at the same time.
+
+`actions/` itself is a flat folder. Each file is one action: a `defineAction()` call exported as the file's default export. The framework scans this folder on startup and mounts every file it finds. There is no registration step and no index file to keep up to date.
+
+An action's `run()` body is regular server code, so it commonly reaches into a few other directories:
+
+<FileTree
+  id="doc-block-actions-overview-filetree"
+  entries={[
+    {
+      path: "actions/reply-to-email.ts",
+      note: "One action per file. Exports a defineAction() call, and the framework mounts it automatically.",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "Drizzle table definitions most actions read and write through.",
+    },
+    {
+      path: "server/lib/access.ts",
+      note: "Shared access guards (accessFilter, assertAccess, authorize) reused across actions.",
+    },
+    {
+      path: "shared/feature-flags.ts",
+      note: "Flag definitions an action and a server plugin both check.",
+    },
+    {
+      path: "app/components/ReplyButton.tsx",
+      note: "Calls the action from the UI with useActionMutation.",
+    },
+  ]}
+/>
+
+Nothing outside `actions/` should import an action's `run` function directly. Call it through one of the surfaces above instead: the agent tool, a UI hook, HTTP, MCP, A2A, or the CLI. Every one of those paths runs the same schema validation, access checks, and audit trail.
+
+## Start with one action {#hello-action}
+
+The first operation in a chat-first app can be tiny. In the Chat template,
+replace `actions/hello.ts` or add a new file beside it:
+
+```ts
+// actions/hello.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Say hello from the local agent.",
+  schema: z.object({
+    name: z.string().default("world"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});
+```
+
+Run it from the same folder:
+
+```bash
+pnpm action hello '{"name":"Steve"}'
+```
+
+The CLI accepts a JSON object as the action input, which matches the structured
+tool calls agents already make. Simple flags still work for quick manual runs:
+
+```bash
+pnpm action hello --name Steve
+```
+
+Then run the app-agent loop against the folder:
+
+```bash
+npx agent-native agent "Call hello for Steve and explain the result"
+```
+
+That is the same app-agent loop your scheduled jobs, chat UI, external MCP
+tools, and future screens will use. Chat and domain templates are for adding UI
+around actions, not a required prerequisite for the action itself.
+
+## What's next
+
+- [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy, schema, and HTTP config
+- [**Access & Authorization**](/docs/actions-access-control) — exposure flags, `ctx` scoping, and `authorize`
+- [**Run Context**](/docs/actions-run-context) — the full `ctx` field table
+- [**Other Surfaces**](/docs/actions-other-surfaces) — native chat UI, CLI, A2A, MCP, and standard actions
+- [**Advanced & Legacy**](/docs/actions-advanced) — feature-flag gating and legacy CLI-style actions
+- [**Overview**](/docs/client-overview) — the `app/` side of this same contract
+- [**Data & Sync**](/docs/client-data) — `useActionQuery`, `useActionMutation`, and `callAction` in the UI
+- [**Agent Surfaces**](/docs/agent-surfaces) — how one action grows from chat tool to full screen

package/docs/content/actions-run-context.mdx

@@ -0,0 +1,180 @@
+---
+title: "Run Context"
+description: "The ctx second argument passed to run(): the full ActionRunContext signature and the caller union, for tracking, automation attribution, and cross-cutting concerns."
+---
+
+# Run Context
+
+`run` receives an optional second argument, `ctx`, carrying the resolved request identity and the surface that invoked the action. Read it instead of calling `getRequestUserEmail()` / `getRequestOrgId()` by hand, and pass the whole `ctx` to tracking:
+
+```ts
+export default defineAction({
+  description: "Log an audit entry for the current request.",
+  schema: z.object({ event: z.string() }),
+  run: async (args, ctx) => {
+    // ctx is undefined-safe: a 1-arg `run(args)` is still valid.
+    const actor = ctx?.userEmail ?? "system";
+    if (ctx?.caller === "frontend") {
+      // tighter rules for browser-initiated calls, looser for "tool"/"cli"
+    }
+    await db.insert(audit).values({
+      actor,
+      orgId: ctx?.orgId ?? null,
+      source: ctx?.caller ?? "unknown",
+      event: args.event,
+    });
+    return { ok: true };
+  },
+});
+```
+
+Most actions only ever read `ctx?.userEmail` and `ctx?.orgId`, the [access-control scoping](/docs/actions-access-control#access-control) used in nearly every real action. The rest of this page covers cross-cutting concerns like tracking and automation attribution, which fewer actions need.
+
+## The `ctx` argument {#ctx}
+
+`ctx` carries two kinds of information: the resolved request identity (`userEmail`, `orgId`) that's present on nearly every call, and metadata about the surface that invoked the action (`caller`, plus surface-specific fields like `threadId` or `automation` that are only populated for certain callers). The full shape, as the second argument to `run()`:
+
+<Signature
+  id="doc-block-actions-run-context-1"
+  name="run"
+  params={[
+    {
+      name: "args",
+      type: "TInput",
+      description: "The validated input, parsed from `schema`.",
+    },
+    {
+      name: "ctx",
+      type: "ActionRunContext",
+      optional: true,
+      description:
+        "The resolved request identity and the surface that invoked the action. Undefined-safe: a 1-argument `run(args)` handler is still valid.",
+      fields: [
+        {
+          name: "userEmail",
+          type: "string",
+          optional: true,
+          description:
+            "Resolved request user. **Never defaulted to a dev identity**: `undefined` when the request has no authenticated user. Apply your own fallback if you need one.",
+        },
+        {
+          name: "orgId",
+          type: "string | null",
+          description:
+            "Resolved org id, or `null` when the request has no org.",
+        },
+        {
+          name: "caller",
+          type: "ActionCaller",
+          description:
+            "How the action was invoked. See [the caller union](#caller) below.",
+        },
+        {
+          name: "send",
+          type: "(event) => void",
+          optional: true,
+          description:
+            'Emits an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`). `undefined` elsewhere.',
+        },
+        {
+          name: "attachments",
+          type: "AgentChatAttachment[]",
+          optional: true,
+          description:
+            'Files, images, and pasted text blocks submitted with the current agent turn. Populated only when `caller: "tool"`. `undefined` on all other surfaces.',
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description:
+            'Aborts when the run is soft-timed-out, cancelled, or the server shuts down. Populated only when `caller: "tool"`. Long-running actions can observe it to cancel early instead of waiting for the per-tool 60s hard timeout.',
+        },
+        {
+          name: "actionName",
+          type: "string",
+          optional: true,
+          description:
+            "The registry key of the action being called (e.g. `delete-recording`), set at each dispatch site so cross-cutting concerns like the audit log can attribute the call. `undefined` for direct programmatic `run()` calls that bypass the dispatcher.",
+        },
+        {
+          name: "threadId",
+          type: "string",
+          optional: true,
+          description:
+            'The agent conversation thread that triggered this call. Populated only when `caller: "tool"`, so the audit log can link a mutation back to the exact agent run.',
+        },
+        {
+          name: "runId",
+          type: "string",
+          optional: true,
+          description:
+            'The agent run attempt that triggered this call. Populated only when `caller: "tool"`.',
+        },
+        {
+          name: "turnId",
+          type: "string",
+          optional: true,
+          description:
+            'The specific turn within that run that triggered this call. Populated only when `caller: "tool"`.',
+        },
+        {
+          name: "automation",
+          type: "ActionAutomationContext",
+          optional: true,
+          description:
+            'Present only when `caller: "automation"`. Carries `triggerId`, `triggerName`, and an optional `policyId` for the event-triggered automation that dispatched this call.',
+        },
+        {
+          name: "networkProtocol",
+          type: '"a2a" | "mcp" | "provider-api"',
+          optional: true,
+          description:
+            "Which delegated-call protocol this request arrived over. Set only for those direct-dispatch paths.",
+        },
+        {
+          name: "networkId",
+          type: "string",
+          optional: true,
+          description:
+            "A correlation id for that delegated call, e.g. the A2A delegation JWT id.",
+        },
+        {
+          name: "networkPeer",
+          type: "string",
+          optional: true,
+          description: "The calling peer's identity for that delegated call.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TReturn> | TReturn",
+    description:
+      "The action's result, validated against `outputSchema` if one is set.",
+  }}
+/>
+
+`run()` stays backward compatible: existing 1-argument handlers and handlers that only destructure `{ send }` continue to work unchanged.
+
+### The `caller` union {#caller}
+
+`caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a" | "automation"`:
+
+| `caller`       | Set when…                                                                                                                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"tool"`       | The in-app agent loop, a sub-agent or agent team, or natural-language cross-app A2A delegation, which drives the same agent loop, so its tool calls are `"tool"`.                                        |
+| `"frontend"`   | A browser call via `useActionMutation()`, `useActionQuery()`, or `callAction()` (tagged with the `X-Agent-Native-Frontend: 1` header).                                                                   |
+| `"http"`       | A bare programmatic `POST` or `GET` to `/_agent-native/actions/<name>` without the frontend marker.                                                                                                      |
+| `"cli"`        | `pnpm action <name>` (the CLI runner).                                                                                                                                                                   |
+| `"mcp"`        | An external agent over the MCP `tools/call` endpoint.                                                                                                                                                    |
+| `"a2a"`        | A direct HTTP call to `/_agent-native/actions/<name>` carrying a signed A2A delegation token. This is an explicitly exposed, cross-app dispatch, distinct from the natural-language `"tool"` path above. |
+| `"automation"` | An event-triggered automation dispatched from a stored workspace trigger. `ctx.automation` carries the trigger lineage. See [Automations](/docs/automations).                                            |
+
+## What's next
+
+- [**Access & Authorization**](/docs/actions-access-control) — the `ctx.userEmail`/`ctx.orgId` scoping pattern this context enables
+- [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy and HTTP config
+- [**Other Surfaces**](/docs/actions-other-surfaces) — how CLI, A2A, MCP, and automation callers set `caller`
+- [**Audit Log**](/docs/audit-log) — how `threadId`/`runId`/`turnId` link a mutation back to its agent run
+- [**Automations**](/docs/automations) — the `ctx.automation` trigger lineage

package/docs/content/agent-surfaces.mdx

@@ -591,7 +591,7 @@ tool-result metadata. Start there when wiring an external agent into the chat.
 
 <Cards>
 
-### [Actions](/docs/actions)
+### [Actions](/docs/actions-overview)
 
 Define the operation once. Every surface above calls the same one.
 

package/docs/content/agent-teams.mdx

@@ -328,4 +328,4 @@ When a sub-agent is at or below the cap, the framework injects a line into its r
 
 - [**Agent Resources — Custom Agents**](/docs/agent-resources#custom-agents) — the profile format
 - [**A2A Protocol**](/docs/a2a-protocol) — when the "sub-agent" lives in a different app entirely
-- [**Actions**](/docs/actions) — the tools a sub-agent calls
+- [**Actions**](/docs/actions-overview) — the tools a sub-agent calls

package/docs/content/agent-web-surfaces.mdx

@@ -212,6 +212,6 @@ The audit exits non-zero if a required public surface is missing.
 
 ## What's next
 
-- [**Actions**](/docs/actions) — how to opt actions into the public agent protocol
+- [**Actions**](/docs/actions-overview) — how to opt actions into the public agent protocol
 - [**MCP Protocol**](/docs/mcp-protocol) — the MCP surface that `publicMcp: true` enables
 - [**Deployment**](/docs/deployment) — where these static files are written during builds

package/docs/content/audit-log.mdx

@@ -182,7 +182,7 @@ Configure via environment:
 
 ## What's next
 
-- [**Actions**](/docs/actions) — the `defineAction` seam where capture happens
+- [**Actions**](/docs/actions-overview) — the `defineAction` seam where capture happens
 - [**Human-in-the-Loop Approvals**](/docs/human-approval) — gated actions, recorded as `denied`
 - [**Security & Data Scoping**](/docs/security) — the ownership model audit reads reuse
 - [**Observability**](/docs/observability) — agent-run telemetry (the other "what happened")

package/docs/content/automation-connectors.mdx

@@ -119,5 +119,5 @@ See [Zapier REST Hook triggers](https://docs.zapier.com/integrations/build/hook-
 
 - [**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
+- [**Actions**](/docs/actions-overview) — `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

@@ -450,7 +450,7 @@ for the full `plan.commented` payload reference and all four plan events.
 ## What's next
 
 - [**Recurring Jobs**](/docs/recurring-jobs) — legacy compatibility and advanced scheduled-job fields
-- [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
+- [**Actions**](/docs/actions-overview) — 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
 - [**Events and Automations**](/docs/template-plan-automations) — the Plan event reference and automation recipes

package/docs/content/blueprint-installer.mdx

@@ -124,5 +124,5 @@ A new curated blueprint under an existing kind needs no code — but if you crea
 ## What's next
 
 - [**Sandbox Adapters**](/docs/sandbox-adapters) — the seam the `add sandbox docker` blueprint targets
-- [**Actions**](/docs/actions) — the single source of truth every blueprint builds on
+- [**Actions**](/docs/actions-overview) — the single source of truth every blueprint builds on
 - [**External Agents**](/docs/external-agents) — connecting the coding agent you pipe blueprints into

package/docs/content/cli-adapters.mdx

@@ -169,4 +169,4 @@ CLI adapters use `node:child_process`, which does not exist on edge/worker runti
 ## What's next
 
 - [**Adapters**](/docs/sandbox-adapters) — the canonical guide to both adapter seams.
-- [**Actions**](/docs/actions) — the action surface CLI adapters are usually wrapped in.
+- [**Actions**](/docs/actions-overview) — the action surface CLI adapters are usually wrapped in.

package/docs/content/client-agent-chat.mdx

@@ -37,7 +37,7 @@ The user experience is as follows:
 
 1. The user picks **Offer a refund**, which causes `sendDraftRequest()` to send the prompt and ticket context to the agent.
 
-1. The agent calls the `draft-ticket-reply` [action](/docs/actions), and the drafted reply appears in the reply composer.
+1. The agent calls the `draft-ticket-reply` [action](/docs/actions-overview), and the drafted reply appears in the reply composer.
 
 ## askUserQuestion(opts) {#ask-user-question}
 

package/docs/content/client-data.mdx

@@ -5,7 +5,7 @@ description: "The action hooks app/ uses to read, write, and stay live-synced wi
 
 # Data & Sync
 
-The primary way to read and write app data from client application is through [action](/docs/actions) hooks. By embedding requests into actions, both your client and agent can interact with your application in the same way.
+The primary way to read and write app data from client application is through [action](/docs/actions-overview) hooks. By embedding requests into actions, both your client and agent can interact with your application in the same way.
 
 In the example below, a ticket is assigned to the current user manually through a dropdown, and then through the chat agent. Both the UI and agent access the same action.
 
@@ -426,7 +426,7 @@ For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating a
 
 - [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout this page's hooks live in
 - [**Agent Chat**](/docs/client-agent-chat) — sending prompts and staging context for the agent
-- [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
+- [**Actions**](/docs/actions-overview) — the `defineAction` surface behind every hook on this page
 - [**Advanced**](/docs/client-advanced) — direct `application_state` access
 - [**Sync Internals**](/docs/client-sync-internals) — syncing a raw `useQuery` with `useChangeVersion`
 - [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` keeps the UI current