@agent-native/core 0.164.4 → 0.164.12

package/docs/content/docs-components.mdx

@@ -151,7 +151,7 @@ Each step is a `###` heading followed by the body content. Steps work best for 3
 
 Typed operations callable from the agent, UI, CLI, and HTTP. Define once, call from anywhere.
 
-### [Database](/docs/database)
+### [Database](/docs/server-database)
 
 SQL persistence with automatic migrations. SQLite locally, Postgres/Turso in production.
 
@@ -172,7 +172,7 @@ Plain-text instruction files that give the agent domain knowledge and task-speci
 
 Typed operations callable from the agent, UI, CLI, and HTTP. Define once, call from anywhere.
 
-### [Database](/docs/database)
+### [Database](/docs/server-database)
 
 SQL persistence with automatic migrations. SQLite locally, Postgres/Turso in production.
 

package/docs/content/environment-variables.mdx

@@ -12,7 +12,7 @@ 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)
+For a normal app, start with [Deployment: Environment Variables](/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.
@@ -24,46 +24,46 @@ 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. Production also accepts `<APP_NAME>_DATABASE_URL` or Netlify's `NETLIFY_DATABASE_URL`. | 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`                                      | Optional canonical public origin used for auth, OAuth, A2A, webhooks, and generated links. Netlify and Vercel metadata are inferred when it is unset.                   | An absolute public `http(s)` origin.                                                                           |
-| `BETTER_AUTH_URL`                              | Optional Better Auth origin override. Known template or request context, `APP_URL`, and platform metadata such as Netlify or Vercel are used when it is unset.          | 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`                           | Stable Better Auth session signing secret for standalone production apps. Workspace deploys can derive it from `A2A_SECRET`.                                            | 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.                                                   |
-| `AGENT_ENGINE`                                 | Explicitly selects the agent engine instead of auto-detecting from provider keys.                                                                                       | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
-| `AGENT_ENGINE_PREFER_BYO_KEY`                  | Prefers a provider key you set over the managed Builder gateway during auto-detection.                                                                                  | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
-| `AUTH_MODE`                                    | Selects the local authentication behavior used by CLI and agent flows.                                                                                                  | Unset or `local`; this is not a browser login bypass.                                                          |
-| `AGENT_NATIVE_ALLOW_BUILDER_PREVIEW_LOCAL_DEV` | Explicitly enables the existing local-dev sign-in button on approved Builder preview hosts during development.                                                          | `1` or `true`; requires development mode and must stay off public or production deployments.                   |
-| `AUTH_DISABLED`                                | Disables auth for local or preview-only work. Unset already means false.                                                                                                | `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).       |
-| `AGENT_NATIVE_ENABLE_KEEP_WARM`                | Opts into the Netlify keep-warm scheduled function; unset by default.                                                                                                   | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM`               | Compatibility kill switch for the Netlify keep-warm scheduled function.                                                                                                 | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
-| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`              | Keep-warm cadence override when enabled.                                                                                                                                | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                         |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND`    | Drops only the background-function warm and keeps the server warm when keep-warm is enabled.                                                                            | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
-| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`        | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work.                                                                          | `1`; queued work is not retried without another driver.                                                        |
-| `AGENT_NATIVE_SKIP_ENSURE_TABLES`              | Skips on-demand schema DDL for an already-migrated database.                                                                                                            | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set.     |
-| `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.                                                                |
+| Variable                                       | What it controls                                                                                                                                                        | Supported values or format                                                                                              |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                                 | Primary SQL connection. Local development falls back to SQLite when it is unset. Production also accepts `<APP_NAME>_DATABASE_URL` or Netlify's `NETLIFY_DATABASE_URL`. | 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`                                      | Optional canonical public origin used for auth, OAuth, A2A, webhooks, and generated links. Netlify and Vercel metadata are inferred when it is unset.                   | An absolute public `http(s)` origin.                                                                                    |
+| `BETTER_AUTH_URL`                              | Optional Better Auth origin override. Known template or request context, `APP_URL`, and platform metadata such as Netlify or Vercel are used when it is unset.          | 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`                           | Stable Better Auth session signing secret for standalone production apps. Workspace deploys can derive it from `A2A_SECRET`.                                            | 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.                                                            |
+| `AGENT_ENGINE`                                 | Explicitly selects the agent engine instead of auto-detecting from provider keys.                                                                                       | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                               |
+| `AGENT_ENGINE_PREFER_BYO_KEY`                  | Prefers a provider key you set over the managed Builder gateway during auto-detection.                                                                                  | `true` or `1`; Builder still applies as the fallback when no provider key is set.                                       |
+| `AUTH_MODE`                                    | Selects the local authentication behavior used by CLI and agent flows.                                                                                                  | Unset or `local`; this is not a browser login bypass.                                                                   |
+| `AGENT_NATIVE_ALLOW_BUILDER_PREVIEW_LOCAL_DEV` | Explicitly enables the existing local-dev sign-in button on approved Builder preview hosts during development.                                                          | `1` or `true`; requires development mode and must stay off public or production deployments.                            |
+| `AUTH_DISABLED`                                | Disables auth for local or preview-only work. Unset already means false.                                                                                                | `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/actions-agent-tools#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/ssr-caching).                           |
+| `AGENT_NATIVE_ENABLE_KEEP_WARM`                | Opts into the Netlify keep-warm scheduled function; unset by default.                                                                                                   | `1`; see [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                  |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`               | Compatibility kill switch for the Netlify keep-warm scheduled function.                                                                                                 | `1`; see [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                  |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`              | Keep-warm cadence override when enabled.                                                                                                                                | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                                  |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND`    | Drops only the background-function warm and keeps the server warm when keep-warm is enabled.                                                                            | `1`; see [Keep-warm](/docs/netlify#netlify-keep-warm).                                                                  |
+| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`        | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work.                                                                          | `1`; queued work is not retried without another driver.                                                                 |
+| `AGENT_NATIVE_SKIP_ENSURE_TABLES`              | Skips on-demand schema DDL for an already-migrated database.                                                                                                            | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set.              |
+| `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:
 

package/docs/content/file-uploads.mdx

@@ -1,11 +1,11 @@
 ---
 title: "File Uploads"
-description: "Configure durable file upload storage — Builder.io or custom object storage for production."
+description: "Configure durable file upload storage with Builder.io or a custom object storage provider for production."
 ---
 
 # File Uploads
 
-The framework provides a file upload abstraction that routes uploads through a configurable provider. Templates call `uploadFile()` and get back a URL — the storage backend is swappable without changing application code.
+The framework provides a file upload abstraction that routes uploads through a configurable provider. Templates call `uploadFile()` and get back a URL. The storage backend is swappable without changing application code.
 
 ## How It Works {#how-it-works}
 
@@ -13,9 +13,21 @@ Upload requests go to `POST /_agent-native/file-upload`, which dispatches to the
 
 The provider resolution order is:
 
-1. **User-registered providers** — custom providers registered via `registerFileUploadProvider()`
-2. **Builder.io provider** — built-in, activates automatically when Builder.io is connected
-3. **No provider** — the upload is rejected and the chat renders a storage setup CTA; binary data is never persisted in SQL
+1. **User-registered providers**: custom providers registered via `registerFileUploadProvider()`.
+2. **Builder.io provider**: built-in, and it activates automatically when Builder.io is connected.
+3. **No provider**: the upload is rejected and the chat renders a storage setup CTA. Binary data is never persisted in SQL.
+
+Among user-registered providers, the first one registered that reports
+itself configured wins. `registerFileUploadProvider()` is idempotent per
+`id`. Registering under an id that is already in use replaces the existing
+provider.
+
+The UI decides whether to show a storage-setup prompt using only the
+synchronous `isConfigured()` check, before an upload is attempted. The
+actual upload checks both `isConfigured()` and `isConfiguredForRequest()`.
+A provider that only reports itself configured through
+`isConfiguredForRequest()` stays invisible to the setup prompt even though
+uploads through it would succeed.
 
 <Diagram id="doc-block-hq5uvx" title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. Without one, the upload fails closed so binary data is never persisted in SQL.">
 
@@ -32,7 +44,7 @@ The provider resolution order is:
       <span class="diagram-pill accent">1</span>
       <div class="diagram-node">
         User-registered<br /><small class="diagram-muted"
-          >registerFileUploadProvider() — S3, R2, GCS…</small
+          >registerFileUploadProvider() for S3, R2, GCS…</small
         >
       </div>
     </div>
@@ -40,7 +52,7 @@ The provider resolution order is:
       <span class="diagram-pill">2</span>
       <div class="diagram-node">
         Builder.io<br /><small class="diagram-muted"
-          >auto when connected — CDN-served</small
+          >auto when connected, CDN-served</small
         >
       </div>
     </div>
@@ -48,7 +60,7 @@ The provider resolution order is:
       <span class="diagram-pill warn">3</span>
       <div class="diagram-node">
         No provider<br /><small class="diagram-muted"
-          >setup CTA — no binary persistence</small
+          >setup CTA, no binary persistence</small
         >
       </div>
     </div>
@@ -85,8 +97,24 @@ The provider resolution order is:
   "contentType": "multipart/form-data"
 }} responses={[
   {
-    "status": "200",
-    "description": "{ url, id?, provider } — the public URL and which provider handled it."
+    "status": "201",
+    "description": "`{ url, id?, provider }`: the public URL and which provider handled it."
+  },
+  {
+    "status": "401",
+    "description": "No authenticated session."
+  },
+  {
+    "status": "413",
+    "description": "File exceeds the 25 MB upload ceiling."
+  },
+  {
+    "status": "415",
+    "description": "Blocked MIME type, such as an executable or script."
+  },
+  {
+    "status": "503",
+    "description": "No file upload provider is configured."
   }
 ]}>
 
@@ -104,42 +132,47 @@ When your app is connected to Builder.io, file uploads are automatically routed
 
 ## Custom Providers {#custom-providers}
 
-Register a custom provider in a server plugin to use any storage backend (S3, Cloudflare R2, GCS, etc.):
+The framework already ships a built-in provider for S3-compatible storage
+(AWS S3, Cloudflare R2, MinIO, and similar). Connect it with environment
+variables or through the sidebar onboarding checklist. No code is required.
+See [Onboarding](/docs/onboarding).
+
+Register a custom provider only for a different kind of backend. This
+example uploads through a generic HTTP API using `fetch()`:
 
 ```ts filename="server/plugins/file-upload.ts"
-import { S3 } from "@aws-sdk/client-s3";
 import { registerFileUploadProvider } from "@agent-native/core/file-upload";
-import { defineNitroPlugin, resolveSecret } from "@agent-native/core/server";
-
-const s3Client = new S3({ region: process.env.AWS_REGION });
+import { defineNitroPlugin } from "@agent-native/core/server";
 
 export default defineNitroPlugin(() => {
-  const readBucket = () => resolveSecret("S3_BUCKET");
-
   registerFileUploadProvider({
-    id: "s3",
-    name: "Amazon S3",
-    isConfigured: () => false,
-    isConfiguredForRequest: async () => !!(await readBucket()),
+    id: "my-storage",
+    name: "My Storage",
+    isConfigured: () => !!process.env.UPLOAD_ENDPOINT,
     upload: async ({ data, filename, mimeType }) => {
-      const bucket = await readBucket();
-      if (!bucket) throw new Error("S3 storage is not configured");
-      const key = `uploads/${Date.now()}-${filename}`;
-      await s3Client.putObject({
-        Bucket: bucket,
-        Key: key,
-        Body: data,
-        ContentType: mimeType,
-      });
-      return {
-        url: `https://${bucket}.s3.amazonaws.com/${key}`,
-        provider: "s3",
-      };
+      const endpoint = process.env.UPLOAD_ENDPOINT!;
+      const body = new FormData();
+      body.append("file", new Blob([data], { type: mimeType }), filename);
+
+      // This example assumes an upload API that accepts a multipart file
+      // and returns { url }. Adjust the request and response handling to
+      // match your own provider's actual contract.
+      const response = await fetch(endpoint, { method: "POST", body });
+      if (!response.ok) {
+        throw new Error(`Upload failed with status ${response.status}`);
+      }
+
+      const { url } = await response.json();
+      return { url, provider: "my-storage" };
     },
   });
 });
 ```
 
+Use `resolveSecret()` from `@agent-native/core/server` instead of an
+environment variable when the provider needs a real credential, such as an
+API key. See [Security — Secrets Management](/docs/security#secrets).
+
 ## Upload API {#upload-api}
 
 The `FileUploadProvider` interface:
@@ -158,6 +191,8 @@ interface FileUploadInput {
   filename?: string; // Original filename
   mimeType?: string; // MIME type, e.g. "image/png"
   ownerEmail?: string; // For request-scoped provider credentials
+  stableUrl?: boolean; // Builder.io hint: one stable URL while compression finishes
+  recordAsset?: boolean; // Builder.io hint: set false to skip the asset library
 }
 
 interface FileUploadResult {
@@ -179,15 +214,15 @@ const result = await uploadFile({
 });
 
 if (result) {
-  // Provider handled it — result.url is the public URL
+  // Provider handled it. result.url is the public URL.
 } else {
-  // No provider configured — show the storage setup CTA, or skip
+  // No provider configured. Show the storage setup CTA, or skip.
 }
 ```
 
 ## Resumable / Streaming Uploads {#resumable}
 
-A provider can optionally implement a `resumable` block on `FileUploadProvider` for uploads that need to stream to storage as data arrives instead of buffering the whole file first — the Clips template uses this to relay a recording to storage chunk-by-chunk while it is still being recorded, rather than assembling the full blob after the recorder stops.
+A provider can optionally implement a `resumable` block on `FileUploadProvider` for uploads that need to stream to storage as data arrives instead of buffering the whole file first. The Clips template uses this to relay a recording to storage chunk-by-chunk while it is still being recorded, rather than assembling the full blob after the recorder stops.
 
 ```ts
 interface FileUploadProvider {
@@ -227,11 +262,10 @@ interface ResumableChunkResult {
 }
 ```
 
-When `resumable` is present, callers that stream data in (like a recorder) call `startSession` once, `relayChunk` repeatedly as bytes arrive, and `completeSession` when the stream ends — instead of the single buffered `upload()` call. A provider with no `resumable` block only ever sees the buffered path; implement it only when your storage backend has a native chunked/resumable upload API (S3 multipart, GCS resumable uploads, etc.) worth exposing.
+When `resumable` is present, callers that stream data in (like a recorder) call `startSession` once, `relayChunk` repeatedly as bytes arrive, and `completeSession` when the stream ends. This replaces the single buffered `upload()` call. A provider with no `resumable` block only ever sees the buffered path. Implement it only when your storage backend has a native chunked/resumable upload API (S3 multipart, GCS resumable uploads, etc.) worth exposing.
 
 ## What's next
 
-- [**Database**](/docs/database) — why binary blobs stay out of SQL and go through this provider abstraction instead
+- [**Database**](/docs/server-database) — the `getDb()`/schema pattern for persisting the URL `uploadFile()` returns
 - [**Security — Secrets Management**](/docs/security#secrets) — how `resolveSecret()` and the credential vault encrypt provider keys at rest
 - [**Onboarding**](/docs/onboarding) — registering a custom provider's setup step in the sidebar checklist
-- [**Deployment**](/docs/deployment) — connecting Builder.io or a custom provider in production

package/docs/content/harness-agents.mdx

@@ -329,7 +329,7 @@ you do.
 When a harness pauses for approval it emits an `approval-request` event and the
 session is marked `idle` with the pending approval recorded, so the UI can
 surface it and resume on the user's decision. See
-[Human Approval](/docs/human-approval) for the approval surface.
+[Human Approval](/docs/actions-access-control#needs-approval) for the approval surface.
 
 ## Events {#events}
 
@@ -419,4 +419,4 @@ one implementation of this contract, not the public abstraction.
 - [Agent-Native Code UI](/docs/code-agents-ui) — the reusable coding workspace surface.
 - [Custom Agents & Teams](/docs/agent-teams) — background runs and sub-agent delegation.
 - [Sandbox Adapters](/docs/sandbox-adapters) — pluggable execution backends for coding harnesses.
-- [Human Approval](/docs/human-approval) — the approval surface harness runs use.
+- [Human Approval](/docs/actions-access-control#needs-approval) — the approval surface harness runs use.

package/docs/content/internationalization.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Internationalization"
-description: "Localize Agent Native apps with shared locale catalogs, a language picker, browser-language fallback, and locale-aware docs content."
+description: "Localize Agent Native apps with shared locale catalogs, a language picker, and browser-language fallback."
 ---
 
 # Internationalization
@@ -41,88 +41,78 @@ resolved locale/catalog into that script to avoid hydration mismatches.
 Each localized template keeps catalogs under `app/i18n/`:
 
 ```ts filename="app/i18n/index.ts"
+import { createAgentNativeI18nCatalog } from "@agent-native/core/client/i18n";
 import enUS from "./en-US";
-import type { AgentNativeI18nCatalog } from "@agent-native/core/client/i18n";
-export const i18nCatalog = {
-  sourceLocale: "en-US",
+
+export const i18nCatalog = createAgentNativeI18nCatalog({
   messages: enUS,
-  loadMessages: async (locale) => {
-    switch (locale) {
-      case "zh-CN":
-        return (await import("./zh-CN")).default;
-      default:
-        return null;
-    }
+  localeLoaders: {
+    "zh-CN": () => import("./zh-CN"),
+    "zh-TW": () => import("./zh-TW"),
+    "es-ES": () => import("./es-ES"),
+    "fr-FR": () => import("./fr-FR"),
+    "de-DE": () => import("./de-DE"),
+    "ja-JP": () => import("./ja-JP"),
+    "ko-KR": () => import("./ko-KR"),
+    "pt-BR": () => import("./pt-BR"),
+    "hi-IN": () => import("./hi-IN"),
+    "ar-SA": () => import("./ar-SA"),
   },
-} satisfies AgentNativeI18nCatalog;
+});
 ```
 
-Always bundle `en-US`. Dynamic-import non-English catalogs so users only
-download the active locale. The supported locale codes are `en-US`, `zh-CN`,
-`zh-TW`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, and
-`ar-SA`.
+`messages` bundles `en-US` directly so it is always available before any
+locale loads. `localeLoaders` dynamic-imports every other catalog so users
+only download the active locale. The supported locale codes are `en-US`,
+`zh-CN`, `zh-TW`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`,
+`hi-IN`, and `ar-SA`.
+
+This list is fixed by the framework. It is not just what this example
+happens to bundle. `LocaleCode` is a TypeScript union of exactly these
+codes, and `set-localization-preference` rejects anything else at runtime.
+Each locale also needs framework-curated metadata, such as text direction
+for right-to-left languages. Adding a new locale means extending the
+framework itself, not adding a catalog file to your app.
+
+`createAgentNativeI18nCatalog` also accepts an optional `sourceLocale`,
+which defaults to `en-US`, and an optional `supportedLocales` array. Set
+`supportedLocales` when an app ships translations for only some of the
+framework's locales instead of all ten. It defaults to every locale the
+framework supports. `LanguagePicker` only lists locales in this set, and any
+detected or requested locale outside it falls back to `sourceLocale`.
 
 ## UI
 
-Use `useT()` for interface strings and put `<LanguagePicker />` on the app's
-`/settings` page. Sidebar apps should expose **Settings** in the app sidebar;
-the header language icon is only a shortcut.
+Use `useT()` to translate interface strings:
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client/i18n";
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-function SettingsPage() {
+import { useT } from "@agent-native/core/client/i18n";
+
+function Greeting({ name }: { name: string }) {
   const t = useT();
-  return (
-    <>
-      <h2>{t("settings.languageTitle")}</h2>
-      <LanguagePicker label={t("settings.languageLabel")} />
-
-      <h2>{t("settings.agentTitle")}</h2>
-      <p>{t("settings.agentDescription")}</p>
-      <button type="button" onClick={() => openAgentSettings()}>
-        {t("settings.openAgentSettings")}
-      </button>
-    </>
-  );
+  return <p>{t("greeting.hello", { name })}</p>;
 }
 ```
 
-The "Agent settings" control should open the right agent sidebar's Settings tab
-for model, API key, automation, voice, and other framework-level controls.
-Apps may duplicate high-value framework settings in their own settings page
-when the setting is central to the app, but the sidebar settings tab remains the
-source of truth.
-
 Use `useFormatters()` for dates, numbers, relative time, and lists. Do not put
 locale-sensitive date/number formatting inside translation strings.
 
-## Docs Site Content {#docs-site-content}
-
-Public docs pages use the same core provider, but with
-`persistPreference={false}` so anonymous docs traffic uses localStorage and the
-browser language instead of SQL settings actions. The English source remains in
-`packages/core/docs/content/*.mdx`. Localized page overrides live next to it under
-`packages/core/docs/content/locales/<locale>/<slug>.mdx`.
-
-Use the same BCP-47 locale codes as app catalogs. Keep the same slug as the
-English source, preserve stable anchors with `{#anchor}` on translated headings,
-and leave routes, action names, protocol fields, env vars, and provider names
-untranslated. If a locale has no translated Markdown for a page, the docs site
-falls back to English for that page while still localizing navigation and chrome.
-
-Docs Markdown may include structured `an-*` visual blocks. Translate their
-user-facing prose fields where it makes sense, such as file-tree titles and
-`entries[].note`, callout bodies, tab labels, and annotated-code labels/notes.
-Keep stable identifiers unchanged: filenames, paths, env vars, route strings,
-action names, language tags, code snippets, JSON keys, and protocol names.
+Put `<LanguagePicker />` wherever the app lets a user change their language.
+See [Toolkit: Settings](/docs/toolkit-settings) for the standard settings
+page pattern, including where `openAgentSettings()` fits in.
 
 ## Actions And Persistence
 
 Every app inherits:
 
-- `get-localization-preference` — read the current user's `{ locale }`
-- `set-localization-preference` — set `"system"` or a supported locale
+- `get-localization-preference` — read the current user's `{ locale, timezone }`
+- `set-localization-preference` — set `locale` and/or `timezone`, each optional
+
+`locale` is `"system"` or a supported BCP-47 locale. `timezone` is `"system"`
+or an IANA zone such as `America/New_York`. It exists so scheduled and
+automation work runs in the user's zone instead of the host's. Setting only
+one field leaves the other unchanged, because `set-localization-preference`
+merges onto the existing stored value instead of overwriting it.
 
 The durable value lives in user-scoped SQL settings under `localization`.
 `localStorage` is only used for pre-hydration and anonymous fallback. The active
@@ -137,10 +127,16 @@ Run:
 pnpm guard:i18n-catalogs
 ```
 
-The guard verifies supported locale filenames, key parity, placeholder parity,
-stale keys, and CLDR plural categories through `Intl.PluralRules`. It checks
-structure, not translation quality; high-visibility strings still need human
-review.
+For app and template catalogs, the guard checks:
+
+- Locale filenames, key parity, placeholder parity, and stale keys
+- Duplicate keys and leftover development-only markers
+- Wrong-script contamination, for example Chinese text inside an Arabic catalog
+- CLDR plural categories through `Intl.PluralRules`
+- `t()` calls in app source whose key is missing from the English catalog
+
+The guard checks structure, not translation quality. High-visibility strings
+still need human review.
 
 Do not translate stable identifiers such as action names, routes, enum values,
 app-state keys, database values, protocol fields, env var names, or provider

package/docs/content/key-concepts.mdx

@@ -170,7 +170,7 @@ Adopting the framework is valuable mostly because of what you stop having to bui
 
 ## Data in SQL {#data-in-sql}
 
-All application state lives in a SQL database via Drizzle ORM. Schemas are provider-agnostic; the supported databases, `DATABASE_URL` config, and portability rules live in [Database](/docs/database).
+All application state lives in a SQL database via Drizzle ORM. Schemas are provider-agnostic; the supported databases, `DATABASE_URL` config, and portability rules live in [Database](/docs/server-database).
 
 Core SQL stores are auto-created and available in every template:
 
@@ -295,7 +295,7 @@ should also expose scoped `db-exec` / `db-patch`; set `database: "off"` /
 sharing, review comments, version history, feature flags, localization, audit,
 context X-Ray, profile, automations, docs, resources, web, cross-app delegation,
 chat, and email. See
-[Production Agent Tools](/docs/deployment#production-agent-tools) for the full
+[Production Agent Tools](/docs/actions-agent-tools#production-agent-tools) for the full
 list, the `"minimal"` preset, and why disabling a group leaves its HTTP routes
 mounted.
 
@@ -484,7 +484,7 @@ without source changes, use [Extensions](/docs/extensions).
 
 Two architectural rules keep apps portable across databases and hosts:
 
-- **Database-agnostic.** Write schemas with `@agent-native/core/db/schema` and reads/writes with Drizzle's portable query DSL so the same code runs on any supported provider. Use raw SQL only for additive migrations or one-off maintenance, kept parameterized and dialect-agnostic. See [Database](/docs/database).
+- **Database-agnostic.** Write schemas with `@agent-native/core/db/schema` and reads/writes with Drizzle's portable query DSL so the same code runs on any supported provider. Use raw SQL only for additive migrations or one-off maintenance, kept parameterized and dialect-agnostic. See [Database](/docs/server-database).
 - **Hosting-agnostic.** The server runs on Nitro and compiles to any deployment target. Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins, and never assume a persistent server process. Serverless and edge are stateless, so keep all state in SQL. See [Deployment](/docs/deployment).
 
 ## Agent Resources {#workspace}

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

@@ -286,10 +286,10 @@ Brand colors, typography, spacing scales, and any shared component classes can l
 
 ## Deployment {#deployment}
 
-You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy. [Deployment — Workspace Deploy](/docs/deployment#workspace-deploy) covers the full command, per-preset details (Cloudflare, Netlify, Vercel), and a diagram of the shape; the tradeoff:
+You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy. [Workspace Deployment — One Origin, Many Apps](/docs/workspace-deployment#workspace-deploy) covers the full command, per-preset details (Cloudflare, Netlify, Vercel), and a diagram of the shape; the tradeoff:
 
 - **Unified deploy (recommended)** — `npx @agent-native/core@latest deploy` builds every app in the workspace and ships them behind a single origin, one path per app (`your-agents.com/mail/*`, `/calendar/*`, ...). Being on the same origin is where the real payoff lives: a shared login session (log into any app, every app is logged in), zero-config cross-app A2A (`@mail` tagging `@calendar` is a same-origin fetch — no CORS, no JWT signing between siblings), and one DNS record, cert, and CDN cache to manage.
-- **Per-app independent deploy** — prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it. For a self-hosted VPS or Docker Compose setup on one origin instead, see [Deployment — Self-hosted workspace with Docker Compose](/docs/deployment#workspace-docker-compose).
+- **Per-app independent deploy** — prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it. For a self-hosted VPS or Docker Compose setup on one origin instead, see [Workspace Deployment — Self-hosted Workspace with Docker Compose](/docs/workspace-deployment#workspace-docker-compose).
 
 Whichever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. The shared package itself is never deployed standalone — pnpm symlinks it into each app's `node_modules/` at build time.