@agent-native/core 0.63.0 → 0.63.2

package/docs/content/pure-agent-apps.md

@@ -1,139 +1,32 @@
 ---
 title: "Pure-Agent Apps"
-description: "Apps where the first product surface is the app-agent loop: define actions, run them locally, and add UI only when users need it."
+description: "Apps where the agent is the whole product: the app-agent loop is the front door, and UI is added only when humans need it."
 ---
 
 # Pure-Agent Apps
 
-This is the minimal end of agent-native: an app whose first product surface is
-the agent loop, not a dashboard. That loop can start headlessly from CLI, jobs,
-webhooks, Slack, email, or A2A. Add Chat when a human-facing conversation UI is
-the right way to inspect and steer the work. For the full-UI end, start from a
-[template](/docs/cloneable-saas). If you are choosing between headless, chat,
-embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
+A pure-agent app is the minimal end of agent-native: the app-agent loop is the
+product, not a dashboard. You send a request from the terminal, Slack, email, a
+scheduled job, another agent, or Chat — "summarize my unread emails," "post the
+daily metrics to Slack" — and the agent acts and returns the result wherever it
+belongs. It is still a real app: actions, sessions, app state, history,
+settings, credentials, and share records all live in SQL.
 
-Imagine starting with one action and the app-agent loop. No dashboard. No
-sidebar full of menus. No forms. You ask for what you want from the terminal,
-from Slack, from email, from a scheduled job, from another agent, or from Chat -
-"summarize my unread emails," "post the daily metrics to Slack," "find the
-candidates who replied last week" - and the agent goes off and does it. The
-output shows up in the channel that asked, wherever it belongs.
+Reach for this shape when the work runs in the background, the output leaves the
+app, the domain is one-shot, or you're prototyping. The agent still needs a UI —
+not a dashboard, but a place for humans to supervise, configure, and steer it —
+which is why even pure-agent apps usually mount the built-in Chat shell.
 
-That's a pure-agent app. The agent _is_ the product.
+This is the **headless** product shape. The full decision guide, what ships in
+the box, the scaffold, repo access, and run sharing now live in one place:
 
-It is still an app, not a stateless prompt. Actions, auth sessions, app state, thread history, run history, settings, credentials, and share records live in SQL. Locally that defaults to SQLite; hosted deployments should use a persistent SQL database.
-
-## What it feels like to use one {#user-experience}
-
-Most apps are built around a UI: a database table you browse, a form you fill, a chart you read. The agent is a sidekick.
-
-In a pure-agent app, that's flipped. The agent loop is the front door. You type
-or send a request; the agent takes action; you see the result. Chat can be the
-browser front door, but headless apps can also start from CLI, jobs, webhooks,
-or A2A. Everything else - settings, history, what's currently running - is
-available when you need it, but most of the time you do not need a custom
-dashboard.
-
-Examples of where this works really well:
-
-- **Background workers** — a triage agent that watches your inbox and labels things, a daily-report agent that posts to Slack each morning, an on-call agent that responds to alerts.
-- **One-shot helpers** — "research this company and write a one-pager," "scan my GitHub issues and tell me which ones look stale."
-- **Channel-driven assistants** — agents you mostly talk to from Slack, Telegram, email, or another agent (via [A2A](/docs/a2a-protocol)). The "app" itself is mostly a control panel.
-- **Internal tools** — an agent that knows your runbooks, your APIs, your conventions, and can act on them.
-
-The hot take is "agents will replace apps." The honest version is "agents still need a UI — for humans to supervise, configure, and steer them." Pure-agent apps give you that UI without the dashboard sprawl.
-
-## When this beats a traditional app {#when}
-
-Pick the pure-agent pattern when:
-
-- **The work happens in the background.** Most of the value is created while the user isn't looking.
-- **The output leaves the app.** The agent posts to Slack, sends email, updates a third-party system. There's nothing to browse in-app — the value is elsewhere.
-- **The domain is one-shot.** Research bot, summary generator, report writer. There's no persistent object that needs a list view.
-- **You're prototyping.** Ship the agent now; add a richer UI later if it turns out users actually want one.
-
-If your product is built around persistent objects users browse, pivot, and share - emails, events, documents, charts - pick a [template](/docs/cloneable-saas) instead. Those have full UIs _plus_ the agent.
-
-## What ships in the box when you add Chat {#minimum-ui}
-
-When you add the built-in Chat shell, a pure-agent app gets five built-in
-surfaces, all provided by the framework - you don't build them:
-
-1. **Chat** — the main input. Users talk to the agent, steer it, queue tasks.
-2. **Workspace** — skills, memory, instructions, custom sub-agents, connected MCP servers, scheduled jobs. Customize the agent's behavior without shipping code.
-3. **Job history** — which scheduled jobs ran, when, whether they succeeded, what they did.
-4. **Thread history** — every past conversation, each preserved with its tool calls and final output.
-5. **Settings** — API keys, connected accounts, onboarding status.
-
-Those five are usually enough. No analytics dashboard. No Kanban. No forms. Just: talk to it, see what it's done, configure how it behaves.
-
-## Why you'd pick this over "an app with an AI sidebar" {#vs-traditional}
-
-Two reasons:
-
-1. **You don't have to build the UI.** A pure-agent app skips weeks of dashboard work. The chat handles input; the framework handles supervision and history; the agent handles output.
-2. **It's channel-agnostic from day one.** The same agent that runs in your web UI also runs from Slack, Telegram, email, and other agents — because everything goes through the agent, not the UI. See [Messaging the agent](/docs/messaging) for how that works.
-
-The trade-off: pure-agent apps don't give users a "browse-everything-at-a-glance" view. If your users need that, mix patterns: start pure-agent, add a small status page or list view if you discover users want one.
-
-## Building one {#building}
-
-If you're not a developer, you can usually start with the [Dispatch template](/docs/template-dispatch) — it's a workspace-style pure-agent app with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
-
-For developers who want the absolute minimum, start from a headless scaffold:
-
-```bash
-npx @agent-native/core@latest create my-agent --headless
-```
-
-This gives you the framework runtime, SQL-backed state, an `actions/` directory, and `pnpm agent` for running the local app-agent loop. Add one useful `defineAction()` and you have a real agent-native app. The same action can later render in chat, appear behind a button, expose an MCP tool, or move into a full UI without changing the core operation.
-
-Use [**Chat**](/docs/template-chat) when you are ready to add a browser UI but do not want a domain template. Chat is the add-UI scaffold path, not the required default for a pure-agent app.
-
-If you really want _zero_ custom UI except the agent, keep the app route focused on the built-in chat surface. The only thing the user sees is the chat. Everything else - job history, workspace, settings - is one click away in the panel's tabs.
-
-### What you still get for free {#still-free}
-
-Even with no custom UI, you still inherit every framework benefit:
-
-- **Actions** as agent tools, HTTP endpoints, MCP tools, and A2A tools. External agents, Claude Desktop, and your own HTTP clients can drive the agent without going through the chat UI.
-- **Recurring jobs** for scheduled work — "every morning at 7, summarize my unread emails and post to Slack."
-- **The workspace** for per-user customization, skills, memory, MCP connections.
-- **Sub-agent delegation** via [agent teams](/docs/agent-teams).
-- **Portability** — deploys to any serverless host with any supported SQL database.
-- **Multi-tenant by default** — each user gets their own workspace without a dev-box.
-
-### Adding a tiny bit of UI {#tiny-ui}
-
-Most pure-agent apps eventually want a little custom UI — not a dashboard, but maybe a status page, a job history, or a config screen. The [drop-in agent](/docs/drop-in-agent) components coexist with anything else you render. Add a single `/status` route that lists recent runs; keep everything else in the chat. That's usually enough.
-
-Future UI-grafting tooling should use a distinct verb or namespace. `agent-native add` already means integration blueprints such as providers, channels, and sandbox adapters, so it should not also mean "add UI to this headless app."
-
-## Repo access for cloud headless {#repo-access}
-
-Local headless apps run against the folder on your machine. For cloud headless
-apps that need repository access, use connector-scoped access: a GitHub
-connector and token CRUD that can list repositories, search files, read files,
-create or edit files, and delete files with the user's permission.
-
-Do not design this as "clone the user's repo into our VM" or "give the agent a long-lived sandbox copy of the repo" as the primary model. Sandboxes are useful for isolated code execution, but repo access should be a provider integration with explicit tokens, scoped permissions, auditability, and revocation.
-
-## Sharing sessions and runs {#sharing-runs}
-
-Pure-agent work produces durable sessions and runs. Shareability should roll out in phases:
-
-- **First:** read-only share links so a teammate can open a thread or run, inspect the sanitized transcript, outputs, and status, and follow along without taking control.
-- **Later:** permissioned writable collaboration, such as continuing a run, editing schedules, approving actions, or changing configuration with explicit access checks.
-
-That staged model keeps the first sharing surface useful without pretending collaborative control is solved before the permission model is ready.
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
 ## What's next
 
-- [**Getting Started**](/docs/getting-started) — create a chat app or headless action first
-- [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) — the full headless decision guide and APIs
+- [**Getting Started**](/docs/getting-started) — create a chat app or headless agent first
+- [**Dispatch**](/docs/template-dispatch) — the workspace template that's a great pure-agent starting point
 - [**Messaging the agent**](/docs/messaging) — how users talk to the agent across web, Slack, Telegram, email
 - [**Recurring Jobs**](/docs/recurring-jobs) — scheduled prompts the agent runs on its own
-- [**Dispatch**](/docs/template-dispatch) — the workspace template that's a great starting point for pure-agent apps
-- [**Drop-in Agent**](/docs/drop-in-agent) — mounting `<AgentPanel>` fullscreen or in a sidebar
 - [**Actions**](/docs/actions) — the tools your pure-agent will call
-- [**Workspace**](/docs/workspace) — the customization surface for skills, memory, and MCP servers

package/docs/content/real-time-collaboration.md

@@ -125,7 +125,7 @@ pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @
 
 Prevents Vite from re-bundling TipTap in incompatible ways during dev:
 
-```typescript
+```ts
 // vite.config.ts
 export default defineConfig({
   plugins: [reactRouter()],
@@ -149,7 +149,7 @@ via `registerShareableResource`. Without it, collab push events are delivered
 to all authenticated users without document-level scoping, and the server
 logs a one-time warning.
 
-```typescript
+```ts
 // server/plugins/collab.ts
 import { createCollabPlugin } from "@agent-native/core/server";
 
@@ -163,7 +163,7 @@ export default createCollabPlugin({
 
 ### 4. Use the client hook
 
-```typescript
+```ts
 import {
   useCollaborativeDoc,
   emailToColor,
@@ -186,7 +186,7 @@ const { ydoc, awareness, isLoading, activeUsers, agentActive, agentPresent } =
 
 ### 5. Add TipTap extensions
 
-```typescript
+```ts
 import Collaboration from "@tiptap/extension-collaboration";
 import CollaborationCaret from "@tiptap/extension-collaboration-caret";
 
@@ -208,7 +208,7 @@ const editor = useEditor({
 The Collaboration extension does not auto-seed from a `content` prop. If the
 Y.Doc is empty and the document has existing content, seed it:
 
-```typescript
+```ts
 useEffect(() => {
   if (!ydoc || !editor || !isLoaded) return;
   const fragment = ydoc.getXmlFragment("default");
@@ -337,7 +337,7 @@ Awareness state changes now propagate at ~150ms instead of the 2s poll cycle:
 
 Returns a reactive list of remote participants and a setter for the local presence payload:
 
-```typescript
+```ts
 import { usePresence } from "@agent-native/core/client";
 
 const { others, setPresence } = usePresence(awareness, ydoc?.clientID);
@@ -400,7 +400,7 @@ import { RemoteSelectionRings } from "@agent-native/core/client";
 
 Invoke a callback whenever the followed participant's viewport changes:
 
-```typescript
+```ts
 import { useFollowUser } from "@agent-native/core/client";
 
 const { isFollowing, stopFollowing } = useFollowUser({
@@ -435,7 +435,7 @@ The `PresenceBar` component now accepts optional follow-mode props:
 
 ### Normalized coordinate helpers {#norm-coords}
 
-```typescript
+```ts
 import { toNormalized, fromNormalized } from "@agent-native/core/client";
 
 // In a pointer event handler:
@@ -454,7 +454,7 @@ const px = fromNormalized(norm, container.getBoundingClientRect());
 
 Server-side actions call `agentUpdateSelection()` to publish where the agent is working. The design template's `edit-design` and `generate-design` actions call this automatically. Other templates can do the same:
 
-```typescript
+```ts
 import {
   agentEnterDocument,
   agentLeaveDocument,
@@ -511,7 +511,7 @@ plugin:
 
 ### Always set `resourceType`
 
-```typescript
+```ts
 createCollabPlugin({
   resourceType: "document", // the name passed to registerShareableResource
 });
@@ -535,7 +535,7 @@ Write routes (`update`, `text`, `json`, `patch`, `search-replace`) reject
 payloads exceeding the configured limit with HTTP 413. The default is 2 MB.
 Override per-plugin:
 
-```typescript
+```ts
 createCollabPlugin({
   resourceType: "document",
   maxPayloadBytes: 512 * 1024, // 512 KB
@@ -561,7 +561,7 @@ applies them atomically, so concurrent edits to different items both survive.
 **Slides (`patch-deck`)** — Instead of replacing the entire deck JSON on every
 change, the action accepts per-slide operations:
 
-```typescript
+```ts
 // Conceptual patch-deck action shape
 type PatchDeckOp =
   | { type: "patch"; slideId: string; fields: Partial<SlideFields> }
@@ -593,7 +593,7 @@ The Design template uses `Y.UndoManager` to scope undo/redo to the local
 user's own edits. Remote peer edits and agent edits are never undone by a
 user's Cmd+Z.
 
-```typescript
+```ts
 import * as Y from "yjs";
 
 const LOCAL_EDIT_ORIGIN = "local";
@@ -660,7 +660,7 @@ layers on top of the same awareness state.
 
 ## Related docs {#related}
 
-- [Real-Time Sync](/docs/real-time-sync) — the `useDbSync` + `useChangeVersion`
+- [Real-Time Sync](/docs/client#usedbsync) — the `useDbSync` + `useChangeVersion`
   system that delivers the `updatedAt` bump driving editor reconciliation.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   and `assertAccess` for the access model referenced by `resourceType`.

package/docs/content/routing.md

@@ -0,0 +1,71 @@
+---
+title: "Routing"
+description: "File-based routing for agent-native apps with React Router v7 — pages, dynamic params, and navigation."
+---
+
+# Routing
+
+Agent-native apps use **React Router v7** with file-based routing via `flatRoutes()` from `@react-router/fs-routes`. Every file in `app/routes/` becomes a URL. Templates use the dot-notation convention — dots separate URL segments inside a single filename.
+
+## File-Based Routing {#file-based-routing}
+
+### File → URL mapping
+
+| File                  | URL                | Notes                                  |
+| --------------------- | ------------------ | -------------------------------------- |
+| `_index.tsx`          | `/`                | Index route                            |
+| `settings.tsx`        | `/settings`        | Simple page                            |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | Dot = `/`, `$` = dynamic param         |
+| `_app.tsx`            | (no URL segment)   | Pathless layout — prefix with `_`      |
+| `inbox/route.tsx`     | `/inbox`           | Folder form — `route.tsx` is the index |
+
+Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a pathless layout route (no URL segment). Templates use `flatRoutes()` — the dot-notation file above is primary; the nested-folder form `inbox/route.tsx` also works.
+
+## Adding a new page {#adding-a-page}
+
+Create the file and export a default component:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+That's it — React Router picks it up automatically, no registration needed.
+
+## Dynamic params {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## Navigation {#navigation}
+
+Use `<Link>` for client-side navigation and `useNavigate()` for programmatic navigation:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## What's next
+
+- [**Client**](/docs/client) — the agent-native browser hooks and utilities
+- [**Server**](/docs/server) — file-based server routes and the `/_agent-native/` namespace

package/docs/content/sandbox-adapters.md

@@ -1,8 +1,35 @@
 ---
-title: "Sandbox Adapters"
-description: "Swap the backend that runs the agent's run-code tool — local child process by default, a remote/durable runner when you need to exceed the hosted code-exec ceiling."
+title: "Adapters"
+description: "The framework's two adapter seams: sandbox adapters swap the backend that runs the agent's run-code tool, and CLI adapters give the agent structured access to command-line tools."
+search: "adapters sandbox adapter cli adapter run-code SandboxAdapter CliAdapter ShellCliAdapter durable runner remote sandbox edge serverless child_process"
 ---
 
+# Adapters
+
+> **Who is this for:** host authors extending the runtime. App developers rarely
+> need this — the defaults work out of the box.
+
+Agent-Native has two adapter seams that factor a concern out behind a narrow,
+swappable interface:
+
+- **Sandbox adapters** swap the backend that runs the agent's `run-code` tool —
+  a local child process by default, or a Docker / remote / durable runner.
+- **CLI adapters** give the agent structured access to command-line tools
+  (`gh`, `ffmpeg`, `stripe`) with discovery, availability checks, and a
+  consistent result shape.
+
+Both share one runtime constraint: they rely on Node.js system bindings and do
+not run on edge/worker runtimes — see [Edge and serverless](#edge-serverless).
+
+## Which coding doc do I want? {#which-doc}
+
+| You want to…                                                               | Use                                          |
+| -------------------------------------------------------------------------- | -------------------------------------------- |
+| Swap the backend that runs the agent's **`run-code` tool**                 | **Sandbox adapters** (this page)             |
+| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | **CLI adapters** (this page)                 |
+| Render a Claude-Code/Codex-style **coding workspace UI**                   | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | [Harness Agents](/docs/harness-agents)       |
+
 # Sandbox Adapters
 
 The `run-code` tool runs agent-supplied JavaScript in an isolated environment. **Sandbox adapters** factor the _execution_ concern out of that tool so the backend can be swapped — a local child process by default, or a Docker / remote / durable runner — without touching the agent loop, `run-code.ts`, the localhost bridge, the env scrub, or the output formatting.
@@ -74,13 +101,13 @@ Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "
 - Temp files are cleaned up best-effort after the run.
 
 > [!WARNING]
-> The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes (Cloudflare Workers, Netlify Edge Functions). Run `run-code` in a standard Node.js environment, or register a remote adapter.
+> The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes. Run `run-code` in a standard Node.js environment, or register a remote adapter — see [Edge and serverless](#edge-serverless).
 
 ## Selecting an adapter {#selection}
 
 Resolution order — an explicitly registered adapter wins; otherwise the env var selects a built-in; otherwise the local default is used:
 
-```txt
+```text
 registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
 ```
 
@@ -127,8 +154,55 @@ Register it under a new `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and/or via
 > [!TIP]
 > The `agent-native add sandbox docker` blueprint emits a full, self-contained recipe for implementing a Docker adapter against this seam. See [Blueprint Installer](/docs/blueprint-installer).
 
+# CLI Adapters
+
+The other adapter seam 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. Every CLI adapter implements `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+For most CLIs, `ShellCliAdapter` wraps any binary with sensible defaults, and `CliRegistry` collects adapters for runtime discovery:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+Wrap a CLI call in `defineAction` to expose it on the action surface. See the [CLI Adapters](/docs/cli-adapters) quick reference for `ShellCliAdapter` options, custom adapters, and the action-wrapping pattern.
+
+## Edge and serverless {#edge-serverless}
+
+> [!WARNING]
+> Both adapter seams rely on Node.js system bindings. The sandbox `LocalChildProcessAdapter` and CLI adapters (`ShellCliAdapter` and custom adapters) use `node:child_process` (`execFile` / `spawn`), which **does not exist** on edge/worker runtimes such as Cloudflare Workers or Netlify Edge Functions. If you deploy server routes to these edge presets, executing these adapters throws a runtime exception. Run adapter endpoints and tasks in a standard Node.js environment (traditional server containers or serverless Node functions) — or, for the sandbox seam, register a remote adapter that ships work out of process.
+
 ## What's next
 
+- [**CLI Adapters**](/docs/cli-adapters) — the quick reference for the CLI seam
 - [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker` prints a Docker-adapter recipe
 - [**Agent Teams**](/docs/agent-teams) — delegating heavy work to sub-agents
 - [**Security**](/docs/security) — the env scrub and bridge allowlist posture

package/docs/content/security.md

@@ -7,6 +7,23 @@ description: "Security model for agent-native apps: input validation, SQL inject
 
 Agent-native apps are designed to be secure by default. The framework provides automatic protections at multiple layers — you get SQL-level data isolation, parameterized queries, input validation, and authentication out of the box.
 
+## What you get for free, and what you own {#what-you-own}
+
+When you build on the standard patterns, the framework already handles most of the threat surface for you:
+
+- **Data isolation** — agent SQL is rewritten so it can only see the current user's (and active org's) rows. See [Data Scoping](#data-scoping).
+- **SQL injection** — `db-query`/`db-exec` and Drizzle always parameterize. See [SQL Injection Prevention](#sql-injection).
+- **XSS** — React auto-escapes, TipTap and `react-markdown` sanitize. See [XSS Prevention](#xss).
+- **Auth & CSRF** — every `defineAction` is auth-guarded; cookies are `httpOnly` + `SameSite=lax`. See [Authentication](#auth).
+- **Secret encryption** — credentials and the vault are encrypted at rest. See [Secrets Management](#secrets).
+
+That leaves a small surface you actually have to think about:
+
+- **A. Tag your tables for scoping.** Add `owner_email` (and `org_id` for team data) via [`ownableColumns()`](#data-scoping), and route Drizzle reads/writes through the [access guards](#access-guards).
+- **B. Validate and route external input.** Give every action a Zod [`schema:`](#input-validation), and send any server-side fetch of a user/agent URL through the [SSRF guard](#ssrf).
+
+Get those two right and the rest is defaults. The [Production Checklist](#production-checklist) is the one-page confirmation before you ship.
+
 ## Security by Design {#secure-by-design}
 
 The framework architecture prevents common vulnerabilities when you use the standard patterns:
@@ -26,7 +43,7 @@ The framework architecture prevents common vulnerabilities when you use the stan
 
 Use `defineAction` with a Zod `schema:` for every action. The framework validates input automatically before your code runs:
 
-```typescript
+```ts
 import { z } from "zod";
 import { defineAction } from "@agent-native/core/action";
 
@@ -48,7 +65,7 @@ Invalid input returns clear error messages (400 for HTTP, structured error for a
 
 The framework's `db-query` and `db-exec` tools use parameterized queries. User input is passed as arguments, never interpolated into the SQL string:
 
-```typescript
+```ts
 // SAFE — parameterized query (framework default)
 await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] });
 
@@ -72,7 +89,7 @@ React auto-escapes all JSX expressions. Additional guidelines:
 
 Any server-side `fetch` of a user- or agent-controlled URL must go through the framework SSRF guard, or it can be pointed at cloud metadata (`169.254.169.254`), `localhost`, or internal services:
 
-```typescript
+```ts
 import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
 
 const res = await ssrfSafeFetch(userProvidedUrl, {}, { maxRedirects: 3 });
@@ -98,7 +115,7 @@ The signed-in session carries `email` and (when an org is active) `orgId`. The f
 
 Every table with user-specific data **must** have an `owner_email` text column. Use the camelCase Drizzle property name — `accessFilter` reads `resourceTable.ownerEmail`:
 
-```typescript
+```ts
 import {
   table,
   text,
@@ -141,7 +158,7 @@ For multi-user apps where teams share data, add an `org_id` column. When both co
 
 The `ownableColumns()` schema helper adds `owner_email`, `org_id`, and `visibility` in one call, so new tenant-aware tables get the full scoping contract by default:
 
-```typescript
+```ts
 import { table, text, ownableColumns } from "@agent-native/core/db/schema";
 
 export const projects = table("projects", {
@@ -212,7 +229,43 @@ Without `A2A_SECRET` in production, every A2A endpoint and the `/_agent-native/i
 
 Inbound webhook handlers (Resend, SendGrid, Slack, Telegram, WhatsApp, Recall.ai, Deepgram, Zoom, Google Docs Pub/Sub) refuse forged requests by default in production: when the corresponding signing secret env var is missing, the handler returns 401 instead of accepting and dispatching.
 
-This was previously a "warn and accept" stance — set the secret you'd otherwise be missing, or opt back into the old behavior with `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` for local dev only. See [deployment.md → Inbound Webhooks](/docs/deployment#env-webhooks) for the full env-var list.
+This was previously a "warn and accept" stance — set the secret you'd otherwise be missing, or opt back into the old behavior with `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` for local dev only. See [Messaging](/docs/messaging#env-vars) for the per-integration signing-secret variables.
+
+## Production Checklist {#production-checklist}
+
+### Auth & secrets
+
+- [ ] `BETTER_AUTH_SECRET` set to a random 32+ char string (`openssl rand -hex 32`), unless this is a hosted workspace deploy deriving it from `A2A_SECRET`
+- [ ] `OAUTH_STATE_SECRET` set to a separate random 32+ char string (don't reuse `BETTER_AUTH_SECRET`) — see [OAuth State Signing](#oauth-state)
+- [ ] `A2A_SECRET` set on every app that calls or receives A2A traffic — see [A2A Identity Verification](#a2a-identity)
+- [ ] `SECRETS_ENCRYPTION_KEY` set (or rely on the `BETTER_AUTH_SECRET` fallback) — see [Secrets Management](#secrets)
+- [ ] `AUTH_SKIP_EMAIL_VERIFICATION` is **not** set in production (or set only on QA preview deploys)
+
+### Webhook secrets (set the ones for integrations you use)
+
+- [ ] Signing secret set for each enabled inbound integration — see [Inbound Webhooks](#webhooks) and [Messaging](/docs/messaging#env-vars) for the per-integration list
+- [ ] `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` is **not** set in prod
+
+### Schema
+
+- [ ] Every user-facing table has `owner_email`, multi-user tables also `org_id` — see [Data Scoping](#data-scoping)
+- [ ] Ownable-table reads/writes go through the [access guards](#access-guards)
+- [ ] All actions use `defineAction` with Zod `schema:` — see [Input Validation](#input-validation)
+- [ ] Server-side fetches of user/agent URLs go through `ssrfSafeFetch` — see [SSRF](#ssrf)
+- [ ] No `dangerouslySetInnerHTML` with user content (or output is run through DOMPurify)
+- [ ] No string-concatenated SQL
+- [ ] `pnpm guards` is clean (`guard-no-unscoped-queries`, `guard-no-env-credentials`, `guard-no-env-mutation`, `guard-no-localhost-fallback`, `guard-no-unscoped-credentials`, `guard-no-drizzle-push`)
+- [ ] Tested with two user accounts to verify data isolation
+
+### Misc hardening
+
+- [ ] `AGENT_NATIVE_DEBUG_ERRORS` is **not** set in real prod (only on debug previews)
+- [ ] `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK` is **not** set unless your org actually shares workspace keys — see [Cross-User Tooling Secrets](#tooling-secrets)
+- [ ] In multi-tenant deployments, **users bring their own `ANTHROPIC_API_KEY`** — the framework refuses to fall back to the deploy-level env var
+
+---
+
+The sections below cover niche environment flags you only reach for in specific deployments. Most apps never touch them.
 
 ## OAuth State Signing {#oauth-state}
 
@@ -237,36 +290,3 @@ AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
 ```
 
 Workspace-scope secret writes still require org owner/admin role regardless of this flag.
-
-## Production Checklist {#production-checklist}
-
-### Auth & secrets
-
-- [ ] `BETTER_AUTH_SECRET` set to a random 32+ char string (`openssl rand -hex 32`), unless this is a hosted workspace deploy deriving it from `A2A_SECRET`
-- [ ] `OAUTH_STATE_SECRET` set to a separate random 32+ char string (don't reuse `BETTER_AUTH_SECRET`), unless this is a hosted workspace deploy deriving it from `A2A_SECRET`
-- [ ] `A2A_SECRET` set on every app that calls or receives A2A traffic
-- [ ] `SECRETS_ENCRYPTION_KEY` set (or rely on the `BETTER_AUTH_SECRET` fallback)
-- [ ] `AUTH_SKIP_EMAIL_VERIFICATION` is **not** set in production (or set only on QA preview deploys)
-
-### Webhook secrets (set the ones for integrations you use)
-
-- [ ] `EMAIL_INBOUND_WEBHOOK_SECRET` if Resend / SendGrid inbound is enabled
-- [ ] `SLACK_SIGNING_SECRET` if Slack is enabled
-- [ ] `TELEGRAM_WEBHOOK_SECRET` / `WHATSAPP_APP_SECRET` for those integrations
-- [ ] `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` is **not** set in prod
-
-### Schema
-
-- [ ] Every user-facing table has `owner_email`
-- [ ] Multi-user tables also have `org_id`
-- [ ] All actions use `defineAction` with Zod `schema:`
-- [ ] No `dangerouslySetInnerHTML` with user content (or output is run through DOMPurify)
-- [ ] No string-concatenated SQL
-- [ ] `pnpm guards` is clean (`guard-no-unscoped-queries`, `guard-no-env-credentials`, `guard-no-env-mutation`, `guard-no-localhost-fallback`, `guard-no-unscoped-credentials`, `guard-no-drizzle-push`)
-- [ ] Tested with two user accounts to verify data isolation
-
-### Misc hardening
-
-- [ ] `AGENT_NATIVE_DEBUG_ERRORS` is **not** set in real prod (only on debug previews)
-- [ ] `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK` is **not** set unless your org actually shares workspace keys
-- [ ] In multi-tenant deployments, **users bring their own `ANTHROPIC_API_KEY`** — the framework refuses to fall back to the deploy-level env var