@agent-native/core 0.137.8 → 0.138.0

package/docs/AGENTS.md

@@ -21,6 +21,9 @@ version installed in the app.
 From a generated app root:
 
 ```bash
+pnpm action framework-search --pattern "defineAction"
+pnpm action framework-search --pattern "templates/*/actions/*.ts" --mode glob --scope source
+pnpm action framework-search --pattern "Agent(?:Panel|Sidebar)" --mode regex --scope source
 pnpm action docs-search --list
 pnpm action docs-search --query "actions"
 pnpm action docs-search --slug actions
@@ -30,8 +33,10 @@ pnpm action source-search --path templates/plan/AGENTS.md
 pnpm action source-search --path templates/chat/actions/hello.ts
 ```
 
-The built-in app agent also has read-only `docs-search` and `source-search`
-tools with the same options.
+The built-in app agent also has a read-only `framework-search` tool for one
+bounded search across docs and readable Core, Toolkit, and first-party
+template source. Use `docs-search` and `source-search` for focused reads after
+it identifies the relevant page or file.
 
 If the action runner is unavailable, search the package files directly:
 

package/docs/SKILL.md

@@ -14,14 +14,16 @@ examples or template patterns matter, inspect the packaged source corpus too.
 ## How
 
 1. Start from the generated app root.
-2. Search with `pnpm action docs-search --query "<feature>"`.
-3. Read a specific page with `pnpm action docs-search --slug <slug>`.
-4. Search source examples with `pnpm action source-search --query "<pattern>"`
+2. Start cross-corpus discovery with `pnpm action framework-search --pattern "<feature>"`.
+3. Use `--scope docs` or `--scope source` and `--mode glob`, `--mode sql-like`,
+   or `--mode regex` when the question needs a narrower pattern.
+4. Read a specific page with `pnpm action docs-search --slug <slug>`.
+5. Search source examples with `pnpm action source-search --query "<pattern>"`
    or read a file with `pnpm action source-search --path <path>`.
-5. If the action runner is unavailable, search
+6. If the action runner is unavailable, search
    `node_modules/@agent-native/core/docs` directly with `rg`.
    Search `node_modules/@agent-native/core/corpus` for source examples.
-6. For app-specific rules, also read the app's own `AGENTS.md` and any relevant
+7. For app-specific rules, also read the app's own `AGENTS.md` and any relevant
    `.agents/skills/<name>/SKILL.md`.
 
 ## Useful Slugs

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

@@ -0,0 +1,165 @@
+---
+title: "Agent-Native app configuration"
+description: "Configure public app defaults with agent-native.json or a typed agent-native.config.ts file."
+search: "agent-native.json agent-native.config.ts onboarding first-run Builder BYOK integrations configuration"
+---
+
+# Agent-Native app configuration
+
+Use app configuration for committed, non-secret defaults that should travel
+with the app. Use environment variables for deployment values, credentials,
+and local machine controls. The framework reads `agent-native.json` from the
+app root when the `agentNative()` Vite preset runs.
+
+The file is an additive app manifest. Existing feature-owned sections such as
+`doctor`, `apps`, and local-file declarations can stay in the same file; the
+onboarding reader only consumes the `version` and `onboarding` fields described
+here.
+
+## The onboarding contract
+
+The shared first-run surface has three supported modes:
+
+| Mode                       | Local or hosted result                                                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `off`                      | No shared first-run surface. This is the default for ordinary apps.                                                                                          |
+| `connect`                  | Show Connect Builder or Add your own keys, then go straight to the app. The generic integrations catalog is omitted.                                         |
+| `connect-and-integrations` | Show Connect Builder or Add your own keys, followed by the generic integrations catalog. Use this for a hosted app that should expose its integration setup. |
+
+A turn-into-app result normally commits a mode map so `pnpm dev` is useful
+immediately while a production build has the hosted setup path:
+
+```json filename="agent-native.json"
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "connect",
+      "production": "connect-and-integrations"
+    }
+  }
+}
+```
+
+An ordinary app can omit `onboarding` or make the default explicit:
+
+```json filename="agent-native.json"
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": "off"
+  }
+}
+```
+
+First-party templates use `off` while running locally and
+`connect-and-integrations` for a production build. The
+`/turn-into-app` skill deliberately changes only the local value to `connect`
+so a newly generated workflow is immediately testable without putting the
+hosted integration catalog in front of the user.
+
+The environment map uses the exact Vite `mode` first, then falls back to
+`development` for `vite dev`, `production` for `vite build`, and finally
+`default` or `off`. This lets a project add a named mode such as `staging`
+without making the app depend on a new environment variable.
+
+## Typed dynamic configuration
+
+When a static JSON map is not enough, add `agent-native.config.ts`. It returns
+the same serializable shape and can use the Vite command and mode:
+
+```ts filename="agent-native.config.ts"
+import { defineAgentNativeConfig } from "@agent-native/core/config";
+
+export default defineAgentNativeConfig(({ command, mode }) => ({
+  version: 1,
+  onboarding: {
+    firstRun:
+      command === "serve" || mode === "preview"
+        ? "connect"
+        : "connect-and-integrations",
+  },
+}));
+```
+
+The preset loads `agent-native.config.ts` or `agent-native.config.mts`
+automatically on the supported Node runtime. The TypeScript file takes
+precedence over the JSON app defaults. An explicit `agentNative({
+agentNativeConfig })` option takes precedence over both when an app needs to
+compose configuration in its Vite config.
+
+The resolved config is serialized into the browser bundle. Keep it public:
+never put API keys, tokens, database URLs, auth secrets, `AUTH_DISABLED`, or
+other credentials in either config file.
+
+## Precedence and compatibility
+
+For a Vite app, the effective value is resolved in this order:
+
+1. An explicit `agentNativeConfig` passed to `agentNative()` or `defineConfig()`.
+2. The optional typed `agent-native.config.ts` or `.mts` file.
+3. `agent-native.json`.
+4. Framework defaults, which are `off` for first-run onboarding.
+5. The legacy `VITE_AGENT_NATIVE_FIRST_RUN_ONBOARDING` flags can still
+   override the resolved public config for older apps, but new apps should not
+   add them. They are public browser flags and remain documented only for
+   migration.
+
+The development Connect Builder card explains the deployment-level
+`ANTHROPIC_API_KEY` and `OPENAI_API_KEY` fallback and links to the
+[environment-variable reference](/docs/environment-variables). A key in the
+deployment environment is not a substitute for user- or organization-scoped
+credentials in a hosted multi-user app. See [Onboarding & API Keys](/docs/onboarding)
+and [Security](/docs/security) for the credential boundary.
+
+## What belongs in config versus `.env`
+
+Good config candidates are public defaults that describe the product's shape:
+
+- first-run onboarding mode and other setup presentation defaults;
+- the app's default MCP catalog visibility or preset filters, once expressed
+  through the shared config contract;
+- route warmup, public design tokens, and other build-time UX choices already
+  passed to the `agentNative()` Vite preset;
+- non-secret app identity and default navigation metadata, if the framework
+  later gives those values a shared runtime consumer.
+
+Keep these in environment variables or the secret store:
+
+- API keys, OAuth secrets, signing keys, database URLs, and provider tokens;
+- `APP_URL`, `APP_BASE_PATH`, deployment preset, port, and host-specific
+  values that change between deploy targets;
+- `AUTH_DISABLED`, test switches, CI controls, and local machine paths;
+- runtime flags whose safe value depends on the hosting environment rather than
+  the app's product contract.
+
+The complete inventory is [Environment Variables](/docs/environment-variables).
+That reference is intentionally broader than the config surface and is the
+source to consult before adding a new environment variable.
+
+## Environment audit and next candidates
+
+The current config surface intentionally starts with onboarding, where a
+committed app default is more useful than a deployment flag. The next good
+public candidates are:
+
+| Candidate                                 | Why it belongs in app config                                               | Status                                                                 |
+| ----------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| MCP catalog visibility and preset filters | Describes which setup choices the app offers, not a secret or host policy. | A good next addition; currently keep using the `agentNative()` option. |
+| Route warmup strategy                     | A product-level loading preference that can be reviewed with the app.      | A good next addition; currently keep using the `agentNative()` option. |
+| Default navigation or app identity        | Makes generated apps open on the right domain route and name.              | Add only after a shared runtime consumer exists.                       |
+| Design-system theme                       | Can vary intentionally per app, but is a larger structured object.         | Keep in `vite.config.ts` or app code until the schema is stable.       |
+
+Do not move `DATABASE_URL`, `APP_URL`, `PORT`, `NITRO_PRESET`, auth switches,
+provider keys, OAuth secrets, signing keys, telemetry endpoints, or security
+flags into this file. They vary by deploy target, affect trust boundaries, or
+must remain outside the browser bundle. This split keeps config useful for
+scaffolders without turning it into a second environment-variable system.
+
+## Why there are two formats
+
+`agent-native.json` is portable, inspectable, and easy for scaffolders and
+other tools to write. `agent-native.config.ts` follows the typed-config pattern
+used by frameworks such as Next.js while keeping the browser contract
+serializable. Prefer JSON for a fixed app default and TypeScript when the
+default genuinely depends on the Vite command or mode.

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

@@ -97,7 +97,7 @@ directly without adopting Toolkit or a template.
 | [Collaboration](/docs/toolkit-collaboration)             | Realtime editing, presence, live cursors, recent-edit highlights, collaborative undo.                                            |
 | [Settings](/docs/toolkit-settings)                       | Standard settings pages and tabs so app settings and agent/provider settings live in one predictable place.                      |
 | [Org & Team](/docs/toolkit-org-team)                     | Team pages, org switching, invites, org domains, roles, and app switching.                                                       |
-| [Setup & Connections](/docs/toolkit-setup-connections)   | Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect.                                       |
+| [Setup & Connections](/docs/toolkit-setup-connections)   | Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect (free tier available).                 |
 | [Command & Navigation](/docs/toolkit-command-navigation) | Command menu, deep links, standard app routes, sidebar and shell patterns.                                                       |
 | [Resources](/docs/toolkit-resources)                     | Resource trees, editors, file picker/search, attachments, and local file mode.                                                   |
 | [Agent UX](/docs/toolkit-agent-ux)                       | Composer, model picker, context chips, approvals, run recovery, and the runs tray.                                               |

package/docs/content/deployment.mdx

@@ -517,6 +517,11 @@ Three things to keep in mind:
 
 ## Environment Variables {#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                                                                                                                                                                                                                                                                                                                                                             |
@@ -640,11 +645,11 @@ In a standard production deployment with [production code execution](#production
 
 ### Builder.io: Visual Editing in Production {#builderio}
 
-[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) is a separate managed code-capable workflow where an agent can modify your app's UI in production. Connect your repo to Builder.io and prompt for UI changes directly — no redeploy needed.
+[Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=deployment) is a separate managed code-capable workflow where an agent can modify your app's UI in production. Connect your repo to Builder.io (free tier available) and prompt for UI changes directly — no redeploy needed.
 
 **How it works:**
 
-1. Connect your agent-native repo to Builder.io
+1. Connect your agent-native repo to Builder.io (free tier available)
 2. Builder.io provides a cloud frame with the agent, visual editing, and real-time collaboration
 3. Prompt the agent to make UI changes — it edits your components, routes, and styles live
 4. Changes are committed back to your repo

package/docs/content/doctor.mdx

@@ -1,18 +1,20 @@
 ---
 title: "Doctor (Code Checks)"
-description: "agent-native doctor scans a generated app's source for the framework's security and architecture invariants — the same code-safety guards this monorepo enforces on itself, ported to run against a single app root."
+description: "agent-native doctor scans generated app and workspace source for the framework's security and architecture invariants — the portable code-safety guards shared outside the monorepo CI suite."
 ---
 
 # Doctor (Code Checks)
 
-Generated apps contain source code that can be changed through the repository's
+Generated apps and workspaces contain source code that can be changed through the repository's
 development workflow, including by an agent frame intentionally granted
 workspace and write tooling. `agent-native doctor` is the automated check for that: it
 scans app source for the framework's security-critical code-safety invariants —
 the same class of check that lives in this framework's own CI as
-`scripts/guard-*.mjs` — ported to run against a single generated app instead of
-the framework's multi-template monorepo layout. It's read-only: doctor never
-edits your code, it only reports.
+`scripts/guard-*.mjs` — ported to run against generated projects instead of
+the framework's multi-template monorepo layout. A workspace-root run scans each
+`apps/<name>` project and the workspace's `packages/shared` package when present,
+prefixing findings with the project path. It's read-only: doctor never edits
+your code, it only reports.
 
 ## Quick start {#quick-start}
 
@@ -20,12 +22,17 @@ edits your code, it only reports.
 agent-native doctor
 ```
 
-Every scaffolded app also gets a `pnpm doctor` script that runs the same command:
+Every scaffolded app and workspace gets the collision-free
+`pnpm agent-native:doctor` command. When a template does not already define its
+own `doctor` script, the CLI also adds the shorter `pnpm doctor` alias:
 
 ```bash
 pnpm doctor
 ```
 
+The full framework-repository `pnpm guards` suite remains a monorepo check;
+generated projects use this version-matched portable Doctor surface instead.
+
 A clean run:
 
 ```
@@ -83,7 +90,7 @@ installed.
 agent-native doctor                        Scan app source for security-critical guard violations
 agent-native doctor --json                 Machine-readable report: { ok, findings, guardsRun, strict }
 agent-native doctor --only <guard,guard>   Run only the named guard(s)
-agent-native doctor --strict               Escalate findings to a hard failure when used by `agent-native build --strict`
+agent-native doctor --strict               Keep the build gate explicit when invoked by `agent-native build`
 agent-native doctor --cwd <dir>            Run against a project root other than the current directory
 agent-native doctor --fix                  Not implemented in this version
 agent-native doctor --help                 Show this help
@@ -97,16 +104,16 @@ Exit codes: **`0`** clean, **`1`** findings present, **`2`** usage or execution
 
 ## The build hook {#build-hook}
 
-`agent-native build` always runs doctor as a pre-step before the real build. It's **warn-only by default**: findings print to stderr prefixed `[doctor]`, and the build continues. It only turns findings into a hard failure — `process.exit(1)` before the build runs — when:
+`agent-native build` always runs doctor as a pre-step before the real build. It is a **hard gate by default**: findings print to stderr prefixed `[doctor]`, and the build exits before publishing. A project using `agent-native build` can explicitly opt out with `failOnBuild: false`, but `--strict` always keeps the gate enabled. Community templates that use another build command receive a strict `prebuild` hook instead:
 
-- `agent-native build --strict` was passed, or
-- `agent-native.json` sets `{ "doctor": { "failOnBuild": true } }`.
+- `agent-native.json` sets `{ "doctor": { "failOnBuild": false } }` only when that exception has been reviewed.
 
-If the doctor pre-step itself throws — an unreadable file, a bug in a guard — the build step catches it, logs a warning, and continues. A doctor bug never blocks a deploy on its own.
+If the doctor pre-step itself throws — for example, because a source file is unreadable or a guard crashes — the build is blocked. A partial security scan must never look like a clean result.
 
 ## Per-app configuration {#config}
 
-`agent-native.json`'s optional `"doctor"` key. Every field is optional with an empty/false default, so a fresh app runs every v1 guard with zero config:
+`agent-native.json`'s optional `"doctor"` key. A fresh app runs every v1 guard
+with zero config and fails builds on findings by default:
 
 ```json
 {
@@ -124,7 +131,7 @@ If the doctor pre-step itself throws — an unreadable file, a bug in a guard
 | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `disabledGuards`        | `string[]`              | Guard names (from the table above) to skip — excluded from the default run and from the build hook. An explicit `--only` list overrides this and runs even a disabled guard.                                                               |
 | `dbToolScopingDenylist` | `Record<table, reason>` | Bare table name (the SQL name, not template-prefixed) → reviewer-readable reason. Used only by `db-tool-scoping`. A denylist entry with no matching table in `server/db/schema.ts` itself becomes a finding — "stale … entry — remove it." |
-| `failOnBuild`           | `boolean`               | See [The build hook](#build-hook). Default `false`.                                                                                                                                                                                        |
+| `failOnBuild`           | `boolean`               | See [The build hook](#build-hook). Default `true`; set `false` only for a reviewed exception.                                                                                                                                              |
 
 ## Opt-out markers {#opt-out}
 
@@ -174,6 +181,7 @@ The actual `--json` payload also carries a `strict` field reflecting whether `--
     "explicit-collab-access",
     "migration-manifest"
   ],
+  "workspaceApps": ["apps/mail", "apps/tasks"],
   "strict": false
 }
 ```

package/docs/content/environment-variables.mdx

@@ -0,0 +1,158 @@
+---
+title: "Environment Variables"
+description: "Reference for Agent-Native framework, workspace, authentication, and deployment environment variables."
+search: "environment variables env .env DATABASE_URL APP_URL BETTER_AUTH_SECRET Google OAuth workspace app"
+---
+
+# Environment Variables
+
+This page covers the environment variables owned by the Agent-Native framework
+and workspace runtime. It is not a setup inventory of every template or
+deployment system in this repository. Template-only values stay in the
+maintainer inventory; the setup tables below focus on the shared configuration
+most apps need.
+
+For a normal app, start with [Deployment](/docs/deployment#environment-variables)
+and [Authentication](/docs/authentication). Keep user-, organization-, and
+workspace-scoped credentials in the database-backed secret or connection store;
+use environment variables for deploy-level configuration.
+
+For committed, non-secret app defaults such as first-run onboarding, use the
+[Agent-Native app configuration guide](/docs/agent-native-config) instead of
+adding another browser-exposed environment setting. Keep credentials and
+deployment-specific values in the environment or scoped secret store.
+
+## Common application and deployment variables
+
+| Variable                                    | What it controls                                                                                | Supported values or format                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                              | Primary SQL connection. Local development falls back to SQLite when it is unset.                | A provider-specific SQL URL, or unset for local SQLite.                                                        |
+| `DATABASE_AUTH_TOKEN`                       | Separate database token when the database provider requires one.                                | An opaque provider token, or unset when the URL includes authentication.                                       |
+| `APP_URL`                                   | Canonical public origin used for auth, OAuth, A2A, webhooks, and generated links.               | An absolute public `http(s)` origin.                                                                           |
+| `BETTER_AUTH_URL`                           | Public origin used by Better Auth for cookies and callbacks.                                    | An absolute public `http(s)` origin.                                                                           |
+| `APP_BASE_PATH`                             | Mounts an app under a path such as `/mail`.                                                     | Unset for a standalone app, or a slash-prefixed path.                                                          |
+| `PORT`                                      | Local Node/Nitro server port.                                                                   | A decimal TCP port.                                                                                            |
+| `NITRO_PRESET`                              | Build and deployment adapter.                                                                   | A preset supported by the target host, such as `node`, `netlify`, `vercel`, or `cloudflare_pages`.             |
+| `BETTER_AUTH_SECRET`                        | Better Auth session signing and the legacy encryption fallback. Required in production.         | A fresh random value of at least 32 characters.                                                                |
+| `OAUTH_STATE_SECRET`                        | Dedicated signing key for OAuth state envelopes. Falls back to `BETTER_AUTH_SECRET` when unset. | A fresh random value of at least 32 characters.                                                                |
+| `A2A_SECRET`                                | Shared HMAC for trusted cross-app A2A calls and signed handoffs.                                | One shared random value across trusted apps.                                                                   |
+| `SECRETS_ENCRYPTION_KEY`                    | Legacy app-local/shared encryption fallback.                                                    | A stable encryption key; prefer the workspace key for new shared vaults.                                       |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Stable encryption key for a workspace-shared secrets vault.                                     | The same stable key in every app that reads the vault.                                                         |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation.                                                         | The old key only; remove it after migration.                                                                   |
+| `ANTHROPIC_API_KEY`                         | Optional deploy-level fallback for the embedded production agent.                               | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
+| `AUTH_MODE`                                 | Selects the local authentication behavior used by CLI and agent flows.                          | Unset or `local`; this is not a browser login bypass.                                                          |
+| `AUTH_DISABLED`                             | Disables auth for local or preview-only work.                                                   | `true` or `1`; never use on a public production app.                                                           |
+| `AUTH_MAGIC_LINK`                           | Controls the password-first versus magic-link sign-in path.                                     | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
+| `AUTH_SKIP_EMAIL_VERIFICATION`              | Skips signup email verification for local QA or previews.                                       | `1`; never use it to weaken production auth.                                                                   |
+| `ACCESS_TOKEN` / `ACCESS_TOKENS`            | Static bearer fallback for MCP and Connect clients.                                             | One token or a delimited token list; these are not browser auth.                                               |
+| `AGENT_PROD_CODE_EXECUTION`                 | Production code-execution policy.                                                               | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/deployment#production-code-execution). |
+| `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide public SSR shell cache policy.                                                  | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/deployment#ssr-caching).       |
+| `COOKIE_DOMAIN`                             | Shares auth cookies across same-database subdomains when explicitly configured.                 | A cookie domain.                                                                                               |
+| `CORS_ALLOWED_ORIGINS`                      | Cross-origin request allowlist.                                                                 | A comma-separated list of exact origins.                                                                       |
+| `WEBHOOK_BASE_URL`                          | Optional public base URL for self-callback and webhook targets.                                 | An absolute public `http(s)` origin.                                                                           |
+| `APP_NAME`                                  | App identity used by workspace and app-scoped configuration.                                    | A short app name, such as `mail`.                                                                              |
+| `APP_ID` / `APP_TEMPLATE`                   | Optional app identity and generated-template metadata.                                          | App-owned strings.                                                                                             |
+| `NODE_ENV`                                  | Node runtime mode.                                                                              | Normally `development`, `test`, or `production`.                                                               |
+| `CI`                                        | Marks CI-driven test and build behavior.                                                        | A CI-provided truthy value.                                                                                    |
+| `DEBUG`                                     | Enables resolver-specific debug logging.                                                        | A resolver-supported truthy or namespace value.                                                                |
+
+Generate strong secrets with:
+
+```bash
+openssl rand -hex 32
+```
+
+## Google sign-in
+
+Set one complete Google OAuth client pair to show the Google sign-in flow.
+Prefer a low-scope identity-only client for app login, and keep API access in a
+separate connection when a product needs broader Google scopes.
+
+| Variable                       | What it controls                                                                                | Supported values or format                |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `GOOGLE_SIGN_IN_CLIENT_ID`     | Preferred low-scope Google OAuth client ID for app login.                                       | The client ID from Google Cloud Console.  |
+| `GOOGLE_SIGN_IN_CLIENT_SECRET` | Secret for the preferred sign-in client.                                                        | The matching client secret.               |
+| `GOOGLE_CLIENT_ID`             | Backwards-compatible sign-in fallback and provider OAuth client ID for Google API integrations. | The matching Google OAuth client ID.      |
+| `GOOGLE_CLIENT_SECRET`         | Secret for `GOOGLE_CLIENT_ID`.                                                                  | The matching client secret.               |
+| `GOOGLE_AUTH_MODE`             | Chooses the sign-in interaction.                                                                | `auto` (default), `popup`, or `redirect`. |
+
+Register the callback URL in Google Cloud Console as the app's public URL,
+including its base path, followed by
+`/_agent-native/google/callback`. See [Authentication - Google OAuth](/docs/authentication#social-providers).
+
+`GOOGLE_LEGACY_CLIENT_ID` and `GOOGLE_LEGACY_CLIENT_SECRET` are accepted for
+older Google provider connections. `GOOGLE_SERVICE_ACCOUNT_KEY` and
+`GOOGLE_APPLICATION_CREDENTIALS` are server-side service-account options for
+specific Google API integrations; they are not required for browser sign-in.
+
+## Optional AI, search, and email fallbacks
+
+These are deploy-level fallbacks for single-tenant or local use. Hosted,
+multi-user apps should prefer the scoped credential and connection store.
+
+| Variable                       | What it controls                                         | Supported values or format                              |
+| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------- |
+| `OPENAI_API_KEY`               | OpenAI model, realtime voice, or transcription fallback. | An OpenAI API key.                                      |
+| `OPENAI_BASE_URL`              | OpenAI-compatible endpoint used with `OPENAI_API_KEY`.   | An absolute `http(s)` URL without embedded credentials. |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Gemini model fallback for the built-in AI engine.        | A Google AI API key.                                    |
+| `GEMINI_API_KEY`               | Gemini transcription fallback.                           | A Google AI API key.                                    |
+| `OPENROUTER_API_KEY`           | OpenRouter model fallback.                               | An OpenRouter API key.                                  |
+| `GROQ_API_KEY`                 | Groq model or transcription fallback.                    | A Groq API key.                                         |
+| `MISTRAL_API_KEY`              | Mistral model fallback.                                  | A Mistral API key.                                      |
+| `COHERE_API_KEY`               | Cohere model fallback.                                   | A Cohere API key.                                       |
+| `BRAVE_SEARCH_API_KEY`         | Brave web-search fallback.                               | A Brave Search API key.                                 |
+| `TAVILY_API_KEY`               | Tavily web-search fallback.                              | A Tavily API key.                                       |
+| `EXA_API_KEY`                  | Exa web-search fallback.                                 | An Exa API key.                                         |
+| `FIRECRAWL_API_KEY`            | Firecrawl web-search fallback.                           | A Firecrawl API key.                                    |
+| `RESEND_API_KEY`               | Resend transactional email delivery.                     | A Resend API key.                                       |
+| `SENDGRID_API_KEY`             | SendGrid transactional email delivery.                   | A SendGrid API key.                                     |
+| `EMAIL_FROM`                   | Sender address used for transactional email.             | A valid email address or display-name address.          |
+| `EMAIL_AGENT_ADDRESS`          | Inbound address used by email-enabled apps.              | A valid email address.                                  |
+| `EMAIL_INBOUND_WEBHOOK_SECRET` | Verifies inbound email webhook signatures.               | A stable random secret.                                 |
+
+## Per-app values in a workspace
+
+The workspace root `.env` is loaded into every app. An app-local file such as
+`apps/mail/.env` wins when the same key exists in both places, so use the root
+file for shared values and the app file for app-specific values.
+
+Some deploy-level values also support an app-name prefix. Set `APP_NAME`,
+uppercase it, and replace non-alphanumeric characters with `_`:
+
+```bash
+APP_NAME=mail
+MAIL_DATABASE_URL=<MAIL_DATABASE_URL>
+MAIL_DATABASE_AUTH_TOKEN=<MAIL_DATABASE_AUTH_TOKEN>
+MAIL_SECRETS_ENCRYPTION_KEY=<MAIL_SECRETS_ENCRYPTION_KEY>
+```
+
+The prefix form is supported for database URLs/tokens and app-local secret
+encryption. Do not invent a prefix for an arbitrary variable; use
+`apps/<name>/.env` or the shared root `.env` according to the variable's scope.
+
+## Public versus secret values
+
+Variables whose names start with `VITE_` and values read through
+`import.meta.env` can be bundled into browser code. Treat them as public
+configuration. Never put an API key, token, password, or private key in a
+browser-exposed variable.
+
+Advanced integration and host-detection keys stay with their owning feature
+guides and the maintainer inventory rather than appearing as a generic setup
+block here. Use a scoped workspace connection for user or provider credentials,
+and follow the owning app or feature guide when one is actually needed.
+See [Security](/docs/security) for the credential boundary and
+[Deployment](/docs/deployment) for production hosting.
+
+## Keeping the reference complete
+
+The maintainer-only repository inventory remains broader than this public page.
+Run the focused check from the repository root when adding a framework variable:
+
+```bash
+pnpm run guard:env-documentation
+```
+
+The check keeps the exhaustive internal inventory aligned with source while
+also checking that the curated setup tables above do not omit a key they
+explicitly document.

package/docs/content/file-uploads.mdx

@@ -102,7 +102,7 @@ A one-time warning is logged when the fallback is used.
 
 ## Builder.io Hosting {#builder-hosting}
 
-When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Files are served from a CDN with no configuration needed. This is the recommended production setup.
+When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Builder.io's free tier includes this managed storage. Files are served from a CDN with no configuration needed. This is the recommended production setup.
 
 ## Custom Providers {#custom-providers}
 

package/docs/content/getting-started.mdx

@@ -99,7 +99,7 @@ The agent chat can't respond until you connect an AI engine. After you're logged
 
 | Path                   | Steps                                                                                                                                      |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Connect Builder**    | Click **Connect Builder.io**, choose the Builder Space, then click **Authorize**. No keys to manage yourself.                              |
+| **Connect Builder**    | Click **Connect Builder.io** (free tier available), choose the Builder Space, then click **Authorize**. No keys to manage yourself.        |
 | **Bring your own key** | Enter your Anthropic or OpenAI API key in the Setup panel. Get an Anthropic key at [console.anthropic.com](https://console.anthropic.com). |
 
 Alternatively, create a `.env` file in the `my-app/` directory (the same

package/docs/content/key-concepts.mdx

@@ -25,7 +25,7 @@ At runtime, every agent-native app is three things working together:
 
 - **Agent** — Autonomous AI that reads data, writes data, runs actions, and uses configured tools. It can also modify source when its frame is intentionally granted workspace and write tooling. Customizable with skills and instructions.
 - **Application** — The product surface around the agent. This may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
-- **Computer** — Database, browser, and configured tool runtimes. Agents work through the app's action and data surface; MCP servers are optional add-ons, not the foundation.
+- **Computer** — Database, browser, and configured tool runtimes. Agents work through the app's action and data surface; an app may expose that same action surface over MCP, while external MCP servers remain optional add-ons rather than the foundation.
 
 <Diagram id="doc-block-t1f7pj" title="Agent, application, and computer" summary="Three layers working together over one shared SQL store. The agent and the application both read and write the same data.">
 

package/docs/content/multi-app-workspace.mdx

@@ -260,7 +260,7 @@ my-company-platform/
 
 A few onboarding flows are workspace-aware out of the box:
 
-- **Builder `/cli-auth`**: clicking "Connect Builder" from any app writes `BUILDER_PRIVATE_KEY` and friends to scoped DB secrets, so every app can resolve the connection without sharing a deploy-global key.
+- **Builder `/cli-auth`**: clicking "Connect Builder" (free tier available) from any app writes `BUILDER_PRIVATE_KEY` and friends to scoped DB secrets, so every app can resolve the connection without sharing a deploy-global key.
 - **Compatibility key route** (`POST /_agent-native/env-vars`): older onboarding forms still call this route name, but it now saves values as scoped DB secrets. Pass `scope: "workspace"` to share with the active org, or omit it for a per-user key.
 
 This works because every app in the same workspace points at the same `DATABASE_URL` by default, so framework credential storage (`@agent-native/core/credentials`) makes a credential available to every app without per-app config. Add a thin helper in `packages/shared` if your workspace wants a stricter naming convention.

package/docs/content/template-clips-ai-and-editing.mdx

@@ -12,11 +12,11 @@ This page covers what happens to a recording after it's captured: transcription
 
 Transcription tries the fastest, free option first and only falls back to a paid one when it has to:
 
-| Order | Provider                        | Notes                                                                                     |
-| ----- | ------------------------------- | ----------------------------------------------------------------------------------------- |
-| 1     | Native (on-device)              | Browser Web Speech API or desktop local Whisper/macOS speech — instant, no API key        |
-| 2     | Builder.io managed (Gemini)     | Cloud fallback when native text is missing; no extra key needed once Builder is connected |
-| 3     | Groq (`whisper-large-v3-turbo`) | Optional backup if you'd rather bring your own key                                        |
+| Order | Provider                        | Notes                                                                                                                                         |
+| ----- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1     | Native (on-device)              | Browser Web Speech API or desktop local Whisper/macOS speech — instant, no API key                                                            |
+| 2     | Builder.io managed (Gemini)     | Cloud fallback when native text is missing; no extra key needed once Builder is connected; Builder.io's free tier includes managed AI credits |
+| 3     | Groq (`whisper-large-v3-turbo`) | Optional backup if you'd rather bring your own key                                                                                            |
 
 Once a transcript is ready, the agent fills in a title, summary, and chapter markers automatically, and keeps them current as you edit. You can also ask directly:
 
@@ -104,7 +104,7 @@ Human views and agent views are tracked in separate counters on purpose, so an a
 
 ## Builder credit status
 
-Backup transcription, transcript cleanup, and AI titles/summaries run on Builder.io-managed AI credits by default. If one of those stops working, ask the agent — it checks the current credit status and explains whether credits are paused rather than treating it as a bug. The fix is either adding Builder.io credits/upgrading, or connecting a personal Groq key as a fallback for transcription.
+Backup transcription, transcript cleanup, and AI titles/summaries run on Builder.io-managed AI credits by default, including the free tier's credits. If one of those stops working, ask the agent — it checks the current credit status and explains whether credits are paused rather than treating it as a bug. The fix is either adding Builder.io credits/upgrading, or connecting a personal Groq key as a fallback for transcription.
 
 ## What's next
 

package/docs/content/template-clips-developers.mdx

@@ -18,7 +18,7 @@ See [Getting started](/docs/getting-started) for installing dependencies, runnin
 
 Clips is a larger template with a native recorder (it ships a desktop companion for local capture). Four setup steps get recordings uploading end to end:
 
-1. **Video storage (required).** Connect a storage backend through the onboarding wizard or Clips Settings. The easiest path is Builder.io (free during beta, one-click). For self-hosted storage, save `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and optionally `S3_REGION` and `S3_PUBLIC_BASE_URL` in the app; the values are stored as scoped DB secrets. Cloudflare R2 and DigitalOcean Spaces use the same key names with the `R2_*` prefix.
+1. **Video storage (required).** Connect a storage backend through the onboarding wizard or Clips Settings. The easiest path is Builder.io (free tier includes video storage and AI credits, one-click). For self-hosted storage, save `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and optionally `S3_REGION` and `S3_PUBLIC_BASE_URL` in the app; the values are stored as scoped DB secrets. Cloudflare R2 and DigitalOcean Spaces use the same key names with the `R2_*` prefix.
 2. **Google Calendar (optional).** To sync upcoming meetings, connect a Google Calendar account from Settings. The OAuth callback URL in dev is `http://localhost:8094/_agent-native/google/callback`. Set up a Google OAuth client in [Google Cloud Console](https://console.cloud.google.com/) with the Gmail and Google Calendar APIs enabled.
 3. **Screen-capture permissions.** On macOS, grant Screen Recording permission to the browser (or the desktop companion app) in System Settings → Privacy & Security → Screen Recording.
 4. **Slack previews (optional).** Create a Slack app with `links:read`, `links:write`, and `links.embed:write`; subscribe to `link_shared`; add your Clips share domain under **App Unfurl Domains**; set the Request URL to `https://your-clips.example.com/api/slack/unfurl`; and add the OAuth redirect URL `https://your-clips.example.com/api/slack/oauth/callback`. Configure `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and `SLACK_SIGNING_SECRET`, then connect workspaces from Clips Settings.
@@ -29,7 +29,7 @@ The hosted Clips app at [clips.agent-native.com](https://clips.agent-native.com)
 
 1. **Create the app** with the quick-start command above.
 
-2. **Configure production state.** Set a persistent `DATABASE_URL`, the normal production auth/secrets variables from [Deployment](/docs/deployment), and a video storage provider. Builder.io Connect is the easiest storage path; for self-hosted storage, save `S3_*` or `R2_*` keys from Clips Settings for an S3-compatible bucket.
+2. **Configure production state.** Set a persistent `DATABASE_URL`, the normal production auth/secrets variables from [Deployment](/docs/deployment), and a video storage provider. Builder.io Connect is the easiest storage path, and its free tier includes video storage and AI credits; for self-hosted storage, save `S3_*` or `R2_*` keys from Clips Settings for an S3-compatible bucket.
 
 3. **Deploy the web app.** For a plain Node deploy:
 
@@ -44,7 +44,7 @@ The hosted Clips app at [clips.agent-native.com](https://clips.agent-native.com)
 
 5. **Enable the Chrome extension after publishing.** See [Chrome extension and embedded bug reports](#chrome-extension-and-embedded-bug-reports) below.
 
-6. **Connect optional integrations.** Google Calendar powers the Meetings tab, `GEMINI_API_KEY` or Builder.io Connect powers transcript cleanup and titles, `GROQ_API_KEY` can provide speech-to-text fallback, and the Slack OAuth connection in Settings enables playable Slack unfurls.
+6. **Connect optional integrations.** Google Calendar powers the Meetings tab, `GEMINI_API_KEY` or Builder.io Connect (free tier includes AI credits) powers transcript cleanup and titles, `GROQ_API_KEY` can provide speech-to-text fallback, and the Slack OAuth connection in Settings enables playable Slack unfurls.
 
 For local development, run the web app with `pnpm dev` and point the desktop tray app at `http://localhost:8094`.
 

package/docs/content/toolkit-settings.mdx

@@ -105,7 +105,7 @@ on so settings stay findable everywhere.
 
 ## UX Standard {#ux-standard}
 
-- Keep model keys, OAuth connections, Builder connect, language, team, and app
+- Keep model keys, OAuth connections, Builder connect (free tier available), language, team, and app
   preferences in one route.
 - Keep search on and register a `SettingsSearchEntry` for every meaningful
   control so users can find settings by name instead of scanning tabs.