@agent-native/core 0.117.1 → 0.118.0

package/src/localization/default-messages.ts

@@ -32,6 +32,27 @@ const messages = {
     openTeamSettings: "Open team settings",
     openResourceSettings: "Open resource settings",
     backHome: "Back to home",
+    mcpConnectionsTitle: "MCP connections",
+    mcpConnectionsDescription:
+      "Connect remote MCP servers so the agent can use their tools.",
+    openMcpConnections: "Manage MCP connections",
+    profileTitle: "Account",
+    profileDescription: "Your name, profile photo, and signed-in identity.",
+    profileLoading: "Loading...",
+    profileSignedOut: "Signed out",
+    profilePhotoUpdated: "Photo updated",
+    profilePhotoError: "Could not update photo",
+    profileUploading: "Uploading...",
+    profileChangePhoto: "Change photo",
+    profileNameLabel: "Name",
+    profileNamePlaceholder: "Your name",
+    profileNameDescription:
+      "This name is used when referring to you across Agent-Native apps.",
+    profileSave: "Save changes",
+    profileSaving: "Saving...",
+    profileSaved: "Profile updated",
+    profileSaveError: "Could not update profile",
+    profileMenuItem: "Profile",
   },
   agentResources: {
     openDocs: "Open {{section}} documentation",
@@ -315,6 +336,7 @@ const messages = {
     addOwnKeys: "Add your own keys",
     configureProviderKeys: "Configure Anthropic, OpenAI, or another provider",
     checkingAiConnection: "Checking AI connection...",
+    connectionUnavailable: "Unable to check AI connection. Click to retry.",
     voiceMode: {
       entryButtonLabel: "Use microphone",
       promptTitle: "Use your voice",
@@ -634,23 +656,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/src/mcp-client/oauth-routes.ts

@@ -54,6 +54,20 @@ export interface McpOAuthRoutesOptions {
   reconfigure: () => Promise<void>;
 }
 
+export function redirectWithStagedCookies(
+  event: H3Event,
+  location: string,
+): Response {
+  const headers = new Headers({
+    Location: location,
+    "Cache-Control": "no-store",
+  });
+  for (const cookie of event.res?.headers?.getSetCookie?.() ?? []) {
+    headers.append("set-cookie", cookie);
+  }
+  return new Response(null, { status: 302, headers });
+}
+
 export function mountMcpOAuthRoutes(
   nitroApp: any,
   options: McpOAuthRoutesOptions,
@@ -182,7 +196,7 @@ async function handleMcpOAuthStart(
       path: "/",
       maxAge: FLOW_TTL_SECONDS,
     });
-    return Response.redirect(started.authorizationUrl.href, 302);
+    return redirectWithStagedCookies(event, started.authorizationUrl.href);
   } catch {
     setResponseStatus(event, 400);
     return {
@@ -254,7 +268,7 @@ async function handleMcpOAuthCallback(
     const returnPath =
       flow.returnUrl ??
       `/settings/connections?connected=mcp-${encodeURIComponent(flow.name)}`;
-    return Response.redirect(getAppUrl(event, returnPath), 302);
+    return redirectWithStagedCookies(event, getAppUrl(event, returnPath));
   } catch {
     setResponseStatus(event, 400);
     return { error: "MCP OAuth authorization could not be completed." };

package/src/scripts/call-agent.ts

@@ -443,7 +443,11 @@ export async function run(
       // Terminal states resolve the poll; "input-required" means the remote is
       // blocked waiting on us, not making progress. Only actively-working
       // states count as liveness worth surfacing.
-      const ACTIVELY_WORKING_STATES = new Set(["working", "submitted"]);
+      const ACTIVELY_WORKING_STATES = new Set([
+        "working",
+        "submitted",
+        "processing",
+      ]);
       const callStartedAt = Date.now();
       let lastProgressEmitAt = callStartedAt;
       const onRemotePollUpdate = (task: Task) => {

package/src/server/action-discovery.ts

@@ -658,6 +658,14 @@ export async function mergeCoreSharingActions(
       "set-localization-preference",
       () => import("../localization/actions/set-localization-preference.js"),
     ],
+    [
+      "get-user-profile",
+      () => import("../user-profile/actions/get-user-profile.js"),
+    ],
+    [
+      "update-user-profile",
+      () => import("../user-profile/actions/update-user-profile.js"),
+    ],
     [
       "change-appearance",
       () => import("../appearance/actions/change-appearance.js"),

package/src/server/better-auth-instance.ts

@@ -740,8 +740,8 @@ export function getBetterAuthSync(): BetterAuthInstance | undefined {
  * The subset of Better Auth's internal adapter we use for federated-SSO
  * JIT account linking. Better Auth owns these writes (id + timestamp +
  * schema handling), so callers never hand-roll SQL against `user`/`account`.
- * Read-only lookups + strictly-additive `linkAccount`/`createUser` only — no
- * update/delete of existing identity rows.
+ * Read-only lookups plus account-linking and profile-update operations used by
+ * shared Core surfaces. Better Auth owns the actual identity writes.
  */
 export interface BetterAuthInternalAdapter {
   findUserByEmail: (
@@ -761,6 +761,11 @@ export interface BetterAuthInternalAdapter {
     name: string;
     emailVerified?: boolean;
   }) => Promise<{ id: string }>;
+  /** Optional because older/custom adapter shapes may not expose mutations. */
+  updateUser?: (
+    userId: string,
+    data: { name?: string; image?: string | null },
+  ) => Promise<unknown>;
 }
 
 /**

package/src/server/email-template.ts

@@ -18,6 +18,10 @@
  *   });
  */
 
+import { getAppName } from "./app-name.js";
+
+export const AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID = "agent-native-logo";
+
 export interface EmailCta {
   label: string;
   url: string;
@@ -34,6 +38,8 @@ export interface RenderEmailArgs {
   cta?: EmailCta;
   /** Small muted text under the CTA (e.g. expiry note). */
   footer?: string;
+  /** Optional app name shown beside the framework logo. */
+  brandName?: string;
   /**
    * Optional brand hex color for the CTA button and inline links. Defaults to
    * a monochrome near-white button with dark text.
@@ -71,6 +77,7 @@ function sanitizeHexColor(input: string | undefined): string | undefined {
 export function renderEmail(args: RenderEmailArgs): RenderedEmail {
   const preheader = args.preheader || "";
   const brand = sanitizeHexColor(args.brandColor);
+  const brandName = args.brandName?.trim() || getAppName() || "Agent Native";
 
   // Monochrome default: near-white button with dark text. Brand override:
   // colored button with white text.
@@ -104,6 +111,16 @@ export function renderEmail(args: RenderEmailArgs): RenderedEmail {
     ? `<p style="margin:28px 0 0 0; font-size:13px; line-height:1.5; color:#71717a;">${escapeHtml(args.footer)}</p>`
     : "";
 
+  const brandHeaderHtml = `
+                <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" style="margin:0 0 28px 0; padding:0 0 24px 0; border-bottom:1px solid #27272a;">
+                  <tr>
+                    <td align="center">
+                      <img src="cid:${AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID}" alt="${escapeAttr(brandName)}" width="28" height="28" style="display:inline-block; vertical-align:middle; width:28px; height:28px; margin:0 8px 0 0; border:0;" />
+                      <span style="font-size:18px; line-height:28px; font-weight:600; color:#fafafa; vertical-align:middle;">${escapeHtml(brandName)}</span>
+                    </td>
+                  </tr>
+                </table>`;
+
   const html = `<!DOCTYPE html>
 <html lang="en">
   <head>
@@ -129,6 +146,7 @@ export function renderEmail(args: RenderEmailArgs): RenderedEmail {
           <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" style="max-width:560px;">
             <tr>
               <td style="background-color:#141417; border:1px solid #27272a; border-radius:16px; padding:36px 36px 32px 36px;">
+                ${brandHeaderHtml}
                 <h1 style="margin:0 0 20px 0; font-size:24px; line-height:1.3; font-weight:600; color:#fafafa; letter-spacing:-0.02em;">
                   ${escapeHtml(args.heading)}
                 </h1>

package/src/server/email-templates.ts

@@ -58,6 +58,7 @@ export function renderInviteEmail(
   const onApp = appName ? ` on ${appName}` : "";
 
   const { html, text } = renderEmail({
+    brandName: appName,
     preheader: `${inviter} invited you to join ${orgName}${onApp}.`,
     heading: `You're invited to join ${orgName}`,
     paragraphs: [
@@ -95,6 +96,7 @@ export function renderVerifySignupEmail(
   const appName = resolveAppName();
 
   const { html, text } = renderEmail({
+    brandName: appName,
     preheader: `Confirm ${email} to finish setting up your ${appName} account.`,
     heading: `Verify your email for ${appName}`,
     paragraphs: [
@@ -130,6 +132,7 @@ export function renderResetPasswordEmail(
   const appName = resolveAppName();
 
   const { html, text } = renderEmail({
+    brandName: appName,
     preheader: `Reset the password for ${email}. This link expires in 1 hour.`,
     heading: `Reset your ${appName} password`,
     paragraphs: [

package/src/server/email.ts

@@ -10,7 +10,10 @@
  * so the reset-password flow still works end-to-end for local development.
  */
 
+import { readFileSync } from "node:fs";
+
 import { resolveSecret } from "./credential-provider.js";
+import { AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID } from "./email-template.js";
 
 export type EmailProvider = "resend" | "sendgrid" | "dev";
 
@@ -35,6 +38,38 @@ export interface SendEmailArgs {
   attachments?: EmailAttachment[];
 }
 
+let cachedAgentNativeLogo: Buffer | undefined;
+
+function getAgentNativeLogoAttachment(): EmailAttachment {
+  cachedAgentNativeLogo ??= readFileSync(
+    new URL("../../src/assets/branding/favicon.png", import.meta.url),
+  );
+  return {
+    filename: "agent-native-logo.png",
+    content: cachedAgentNativeLogo,
+    contentType: "image/png",
+    contentId: AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID,
+    disposition: "inline",
+  };
+}
+
+function resolveAttachments(
+  args: SendEmailArgs,
+): EmailAttachment[] | undefined {
+  if (!args.html.includes(`cid:${AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID}`)) {
+    return args.attachments;
+  }
+  if (
+    args.attachments?.some(
+      (attachment) =>
+        attachment.contentId === AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID,
+    )
+  ) {
+    return args.attachments;
+  }
+  return [...(args.attachments ?? []), getAgentNativeLogoAttachment()];
+}
+
 interface EmailTransportConfig {
   provider: EmailProvider;
   resendApiKey?: string;
@@ -94,6 +129,7 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
   const config = await resolveEmailTransport();
   const provider = config.provider;
   const from = getFromAddress(config, args.from);
+  const attachments = resolveAttachments(args);
 
   if (provider === "resend") {
     const payload: Record<string, unknown> = {
@@ -105,8 +141,8 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
     };
     if (args.cc) payload.cc = Array.isArray(args.cc) ? args.cc : [args.cc];
     if (args.replyTo) payload.reply_to = args.replyTo;
-    if (args.attachments?.length) {
-      payload.attachments = args.attachments.map((a) => ({
+    if (attachments?.length) {
+      payload.attachments = attachments.map((a) => ({
         filename: a.filename,
         content:
           typeof a.content === "string"
@@ -159,8 +195,8 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
     if (args.inReplyTo) sgHeaders["In-Reply-To"] = args.inReplyTo;
     if (args.references) sgHeaders["References"] = args.references;
     if (Object.keys(sgHeaders).length) sgPayload.headers = sgHeaders;
-    if (args.attachments?.length) {
-      sgPayload.attachments = args.attachments.map((a) => ({
+    if (attachments?.length) {
+      sgPayload.attachments = attachments.map((a) => ({
         filename: a.filename,
         content:
           typeof a.content === "string"

package/src/server/realtime-voice.ts

@@ -646,7 +646,7 @@ function createSessionHandler(
               },
               turn_detection: {
                 type: "semantic_vad",
-                create_response: true,
+                create_response: false,
                 interrupt_response: true,
                 eagerness: "auto",
               },

package/src/sharing/actions/share-resource.ts

@@ -299,6 +299,7 @@ export default defineAction({
           process.env.APP_NAME || process.env.VITE_APP_NAME || "Agent Native";
         const subject = `${actor} shared "${resourceTitle}" with you on ${appName}`;
         const { html, text } = renderEmail({
+          brandName: appName,
           preheader: subject,
           heading: "You've been given access",
           paragraphs: [

package/src/styles/agent-native.css

@@ -927,35 +927,11 @@
   display: inline-block;
 }
 
-.agent-tool-call {
-  position: relative;
-}
-
 @media (prefers-reduced-motion: no-preference) {
   .agent-tool-call--entering {
     animation: agent-tool-call-enter 220ms var(--ease-out-strong) both;
   }
 
-  .agent-tool-call[data-active-tail="true"]::after {
-    position: absolute;
-    z-index: 1;
-    inset: 0 0 auto;
-    height: 2rem;
-    pointer-events: none;
-    content: "";
-    background: linear-gradient(
-      90deg,
-      transparent 0%,
-      transparent 38%,
-      hsl(var(--foreground) / 0.055) 50%,
-      transparent 62%,
-      transparent 100%
-    );
-    background-repeat: repeat;
-    background-size: 14rem 100%;
-    animation: agent-thinking-shine 2.6s linear infinite;
-  }
-
   @supports ((background-clip: text) or (-webkit-background-clip: text)) {
     .agent-thinking-indicator__text,
     .agent-running-shimmer {

package/src/templates/chat/.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/chat/.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/chat/.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