@agent-native/core 0.145.8 → 0.146.1

package/dist/vite/agent-native-config-loader.d.ts

@@ -0,0 +1,10 @@
+import { type AgentNativeConfig, type AgentNativeConfigContext, type AgentNativeConfigInput } from "../config.js";
+/** The canonical filename comes first; the remaining names stay compatible. */
+export declare const AGENT_NATIVE_CONFIG_FILE_CANDIDATES: readonly ["agent-native.config.ts", "agent-native.ts", "agent-native.mts", "agent-native.config.mts"];
+export declare function createAgentNativeConfigContext(command: AgentNativeConfigContext["command"] | undefined, mode: string): AgentNativeConfigContext;
+export declare function readAgentNativeJsonConfig(cwd: string): AgentNativeConfig;
+export declare function loadAgentNativeConfigFile(cwd: string): Promise<AgentNativeConfigInput | undefined>;
+export declare function loadResolvedAgentNativeConfig(cwd: string, context: AgentNativeConfigContext, options?: {
+    loadProjectConfig?: boolean;
+    projectConfig?: AgentNativeConfigInput;
+}): Promise<AgentNativeConfig>;

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

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { mergeAgentNativeConfigs, normalizeAgentNativeConfig, resolveAgentNativeConfig, } from "../config.js";
+/** The canonical filename comes first; the remaining names stay compatible. */
+export const AGENT_NATIVE_CONFIG_FILE_CANDIDATES = [
+    "agent-native.config.ts",
+    "agent-native.ts",
+    "agent-native.mts",
+    "agent-native.config.mts",
+];
+export function createAgentNativeConfigContext(command, mode) {
+    const resolvedCommand = command === "build" ? "build" : "serve";
+    return {
+        command: resolvedCommand,
+        mode,
+        isDev: resolvedCommand === "serve",
+        isBuild: resolvedCommand === "build",
+    };
+}
+export function readAgentNativeJsonConfig(cwd) {
+    const configPath = path.join(cwd, "agent-native.json");
+    if (!fs.existsSync(configPath))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Could not read ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return normalizeAgentNativeConfig(parsed, configPath);
+}
+export async function loadAgentNativeConfigFile(cwd) {
+    const configPath = AGENT_NATIVE_CONFIG_FILE_CANDIDATES.map((filename) => path.join(cwd, filename)).find((candidate) => fs.existsSync(candidate));
+    if (!configPath)
+        return undefined;
+    try {
+        const module = (await import(pathToFileURL(configPath).href));
+        const config = module.default ?? module.agentNativeConfig;
+        if (typeof config !== "object" && typeof config !== "function") {
+            throw new Error("the default export must be an object or function");
+        }
+        return config;
+    }
+    catch (error) {
+        throw new Error(`Could not load ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function loadResolvedAgentNativeConfig(cwd, context, options = {}) {
+    const projectConfig = options.projectConfig ??
+        (options.loadProjectConfig === false
+            ? undefined
+            : await loadAgentNativeConfigFile(cwd));
+    return resolveAgentNativeConfig(mergeAgentNativeConfigs(readAgentNativeJsonConfig(cwd), projectConfig ? resolveAgentNativeConfig(projectConfig, context) : {}), context);
+}

package/dist/vite/agents-bundle-plugin.d.ts

@@ -1,2 +1,6 @@
 import type { Plugin } from "vite";
-export declare function agentsBundlePlugin(): Plugin;
+import type { AgentNativeConfigInput } from "../config.js";
+export interface AgentsBundlePluginOptions {
+    agentNativeConfig?: AgentNativeConfigInput;
+}
+export declare function agentsBundlePlugin(options?: AgentsBundlePluginOptions): Plugin;

package/dist/vite/agents-bundle-plugin.js

@@ -15,7 +15,8 @@ import fs from "fs";
  */
 import path from "path";
 import { getWorkspaceCoreExports } from "../deploy/workspace-core.js";
-import { readAgentsBundleFromFs, } from "../server/agents-bundle.js";
+import { readAgentsBundleFromFs, resolveAgentInstructionPaths, } from "../server/agents-bundle.js";
+import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "./agent-native-config-loader.js";
 const VIRTUAL_ID = "virtual:agents-bundle";
 const RESOLVED_ID = "\0" + VIRTUAL_ID;
 const TEMPLATE_SKILLS_DIRS = [
@@ -33,7 +34,7 @@ const TEMPLATE_SKILLS_DIRS = [
  * reload is batched.
  */
 const FULL_RELOAD_COALESCE_MS = 500;
-async function emitBundleModule(projectRoot) {
+async function emitBundleModule(projectRoot, agentConfig) {
     // If the project is inside an enterprise monorepo with a workspace core,
     // merge in its AGENTS.md + skills. Template skills override workspace
     // core skills on name collision.
@@ -51,7 +52,9 @@ async function emitBundleModule(projectRoot) {
     catch {
         // fall back to template-only
     }
-    const bundle = readAgentsBundleFromFs(projectRoot, workspaceSource);
+    const bundle = readAgentsBundleFromFs(projectRoot, workspaceSource, {
+        instructions: agentConfig.instructions,
+    });
     // Serialize as JSON and wrap in `export default` — this produces a valid
     // ES module that any bundler (Rollup, esbuild, Rolldown) can statically
     // analyze and tree-shake if nothing imports it.
@@ -62,12 +65,17 @@ const bundle = ${JSON.stringify(bundle)};
 export default bundle;
 `;
 }
-export function agentsBundlePlugin() {
+export function agentsBundlePlugin(options = {}) {
     let projectRoot = "";
+    let agentConfigPromise = Promise.resolve({});
     return {
         name: "agent-native-agents-bundle",
-        configResolved(config) {
+        async configResolved(config) {
             projectRoot = config.root;
+            agentConfigPromise = loadResolvedAgentNativeConfig(projectRoot, createAgentNativeConfigContext(config.command, config.mode), {
+                loadProjectConfig: options.agentNativeConfig === undefined,
+                projectConfig: options.agentNativeConfig,
+            });
         },
         resolveId(id) {
             if (id === VIRTUAL_ID)
@@ -79,7 +87,7 @@ export function agentsBundlePlugin() {
                 return null;
             if (!projectRoot)
                 projectRoot = process.cwd();
-            return await emitBundleModule(projectRoot);
+            return await emitBundleModule(projectRoot, await agentConfigPromise);
         },
         async configureServer(server) {
             // Watch AGENTS.md + any SKILL.md changes and invalidate the virtual
@@ -87,6 +95,9 @@ export function agentsBundlePlugin() {
             // the workspace core's AGENTS.md + skills directory (if present)
             // so edits to the enterprise mid-layer propagate to every app.
             const watcher = server.watcher;
+            const agentConfig = await agentConfigPromise;
+            const instructionPaths = resolveAgentInstructionPaths(agentConfig.instructions);
+            const instructionFiles = new Set([instructionPaths.runtime, instructionPaths.development].map((file) => path.resolve(projectRoot, file)));
             // Resolve the workspace core up front so we can tell which files
             // outside projectRoot should trigger invalidation.
             let workspaceAgentsMdPath = null;
@@ -102,6 +113,8 @@ export function agentsBundlePlugin() {
                 // ignore
             }
             const shouldInvalidate = (file) => {
+                if (instructionFiles.has(path.resolve(file)))
+                    return true;
                 const rel = path.relative(projectRoot, file);
                 if (!rel.startsWith("..")) {
                     if (rel === "AGENTS.md")
@@ -158,6 +171,16 @@ export function agentsBundlePlugin() {
                 if (fs.existsSync(skillsDir))
                     watcher.add(skillsDir);
             }
+            for (const instructionFile of instructionFiles) {
+                if (fs.existsSync(instructionFile)) {
+                    watcher.add(instructionFile);
+                }
+                else {
+                    const parent = path.dirname(instructionFile);
+                    if (fs.existsSync(parent))
+                        watcher.add(parent);
+                }
+            }
             if (workspaceAgentsMdPath && fs.existsSync(workspaceAgentsMdPath)) {
                 watcher.add(workspaceAgentsMdPath);
             }

package/dist/vite/client.d.ts

@@ -117,8 +117,10 @@ export interface ClientConfigOptions {
     define?: UserConfig["define"];
     /**
      * Public app behavior from `agent-native.json` or an optional typed
-     * `agent-native.ts` file. Explicit Vite options win over the JSON file,
-     * while the file remains the default project-level source of truth.
+     * `agent-native.config.ts` file. Explicit Vite options win over the JSON
+     * file, while the typed file remains the default project-level source of
+     * truth. `agent-native.ts`, `.mts`, and `agent-native.config.mts` remain
+     * compatibility aliases.
      */
     agentNativeConfig?: AgentNativeConfigInput;
     /**

package/dist/vite/client.js

@@ -2,12 +2,12 @@ import { EventEmitter } from "events";
 import fs from "fs";
 import { createRequire, syncBuiltinESMExports } from "module";
 import path from "path";
-import { fileURLToPath, pathToFileURL } from "url";
+import { fileURLToPath } from "url";
 import { renderDesignSystemThemeCss, } from "@agent-native/toolkit/design-system/theme";
 import { loadEnv, } from "vite";
 import { mergePendingChangelog, parsePendingEntry, } from "../changelog/parse.js";
 import { getViteDevRecoveryScript } from "../client/vite-dev-recovery-script.js";
-import { mergeAgentNativeConfigs, normalizeAgentNativeConfig, resolveAgentNativeConfig, } from "../config.js";
+import { mergeAgentNativeConfigs, resolveAgentNativeConfig, } from "../config.js";
 import { writeAgentNativeNitroPresetMarker } from "../deploy/nitro-preset.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import { verifyEmbedSessionToken } from "../server/embed-session.js";
@@ -17,6 +17,7 @@ import { normalizeMcpIntegrationsConfig, } from "../shared/mcp-integration-confi
 import { normalizeAgentNativeRouteWarmupConfig, } from "../shared/route-warmup-config.js";
 import { formatRuntimeConfigReport, getRuntimeConfigReport, } from "../shared/runtime-config.js";
 import { actionTypesPlugin } from "./action-types-plugin.js";
+import { createAgentNativeConfigContext, loadAgentNativeConfigFile, readAgentNativeJsonConfig, } from "./agent-native-config-loader.js";
 import { agentsBundlePlugin } from "./agents-bundle-plugin.js";
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -2405,9 +2406,17 @@ function getConfiguredAppBasePath() {
     return { appBasePath, base };
 }
 function createNitroDevPlugin(options, appBasePath) {
+    const nitroOptions = options.nitro ?? {};
     return nitroVitePlugin({
         serverDir: "./server",
-        ...(options.nitro ?? {}),
+        ...nitroOptions,
+        replace: {
+            ...nitroOptions.replace,
+            // Netlify's netlify.toml environment is available to the build but not
+            // injected into deployed Functions. Nitro is a separate server build,
+            // so it needs the release ownership decision in its own replacement map.
+            "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(process.env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
+        },
         // Never auto-load test files as server handlers/plugins/middleware.
         // Nitro scans server/{plugins,middleware,routes,api}/*; a co-located
         // *.spec.ts would otherwise be loaded at runtime and crash the server
@@ -2568,7 +2577,7 @@ function createAgentNativePlugins(options, { command, includeReactTransform, use
         ...userPlugins,
         appChangelogRawPlugin(),
         actionTypesPlugin(),
-        agentsBundlePlugin(),
+        agentsBundlePlugin({ agentNativeConfig: options.agentNativeConfig }),
         autoReloadOnOptimizeDep(),
         fullReloadOnOptimizeDep504(),
         embedDevFrameHeaders(),
@@ -2612,52 +2621,6 @@ function resolveAgentNativeTemplate(cwd) {
         ?.trim()
         .toLowerCase() ?? "");
 }
-function createAgentNativeConfigContext(command, mode) {
-    const resolvedCommand = command === "build" ? "build" : "serve";
-    return {
-        command: resolvedCommand,
-        mode,
-        isDev: resolvedCommand === "serve",
-        isBuild: resolvedCommand === "build",
-    };
-}
-function readAgentNativeJsonConfig(cwd) {
-    const configPath = path.join(cwd, "agent-native.json");
-    if (!fs.existsSync(configPath))
-        return {};
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    }
-    catch (error) {
-        throw new Error(`Could not read ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return normalizeAgentNativeConfig(parsed, configPath);
-}
-async function loadAgentNativeConfigFile(cwd) {
-    const candidates = [
-        "agent-native.ts",
-        "agent-native.mts",
-        "agent-native.config.ts",
-        "agent-native.config.mts",
-    ];
-    const configPath = candidates
-        .map((filename) => path.join(cwd, filename))
-        .find((candidate) => fs.existsSync(candidate));
-    if (!configPath)
-        return undefined;
-    try {
-        const module = (await import(pathToFileURL(configPath).href));
-        const config = module.default ?? module.agentNativeConfig;
-        if (typeof config !== "object" && typeof config !== "function") {
-            throw new Error("the default export must be an object or function");
-        }
-        return config;
-    }
-    catch (error) {
-        throw new Error(`Could not load ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
 function reportRuntimeConfigDiagnostics(appConfig, context, mode, env = process.env) {
     const production = mode === "production" || process.env.NODE_ENV === "production";
     if (!production)
@@ -2784,6 +2747,10 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
             __AGENT_NATIVE_APP_CONFIG__: JSON.stringify(appConfig),
             __AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID__: JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
             "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
+            // The release migration owner is configured at build time. Netlify's
+            // 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() || ""),
             __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/dist/vite/index.d.ts

@@ -1,6 +1,6 @@
 export { agentNative, defineConfig, type AgentNativeVitePluginOptions, type ClientConfigOptions, type NitroOptions, } from "./client.js";
-export { defineAgentNativeConfig, type AgentNativeConfig, type AgentNativeConfigContext, type AgentNativeConfigFactory, type AgentNativeConfigInput, type AgentNativeDiagnosticsConfig, type AgentNativeFirstRunOnboardingMode, type AgentNativeFirstRunOnboardingSetting, type AgentNativeRuntimeAuthConfig, type AgentNativeRuntimeConfig, type AgentNativeRuntimeDatabaseConfig, type AgentNativeRuntimeEnvironmentConfig, } from "../config.js";
+export { defineAgentNativeConfig, type AgentNativeConfig, type AgentNativeConfigContext, type AgentNativeConfigFactory, type AgentNativeConfigInput, type AgentNativeDiagnosticsConfig, type AgentNativeFirstRunOnboardingMode, type AgentNativeFirstRunOnboardingSetting, type AgentNativeInstructionsConfig, type AgentNativeRuntimeAuthConfig, type AgentNativeRuntimeConfig, type AgentNativeRuntimeDatabaseConfig, type AgentNativeRuntimeEnvironmentConfig, } from "../config.js";
 export type { AgentNativeRouteWarmupConfigInput, AgentNativeRouteWarmupResolvedConfig, AgentNativeRouteWarmupStrategy, } from "../shared/route-warmup-config.js";
 export { actionTypesPlugin, generateActionRegistryForProject, } from "./action-types-plugin.js";
-export { agentsBundlePlugin } from "./agents-bundle-plugin.js";
+export { agentsBundlePlugin, type AgentsBundlePluginOptions, } from "./agents-bundle-plugin.js";
 export { createAgentWebVitePlugin, type AgentWebVitePluginOptions, } from "./agent-web-plugin.js";

package/dist/vite/index.js

@@ -1,5 +1,5 @@
 export { agentNative, defineConfig, } from "./client.js";
 export { defineAgentNativeConfig, } from "../config.js";
 export { actionTypesPlugin, generateActionRegistryForProject, } from "./action-types-plugin.js";
-export { agentsBundlePlugin } from "./agents-bundle-plugin.js";
+export { agentsBundlePlugin, } from "./agents-bundle-plugin.js";
 export { createAgentWebVitePlugin, } from "./agent-web-plugin.js";

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

@@ -1,14 +1,14 @@
 ---
 title: "Agent-Native app configuration"
-description: "Configure public Agent-Native app defaults with agent-native.ts, its typed aliases, or agent-native.json compatibility."
-search: "agent-native.ts agent-native.config.ts agent-native.config.mts agent-native.json onboarding runtime readiness configuration"
+description: "Configure public Agent-Native app defaults with agent-native.config.ts, its typed aliases, or agent-native.json compatibility."
+search: "agent-native.config.ts agent-native.ts agent-native.mts agent-native.config.mts agent-native.json onboarding runtime readiness configuration instructions"
 ---
 
 # Agent-Native app configuration
 
-Use `agent-native.ts` for new shared Agent-Native configuration. It is a typed,
-mode-aware source for committed, non-secret app defaults. The framework also
-accepts `agent-native.mts`, `agent-native.config.ts`, and
+Use `agent-native.config.ts` for new shared Agent-Native configuration. It is a
+typed, mode-aware source for committed, non-secret app defaults. The framework
+also accepts `agent-native.ts`, `agent-native.mts`, and
 `agent-native.config.mts` as filename aliases, and continues to read
 `agent-native.json` for compatibility.
 
@@ -23,9 +23,9 @@ app's Vite configuration. In a workspace, each app has its own root and its own
 configuration file. The Vite preset reads from the current app root, not from
 `server/plugins/` or a workspace-wide directory.
 
-For new apps, create `agent-native.ts`:
+For new apps, create `agent-native.config.ts`:
 
-```ts filename="agent-native.ts"
+```ts filename="agent-native.config.ts"
 import { defineAgentNativeConfig } from "@agent-native/core/config";
 
 export default defineAgentNativeConfig(({ command, mode, isBuild }) => {
@@ -88,6 +88,32 @@ configuration portion of `agent-native.json`:
 | `runtime.database.required`    | `boolean`                                                         | Declares whether production needs a persistent remote SQL database.                                                                                                                       |
 | `runtime.environment.required` | `string[]`                                                        | Declares additional required environment variable names. Names must match `[A-Za-z_][A-Za-z0-9_]*`; values do not belong in the config.                                                   |
 | `diagnostics.failOnBuild`      | `boolean`                                                         | When `true`, a production Vite build throws on runtime configuration issues. When absent or `false`, it reports them without failing the build.                                           |
+| `instructions.runtime`         | `string`                                                          | Optional relative Markdown path for the in-app runtime agent. Defaults to `AGENTS.md`.                                                                                                    |
+| `instructions.development`     | `string`                                                          | Optional relative Markdown path for development/coding agents. Defaults to `AGENTS.md`.                                                                                                   |
+
+### Separate runtime and development instructions
+
+The default is intentionally flat: both audiences read `AGENTS.md`, and
+existing apps do not need to change. To keep development guidance out of the
+deployed app agent, opt in with audience-specific paths:
+
+```ts filename="agent-native.config.ts"
+import { defineAgentNativeConfig } from "@agent-native/core/config";
+
+export default defineAgentNativeConfig({
+  instructions: {
+    runtime: "app-agent/AGENTS.md",
+    development: "DEVELOPING.md",
+  },
+});
+```
+
+Paths are relative to the app root and cannot escape it. If an explicitly
+selected file is missing, that audience receives no file; the framework does
+not fall back to `AGENTS.md`, because that could reintroduce development-only
+guidance into runtime. Skills keep their existing frontmatter audience scope:
+use `scope: runtime`, `scope: dev`, or `scope: both` when a skill needs a
+different boundary.
 
 ### Mode maps for onboarding
 
@@ -98,7 +124,7 @@ exact Vite modes. The resolver checks the exact `mode` first. If there is no
 exact match, it checks `development` for `serve` or `production` for `build`,
 then `default`, and finally falls back to `off`:
 
-```ts filename="agent-native.ts"
+```ts filename="agent-native.config.ts"
 import { defineAgentNativeConfig } from "@agent-native/core/config";
 
 export default defineAgentNativeConfig({
@@ -143,7 +169,7 @@ guidance, never secret values.
 For example, this is a useful readiness declaration when an app uses the
 framework's normal auth and database contracts:
 
-```ts filename="agent-native.ts"
+```ts filename="agent-native.config.ts"
 import { defineAgentNativeConfig } from "@agent-native/core/config";
 
 export default defineAgentNativeConfig({
@@ -160,7 +186,7 @@ Set the actual deployment values outside the repository. For example, provide
 `BETTER_AUTH_SECRET`, `DATABASE_URL`, and `PUBLIC_API_ORIGIN` in Netlify,
 Vercel, another deployment environment, or the appropriate scoped secret
 store. Do not replace those placeholders with literal values in
-`agent-native.ts`.
+`agent-native.config.ts`.
 
 `diagnostics.failOnBuild` is for runtime configuration diagnostics. It is not
 the same setting as the separate `doctor.failOnBuild` option documented in the
@@ -174,8 +200,8 @@ For a Vite app, the effective shared configuration follows this order:
    persistent database default to required in production diagnostics.
 2. `agent-native.json` at the app root.
 3. The automatically loaded typed file, if present. The loader checks these
-   candidates in order: `agent-native.ts`, `agent-native.mts`,
-   `agent-native.config.ts`, `agent-native.config.mts`.
+   candidates in order: `agent-native.config.ts`, `agent-native.ts`,
+   `agent-native.mts`, `agent-native.config.mts`.
 4. 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`.
@@ -185,8 +211,8 @@ For a Vite app, the effective shared configuration follows this order:
    resolved onboarding mode. Use the config file 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.ts` preferred for new
-apps. The names are aliases, not four layers that are merged together.
+candidate in the loader's order wins, with `agent-native.config.ts` preferred
+for new apps. The names are aliases, not four layers that are merged together.
 
 The JSON and typed sources are merged by supported nested section:
 
@@ -200,7 +226,7 @@ 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.ts` adds `runtime.database.required` 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.
 
@@ -223,7 +249,7 @@ 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.ts` should describe the app's
+it changes between targets. `agent-native.config.ts` should describe the app's
 public shape, not become a second environment-variable file.
 
 ## `agent-native.json` compatibility
@@ -254,7 +280,7 @@ default that never depends on the Vite command or mode:
 }
 ```
 
-For new app-owned configuration, prefer `agent-native.ts` when the app needs
+For new app-owned configuration, prefer `agent-native.config.ts` when the app needs
 types, a mode-aware factory, or a clear place to evolve public defaults. Keep
 `agent-native.json` when portability or existing manifest sections are the
 reason to use it. Both formats accept the same shared options shown above.

package/docs/content/drop-in-agent.mdx

@@ -142,11 +142,11 @@ children stays in the main app area. The agent chat is the side panel.
   ]}
 />
 
-That's it. The user now has a toggleable agent on every page — with chat history, resources tab, CLI terminal, voice input, and a fullscreen mode. State persists across reloads via `localStorage`.
+That's it. The user now has a toggleable agent on every page — with chat history, resources tab, CLI terminal, voice input, and a wider drawer. State persists across reloads via `localStorage`.
 
 ### Props
 
-- **`children`** — your app's normal layout and routes. Rendered in the main area; the agent panel mounts beside it on desktop and over it on mobile/fullscreen.
+- **`children`** — your app's normal layout and routes. Rendered in the main area; the agent panel mounts beside it on desktop and over it on mobile.
 - **`emptyStateText`** — greeting shown when the chat has no messages. Default: `"How can I help you?"`.
 - **`suggestions`** — starter prompts rendered as clickable chips when empty.
 - **`dynamicSuggestions`** — context-aware prompt chips merged with `suggestions`. Enabled by default; pass `false` to show only static suggestions, or `{ max, includeStatic, getSuggestions }` to customize.
@@ -177,7 +177,7 @@ export default function AgentRoute() {
 - **`defaultMode`** — `"chat"` or `"cli"`. Default: `"chat"`.
 - **`className`** — CSS class for the outer container.
 - **`onCollapse`** — if provided, a collapse button appears in the header.
-- **`isFullscreen`** / **`onToggleFullscreen`** — wire up external fullscreen state if you want a Claude-style centered column.
+- **`isFullscreen`** — set this when you want a Claude-style centered column for a page-level or custom panel surface. The sidebar uses the wider drawer instead.
 - **`storageKey`** — namespace for `localStorage` keys. Useful when you render multiple panels (different app instances or workspaces) in the same page.
 
 Full props: `AgentPanelProps` in `@agent-native/core/client`.

package/docs/content/environment-variables.mdx

@@ -90,7 +90,7 @@ values.
 Every framework app exposes the redacted report at
 `/_agent-native/ping?configuration=1`. The shared provider shell turns a
 non-healthy production report into a warning or error chip with a **Copy
-prompt for AI** button. `agent-native.ts` or its compatibility aliases can add
+prompt for AI** button. `agent-native.config.ts` or its compatibility aliases can add
 non-secret requirements under `runtime.environment.required`; set the actual
 values in Netlify, Vercel, or the deployment's secret store.
 

package/docs/content/getting-started-actions.mdx

@@ -89,5 +89,4 @@ custom native components, see [Native Chat UI](/docs/native-chat-ui).
 ## Continue
 
 Continue with [Add a Page](/docs/getting-started-pages) to use the same action
-outside the transcript. When results need to survive conversations, return to
-[Persist Data in SQL](/docs/getting-started-database).
+outside the transcript.

package/docs/content/getting-started-pages.mdx

@@ -71,6 +71,5 @@ patterns, see [Context Awareness](/docs/context-awareness).
 ## Continue
 
 You've built a chat app with an action and a page that calls the same source of
-truth. Continue with [Persist Data in SQL](/docs/getting-started-database) when
-results need to persist, or explore [Key Concepts](/docs/key-concepts) and
+truth. Continue with [Key Concepts](/docs/key-concepts) or
 [Agent Surfaces](/docs/agent-surfaces).

package/docs/content/getting-started.mdx

@@ -26,10 +26,6 @@ Define a typed text analyzer and render its result as a chart in the chat.
 
 Build a React route that calls the same action outside the transcript.
 
-### Persist data in SQL (optional)
-
-Add a table and persistence actions when results need to survive conversations.
-
 </Steps>
 
 ## 1. Create a chat app {#create-your-app}

package/docs/content/what-is-agent-native.mdx

@@ -79,10 +79,10 @@ Every operation is defined as a typed **action**: a name, a schema, and a `run`
 
 ```mermaid
 graph TD
-  UI_IN["👤 Click a button"]
-  AG_IN["🤖 Type a message to the agent"]
-  ACTION["⚡ Same typed action"]
-  DB["🗄️ Shared database"]
+  UI_IN["Click a button"]
+  AG_IN["Type a message to the agent"]
+  ACTION["Same typed action"]
+  DB["Shared database"]
   UI_OUT["UI updates instantly"]
   AG_OUT["Agent sees the change"]
 

package/package.json

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

package/src/templates/chat/.agents/skills/turn-into-app/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Turn visible project context, a proven thread, skill, or workflow into a
   runnable Agent-Native app with simple buttons, visible agent steps, preview,
   and deployment handoff. Use when a user invokes `/turn-into-app` or asks to
-  make a workflow into an app.
+  make a workflow into an app, including from Claude or ChatGPT on the web.
 user-invocable: true
 scope: both
 metadata:
@@ -13,9 +13,36 @@ metadata:
 
 # Turn Into App
 
+## Host execution boundary
+
+The build location depends on the host. Treat this as a hard routing rule:
+
+- In Claude Web, ChatGPT Web, or a Claude/ChatGPT Project on the web, you are
+  the source analyst and handoff orchestrator. You must not build the app in
+  the host sandbox. Do not run `npm`, `pnpm`, `npx`, `agent-native create`, or
+  `add-app`; do not edit files, create artifacts, or start a local dev server.
+  After writing the bounded source brief, call the connected Dispatch action
+  `start-workspace-app-creation`. Pass the brief and repeatable workflow in
+  `prompt`, plus the inferred `appId`, `description`, `template`, and selected
+  `resourceIds` when available. This is the Builder handoff.
+- Do not substitute the generic `create_workspace_app` MCP tool in an online
+  host. That tool is a local workspace scaffolder, not the Builder handoff.
+- Connect the Agent-Native Dispatch MCP connector only. Dispatch uses the
+  authenticated Builder Projects API to reuse or provision the workspace
+  project before starting the Builder Cloud Agent; a separate Builder CMS MCP
+  connection is not required for this workflow.
+- If `start-workspace-app-creation` is not available or Dispatch is not
+  authenticated, stop with the connector setup needed. Do not fall back to a
+  local build or claim that the app exists.
+- In Claude Code, Codex Code, or another local code-agent runtime with a target
+  workspace, follow the local implementation steps below. The local agent may
+  scaffold, edit, run, and verify the app there.
+
 ## Default behavior
 
-This is an end-to-end build skill, not a request for an app proposal.
+For a local code-agent runtime this is an end-to-end build skill, not a request
+for an app proposal. For an online host, the end-to-end result is a verified
+Builder handoff and the resulting workspace app, not code written in the host.
 
 - With no argument, choose the source in this order: visible project context,
   then the current thread. A fresh Claude or ChatGPT Project is a valid source
@@ -47,9 +74,12 @@ private web access, invent an importer, add fake OAuth, or scrape a logged-in
 page. If the needed context is not visible, ask for an export, transcript, or
 attachment and treat that artifact as imported source material.
 
-Deliver a fresh app in a new directory, implement the repeatable workflow with
-buttons and agent handoffs, start its dev server, verify the main path, and
-continue through build/deployment handoff. Do not stop at a plan.
+For local code-agent runtimes, deliver a fresh app in a new directory,
+implement the repeatable workflow with buttons and agent handoffs, start its dev
+server, verify the main path, and continue through build/deployment handoff. Do
+not stop at a plan. For online hosts, call Dispatch first after the source brief,
+then report the returned Builder branch/path and verify the workspace app through
+Dispatch when it becomes available.
 
 ## Fresh project context mode
 
@@ -190,12 +220,12 @@ Do not use `create` for an existing workspace; it scaffolds a new standalone
 workspace rather than adding an app to the current one.
 
 When the source came from a fresh external Project and the target is a Builder
-workspace, prefer the available Dispatch MCP workspace handoff after writing
-the source brief. Call `start-workspace-app-creation` with a concise prompt,
-the inferred app id, and the brief's repeatable workflow. Pass selected
-workspace resource IDs when they are available, rather than pasting entire
-knowledge files. Continue from the returned workspace path or Builder handoff
-and report the actual verification result.
+workspace, the online host path is mandatory: after writing the source brief,
+call `start-workspace-app-creation` with a concise prompt, the inferred app id,
+and the brief's repeatable workflow. Pass selected workspace resource IDs when
+they are available, rather than pasting entire knowledge files. Continue from
+the returned workspace path or Builder branch handoff and report the actual
+verification result. Do not run the local scaffold commands in this host mode.
 
 Use a first-party template only when it materially fits the workflow. Keep the
 new app independent from the source thread's working tree unless the user