@agent-native/core 0.0.0-beta-20260820224008 → 0.0.0-beta-20260820231735

package/corpus/templates/brain/actions/list-sources.ts

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import { nextBrainSourceSyncAt } from "../server/jobs/sync-sources.js";
 import { listAccessibleAudienceIds } from "../server/lib/audiences.js";
+import { sourceHealthState } from "../server/lib/brain-health.js";
 import { parseJson, serializeSource } from "../server/lib/brain.js";
 import { sourceProviderSchema } from "./_schemas.js";
 
@@ -71,14 +72,23 @@ export default defineAction({
       .from(schema.brainSources)
       .where(and(...clauses))
       .orderBy(desc(schema.brainSources.updatedAt));
+    const nowMs = Date.now();
     const sources = await Promise.all(
-      rows.map(async (row) => ({
-        ...serializeSource(row),
-        recordCount: await sourceRecordCount(row.id),
-        latestRun: await latestRun(row.id),
-        nextSyncAt: nextBrainSourceSyncAt(row),
-      })),
+      rows.map(async (row) => {
+        const latest = await latestRun(row.id);
+        const nextSyncAt = nextBrainSourceSyncAt(row);
+        return {
+          ...serializeSource(row),
+          recordCount: await sourceRecordCount(row.id),
+          latestRun: latest,
+          nextSyncAt,
+          health: sourceHealthState(row, latest, nextSyncAt, nowMs),
+        };
+      }),
     );
-    return { count: rows.length, sources };
+    return {
+      count: rows.length,
+      sources,
+    };
   },
 });

package/corpus/templates/brain/app/components/brain/Surface.tsx

@@ -117,7 +117,8 @@ export function StatusBadge({ status }: { status: string }) {
       ? IconCircleCheck
       : normalized.includes("review") ||
           normalized.includes("degraded") ||
-          normalized.includes("stale")
+          normalized.includes("stale") ||
+          normalized.includes("needs")
         ? IconClock
         : normalized.includes("error")
           ? IconAlertTriangle
@@ -132,7 +133,8 @@ export function StatusBadge({ status }: { status: string }) {
           "border-border bg-secondary text-secondary-foreground",
         (normalized.includes("review") ||
           normalized.includes("degraded") ||
-          normalized.includes("stale")) &&
+          normalized.includes("stale") ||
+          normalized.includes("needs")) &&
           "border-amber-500/35 bg-amber-500/10 text-amber-700 dark:text-amber-300",
         normalized.includes("error") &&
           "border-destructive/35 bg-destructive/10 text-destructive",

package/corpus/templates/brain/app/lib/brain.ts

@@ -20,7 +20,14 @@ export type BrainView =
   | "settings";
 
 export type KnowledgeStatus = "approved" | "needs_review" | "draft" | "stale";
-export type SourceHealth = "healthy" | "degraded" | "paused" | "error";
+export type SourceHealth =
+  | "healthy"
+  | "needs_setup"
+  | "needs_sync"
+  | "stale"
+  | "degraded"
+  | "paused"
+  | "error";
 export type ReviewPriority = "high" | "medium" | "low";
 
 export interface Citation {
@@ -1144,8 +1151,11 @@ export function sourceDescription(source: BrainSource) {
 export function sourceHealth(source: BrainSource): SourceHealth {
   if (source.health) return source.health;
   if (sourceRetryAfter(source)) return "degraded";
-  if (source.status === "active")
-    return source.lastError ? "degraded" : "healthy";
+  if (source.status === "active") {
+    if (source.lastError) return "degraded";
+    if (sourceAutoSync(source) && !source.lastSyncedAt) return "needs_sync";
+    return "healthy";
+  }
   if (source.status === "error") return "error";
   if (source.status === "paused" || source.status === "archived")
     return "paused";

package/corpus/templates/brain/server/lib/brain-health.ts

@@ -189,9 +189,9 @@ function latestIso(values: Array<string | null | undefined>) {
   return latest;
 }
 
-function sourceHealthState(
+export function sourceHealthState(
   source: SourceRow,
-  latestRun: SyncRunRow | null,
+  latestRun: Pick<SyncRunRow, "status"> | null,
   nextSyncAt: string | null,
   nowMs: number,
 ): BrainSourceHealthState {
@@ -530,12 +530,9 @@ export async function readBrainHealth() {
     };
   });
 
-  const sourceHealthCounts = countStatuses<
-    BrainSourceHealthState | "active" | "paused" | "error"
-  >([
-    ...sourceSummaries.map((source) => ({ status: source.health })),
-    ...sourceRows.map((source) => ({ status: source.status })),
-  ]);
+  const sourceHealthCounts = countStatuses<BrainSourceHealthState>(
+    sourceSummaries.map((source) => ({ status: source.health })),
+  );
   const captureCounts = countStatuses(captureRows);
   const captureDispositionCounts = countStatuses(
     captureRows.map((capture) => ({

package/corpus/templates/brain/server/lib/brain.ts

@@ -755,6 +755,7 @@ export async function createCapture(values: {
       title: source.title,
       provider: source.provider as BrainSourceProvider,
       ownerEmail: source.ownerEmail,
+      orgId: source.orgId,
     },
     sourceConfig: parseJson<Record<string, unknown>>(source.configJson, {}),
     settings,

package/corpus/templates/brain/server/lib/capture-sanitization.ts

@@ -71,6 +71,7 @@ export interface CaptureSanitizationInput {
     title: string;
     provider: BrainSourceProvider;
     ownerEmail: string;
+    orgId?: string | null;
   };
   sourceConfig?: Record<string, unknown>;
   settings: BrainSettings;
@@ -440,6 +441,10 @@ async function classifyWithApprovedModel(
     apiKeyEnvVar: userApiKey.apiKeyEnvVar,
     appId: "brain",
     engineOption: engineName,
+    credentialIdentity: {
+      userEmail: input.source.ownerEmail,
+      orgId: input.source.orgId ?? undefined,
+    },
   });
 
   const maxChars = Math.min(

package/corpus/templates/brain/server/routes/api/brain/queue/run.post.ts

@@ -10,7 +10,8 @@ declare global {
   var __AGENT_NATIVE_BRAIN_SCHEDULED_RUNTIME__: boolean | undefined;
 }
 
-export const BRAIN_QUEUE_SWEEP_LIMIT = 10;
+export const BRAIN_QUEUE_SWEEP_LIMIT = 25;
+export const BRAIN_MAX_DISTILLATIONS_PER_SWEEP = 2;
 
 function productionLike() {
   return (
@@ -53,7 +54,7 @@ export default defineEventHandler(async (event) => {
     processBrainIngestQueueOnce({
       limit: BRAIN_QUEUE_SWEEP_LIMIT,
       runDistillation: true,
-      maxDistillations: 1,
+      maxDistillations: BRAIN_MAX_DISTILLATIONS_PER_SWEEP,
     }),
     expireSensitivityQuarantines(),
   ]);

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/config.d.ts

@@ -113,7 +113,9 @@ export declare function agentNativeConfigEnvName(path: readonly string[]): strin
  */
 export declare function readAgentNativeConfigEnv(env: Record<string, string | undefined>): AgentNativeConfig;
 export declare function normalizeAgentNativeConfig(input: unknown, source?: string): AgentNativeConfig;
-export declare function mergeAgentNativeConfigs(base: AgentNativeConfig, override: AgentNativeConfig): AgentNativeConfig;
+export declare function mergeAgentNativeConfigs(base: AgentNativeConfig, override: AgentNativeConfig, options?: {
+    arrayStrategy?: "merge" | "replace";
+}): AgentNativeConfig;
 export declare function resolveAgentNativeConfig(input: AgentNativeConfigInput | undefined, context: AgentNativeConfigContext): AgentNativeConfig;
 export declare function resolveFirstRunOnboardingMode(setting: AgentNativeFirstRunOnboardingSetting, context: AgentNativeConfigContext): AgentNativeFirstRunOnboardingMode;
 export declare function isAgentNativeDeploymentEnvironment(value: unknown): value is AgentNativeDeploymentEnvironment;

package/dist/config.js

@@ -315,7 +315,8 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     }
     return normalized;
 }
-export function mergeAgentNativeConfigs(base, override) {
+export function mergeAgentNativeConfigs(base, override, options = {}) {
+    const arrayStrategy = options.arrayStrategy ?? "merge";
     return {
         ...(base.version === undefined && override.version === undefined
             ? {}
@@ -348,7 +349,7 @@ export function mergeAgentNativeConfigs(base, override) {
                     ? {
                         ...base.runtime?.environment,
                         ...override.runtime?.environment,
-                        required: mergeStringLists(base.runtime?.environment?.required, override.runtime?.environment?.required),
+                        required: mergeStringLists(base.runtime?.environment?.required, override.runtime?.environment?.required, arrayStrategy),
                     }
                     : undefined,
             }
@@ -390,7 +391,7 @@ export function mergeAgentNativeConfigs(base, override) {
                 ...override.changelog,
             }
             : undefined,
-        harness: mergeHarnessSettings(base.harness, override.harness),
+        harness: mergeHarnessSettings(base.harness, override.harness, arrayStrategy),
     };
 }
 export function resolveAgentNativeConfig(input, context) {
@@ -551,7 +552,7 @@ function normalizeHarnessConfig(value, source) {
             : { runtimes: [...new Set(runtimes)] }),
     };
 }
-function mergeHarnessSettings(base, override) {
+function mergeHarnessSettings(base, override, arrayStrategy = "merge") {
     if (override === undefined)
         return base;
     if (typeof override === "boolean")
@@ -563,10 +564,12 @@ function mergeHarnessSettings(base, override) {
     }
     return {
         runtimes: [
-            ...new Set([
-                ...(base.runtimes ?? []),
-                ...(override.runtimes ?? []),
-            ]),
+            ...(arrayStrategy === "replace"
+                ? (override.runtimes ?? base.runtimes ?? [])
+                : new Set([
+                    ...(base.runtimes ?? []),
+                    ...(override.runtimes ?? []),
+                ])),
         ],
     };
 }
@@ -592,9 +595,11 @@ function normalizeRequiredEnvKeys(value, source) {
     }
     return [...new Set(keys)];
 }
-function mergeStringLists(base, override) {
+function mergeStringLists(base, override, arrayStrategy = "merge") {
     if (base === undefined && override === undefined)
         return undefined;
+    if (arrayStrategy === "replace")
+        return override ?? base;
     return [...new Set([...(base ?? []), ...(override ?? [])])];
 }
 function isFirstRunMode(value) {

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,16 +41,16 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
     ok?: undefined;
 } | {
     summary?: undefined;
@@ -59,9 +59,9 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     error: any;
     ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/resources/handlers.d.ts

@@ -51,8 +51,8 @@ export declare function handleDeleteResource(event: any): Promise<{
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -73,10 +73,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
+    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
-    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/vite/agent-native-config-loader.js

@@ -81,7 +81,7 @@ export async function loadResolvedAgentNativeConfig(cwd, context, options = {})
             : await loadAgentNativeConfigFile(cwd));
     return resolveAgentNativeConfig(mergeAgentNativeConfigs(mergeAgentNativeConfigs(mergeAgentNativeConfigs(workspaceConfig
         ? resolveAgentNativeConfig(workspaceConfig, context)
-        : {}, readAgentNativeJsonConfig(cwd)), readAgentNativeConfigEnv(options.environment ?? process.env)), projectConfig ? resolveAgentNativeConfig(projectConfig, context) : {}), context);
+        : {}, readAgentNativeJsonConfig(cwd)), projectConfig ? resolveAgentNativeConfig(projectConfig, context) : {}), readAgentNativeConfigEnv(options.environment ?? process.env), { arrayStrategy: "replace" }), context);
 }
 function findConfigPath(cwd) {
     return AGENT_NATIVE_CONFIG_FILE_CANDIDATES.map((filename) => path.join(cwd, filename)).find((candidate) => fs.existsSync(candidate));

package/dist/vite/client.js

@@ -2806,7 +2806,7 @@ function reportRuntimeConfigDiagnostics(appConfig, context, mode, env = process.
     }
     console.warn(message);
 }
-function createAgentNativeConfig(options = {}, command, userConfig = {}, mode = process.env.NODE_ENV === "production" ? "production" : "development", projectConfig) {
+function createAgentNativeConfig(options = {}, command, userConfig = {}, mode = process.env.NODE_ENV === "production" ? "production" : "development", projectConfig, workspaceConfig) {
     const cwd = process.cwd();
     const configContext = createAgentNativeConfigContext(command, mode);
     const projectConfigInput = projectConfig ?? options.agentNativeConfig;
@@ -2822,9 +2822,11 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
         ...loadEnv(mode, cwd, ""),
         ...process.env,
     };
-    const appConfig = resolveAgentNativeConfig(mergeAgentNativeConfigs(mergeAgentNativeConfigs(readAgentNativeJsonConfig(cwd), readAgentNativeConfigEnv(runtimeEnv)), projectConfigInput
+    const appConfig = resolveAgentNativeConfig(mergeAgentNativeConfigs(mergeAgentNativeConfigs(mergeAgentNativeConfigs(workspaceConfig
+        ? resolveAgentNativeConfig(workspaceConfig, configContext)
+        : {}, readAgentNativeJsonConfig(cwd)), projectConfigInput
         ? resolveAgentNativeConfig(projectConfigInput, configContext)
-        : {}), configContext);
+        : {}), readAgentNativeConfigEnv(runtimeEnv), { arrayStrategy: "replace" }), configContext);
     const inferredDeploymentEnvironment = appConfig.deployment?.environment ??
         inferAgentNativeDeploymentEnvironment(process.env, mode);
     const resolvedAppConfig = appConfig.deployment?.environment === undefined &&
@@ -3139,14 +3141,10 @@ function createAgentNativeConfigPlugin(options) {
         name: "agent-native-config",
         enforce: "pre",
         async config(config, env) {
-            const context = createAgentNativeConfigContext(env.command, env.mode);
             const workspaceConfig = await loadWorkspaceAgentNativeConfigFile(process.cwd());
             const projectConfig = options.agentNativeConfig ??
                 (await loadAgentNativeConfigFile(process.cwd()));
-            const resolvedConfig = mergeAgentNativeConfigs(workspaceConfig
-                ? resolveAgentNativeConfig(workspaceConfig, context)
-                : {}, projectConfig ? resolveAgentNativeConfig(projectConfig, context) : {});
-            return createAgentNativeConfig(options, env.command, config, env.mode, resolvedConfig);
+            return createAgentNativeConfig(options, env.command, config, env.mode, projectConfig, workspaceConfig);
         },
     };
 }

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

@@ -16,13 +16,19 @@ The resolved configuration is serialized into the browser bundle. Treat every
 value in these files as public. Put credentials and deployment-specific values
 in the environment or the scoped secret store instead.
 
-This file is the home for public, app-owned configuration - the values that
-describe how an app should behave or what capabilities it exposes. Prefer it
-for new non-secret app settings. When the same public setting needs a
-deployment-specific value, the framework also accepts a deterministic
-`AGENT_NATIVE_CONFIG*` environment alias. Environment variables still own
-secrets, provider credentials, database URLs, host-specific values, and other
-server-only values that are not part of this public config.
+This file is the primary home for public, app-owned configuration - the values
+that describe how an app should behave or what capabilities it exposes. Put
+the committed default here first. When the same public setting needs a
+deployment-specific value, the framework accepts a deterministic
+`AGENT_NATIVE_CONFIG*` environment alias as the final override. Environment
+variables still own secrets, provider credentials, database URLs, host-specific
+values, and other server-only values that are not part of this public config.
+
+The server-only `defineAppConfig()` schema is a deliberate boundary, not a
+second spelling of this file. It configures behavior that must stay out of the
+browser bundle, such as credential scoping, webhook trust, and workspace
+runtime wiring. Its declared environment aliases are documented separately in
+the maintainer environment inventory.
 
 ## File location and loading
 
@@ -109,13 +115,23 @@ Every supported public config path has an environment alias under the
 `AGENT_NATIVE_CONFIG` namespace. Convert each lower-camel-case path segment to
 upper snake case and join segments with underscores:
 
-| Config path            | Environment alias                          |
-| ---------------------- | ------------------------------------------ |
-| the whole config       | `AGENT_NATIVE_CONFIG`                      |
-| `runtime`              | `AGENT_NATIVE_CONFIG_RUNTIME`              |
-| `runtime.auth`         | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH`         |
-| `runtime.auth.enabled` | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED` |
-| `translations.locales` | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES` |
+| Config path                    | Environment alias                                  |
+| ------------------------------ | -------------------------------------------------- |
+| the whole config               | `AGENT_NATIVE_CONFIG`                              |
+| `onboarding.firstRun`          | `AGENT_NATIVE_CONFIG_ONBOARDING_FIRST_RUN`         |
+| `runtime`                      | `AGENT_NATIVE_CONFIG_RUNTIME`                      |
+| `runtime.auth`                 | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH`                 |
+| `runtime.auth.enabled`         | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED`         |
+| `runtime.database.required`    | `AGENT_NATIVE_CONFIG_RUNTIME_DATABASE_REQUIRED`    |
+| `runtime.environment.required` | `AGENT_NATIVE_CONFIG_RUNTIME_ENVIRONMENT_REQUIRED` |
+| `deployment.environment`       | `AGENT_NATIVE_CONFIG_DEPLOYMENT_ENVIRONMENT`       |
+| `diagnostics.failOnBuild`      | `AGENT_NATIVE_CONFIG_DIAGNOSTICS_FAIL_ON_BUILD`    |
+| `instructions.runtime`         | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_RUNTIME`         |
+| `instructions.development`     | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_DEVELOPMENT`     |
+| `translations.locales`         | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES`         |
+| `changelog.enabled`            | `AGENT_NATIVE_CONFIG_CHANGELOG_ENABLED`            |
+| `harness`                      | `AGENT_NATIVE_CONFIG_HARNESS`                      |
+| `harness.runtimes`             | `AGENT_NATIVE_CONFIG_HARNESS_RUNTIMES`             |
 
 The whole config, an object section, or a deeply nested object can be supplied
 as one JSON string. Arrays also use JSON strings. More-specific aliases are
@@ -148,12 +164,16 @@ scoped secret and connection stores.
 ## Configuration vs environment variables
 
 Use the config file or JSON manifest for stable, non-secret application
-defaults. Use environment variables or the scoped secret store for values that
-belong to a deployment or a user or organization connection:
+defaults. Use the canonical config alias when a public value needs a deployment
+override. Use a separate environment variable or the scoped secret store only
+when the value belongs to a deployment, the server, or a user or organization
+connection:
 
 | Put it in                                                             | Examples                                                                                                           | Notes                                                                                                                                               |
 | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent-native.config.ts` or the shared section of `agent-native.json` | onboarding mode, required runtime contracts, release lane, shipped locales, changelog, hosted harness capabilities | Committed app policy. It is resolved during the Vite config phase and can use `command`, `mode`, `isDev`, and `isBuild`.                            |
+| `agent-native.config.ts` or the shared section of `agent-native.json` | onboarding mode, required runtime contracts, release lane, shipped locales, changelog, hosted harness capabilities | Committed public app policy. It is resolved during the Vite config phase and can use `command`, `mode`, `isDev`, and `isBuild`.                     |
+| `AGENT_NATIVE_CONFIG_<PATH>`                                          | A deployment-specific public override of one config path                                                           | Final override for the typed/JSON public config. Its value is bundled for the browser, so it is never a secret.                                     |
+| Server-only `defineAppConfig()`                                       | credential scoping, webhook trust, agent runtime controls, workspace wiring                                        | Not serialized into the browser. Its declared aliases are the deliberate exception for server behavior.                                             |
 | Deployment environment variables                                      | `DATABASE_URL`, `BETTER_AUTH_SECRET`, `APP_URL`, `NITRO_PRESET`, provider keys, host-specific toggles              | Set by the deployment platform or local `.env`. Keep secret values out of source control. See [Environment Variables](/docs/environment-variables). |
 | `runtime.environment.required`                                        | `"PUBLIC_API_ORIGIN"`, `"STRIPE_PUBLISHABLE_KEY"`                                                                  | A declaration of names the production readiness check must find. It does not set, expose, or replace the values.                                    |
 
@@ -282,26 +302,28 @@ the same setting as the separate `doctor.failOnBuild` option documented in the
 
 ## Precedence and merge behavior
 
-For a Vite app, the effective shared configuration follows this order:
+For a Vite app, the effective public configuration follows this order:
 
 1. Framework defaults. First-run onboarding defaults to `off`; auth and a
    persistent database default to required in production diagnostics.
-2. `agent-native.json` at the app root.
-3. `AGENT_NATIVE_CONFIG` and its path aliases from the deployment environment.
-   The legacy `AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT` variable remains a
-   fallback for deployment inference only; it does not override explicit JSON,
-   typed, or canonical config-alias values.
+2. A workspace-level typed config, when the app is inside a configured
+   workspace.
+3. `agent-native.json` at the app root.
 4. The automatically loaded typed file, if present. The loader checks these
    candidates in order: `agent-native.config.ts`, `agent-native.ts`,
    `agent-native.mts`, `agent-native.config.mts`.
 5. An explicit `agentNativeConfig` passed to `agentNative()` or the legacy
    `defineConfig()` wrapper. Supplying this option skips automatic typed-file
    loading, while the explicit value still overlays `agent-native.json`.
-6. For onboarding only, the legacy public Vite variables
+6. `AGENT_NATIVE_CONFIG` and its path aliases from the deployment environment.
+   These are the final public-config overrides. The legacy
+   `AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT` variable remains a fallback for
+   deployment inference only; it does not override an explicit config value.
+7. For onboarding only, the legacy public Vite variables
    `VITE_AGENT_NATIVE_FIRST_RUN_ONBOARDING` and
    `VITE_AGENT_NATIVE_FIRST_RUN_ONBOARDING_SKIP_INTEGRATIONS` can override the
-   resolved onboarding mode. Use the config file or its canonical path alias
-   for new work.
+   resolved onboarding mode for backwards compatibility. Use the config file
+   or its canonical path alias for new work.
 
 Use only one of the four typed filenames. If more than one exists, the first
 candidate in the loader's order wins, with `agent-native.config.ts` preferred
@@ -319,9 +341,10 @@ The JSON and typed sources are merged by supported nested section:
   supplies it, it replaces the lower-precedence string or mode map as a whole.
 
 For example, JSON can provide `runtime.auth.enabled` and
-`NOTION_API_KEY`, while `agent-native.config.ts` adds `runtime.database.required` and
-`GOOGLE_CLIENT_ID`. The result keeps the auth setting, adds the database
-setting, and checks both environment names.
+`runtime.environment.required: ["NOTION_API_KEY"]`, while
+`agent-native.config.ts` adds `runtime.database.required` and
+`runtime.environment.required: ["GOOGLE_CLIENT_ID"]`. The result keeps the
+auth setting, adds the database setting, and checks both environment names.
 
 ## What is safe to commit
 
@@ -342,8 +365,9 @@ Do not commit these values to either config format:
   vary by environment.
 
 Even a value that is not a secret should stay in deployment configuration when
-it changes between targets. `agent-native.config.ts` should describe the app's
-public shape, not become a second environment-variable file.
+it is a platform fact, a routing detail, or server-only behavior that changes
+between targets. For public app behavior, use the typed config plus its
+canonical deployment alias rather than inventing another standalone variable.
 
 ## `agent-native.json` compatibility
 

package/docs/content/environment-variables.mdx

@@ -12,20 +12,57 @@ 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: 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.
-
-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 standalone environment setting. If a public config value must
-vary by deployment, use its deterministic `AGENT_NATIVE_CONFIG_<PATH>` alias,
-which also becomes part of the public browser bundle. Keep credentials and
-user-, organization-, or workspace-scoped values in the appropriate secret or
-connection store.
-
-## Common application and deployment variables
+For a normal app, start with the [Agent-Native app configuration guide](/docs/agent-native-config),
+then use [Deployment: Environment Variables](/docs/deployment-environment-variables)
+and [Authentication](/docs/authentication) for the deliberate environment-only
+parts. 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, use `agent-native.config.ts` first. If a
+public config value must vary by deployment, use its deterministic
+`AGENT_NATIVE_CONFIG_<PATH>` alias. That alias is the final override of the
+typed/JSON config and also becomes part of the public browser bundle. Do not
+create another standalone Vite-prefixed or Agent-Native-prefixed variable for
+a public setting already represented by the config guide.
+
+## Start with Agent-Native app configuration
+
+The typed config is the primary documentation and default source for public
+app behavior. Its deployment aliases are the standard environment override:
+
+| Config path                    | Deployment override alias                          |
+| ------------------------------ | -------------------------------------------------- |
+| `onboarding.firstRun`          | `AGENT_NATIVE_CONFIG_ONBOARDING_FIRST_RUN`         |
+| `runtime.auth.enabled`         | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED`         |
+| `runtime.database.required`    | `AGENT_NATIVE_CONFIG_RUNTIME_DATABASE_REQUIRED`    |
+| `runtime.environment.required` | `AGENT_NATIVE_CONFIG_RUNTIME_ENVIRONMENT_REQUIRED` |
+| `deployment.environment`       | `AGENT_NATIVE_CONFIG_DEPLOYMENT_ENVIRONMENT`       |
+| `diagnostics.failOnBuild`      | `AGENT_NATIVE_CONFIG_DIAGNOSTICS_FAIL_ON_BUILD`    |
+| `instructions.runtime`         | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_RUNTIME`         |
+| `instructions.development`     | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_DEVELOPMENT`     |
+| `translations.locales`         | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES`         |
+| `changelog.enabled`            | `AGENT_NATIVE_CONFIG_CHANGELOG_ENABLED`            |
+| `harness`                      | `AGENT_NATIVE_CONFIG_HARNESS`                      |
+| `harness.runtimes`             | `AGENT_NATIVE_CONFIG_HARNESS_RUNTIMES`             |
+
+Use [Agent-Native app configuration](/docs/agent-native-config) for the full
+schema, mode-aware examples, JSON fragments, and precedence rules. The
+resolved public config is bundled into the browser, so it must contain only
+non-secret app policy.
+
+Some non-secret environment variables remain deliberate exceptions because
+they configure server-only behavior, platform facts, routing, or deployment
+secrets. Server-only product controls use the framework's `defineAppConfig()`
+schema and its declared aliases; they are not public `agent-native.config.ts`
+fields. The maintainer inventory's generated **Declared app configuration**
+section is the exhaustive list of those server fields and aliases.
+
+## Server, environment-only, and deployment variables
+
+The table below covers values that belong to the running deployment, a
+server-only config surface, or an environment-only compatibility surface. For
+public app behavior, use the config paths above instead.
 
 | Variable                                       | What it controls                                                                                                                                                        | Supported values or format                                                                                              |
 | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.0.0-beta-20260820224008",
+  "version": "0.0.0-beta-20260820231735",
   "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": {