@agent-native/core 0.113.0 → 0.114.1

package/corpus/templates/content/server/plugins/db.ts

@@ -4,6 +4,7 @@ import {
   runMigrations,
 } from "@agent-native/core/db";
 
+import { repairFilesSystemPropertyDefinitions } from "../../actions/_files-system-properties.js";
 import { repairUnseededBlocksFields } from "../../actions/_property-utils.js";
 import * as schema from "../db/schema.js";
 
@@ -847,6 +848,14 @@ const runContentMigrations = runMigrations(
         CREATE UNIQUE INDEX IF NOT EXISTS content_database_items_database_document_unique
           ON content_database_items (database_id, document_id)`,
     },
+    {
+      version: 75,
+      name: "content-files-system-properties",
+      sql: `ALTER TABLE document_property_definitions ADD COLUMN IF NOT EXISTS system_role TEXT;
+        ALTER TABLE content_databases ADD COLUMN IF NOT EXISTS files_system_properties_seeded INTEGER NOT NULL DEFAULT 0;
+        CREATE UNIQUE INDEX IF NOT EXISTS document_property_definitions_database_system_role_unique
+          ON document_property_definitions (database_id, system_role)`,
+    },
   ],
   { table: "content_migrations" },
 );
@@ -922,4 +931,12 @@ export default async function contentDatabasePlugin(
     // legacy databases without their primary Blocks field until a full reboot.
     scheduleBlocksRepairRetry();
   }
+  try {
+    await repairFilesSystemPropertyDefinitions();
+  } catch (err) {
+    console.warn(
+      "[db] Files system-property repair failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
 }

package/corpus/templates/content/shared/api.ts

@@ -168,6 +168,7 @@ export type {
 export interface DocumentPropertyDefinition {
   id: string;
   databaseId: string | null;
+  systemRole?: DocumentPropertySystemRole | null;
   name: string;
   type: DocumentPropertyType;
   description?: string;
@@ -178,6 +179,11 @@ export interface DocumentPropertyDefinition {
   updatedAt: string;
 }
 
+export type DocumentPropertySystemRole =
+  | "files_kind"
+  | "files_parent"
+  | "files_source";
+
 export interface DocumentProperty {
   definition: DocumentPropertyDefinition;
   value: DocumentPropertyValue;
@@ -227,6 +233,7 @@ export interface ContentDatabase {
   id: string;
   documentId: string;
   title: string;
+  systemRole?: string | null;
   description?: string;
   viewConfig: ContentDatabaseViewConfig;
   createdAt: string;
@@ -334,6 +341,8 @@ export interface ContentDatabaseViewConfig {
   columnWidths: Record<string, number>;
 }
 
+export const CONTENT_DATABASE_PERSONAL_VIEW_OVERRIDES_VERSION = 2;
+
 export interface ContentDatabasePersonalViewOverrides {
   version: number;
   activeViewId?: string;

package/corpus/templates/content/shared/database-form.ts

@@ -1,4 +1,8 @@
-import type { ContentDatabaseFormQuestion, ContentDatabaseView } from "./api";
+import type {
+  ContentDatabaseFormQuestion,
+  ContentDatabaseView,
+  DocumentPropertySystemRole,
+} from "./api";
 import {
   isComputedPropertyType,
   type DocumentPropertyType,
@@ -8,6 +12,7 @@ export interface ContentDatabaseFormPropertyLike {
   definition: {
     id: string;
     type: DocumentPropertyType;
+    systemRole?: DocumentPropertySystemRole | null;
   };
 }
 
@@ -18,7 +23,11 @@ export function contentDatabaseFormQuestions(
   const availableKeys = [
     "name",
     ...properties
-      .filter((property) => !isComputedPropertyType(property.definition.type))
+      .filter(
+        (property) =>
+          !property.definition.systemRole &&
+          !isComputedPropertyType(property.definition.type),
+      )
       .map((property) => property.definition.id),
   ];
   const available = new Set(availableKeys);

package/corpus/templates/content/vite.config.ts

@@ -429,6 +429,7 @@ export default defineConfig({
     contentLocalComponentsPlugin(),
     ...reactRouterPlugins(),
     ...agentNativePlugins({
+      clientCompatibilityVersion: "content-spaces-v1",
       fsAllow: [
         ...(localWorkspaceRoot ? [localWorkspaceRoot] : []),
         ...dynamicLocalComponentDirs,

package/corpus/templates/design/.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/design/.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/dispatch/.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/dispatch/.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/forms/.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/forms/.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