@agent-native/core 0.145.7 → 0.146.0

package/dist/templates/headless/.agents/skills/turn-into-app/references/fresh-project.md

@@ -51,13 +51,24 @@ also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
 
+For Claude Web, ChatGPT Web, and their web Projects, the host is an
+orchestrator, not the build environment. After forming the source brief, call
+the Dispatch `start-workspace-app-creation` action so Builder creates the app
+in the connected workspace. Do not use the host's code interpreter, shell,
+artifact editor, `create_workspace_app`, or local `pnpm`/`npm` commands. If the
+handoff action is unavailable, stop and ask the user to authenticate Dispatch;
+do not fall back to a local sandbox build. Claude Code and Codex Code are the
+local-agent exception and may follow the implementation steps in the main
+skill.
+
 In a new Project chat, say:
 
 ```text
 Turn this project into an app. Use the visible Project instructions,
 knowledge files, and any selected successful runs as the source. Create the
-app in the connected Agent-Native workspace, keep the source brief bounded,
-and report the real path and verification result.
+app in the connected Agent-Native workspace through Dispatch and Builder, keep
+the source brief bounded, and report the real Builder branch/path and
+verification result. Do not build it in this chat's sandbox.
 ```
 
 If the host does not show the Project instructions or files to the model, stop

package/dist/templates/workspace-core/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  not show generic "Loading..." text for content loads; reserve `Spinner` for
+  brief mutations, uploads, and progress actions. Use the app's existing
+  loading primitive when it is a genuine design-system adapter. Empty states
+  should have one clear next action.
 
 ## Anti-Patterns
 

package/dist/templates/workspace-core/.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,32 @@ 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.
+- 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 +70,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 +216,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

package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/fresh-project.md

@@ -51,13 +51,24 @@ also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
 
+For Claude Web, ChatGPT Web, and their web Projects, the host is an
+orchestrator, not the build environment. After forming the source brief, call
+the Dispatch `start-workspace-app-creation` action so Builder creates the app
+in the connected workspace. Do not use the host's code interpreter, shell,
+artifact editor, `create_workspace_app`, or local `pnpm`/`npm` commands. If the
+handoff action is unavailable, stop and ask the user to authenticate Dispatch;
+do not fall back to a local sandbox build. Claude Code and Codex Code are the
+local-agent exception and may follow the implementation steps in the main
+skill.
+
 In a new Project chat, say:
 
 ```text
 Turn this project into an app. Use the visible Project instructions,
 knowledge files, and any selected successful runs as the source. Create the
-app in the connected Agent-Native workspace, keep the source brief bounded,
-and report the real path and verification result.
+app in the connected Agent-Native workspace through Dispatch and Builder, keep
+the source brief bounded, and report the real Builder branch/path and
+verification result. Do not build it in this chat's sandbox.
 ```
 
 If the host does not show the Project instructions or files to the model, stop

package/dist/templates/workspace-core/AGENTS.md

@@ -44,6 +44,9 @@ agent should know.
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and domain-specific navigation. Never use sparkle, wand,
   magic, or robot icons as AI affordances.
+- Data loads use layout-matching `Skeleton` geometry, never a
+  generic "Loading..." label. Reserve `Spinner` for brief mutations, uploads,
+  and progress actions.
 - Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
   type for content previews. Give the AgentSidebar a subtle surface/divider
   boundary, and stack original/generated review vertically by default.

package/dist/templates/workspace-root/AGENTS.md

@@ -69,6 +69,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and domain-specific navigation. Never use sparkle, wand,
   magic, or robot icons as AI affordances.
+- Page and section data loads use layout-matching `Skeleton` geometry, never a
+  generic "Loading..." label. Reserve `Spinner` for brief mutations, uploads,
+  and progress actions.
 - Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
   type for content previews. Give the AgentSidebar a subtle surface/divider
   boundary, and stack original/generated review vertically by default.

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));
@@ -2568,7 +2569,7 @@ function createAgentNativePlugins(options, { command, includeReactTransform, use
         ...userPlugins,
         appChangelogRawPlugin(),
         actionTypesPlugin(),
-        agentsBundlePlugin(),
+        agentsBundlePlugin({ agentNativeConfig: options.agentNativeConfig }),
         autoReloadOnOptimizeDep(),
         fullReloadOnOptimizeDep504(),
         embedDevFrameHeaders(),
@@ -2612,52 +2613,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)

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.7",
+  "version": "0.146.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -412,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.4"
+    "@agent-native/toolkit": "^0.13.4",
+    "@agent-native/recap-cli": "0.5.3"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

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

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  not show generic "Loading..." text for content loads; reserve `Spinner` for
+  brief mutations, uploads, and progress actions. Use the app's existing
+  loading primitive when it is a genuine design-system adapter. Empty states
+  should have one clear next action.
 
 ## Anti-Patterns