@agent-native/core 0.117.1 → 0.118.0

package/corpus/core/src/templates/default/.agents/skills/shadcn-ui/SKILL.md

@@ -17,10 +17,33 @@ This skill keeps shadcn/ui work project-aware. Components are source files in th
 ## First Steps
 
 1. Work from the app root that owns `components.json`.
-2. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
-3. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
-4. Check `app/components/ui/` or the resolved `ui` path before importing a component.
-5. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+2. In an Agent Native app, inspect `app/design-system.ts` and
+   `ToolkitProvider` before choosing a primitive. A registered company design
+   system takes precedence over the default shadcn adapter.
+3. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
+4. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
+5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
+6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+
+## Agent Native Adapter Rule
+
+Pages, routes, and domain components import controls through the app's local UI
+adapter layer. Never import `@agent-native/toolkit/ui/*` directly in app product
+code. Direct imports bypass `app/design-system.ts` and make Toolkit/Core
+surfaces use different controls from the app.
+
+When shadcn is the app's adapter, add or update the local primitive and keep
+product code on that local import. When a company design system is registered,
+adapt its components to the semantic contracts from
+`@agent-native/toolkit/design-system`; do not recreate a parallel shadcn
+surface. The semantic API is styling-runtime agnostic, so do not require
+Tailwind, CVA, or `className` in customer adapters.
+
+For shared Toolkit features, customize presentation through semantic
+components, a feature-level controller, and product-level render slots. Keep
+the same controller for default and custom views. Use the conformance kit for
+behavior components whose focus, portal, keyboard, dismissal, or stacking
+behavior comes from the company design system.
 
 ## Adding Or Updating Components
 
@@ -91,5 +114,6 @@ Do not wrap triggers in extra divs just to place a Button or Link inside them.
 ## Related Skills
 
 - **frontend-design** — Product UX, visual direction, responsive polish, and verification
+- **customizing-agent-native** — Registered design systems, controllers, slots, conformance, and ejection
 - **actions** — Data fetching and mutation patterns for agent-native apps
 - **security** — User data, forms, external input, and action safety

package/corpus/core/src/templates/default/app/components/ui/toolkit-provider.tsx

@@ -0,0 +1,10 @@
+import { ToolkitProvider } from "@agent-native/toolkit/provider";
+import type { ReactNode } from "react";
+
+import { designSystem } from "@/design-system";
+
+export function AppToolkitProvider({ children }: { children: ReactNode }) {
+  return (
+    <ToolkitProvider designSystem={designSystem}>{children}</ToolkitProvider>
+  );
+}

package/corpus/core/src/templates/default/app/design-system.ts

@@ -0,0 +1,3 @@
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+
+export const designSystem = defineDesignSystem({});

package/corpus/core/src/templates/default/app/global.css

@@ -52,7 +52,7 @@
   --muted-foreground: 0 0% 60%;
   --accent: 0 0% 18%;
   --accent-foreground: 0 0% 90%;
-  --destructive: 0 63% 51%;
+  --destructive: 0 84% 60%;
   --destructive-foreground: 0 0% 98%;
   --border: 0 0% 24%;
   --input: 0 0% 24%;

package/corpus/core/src/templates/default/app/i18n/ar-SA.ts

@@ -359,24 +359,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/corpus/core/src/templates/default/app/i18n/de-DE.ts

@@ -352,24 +352,24 @@ const messages = {
     hideEveryone: "Versteck dich vor allen",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "{{name}} archivieren?",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "Dadurch wird es aus Ihrer Erweiterungsliste ausgeblendet, ohne dass es für andere gelöscht wird.",
     removeEverywhereDescription:
-      "Dadurch wird es überall dort entfernt, wo es geteilt wird.",
+      "Dadurch wird es überall dort archiviert, wo es geteilt wird.",
     cancel: "Abbrechen",
     remove: "Entfernen",
     removing: "Entfernen...",
-    delete: "Löschen",
-    deleting: "Wird gelöscht...",
+    delete: "Archivieren",
+    deleting: "Wird archiviert...",
     openFullView: "Vollansicht öffnen",
     removeFromWidgetArea: "Aus diesem Widget-Bereich entfernen",
-    deleteExtensionEllipsis: "Erweiterung löschen...",
+    deleteExtensionEllipsis: "Erweiterung archivieren...",
     removeFromMyListEllipsis: "Von meiner Liste entfernen...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "Dadurch wird die Erweiterung überall und für alle entfernt, mit denen sie geteilt wird.",
+      "Dadurch wird die Erweiterung überall und für alle archiviert, mit denen sie geteilt wird.",
     addWidget: "Widget hinzufügen",
     loading: "Wird geladen...",
     noWidgetsAvailable: "Für diesen Slot sind noch keine Widgets verfügbar.",

package/corpus/core/src/templates/default/app/i18n/en-US.ts

@@ -344,23 +344,23 @@ const messages = {
     hideEveryone: "Hide from everyone",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "Archive {{name}}?",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "This hides it from your Extensions list without deleting it for anyone else.",
-    removeEverywhereDescription: "This removes it everywhere it is shared.",
+    removeEverywhereDescription: "This archives it everywhere it is shared.",
     cancel: "Cancel",
     remove: "Remove",
     removing: "Removing...",
-    delete: "Delete",
-    deleting: "Deleting...",
+    delete: "Archive",
+    deleting: "Archiving...",
     openFullView: "Open full view",
     removeFromWidgetArea: "Remove from this widget area",
-    deleteExtensionEllipsis: "Delete extension...",
+    deleteExtensionEllipsis: "Archive extension...",
     removeFromMyListEllipsis: "Remove from my list...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "This removes the extension everywhere, for everyone it's shared with.",
+      "This archives the extension everywhere, for everyone it's shared with.",
     addWidget: "Add widget",
     loading: "Loading...",
     noWidgetsAvailable: "No widgets available for this slot yet.",

package/corpus/core/src/templates/default/app/i18n/es-ES.ts

@@ -355,24 +355,24 @@ const messages = {
     hideEveryone: "esconderse de todos",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "¿Archivar {{name}}?",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "Esto lo oculta de su lista de Extensiones sin eliminarlo para nadie más.",
     removeEverywhereDescription:
-      "Esto lo elimina en todos los lugares donde se comparte.",
+      "Esto lo archiva en todos los lugares donde se comparte.",
     cancel: "Cancelar",
     remove: "Eliminar",
     removing: "Eliminando...",
-    delete: "Eliminar",
-    deleting: "Eliminando...",
+    delete: "Archivar",
+    deleting: "Archivando...",
     openFullView: "Abrir vista completa",
     removeFromWidgetArea: "Eliminar de esta área de widgets",
-    deleteExtensionEllipsis: "Eliminar extensión...",
+    deleteExtensionEllipsis: "Archivar extensión...",
     removeFromMyListEllipsis: "Quitar de mi lista...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "Esto elimina la extensión en todas partes, para todas las personas con las que se comparte.",
+      "Esto archiva la extensión en todas partes, para todas las personas con las que se comparte.",
     addWidget: "Agregar widget",
     loading: "Cargando...",
     noWidgetsAvailable:

package/corpus/core/src/templates/default/app/i18n/fr-FR.ts

@@ -355,23 +355,23 @@ const messages = {
     hideEveryone: "Cacher de tout le monde",
     localFileDescription:
       "This extension is backed by {{entryPath}}. Edit or remove it from the workspace.",
-    deleteQuestion: "Delete {{name}}?",
+    deleteQuestion: "Archiver {{name}} ?",
     removeQuestion: "Remove {{name}}?",
     hideForYouDescription:
       "Cela le masque de votre liste d'extensions sans le supprimer pour quelqu'un d'autre.",
-    removeEverywhereDescription: "Cela le supprime partout où il est partagé.",
+    removeEverywhereDescription: "Cela l’archive partout où il est partagé.",
     cancel: "Annuler",
     remove: "Retirer",
     removing: "Suppression...",
-    delete: "Supprimer",
-    deleting: "Suppression...",
+    delete: "Archiver",
+    deleting: "Archivage...",
     openFullView: "Ouvrir la vue complète",
     removeFromWidgetArea: "Supprimer de cette zone de widget",
-    deleteExtensionEllipsis: "Supprimer l'extension...",
+    deleteExtensionEllipsis: "Archiver l'extension...",
     removeFromMyListEllipsis: "Supprimer de ma liste...",
     removeFromWidgetAreaForMe: "Remove from this widget area (for me)",
     deleteEverywhereConfirmation:
-      "Cela supprime l'extension partout, pour toutes les personnes avec lesquelles elle est partagée.",
+      "Cela archive l'extension partout, pour toutes les personnes avec lesquelles elle est partagée.",
     addWidget: "Ajouter un widget",
     loading: "Chargement...",
     noWidgetsAvailable:

package/corpus/core/src/templates/default/app/i18n/hi-IN.ts

@@ -338,24 +338,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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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