@agent-native/core 0.113.0 → 0.114.1

package/dist/templates/chat/.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/dist/templates/chat/.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/dist/templates/chat/AGENTS.md

@@ -54,8 +54,9 @@ workflow needs durable UI around the conversation.
 - Prefer those installed docs over memory or public docs when package APIs,
   generated-app conventions, workspaces, actions, or agent surfaces are involved.
 - Read `customizing-agent-native` before overriding the chat shell or shared UI.
-  Keep Core thread/runtime behavior, try public props and composition first,
-  and copy only the smallest presentation component into app-owned source.
+  Keep Core thread/runtime behavior and use the supported ladder: configure →
+  compose → eject the smallest presentation unit → propose a shared seam.
+  Preview before `--apply` and commit `agent-native.ejections.json`.
 
 ## Skills
 

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