@agent-native/core 0.163.0 → 0.163.2

package/dist/collab/storage.d.ts

@@ -18,6 +18,8 @@ export declare function trySaveYDocState(docId: string, state: Uint8Array, textS
 export declare function saveYDocState(docId: string, state: Uint8Array, textSnapshot: string): Promise<void>;
 /** Check if a document has collaborative state. */
 export declare function hasCollabState(docId: string): Promise<boolean>;
+/** Load all existing document ids in one query for startup reconciliation. */
+export declare function listCollabDocIds(): Promise<Set<string>>;
 /** Delete collaborative state for a document. */
 export declare function deleteCollabState(docId: string): Promise<void>;
 declare function uint8ArrayToBase64(arr: Uint8Array): string;

package/dist/collab/storage.js

@@ -148,6 +148,13 @@ export async function hasCollabState(docId) {
     });
     return rows.length > 0;
 }
+/** Load all existing document ids in one query for startup reconciliation. */
+export async function listCollabDocIds() {
+    await ensureTable();
+    const client = getDbExec();
+    const { rows } = await client.execute("SELECT doc_id FROM _collab_docs");
+    return new Set(rows.flatMap((row) => typeof row.doc_id === "string" && row.doc_id ? [row.doc_id] : []));
+}
 /** Delete collaborative state for a document. */
 export async function deleteCollabState(docId) {
     await ensureTable();

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/config.js

@@ -374,14 +374,24 @@ export function isAgentNativeDeploymentEnvironment(value) {
  * never parses process.env itself.
  */
 export function inferAgentNativeDeploymentEnvironment(env, mode) {
+    const explicit = env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT?.trim().toLowerCase();
+    if (explicit && !isAgentNativeDeploymentEnvironment(explicit)) {
+        throw new Error('AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT must be "local", "beta", "production", or "preview"');
+    }
+    if (isAgentNativeDeploymentEnvironment(explicit))
+        return explicit;
     const context = env.CONTEXT?.trim().toLowerCase();
     const branch = env.BRANCH?.trim().toLowerCase();
-    if (branch === "production" || context === "production") {
+    const vercelEnv = env.VERCEL_ENV?.trim().toLowerCase();
+    if (branch === "production" ||
+        (context === "production" && branch !== "beta")) {
         return "production";
     }
     if (branch === "beta" || (context === "branch-deploy" && branch === "main")) {
         return "beta";
     }
+    if (vercelEnv === "preview")
+        return "preview";
     if (context === "deploy-preview" ||
         context === "branch-deploy" ||
         branch?.startsWith("deploy-preview")) {

package/dist/deploy/build.d.ts

@@ -337,4 +337,4 @@ export declare function resolveNitroBundledYjsEntry(): string;
  * small set above through the controlled post-build pass.
  */
 export declare function nitroNoExternalsForPreset(targetPreset: string): true | readonly string[];
-export declare function resolveNitroBuildReplacements(env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function resolveNitroBuildReplacements(env?: NodeJS.ProcessEnv, deploymentEnvironment?: string): Record<string, string>;

package/dist/deploy/build.js

@@ -891,6 +891,77 @@ function isTruthyRuntimeValue(value) {
   );
 }
 
+function normalizeExplicitDeploymentEnvironment(value) {
+  const normalized = firstNonEmpty(value)?.toLowerCase();
+  if (!normalized) return;
+  if (
+    normalized !== "local" &&
+    normalized !== "beta" &&
+    normalized !== "production" &&
+    normalized !== "preview"
+  ) {
+    throw new Error(
+      'AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT must be "local", "beta", "production", or "preview"',
+    );
+  }
+  return normalized;
+}
+
+function normalizeFallbackDeploymentEnvironment(value) {
+  const normalized = firstNonEmpty(value)?.toLowerCase();
+  if (normalized === "development" || normalized === "test") return "local";
+  return normalized === "local" ||
+    normalized === "beta" ||
+    normalized === "production" ||
+    normalized === "preview"
+    ? normalized
+    : undefined;
+}
+
+function resolveDeploymentEnvironment() {
+  const env = globalThis.process?.env || {};
+  const explicit = normalizeExplicitDeploymentEnvironment(
+    env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT,
+  );
+  if (explicit) return explicit;
+
+  const context = firstNonEmpty(
+    typeof env.CONTEXT === "string" ? env.CONTEXT : undefined,
+    typeof env.NETLIFY_CONTEXT === "string" ? env.NETLIFY_CONTEXT : undefined,
+    typeof env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT === "string"
+      ? env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT
+      : undefined,
+  )?.toLowerCase();
+  const branch =
+    typeof env.BRANCH === "string" ? env.BRANCH.trim().toLowerCase() : "";
+  const vercelEnv = String(env.VERCEL_ENV || "").trim().toLowerCase();
+  const sentryEnvironment = firstNonEmpty(env.SENTRY_ENVIRONMENT);
+  if (branch === "beta") return "beta";
+  if (
+    branch === "production" ||
+    (context === "production" && branch !== "beta")
+  ) {
+    return "production";
+  }
+  if (context === "branch-deploy" && branch === "main") return "beta";
+  if (
+    context === "deploy-preview" ||
+    context === "branch-deploy" ||
+    branch.startsWith("deploy-preview") ||
+    vercelEnv === "preview"
+  ) {
+    return "preview";
+  }
+  if (!context && !branch && !vercelEnv && sentryEnvironment) {
+    return normalizeFallbackDeploymentEnvironment(sentryEnvironment) || "production";
+  }
+  return (
+    normalizeFallbackDeploymentEnvironment(firstNonEmpty(context, vercelEnv)) ||
+    normalizeFallbackDeploymentEnvironment(env.NODE_ENV) ||
+    "production"
+  );
+}
+
 function getSentryClientConfigScript() {
   const env = globalThis.process?.env || {};
   const key = firstNonEmpty(env.SENTRY_CLIENT_KEY, env.VITE_SENTRY_CLIENT_KEY);
@@ -909,16 +980,15 @@ function getSentryClientConfigScript() {
       env.VITE_SENTRY_DSN,
       env.SENTRY_DSN,
     ) || (key && projectId && host ? "https://" + key + "@" + host + "/" + projectId : undefined);
-  if (!dsn) return null;
+  const deploymentEnvironment = resolveDeploymentEnvironment();
   const config = {
-    sentryDsn: dsn,
-    sentryEnvironment:
-      firstNonEmpty(
-        env.SENTRY_ENVIRONMENT,
-        env.NETLIFY_CONTEXT,
-        env.VERCEL_ENV,
-        env.NODE_ENV,
-      ) || "production",
+    ...(dsn
+      ? {
+          sentryDsn: dsn,
+          sentryEnvironment: deploymentEnvironment,
+        }
+      : {}),
+    deploymentEnvironment,
   };
   return (
     '<script data-agent-native-sentry-config>' +
@@ -3742,7 +3812,9 @@ function createBrowserOnlyServerStubPlugin() {
         },
     };
 }
-export function resolveNitroBuildReplacements(env = process.env) {
+export function resolveNitroBuildReplacements(env = process.env, deploymentEnvironment) {
+    const configuredDeploymentEnvironment = deploymentEnvironment?.trim() ||
+        env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT?.trim();
     return {
         // Netlify exposes DEPLOY_ID only while building. Embed it into the Nitro
         // function so preview OAuth relays can target this immutable deployment
@@ -3755,7 +3827,12 @@ export function resolveNitroBuildReplacements(env = process.env) {
         // a separate server build, so embed release migration ownership here as
         // well as in the Vite server bundle.
         "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
-        "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(env.CONTEXT?.trim() || ""),
+        "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(env.CONTEXT?.trim() || env.NETLIFY_CONTEXT?.trim() || ""),
+        ...(configuredDeploymentEnvironment
+            ? {
+                "process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT": JSON.stringify(configuredDeploymentEnvironment),
+            }
+            : {}),
     };
 }
 async function buildWithNitro() {
@@ -3841,7 +3918,7 @@ export default bundle;
         virtual: {
             "virtual:agents-bundle": agentsBundleModuleSource,
         },
-        replace: resolveNitroBuildReplacements(),
+        replace: resolveNitroBuildReplacements(process.env, nitroAgentConfig.deployment?.environment),
         // Replace browser-only renderers (Excalidraw/Mermaid) with an inert proxy in
         // the server bundle. Without this, Nitro's Rolldown build pulls the real
         // Excalidraw into a shared vendor chunk imported statically by the SSR render

package/dist/file-upload/actions/upload-image.d.ts

@@ -17,11 +17,11 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
-    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
+    error?: undefined;
 }>;
 export default _default;

package/dist/observability/routes.d.ts

@@ -62,6 +62,6 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/observability/tracking-identity.js

@@ -1,3 +1,4 @@
+import { resolveDeployEnvironment } from "../server/deploy-environment.js";
 function normalizeTrackingSlug(value) {
     const raw = value?.trim().toLowerCase();
     if (!raw)
@@ -44,6 +45,7 @@ export function trackingIdentityProperties() {
         normalizeTrackingSlug(process.env.VITE_APP_TEMPLATE) ||
         app;
     return {
+        deployment_environment: resolveDeployEnvironment(),
         ...(app ? { app, agent_native_app: app } : {}),
         ...(template ? { template, agent_native_template: template } : {}),
     };

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/collab-plugin.d.ts

@@ -41,6 +41,8 @@ export interface CollabPluginOptions {
     idColumn?: string;
     /** Whether to auto-seed existing documents on startup. Default: true */
     autoSeed?: boolean;
+    /** Map a source-table id to the id used by the collab document store. */
+    resolveCollabDocumentId?: (sourceId: string) => string;
     /**
      * Callback invoked after a collab update to sync the content column.
      * If not provided, the plugin auto-syncs using table/contentColumn/idColumn.
@@ -78,4 +80,8 @@ export interface CollabPluginOptions {
 }
 export declare function normalizeCollabAccess(options: Pick<CollabPluginOptions, "access" | "resourceType" | "resolveResourceId">): NormalizedCollabAccess;
 export declare function createCollabPlugin(options?: CollabPluginOptions): NitroPluginDef;
+export declare function selectUnseededCollabRows(rows: ReadonlyArray<Record<string, unknown>>, idColumn: string, existingDocIds: ReadonlySet<string>, resolveCollabDocumentId?: (sourceId: string) => string): Array<{
+    row: Record<string, unknown>;
+    docId: string;
+}>;
 export {};

package/dist/server/collab-plugin.js

@@ -16,7 +16,7 @@ import { defineEventHandler, getMethod, setResponseStatus, } from "h3";
 import { postAwareness, getActiveUsers } from "../collab/awareness.js";
 import { getCollabEmitter } from "../collab/emitter.js";
 import { getCollabState, postCollabUpdate, postCollabText, postCollabSearchReplace, } from "../collab/routes.js";
-import { hasCollabState } from "../collab/storage.js";
+import { listCollabDocIds } from "../collab/storage.js";
 import { postCollabJson, getCollabJson, postCollabPatch, } from "../collab/struct-routes.js";
 import { seedFromText, seedFromJson } from "../collab/ydoc-manager.js";
 import { getDbExec } from "../db/client.js";
@@ -82,6 +82,7 @@ function warnForImplicitAllAuthenticatedAccess(table) {
 export function createCollabPlugin(options = {}) {
     const normalizedAccess = normalizeCollabAccess(options);
     const { table = "documents", contentColumn = "content", idColumn = "id", autoSeed = true, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, } = options;
+    const resolveCollabDocumentId = options.resolveCollabDocumentId ?? ((sourceId) => sourceId);
     const resourceType = normalizedAccess.mode === "resource"
         ? normalizedAccess.resourceType
         : undefined;
@@ -308,13 +309,14 @@ export function createCollabPlugin(options = {}) {
             // Run in background so it doesn't block startup
             setTimeout(async () => {
                 try {
+                    // Read existing ids once, then apply the plugin's document-id
+                    // mapping before filtering. A source-table SQL predicate can use
+                    // the wrong id for integrations such as Analytics' dash-* docs.
+                    const existingDocIds = await listCollabDocIds();
                     const client = getDbExec();
                     const { rows } = await client.execute(`SELECT ${idColumn}, ${seedColumn} FROM ${table}`);
-                    for (const row of rows) {
-                        const docId = row[idColumn];
-                        const exists = await hasCollabState(docId);
-                        if (exists)
-                            continue;
+                    for (const { row, docId } of selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId)) {
+                        let seeded = false;
                         if (isJson) {
                             const raw = row[seedColumn] ?? "{}";
                             try {
@@ -323,6 +325,7 @@ export function createCollabPlugin(options = {}) {
                                     ? "array"
                                     : "map";
                                 await seedFromJson(docId, parsed, "data", inferredType);
+                                seeded = true;
                             }
                             catch {
                                 // Invalid JSON — skip
@@ -331,7 +334,10 @@ export function createCollabPlugin(options = {}) {
                         else {
                             const content = row[seedColumn] ?? "";
                             await seedFromText(docId, content);
+                            seeded = true;
                         }
+                        if (seeded)
+                            existingDocIds.add(docId);
                     }
                 }
                 catch {
@@ -341,3 +347,18 @@ export function createCollabPlugin(options = {}) {
         }
     };
 }
+export function selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId = (sourceId) => sourceId) {
+    const seenDocIds = new Set(existingDocIds);
+    const unseeded = [];
+    for (const row of rows) {
+        const sourceId = String(row[idColumn] ?? "");
+        if (!sourceId)
+            continue;
+        const docId = resolveCollabDocumentId(sourceId);
+        if (seenDocIds.has(docId))
+            continue;
+        seenDocIds.add(docId);
+        unseeded.push({ row, docId });
+    }
+    return unseeded;
+}

package/dist/server/deploy-environment.d.ts

@@ -5,7 +5,7 @@
  * not the vendor, and a second backend that reports errors without them
  * produces issues nobody can tie to a release.
  */
-/** The deploy environment name, e.g. `production`, `deploy-preview`. */
+/** The deploy environment name, e.g. `production`, `beta`, or `preview`. */
 export declare function resolveDeployEnvironment(): string;
 /**
  * Resolve the agent-native version baked into core's package.json so the

package/dist/server/deploy-environment.js

@@ -8,6 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isAgentNativeDeploymentEnvironment } from "../config.js";
 function firstNonEmpty(...values) {
     for (const value of values) {
         const trimmed = value?.trim();
@@ -16,9 +17,46 @@ function firstNonEmpty(...values) {
     }
     return undefined;
 }
-/** The deploy environment name, e.g. `production`, `deploy-preview`. */
+function normalizeFallbackEnvironment(value) {
+    const normalized = firstNonEmpty(value)?.toLowerCase();
+    if (normalized === "development" || normalized === "test")
+        return "local";
+    return isAgentNativeDeploymentEnvironment(normalized)
+        ? normalized
+        : undefined;
+}
+/** The deploy environment name, e.g. `production`, `beta`, or `preview`. */
 export function resolveDeployEnvironment() {
-    return (firstNonEmpty(process.env.SENTRY_ENVIRONMENT, process.env.NETLIFY_CONTEXT, process.env.VERCEL_ENV, process.env.NODE_ENV) ?? "production");
+    const explicit = firstNonEmpty(process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT)?.toLowerCase();
+    if (explicit) {
+        if (!isAgentNativeDeploymentEnvironment(explicit)) {
+            throw new Error('AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT must be "local", "beta", "production", or "preview"');
+        }
+        return explicit;
+    }
+    const context = firstNonEmpty(process.env.CONTEXT, process.env.NETLIFY_CONTEXT, process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT)?.toLowerCase();
+    const branch = process.env.BRANCH?.trim().toLowerCase();
+    const vercelEnv = process.env.VERCEL_ENV?.trim().toLowerCase();
+    if (branch === "beta")
+        return "beta";
+    if (branch === "production" ||
+        (context === "production" && branch !== "beta")) {
+        return "production";
+    }
+    if (context === "branch-deploy" && branch === "main")
+        return "beta";
+    if (context === "deploy-preview" ||
+        context === "branch-deploy" ||
+        branch?.startsWith("deploy-preview") ||
+        vercelEnv === "preview") {
+        return "preview";
+    }
+    if (!context && !branch && !vercelEnv) {
+        return (normalizeFallbackEnvironment(firstNonEmpty(process.env.SENTRY_ENVIRONMENT, process.env.NODE_ENV)) ?? "production");
+    }
+    return (normalizeFallbackEnvironment(firstNonEmpty(context, vercelEnv)) ??
+        normalizeFallbackEnvironment(process.env.NODE_ENV) ??
+        "production");
 }
 /**
  * Resolve the agent-native version baked into core's package.json so the

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/sentry-config.js

@@ -28,11 +28,15 @@ export function resolvePublicSentryDsn() {
 }
 export function getSentryClientConfigScript() {
     const dsn = resolvePublicSentryDsn();
-    if (!dsn)
-        return null;
+    const deploymentEnvironment = resolveDeployEnvironment();
     const config = {
-        sentryDsn: dsn,
-        sentryEnvironment: resolveSentryEnvironment(),
+        ...(dsn
+            ? {
+                sentryDsn: dsn,
+                sentryEnvironment: resolveSentryEnvironment(),
+            }
+            : {}),
+        deploymentEnvironment,
     };
     return [
         "<script data-agent-native-sentry-config>",

package/dist/server/sentry.js

@@ -62,6 +62,10 @@ export function initServerSentry() {
         // cookies, or process.env contents to Sentry without explicit consent.
         sendDefaultPii: false,
         beforeSend(event) {
+            event.tags = {
+                ...event.tags,
+                deployment_environment: resolveDeployEnvironment(),
+            };
             // Drop rules live in `error-noise-filter.ts` so every backend applies
             // the same ones — they describe which server errors are non-bugs in
             // this framework, not a Sentry preference.

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

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

package/dist/tracking/registry.js

@@ -1,3 +1,4 @@
+import { resolveDeployEnvironment } from "../server/deploy-environment.js";
 import { getRequestContext } from "../server/request-context.js";
 import { ANALYTICS_CLIENT_PLATFORM_PROPERTY } from "../shared/analytics-platform.js";
 const REGISTRY_KEY = Symbol.for("@agent-native/core/tracking.registry");
@@ -46,12 +47,13 @@ function resolveTrackingSource(source) {
 export function track(name, properties, source) {
     const { userId, anonymousId, sessionId } = resolveTrackingSource(source);
     const clientPlatform = getRequestContext()?.clientPlatform;
-    const trackedProperties = clientPlatform
-        ? {
-            ...(properties ?? {}),
-            [ANALYTICS_CLIENT_PLATFORM_PROPERTY]: clientPlatform,
-        }
-        : properties;
+    const trackedProperties = {
+        ...(properties ?? {}),
+        deployment_environment: resolveDeployEnvironment(),
+        ...(clientPlatform
+            ? { [ANALYTICS_CLIENT_PLATFORM_PROPERTY]: clientPlatform }
+            : {}),
+    };
     const event = {
         name,
         properties: trackedProperties,

package/dist/vite/client.js

@@ -2913,6 +2913,11 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
             // netlify.toml environment is available to the build but not injected
             // into deployed Functions, so embed the decision in the server bundle.
             "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(process.env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
+            ...(resolvedAppConfig.deployment?.environment
+                ? {
+                    "process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT": JSON.stringify(resolvedAppConfig.deployment.environment),
+                }
+                : {}),
             __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
             "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
             // Framework route warmup controls how SSR `.data` routes are fetched:

package/docs/content/deployment.mdx

@@ -26,11 +26,11 @@ pnpm install
 
 The install step creates the lockfile that the production Dockerfile below copies into its build stage.
 
-### 2. Add a local Compose file
+### 2. Add the local Docker files
 
-Create `docker-compose.yml` in the app root. It uses the [Dockerfile](#docker) in the next section and starts Postgres only on the private Compose network:
+Create `Dockerfile`, `.dockerignore`, and `docker-compose.yml` in the app root. `docker compose up --build` needs the Dockerfile, and `.dockerignore` keeps host-only files such as `node_modules` out of the Linux build context. Compose starts Postgres only on the private Compose network.
 
-You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture.
+You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [.dockerignore](https://www.agent-native.com/examples/self-hosted-chat/.dockerignore), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture. The [Dockerfile](#docker) below matches the fixture.
 
 ```yaml filename="docker-compose.yml" maxLines=40
 services:
@@ -53,7 +53,7 @@ services:
       POSTGRES_USER: agent_native
       POSTGRES_HOST_AUTH_METHOD: trust
     volumes:
-      - postgres-data:/var/lib/postgresql
+      - postgres-data-v18:/var/lib/postgresql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U agent_native -d agent_native"]
       interval: 5s
@@ -61,9 +61,11 @@ services:
       retries: 10
 
 volumes:
-  postgres-data:
+  postgres-data-v18:
 ```
 
+PostgreSQL 18 uses `/var/lib/postgresql` as its volume mount path, unlike PostgreSQL 17 and earlier. The versioned volume name keeps this fresh fixture separate from older local stacks. If you are upgrading an existing PostgreSQL 17 or earlier stack, back up and migrate its data before changing the image or mount path. Do not point this fixture at the old volume without a migration.
+
 ### 3. Run it
 
 ```bash
@@ -322,6 +324,18 @@ EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]
 ```
 
+Create `.dockerignore` alongside the Dockerfile:
+
+```text filename=".dockerignore"
+node_modules
+.output
+data
+.env
+.env.*
+!.env.example
+.git
+```
+
 ### Self-hosted workspace with Docker Compose {#workspace-docker-compose}
 
 The Dockerfile above is for one standalone app. A workspace is not one Nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.163.0",
+  "version": "0.163.2",
   "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": {