@agent-native/core 0.137.7 → 0.138.0

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.

package/docs/content/voice-input.mdx

@@ -7,13 +7,13 @@ description: "Voice dictation in the agent chat composer — Builder Gemini, BYO
 
 Every agent-native app has a microphone in the chat composer. Click it, talk, and your words get transcribed into the prompt. Useful on mobile, useful for long prompts, useful when your hands are on something else.
 
-The framework handles all of this automatically. Builder-connected users get Builder-hosted Gemini Flash-Lite by default; otherwise users can bring their own provider key or fall back to browser speech recognition.
+The framework handles all of this automatically. Builder-connected users get Builder-hosted Gemini Flash-Lite by default, with managed AI credits available on Builder.io's free tier; otherwise users can bring their own provider key or fall back to browser speech recognition.
 
 ## How it works {#how-it-works}
 
 The composer's voice button records audio in the browser, then picks a provider:
 
-1. **Builder Gemini Flash-Lite (default when Builder is connected).** The browser POSTs audio to `/_agent-native/transcribe-voice`, which proxies through Builder.io using Gemini Flash-Lite. No Google API key required.
+1. **Builder Gemini Flash-Lite (default when Builder is connected).** The browser POSTs audio to `/_agent-native/transcribe-voice`, which proxies through Builder.io using Gemini Flash-Lite. No Google API key required; managed AI credits are available on Builder.io's free tier.
 2. **BYOK cloud providers.** Users can choose Google Gemini, Groq Whisper, or OpenAI Whisper from Settings. The route resolves user-scoped encrypted secrets before shared deployment credentials.
 3. **Browser Web Speech API (fallback).** If no server provider is available, the composer can use the browser's built-in speech recognition. Works in Chromium-based browsers (Chrome, Edge, Arc) and Safari. Less accurate; streams live.
 
@@ -69,7 +69,7 @@ The route is **same-origin only** — cross-site POSTs are rejected so an attack
 
 ## Enabling Providers {#enabling-providers}
 
-Builder is the easiest path: connect Builder.io from Settings and the default provider becomes Builder Gemini Flash-Lite. For BYOK providers, add the matching key in Settings → API Keys.
+Builder is the easiest path: connect Builder.io (free tier available) from Settings and the default provider becomes Builder Gemini Flash-Lite. For BYOK providers, add the matching key in Settings → API Keys.
 
 ### Per-user (recommended for SaaS)
 
@@ -87,7 +87,7 @@ Set `GEMINI_API_KEY`, `GROQ_API_KEY`, or `OPENAI_API_KEY` as an environment vari
 
 ## Realtime speech mode {#realtime-speech-mode}
 
-Beyond one-shot dictation, the composer also offers a live, hands-free conversation mode. When the mic opens, a popover lets you choose **Realtime speech** or **Editable dictation**. Realtime speech uses a connected Builder account automatically (same as dictation), or an `OPENAI_API_KEY` if Builder isn't connected — connects the browser to `gpt-realtime-2.1` over WebRTC. The chat collapses into a speech orb in the bottom-end corner; click the orb to show or hide chat without ending the conversation. The orb stays visible above the chat even if the chat opens automatically, and its compact waveform reacts to your voice and the assistant's voice.
+Beyond one-shot dictation, the composer also offers a live, hands-free conversation mode. When the mic opens, a popover lets you choose **Realtime speech** or **Editable dictation**. Realtime speech uses a connected Builder account automatically (same as dictation; free tier available), or an `OPENAI_API_KEY` if Builder isn't connected — connects the browser to `gpt-realtime-2.1` over WebRTC. The chat collapses into a speech orb in the bottom-end corner; click the orb to show or hide chat without ending the conversation. The orb stays visible above the chat even if the chat opens automatically, and its compact waveform reacts to your voice and the assistant's voice.
 
 The speech model uses the same authenticated Agent Native tools as chat, so it can navigate the app and call actions while it talks. Approval-gated actions remain paused until you approve them. Only completed user and assistant text turns are appended to the original chat thread. Ending voice mode opens that chat so you can continue over text; audio and interim transcript fragments are never stored. A realtime session lasts at most 60 minutes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.137.7",
+  "version": "0.138.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -98,6 +98,10 @@
       "types": "./dist/agent-native/index.d.ts",
       "default": "./dist/agent-native/index.js"
     },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
     "./agent-web": "./dist/agent-web/index.js",
     "./db": "./dist/db/index.js",
     "./db-admin": "./dist/db-admin/index.js",
@@ -401,7 +405,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.1"
+    "@agent-native/toolkit": "^0.13.2"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/eject/provider-api-definitions.ts

@@ -36,6 +36,7 @@ export const providerApiOverrides: ProviderApiConfig[] = [
   provider("gcloud"),
   provider("github"),
   provider("figma"),
+  provider("fullstory"),
   provider("gmail"),
   provider("gong"),
   provider("google_calendar"),

package/src/eject/remote-mcp-presets.ts

@@ -59,6 +59,7 @@ function preset(id: string): DefaultMcpIntegration {
 export const DEFAULT_MCP_INTEGRATIONS: DefaultMcpIntegration[] = [
   preset("context7"),
   preset("sentry"),
+  preset("fullstory"),
   preset("notion"),
   preset("granola"),
   preset("semgrep"),

package/src/templates/chat/.agents/skills/agent-native-docs/SKILL.md

@@ -31,6 +31,26 @@ the framework monorepo checkout.
 
 From a generated app directory:
 
+```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
+```
+
+Use `framework-search` first when a question may cross the docs and source
+boundary. It searches the version-matched framework docs, runtime-visible
+skills, readable Core or Toolkit package source, and first-party template
+corpus in one bounded read-only call. Use `scope: docs` or `scope: source` to
+narrow it, then use the existing focused readers for the page or file you need.
+
+The same tool is available in the headless `pnpm agent` loop and every built-in
+app agent. Its default substring mode is safest for ordinary questions; use
+`glob` for wildcard paths, `sql-like` for `%` and `_` wildcards, and `regex`
+for precise structural matches. Results are bounded, so refine the pattern or
+path instead of treating a truncated result as exhaustive.
+
+From a generated app directory, the lower-level readers remain available:
+
 ```bash
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
@@ -41,9 +61,9 @@ pnpm action source-search --path templates/chat/actions/hello.ts
 pnpm action source-search --list
 ```
 
-The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
-read-only `source-search` tool with `query`, `path`, and `list`.
+The headless `pnpm agent` loop and built-in app agent also expose read-only
+`framework-search`, `docs-search`, and `source-search` tools. Use the unified
+tool for discovery, then the focused tools for full page or file reads.
 
 If the action runner is unavailable, search the package directly:
 

package/src/templates/chat/.agents/skills/agent-native-toolkit/SKILL.md

@@ -65,6 +65,22 @@ Contextual agent UI is not a reason to expose every option at once. Start with
 the domain task's primary action, reveal review or configuration only when the
 current state needs it, and let the sidebar carry conversational depth.
 
+## Visual Direction And Workspace Variety
+
+Shared workspace behavior should be consistent without forcing every app into
+the same visual skin. Keep shell and component tokens semantic, then let each
+app declare a named direction in `DESIGN.md` before styling. A new app should
+choose its palette family and composition from the product context, compare
+nearby apps, and avoid inheriting their accent by default. Use the
+`frontend-design` visual-direction reference for mode, palette, type, density,
+shape, anti-references, and the `distill` / `typeset` / `colorize` / `layout` /
+`polish` / `audit` review vocabulary.
+
+Do not make warm beige plus terracotta the workspace fallback. Preserve a
+workspace-level brand when one exists; otherwise keep shared chrome neutral and
+allow app-owned accents to distinguish products while retaining accessible
+semantic states and the shared AgentSidebar contract.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI:

package/src/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -34,6 +34,22 @@ Before coding, decide:
 
 Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
 
+## Visual Direction Contract
+
+Before styling a new app or workspace surface, define its product mode,
+audience, visual world, palette family, type treatment, composition, shape
+language, and anti-references in `DESIGN.md`. Read
+`references/visual-direction.md` for the direction families and review
+vocabulary. This is the Impeccable-inspired design contract for Agent-Native
+apps: understand the product, name the mode, deal a few coherent directions,
+commit to one, and audit the result instead of averaging back to a starter.
+
+Preserve an existing brand system and component library. When no brand exists,
+choose a deliberate direction based on the domain and compare sibling apps
+before selecting its accent family. Shared behavior and semantic token names
+should stay consistent; palette, density, composition, type contrast, and
+shape language should not be identical by default.
+
 ## Minimalism And Progressive Disclosure
 
 Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
@@ -81,13 +97,13 @@ passed this requirement yet.
   operational apps, make a clear sans-serif hierarchy the default; reserve a
   serif or editorial face for a deliberate content preview or brand moment,
   not the whole application shell.
-- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
+- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes, default warm beige/terracotta, and default purple/blue gradients unless the brand demands them. New apps should choose a product-fitting accent family rather than inherit the previous app's color.
 - **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
-**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option. Commit to one named direction, pair any reference with the reason it fits, and match implementation effort to the vision. If the brief is open, consider two or three coherent visual worlds, then commit to one instead of averaging them. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
 
 ## Agent-Native UI Rules
 
@@ -164,6 +180,9 @@ as an operator would use it repeatedly:
 - For review flows, stack the source/original first and the generated or safe
   result second by default. Use side-by-side comparison only when the content
   is short enough to scan without excessive horizontal reading.
+- Compare the result with sibling apps. Shared toolkit behavior should feel
+  consistent, but a repeated palette, hero composition, type pairing, and
+  radius language without a product reason is visual drift, not consistency.
 - Check the result at the target desktop width and a narrow width. If the first
   viewport feels like documentation instead of a tool, subtract again.
 
@@ -216,6 +235,8 @@ For substantial frontend work:
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,
    `portalContainer`, and z-index stacking checks.
+6. For a new app or a visual redesign, review `DESIGN.md` against the rendered
+   surface and run the anti-slop audit in `references/visual-direction.md`.
 
 ## Related Skills
 

package/src/templates/chat/.agents/skills/frontend-design/references/visual-direction.md

@@ -0,0 +1,99 @@
+# Visual Direction Reference
+
+Use this reference when a new app or workspace needs a visual point of view and
+does not already have an established brand system. It adapts the useful parts
+of Impeccable's workflow: understand the product, name the surface mode, deal
+several coherent directions, commit to one, and audit the result for defaults
+that became the design by accident.
+
+## The direction contract
+
+Before writing UI, capture these decisions in the app's `DESIGN.md`:
+
+| Decision             | What to record                                                      |
+| -------------------- | ------------------------------------------------------------------- |
+| Product mode         | `operate`, `read`, `persuade`, or `experience`                      |
+| Audience and cadence | Who uses it, how often, and under what conditions                   |
+| Visual world         | A short name and the feeling it creates                             |
+| Palette family       | The semantic accent family and neutral undertone                    |
+| Type treatment       | Sans-first, editorial contrast, or display-led emphasis             |
+| Composition          | Dense console, focused workbench, document, canvas, or guided steps |
+| Shape language       | Quiet corners, crisp geometry, or soft utility surfaces             |
+| Anti-references      | Defaults this app must not drift toward                             |
+
+`DESIGN.md` is a portable design contract, not a license to bypass the app's
+tokens or component system. If the app already has a brand system, document it
+and preserve it. If it does not, choose a direction before styling.
+
+## Palette families
+
+Use one family as an accent and keep the rest of the system semantic and quiet.
+These are starting points, not a fixed theme library:
+
+| Family           | Good fit                                    | Typical character                 |
+| ---------------- | ------------------------------------------- | --------------------------------- |
+| Ink / graphite   | Admin, security, sensitive review           | Serious, low-noise, high contrast |
+| Cobalt / sky     | Planning, collaboration, scheduling         | Clear, trustworthy, alert         |
+| Pine / teal      | Automation, systems, finance, data          | Calm, capable, grounded           |
+| Indigo / violet  | Slides, creative tools, research            | Exploratory, focused, expressive  |
+| Plum / berry     | Publishing, knowledge, editorial work       | Distinctive, thoughtful, human    |
+| Coral / rose     | Communication, people, customer workflows   | Warm, direct, social              |
+| Ochre / citron   | Lightweight planning or energetic utilities | Optimistic, sparing, directional  |
+| Paper / charcoal | Long-form reading, exports, approvals       | Tactile, restrained, legible      |
+
+Do not make warm beige plus terracotta the universal fallback. Do not rotate
+through saturated colors mechanically. Choose the family that supports the
+workflow, then verify contrast, dark mode, focus states, destructive states,
+and the sidebar boundary.
+
+## Variation without chaos
+
+Vary at least two independent axes when sibling apps share a workspace:
+
+- accent family or neutral undertone;
+- information density and page composition;
+- type contrast and display treatment;
+- radius and border language;
+- navigation emphasis and use of whitespace.
+
+Keep shared behavior, semantic token names, accessibility, and AgentSidebar
+placement consistent. The goal is a family of products, not five unrelated
+themes and not five copies of the same starter.
+
+For a batch of apps, keep a small direction ledger in the workspace
+`DESIGN.md` or the handoff. Record each app's mode, direction, and palette
+family, then choose a new family or a clearly different composition for the
+next app unless an existing brand requires reuse. Never copy a sibling's
+`global.css` palette block or treat the last app's accent as the generator
+default.
+
+## Review vocabulary
+
+Make one named intervention at a time so the agent can reason about the
+change:
+
+- `distill` - remove copy, controls, cards, and chrome that do not serve the
+  next decision;
+- `typeset` - repair hierarchy, measure, line length, and emphasis;
+- `colorize` - establish a restrained semantic palette and contrast states;
+- `layout` - repair grouping, density, alignment, and responsive composition;
+- `polish` - resolve the small visual inconsistencies after the structure is
+  right;
+- `audit` - check slop, accessibility, responsive behavior, and visual drift.
+
+Do not average several directions into a generic compromise. Deal two or three
+coherent options when the brief is open, select one, and encode the decision in
+tokens and `DESIGN.md`.
+
+## Anti-slop audit
+
+Before handoff, inspect the first viewport and ask:
+
+- Did the app inherit the neighboring app's palette or hero layout without a
+  product reason?
+- Are there equal-weight cards, status chips, helper paragraphs, or controls
+  that should be removed or disclosed?
+- Does the typography fit the product mode instead of decorating the shell?
+- Is the AgentSidebar distinct but quiet, with the domain page still primary?
+- Are focus, loading, empty, error, dark, and narrow-width states part of the
+  same design direction?

package/src/templates/chat/AGENTS.md

@@ -22,6 +22,9 @@ workflow needs durable UI around the conversation.
 - Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
   type for content previews. Give the AgentSidebar a subtle surface/divider
   boundary, and stack original/generated review vertically by default.
+- Before visual work, read `frontend-design` and fill in `DESIGN.md`. Choose a
+  product-fitting visual direction and palette family; do not make warm beige
+  plus terracotta the default or copy a sibling app's accent automatically.
 - Every AI-labeled button must call `sendToAgentChat()` with
   `openSidebar: true`; label deterministic local actions as local or preview.
 - Scale effort to the task. A small, well-specified change is a short read, the