@agent-native/core 0.164.4 → 0.164.12

package/docs/content/actions-access-control.mdx

@@ -83,7 +83,141 @@ Use it only for safe, read-only, or ingest-only actions, the kind you'd let a st
 
 A handful of actions are too consequential to let the agent run on its own, like sending an email, charging a card, or 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.
 
-See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full end-to-end flow.
+<Callout tone="warning">
+  Keep approvals rare. Every gated action is a hard stop in the agent loop. It
+  interrupts the run and demands a human round-trip. Use `needsApproval` only
+  for genuinely high-consequence, hard-to-undo, outward-facing operations. If
+  you find yourself gating reads or routine writes, you're holding it wrong. The
+  default is **off**, and almost every action should leave it off.
+</Callout>
+
+<AnnotatedCode
+  id="doc-block-13p4g9y"
+  title="Gating the one consequential action"
+  filename="actions/send-email.ts"
+  language="ts"
+  code={
+    'export default defineAction({\n  description: "Send an email via Gmail.",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting and queueing are\n  // not affected. Only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "10",
+      label: "The whole gate",
+      note: "One flag. When it is truthy and the call has not been approved, the loop stops before `run`. The model never reaches the side effect on its own.",
+    },
+    {
+      lines: "11-13",
+      label: "run() is untouched",
+      note: "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`.",
+    },
+  ]}
+/>
+
+- **`needsApproval: true`** always requires approval.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** requires approval only when the predicate returns true. Use this to gate conditionally, for example only for external recipients or only above a dollar threshold:
+
+  ```ts
+  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
+  ```
+
+  Keep the predicate pure and fast. If the predicate throws an error, the framework treats the call the same as if the predicate had returned true, so the action pauses for approval instead of running. This means a broken predicate can never silently let a high-consequence action run without a human approving it first.
+
+When `needsApproval` is omitted, behavior is byte-for-byte unchanged. There is no extra cost on the common path.
+
+This works the same way for legacy `parameters`-style actions and for schema-based actions. It also works the same way for the in-app agent, sub-agents, A2A, and MCP callers, because every agent surface routes through the same loop.
+
+### How the loop pauses {#loop}
+
+When the agent calls a gated action and this specific call has **not** already been approved, the loop does **not** execute `run()`. Instead it:
+
+1. Resolves the gate. For a predicate, the loop calls `needsApproval(input, ctx)`. If that call throws an error, the loop treats it the same as a `true` result, so the action requires approval.
+2. Emits a `tool_start` event (so the UI shows the call) followed immediately by an **`approval_required`** event, then stops the turn. The action's side effect never happens.
+
+The `approval_required` event carries everything the client needs to render an affordance:
+
+| Field         | Type     | Notes                                                               |
+| ------------- | -------- | ------------------------------------------------------------------- |
+| `tool`        | `string` | The action name the agent tried to call.                            |
+| `input`       | object   | The arguments the agent passed.                                     |
+| `approvalKey` | `string` | **Stable key** the client echoes back to approve _this exact call_. |
+| `toolCallId`  | `string` | The model-side tool-call id, when available.                        |
+
+The `approvalKey` is derived deterministically from the tool name plus its input, so the same logical call always produces the same key. The model never sees or sets it. It exists purely as a handshake between the framework and the human's Approve affordance.
+
+The paused tool returns a result telling the model the turn is paused and not to retry, so the model does not spin.
+
+### How the human approves {#approve}
+
+On `approval_required`, the chat UI renders an **Approve / Deny** affordance on the paused tool call. This is wired automatically in `AssistantChat`. You do not need to build it per template.
+
+<WireframeBlock id="doc-block-humanapprovalwf1">
+  <Screen
+    surface="popover"
+    html={
+      "<div style='display:flex;flex-direction:column;box-sizing:border-box;padding:16px;gap:12px'><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><div style='display:flex;align-items:center;gap:8px'><span class='wf-pill warn'>Needs approval</span><strong>send-email</strong></div><div style='display:flex;flex-direction:column;gap:2px'><span class='wf-muted'>to: alex@acme.com</span><span class='wf-muted'>subject: Following up on the proposal</span></div><div style='display:flex;gap:8px'><button>Deny</button><button class='primary'>Approve</button></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+- **Approve** re-issues the turn as an ordinary continuation message that carries the call's key in `approvedToolCalls: [approvalKey]`. On the re-issued turn, the gate sees the key in the approved set and lets that specific call run normally.
+- **Deny** dismisses the affordance locally. Nothing is re-issued, so the action never runs.
+
+`approvedToolCalls` is a field on the chat request (`AgentChatRequest.approvedToolCalls`). Keys that are not present in it stay paused. Approving one call never approves any other call. Because the key is content-addressed, an approval only authorizes that exact call with those exact arguments. If the model later proposes a different send, that becomes a new key and needs its own fresh approval.
+
+### End-to-end {#flow}
+
+<Diagram id="doc-block-2nor1g" title="The approval interrupt" summary={"A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key. Only then does the side effect happen."}>
+
+```html
+<div class="diagram-approve">
+  <div class="diagram-box" data-rough>Agent calls send-email</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-panel warn" data-rough>
+    <strong>Gate truthy, call not yet approved</strong
+    ><small class="diagram-muted"
+      >loop emits tool_start + approval_required { tool, input, approvalKey
+      }</small
+    ><span class="diagram-pill warn">run() has not executed</span>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box" data-rough>
+    Human clicks Approve in chat<br /><small class="diagram-muted"
+      >client re-issues the turn with approvedToolCalls: [approvalKey]</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-panel ok" data-rough>
+    <span class="diagram-pill ok"
+      >Gate sees the key &rarr; run() executes &rarr; email sends</span
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-approve {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+}
+.diagram-approve .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: center;
+  padding: 12px 16px;
+  text-align: center;
+}
+.diagram-approve .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+The Mail template's `send-email` action is the canonical use of this gate in the framework, and it is intentionally rare. It sets `needsApproval: true` so the agent can draft and queue emails freely. It can never actually send a message without a human approving that specific send.
 
 ## Restrict callers by role {#authorize}
 
@@ -220,7 +354,7 @@ A few other options. `audit: { onRead: true }` audits a sensitive read, like a s
 - [**Overview**](/docs/actions-overview) — what an action is and the hello-world walkthrough
 - [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy, schema, and HTTP config
 - [**Run Context**](/docs/actions-run-context) — the `ctx` argument these checks read
-- [**Human-in-the-Loop Approvals**](/docs/human-approval) — the `needsApproval` gate in depth
+- [**Mail template**](/docs/template-mail) — `send-email` is the reference example for `needsApproval`
 - [**Audit Log**](/docs/audit-log) — the automatic who-changed-what trail
 - [**Security**](/docs/security) — `accessFilter`/`assertAccess` and the extension iframe trust boundary
 - [**Sharing**](/docs/sharing) — the framework sharing system these helpers back

package/docs/content/actions-agent-tools.mdx

@@ -0,0 +1,101 @@
+---
+title: "Production Agent Access"
+description: "Control which framework tools and code-execution capabilities a deployed production agent has, through frameworkTools and codeExecution."
+---
+
+# Production Agent Access
+
+## Production Agent Tools {#production-agent-tools}
+
+Production agents get the app's registered actions plus the framework's own
+tools. `frameworkTools` selects which of those framework tools this app exposes.
+Every group defaults to today's behavior, so omitting the option changes
+nothing:
+
+```ts filename="server/plugins/agent-chat.ts"
+export default createAgentChatPlugin({
+  frameworkTools: {
+    database: "read", // "write" | "read" | "off", default "read"
+    extensions: true, // default false
+    sharing: false, // this app has no share surface
+    review: false,
+  },
+});
+```
+
+```ts filename="server/plugins/core-routes.ts"
+export default createCoreRoutesPlugin({
+  extensionTools: true,
+});
+```
+
+`database` and `extensions` accept the values the old top-level flags did:
+
+- `database: "read"`. Default. Registers only `db-schema` and `db-query`.
+  Agents inspect data with SQL but must use typed app actions for writes.
+- `database: "write"` or `true`. Additionally registers `db-exec` and
+  `db-patch` for deliberate raw SQL maintenance. Writes are scoped to the
+  current user/org and schema changes are blocked.
+- `database: "off"` or `false`. Removes raw database tools from the
+  agent surface so the app's actions are the only data access path.
+- `extensions: true`. Opts the app into framework extension-management
+  actions and prompt guidance (`create-extension`, `update-extension`, etc.).
+  Set `extensionTools: true` on the core-routes plugin as well to allow
+  authenticated REST creation. Extensions are disabled by default.
+
+The remaining groups are booleans, all on by default: `sharing`, `review`,
+`history`, `featureFlags`, `localization`, `audit`, `contextXray`,
+`userProfile`, `automation`, `docs`, `resources`, `web`, `workspaceApps`,
+`chat`, and `email`. Use `frameworkTools: "minimal"` to turn every group off at
+once for a voice-first or single-purpose app, or
+`frameworkTools: { preset: "minimal", resources: true }` to keep just one. An
+explicit group key always wins over the preset.
+
+Switching a group off removes it from the **agent** surfaces only: interactive
+chat, MCP, A2A, and background runs. The matching HTTP action routes stay
+mounted, because the UI reaches them through client hooks. Disabling `sharing`
+must not 404 a share dialog that is still on screen. Weigh that parity cost
+before using it: the framework's contract is that anything the UI can do the
+agent can do, so `sharing: false` alongside a visible share button is a
+deliberate break, and only makes sense when the app has no such surface at all.
+
+Framework tools are no longer promoted into the first model request by default,
+independent of this option. They stay in the searchable registry and load
+through `tool-search`, or immediately if the app names them in
+`initialToolNames`.
+
+<Callout tone="warning">
+  The top-level `databaseTools` and `extensionTools` options are deprecated in
+  favor of `frameworkTools.database` and `frameworkTools.extensions`. They are
+  still honored, but setting a top-level flag and its `frameworkTools`
+  equivalent to conflicting values throws at plugin startup rather than booting
+  with a tool surface nobody chose.
+</Callout>
+
+## Production Code Execution {#production-code-execution}
+
+By default, production agents run without code-execution tools. They can call app actions, database tools, MCP tools, browser/session tools, and other registered framework tools, but they do not get shell or filesystem access.
+
+Node-compatible deployments can opt into production code execution through the agent chat plugin or an environment override:
+
+```ts filename="server/plugins/agent-chat.ts"
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+The available modes are:
+
+- `off`. The default. No code-execution tools are registered in production.
+- `sandboxed`. Registers `run-code`, an isolated Node.js JavaScript runner with a scrubbed environment, a fresh temp directory, output/time limits, and a localhost bridge to allowlisted registered tools such as `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request`, and the Resources-backed workspace file bridge used by `workspaceRead` / `workspaceWrite`.
+- `trusted`. Registers `run-code` plus the full coding tool registry (`bash`, `read`, `edit`, `write`). Use this only for single-tenant or operator-controlled deployments where full shell access to the host is intentional.
+
+Set `AGENT_PROD_CODE_EXECUTION=sandboxed` or `AGENT_PROD_CODE_EXECUTION=trusted` to override the plugin option for a specific deployment without a code change. `AGENT_PROD_CODE_EXECUTION=off` forces code execution off even when the plugin option enables it.
+
+The `run-code` sandbox is process-level isolation, not an OS container. It strips app secrets from the child process environment and uses the Node permission model when available, but outbound network is not blocked by Node itself. Authenticated calls should go through the bridge helpers the tool exposes.
+
+## What's next
+
+- [**Actions: Access & Authorization**](/docs/actions-access-control) — the per-action access-control axes this page's tool-level gating complements
+- [**Updating UI in Production**](/docs/updating-ui-in-production) — what a deployed agent can and can't edit with code execution left off
+- [**Deployment: Environment Variables**](/docs/deployment-environment-variables) — `AGENT_PROD_CODE_EXECUTION` and other production env vars

package/docs/content/actions-defining.mdx

@@ -29,7 +29,7 @@ Every action starts with a call to `defineAction()`. It bundles a description fo
     {
       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. `getDb()` and `schema` come from your app's `server/db/index.ts`. See [Database](/docs/database).",
+      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/server-database).",
     },
   ]}
 />
@@ -271,5 +271,5 @@ The repo includes an advisory helper, `node scripts/audit-template-actions.mjs [
 - [**Access & Authorization**](/docs/actions-access-control) — `agentTool`, `toolCallable`, `authorize`, and `ctx` scoping
 - [**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
-- [**Database**](/docs/database) — `getDb()`/`schema` used inside `run()`
+- [**Database**](/docs/server-database) — `getDb()`/`schema` used inside `run()`
 - [**Data & Sync**](/docs/client-data) — calling this action from the UI

package/docs/content/audit-log.mdx

@@ -183,7 +183,7 @@ Configure via environment:
 ## What's next
 
 - [**Actions**](/docs/actions-overview) — the `defineAction` seam where capture happens
-- [**Human-in-the-Loop Approvals**](/docs/human-approval) — gated actions, recorded as `denied`
+- [**Human-in-the-Loop Approvals**](/docs/actions-access-control#needs-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")
 - [**Toolkit piece: History Kit**](/docs/toolkit-history) — the version-history timeline and undo/redo UI built on this trail

package/docs/content/authentication.mdx

@@ -456,7 +456,7 @@ function SignInCta() {
 
 Normal app pages use one impersonal, public-cacheable SSR shell for every visitor. `AppProviders` checks the session on the client; on a private path such as `/dashboard`, it redirects an anonymous visitor to `/sign-in?return=%2Fdashboard` before mounting private app UI. After sign-in, the visitor returns to `/dashboard`. Pass `isPublicPath` for public/SEO routes, or `sessionBypass` for a surface that authenticates through another scoped mechanism such as an MCP embed token.
 
-How long that shell is cached is a deployment-wide setting — see [SSR Caching](/docs/deployment#ssr-caching) for `AGENT_NATIVE_SSR_CACHE`. Shortening or disabling the cache changes duration only; SSR still renders the anonymous branch with cookies stripped.
+How long that shell is cached is a deployment-wide setting — see [SSR Caching](/docs/ssr-caching) for `AGENT_NATIVE_SSR_CACHE`. Shortening or disabling the cache changes duration only; SSR still renders the anonymous branch with cookies stripped.
 
 ### Behind the scenes: Google OAuth
 

package/docs/content/cloudflare.mdx

@@ -0,0 +1,43 @@
+---
+title: "Cloudflare"
+description: "Deploy an agent-native app to Cloudflare Pages or Cloudflare Workers with the matching Nitro preset."
+---
+
+# Cloudflare
+
+## Cloudflare Pages {#cloudflare-pages}
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "cloudflare_pages" } })],
+});
+```
+
+## Cloudflare Workers {#cloudflare-workers}
+
+Use Nitro's native module output for a Cloudflare Worker. This keeps SSR
+enabled and emits the Worker entry point plus static assets under
+`.output/server` and `.output/public`:
+
+```ts filename="vite.config.ts"
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "cloudflare_module" } })],
+});
+```
+
+Build and deploy the generated Worker with Wrangler:
+
+```bash
+npx @agent-native/core@latest build
+npx wrangler deploy --config .output/server/wrangler.json
+```
+
+You can also select the preset explicitly with
+`NITRO_PRESET=cloudflare_module`. Configure a durable external SQL database
+before deploying. A Worker filesystem is not a persistent application store.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Workspace Deployment**](/docs/workspace-deployment) — Cloudflare Pages is the default preset for the unified `deploy` command
+- [**Node.js & Docker**](/docs/node-docker), [**Vercel**](/docs/vercel), [**Netlify**](/docs/netlify), and [**Other Platforms**](/docs/other-platforms) — the other Nitro presets

package/docs/content/creating-templates.mdx

@@ -238,7 +238,7 @@ export default runMigrations(
 );
 ```
 
-Use the [Database](/docs/database) and [Security](/docs/security) docs before adding schemas that hold user or org data.
+Use the [Database](/docs/server-database) and [Security](/docs/security) docs before adding schemas that hold user or org data.
 
 ## Define Operations As Actions {#actions}
 

package/docs/content/deploy-an-app.mdx

@@ -0,0 +1,109 @@
+---
+title: "Deploy an app"
+description: "Build and deploy one Agent-Native app to Node.js, Vercel, Netlify, Cloudflare, AWS, or Deno."
+search: "deploy app standalone build Nitro preset Node.js Vercel Netlify Cloudflare AWS Deno"
+---
+
+# Deploy an app
+
+Use this path for a standalone app, or for one app from a workspace that you
+want to run on its own domain. For several apps on one origin, use [Deploy a
+workspace](/docs/workspace-deployment) instead.
+
+<Steps>
+
+### Create or open the app
+
+Create a standalone Chat app, or work from an existing app:
+
+```bash
+npx @agent-native/core@latest create my-app --standalone --template chat
+cd my-app
+pnpm install
+```
+
+### Choose a deployment target
+
+The default target is Node.js. For another host, set the Nitro preset in
+`vite.config.ts` or set `NITRO_PRESET` at build time.
+
+```ts filename="vite.config.ts"
+import { agentNative } from "@agent-native/core/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [agentNative({ nitro: { preset: "vercel" } })],
+});
+```
+
+See the target page for the provider command and runtime details:
+
+- [**Node.js & Docker**](/docs/node-docker)
+- [**Vercel**](/docs/vercel)
+- [**Netlify**](/docs/netlify)
+- [**Cloudflare**](/docs/cloudflare)
+- [**AWS Lambda and Deno Deploy**](/docs/other-platforms)
+
+### Build the app
+
+Build the client and server output:
+
+```bash
+npx @agent-native/core@latest build
+```
+
+The default Node.js output runs with:
+
+```bash
+node .output/server/index.mjs
+```
+
+For a local production-shaped check with Postgres and Docker, follow the
+[Node.js & Docker quickstart](/docs/node-docker#self-host-quickstart).
+
+### Configure the deployment
+
+Set `DATABASE_URL` to a persistent SQL database before the first production
+deploy. A standalone app using framework auth also needs a stable
+`BETTER_AUTH_SECRET`. Add the provider and integration variables your app uses.
+
+Use the [deployment environment reference](/docs/deployment-environment-variables)
+for production secrets, auth, webhooks, workspace inheritance, and runtime
+flags.
+
+### Deploy and verify
+
+Publish the output using your provider's normal deploy command. Then verify the
+public URL, sign-in flow, database reads and writes, and any OAuth callbacks or
+webhooks your app uses.
+
+</Steps>
+
+<Callout tone="warning">
+
+Do not use the local SQLite file as production storage. Do not reuse the sample
+auth secret from a local Docker setup. Keep secrets in the deployment
+provider's environment or managed secret store.
+
+</Callout>
+
+## Deploying one app from a workspace
+
+Each workspace app is independently deployable. Run the build from the app
+directory:
+
+```bash
+cd apps/<name>
+npx @agent-native/core@latest build
+```
+
+Give that app its own public origin and configure its database and auth URL for
+that origin. If the apps should share one origin, shared login, and same-origin
+app to app communication, use [Workspace Deployment](/docs/workspace-deployment).
+
+## What's next
+
+- [**Deployment**](/docs/deployment) - the database prerequisite and target overview
+- [**Workspace Deployment**](/docs/workspace-deployment) - one origin for many apps
+- [**Database**](/docs/server-database#production) - production SQL adapters and connections
+- [**Security**](/docs/security) - the production security checklist

package/docs/content/deployment-environment-variables.mdx

@@ -0,0 +1,101 @@
+---
+title: "Deployment: Environment Variables"
+description: "The production environment variable reference for build, runtime, secrets, and hosting behavior."
+---
+
+# Deployment: Environment Variables
+
+For the repository-wide reference, including template, provider, local, and CI
+variables, see [Environment Variables](/docs/environment-variables). The tables
+below remain the authoritative deployment guide for production values and
+hosting behavior.
+
+## Build / Runtime {#env-runtime}
+
+| Variable                                    | Description                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                                      | Server port (Node.js only)                                                                                                                                                                                                                                                                                                                                              |
+| `NITRO_PRESET`                              | Override build preset at build time                                                                                                                                                                                                                                                                                                                                     |
+| `APP_BASE_PATH`                             | Mount the app under a prefix (e.g. `/mail`). Set automatically by `npx @agent-native/core@latest deploy`. Leave unset for standalone.                                                                                                                                                                                                                                   |
+| `APP_URL`                                   | Optional canonical public origin. Checked ahead of `BETTER_AUTH_URL` when resolving the A2A JWT audience, the OAuth public origin, self-dispatch webhook targets, and generated resource links. Set it explicitly on preview/staging deploys where the request host is unreliable.                                                                                      |
+| `AGENT_PROD_CODE_EXECUTION`                 | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](/docs/actions-agent-tools#production-code-execution).                                                                                                                                                                                              |
+| `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide SSR shell cache policy: unset/`on` keeps the default hard-cache, `off` sends `no-store`, or a duration such as `30s` / `5m` sets a shorter freshness. See [SSR Caching](/docs/ssr-caching).                                                                                                                                                             |
+| `AGENT_NATIVE_ENABLE_KEEP_WARM`             | Opt into the Netlify keep-warm scheduled function. Unset by default. See [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                                                                                                                                                                                                  |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Compatibility kill switch for the Netlify keep-warm scheduled function. See [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                                                                                                                                                                                               |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Override the keep-warm cadence with a 5-field cron expression (default `* * * * *` when enabled). An unparseable value fails the build. See [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                                                                                                                               |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drop only the background-function warm and keep the server warm. See [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                                                                                                                                                                                                      |
+| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`     | Turn off the in-process backstop sweep timers (automation redispatch, agent-teams reconciliation, sandbox-execution recovery). On serverless these run per warm container, so their query rate scales with instance count. Set it **only** where a durable scheduler already drives the same recovery, or queued work will not be retried.                              |
+| `AGENT_NATIVE_SKIP_ENSURE_TABLES`           | Skip on-demand schema DDL on deployments the automatic serverless skip does not cover. Requires that your schema is already migrated. See [On-demand schema DDL](/docs/deployment#skip-ensure-tables).                                                                                                                                                                  |
+| `AGENT_NATIVE_BUILDER_RELAY_SECRET`         | Dedicated 32+ char shared HMAC secret for preview-safe Builder authorization relay. Set the same value on the approved corporate callback deployment and preview deployments only when authorization must land in an isolated preview database.                                                                                                                         |
+| `AGENT_NATIVE_BUILDER_RELAY_TARGET_ORIGINS` | Corporate callback-only, comma-separated allowlist of exact trusted preview origins (for example, `https://0123456789abcdef01234567--content.netlify.app`). Set it only on the corporate callback deployment. Netlify origins must use an immutable, deploy-specific 24-hex permalink. Mutable `deploy-preview-*` aliases, wildcards, and domain suffixes are rejected. |
+
+Database connection variables (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, per-app `<APP_NAME>_DATABASE_URL`) live in [Database](/docs/server-database#production).
+
+## Schema setup and cold starts {#skip-ensure-tables}
+
+On the first database touch, each data store checks whether its tables, columns,
+and indexes exist, then creates only what is missing. Managed serverless
+deployments skip this boot-time check in production. Other deployments can make
+the same tradeoff explicit with `AGENT_NATIVE_SKIP_ENSURE_TABLES=1` after the
+schema has been migrated.
+
+Use the flag only when your deployment owns schema migrations. If a required
+table is missing, the first real query fails loudly instead of repairing the
+schema at runtime.
+
+The check is batched into one introspection pass per database. This keeps the
+default safe for long-lived Node servers while limiting cold-start work on
+platforms that do not skip it automatically.
+
+## Production-sensitive configuration {#env-required-prod}
+
+These settings cover production-sensitive behavior. A standalone app using the
+framework auth needs a stable `BETTER_AUTH_SECRET` and a persistent database.
+The public auth URL is inferred from the request, known template, or hosting
+platform when it is unset. Workspace and A2A settings are conditional on those
+features. Missing values either fail-closed or fall back to weaker behavior
+with a loud warning.
+
+| Variable                                    | Description                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`                        | 32+ char random string. Signs session cookies and is the fallback for `OAUTH_STATE_SECRET` and app-local encrypted values. It is also a legacy read candidate for existing shared vault ciphertext. Hard-required: the framework throws on startup if missing in production.                                                                       |
+| `BETTER_AUTH_URL`                           | Optional public origin override for this app (e.g. `https://mail.example.com`). The framework infers it from request, known-template, and hosting-platform context when unset.                                                                                                                                                                     |
+| `ANTHROPIC_API_KEY`                         | API key for the embedded production agent. **In multi-tenant deploys**, the framework refuses to fall back to this when the user has no per-user key. Bring-your-own-key is required. Single-tenant self-hosted installs use it as a global key.                                                                                                   |
+| `OAUTH_STATE_SECRET`                        | Dedicated HMAC key for OAuth state envelopes (Google, Atlassian, Zoom). Falls back to `BETTER_AUTH_SECRET` when unset, but a dedicated value is recommended so rotating one doesn't invalidate the other. Generate via `openssl rand -hex 32`.                                                                                                     |
+| `A2A_SECRET`                                | Shared HMAC for inter-app A2A JSON-RPC and signed background handoffs. Required for hosted workspace deploys and A2A features. Without it, those endpoints fail closed in production. When no dedicated workspace vault key is set, shared vault ciphertext uses a purpose-derived key from this value, so rotating it also rotates the vault key. |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Preferred stable AES-256-GCM key for the shared encrypted-at-rest secrets vault. Set the same value in every app that reads the vault. It is separate from app-local OAuth/credential encryption, so A2A trust can rotate without stranding vault rows. Existing A2A-, Better Auth-, and app-key ciphertext is migrated on successful reads.       |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Optional previous workspace vault key used only during a rotation window. Deploy it alongside the new `WORKSPACE_SECRETS_ENCRYPTION_KEY`, let successful reads re-encrypt rows, then remove it after migration.                                                                                                                                    |
+| `SECRETS_ENCRYPTION_KEY`                    | Legacy combined key for app-local encryption and the shared vault. It remains supported, but new multi-app deployments should use `WORKSPACE_SECRETS_ENCRYPTION_KEY` for the shared vault so changing workspace encryption does not change app-local OAuth ciphertext.                                                                             |
+
+## Auth & Identity {#env-auth}
+
+OAuth provider credentials (Google, GitHub), static MCP bearer fallbacks (`ACCESS_TOKEN` / `ACCESS_TOKENS`), and email-verification toggles are documented in [Authentication](/docs/authentication). Set them there per the auth mode you choose.
+
+## Inbound Webhooks {#env-webhooks}
+
+Each messaging integration requires its own signing secret in production (handlers fail-closed on forged requests when the secret is missing). The per-integration variables are listed in [Messaging](/docs/messaging) and [Security](/docs/security). For local development only, `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` opts back into "warn and accept". Never set it in prod.
+
+## Security Configuration (Opt-in) {#security-config}
+
+Defaults are strict. A handful of opt-in flags relax behavior (debug stack traces, unverified webhooks, workspace-scoped key fallback, the MCP hub multi-org switch, runtime env-var writes). They are documented with their security trade-offs in [Security](/docs/security). Don't set them unless you specifically want the relaxed path.
+
+## Workspace .env Inheritance {#env-inheritance}
+
+Inside a workspace, the root `.env` is loaded into every app automatically, so shared keys like `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET`, and `OAUTH_STATE_SECRET` only need to be set once. Per-app `apps/<name>/.env` wins on conflict.
+
+## Generating Strong Secrets {#env-generate-secrets}
+
+For any secret marked "32+ char random" (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `WORKSPACE_SECRETS_ENCRYPTION_KEY`, `SECRETS_ENCRYPTION_KEY`, `AGENT_NATIVE_BUILDER_RELAY_SECRET`), generate fresh values with:
+
+```bash
+openssl rand -hex 32
+```
+
+Rotate signing/session keys by replacing the env var on every instance and redeploying. Sessions and OAuth state envelopes signed under the old key become invalid, so users may need to sign in again. Rotate `WORKSPACE_SECRETS_ENCRYPTION_KEY` with the `..._PREVIOUS` window described above so encrypted vault rows remain readable while they migrate.
+
+## What's next
+
+- [**Deployment**](/docs/deployment) — pick a persistent database and a preset before your first production deploy
+- [**Environment Variables**](/docs/environment-variables) — the repository-wide reference, including template, provider, local, and CI variables
+- [**Security**](/docs/security) — the production checklist and opt-in flags referenced throughout this page
+- [**Authentication**](/docs/authentication) — OAuth credentials and env vars for the auth mode you choose