@agent-native/core 0.113.0 → 0.114.1

package/corpus/core/src/server/action-routes.ts

@@ -30,6 +30,26 @@ import {
   getAllowedCorsOrigin as resolveAllowedCorsOrigin,
   readCorsAllowedOrigins,
 } from "./cors-origins.js";
+
+declare const __AGENT_NATIVE_BUILD_ID__: string | undefined;
+declare const __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__: string | undefined;
+
+function requiredClientCompatibilityVersion(): string {
+  const configured =
+    typeof __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__ === "string"
+      ? __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__
+      : process.env.AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION;
+  return configured?.trim() ?? "";
+}
+
+function currentBuildId(): string {
+  const configured =
+    typeof __AGENT_NATIVE_BUILD_ID__ === "string"
+      ? __AGENT_NATIVE_BUILD_ID__
+      : process.env.AGENT_NATIVE_BUILD_ID;
+  return configured?.trim() || "unknown";
+}
+
 /**
  * Auto-mount actions as HTTP endpoints under /_agent-native/actions/:name.
  *
@@ -187,8 +207,8 @@ function handleOptionsRequest(event: any): string {
       event,
       "Access-Control-Allow-Headers",
       cors.credentials
-        ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,${EMBED_TARGET_HEADER}`
-        : `${MCP_EMBED_CORS_ALLOW_HEADERS},X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend`,
+        ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,${EMBED_TARGET_HEADER}`
+        : `${MCP_EMBED_CORS_ALLOW_HEADERS},X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id`,
     );
   }
 
@@ -320,6 +340,11 @@ export function mountActionRoutes(
         }
 
         setResponseHeader(event, "Cache-Control", "no-store");
+        setResponseHeader(
+          event,
+          "Access-Control-Expose-Headers",
+          "X-Agent-Native-Client-Mismatch,X-Agent-Native-Build-Id,X-Agent-Native-Client-Compatibility",
+        );
 
         // Allow the declared method
         if (effectiveMethod !== method) {
@@ -327,6 +352,31 @@ export function mountActionRoutes(
           return { error: `Method not allowed. Use ${method}.` };
         }
 
+        const requiredCompatibility = requiredClientCompatibilityVersion();
+        if (isFrontendActionRequest(event) && requiredCompatibility) {
+          const receivedCompatibility = getHeader(
+            event,
+            "x-agent-native-client-compatibility",
+          );
+          if (receivedCompatibility !== requiredCompatibility) {
+            const serverBuildId = currentBuildId();
+            setResponseStatus(event, 409);
+            setResponseHeader(event, "X-Agent-Native-Client-Mismatch", "1");
+            setResponseHeader(event, "X-Agent-Native-Build-Id", serverBuildId);
+            setResponseHeader(
+              event,
+              "X-Agent-Native-Client-Compatibility",
+              requiredCompatibility,
+            );
+            return {
+              error: "This browser tab must reload before it can use this app.",
+              code: "client_build_mismatch",
+              serverBuildId,
+              requiredCompatibility,
+            };
+          }
+        }
+
         // (audit H5) Per-action `toolCallable` opt-out for the tools-iframe
         // bridge. The bridge tags every outbound action call with
         // X-Agent-Native-Tool-Bridge: 1. When that header is present and the

package/corpus/core/src/server/auth-plugin.ts

@@ -4,16 +4,21 @@ import {
   getH3App,
   awaitBootstrap,
   markDefaultPluginProvided,
+  trackPluginInit,
 } from "./framework-request-handler.js";
 
 type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 
 export function createAuthPlugin(options?: AuthOptions): NitroPluginDef {
-  return async (nitroApp: any) => {
+  return (nitroApp: any) => {
     markDefaultPluginProvided(nitroApp, "auth");
-    // Wait for any other default plugins to finish mounting first.
-    await awaitBootstrap(nitroApp);
-    await autoMountAuth(getH3App(nitroApp), options);
+    const initPromise = (async () => {
+      await awaitBootstrap(nitroApp);
+      await autoMountAuth(getH3App(nitroApp), options);
+    })();
+    trackPluginInit(nitroApp, initPromise, {
+      paths: ["/_agent-native/auth"],
+    });
   };
 }
 

package/corpus/core/src/server/better-auth-instance.ts

@@ -317,8 +317,12 @@ export function resolveSignupTrackingProperties(): Record<string, string> {
 export function shouldSkipEmailVerification(): boolean {
   const value = process.env.AUTH_SKIP_EMAIL_VERIFICATION;
   if (value == null) {
+    const deployContext =
+      process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT || process.env.CONTEXT;
     return (
-      process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test"
+      process.env.NODE_ENV === "development" ||
+      process.env.NODE_ENV === "test" ||
+      deployContext === "deploy-preview"
     );
   }
   const normalized = value.trim().toLowerCase();

package/corpus/core/src/setup-connections/index.ts

@@ -43,6 +43,7 @@ export {
   listWorkspaceConnectionProviders,
   listWorkspaceConnectionProvidersForCapability,
   listWorkspaceConnectionProvidersForTemplate,
+  mergeWorkspaceConnectionProviders,
   workspaceConnectionProviderSupports,
   type ListWorkspaceConnectionProvidersOptions,
   type WorkspaceConnectionCapability,

package/corpus/core/src/shared/mcp-embed-headers.ts

@@ -1,5 +1,5 @@
 export const MCP_EMBED_CORS_ALLOW_HEADERS =
-  "Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-Agent-Native-Frontend,X-User-Timezone,X-Agent-Native-Embed-Target,X-Agent-Native-Embed-Transplant";
+  "Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,X-User-Timezone,X-Agent-Native-Embed-Target,X-Agent-Native-Embed-Transplant";
 export const EMBED_TRANSPLANT_HEADER = "x-agent-native-embed-transplant";
 
 const CLAUDE_MCP_CONTENT_HOST_RE = /^[a-f0-9]{32}\.claudemcpcontent\.com$/i;

package/corpus/core/src/shared/merge-by-id.ts

@@ -0,0 +1,14 @@
+export interface IdentifiedDefinition {
+  id: string;
+}
+
+export function mergeDefinitionsById<T extends IdentifiedDefinition>(
+  defaults: readonly T[],
+  overrides: readonly T[] = [],
+): T[] {
+  const merged = new Map(
+    defaults.map((definition) => [definition.id, definition]),
+  );
+  for (const override of overrides) merged.set(override.id, override);
+  return [...merged.values()];
+}

package/corpus/core/src/templates/default/.agents/skills/agent-native-docs/SKILL.md

@@ -59,22 +59,24 @@ read files under `node_modules/@agent-native/core/corpus/core/` or
 
 Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
 readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
-`customizing-agent-native` before copying a shared component: inspect package
-source as a read-only reference, copy only the smallest UI piece into app-owned
-source, and preserve public actions, application state, auth, and agent-chat
-runtime contracts. Never edit `node_modules` or deep-import its private source.
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
 
 ## Useful Slugs
 
-| Need | Slugs |
-| --- | --- |
-| Actions and typed client calls | `actions`, `client` |
-| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
-| UI state visible to the agent | `context-awareness` |
-| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
-| Automations and schedules | `automations`, `recurring-jobs` |
-| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
-| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
 
 ## Don't
 

package/corpus/core/src/templates/default/.agents/skills/customizing-agent-native/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: customizing-agent-native
 description: >-
-  How to adopt, compose, or selectively copy Agent Native UI into app-owned
-  code. Use when overriding shared components, customizing a template, adding
-  UI to chat or headless apps, or inspecting installed framework source.
+  How to configure, compose, or eject Agent Native features into app-owned
+  code. Use when overriding shared components or integrations, customizing a
+  template, adding UI to chat or headless apps, or inspecting package source.
 scope: dev
 metadata:
   internal: true
@@ -14,21 +14,59 @@ metadata:
 ## Rule
 
 Start with the public component and its props, slots, callbacks, and stable
-class names. If those seams are not enough, copy the smallest useful reference
-implementation into the app and make that copy app-owned. Never edit
-`node_modules`, deep-import a private source file at runtime, or patch an
+class names. If those seams are not enough, use the eject CLI to transfer the
+smallest supported feature into the app and make that copy app-owned. Never
+edit `node_modules`, deep-import a private source file at runtime, or patch an
 `@agent-native/*` package.
 
 Use this order:
 
 1. Configure the public component.
 2. Compose public primitives behind a local app component.
-3. Copy one component or helper into app source and change the app import.
+3. Eject the smallest feature into app-owned source.
 4. Propose a new Toolkit seam when the same override is useful in two apps.
 
-Copying is for intentional product customization, not for hiding an upgrade
+Ejection is for intentional product customization, not for hiding an upgrade
 failure or replacing Core runtime behavior.
 
+## Eject A Feature
+
+Discover and inspect the ejection units published by installed first-party
+packages before changing source:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The command is dry-run by default. It prints the file closure, consumer import
+rewrites, protected package contracts, and verification commands before
+writing. `--apply` copies the package-version-matched source into the app and
+rewrites only imports covered by the unit manifest.
+
+Every first-party public ejection unit must have a complete manifest. If one is
+missing, treat that as a framework coverage bug instead of inventing a copy
+recipe. For an unknown third-party package, use the emitted add-style blueprint
+as a starting point. Protected runtime behavior is never copied; follow the
+reported configuration, adapter, or extension seam instead.
+
+Applied ejections are recorded in the committed
+`agent-native.ejections.json`, including package version, manifest digest,
+target hashes, and import rewrites. Use the recorded state to review drift or
+undo an unchanged ejection:
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+Restore is hash-gated. It refuses to remove locally edited files or reverse
+changed imports and prints their diff instead. Keep an edited ejection as
+app-owned code, or reconcile those edits before restoring it.
+
 ## Find The Installed Implementation
 
 Use the source that matches the installed package version:
@@ -45,12 +83,13 @@ rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
 - Core and first-party template source lives under
   `node_modules/@agent-native/core/corpus/core/` and
   `node_modules/@agent-native/core/corpus/templates/`.
-- Treat those trees as read-only references. Copy files into an app directory
-  such as `app/components/`, then import the local copy.
+- Treat those trees as read-only references. Prefer `agent-native eject` so the
+  package manifest selects the complete source closure and rewrites imports.
+  Manual inspection is still useful for deciding whether to configure,
+  compose, eject, or propose a shared seam.
 
-When a copied component imports sibling helpers, copy only the required
-siblings or replace them with public package imports. Do not copy an entire
-package or template to change one surface.
+Do not manually guess at sibling dependencies. The ejection manifest owns the
+required file closure and keeps protected contracts on public package imports.
 
 ## Preserve The Agent-Native Contract
 
@@ -69,29 +108,33 @@ UI ownership may change; product contracts should not:
 ## App Shapes
 
 - **Template app:** begin with its existing local adapters and domain UI. Use
-  Toolkit for repeated workspace UI; copy only the piece being customized.
+  Toolkit for repeated workspace UI; eject only the unit being customized.
 - **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
-  Core. Compose or copy Toolkit presentation such as chat-history UI around it.
+  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
 - **Headless app:** stay action-first while no UI is needed. When adding a UI,
   use the Chat template as the on-ramp or add Toolkit components without
   replacing the existing actions.
 - **Workspace:** put one-app overrides in that app. Promote a local component
   to `packages/shared` only when multiple workspace apps use it.
 
-## After Copying
+## After Ejecting
 
-- Remove unused dependencies and imports from the copied file.
+- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
+- Remove unused dependencies and imports from the ejected files.
 - Keep visible text in the app's localization catalogs.
-- Run the app's formatter, typecheck, and focused tests.
+- Run the manifest verification commands plus the app's formatter, typecheck,
+  and focused tests.
 - Re-check the installed source during future package upgrades; the app-owned
-  copy does not receive upstream fixes automatically.
+  ejection does not receive upstream fixes automatically. Use `eject diff` to
+  distinguish recorded output from subsequent local edits.
 
 ## Don't
 
 - Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
 - Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
 - Don't copy Core auth, DB, action, agent-loop, or transport internals.
-- Don't fork a full template when a prop, slot, wrapper, or one-file copy works.
+- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
+- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
 
 ## Related Skills
 

package/corpus/core/src/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -40,9 +40,11 @@ Tier 4 includes **all** of the following — not only editing package source:
 
 This does not prohibit intentional app-owned UI customization. When public
 props and composition are insufficient, the `customizing-agent-native` skill
-allows copying the smallest reference UI component from the installed source
-into the app. The copy must use public runtime contracts and must not replace
-Core auth, DB, actions, agent execution, or transport behavior.
+uses `agent-native eject` to transfer the smallest supported unit from the
+installed package into the app. The ejected unit must keep public runtime
+contracts and must not replace Core auth, DB, actions, agent execution, or
+transport behavior. Manual copying is only the fallback described by an unknown
+third-party package's add-style blueprint.
 
 When an older branch needs current packages, use **`agent-native upgrade`**
 (see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
@@ -94,8 +96,9 @@ inline strings in components.
 - Don't modify `.env` files or files containing secrets
 - Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
   `@agent-native/*` package internals (including under `node_modules`)
-- Don't confuse a read-only reference copy with editing package internals: use
-  `customizing-agent-native` for selective app-owned UI adoption
+- Don't confuse readable package source with app-owned code: use
+  `customizing-agent-native` and `agent-native eject` for supported ownership
+  transfer
 - Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
   `@agent-native/*` to "make the app run" after a version bump
 - Don't invent local dispatch/core behavior overrides when upgrade fails —
@@ -107,7 +110,7 @@ inline strings in components.
 ## Related Skills
 
 - **upgrade-agent-native** — supported path to bring an older app/workspace current
-- **customizing-agent-native** — safe selective adoption of installed reference UI
+- **customizing-agent-native** — configure, compose, or eject installed features safely
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/corpus/core/src/templates/default/AGENTS.md

@@ -35,10 +35,11 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
   `node_modules/@agent-native/core/corpus/` for source examples.
 
 When intentionally customizing shared UI, read `customizing-agent-native`.
-Configure or compose public components first. If needed, inspect the installed
-Toolkit source or Core corpus and copy only the smallest UI piece into app-owned
-source. Never edit `node_modules`, deep-import private source, or copy runtime
-auth, data, action, or agent-chat internals.
+Use the supported ladder: configure → compose → eject the smallest unit →
+propose a shared seam. Preview `agent-native eject <unit>` before `--apply`,
+commit `agent-native.ejections.json`, and never edit `node_modules`, deep-import
+private source, or eject protected runtime auth, data, action, or agent-chat
+internals.
 
 Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
@@ -163,7 +164,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | Skill                      | When to read                                                                      |
 | -------------------------- | --------------------------------------------------------------------------------- |
 | `agent-native-docs`        | Before using advanced Agent Native framework APIs or generated-app features       |
-| `customizing-agent-native` | Before overriding or selectively copying shared Agent Native UI                   |
+| `customizing-agent-native` | Before configuring, composing, or ejecting shared Agent Native features           |
 | `adding-a-feature`         | **Read first when adding ANY new feature** — the four-area parity checklist       |
 | `feature-flags`            | Before shipping a staged production rollout or replacing a compile-time switch    |
 | `real-time-sync`           | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |

package/corpus/core/src/templates/headless/.agents/skills/agent-native-docs/SKILL.md

@@ -59,22 +59,24 @@ read files under `node_modules/@agent-native/core/corpus/core/` or
 
 Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
 readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
-`customizing-agent-native` before copying a shared component: inspect package
-source as a read-only reference, copy only the smallest UI piece into app-owned
-source, and preserve public actions, application state, auth, and agent-chat
-runtime contracts. Never edit `node_modules` or deep-import its private source.
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
 
 ## Useful Slugs
 
-| Need | Slugs |
-| --- | --- |
-| Actions and typed client calls | `actions`, `client` |
-| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
-| UI state visible to the agent | `context-awareness` |
-| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
-| Automations and schedules | `automations`, `recurring-jobs` |
-| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
-| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
 
 ## Don't
 

package/corpus/core/src/templates/headless/.agents/skills/customizing-agent-native/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: customizing-agent-native
 description: >-
-  How to adopt, compose, or selectively copy Agent Native UI into app-owned
-  code. Use when overriding shared components, customizing a template, adding
-  UI to chat or headless apps, or inspecting installed framework source.
+  How to configure, compose, or eject Agent Native features into app-owned
+  code. Use when overriding shared components or integrations, customizing a
+  template, adding UI to chat or headless apps, or inspecting package source.
 scope: dev
 metadata:
   internal: true
@@ -14,21 +14,59 @@ metadata:
 ## Rule
 
 Start with the public component and its props, slots, callbacks, and stable
-class names. If those seams are not enough, copy the smallest useful reference
-implementation into the app and make that copy app-owned. Never edit
-`node_modules`, deep-import a private source file at runtime, or patch an
+class names. If those seams are not enough, use the eject CLI to transfer the
+smallest supported feature into the app and make that copy app-owned. Never
+edit `node_modules`, deep-import a private source file at runtime, or patch an
 `@agent-native/*` package.
 
 Use this order:
 
 1. Configure the public component.
 2. Compose public primitives behind a local app component.
-3. Copy one component or helper into app source and change the app import.
+3. Eject the smallest feature into app-owned source.
 4. Propose a new Toolkit seam when the same override is useful in two apps.
 
-Copying is for intentional product customization, not for hiding an upgrade
+Ejection is for intentional product customization, not for hiding an upgrade
 failure or replacing Core runtime behavior.
 
+## Eject A Feature
+
+Discover and inspect the ejection units published by installed first-party
+packages before changing source:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The command is dry-run by default. It prints the file closure, consumer import
+rewrites, protected package contracts, and verification commands before
+writing. `--apply` copies the package-version-matched source into the app and
+rewrites only imports covered by the unit manifest.
+
+Every first-party public ejection unit must have a complete manifest. If one is
+missing, treat that as a framework coverage bug instead of inventing a copy
+recipe. For an unknown third-party package, use the emitted add-style blueprint
+as a starting point. Protected runtime behavior is never copied; follow the
+reported configuration, adapter, or extension seam instead.
+
+Applied ejections are recorded in the committed
+`agent-native.ejections.json`, including package version, manifest digest,
+target hashes, and import rewrites. Use the recorded state to review drift or
+undo an unchanged ejection:
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+Restore is hash-gated. It refuses to remove locally edited files or reverse
+changed imports and prints their diff instead. Keep an edited ejection as
+app-owned code, or reconcile those edits before restoring it.
+
 ## Find The Installed Implementation
 
 Use the source that matches the installed package version:
@@ -45,12 +83,13 @@ rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
 - Core and first-party template source lives under
   `node_modules/@agent-native/core/corpus/core/` and
   `node_modules/@agent-native/core/corpus/templates/`.
-- Treat those trees as read-only references. Copy files into an app directory
-  such as `app/components/`, then import the local copy.
+- Treat those trees as read-only references. Prefer `agent-native eject` so the
+  package manifest selects the complete source closure and rewrites imports.
+  Manual inspection is still useful for deciding whether to configure,
+  compose, eject, or propose a shared seam.
 
-When a copied component imports sibling helpers, copy only the required
-siblings or replace them with public package imports. Do not copy an entire
-package or template to change one surface.
+Do not manually guess at sibling dependencies. The ejection manifest owns the
+required file closure and keeps protected contracts on public package imports.
 
 ## Preserve The Agent-Native Contract
 
@@ -69,29 +108,33 @@ UI ownership may change; product contracts should not:
 ## App Shapes
 
 - **Template app:** begin with its existing local adapters and domain UI. Use
-  Toolkit for repeated workspace UI; copy only the piece being customized.
+  Toolkit for repeated workspace UI; eject only the unit being customized.
 - **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
-  Core. Compose or copy Toolkit presentation such as chat-history UI around it.
+  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
 - **Headless app:** stay action-first while no UI is needed. When adding a UI,
   use the Chat template as the on-ramp or add Toolkit components without
   replacing the existing actions.
 - **Workspace:** put one-app overrides in that app. Promote a local component
   to `packages/shared` only when multiple workspace apps use it.
 
-## After Copying
+## After Ejecting
 
-- Remove unused dependencies and imports from the copied file.
+- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
+- Remove unused dependencies and imports from the ejected files.
 - Keep visible text in the app's localization catalogs.
-- Run the app's formatter, typecheck, and focused tests.
+- Run the manifest verification commands plus the app's formatter, typecheck,
+  and focused tests.
 - Re-check the installed source during future package upgrades; the app-owned
-  copy does not receive upstream fixes automatically.
+  ejection does not receive upstream fixes automatically. Use `eject diff` to
+  distinguish recorded output from subsequent local edits.
 
 ## Don't
 
 - Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
 - Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
 - Don't copy Core auth, DB, action, agent-loop, or transport internals.
-- Don't fork a full template when a prop, slot, wrapper, or one-file copy works.
+- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
+- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
 
 ## Related Skills
 

package/corpus/core/src/templates/headless/AGENTS.md

@@ -40,9 +40,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
   `node_modules/@agent-native/core/corpus/` for source examples.
 
 When adding or customizing a browser UI, read `customizing-agent-native`.
-Configure or compose public components first; if needed, copy only the smallest
-reference UI piece into app-owned source. Never edit `node_modules`, deep-import
-private source, or replace the headless app's existing action contracts.
+Use the supported ladder: configure → compose → eject the smallest unit →
+propose a shared seam. Preview `agent-native eject <unit>` before `--apply`,
+commit `agent-native.ejections.json`, and never edit `node_modules`, deep-import
+private source, or eject protected runtime/action contracts.
 
 Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` for app-specific rules, then use
@@ -88,4 +89,4 @@ Skills in `.agents/skills/` provide detailed guidance. Read
 `.agents/skills/agent-native-docs/SKILL.md` before using advanced Agent Native
 framework APIs, generated-app features, automations, A2A, sharing, or MCP.
 Read `.agents/skills/customizing-agent-native/SKILL.md` before adding UI or
-overriding shared Agent Native components.
+overriding shared Agent Native features.

package/corpus/core/src/templates/workspace-core/.agents/skills/agent-native-docs/SKILL.md

@@ -59,22 +59,24 @@ read files under `node_modules/@agent-native/core/corpus/core/` or
 
 Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
 readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
-`customizing-agent-native` before copying a shared component: inspect package
-source as a read-only reference, copy only the smallest UI piece into app-owned
-source, and preserve public actions, application state, auth, and agent-chat
-runtime contracts. Never edit `node_modules` or deep-import its private source.
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
 
 ## Useful Slugs
 
-| Need | Slugs |
-| --- | --- |
-| Actions and typed client calls | `actions`, `client` |
-| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
-| UI state visible to the agent | `context-awareness` |
-| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
-| Automations and schedules | `automations`, `recurring-jobs` |
-| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
-| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
 
 ## Don't