@agent-native/core 0.117.1 → 0.118.0

package/src/templates/default/app/i18n/ja-JP.ts

@@ -344,24 +344,24 @@ const messages = {
     hideEveryone: "みんなから隠れて",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "{{name}}をアーカイブしますか？",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "これにより、他のユーザーが削除することなく、拡張機能リストから非表示になります。",
     removeEverywhereDescription:
-      "これにより、共有されているすべての場所で削除されます。",
+      "これにより、共有されているすべての場所でアーカイブされます。",
     cancel: "キャンセル",
     remove: "削除",
     removing: "削除中...",
-    delete: "削除",
-    deleting: "削除中...",
+    delete: "アーカイブ",
+    deleting: "アーカイブ中...",
     openFullView: "フルビューを開く",
     removeFromWidgetArea: "このウィジェット領域から削除する",
-    deleteExtensionEllipsis: "拡張機能を削除...",
+    deleteExtensionEllipsis: "拡張機能をアーカイブ...",
     removeFromMyListEllipsis: "リストから削除...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "これにより、共有されているすべてのユーザーの拡張機能がどこからでも削除されます。",
+      "これにより、共有されているすべてのユーザーの拡張機能がどこからでもアーカイブされます。",
     addWidget: "ウィジェットを追加する",
     loading: "読み込み中...",
     noWidgetsAvailable:

package/src/templates/default/app/i18n/ko-KR.ts

@@ -337,24 +337,24 @@ const messages = {
     hideEveryone: "모든 사람에게서 숨기기",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "{{name}}을(를) 보관할까요?",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "이렇게 하면 다른 사람을 위해 삭제하지 않고 확장 프로그램 목록에서 숨겨집니다.",
     removeEverywhereDescription:
-      "이렇게 하면 공유된 모든 위치에서 해당 항목이 제거됩니다.",
+      "이렇게 하면 공유된 모든 위치에서 해당 항목이 보관됩니다.",
     cancel: "취소",
     remove: "제거",
     removing: "삭제 중...",
-    delete: "삭제",
-    deleting: "삭제 중...",
+    delete: "보관",
+    deleting: "보관 중...",
     openFullView: "전체 보기 열기",
     removeFromWidgetArea: "이 위젯 영역에서 제거",
-    deleteExtensionEllipsis: "확장 프로그램 삭제...",
+    deleteExtensionEllipsis: "확장 프로그램 보관...",
     removeFromMyListEllipsis: "내 목록에서 제거...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "이렇게 하면 확장 프로그램을 공유하는 모든 사람의 모든 위치에서 확장 프로그램이 제거됩니다.",
+      "이렇게 하면 확장 프로그램을 공유하는 모든 사람의 모든 위치에서 확장 프로그램이 보관됩니다.",
     addWidget: "위젯 추가",
     loading: "로드 중...",
     noWidgetsAvailable: "이 슬롯에는 아직 사용할 수 있는 위젯이 없습니다.",

package/src/templates/default/app/i18n/pt-BR.ts

@@ -353,24 +353,24 @@ const messages = {
     hideEveryone: "Esconda-se de todos",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "Arquivar {{name}}?",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "Isso o oculta da sua lista de extensões sem excluí-lo para mais ninguém.",
     removeEverywhereDescription:
-      "Isso o remove em todos os lugares em que é compartilhado.",
+      "Isso o arquiva em todos os lugares em que é compartilhado.",
     cancel: "Cancelar",
     remove: "Remover",
     removing: "Removendo...",
-    delete: "Excluir",
-    deleting: "Excluindo...",
+    delete: "Arquivar",
+    deleting: "Arquivando...",
     openFullView: "Abrir visualização completa",
     removeFromWidgetArea: "Remover desta área de widget",
-    deleteExtensionEllipsis: "Excluir extensão...",
+    deleteExtensionEllipsis: "Arquivar extensão...",
     removeFromMyListEllipsis: "Remover da minha lista...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "Isso remove a extensão de todos os lugares, para todas as pessoas com quem ela é compartilhada.",
+      "Isso arquiva a extensão em todos os lugares, para todas as pessoas com quem ela é compartilhada.",
     addWidget: "Adicionar widget",
     loading: "Carregando...",
     noWidgetsAvailable: "Ainda não há widgets disponíveis para este slot.",

package/src/templates/default/app/i18n/zh-CN.ts

@@ -330,22 +330,22 @@ const messages = {
     hideEveryone: "向所有人隐藏",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "要归档 {{name}} 吗？",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "这会将其从您的扩展列表中隐藏，而不会为其他任何人删除它。",
-    removeEverywhereDescription: "这会在共享的所有地方删除它。",
+    removeEverywhereDescription: "这会在共享的所有地方归档它。",
     cancel: "取消",
     remove: "移除",
-    removing: "正在删除...",
-    delete: "删除",
-    deleting: "正在删除...",
+    removing: "正在移除...",
+    delete: "归档",
+    deleting: "正在归档...",
     openFullView: "打开全视图",
     removeFromWidgetArea: "从此小部件区域中删除",
-    deleteExtensionEllipsis: "删除扩展...",
+    deleteExtensionEllipsis: "归档扩展...",
     removeFromMyListEllipsis: "从我的列表中删除...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
-    deleteEverywhereConfirmation: "这会删除所有与之共享的每个人的扩展程序。",
+    deleteEverywhereConfirmation: "这会为所有与之共享的人归档该扩展程序。",
     addWidget: "添加小部件",
     loading: "正在加载...",
     noWidgetsAvailable: "此插槽尚无可用的小部件。",

package/src/templates/default/app/i18n/zh-TW.ts

@@ -330,22 +330,22 @@ const messages = {
     hideEveryone: "向所有人隱藏",
     localFileDescription:
       "此擴充功能由 {{entryPath}} 支援。請從工作區編輯或移除它。",
-    deleteQuestion: "要刪除 {{name}} 嗎？",
+    deleteQuestion: "要封存 {{name}} 嗎？",
     removeQuestion: "要移除 {{name}} 嗎？",
     hideForYouDescription:
       "這會將其從您的擴充功能清單中隱藏，而不會為其他任何人刪除它。",
-    removeEverywhereDescription: "這會在共用的所有地方刪除它。",
+    removeEverywhereDescription: "這會在共用的所有地方封存它。",
     cancel: "取消",
     remove: "移除",
-    removing: "正在刪除...",
-    delete: "刪除",
-    deleting: "正在刪除...",
+    removing: "正在移除...",
+    delete: "封存",
+    deleting: "正在封存...",
     openFullView: "開啟全檢視",
     removeFromWidgetArea: "從此小工具區域中刪除",
-    deleteExtensionEllipsis: "刪除擴充功能...",
+    deleteExtensionEllipsis: "封存擴充功能...",
     removeFromMyListEllipsis: "從我的清單中刪除...",
     removeFromWidgetAreaForMe: "從這個小工具區域移除（只套用於我）",
-    deleteEverywhereConfirmation: "這會刪除所有與之共用的每個人的擴充功能。",
+    deleteEverywhereConfirmation: "這會為所有與之共用的人封存該擴充功能。",
     addWidget: "新增小工具",
     loading: "正在載入...",
     noWidgetsAvailable: "此插槽尚無可用的小工具。",

package/src/templates/default/app/root.tsx

@@ -23,6 +23,7 @@ import {
   useRouteError,
 } from "react-router";
 
+import { AppToolkitProvider } from "./components/ui/toolkit-provider";
 import { useNavigationState } from "./hooks/use-navigation-state";
 import { i18nCatalog } from "./i18n";
 import { TAB_ID } from "./lib/tab-id";
@@ -256,8 +257,10 @@ export default function Root() {
   const [queryClient] = useState(() => createAgentNativeQueryClient());
   return (
     <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
-      <DbSyncSetup />
-      <Outlet />
+      <AppToolkitProvider>
+        <DbSyncSetup />
+        <Outlet />
+      </AppToolkitProvider>
     </AppProviders>
   );
 }

package/src/templates/default/package.json

@@ -15,6 +15,7 @@
   },
   "dependencies": {
     "@agent-native/core": "latest",
+    "@agent-native/toolkit": "latest",
     "@assistant-ui/react": "^0.12.19",
     "@assistant-ui/react-markdown": "^0.12.6",
     "@fontsource-variable/inter": "^5.2.8",

package/src/templates/headless/.agents/skills/agent-native-toolkit/SKILL.md

@@ -47,6 +47,34 @@ Before creating an app-local version of repeated workspace or agent UI:
 Use public package exports at runtime. Published source and ejection manifests
 are discovery and ownership-transfer mechanisms, not private runtime APIs.
 
+## Design-System Boundary
+
+Every app keeps an explicit design-system seam in `app/design-system.ts` using
+`defineDesignSystem` from `@agent-native/toolkit/design-system`, and supplies it
+to `ToolkitProvider`. The semantic contract contains:
+
+- nine leaf components: `ActionButton`, `IconButton`, `TextField`, `TextArea`,
+  `Spinner`, `Skeleton`, `Status`, `Surface`, and `Avatar`
+- eight behavior components: `Tooltip`, `Menu`, `Popover`, `Dialog`, `Picker`,
+  `Checkbox`, `Switch`, and `Tabs`
+
+These are semantic contracts, not styling contracts. An adapter may use
+Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,
+or another React design system. Do not assume CVA, utility classes, or even a
+`className`; behavior adapters may supply their overlay and focus
+implementation wholesale while honoring portal, focus-restoration, keyboard,
+dismissal, ARIA, and z-index interoperability.
+
+Pages, routes, and domain components import ordinary controls through the app's
+local adapter layer, usually `@/components/ui/*`. They must not import
+`@agent-native/toolkit/ui/*` directly. Toolkit feature exports are still the
+right home for shared workspace behavior; their presentation flows through the
+registered semantic components, feature controller, and product-level slots.
+
+Customer adapter packages are normal npm packages imported explicitly by the
+app. Never auto-detect them or load React components from JSON. Run the adapter
+against `@agent-native/toolkit/conformance` in customer CI before adopting it.
+
 ## Settings Direction
 
 Durable settings belong in the Settings app or a registered settings route. The
@@ -59,6 +87,12 @@ quick controls and deep links such as:
 - `/settings/usage`
 - `/settings/apps/:appId`
 
+The shared Account section is the canonical profile surface at
+`/settings#account`. It owns the editable display name and existing avatar
+control through the authenticated `get-user-profile` and `update-user-profile`
+actions. Shared workspace chrome such as `OrgSwitcher` should link to this
+surface rather than creating an app-local profile page.
+
 When adding a new API key, OAuth grant, provider connection, model selector, app
 preference, notification preference, or usage/billing surface, register it as a
 settings tab or app settings panel first. Only add sidebar UI when it is needed
@@ -107,8 +141,9 @@ in the moment of agent use.
 When adding or refactoring one of these areas:
 
 1. Search existing framework and template code for duplicated UI or actions.
-2. Decide the shared contract: data shape, action API, React component/hook, and
-   app adapter points.
+2. Decide the shared contract: data shape, action API, feature-level headless
+   controller, default view, semantic components, and product-level render
+   slots.
 3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
 4. Expose the same capability to the UI and agent through actions or documented
    client helpers.
@@ -119,6 +154,12 @@ When adding or refactoring one of these areas:
    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.
+8. Keep one controller as the source of truth for the default and custom render
+   paths. A custom design must not fork actions, analytics, async state, or
+   accessibility behavior.
+9. Verify the default adapter and at least one non-Tailwind adapter with the
+   conformance kit, including focus and portal stacking across mixed overlay
+   implementations.
 
 ## Related Skills
 

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

@@ -13,22 +13,93 @@ metadata:
 
 ## Rule
 
-Start with the public component and its props, slots, callbacks, and stable
-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.
+Start with the app's registered design system and local UI adapters, then use
+the public feature's props, semantic components, controller, product slots,
+and callbacks. 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. Eject the smallest feature into app-owned source.
-4. Propose a new Toolkit seam when the same override is useful in two apps.
+1. Set brand tokens with the build-time theme configuration when tokens are
+   enough.
+2. Register company components in `app/design-system.ts` with
+   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
+3. Configure a public feature through its semantic components, headless
+   controller, and product-level render slots.
+4. Compose app primitives behind the app's local UI adapter layer.
+5. Eject the smallest feature into app-owned source.
+6. Propose a new Toolkit seam when the same override is useful in two apps.
 
 Ejection is for intentional product customization, not for hiding an upgrade
 failure or replacing Core runtime behavior.
 
+## Use A Company Design System
+
+Keep the explicit, typed registration seam in `app/design-system.ts`:
+
+```tsx
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+import {
+  AcmeActionButtonAdapter,
+  AcmeDialogAdapter,
+} from "./design-system/acme-adapter";
+
+export const designSystem = defineDesignSystem({
+  name: "Acme",
+  components: {
+    ActionButton: AcmeActionButtonAdapter,
+    Dialog: AcmeDialogAdapter,
+  },
+});
+```
+
+Adapters translate the semantic Toolkit contract into company component props.
+They are ordinary React components and may use MUI-style providers, React Aria,
+CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
+optional interoperability hooks, not Tailwind or CVA requirements.
+
+The contract has nine leaf components (`ActionButton`, `IconButton`,
+`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
+and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
+`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
+behavior, not date picking. Behavior adapters own their portal, focus,
+keyboard, dismissal, and stacking implementation while honoring the semantic
+props and `portalContainer` interop contract.
+
+App product code imports standard controls from its local adapter path, usually
+`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
+pages, routes, or domain components. That bypasses the app seam and makes a
+future design-system replacement incomplete. Toolkit feature packages remain
+valid imports; configure their presentation through the registered semantic
+components, controller, and product slots.
+
+Run the published conformance kit against a complete adapter in its own CI:
+
+```tsx
+import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
+
+await assertDesignSystemConformance({
+  adapterName: "Acme",
+  components,
+  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+});
+```
+
+New components and optional props are minor contract changes. Required props,
+removed APIs, or behavioral changes require a new contract major.
+
+## Customize A Shared Feature
+
+Prefer feature-level headless controllers over rebuilding individual widgets.
+One controller must power both the Toolkit default view and every custom render
+path so behavior, actions, analytics, accessibility state, and error handling
+cannot drift. Use a product-level render slot to replace the view while keeping
+that controller. Eject only when the controller and slots cannot express the
+required product behavior.
+
 ## Eject A Feature
 
 Discover and inspect the ejection units published by installed first-party
@@ -104,11 +175,14 @@ UI ownership may change; product contracts should not:
   Core. Do not copy those runtimes into the app.
 - Keep local adapters narrow so package upgrades still improve every surface
   the app has not intentionally taken ownership of.
+- Keep page, route, and domain code on local UI adapter imports. Never reach
+  around the registered design system with direct Toolkit UI primitive imports.
 
 ## App Shapes
 
-- **Template app:** begin with its existing local adapters and domain UI. Use
-  Toolkit for repeated workspace UI; eject only the unit being customized.
+- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
+  and domain UI. Use Toolkit features for repeated workspace behavior; eject
+  only the unit being customized.
 - **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
   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,
@@ -135,6 +209,7 @@ UI ownership may change; product contracts should not:
 - Don't copy Core auth, DB, action, agent-loop, or transport internals.
 - 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.
+- Don't fork feature state into a custom view; consume the feature's controller.
 
 ## Related Skills
 

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

@@ -47,6 +47,34 @@ Before creating an app-local version of repeated workspace or agent UI:
 Use public package exports at runtime. Published source and ejection manifests
 are discovery and ownership-transfer mechanisms, not private runtime APIs.
 
+## Design-System Boundary
+
+Every app keeps an explicit design-system seam in `app/design-system.ts` using
+`defineDesignSystem` from `@agent-native/toolkit/design-system`, and supplies it
+to `ToolkitProvider`. The semantic contract contains:
+
+- nine leaf components: `ActionButton`, `IconButton`, `TextField`, `TextArea`,
+  `Spinner`, `Skeleton`, `Status`, `Surface`, and `Avatar`
+- eight behavior components: `Tooltip`, `Menu`, `Popover`, `Dialog`, `Picker`,
+  `Checkbox`, `Switch`, and `Tabs`
+
+These are semantic contracts, not styling contracts. An adapter may use
+Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,
+or another React design system. Do not assume CVA, utility classes, or even a
+`className`; behavior adapters may supply their overlay and focus
+implementation wholesale while honoring portal, focus-restoration, keyboard,
+dismissal, ARIA, and z-index interoperability.
+
+Pages, routes, and domain components import ordinary controls through the app's
+local adapter layer, usually `@/components/ui/*`. They must not import
+`@agent-native/toolkit/ui/*` directly. Toolkit feature exports are still the
+right home for shared workspace behavior; their presentation flows through the
+registered semantic components, feature controller, and product-level slots.
+
+Customer adapter packages are normal npm packages imported explicitly by the
+app. Never auto-detect them or load React components from JSON. Run the adapter
+against `@agent-native/toolkit/conformance` in customer CI before adopting it.
+
 ## Settings Direction
 
 Durable settings belong in the Settings app or a registered settings route. The
@@ -59,6 +87,12 @@ quick controls and deep links such as:
 - `/settings/usage`
 - `/settings/apps/:appId`
 
+The shared Account section is the canonical profile surface at
+`/settings#account`. It owns the editable display name and existing avatar
+control through the authenticated `get-user-profile` and `update-user-profile`
+actions. Shared workspace chrome such as `OrgSwitcher` should link to this
+surface rather than creating an app-local profile page.
+
 When adding a new API key, OAuth grant, provider connection, model selector, app
 preference, notification preference, or usage/billing surface, register it as a
 settings tab or app settings panel first. Only add sidebar UI when it is needed
@@ -107,8 +141,9 @@ in the moment of agent use.
 When adding or refactoring one of these areas:
 
 1. Search existing framework and template code for duplicated UI or actions.
-2. Decide the shared contract: data shape, action API, React component/hook, and
-   app adapter points.
+2. Decide the shared contract: data shape, action API, feature-level headless
+   controller, default view, semantic components, and product-level render
+   slots.
 3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
 4. Expose the same capability to the UI and agent through actions or documented
    client helpers.
@@ -119,6 +154,12 @@ When adding or refactoring one of these areas:
    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.
+8. Keep one controller as the source of truth for the default and custom render
+   paths. A custom design must not fork actions, analytics, async state, or
+   accessibility behavior.
+9. Verify the default adapter and at least one non-Tailwind adapter with the
+   conformance kit, including focus and portal stacking across mixed overlay
+   implementations.
 
 ## Related Skills
 

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

@@ -13,22 +13,93 @@ metadata:
 
 ## Rule
 
-Start with the public component and its props, slots, callbacks, and stable
-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.
+Start with the app's registered design system and local UI adapters, then use
+the public feature's props, semantic components, controller, product slots,
+and callbacks. 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. Eject the smallest feature into app-owned source.
-4. Propose a new Toolkit seam when the same override is useful in two apps.
+1. Set brand tokens with the build-time theme configuration when tokens are
+   enough.
+2. Register company components in `app/design-system.ts` with
+   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
+3. Configure a public feature through its semantic components, headless
+   controller, and product-level render slots.
+4. Compose app primitives behind the app's local UI adapter layer.
+5. Eject the smallest feature into app-owned source.
+6. Propose a new Toolkit seam when the same override is useful in two apps.
 
 Ejection is for intentional product customization, not for hiding an upgrade
 failure or replacing Core runtime behavior.
 
+## Use A Company Design System
+
+Keep the explicit, typed registration seam in `app/design-system.ts`:
+
+```tsx
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+import {
+  AcmeActionButtonAdapter,
+  AcmeDialogAdapter,
+} from "./design-system/acme-adapter";
+
+export const designSystem = defineDesignSystem({
+  name: "Acme",
+  components: {
+    ActionButton: AcmeActionButtonAdapter,
+    Dialog: AcmeDialogAdapter,
+  },
+});
+```
+
+Adapters translate the semantic Toolkit contract into company component props.
+They are ordinary React components and may use MUI-style providers, React Aria,
+CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
+optional interoperability hooks, not Tailwind or CVA requirements.
+
+The contract has nine leaf components (`ActionButton`, `IconButton`,
+`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
+and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
+`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
+behavior, not date picking. Behavior adapters own their portal, focus,
+keyboard, dismissal, and stacking implementation while honoring the semantic
+props and `portalContainer` interop contract.
+
+App product code imports standard controls from its local adapter path, usually
+`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
+pages, routes, or domain components. That bypasses the app seam and makes a
+future design-system replacement incomplete. Toolkit feature packages remain
+valid imports; configure their presentation through the registered semantic
+components, controller, and product slots.
+
+Run the published conformance kit against a complete adapter in its own CI:
+
+```tsx
+import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
+
+await assertDesignSystemConformance({
+  adapterName: "Acme",
+  components,
+  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+});
+```
+
+New components and optional props are minor contract changes. Required props,
+removed APIs, or behavioral changes require a new contract major.
+
+## Customize A Shared Feature
+
+Prefer feature-level headless controllers over rebuilding individual widgets.
+One controller must power both the Toolkit default view and every custom render
+path so behavior, actions, analytics, accessibility state, and error handling
+cannot drift. Use a product-level render slot to replace the view while keeping
+that controller. Eject only when the controller and slots cannot express the
+required product behavior.
+
 ## Eject A Feature
 
 Discover and inspect the ejection units published by installed first-party
@@ -104,11 +175,14 @@ UI ownership may change; product contracts should not:
   Core. Do not copy those runtimes into the app.
 - Keep local adapters narrow so package upgrades still improve every surface
   the app has not intentionally taken ownership of.
+- Keep page, route, and domain code on local UI adapter imports. Never reach
+  around the registered design system with direct Toolkit UI primitive imports.
 
 ## App Shapes
 
-- **Template app:** begin with its existing local adapters and domain UI. Use
-  Toolkit for repeated workspace UI; eject only the unit being customized.
+- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
+  and domain UI. Use Toolkit features for repeated workspace behavior; eject
+  only the unit being customized.
 - **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
   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,
@@ -135,6 +209,7 @@ UI ownership may change; product contracts should not:
 - Don't copy Core auth, DB, action, agent-loop, or transport internals.
 - 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.
+- Don't fork feature state into a custom view; consume the feature's controller.
 
 ## Related Skills
 

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

@@ -57,10 +57,26 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 
 ## Agent-Native UI Rules
 
-- Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.
-- **Use shadcn/ui primitives for standard UI**: `DropdownMenu`, `Popover`, `Dialog`, `AlertDialog`, `Sheet`, `Tabs`, `Tooltip`, `Select`, `Command`, `Sidebar`, `Table`, `Card`, `Badge`, `Skeleton`, and related primitives.
+- Agent-native apps use React and Vite. The default adapter uses Tailwind CSS,
+  shadcn/ui, and `@tabler/icons-react`, but an app may register a different
+  company design system in `app/design-system.ts`.
+- **Use the app's design-system seam for standard UI.** Inspect
+  `app/design-system.ts`, `ToolkitProvider`, and the local UI adapter directory
+  before choosing a primitive. Use shadcn primitives when they are the active
+  adapter; use the registered company components when they are not.
 - **When touching shadcn/ui components, also read `shadcn-ui` if it exists.** That skill covers `components.json`, CLI docs, component composition, theming, and registry workflows.
 - Check `app/components/ui/` before importing a shadcn component. If a primitive is missing, add it from the app root with `pnpm dlx shadcn@latest add <component>`, then review the generated file.
+- Pages, routes, and domain components must import controls through the app's
+  local adapter path, usually `@/components/ui/*`. Never import
+  `@agent-native/toolkit/ui/*` directly in app product code.
+- Toolkit/Core feature presentation flows through the semantic components from
+  `@agent-native/toolkit/design-system`. Their props express intent, emphasis,
+  size, controlled values, and behavior; they do not require Tailwind, CVA, or
+  `className`.
+- For deeper feature customization, consume the feature-level headless
+  controller through its product render slot. The same controller must power
+  the default and custom views. Eject the smallest supported unit only after
+  tokens, semantic components, controllers, and slots are insufficient.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
@@ -103,10 +119,14 @@ For substantial frontend work:
 2. Start the dev server when the app needs one.
 3. Verify with browser screenshots at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
+5. When registering or changing a company adapter, run
+   `@agent-native/toolkit/conformance`, including mixed-overlay focus,
+   `portalContainer`, and z-index stacking checks.
 
 ## Related Skills
 
 - **shadcn-ui** — shadcn CLI, component docs, composition rules, theming, and registries
+- **customizing-agent-native** — Design-system registration, feature controllers, product slots, conformance, and ejection
 - **self-modifying-code** — The agent can edit source code to apply design changes
 - **storing-data** — All data lives in SQL; use actions for data access
 - **actions** — `useActionQuery`/`useActionMutation` hooks for frontend data fetching