@agent-native/core 0.113.0 → 0.114.1

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

@@ -87,8 +87,9 @@ When adding or refactoring one of these areas:
    instead of hardcoding app names in core UI.
 6. Update docs and relevant skills so future apps discover the shared path.
 7. Keep the component easy to adopt piecemeal: expose props/slots first and
-   ship readable source so apps can copy the smallest UI piece when their
-   product needs to own it. See `customizing-agent-native`.
+   ship readable source plus a complete ejection unit so apps can take ownership
+   of the smallest feature when needed. See `customizing-agent-native` for the
+   configure → compose → eject → propose seam ladder.
 
 ## Related Skills
 

package/corpus/core/src/templates/workspace-core/.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/workspace-core/.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/workspace-core/AGENTS.md

@@ -25,10 +25,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and this `AGENTS.md` plus `.agents/skills/` for
 workspace-specific conventions.
-Read `customizing-agent-native` before adapting shared UI: configure or compose
-public components first, then copy only the smallest reference UI piece into
-the owning app when necessary. Never edit `node_modules` or replace shared
-runtime contracts.
+Read `customizing-agent-native` before adapting shared UI. Use the supported
+ladder: configure → compose → eject the smallest unit → propose a shared seam.
+Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
+`node_modules` or eject protected runtime contracts.
 
 ## Shared Context
 

package/corpus/core/src/templates/workspace-root/AGENTS.md

@@ -27,10 +27,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and `packages/shared/AGENTS.md` plus
 `packages/shared/.agents/skills/` for workspace-specific conventions.
-Read `customizing-agent-native` before adapting shared UI: configure or compose
-public components first, then copy only the smallest reference UI piece into
-the owning app when necessary. Never edit `node_modules` or replace shared
-runtime contracts.
+Read `customizing-agent-native` before adapting shared UI. Use the supported
+ladder: configure → compose → eject the smallest unit → propose a shared seam.
+Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
+`node_modules` or eject protected runtime contracts.
 To bring an older workspace current, run `pnpm upgrade:agent-native` or
 `npx @agent-native/core@latest upgrade` from the workspace root. That bumps
 `@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.

package/corpus/core/src/vite/client.ts

@@ -947,6 +947,7 @@ function getDefaultOptimizeDeps(cwd: string): string[] {
       specifier: "highlight.js/lib/languages/yaml",
       packageName: "highlight.js",
     },
+    { specifier: "highlight.js/lib/core", packageName: "highlight.js" },
     { specifier: "html2canvas" },
     { specifier: "i18next" },
     { specifier: "input-otp" },
@@ -958,6 +959,7 @@ function getDefaultOptimizeDeps(cwd: string): string[] {
     { specifier: "react-day-picker" },
     { specifier: "react-i18next" },
     { specifier: "react-markdown" },
+    { specifier: "react-dom/server", packageName: "react-dom" },
     { specifier: "react-resizable-panels" },
     { specifier: "recharts" },
     ...(hasDep("react-router", cwd)
@@ -990,6 +992,25 @@ function getDefaultOptimizeDeps(cwd: string): string[] {
     },
     { specifier: "sonner" },
     { specifier: "tailwind-merge" },
+    ...(hasDep("@agent-native/toolkit", cwd)
+      ? [
+          {
+            specifier:
+              "@agent-native/toolkit > @tiptap/react > use-sync-external-store/shim/index.js",
+            packageName: "@agent-native/toolkit",
+          },
+          {
+            specifier:
+              "@agent-native/toolkit > @tiptap/react > use-sync-external-store/shim/with-selector.js",
+            packageName: "@agent-native/toolkit",
+          },
+          {
+            specifier:
+              "@agent-native/toolkit > tiptap-markdown > markdown-it-task-lists",
+            packageName: "@agent-native/toolkit",
+          },
+        ]
+      : []),
     { specifier: "vaul" },
     { specifier: "y-protocols/awareness", packageName: "y-protocols" },
     { specifier: "yjs" },
@@ -1330,6 +1351,12 @@ export interface ClientConfigOptions {
   optimizeDeps?: NonNullable<UserConfig["optimizeDeps"]>;
   /** Additional Vite define constants. */
   define?: UserConfig["define"];
+  /**
+   * Browser/server compatibility epoch for app changes that cannot safely run
+   * across a cached client and a newer action backend. Bump only for an
+   * incompatible protocol or data-model transition, not for every deploy.
+   */
+  clientCompatibilityVersion?: string;
   /**
    * Framework route warmup behavior mounted by AgentSidebar.
    *
@@ -2664,6 +2691,13 @@ function createAgentNativeConfig(
   userConfig: UserConfig = {},
 ): UserConfig {
   const cwd = process.cwd();
+  const buildId =
+    process.env.DEPLOY_ID?.trim() ||
+    process.env.COMMIT_REF?.trim() ||
+    process.env.VERCEL_GIT_COMMIT_SHA?.trim() ||
+    process.env.CF_PAGES_COMMIT_SHA?.trim() ||
+    process.env.AGENT_NATIVE_BUILD_SHA?.trim() ||
+    "development";
 
   // Workspace env fallback. If this app is inside a workspace, tell Vite to
   // also look for .env files at the workspace root. Per-app .env still wins
@@ -2689,9 +2723,11 @@ function createAgentNativeConfig(
 
   const { base } = getConfiguredAppBasePath();
   const isWorkspaceChild = process.env.AGENT_NATIVE_WORKSPACE === "1";
-  const monorepoCoreAllow = [
+  const monorepoPackageAllow = [
     path.resolve(cwd, "../../packages/core"),
     path.resolve(cwd, "../core"),
+    path.resolve(cwd, "../../packages/toolkit"),
+    path.resolve(cwd, "../toolkit"),
   ].filter((candidate) => fs.existsSync(path.join(candidate, "package.json")));
   const monorepoNodeModulesAllow = [
     path.resolve(cwd, "../../node_modules"),
@@ -2746,6 +2782,10 @@ function createAgentNativeConfig(
     define: {
       ...(userConfig.define ?? {}),
       ...(options.define ?? {}),
+      __AGENT_NATIVE_BUILD_ID__: JSON.stringify(buildId),
+      __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__: JSON.stringify(
+        options.clientCompatibilityVersion?.trim() || "",
+      ),
       __AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID__: JSON.stringify(
         process.env.GA_MEASUREMENT_ID?.trim() || "",
       ),
@@ -2796,7 +2836,7 @@ function createAgentNativeConfig(
         ...(userConfig.server?.fs ?? {}),
         allow: [
           ".",
-          ...monorepoCoreAllow,
+          ...monorepoPackageAllow,
           ...monorepoNodeModulesAllow,
           ...workspaceCoreFsAllow,
           ...localWorkspacePackageAllow,

package/corpus/templates/analytics/.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/templates/analytics/.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/templates/assets/.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