@agent-native/core 0.117.2 → 0.118.0

package/corpus/templates/clips/desktop/src/app.tsx

@@ -3682,91 +3682,95 @@ export function App() {
           />
         </div>
 
-        <ReadinessPanel
-          mode={mode}
-          cameraOn={cameraOn}
-          micOn={micOn}
-          includeVoicePaste={voiceDictationEnabled}
-          includeFnMonitoring={fnShortcutEnabled}
-          open={readinessOpen}
-          onOpenChange={updateReadinessOpen}
-          onOpenPermission={openPrivacySettings}
-        />
+        <div className="recorder-disclosures">
+          <ReadinessPanel
+            mode={mode}
+            cameraOn={cameraOn}
+            micOn={micOn}
+            includeVoicePaste={voiceDictationEnabled}
+            includeFnMonitoring={fnShortcutEnabled}
+            open={readinessOpen}
+            onOpenChange={updateReadinessOpen}
+            onOpenPermission={openPrivacySettings}
+          />
 
-        <section className="rewind-home-card" aria-label="Rewind">
-          <button
-            type="button"
-            className="rewind-home-summary"
-            aria-expanded={rewindHomeOpen}
-            onClick={() => setRewindHomeOpen((open) => !open)}
-          >
-            <span className="rewind-home-title">Rewind</span>
-            <span className="rewind-home-state">
-              {homeRewindOn ? "On" : "Off"}
-              {rewindHomeOpen ? (
-                <IconChevronDown size={13} stroke={2} />
-              ) : (
-                <IconChevronRight size={13} stroke={2} />
-              )}
-            </span>
-          </button>
-          {rewindHomeOpen ? (
-            <div className="rewind-home-details">
-              <p>{homeRewindPresentation.detail}</p>
-              <div className="rewind-home-detail-actions">
-                <div className="rewind-home-controls">
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <button
-                        type="button"
-                        className="rewind-agent-prompt-copy"
-                        onClick={() => void copyRewindAgentPrompt()}
-                        aria-label={
-                          rewindAgentPromptCopied
-                            ? "Setup prompt copied — paste it into your agent once"
-                            : "Copy setup prompt for your agent"
-                        }
-                      >
-                        {rewindAgentPromptCopied ? (
-                          <IconCircleCheck size={15} stroke={2} />
-                        ) : (
-                          <IconCopy size={15} stroke={1.9} />
-                        )}
-                      </button>
-                    </TooltipTrigger>
-                    <TooltipContent>
-                      {rewindAgentPromptCopied
-                        ? "Setup prompt copied"
-                        : "Copy setup prompt for your agent"}
-                    </TooltipContent>
-                  </Tooltip>
-                  <Switch
-                    on={homeRewindOn}
-                    disabled={
-                      homeScreenMemoryBusy || isRecording || recordingFlowActive
-                    }
-                    onChange={(remembering) =>
-                      void setHomeRewindRemembering(remembering)
-                    }
-                    label={
-                      featureConfig?.screenMemory?.enabled === true
-                        ? "Remember with Rewind"
-                        : "Set up Rewind"
-                    }
-                  />
+          <section className="rewind-home-card" aria-label="Rewind">
+            <button
+              type="button"
+              className="rewind-home-summary"
+              aria-expanded={rewindHomeOpen}
+              onClick={() => setRewindHomeOpen((open) => !open)}
+            >
+              <span className="rewind-home-title">Rewind</span>
+              <span className="rewind-home-state">
+                {homeRewindOn ? "On" : "Off"}
+                {rewindHomeOpen ? (
+                  <IconChevronDown size={11} stroke={2} />
+                ) : (
+                  <IconChevronRight size={11} stroke={2} />
+                )}
+              </span>
+            </button>
+            {rewindHomeOpen ? (
+              <div className="rewind-home-details">
+                <p>{homeRewindPresentation.detail}</p>
+                <div className="rewind-home-detail-actions">
+                  <button
+                    type="button"
+                    className="rewind-docs-link"
+                    onClick={openRewindDocs}
+                  >
+                    Learn about Rewind
+                    <IconExternalLink size={13} stroke={1.9} />
+                  </button>
+                  <div className="rewind-home-controls">
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <button
+                          type="button"
+                          className="rewind-agent-prompt-copy"
+                          onClick={() => void copyRewindAgentPrompt()}
+                          aria-label={
+                            rewindAgentPromptCopied
+                              ? "Setup prompt copied — paste it into your agent once"
+                              : "Copy setup prompt for your agent"
+                          }
+                        >
+                          {rewindAgentPromptCopied ? (
+                            <IconCircleCheck size={15} stroke={2} />
+                          ) : (
+                            <IconCopy size={15} stroke={1.9} />
+                          )}
+                        </button>
+                      </TooltipTrigger>
+                      <TooltipContent>
+                        {rewindAgentPromptCopied
+                          ? "Setup prompt copied"
+                          : "Copy setup prompt for your agent"}
+                      </TooltipContent>
+                    </Tooltip>
+                    <Switch
+                      on={homeRewindOn}
+                      disabled={
+                        homeScreenMemoryBusy ||
+                        isRecording ||
+                        recordingFlowActive
+                      }
+                      onChange={(remembering) =>
+                        void setHomeRewindRemembering(remembering)
+                      }
+                      label={
+                        featureConfig?.screenMemory?.enabled === true
+                          ? "Remember with Rewind"
+                          : "Set up Rewind"
+                      }
+                    />
+                  </div>
                 </div>
-                <button
-                  type="button"
-                  className="rewind-docs-link"
-                  onClick={openRewindDocs}
-                >
-                  Learn about Rewind
-                  <IconExternalLink size={13} stroke={1.9} />
-                </button>
               </div>
-            </div>
-          ) : null}
-        </section>
+            ) : null}
+          </section>
+        </div>
 
         {!isRecording ? (
           <button

package/corpus/templates/clips/desktop/src/styles.css

@@ -888,6 +888,12 @@ body[data-clips-route="recording-pill"] #root {
 /* Readiness disclosure                                                       */
 /* ------------------------------------------------------------------------- */
 
+.recorder-disclosures {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
 .readiness {
   border: none;
   border-radius: 0;
@@ -955,6 +961,12 @@ body[data-clips-route="recording-pill"] #root {
   line-height: 1;
 }
 
+.readiness-action svg,
+.rewind-home-state svg {
+  width: 11px;
+  height: 11px;
+}
+
 .readiness-open .readiness-action {
   color: var(--fg-muted);
 }
@@ -1401,6 +1413,7 @@ body[data-clips-route="recording-pill"] #root {
   display: inline-flex;
   align-items: center;
   gap: 8px;
+  margin-left: auto;
 }
 
 .rewind-docs-link {

package/corpus/templates/clips/desktop/src-tauri/src/lib.rs

@@ -458,7 +458,16 @@ pub fn run() {
             // login (tagged with `--autostart`) so it doesn't pop up every boot.
             let launched_at_login = std::env::args().any(|arg| arg == "--autostart");
             if !launched_at_login {
-                toggle_popover(app.handle());
+                let app_handle = app.handle().clone();
+                tauri::async_runtime::spawn(async move {
+                    for _ in 0..8 {
+                        tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+                        if tray::refresh_tray_anchor(&app_handle) {
+                            break;
+                        }
+                    }
+                    clips::force_show_popover(&app_handle);
+                });
             }
 
             Ok(())

package/corpus/templates/clips/desktop/src-tauri/src/shortcuts.rs

@@ -26,6 +26,41 @@ fn numpad_enter_shortcut() -> Shortcut {
     Shortcut::new(None, Code::NumpadEnter)
 }
 
+fn countdown_return_shortcuts() -> Vec<Shortcut> {
+    // Windows maps both keys to VK_RETURN, so registering both always fails.
+    #[cfg(target_os = "windows")]
+    {
+        vec![enter_shortcut()]
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        vec![enter_shortcut(), numpad_enter_shortcut()]
+    }
+}
+
+fn countdown_shortcuts() -> Vec<Shortcut> {
+    let mut shortcuts = vec![escape_shortcut()];
+    shortcuts.extend(countdown_return_shortcuts());
+    shortcuts
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn countdown_return_shortcuts_match_platform_registration() {
+        let shortcuts = countdown_return_shortcuts();
+        assert!(shortcuts.contains(&enter_shortcut()));
+
+        #[cfg(target_os = "windows")]
+        assert!(!shortcuts.contains(&numpad_enter_shortcut()));
+
+        #[cfg(not(target_os = "windows"))]
+        assert!(shortcuts.contains(&numpad_enter_shortcut()));
+    }
+}
+
 static CUSTOM_VOICE_SHORTCUT: OnceLock<Mutex<Option<Shortcut>>> = OnceLock::new();
 static CUSTOM_POPOVER_SHORTCUT: OnceLock<Mutex<Option<Shortcut>>> = OnceLock::new();
 static CUSTOM_RECORD_SHORTCUT: OnceLock<Mutex<Option<Shortcut>>> = OnceLock::new();
@@ -344,7 +379,7 @@ pub(crate) async fn prepare_countdown_shortcuts(app: AppHandle) -> Result<u64, S
         COUNTDOWN_SHORTCUTS_ACTIVE.store(true, Ordering::SeqCst);
         let gs = app.global_shortcut();
         let mut newly_registered = Vec::new();
-        for shortcut in [escape_shortcut(), enter_shortcut(), numpad_enter_shortcut()] {
+        for shortcut in countdown_shortcuts() {
             if !gs.is_registered(shortcut) {
                 if let Err(error) = gs.register(shortcut) {
                     for registered in newly_registered {
@@ -379,7 +414,7 @@ pub(crate) async fn finish_countdown_shortcuts(
         }
         COUNTDOWN_SHORTCUTS_ACTIVE.store(false, Ordering::SeqCst);
         let gs = app.global_shortcut();
-        for shortcut in [enter_shortcut(), numpad_enter_shortcut()] {
+        for shortcut in countdown_return_shortcuts() {
             if gs.is_registered(shortcut) {
                 let _ = gs.unregister(shortcut);
             }

package/corpus/templates/clips/desktop/src-tauri/src/tray.rs

@@ -11,6 +11,24 @@ use crate::tray_meetings::{build_meetings_section, handle_meeting_menu_click, Me
 use crate::util::{is_meeting_active, is_recording_active};
 use crate::TRAY_PNG;
 
+pub fn refresh_tray_anchor(app: &tauri::AppHandle) -> bool {
+    let Some(rect) = app
+        .tray_by_id("main")
+        .and_then(|tray| tray.rect().ok().flatten())
+    else {
+        return false;
+    };
+
+    let Some(anchor) = app.try_state::<TrayAnchor>() else {
+        return false;
+    };
+    let Ok(mut guard) = anchor.0.lock() else {
+        return false;
+    };
+    *guard = Some(rect);
+    true
+}
+
 /// Build the full tray menu with the given upcoming-meetings list. Used both
 /// at startup (with `Vec::new()`) and at refresh time when the meetings
 /// watcher pushes a new snapshot — `TrayIcon::set_menu(Some(...))` swaps the

package/corpus/templates/content/.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
@@ -113,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.
@@ -125,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/corpus/templates/content/.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/corpus/templates/content/.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

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