Skip to content

Router that virtually distributes inference across connected devices in the home.

Go

Add engineering guidance and service specifications

Terveab59120e5e90
diff --git a/.agents/skills/kaizen-ui/SKILL.md b/.agents/skills/kaizen-ui/SKILL.md
new file mode 100644
index 0000000..4eebf9b
--- /dev/null
+++ b/.agents/skills/kaizen-ui/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: kaizen-ui
+description: Kaizen UI (KUI) component library and design-pattern advisor for NVIDIA applications. Use whenever someone describes a UI to build, modify, or improve — even without explicit mention of KUI, "design pattern," or "best practice." Covers forms, filters, search, sort, cards, settings, activity feeds, navigation, data visualization, dashboards, loading states, empty states, feedback, iconography, element visibility, and page layout decisions. Also use when modifying existing UI (adding form fields, page sections, nav items, columns); before changes, evaluate whether the current structure still fits and propose restructuring if needed.
+metadata:
+ # what version of the package these skills are based on
+ version: '1.0.0'
+# For tanstack-intent
+type: core
+library: kaizen-ui
+library_version: '1.0.0'
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Kaizen UI (KUI)
+
+KUI has three parts, used together:
+
+- **React components** provide the semantic UI: `<Button>`, `<Card>`, `<FormField>`, `<Stack>`, `<Table>`, `<AppBar>`, etc.
+- **Layout utilities** — Tailwind's core utilities (`px-4`, `max-w-7xl`, `flex`) handle the space between components.
+- **Design tokens** — theme-aware values for colors, borders, and surfaces. Available via Tailwind utilities or CSS variables. See details in [DESIGN_TOKENS.md](./references/guides/DESIGN_TOKENS.md)
+
+| Example Token | Tailwind utility (only when Tailwind is configured) | CSS variable (for raw CSS or non-Tailwind contexts) |
+| -------------- | --------------------------------------------------- | --------------------------------------------------- |
+| Sunken surface | `bg-surface-sunken` | `--background-color-surface-sunken` |
+| Primary text | `text-primary` | `--color-text-primary` |
+| Base border | `border-base` | `--border-color-base` |
+
+## General Guidelines
+
+- Use KUI components over divs/custom elements.
+- KUI provides semantic CSS variables and Tailwind utilities for the design system — use these instead of standard Tailwind colors for brand consistency and automatic light/dark theme support.
+- No emojis.
+
+## References
+
+- [ICONS.md](./references/guides/ICONS.md) describes available icons and how to use them.
+- [CONFIGURATION.md](./references/guides/CONFIGURATION.md) describes how to configure KUI for your project - this is useful to reference when running into issues.
+
+- [Accordion](references/components/Accordion.md)
+ - A multi-section expand/collapse component for organizing content into collapsible panels. Supports single-open and multi-open modes.
+- [Anchor](references/components/Anchor.md)
+ - A styled anchor element that provides consistent link styling across applications.
+ - sometimes known as Link
+- [AnimatedChevron](references/components/AnimatedChevron.md)
+ - An internal utility component. Renders a chevron icon that indicates an open or closed state, which is used in accordion- and menu-related components. Reads `data-state` attribute to determine the state.
+- [AppBar](references/components/AppBar.md)
+ - The top-level masthead for the application. Can contain the NVIDIA logo(or custom branding), navigation, and global actions (user menu, settings). Every application has exactly one AppBar.
+ - sometimes known as Masthead, Navbar, Navigation Bar
+- [Avatar](references/components/Avatar.md)
+ - Use an avatar whenever it's helpful to quickly identify a user. Prioritize images over text to improve clarity. Provide the user's initials as a fallback when no image is available.
+- [Badge](references/components/Badge.md)
+ - A small color-coded label for indicating status, category, or metadata at a glance. Badges are non-interactive - they display information, not trigger actions.
+- [Banner](references/components/Banner.md)
+ - Banners communicate important messages and actions that draw the user's attention. Banners should be embedded in the page layout and span the width of its container. Use sparingly.
+- [Block](references/components/Block.md)
+ - A primitive div component. This component provides a convenient way to create elements with consistent spacing and overflow handling.
+- [Breadcrumbs](references/components/Breadcrumbs.md)
+ - A navigation path showing the user's location within the apps hierarchy, providing a trail back to parent pages and helping users orient themselves in deep navigation structures. Use concise labels. Do not use `Breadcrumbs` for root or first-level pages - there's nothing to navigate back to.
+- [Button](references/components/Button.md)
+ - A clickable element that triggers an action. Use specific verb + noun labels instead of vague text.
+- [ButtonGroup](references/components/ButtonGroup.md)
+ - Use a Button Group to offer a set of choices that are related. It's recommended to show no more than 4 actions. Also consider a Segmented Control when actions are mutually exclusive and must have one active at all times.
+- [Card](references/components/Card.md)
+ - A card contains content and actions about a single subject. Cards carry identity: they describe "a thing" with its own content, actions, and optional media. By default cards are fluid and will grow to fit their container.
+- [Checkbox](references/components/Checkbox.md)
+ - Use checkboxes to allow users to select multiple options from a list or to mark a single item as selected
+- [CodeSnippet](references/components/CodeSnippet.md)
+ - A code snippet component with syntax highlighting, copy functionality, and optional collapse behaviour. Supports both inline code spans and block-level code blocks.
+- [Collapsible](references/components/Collapsible.md)
+ - A utility component that allows you to collapse and expand content.
+- [Combobox](references/components/Combobox.md)
+ - A Combobox combines a text input and listbox to let users filter and pick from declarative `items`.
+- [DatePicker](references/components/DatePicker.md)
+ - A complete date picker component with input field(s) and calendar popup. Supports both single date selection and date range selection modes. The component handles manual date entry through input fields and provides a calendar interface for visual date selection.
+- [Divider](references/components/Divider.md)
+ - A visual separator that creates a clear distinction between content sections
+- [Dropdown](references/components/Dropdown.md)
+ - Use Dropdowns to allow users to select one or multiple options, navigate through links, or take actions. Dropdowns are often used for navigation, filters, or contextual actions.
+- [Flex](references/components/Flex.md)
+ - A primitive flex component.
+- [FormField](references/components/FormField.md)
+ - A component for displaying a form field with label, description, helper text, and validation messages. FormField automatically adapts to different container widths. For horizontal layouts (`labelPosition="left"`), it will switch to vertical layout on small screens.
+ - sometimes known as Form Group, Fieldset, Form Input
+- [Grid](references/components/Grid.md)
+ - A primitive grid component.
+- [Group](references/components/Group.md)
+ - Group is a utility component that joins items together visually.
+- [Hero](references/components/Hero.md)
+ - A Hero is a large page banner that combines important messaging and calls to action with large imagery. Has responsive padding based on the component width.
+- [HorizontalNav](references/components/HorizontalNav.md)
+ - The HorizontalNav component is a customizable navigation bar designed to display a list of links in a horizontal layout. It allows users to navigate between different sections of an application or website.
+- [Inline](references/components/Inline.md)
+ - A primitive span component.
+- [InputShell](references/components/InputShell.md)
+ - Internal utility component. Use this to wrap any element that needs to be styled as an input.
+- [Label](references/components/Label.md)
+ - A label component for forms and inputs. If you're using this component for a form field, just use the FormField component instead. This component is mostly intended for internal use.
+- [List](references/components/List.md)
+ - A flexible list component that supports unordered, ordered, and icon lists.
+- [Menu](references/components/Menu.md)
+ - A static menu component that displays a list of items. Note: if you're looking for a menu that can be used as a dropdown, see the `Dropdown` component. This is the menu component itself and does not have behaviour to hide/show itself.
+- [Modal](references/components/Modal.md)
+ - A modal dialog that can be triggered by a button or other element. Uses the native `<dialog>` element for progressive enhancement, providing built-in backdrop styling, focus management, and support for `form method="dialog"` for native close behavior.
+- [Notification](references/components/Notification.md)
+ - A notification component that displays important messages and alerts to users. It provides a flexible layout with support for icons, headings, subheadings, close buttons and footers. The component uses a grid-based layout through NotificationContent to organize its elements: - Icon on the left (optional) - Header content in the middle containing heading and subheading - Close button on the right (optional) - Footer below (optional)
+- [PageHeader](references/components/PageHeader.md)
+ - The page header describes the current page and displays a title, breadcrumbs, and page-level actions
+- [Pagination](references/components/Pagination.md)
+ - A pagination component that provides different styles of navigation for paginated content.
+- [Panel](references/components/Panel.md)
+ - A panel is a simple container used to wrap content and actions for a given component in a card-like format with a background, border, and padding.
+- [Popover](references/components/Popover.md)
+ - Displays rich content in a portal, triggered by a button click. Use a popover to display specific information, options, or actions related to an element on the page. Built on the native Popover API and CSS Anchor Positioning for progressive enhancement. The trigger uses `popovertarget` so toggling works without JavaScript. Positioning is handled entirely in CSS via `anchor-name` / `position-anchor`.
+- [ProgressBar](references/components/ProgressBar.md)
+ - Use a progress bar to visually communicate processes that involve long wait times, such as downloading, uploading, submitting, or loading data.
+- [RadioGroup](references/components/RadioGroup.md)
+ - A set of radio buttons where no more than one of the options can be selected at a time. **Progressive Enhancement:** Uses native `<input type="radio">` elements which provide built-in keyboard navigation (arrow keys), mutual exclusion, and form submission without JavaScript.
+- [RangeSlider](references/components/RangeSlider.md)
+ - A range slider component allows users to select a range of values (two thumbs). Range sliders reflect a range of values along a bar, from which users may select a range between two values. They are ideal for filtering by price ranges, selecting time windows, or any scenario requiring a min/max selection.
+ - sometimes known as Range Input, Input Range
+- [SegmentedControl](references/components/SegmentedControl.md)
+ - A segmented control allows users to select one option in a set of related options that takes effect on selection. This component is built as a radio group, and uses `name` to group the radio buttons together.
+- [Select](references/components/Select.md)
+ - A Select is a dropdown that allows the user to select a value from a list of options.
+- [SidePanel](references/components/SidePanel.md)
+ - A dialog pinned to the left or right side of the screen that can be triggered by a button or other element. Uses the native `<dialog>` element for progressive enhancement, providing built-in backdrop styling, focus management, and support for `form method="dialog"` for native close behavior. Use a side panel when you need to show supplementary content or actions while maintaining the context of the main view. Side panels are ideal for tasks that require user input or displaying additional information without navigating away from the current page. Common use cases include: - Displaying details about a selected item - Forms that need context from the main view - Configuration panels - Multi-step workflows - Preview panels Consider a Modal instead when: - The task requires full user attention and blocking interaction with the main content - The content needs to be center-focused - The interaction is brief and doesn't require context from the main view
+- [Skeleton](references/components/Skeleton.md)
+ - A skeleton component is a placeholder that mimics the layout of content while it loads, giving users a sense of the structure and reducing perceived wait time. Always try and make the skeleton components as simular in size and shape to the dynamic content as you can
+- [Slider](references/components/Slider.md)
+ - A slider component allows users to select a single value from a range of values. Sliders reflect a range of values along a bar, from which users may select a single value. They are ideal for adjusting settings such as volume, brightness, or applying image filters.
+ - sometimes known as Range Input, Input Range
+- [Spinner](references/components/Spinner.md)
+ - Use a spinner when the user is waiting on an operation including loading, downloading, uploading, processing, etc. that's indeterminate. Spinners are displayed until content appears or a process is complete. This component should be used when the expected duration is more than a second and the completion time is short (up to 5 seconds). A message can be used with a spinner to improve understanding.
+- [Stack](references/components/Stack.md)
+ - A container component for laying out content in a vertical or horizontal stack. This is a wrapper around the {@link Flex} component.
+- [StatusIndicator](references/components/StatusIndicator.md)
+ - A status indicator is a simple circle that is ephemeral and used to signal new changes or, occasionally, status.
+- [StatusMessage](references/components/StatusMessage.md)
+ - Use a status message when there is no data or content available. This helps inform users of the current status and suggests next steps when appropriate.
+- [Stepper](references/components/Stepper.md)
+ - A stepper (progress tracker) that visually represents a user's progress through a series of discrete steps.
+- [Switch](references/components/Switch.md)
+ - A switch allows users to quickly switch between two states. Use a switch to allow users to turn something on or off instantly. Switches are only used with binary actions with a default setting set. It's commonly used for adjusting settings and preferences.
+ - sometimes known as Toggle, ToggleSwitch
+- [Table](references/components/Table.md)
+ - A table organizes sets of data into columns and rows.
+- [Tabs](references/components/Tabs.md)
+ - A high-level tabs component that provides a simple way to create tabbed interfaces. Wraps the lower-level composed tab components for ease of use.
+- [Tag](references/components/Tag.md)
+ - Tags are used to categorize, label, or group items using text and optional icons, providing users with quick, contextual information.
+- [Text](references/components/Text.md)
+ - A primitive component for displaying text.
+- [TextArea](references/components/TextArea.md)
+ - A textarea with additional capabilities such as icons and status.
+- [TextInput](references/components/TextInput.md)
+ - This component is a composition of the `InputShell` and `input` components. The `ref` and HTML attributes are applied to the inner `input` component.
+- [ThemeProvider](references/components/ThemeProvider.md)
+ - A comprehensive theme provider that manages both density (spacing) and theme (light/dark) themes for all child components. This component: - Sets density variants that control spacing throughout child components - Manages color themes with support for system preference detection - Controls motion and animations with support for accessibility preferences - Applies theme classes to the provider element for scoped theming (only when explicitly provided or inherited) - Provides theme context to all descendant components via React Context - Handles system theme changes and updates the UI accordingly - Supports nesting with automatic inheritance from parent providers When nested, child providers inherit density, theme, and defer settings from their parent unless explicitly overridden. If no theme is provided and there's no parent context, no theme class is applied, allowing manually set theme classes to take precedence. This allows for granular theme control in different sections of the application while maintaining consistent defaults and not overriding external theme solutions.
+- [Toast](references/components/Toast.md)
+ - Use a toast to display small messages without disrupting a user's experience. Toasts are commonly used to provide non-critical, contextual feedback following a user's action or process. They're low-emphasis and appear temporarily as an overlay.
+- [Tooltip](references/components/Tooltip.md)
+ - A tooltip displays additional information when users hover or focus on an element. To remove the delay on hover when switching between different tooltips, it is highly recommended to wrap your application in a `TooltipProvider` component. Built on the native Popover API and CSS Anchor Positioning for progressive enhancement. Hover and focus interactions are managed with lightweight JavaScript; uncontrolled tooltips also render a no-JS click target during SSR.
+- [TreeNav](references/components/TreeNav.md)
+ - A tree navigation component that lets users move through links at different levels, like a directory structure. Uses native `<details>`/`<summary>` elements for zero-JS expand/collapse behavior. Branches containing an active descendant are automatically expanded unless they use controlled state (`open` prop) or have an explicit `defaultOpen`.
+- [Upload](references/components/Upload.md)
+ - Upload is a wrapper around `input type="file"` that also renders previews for uploaded files and provides basic file management. Note that file validation and actual upload is not handled by this component beyond what the input element provides.
+- [VerticalNav](references/components/VerticalNav.md)
+ - The VerticalNav component provides a vertical navigation menu that can handle both single links and nested link groups using native HTML `<details>`/`<summary>`.
diff --git a/.agents/skills/kaizen-ui/references/components/Accordion.md b/.agents/skills/kaizen-ui/references/components/Accordion.md
new file mode 100644
index 0000000..6770db8
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Accordion.md
@@ -0,0 +1,107 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Accordion
+
+A multi-section expand/collapse component for organizing content into collapsible panels. Supports single-open and multi-open modes.
+
+## Examples
+
+### Basic Accordion
+
+By default the accordion allows for a single item to be open at a time. Set `multiple` to allow multiple items to be open at a time.
+
+```tsx
+<Accordion
+ // defaults to single selection mode
+ defaultValue="1"
+ items={[
+ {
+ slotTrigger: 'Item 1',
+ slotContent: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
+ value: '1'
+ },
+ { slotTrigger: 'Item 2', slotContent: '...', value: '2' }
+ ]}
+/>
+```
+
+### Default Open Multiple Items Accordion
+
+```tsx
+<Accordion
+ defaultValue={['1', '2']}
+ items={[
+ { slotTrigger: 'Item 1', slotContent: '...', value: '1' },
+ { slotTrigger: 'Item 2', slotContent: '...', value: '2' }
+ ]}
+ multiple
+/>
+```
+
+### With Icon In Trigger
+
+Use gap="inherit" to use the Accordion defined gap for the icon and text.
+
+```tsx
+<Accordion
+ items={[
+ {
+ slotTrigger: (
+ <Flex align="center" gap="inherit">
+ <Icon /> Item 1
+ </Flex>
+ ),
+ slotContent: '...',
+ value: '1'
+ },
+ {
+ slotTrigger: (
+ <Flex align="center" gap="inherit">
+ <Icon /> Item 2
+ </Flex>
+ ),
+ slotContent: '...',
+ value: '2'
+ }
+ ]}
+/>
+```
+
+### Composed
+
+```tsx
+<AccordionRoot>
+ <AccordionItem value="1">
+ <AccordionTrigger>Section 1</AccordionTrigger>
+ <AccordionContent>Content for section 1</AccordionContent>
+ </AccordionItem>
+ <AccordionItem value="2">
+ <AccordionTrigger>
+ <Flex align="center" gap="inherit">
+ <Icon />
+ Section 2
+ </Flex>
+ </AccordionTrigger>
+ <AccordionContent>Content for section 2</AccordionContent>
+ </AccordionItem>
+</AccordionRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `{ slotTrigger: ReactNode; slotContent: ReactNode; value: string; disabled: boolean; chevronPosition: "start" \| "end" }[]` | - | The items to render in the accordion. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| collapsible | `boolean \| never` | `true` | For single item accordions, this prop controls whether the open item can be clicked to close it. When `collapsible` is false open items cannot be closed by clicking on them. This prop is only applicable to single item accordions, and is ignored when `multiple` is true. |
+| defaultValue | `string \| string[]` | - | The default open item(s) in the accordion. |
+| disabled | `boolean` | - | If true, the accordion will be disabled and interaction will be prevented. |
+| multiple | `false \| true` | `false` | When `multiple` is true the Accordion allows for multiple accordion items to be open at a time. |
+| name | `string` | - | A shared name for all accordion items. When provided with `multiple=false`, enables native browser single-select behavior for no-JS scenarios. |
+| onValueChange | `(value: string) => void \| (value: string[]) => void` | - | Callback triggered when accordion items are opened or closed. |
+| value | `string \| string[]` | - | The currently open item(s) in the accordion. When setting this prop, you must also set the `onValueChange` prop to control the state of the accordion. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Anchor.md b/.agents/skills/kaizen-ui/references/components/Anchor.md
new file mode 100644
index 0000000..34455b3
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Anchor.md
@@ -0,0 +1,72 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Anchor
+
+Also known as: Link
+
+A styled anchor element that provides consistent link styling across applications.
+
+## Examples
+
+### Basic Anchor
+
+```tsx
+<Flex gap="2">
+ <Anchor href="/" kind="inline">
+ Inline
+ </Anchor>
+ <Anchor href="/" kind="standalone">
+ Standalone
+ </Anchor>
+</Flex>
+```
+
+### Custom Link Component
+
+Use asChild to render framework specific link components with our styling
+
+```tsx
+<Anchor asChild>
+ <NextLink href="/">Home</NextLink>
+</Anchor>
+```
+
+### Disabled Anchor
+
+A disabled anchor will render as a span instead of an anchor tag
+
+```tsx
+<Anchor disabled href="/">
+ Disabled Link
+</Anchor>
+```
+
+### As Button
+
+Render Anchor as a button for non-navigation tasks
+
+```tsx
+<Anchor asChild>
+ <button onClick={() => console.log('Button clicked')} type="button">
+ View Details
+ </button>
+</Anchor>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| disabled | `boolean` | `false` | Whether the anchor is disabled. When true, the Anchor will render as a span instead of an anchor tag. Note: if using asChild, you may want your component to handle the disabled state instead. In that case pass `disabled` to your component directly instead of to the `Anchor` component. |
+| fontFamily | `"sans" \| "mono"` | - | The font family of the text. |
+| fontSize | `"10" \| "12" \| "14" \| "16" \| "18" \| "20" \| "22" \| "24" \| "28" \| "32" \| "36" \| "40" \| "44" \| "48" \| "50" \| "56" \| "60" \| "64" \| "72" \| "80"` | - | The font size of the text. |
+| fontStyle | `"normal" \| "italic"` | - | The font style of the text. |
+| fontWeight | `"bold" \| "light" \| "regular" \| "semibold"` | - | The font weight of the text. |
+| kind | `"inline" \| "standalone"` | `"inline"` | The kind of anchor to render. Defaults to "inline" which is intended to be used within text(renders a underline). Use "standalone" for Anchors rendered outside of prose(as a CTA for example) - it renders without a underline. |
+| lineHeight | `"100" \| "125" \| "150" \| "175"` | - | The line-height of the text. |
+| textKind | `"inherit" \| "body/bold/2xl" \| "body/bold/3xl" \| "body/bold/lg" \| "body/bold/md" \| "body/bold/xl" \| "body/bold/sm" \| "body/bold/xs" \| "body/regular/lg" \| "body/regular/md" \| "body/regular/sm" \| "body/regular/xl" \| "body/regular/2xl" \| "body/regular/3xl" \| "body/regular/xs" \| "body/semibold/2xl" \| "body/semibold/3xl" \| "body/semibold/lg" \| "body/semibold/md" \| "body/semibold/sm" \| "body/semibold/xl" \| "body/semibold/xs" \| "display/2xl" \| "display/xl" \| "display/lg" \| "display/md" \| "display/sm" \| "display/xs" \| "label/bold/2xl" \| "label/bold/3xl" \| "label/bold/lg" \| "label/bold/md" \| "label/bold/sm" \| "label/bold/xl" \| "label/bold/xs" \| "label/light/lg" \| "label/light/xl" \| "label/light/2xl" \| "label/light/3xl" \| "label/light/md" \| "label/light/sm" \| "label/light/xs" \| "label/regular/lg" \| "label/regular/md" \| "label/regular/sm" \| "label/regular/xs" \| "label/regular/xl" \| "label/regular/2xl" \| "label/regular/3xl" \| "label/semibold/lg" \| "label/semibold/md" \| "label/semibold/sm" \| "label/semibold/xl" \| "label/semibold/2xl" \| "label/semibold/3xl" \| "label/semibold/xs" \| "mono/md" \| "mono/sm" \| "mono/lg" \| "mono/xl" \| "mono/2xl" \| "title/2xl" \| "title/xl" \| "title/lg" \| "title/md" \| "title/sm" \| "title/xs"` | `"body/regular/md"` | The Text typography kind to render as - defaults to "body/regular/md" so it will align with text when rendered inline with text. For standalone Anchors, prefer a "label" typography family. |
+| underline | `boolean` | - | Whether or not the text should be underlined. |
diff --git a/.agents/skills/kaizen-ui/references/components/AnimatedChevron.md b/.agents/skills/kaizen-ui/references/components/AnimatedChevron.md
new file mode 100644
index 0000000..4bea5ea
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/AnimatedChevron.md
@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# AnimatedChevron
+
+An internal utility component. Renders a chevron icon that indicates an open or closed state,
+which is used in accordion- and menu-related components. Reads `data-state` attribute to determine the state.
+
+## Examples
+
+### Basic Usage
+
+Reads open/closed state from `data-state="open"` or `data-state="closed"` from parent.
+
+```tsx
+<div data-state="open">
+ <AnimatedChevron />
+</div>
+```
+
+### Controlled Usage
+
+Manually control the state with the `state` prop.
+
+```tsx
+<AnimatedChevron state="closed" />
+```
+
+### Usage With Collapsible
+
+When used in most of our components, it automatically reads the open/closed state from the parent data attribute, such as Collapsible.
+
+```tsx
+<Collapsible
+ slotTrigger={
+ <button type="button">
+ <AnimatedChevron />
+ </button>
+ }
+>
+ ...
+</Collapsible>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ----- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| state | `"open" \| "closed"` | - | Used for determining whether the Chevron should point up or down, for elements that don't use data-state in the parent component (ex: InputShell) |
diff --git a/.agents/skills/kaizen-ui/references/components/AppBar.md b/.agents/skills/kaizen-ui/references/components/AppBar.md
new file mode 100644
index 0000000..be48a32
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/AppBar.md
@@ -0,0 +1,79 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# AppBar
+
+Also known as: Masthead, Navbar, Navigation Bar
+
+The top-level masthead for the application. Can contain the NVIDIA logo(or custom branding), navigation,
+and global actions (user menu, settings). Every application has exactly one AppBar.
+
+## Examples
+
+### Simple Example
+
+```tsx
+<AppBar
+ slotStart={
+ <>
+ <AppBarExpanderButton />
+ <span>Product</span>
+ </>
+ }
+/>
+```
+
+### Full Example
+
+Note that "AppBarLogo" is included with `@kui/foundations-react` or can come from `@kui-contrib/brand-logo` if you are using that package.
+
+```tsx
+<AppBar
+ slotStart={
+ <>
+ <AppBarExpanderButton onClick={() => console.log('toggle')} />
+ <AppBarLogo />
+ <Anchor kind="standalone" href="/" textKind="inherit">
+ Product Name
+ </Anchor>
+ </>
+ }
+ slotEnd={<Avatar interactive fallback="NV" />}
+>
+ <HorizontalNav
+ defaultValue="home"
+ items={[
+ { value: 'home', href: '/', children: 'Home' },
+ { value: 'about', href: '/about', children: 'About' },
+ { value: 'contact', href: '/contact', children: 'Contact' }
+ ]}
+ />
+</AppBar>
+```
+
+### With Centered Content
+
+```tsx
+<AppBar>
+ <div className="mx-auto">
+ <HorizontalNav
+ defaultValue="home"
+ items={[
+ { value: 'home', href: '/', children: 'Home' },
+ { value: 'about', href: '/about', children: 'About' },
+ { value: 'contact', href: '/contact', children: 'Contact' }
+ ]}
+ />
+ </div>
+</AppBar>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| children | `ReactNode` | - | Renders in the AppBar between the left and right slots. By default this is left aligned. This is where you would place your app's navigation using HorizontalNav - do not include more than 7 links for proper UX. For more links, you should use VerticalNav in your app and no links in AppBar. |
+| slotEnd | `ReactNode` | - | The slot for the end(right) side of the AppBar. Intended to contain global actions (user menu, settings). |
+| slotStart | `ReactNode` | - | The slot for the start(left) side of the AppBar. Intended to contain the brand area and product name. |
diff --git a/.agents/skills/kaizen-ui/references/components/Avatar.md b/.agents/skills/kaizen-ui/references/components/Avatar.md
new file mode 100644
index 0000000..0a3a348
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Avatar.md
@@ -0,0 +1,79 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Avatar
+
+Use an avatar whenever it's helpful to quickly identify a user. Prioritize images over text to improve clarity.
+Provide the user's initials as a fallback when no image is available.
+
+## Examples
+
+### Basic Avatar
+
+```tsx
+<Avatar fallback="JH" alt="Jensen Huang" size="xlarge" src="jhh.jpg" />
+```
+
+### With Name
+
+```tsx
+<div className="flex items-center gap-2">
+ <Avatar
+ fallback="JH"
+ // use empty alt to avoid redundancy with name text
+ alt=""
+ src="jhh.jpg"
+ />
+ <Text kind="label/bold/sm">Jensen Huang</Text>
+</div>
+```
+
+### Interactive Avatar
+
+Sometimes Avatars are used as triggers - in that case use the `interactive` prop so the Avatar has hover states.
+
+```tsx
+<Avatar fallback="JH" alt="Jensen Huang" src="jhh.jpg" interactive />
+```
+
+### As Link Or Button
+
+To render an Avatar as a link or button, use the asChild prop on AvatarRoot to render it as its child element.
+
+```tsx
+<AvatarRoot asChild interactive size="large">
+ <a
+ // or use a button element, depending on the use case
+ href="https://www.nvidia.com/jensen-huang/"
+ rel="noreferrer noopener"
+ target="_blank"
+ >
+ <AvatarImage alt="Jensen Huang" src="jhh.jpg" />
+ <AvatarFallback>JH</AvatarFallback>
+ </a>
+</AvatarRoot>
+```
+
+### Composed
+
+```tsx
+<AvatarRoot size="xxlarge">
+ <AvatarImage alt="Jensen Huang" src="jhh.jpg" />
+ <AvatarFallback>JH</AvatarFallback>
+</AvatarRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------- | --------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **fallback** \* | `ReactNode` | - | Fallback text displayed in the event of no image source, or the image fails to load. Always provide initials or an icon fallback. |
+| alt | `string` | - | Alt text for the Avatar image. You should always provide this. For user profiles, use the user's name (not just the initials). If the user's name is already displayed though, use an empty string to avoid screen reader redundancy. |
+| interactive | `boolean` | - | If true, the avatar will have hover and active interactions and pointer styling. If the `onClick` prop is set, this defaults to true. |
+| kind | `"outline" \| "solid"` | `"outline"` | The style of the avatar, either "outline" or "solid" (no outline). Use "outline" for lighter-weight avatars in dense layouts. |
+| size | `"small" \| "medium" \| "large" \| "xlarge" \| "xxlarge"` | `"medium"` | The size of the avatar. Use "medium" for most cases. "small" in lists/tables. "large" / "xlarge" / "xxlarge" for profile detail pages, depending on the context. |
+| src | `string` | - | The source of the image for the users Avatar |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Badge.md b/.agents/skills/kaizen-ui/references/components/Badge.md
new file mode 100644
index 0000000..7b5f309
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Badge.md
@@ -0,0 +1,77 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Badge
+
+A small color-coded label for indicating status, category, or metadata at a glance. Badges are
+non-interactive - they display information, not trigger actions.
+
+## Notes
+
+- Always use Badge (not plain text) to display entity status. Use a semantic color (e.g., color="green" for healthy, color="warning" for degraded).
+
+- Use kind="solid" for status badges in detail views, side panels, and status bars. Use kind="outline" only for secondary/de-emphasized contexts like card metadata.
+
+- Prefer label-only badges without icons for status (Healthy, Degraded, Pending). Icons on status badges add visual noise without information.
+
+## Examples
+
+### Basic Badge
+
+```tsx
+<Grid cols={2} gap="3" style={{ placeItems: 'center' }}>
+ <Badge color="blue" kind="solid">
+ Badge Text
+ </Badge>
+ <Badge color="blue">Badge Text</Badge>
+ <Badge color="green" kind="solid">
+ Badge Text
+ </Badge>
+ <Badge color="green">Badge Text</Badge>
+ <Badge color="yellow" kind="solid">
+ Badge Text
+ </Badge>
+ <Badge color="yellow">Badge Text</Badge>
+ <Badge color="red" kind="solid">
+ Badge Text
+ </Badge>
+ <Badge color="red">Badge Text</Badge>
+</Grid>
+```
+
+### With Icon
+
+```tsx
+<Badge color="purple">
+ <Shield /> Encrypted
+</Badge>
+```
+
+### As Link
+
+```tsx
+<Badge asChild>
+ <a href="/">Badge as a Link</a>
+</Badge>
+```
+
+### With Truncation
+
+Badge text should be short and concise. By default, overflowing content wraps so it stays readable. If you must truncate (e.g., a constrained layout with unpredictable content), wrap the text in a span with truncation styles.
+
+```tsx
+<Badge>
+ <Shield />
+ <span className="truncate">Long text that will be truncated</span>
+</Badge>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| color | `"blue" \| "green" \| "red" \| "yellow" \| "purple" \| "teal" \| "gray"` | `"blue"` | The badge color. Use a semantic color to convey meaning (e.g., color="green" for healthy, color="yellow" for degraded). |
+| kind | `"outline" \| "solid"` | `"outline"` | The style of the badge. Use kind="solid" for status badges in detail views, side panels, and status bars. Use kind="outline" for secondary/de-emphasized contexts like card metadata. |
diff --git a/.agents/skills/kaizen-ui/references/components/Banner.md b/.agents/skills/kaizen-ui/references/components/Banner.md
new file mode 100644
index 0000000..3670c93
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Banner.md
@@ -0,0 +1,122 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Banner
+
+Banners communicate important messages and actions that draw the user's attention. Banners should
+be embedded in the page layout and span the width of its container. Use sparingly.
+
+## Examples
+
+### Inline Banner
+
+```tsx
+<Flex className="w-full" gap="1" direction="col">
+ <Banner status="info">Lorem ipsum dolor sit</Banner>
+ <Banner status="success">Lorem ipsum dolor sit</Banner>
+ <Banner status="warning">Lorem ipsum dolor sit</Banner>
+</Flex>
+```
+
+### Global Banner
+
+```tsx
+<Banner onClose={hideBanner} status="warning" kind="global">
+ Your account password is expiring soon
+</Banner>
+```
+
+### Header Banner With Actions
+
+```tsx
+<Banner
+ kind="header"
+ onClose={hideBanner}
+ slotSubheading="Our system will be unavailable on Saturday from 2-4 AM"
+ slotActions={
+ <>
+ <Button kind="secondary" size="tiny">
+ Support
+ </Button>
+ <Button kind="secondary" size="tiny">
+ Add to Calendar
+ </Button>
+ </>
+ }
+>
+ Service maintenance scheduled
+</Banner>
+```
+
+### Composed
+
+```tsx
+<BannerRoot kind="global" status="warning">
+ <BannerLayout>
+ <BannerContent>
+ <BannerIcon>
+ <Warning />
+ </BannerIcon>
+ <BannerHeader>
+ <BannerHeading>Service maintenance scheduled</BannerHeading>
+ </BannerHeader>
+ </BannerContent>
+ <BannerActionsSection>
+ <Button kind="secondary" size="tiny">
+ Support
+ </Button>
+ </BannerActionsSection>
+ <BannerCloseButtonSection>
+ <Button aria-label="Close" kind="tertiary" size="tiny">
+ <Close />
+ </Button>
+ </BannerCloseButtonSection>
+ </BannerLayout>
+</BannerRoot>
+```
+
+### Composed Header Example
+
+```tsx
+<BannerRoot kind="header" status="success">
+ <BannerLayout>
+ <BannerContent>
+ <BannerIcon>
+ <SuccessIcon />
+ </BannerIcon>
+ <BannerHeader>
+ <BannerHeading>Maintenance complete</BannerHeading>
+ <BannerSubheading>Our system is back online</BannerSubheading>
+ </BannerHeader>
+ </BannerContent>
+ <BannerActionsSection>
+ <Button kind="secondary" size="tiny">
+ Changelog
+ </Button>
+ </BannerActionsSection>
+ <BannerCloseButtonSection>
+ <Button aria-label="Close" kind="tertiary" size="tiny">
+ <Close />
+ </Button>
+ </BannerCloseButtonSection>
+ </BannerLayout>
+</BannerRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **kind** \* | `"header" \| "inline" \| "global"` | `"inline"` | The kind of banner to render. Choose based on the scope of the message. - `inline`: Contextual alerts to be used in a specific content area. Should be placed in the content flow. - `header`: A banner with a bolded heading and optional subheading. Should be rendered below the AppBar or at the top of a page section. - `global`: A banner that should be used for site-wide messaging. Should be placed at the top of the entire app, above the AppBar. |
+| **slotSubheading** \* | `ReactNode \| never` | - | "header" kind banners render their `children` as the heading - `slotSubheading` is used to render the (smaller) subheading text. |
+| actionsPosition | `"right" \| "bottom"` | - | The position of the actions to render in the banner. By default, the actions will be rendered on the right until the banner is too small. Then they will move to the bottom. You probably don't want to use this prop unless you have a specific reason to do so. |
+| children | `ReactNode` | - | The heading text of the banner. |
+| onClose | `() => void` | - | Handler for dismissing the banner. When provided, renders a close button. Omit for blocking banners (e.g. active outages, compliance notices) that must remain visible until resolved. |
+| ref | `((instance: HTMLDivElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLDivElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| slotActions | `ReactNode` | - | The actions to render in the banner. |
+| slotIcon | `ReactNode` | `status === "info" ? ( <Icon name="info-circle" variant="fill" /> ) : status === "warning" ? ( <Icon name="warning" variant="fill" /> ) : status === "error" ? ( <Icon name="error" variant="fill" /> ) : status === "success" ? ( <Icon name="check-circle" variant="fill" /> ) : null` | Slot for the icon to render in the banner. By default, the icon rendered is based on the status prop of the banner. To render no icon, pass `null` to this prop. |
+| status | `"error" \| "warning" \| "success" \| "info"` | `"info"` | The status of the banner - based on message semantics. - `info`: Provides neutral information (blue) - `warning`: Alerts users to a potentially unwanted outcome or upcoming issues (yellow) - `error`: Indicates a problem that needs attention, outages, or failures (red) - `success`: Confirms a successful action or operation, or resolved issues (green) |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Block.md b/.agents/skills/kaizen-ui/references/components/Block.md
new file mode 100644
index 0000000..75fec8f
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Block.md
@@ -0,0 +1,64 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Block
+
+A primitive div component. This component provides a convenient way to create elements with
+consistent spacing and overflow handling.
+
+## Examples
+
+### Basic Block
+
+```tsx
+<Block
+ style={{
+ height: '100px',
+ width: '200px',
+ border: '3px dotted var(--border-color-base)'
+ }}
+/>
+```
+
+## Props
+
+type SpacingScaleUnion
+
+Prefer semantic density tokens that adapt to the active density theme (compact, standard, spacious):
+"density-xxs" | "density-xs" | "density-sm" | "density-md" | "density-lg" | "density-xl" | "density-2xl" | "density-3xl" | "density-4xl" | "density-5xl"
+
+| Token | Compact | Standard | Spacious |
+| ----------- | ------- | -------- | -------- |
+| density-xxs | 1px | 2px | 4px |
+| density-xs | 2px | 4px | 6px |
+| density-sm | 4px | 6px | 8px |
+| density-md | 6px | 8px | 12px |
+| density-lg | 8px | 12px | 16px |
+| density-xl | 12px | 16px | 24px |
+| density-2xl | 16px | 24px | 32px |
+| density-3xl | 24px | 32px | 48px |
+| density-4xl | 32px | 48px | 64px |
+| density-5xl | 48px | 64px | 80px |
+
+Raw scale values (4px base unit — use only when density tokens don't fit):
+"0" | "0.25" | "0.5" | "0.75" | "1" | "1.5" | "2" | "2.5" | "3" | "3.5" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "14" | "16" | "18" | "20" | "24" | "28" | "32" | "36" | "40" | "44" | "48" | "52" | "56" | "60" | "64" | "72" | "80" | "96" | "250" | "inherit" | "px"
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| gap | `SpacingScaleUnion` | - | Sets spacing between flex and grid items. |
+| overflow | `"hidden" \| "auto" \| "clip" \| "scroll" \| "visible"` | - | Sets content overfow handling. See https://developer.mozilla.org/en-US/docs/Web/CSS/overflow for more. |
+| overflowX | `"hidden" \| "auto" \| "clip" \| "scroll" \| "visible"` | - | Sets content overfow handling for a block level element's left and right edges. See https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-x for more. |
+| overflowY | `"hidden" \| "auto" \| "clip" \| "scroll" \| "visible"` | - | Sets content overfow handling for a block level element's top and bottom edges. See https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-y for more. |
+| padding | `SpacingScaleUnion` | - | Sets padding. |
+| paddingBottom | `SpacingScaleUnion` | - | Sets bottom padding. |
+| paddingLeft | `SpacingScaleUnion` | - | Sets left padding. |
+| paddingRight | `SpacingScaleUnion` | - | Sets right padding. |
+| paddingTop | `SpacingScaleUnion` | - | Sets top padding. |
+| paddingX | `SpacingScaleUnion` | - | Sets horizontal padding. |
+| paddingY | `SpacingScaleUnion` | - | Sets vertical padding. |
+| textOverflow | `"clip" \| "ellipsis"` | - | Sets text overflow handling. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow for more. |
+| textWrap | `"wrap" \| "nowrap" \| "balance" \| "pretty"` | - | Sets text wrap. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-wrap for more. |
+| truncate | `boolean` | - | Enables text truncation handling. Same as setting `{ wrap: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }` |
diff --git a/.agents/skills/kaizen-ui/references/components/Breadcrumbs.md b/.agents/skills/kaizen-ui/references/components/Breadcrumbs.md
new file mode 100644
index 0000000..74c9fb6
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Breadcrumbs.md
@@ -0,0 +1,80 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Breadcrumbs
+
+A navigation path showing the user's location within the apps hierarchy, providing a trail back
+to parent pages and helping users orient themselves in deep navigation structures. Use concise labels.
+
+Do not use `Breadcrumbs` for root or first-level pages - there's nothing to navigate back to.
+
+## Examples
+
+### Basic Breadcrumbs
+
+```tsx
+<Breadcrumbs
+ items={[
+ { children: <a href="/">Home</a> },
+ { children: <a href="/category">Category</a> },
+ 'Current Page'
+ ]}
+/>
+```
+
+### With Icon
+
+Icons should be used sparingly, but the component supports them.
+
+```tsx
+<Breadcrumbs
+ items={[
+ {
+ children: (
+ <a className="flex gap-[inherit]" href="/">
+ <Home />
+ Home
+ </a>
+ )
+ },
+ { children: <a href="/category">Category</a> },
+ {
+ children: (
+ <>
+ <Identification />
+ Product 123
+ </>
+ )
+ }
+ ]}
+/>
+```
+
+### Composed
+
+```tsx
+<BreadcrumbsRoot>
+ <BreadcrumbsItem>
+ <a href="/">Home</a>
+ </BreadcrumbsItem>
+ <BreadcrumbsSeparator />
+ <BreadcrumbsItem>
+ <a href="/category">Category</a>
+ </BreadcrumbsItem>
+ <BreadcrumbsSeparator />
+ <BreadcrumbsItem active>Current Page</BreadcrumbsItem>
+</BreadcrumbsRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `string \| { children: ReactNode }[]` | - | Array of items to be rendered as breadcrumbs. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | Controls the font size of the breadcrumbs. Available in large(16px), medium(14px), and small(12px) font sizes. |
+| slotSeparator | `ReactNode` | - | Replaces the default separator icon with custom rendered content. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Button.md b/.agents/skills/kaizen-ui/references/components/Button.md
new file mode 100644
index 0000000..cd5de70
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Button.md
@@ -0,0 +1,121 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Button
+
+A clickable element that triggers an action. Use specific verb + noun labels instead of vague text.
+
+## Notes
+
+- For page-level CTAs, PageHeader slotActions, empty-state CTAs, and modal primary actions, use color="brand". A bare Button without color="brand" defaults to neutral, which is visually indistinguishable from secondary buttons.
+
+- For destructive actions (Delete, Terminate, Revoke), use kind="primary" color="danger" and pair with a confirmation Modal.
+
+- "Clear all" / "Clear filters" buttons should use kind="tertiary" and be placed alongside the filter chips they reset, not in the discovery toolbar.
+
+- In confirmation modals, action button is trailing (right): [Cancel] [Action] left-to-right.
+
+## Examples
+
+### Basic Button
+
+```tsx
+<Flex direction="col" gap="2">
+ <Button kind="primary" color="brand">
+ Button
+ </Button>
+ <Button kind="secondary" color="neutral">
+ Button
+ </Button>
+ <Button color="danger">Button</Button>
+</Flex>
+```
+
+### With Icon Button
+
+```tsx
+<Button>
+ <Document />
+ Add Document
+</Button>
+```
+
+### Icon Only Button
+
+```tsx
+<Button aria-label="Add document">
+ <Document />
+</Button>
+```
+
+### Primary Action Button
+
+Preferred default for primary actions: primary & brand. Use the primary action button for the most important action in a context. It should be used sparingly and only for the most important actions(submit, create, deploy, save, etc)
+
+```tsx
+<Button color="brand">Create cluster</Button>
+```
+
+### Secondary Action Button
+
+Preferred default for secondary actions: secondary & neutral. Use the secondary action button for actions that are not the most important in a context. It should be used for actions that are not the most important in a context(cancel, close, etc)
+
+```tsx
+<Button kind="secondary">Deploy to GPU</Button>
+```
+
+### Tertiary Or Inline Action Button
+
+Preferred default for tertiary/inline actions: tertiary & neutral. For example - edit, configure, kebab menu triggers, etc
+
+```tsx
+<Button kind="tertiary">View logs</Button>
+```
+
+### Destructive Action Button
+
+Preferred default for destructive actions: primary & danger. Use the destructive action button for actions that are destructive and cannot be undone.
+
+```tsx
+<Button color="danger">Delete cluster</Button>
+```
+
+### Destructive But Revertible Action Button
+
+Preferred default for destructive but reversible actions: secondary & danger. For example - remove from list, unassign, etc.
+
+```tsx
+<Button color="danger" kind="secondary">
+ Remove member
+</Button>
+```
+
+### Button As Link
+
+```tsx
+<Button asChild>
+ <a href="https://example.com">Link</a>
+</Button>
+```
+
+### Button With Truncation
+
+Button text should be short and concise, and if not text will wrap to the next line to ensure users can read the text. If you prefer to truncate the text you should set the `title` prop.
+
+```tsx
+<Button title="Download the full results as a CSV file">
+ <span className="truncate">Download the full results as a CSV file</span>
+</Button>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------- | ------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| color | `"brand" \| "neutral" \| "danger"` | `"neutral"` | The color variant of the button - "brand" - Used for primary actions, suitable for most use cases. Use for page-level CTAs, PageHeader slotActions, empty-state CTAs, and modal primary actions. - "neutral" - Used for regular actions and suitable for most use cases - "danger" - Used for destructive actions. Typically used for actions that cannot be undone, such as delete or remove. Pair with a confirmation Modal for irreversible actions. |
+| disabled | `boolean` | - | Disables the button |
+| kind | `"primary" \| "secondary" \| "tertiary"` | `"primary"` | The kind of button. - "primary" - The most important call-to-action on the page. Only one primary button should be displayed per context. It can be paired with secondary and tertiary buttons. - "secondary" - Used for regular actions and suitable for most use cases. - "tertiary" - Used for low-priority or supplemental actions. It can be paired with other buttons or displayed alone. |
+| size | `"small" \| "tiny" \| "medium" \| "large"` | `"medium"` | The size of the button. - "large" - Best for the main call-to-action for the page - "medium" - Suitable for most use-cases - "small" - Ideal for compact layouts with limited space and less significant actions - "tiny" - Perfect for the compact, dense layouts, often used in tables to maximize horizontal space in cells |
diff --git a/.agents/skills/kaizen-ui/references/components/ButtonGroup.md b/.agents/skills/kaizen-ui/references/components/ButtonGroup.md
new file mode 100644
index 0000000..b43ebfa
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/ButtonGroup.md
@@ -0,0 +1,86 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# ButtonGroup
+
+Use a Button Group to offer a set of choices that are related. It's recommended to show no more
+than 4 actions. Also consider a Segmented Control when actions are mutually exclusive and must have
+one active at all times.
+
+## Examples
+
+### Basic Button Group
+
+Use when offering a set of related choices. Recommended to show no more than 4 actions.
+
+```tsx
+<ButtonGroup
+ items={[{ children: 'Start Training' }, { children: 'Validate' }, { children: 'Stop' }]}
+/>
+```
+
+### With Children Button Group
+
+Use the children API when you need more control over the button group, such as adding dropdowns. Buttons rendered within will use the ButtonGroup's size/kind/color.
+
+```tsx
+<ButtonGroup size="large" color="brand">
+ <Button>Start Training</Button>
+ <Button>Stop</Button>
+ <Dropdown
+ // no children, so Dropdown renders as chevron only icon so aria-label is required
+ aria-label="Validate or See Details"
+ items={['Validate', 'See Details']}
+ />
+</ButtonGroup>
+```
+
+### With Icon Button Group
+
+```tsx
+<ButtonGroup
+ items={[
+ { children: 'Start Training' },
+ { children: 'Validate' },
+ { children: <SettingsIcon />, key: 'settings', 'aria-label': 'Settings' }
+ ]}
+/>
+```
+
+### Disabled Button Group
+
+Use when the entire group of actions is unavailable due to a precondition.
+
+```tsx
+<ButtonGroup
+ disabled
+ items={[{ children: 'Start Training' }, { children: 'Validate' }, { children: 'Stop' }]}
+/>
+```
+
+### Disabled Individual Button
+
+You can also disable individual buttons in the group by passing a `disabled` prop to the button. We recommend using children in this case so you can provide a tooltip explaining why the button is disabled.
+
+```tsx
+<ButtonGroup>
+ <Tooltip disabled={!trainingDisabled} slotContent="Queue is full">
+ <Button disabled={trainingDisabled}>Train Model</Button>
+ </Tooltip>
+ <Button color="danger">Delete Dataset</Button>
+</ButtonGroup>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------- | ------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| color | `"brand" \| "neutral" \| "danger"` | - | The color of the buttons in the group. Overrides individual button colors. |
+| disabled | `boolean` | - | Disables all buttons in the group. |
+| groupKind | `"gap" \| "flush" \| "border"` | - | The internal "Group['kind']" to render. This manages how buttons are separated. |
+| items | `ButtonProps & { children: string; key?: string; } \| ButtonProps & { children: React.ReactNode; key: string; }[]` | - | The items to render in the button group. Either use this or the `children` prop. |
+| kind | `"primary" \| "secondary" \| "tertiary"` | `"primary"` | The kind of buttons in the group. Overrides individual button kinds. |
+| size | `"small" \| "tiny" \| "medium" \| "large"` | - | The size of the individual buttons in the group. Overrides individual button sizes. |
diff --git a/.agents/skills/kaizen-ui/references/components/Card.md b/.agents/skills/kaizen-ui/references/components/Card.md
new file mode 100644
index 0000000..ac0e15f
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Card.md
@@ -0,0 +1,185 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Card
+
+A card contains content and actions about a single subject. Cards carry identity: they describe
+"a thing" with its own content, actions, and optional media. By default cards are fluid and will
+grow to fit their container.
+
+## Notes
+
+- The Card already has padding, so do not add padding to the Card component or to it's children.
+
+- Card is for single-subject entity display (one cluster, one user, one model). Do not use Card as a general container on dashboards — use Panel instead. Card's interaction states and internal structure add unintended visual layering when used as a generic wrapper.
+
+## Examples
+
+### Basic Card That Fits Its Content
+
+```tsx
+<Card className="h-fit">
+ <Badge kind="solid" color="gray">
+ Badge
+ </Badge>
+ <Text kind="body/bold/2xl">Header</Text>
+ <Text kind="body/regular/md">Lorem ipsum dolor sit amet</Text>
+</Card>
+```
+
+### With Header Card
+
+The header slot is rendered absolutely over the media. Use it to add a persistent label or badge above the body content. If there is no media, the header will be rendered above the body content. It is a flex container with a preset gap.
+
+```tsx
+<Card
+ slotHeader={
+ <Flex gap="inherit">
+ <Badge>New</Badge>
+ <Badge>Alt</Badge>
+ </Flex>
+ }
+>
+ Card body content
+</Card>
+```
+
+### With Media Card
+
+Use when the card needs a visual hero area like an image or video above or alongside the content. If the media rendered is dark or light, and you're using `slotHeader` in conjunction with it, you may want to set `mediaTheme` to ensure text and components are readable. This will set light/dark theme in the header slot to ensure sufficient contrast.
+
+```tsx
+<Card slotHeader={<span>Featured</span>} slotMedia={<MediaImg />} mediaTheme="light">
+ Card content below media
+</Card>
+```
+
+### Realistic Example Card
+
+```tsx
+<Card
+ interactive
+ layout="horizontal"
+ kind="solid"
+ slotHeader={
+ <Flex gap="inherit" wrap="wrap">
+ <Badge kind="solid" color="purple">
+ Preview
+ </Badge>
+ <Badge kind="solid" color="teal">
+ Secure
+ </Badge>
+ </Flex>
+ }
+ slotMedia={<img className="brightness-75" src="model.jpg" alt="AI model visualization" />}
+ mediaTheme="dark"
+>
+ <Text kind="label/semibold/lg">NVIDIA</Text>
+ <Text kind="body/bold/2xl">Llama 3.3 Nemotron Super 49B v1.5</Text>
+ <Text kind="body/regular/md">
+ Llama 3.3 Nemotron Super 49B v1.5 is a high-performance inference platform for AI models.
+ </Text>
+ <Flex gap="2" wrap="wrap">
+ <Tag>Tag Text</Tag>
+ <Tag>Tag Text</Tag>
+ <Tag>Tag Text</Tag>
+ </Flex>
+</Card>
+```
+
+### Interactive Card
+
+Use when the entire card should be a clickable target, such as navigation or selection. Render as a link for navigation or a button for actions. If the entire card is interactive, avoid adding nesting interactive elements in the content.
+
+```tsx
+<Card asChild interactive>
+ <button type="button" onClick={handleClick}>
+ <Flex direction="col" gap="1">
+ <Text className="text-secondary" kind="label/bold/sm">
+ DeepSeek
+ </Text>
+ <Text kind="label/bold/md">DeepSeek-V3.1</Text>
+ <Text kind="body/regular/sm">
+ DeepSeek V3.1 Instruct is a hybrid AI model with fast reasoning, 128K context, and
+ strong tool use.
+ </Text>
+ </Flex>
+ </button>
+</Card>
+```
+
+### With Actions
+
+```tsx
+<Card>
+ Card content... Right aligned actions:
+ <Flex gap="2" justify="end" wrap="wrap">
+ <Button kind="tertiary">Export</Button>
+ <Button kind="secondary">Share</Button>
+ </Flex>
+ Or you can have actions stretch across the card:
+ <Flex gap="2" justify="end" wrap="wrap">
+ <Button kind="tertiary" style={{ flex: 1 }}>
+ Export
+ </Button>
+ <Button kind="secondary" style={{ flex: 1 }}>
+ Share
+ </Button>
+ </Flex>
+ Or for just a single action:
+ <Button color="brand" style={{ width: '100%' }}>
+ Share
+ </Button>
+</Card>
+```
+
+### Cards In Responsive Grid
+
+It's common to use cards in a responsive grid. Using the grid component, set a minimum column width and let the cards automatically resize to fill the available space.
+
+```tsx
+<Grid colMinWidth="250px" gap="2">
+ <Card>Card 1</Card>
+ <Card>Card 2</Card>
+ <Card>Card 3</Card>
+</Grid>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the card structure and slot placement.
+
+```tsx
+<Flex direction="col" gap="1">
+ <CardRoot interactive={false} kind="solid">
+ <CardMedia mediaTheme="light" slotHeader={<Badge>Featured</Badge>}>
+ <MediaImg />
+ </CardMedia>
+ <CardContent>Composed card with media</CardContent>
+ </CardRoot>
+ <CardRoot>
+ <CardContent>
+ <div className="nv-card-content-header">
+ <Badge>Featured</Badge>
+ </div>
+ Composed card without media
+ </CardContent>
+ </CardRoot>
+</Flex>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ----------- | --------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| interactive | `boolean` | `false` | If true, the card will be interactive and will show a hover effect. Do not enable on non-clickable cards - it creates false affordance. |
+| kind | `"solid" \| "gradient" \| "float"` | `"solid"` | Card variants. `solid` - renders the media and content in a single card with padding around the content and a hard border between the media and content. Use for most cards. `gradient` - the same as `solid` but with the media fading out to the content. Use for promotional or "hero-like" cards `float` - Should be used with `slotMedia`. This renders the media as a card with its own border, and renders the content without any padding or background. Use for cards that need to visually lift off the background. |
+| layout | `"horizontal" \| "vertical"` | `"vertical"` | Sets the orientation of the card. `horizontal` will place the media to the left of the content. Use `vertical` when the image is the focal point and the content is lightweight. Cards typically display in a grid, saving horizontal space. Use `horizontal` when the content is more important than the image and typically stack vertically. |
+| mediaTheme | `"light" \| "dark"` | - | `slotHeader` is rendered overtop of media. Depending on the colour of your media, you may want your `slotHeader` content to render in light or dark theme to provide the best contrast. Set `mediaTheme` to override the theme on the card media. For example - if you're using a dark image you should set `mediaTheme="light"`. |
+| selected | `boolean` | `false` | If true, the card will be "selected" and will show a selected state. |
+| slotHeader | `ReactNode` | - | The header content of the Card. If `slotMedia` is provided, this will be rendered absolutely over the media. Default styles: `flex gap-2 flex-wrap` |
+| slotMedia | `ReactNode` | - | The media content of the card. If you are using `slotHeader` in conjunction with this, you should probably set `mediaTheme` to ensure text and components are readable. For light media, you should set `mediaTheme="dark"` to render header content in dark theme. For dark media, you should set `mediaTheme="light"`. |
diff --git a/.agents/skills/kaizen-ui/references/components/Checkbox.md b/.agents/skills/kaizen-ui/references/components/Checkbox.md
new file mode 100644
index 0000000..6e12f4e
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Checkbox.md
@@ -0,0 +1,92 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Checkbox
+
+Use checkboxes to allow users to select multiple options from a list or to mark a single item as selected
+
+## Examples
+
+### Basic Checkbox
+
+```tsx
+<Flex direction="col" gap="3">
+ <Checkbox slotLabel="Item" />
+ <Checkbox checked="indeterminate" slotLabel="Item" />
+ <Checkbox checked slotLabel="Item" />
+ <Checkbox checked error slotLabel="Item" />
+</Flex>
+```
+
+### With Label Checkbox
+
+The label is automatically associated with the input.
+
+```tsx
+<Checkbox slotLabel="Accept terms and conditions" />
+```
+
+### Without Label Checkbox
+
+Use aria-label to provide a label for the checkbox when no label is provided via `slotLabel` or associating via `htmlFor`.
+
+```tsx
+<Checkbox aria-label="Accept terms and conditions" />
+```
+
+### With Callback Checkbox
+
+```tsx
+<Checkbox onCheckedChange={checked => console.log(checked)} slotLabel="Toggle me" />
+```
+
+### Indeterminate Checkbox
+
+```tsx
+<Checkbox checked="indeterminate" slotLabel="Select all" />
+```
+
+### Disabled Checkbox
+
+Should generally be paired with an accompanying tooltip or description to explain why it's disabled.
+
+```tsx
+<Checkbox disabled slotLabel="Unavailable option" />
+```
+
+### Error Checkbox
+
+Renders in an error state.
+
+```tsx
+<Checkbox error slotLabel="Required field" />
+```
+
+### Label Left Checkbox
+
+```tsx
+<Checkbox labelSide="left" slotLabel="Left-side label" />
+```
+
+### Composed
+
+```tsx
+<CheckboxRoot>
+ <CheckboxInput defaultChecked id="my-checkbox" />
+ <Label htmlFor="my-checkbox">Checkbox Label</Label>
+</CheckboxRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------- | ----------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| checked | `false \| true \| "indeterminate"` | - | The controlled checked state of the checkbox. Must be used in conjunction with `onCheckedChange`. |
+| defaultChecked | `boolean` | - | The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state. |
+| disabled | `boolean` | - | If true. Puts the checkbox into a disabled state. |
+| error | `boolean` | - | If true. Shows the checkbox in its error state. |
+| labelSide | `"right" \| "left"` | `"right"` | The side of the label to render the checkbox on. |
+| onCheckedChange | `(checked: false \| true \| "indeterminate") => void` | - | Event handler called when the checked state of the checkbox changes. |
+| slotLabel | `ReactNode` | - | A semantic label for the checkbox. Goes on either the right or left side of the checkbox can be changed using the `labelSide` property. Automatically associated with the checkbox. |
diff --git a/.agents/skills/kaizen-ui/references/components/CodeSnippet.md b/.agents/skills/kaizen-ui/references/components/CodeSnippet.md
new file mode 100644
index 0000000..72a19d4
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/CodeSnippet.md
@@ -0,0 +1,125 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# CodeSnippet
+
+A code snippet component with syntax highlighting, copy functionality, and optional collapse behaviour.
+Supports both inline code spans and block-level code blocks.
+
+## Examples
+
+### Basic Code Snippet
+
+Use for displaying code blocks with syntax highlighting and a copy button.
+
+```tsx
+<CodeSnippet language="javascript" value="console.log('Hello, world!');" />
+```
+
+### Inline Code Snippet
+
+Use when referencing code inline within a paragraph of text.
+
+```tsx
+<p>
+ Use the <CodeSnippet kind="inline" value="useState" language="typescript" /> hook to manage
+ state.
+</p>
+```
+
+### Collapsible Code Snippet
+
+Use when displaying long code that should be collapsed by default to save vertical space.
+
+```tsx
+<CodeSnippet value={longCode} language="typescript" collapsible rows={5} />
+```
+
+### With Copy Callback Code Snippet
+
+Use when you need to track or respond to copy events, such as for analytics.
+
+```tsx
+<CodeSnippet value={sampleCode} language="typescript" onCopySuccess={handleCopy} />
+```
+
+### With Custom Actions Code Snippet
+
+Use when you need to add custom actions to the code snippet. For Buttons, prefer 'tiny' size.
+
+```tsx
+<CodeSnippet
+ value={sampleCode}
+ language="typescript"
+ slotActions={
+ <Button className="mr-auto" kind="secondary" size="tiny">
+ Run
+ </Button>
+ }
+/>
+```
+
+### With Fixed Theme
+
+By default, the code snippet will render in the current theme. You can fix the theme to light or dark by applying the light or dark class to the CodeSnippet or its parent
+
+```tsx
+<div className="nv-dark bg-surface-base">
+ <CodeSnippet value={sampleCode} language="typescript" />
+</div>
+```
+
+### With Server Side Rendering Code Snippet
+
+Use when you need to server-side render the code snippet.
+
+```tsx
+;async () => {
+ // use highlightCode util to server side highlight the code
+ const prerenderedCode = await highlightCode(sampleCode, 'typescript')
+ return <CodeSnippet defaultValue={prerenderedCode} language="typescript" value={sampleCode} />
+}
+```
+
+### Composed
+
+```tsx
+<Flex>
+ Block:
+ <CodeSnippetRoot kind="block" collapsible rows={4}>
+ <CodeSnippetActions>
+ <Button kind="secondary" size="tiny">
+ Custom Action
+ </Button>
+ <CodeSnippetCopyButton value={sampleCode} />
+ <CodeSnippetExpanderButton />
+ </CodeSnippetActions>
+ <CodeSnippetCode value={sampleCode} language="typescript" />
+ </CodeSnippetRoot>
+ Inline:
+ <CodeSnippetRoot kind="inline">
+ <CodeSnippetCode value={sampleCode} language="typescript" />
+ </CodeSnippetRoot>
+</Flex>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **kind** \* | `"inline" \| "block"` | `"block"` | The kind of code snippet to render. |
+| **value** \* | `string` | - | The code to display in the code snippet. |
+| collapsible | `never \| boolean` | - | Whether the code snippet is collapsible. Only valid when kind is "block". |
+| defaultOpen | `boolean` | `false` | Default open state for uncontrolled mode. |
+| defaultValue | `string` | - | Pre-rendered HTML for the code snippet. If provided, skips client-side highlighting entirely. **For SSR**: Pass server-rendered HTML here to ensure perfect hydration without re-highlighting. |
+| language | `"html" \| "text" \| "go" \| "typescript" \| "javascript" \| "tsx" \| "jsx" \| "json" \| "css" \| "bash" \| "shell" \| "python" \| "rust" \| "yaml" \| "markdown"` | `"text"` | The language to use for syntax highlighting. |
+| onCopySuccess | `() => void` | - | The callback to call when the code snippet is copied successfully |
+| onOpenChange | `(open: boolean) => void` | - | Callback fired when the open state changes. |
+| open | `boolean` | - | Controlled open state. |
+| rows | `never \| number` | - | The number of rows to show. If collapsible is true, this applies when collapsed. If collapsible is false, this sets a fixed height with scroll. Only valid when kind is "block". |
+| slotActions | `ReactNode` | - | The actions to display on top of the code snippet. |
+| structure | `"inline" \| "classic"` | `Derived from `kind` prop` | The HTML structure to use for rendering. - `classic`: Uses block-level elements (`<div>`, `<pre>`, `<code>`) - cannot be nested inside `<p>` tags - `inline`: Uses inline elements (`<span>`) - safe to nest inside `<p>` tags (e.g., from Markdown) If not specified, defaults based on `kind`: - `kind="block"` → `structure="classic"` - `kind="inline"` → `structure="inline"` Override this when you need block-styled code (with actions, copy button, etc.) but must render inside a `<p>` tag. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Collapsible.md b/.agents/skills/kaizen-ui/references/components/Collapsible.md
new file mode 100644
index 0000000..c554d9e
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Collapsible.md
@@ -0,0 +1,104 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Collapsible
+
+A utility component that allows you to collapse and expand content.
+
+## Examples
+
+### Basic Collapsible
+
+Use when content should be hidden by default to reduce visual noise but available on demand.
+
+```tsx
+<Collapsible slotTrigger="Trigger content">Hidden content revealed on expand.</Collapsible>
+```
+
+### Default Open Collapsible
+
+```tsx
+<Collapsible defaultOpen slotTrigger="Hide details">
+ Content visible by default.
+</Collapsible>
+```
+
+### With Icon In Trigger
+
+```tsx
+<Collapsible
+ slotTrigger={
+ <span className="inline-flex items-center gap-2">
+ <ChevronDown />
+ Header
+ </span>
+ }
+>
+ Content
+</Collapsible>
+```
+
+### With Chevron Trigger
+
+The AnimatedChevron component automatically reads the open/closed state from Collapsible.
+
+```tsx
+<Collapsible
+ slotTrigger={
+ <>
+ <AnimatedChevron /> Toggle content
+ </>
+ }
+>
+ Content
+</Collapsible>
+```
+
+### With Button Trigger
+
+When using a Button in slotTrigger with asChild, render it as a non-interactive element like <div> or <span> to avoid nested interactive elements, allowing the native <summary> element to handle the toggle behavior.
+
+```tsx
+<Collapsible
+ slotTrigger={
+ <Button asChild kind="tertiary">
+ <div>Toggle content</div>
+ </Button>
+ }
+>
+ Content
+</Collapsible>
+```
+
+### Composed
+
+Use composed primitives when you want to render the trigger and content apart from each other.
+
+```tsx
+<CollapsibleRoot defaultOpen>
+ <CollapsibleTrigger>
+ <Button asChild kind="tertiary">
+ <div>
+ Toggle content
+ <AnimatedChevron />
+ </div>
+ </Button>
+ </CollapsibleTrigger>
+ <CollapsibleContent>Additional content - visible by default.</CollapsibleContent>
+</CollapsibleRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------------ | ------------------------- | ------- | ----------------------- |
+| **children** \* | `ReactNode` | - | The collapsible content |
+| **slotTrigger** \* | `ReactNode` | - | The collapsible trigger |
+| defaultOpen | `boolean` | - | |
+| disabled | `boolean` | - | |
+| onOpenChange | `(open: boolean) => void` | - | |
+| open | `boolean` | - | |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Combobox.md b/.agents/skills/kaizen-ui/references/components/Combobox.md
new file mode 100644
index 0000000..7de4f14
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Combobox.md
@@ -0,0 +1,240 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Combobox
+
+A Combobox combines a text input and listbox to let users filter and pick
+from declarative `items`.
+
+## Examples
+
+### Basic Combobox
+
+```tsx
+<Flex direction="col" gap="2">
+ <Combobox
+ aria-label="Fruit"
+ items={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']}
+ placeholder="Search fruits..."
+ />
+ <Combobox
+ aria-label="Fruit"
+ defaultValue={['Apple', 'Banana']}
+ multiple
+ items={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']}
+ placeholder="Search fruits..."
+ />
+</Flex>
+```
+
+### With Default Value Combobox
+
+```tsx
+<Combobox aria-label="Fruit" items={['Apple', 'Banana', 'Cherry']} defaultValue="Banana" />
+```
+
+### Multiple Combobox
+
+Use when users need to select multiple values with type-ahead filtering. By default, the selected values are rendered as tags in the trigger.
+
+```tsx
+<Combobox
+ aria-label="Colors"
+ items={['Red', 'Green', 'Blue', 'Yellow']}
+ multiple
+ placeholder="Pick colors..."
+/>
+```
+
+### Multiple Combobox With Default Values
+
+```tsx
+<Combobox
+ aria-label="Colors"
+ items={['Red', 'Green', 'Blue', 'Yellow']}
+ multiple
+ defaultValue={['Red', 'Green']}
+ placeholder="Pick colors..."
+/>
+```
+
+### Combobox With Separate Item Values
+
+```tsx
+<Combobox
+ aria-label="Colors"
+ items={[
+ { value: 'red', children: 'Red (value: red)' },
+ { value: 'green', children: 'Green (value: green)' },
+ { value: 'blue', children: 'Blue (value: blue)' },
+ { value: 'yellow', children: 'Yellow (value: yellow)' }
+ ]}
+ multiple
+ defaultValue={['red', 'green']}
+ placeholder="Pick colors..."
+/>
+```
+
+### Combobox With Rich Item Children
+
+When setting rich children in `items`, you should also provide a `filterValue` which is a text only representation of `children` that will be used for type-ahead filtering.
+
+```tsx
+<Combobox
+ aria-label="Colors"
+ items={[
+ {
+ value: 'red',
+ filterValue: 'Red',
+ children: (
+ <Flex align="center" gap="density-md">
+ <CircleFill /> Red
+ </Flex>
+ )
+ }
+ ]}
+ placeholder="Pick colors..."
+/>
+```
+
+### Multiple Count Mode Combobox
+
+Use count mode when many selections are expected and individual tags would overflow the trigger.
+
+```tsx
+<Combobox
+ aria-label="Tags"
+ items={VERY_LONG_LIST}
+ multiple
+ multipleMode="count"
+ placeholder="Select frameworks..."
+/>
+```
+
+### Grouped Items Combobox
+
+Use when options logically belong to categories that help users scan the list.
+
+```tsx
+<Combobox
+ aria-label="Team member"
+ items={[
+ { slotHeading: 'Engineering', items: ['Ada', 'Grace'] },
+ { slotHeading: 'Design', items: ['Charles', 'Dorothy'] }
+ ]}
+ placeholder="Search team..."
+/>
+```
+
+### Custom Empty State Combobox
+
+```tsx
+<Combobox aria-label="Fruit" items={[]} emptyStateMessage="No fruits found" />
+```
+
+### Dismissible Combobox
+
+Use when users need a quick way to clear their selection.
+
+```tsx
+<Combobox
+ aria-label="Fruit"
+ items={['Apple', 'Banana', 'Cherry']}
+ dismissible
+ defaultValue="Apple"
+/>
+```
+
+### Disabled Combobox
+
+Use when the selection is locked by external conditions.
+
+```tsx
+<Combobox aria-label="Fruit" items={['Apple', 'Banana']} disabled defaultValue="Apple" />
+```
+
+### With Slot Start And End Combobox
+
+```tsx
+<Combobox
+ aria-label="Fruit"
+ items={['Apple', 'Banana']}
+ slotStart={<SomeIcon />}
+ slotEnd={<SomeIcon />}
+/>
+```
+
+### With Async Loading Combobox
+
+```tsx
+<Combobox
+ aria-label="Fruit"
+ items={VERY_LONG_LIST}
+ onScrollToBottom={() => {
+ console.log('Loading more items...')
+ }}
+/>
+```
+
+### Composed
+
+Use the composed primitives when you need full control over trigger rendering, content layout, or custom items.
+
+```tsx
+<ComboboxRoot defaultValue="Apple">
+ <ComboboxTrigger placeholder="Pick a fruit..." />
+ <ComboboxContent>
+ <ComboboxItem value="Apple">Apple</ComboboxItem>
+ <ComboboxItem value="Banana">Banana</ComboboxItem>
+ <ComboboxItem value="Cherry">Cherry</ComboboxItem>
+ </ComboboxContent>
+</ComboboxRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ items: string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string })[]; children: never; kind: "section"; filterValue: never; slotHeading: ReactNode })[]` | - | The items to render in the Combobox. |
+| allowBackspaceRemoval | `boolean` | - | In multi-select mode, pressing `Backspace` while the input is empty removes the last selected value. When omitted, the default is derived from the selected-values display: enabled when `ComboboxSelectedTags` is mounted in the default `mode="tags"` with no custom renderer (so each selected value has a visible, clearly labelled tag the shortcut targets), and disabled otherwise (`mode="count"`, custom renderer, or no selected-values display at all). Pass an explicit boolean to override the derived default. |
+| children | `(props: { mode: "count" \| "tags"; removeSelectedValue: (value: string) => void; selectedItems: { label: string; value: string; }[]; summaryLabel: string }) => ReactNode` | - | Optional custom renderer for the selected values. When provided, `ComboboxRoot` treats the display as custom and disables `allowBackspaceRemoval` by default. |
+| className | `string` | - | |
+| defaultInputValue | `string` | - | The input value when the Combobox is initially rendered. |
+| defaultOpen | `boolean` | - | The open state of the Combobox when it is initially rendered. |
+| defaultValue | `string \| string[]` | - | The selected value when the Combobox is initially rendered. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| disabled | `boolean` | - | Disables the Combobox. |
+| dismissible | `boolean` | - | When true, renders a dismiss button that clears the Combobox. |
+| emptyStateMessage | `string` | `"No results found"` | The message to display when no results are found. |
+| filteringBehavior | `"after-input" \| "on-open"` | `"after-input"` | Controls when the option list begins filtering. - `"after-input"` shows all options when the popover opens, then filters after the user types. - `"on-open"` filters immediately using the current input value. |
+| filterMatchFn | `(matchTerm: string, value: string) => boolean` | - | Overrides the default substring matching used to filter items. |
+| formatSummaryLabel | `(count: number) => string` | - | Optional formatter for the count summary label used when `mode="count"` and by render-prop consumers. |
+| hideOnEscape | `boolean` | `true` | Whether the Combobox should close when the escape key is pressed. |
+| id | `string` | - | The id used for the input element. |
+| inputValue | `string` | - | Controlled input value. |
+| kind | `"flat" \| "floating"` | `"flat"` | The kind of input to render. - "flat" - renders with a border and background - "floating" - renders borderless with no background |
+| multiple | `boolean` | `false` | Enables single-select mode. |
+| multipleMode | `"count" \| "tags"` | `"tags"` | Controls how selected values are rendered in multi-select mode. Forwarded to `ComboboxSelectedTags` as its `mode` prop. - `"tags"` renders each selection as an individual, clearly labelled tag. - `"count"` renders a compact summary of how many values are selected. The choice also drives the default for `allowBackspaceRemoval`: the shortcut is enabled by default only when `"tags"` is used with no custom `renderValue`/`children`. |
+| name | `string` | - | The form field name used by the hidden native `<select>`. |
+| onInputValueChange | `(value: string) => void` | - | Callback fired when the input text changes. |
+| onOpenChange | `(open: boolean) => void` | - | Callback fired when the popover opens or closes. |
+| onScrollToBottom | `() => void` | - | Callback fired when the listbox scrolls to the bottom. Useful for async loading scenarios. |
+| onValueChange | `((value: string) => void) \| ((value: string[]) => void)` | - | Callback fired when the selected value changes. |
+| open | `boolean` | - | Controlled open state. |
+| placeholder | `string` | - | Placeholder text shown before a value is selected or typed. Pass `null` to explicitly show no placeholder. |
+| readOnly | `boolean` | - | Prevents the value from being changed while preserving form submission. |
+| renderValue | `(value: string \| string[], setValue: ((nextValue: string \| string[]) => void) \| ((nextValueFunc: (prevValue: string \| string[]) => string \| string[]) => void)) => ReactNode` | - | Controls the value rendered when a multi-select Combobox is closed. |
+| required | `boolean` | - | Whether the field is required. |
+| resetValueOnBlur | `boolean` | `false` | Restores the input text to the selected option label on blur, or clears unmatched text when nothing is selected. |
+| selectRef | `((instance: HTMLSelectElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLSelectElement>` | - | Callback ref for the hidden native `<select>` used for form submission. |
+| side | `"right" \| "bottom" \| "left" \| "top"` | `"bottom"` | Side used for the popover positioning. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | Visual size of the Combobox trigger. |
+| slotEnd | `ReactNode` | - | Content rendered after the input. |
+| slotStart | `ReactNode` | - | Content rendered before the input. |
+| status | `"error" \| "success"` | - | The status of the input. Use `withValidation` to automatically apply success/error states based on `:user-valid` and `:user-invalid` pseudo classes. |
+| style | `React.CSSProperties` | - | |
+| value | `string \| string[]` | - | Controlled selected value. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/DatePicker.md b/.agents/skills/kaizen-ui/references/components/DatePicker.md
new file mode 100644
index 0000000..7e2b865
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/DatePicker.md
@@ -0,0 +1,237 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# DatePicker
+
+A complete date picker component with input field(s) and calendar popup.
+Supports both single date selection and date range selection modes.
+The component handles manual date entry through input fields and provides a calendar interface for visual date selection.
+
+## Examples
+
+### Basic Date Picker
+
+Use when users need to select a single date.
+
+```tsx
+<DatePicker />
+```
+
+### Range Date Picker
+
+Set `kind="range"` when users need to select a start and end date, such as for filtering or scheduling.
+
+```tsx
+<DatePicker kind="range" />
+```
+
+### With Default Value Date Picker
+
+Single pickers accept a `Date` for `defaultValue` / `value` and emit `Date | undefined` from `onValueChange`. Range pickers accept a `DateRange` object with optional `from` / `to` Date properties and emit `DateRange | undefined`. The value can become `undefined` when the user clears the field, so always treat the controlled value as nullable.
+
+```tsx
+<Flex direction="col" gap="2">
+ <DatePicker defaultValue={new Date()} />
+ <DatePicker
+ kind="range"
+ defaultValue={{
+ from: new Date(),
+ to: new Date(Date.now() + 7 * 86_400_000)
+ }}
+ />
+</Flex>
+```
+
+### With Range Placeholder Date Picker
+
+Pass an object `{ from, to }` to give the range fields distinct placeholders. A plain string is applied to both inputs.
+
+```tsx
+<DatePicker kind="range" placeholder={{ from: 'Start date', to: 'End date' }} />
+```
+
+### Disable Weekends Date Picker
+
+Use `{ dayOfWeek: [...] }` to disable specific days, where 0 is Sunday and 6 is Saturday. The same matcher shape applies to range pickers.
+
+```tsx
+<DatePicker disabledMatcher={{ dayOfWeek: [0, 6] }} />
+```
+
+### Disable Past Dates Date Picker
+
+Use `{ before }` to forbid dates earlier than a cutoff (here, today), or `{ after }` for the inverse.
+
+```tsx
+<DatePicker disabledMatcher={{ before: new Date() }} />
+```
+
+### Combined Disabled Matcher Date Picker
+
+Pass an array to combine matchers; any date matched by _any_ entry is disabled. Other matcher shapes include a single `Date`, an array of `Date`s, a `{ from, to }` range, and a predicate `(date) => boolean`.
+
+```tsx
+<DatePicker kind="range" disabledMatcher={[{ dayOfWeek: [0, 6] }, { before: new Date() }]} />
+```
+
+### Constrained Range Date Picker
+
+On a range picker `min` and `max` are the minimum and maximum number of **nights** in the selection — not absolute dates. HTML cannot couple two native date inputs, so these are only enforced by the enhanced widget; re-validate no-JS submissions with `validateDateRangeNights` on the server.
+
+```tsx
+<DatePicker kind="range" min={3} max={30} />
+```
+
+### Exclude Disabled Dates Range Date Picker
+
+Range-only. With `excludeDisabledDates`, users cannot select a range that spans a disabled date. Without it, the range may straddle disabled dates as long as the endpoints themselves are selectable.
+
+```tsx
+<DatePicker kind="range" disabledMatcher={{ dayOfWeek: [0, 6] }} excludeDisabledDates />
+```
+
+### Calendar Bounds Date Picker
+
+Use `startMonth` and `endMonth` to constrain the navigable calendar window (defaults: 100 years ago to 5 years from now). These values are also translated into native `min` / `max` for the no-JS fallback. Use `defaultMonth` to set the initially-visible month without selecting a date.
+
+```tsx
+<DatePicker
+ startMonth={new Date(2024, 0, 1)}
+ endMonth={new Date(2024, 11, 31)}
+ defaultMonth={new Date(2024, 5, 1)}
+/>
+```
+
+### Custom Format Date Picker
+
+`format` accepts a `date-fns` token string (e.g. `"yyyy-MM-dd"`, `"dd-MM-yyyy"`, `"MMM d, yyyy"`). Display formatting only — the form value is always submitted as ISO `yyyy-MM-dd`.
+
+```tsx
+<DatePicker format="yyyy-MM-dd" />
+```
+
+### Custom Format Function Date Picker
+
+Use `formatFn` for full control over display formatting; it overrides `format`. Always set `placeholder` when supplying `formatFn` because the format string can no longer be used as a default hint.
+
+```tsx
+<DatePicker
+ formatFn={date =>
+ date.toLocaleDateString('en-US', {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric'
+ })
+ }
+ placeholder="Mon D, YYYY"
+/>
+```
+
+### Time Zone Date Picker
+
+Pass an IANA name (e.g. `"America/New_York"`) or UTC offset (e.g. `"-05:00"`) so the picker interprets and renders the date in that zone instead of the user's local zone.
+
+```tsx
+<DatePicker timeZone="America/New_York" defaultValue={new Date('2024-06-01T12:00:00Z')} />
+```
+
+### Form Submission Date Picker
+
+Apply the form `name` to `DatePickerNativeFallback`, not to `DatePickerInput`. The enhanced text input is display-only; the hidden native `<input type="date">` is the element that participates in form submission and always submits an ISO `yyyy-MM-dd` value. Use `parseDateFromFormData(formData, "dueDate")` on the server.
+
+```tsx
+<DatePicker
+ attributes={{
+ DatePickerNativeFallback: { name: 'dueDate' }
+ }}
+/>
+```
+
+### Form Submission Range Date Picker
+
+Range pickers submit two independent ISO values, so set the `name` on both `DatePickerNativeFallbackFrom` and `DatePickerNativeFallbackTo`. Parse with `parseDateRangeFromFormData(formData, { from: "rolloutFrom", to: "rolloutTo" })`.
+
+```tsx
+<DatePicker
+ kind="range"
+ attributes={{
+ DatePickerNativeFallbackFrom: { name: 'rolloutFrom' },
+ DatePickerNativeFallbackTo: { name: 'rolloutTo' }
+ }}
+/>
+```
+
+### Custom Input Attributes Date Picker
+
+Use the `attributes` API to set per-input `aria-label`, `autoComplete`, `data-*`, etc. without dropping to composed primitives. Single pickers expose `DatePickerInput`; range pickers expose `DatePickerInputFrom` and `DatePickerInputTo`.
+
+```tsx
+<DatePicker
+ kind="range"
+ attributes={{
+ DatePickerInputFrom: {
+ autoComplete: 'off',
+ 'aria-label': 'Trip start date'
+ },
+ DatePickerInputTo: {
+ autoComplete: 'off',
+ 'aria-label': 'Trip end date'
+ }
+ }}
+/>
+```
+
+### Composed
+
+Use the composed primitives when you need full control over trigger, input, calendar layout, or to slot in a custom rendering between any of them.
+
+```tsx
+<DatePickerRoot kind="single">
+ <DatePickerTrigger>
+ <DatePickerInput />
+ <DatePickerNativeFallback />
+ </DatePickerTrigger>
+ <DatePickerContent>
+ <DatePickerCalendar />
+ </DatePickerContent>
+</DatePickerRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| align | `"center" \| "start" \| "end"` | `"center"` | The alignment of the popover content relative to the trigger. |
+| closeOnApply | `boolean` | `true` | Whether to close the datepicker when the apply button is clicked. |
+| defaultMonth | `Date` | `Current month` | The visible month in the datepicker calendar when initially rendered. Use when you do not need to control the month of the datepicker calendar. |
+| defaultOpen | `boolean` | `false` | The open state of the datepicker when it is initially rendered. Use when you do not need to control its open state. |
+| defaultValue | `Date \| { from: Date; to?: Date; }` | - | The initial value. |
+| disabled | `boolean` | - | Whether the datepicker is disabled. |
+| disabledMatcher | `false \| true \| Date \| ((date: Date) => boolean) \| Date[] \| { from: Date; to?: Date; } \| { before: Date; } \| { after: Date; } \| { before: Date; after: Date; } \| { dayOfWeek: number \| number[]; } \| (false \| true \| Date \| ((date: Date) => boolean) \| Date[] \| { from: Date; to?: Date; } \| { before: Date; } \| { after: Date; } \| { before: Date; after: Date; } \| { dayOfWeek: number \| number[]; }[])` | - | Matcher for disabled dates. This can be a single matcher or an array of matchers. |
+| dismissible | `boolean` | - | Whether to show a dismiss/clear button when the input has a value. |
+| endMonth | `Date` | `5 years from now` | The latest month that can be selected from in the datepicker calendar. |
+| excludeDisabledDates | `boolean` | - | When true, excludes disabled dates from range. |
+| format | `string` | `"M/d/yyyy"` | The date format string using `date-fns` format syntax. Used to format the date displayed in the input field and as the default placeholder text. When `formatFn` is provided, this prop is ignored in favor of the custom formatting function. |
+| formatFn | `(date: Date) => string` | - | Custom formatting function for displaying dates in the input field. When provided, this takes precedence over the `format` prop. It's recommended to set a relevant `placeholder` when supplying a custom format function. |
+| kind | `"single" \| "range"` | - | The kind of datepicker. |
+| max | `number` | - | Maximum number of nights in a range. |
+| min | `number` | - | Minimum number of nights in a range. |
+| modal | `boolean` | `false` | The modality of the datepicker. When set to true, interaction with outside elements will be disabled and only datepicker content will be visible to screen readers. Modality is disabled by default to minimize performance impact. |
+| month | `Date` | - | The controlled value of the month in the datepicker calendar. Must be used in conjunction with `onMonthChange`. Use this when you need to programmatically control which month is displayed. |
+| onCloseAutoFocus | `(event: Event) => void` | - | Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`. |
+| onEscapeKeyDown | `(event: KeyboardEvent) => void` | - | Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. |
+| onMonthChange | `(month: Date) => void` | - | Event handler called when the month changes through navigation or dropdown selection. Use this to track or respond to month navigation within the calendar. |
+| onOpenChange | `(open: boolean) => void` | - | Event handler called when the open state of the datepicker changes. |
+| onValueChange | `(value: Date) => void \| (value: { from: Date; to?: Date; }) => void` | - | Event handler called when the value changes. |
+| open | `boolean` | - | The controlled open state of the datepicker. Must be used in conjunction with `onOpenChange`. |
+| placeholder | `string \| string \| { from?: string; to?: string; }` | - | The placeholder text. |
+| readOnly | `boolean` | - | Whether the datepicker is read-only. |
+| renderDropdown | `(props: { className?: string; children?: React.ReactNode; kind: "month" \| "year"; items: DropdownEntry[]; onItemSelect?: (event: Event, item: DropdownDefaultItemEntry \| DropdownCheckboxItemEntry \| DropdownRadioItemEntry) => void; }) => React.JSX.Element` | - | Custom function to render the dropdown for month and year selection. Use this to customize the appearance or behavior of the month/year dropdown menus. The props passed to this function use the standard DropdownProps interface. |
+| side | `"right" \| "bottom" \| "left" \| "top"` | `"bottom"` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the input to render. Available sizes are "small", "medium", and "large". |
+| startMonth | `Date` | - | The earliest month that can be selected from in the datepicker calendar. |
+| status | `"error" \| "success"` | - | The status of the datepicker. |
+| timeZone | `string` | - | The time zone (IANA or UTC offset) to use. |
+| value | `Date \| { from: Date; to?: Date; }` | - | The controlled value. |
diff --git a/.agents/skills/kaizen-ui/references/components/Divider.md b/.agents/skills/kaizen-ui/references/components/Divider.md
new file mode 100644
index 0000000..e05a195
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Divider.md
@@ -0,0 +1,80 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Divider
+
+A visual separator that creates a clear distinction between content sections
+
+## Examples
+
+### Basic Divider
+
+```tsx
+<Flex className="w-full" direction="col" gap="3">
+ <Divider />
+ <Divider width="medium" />
+ <Divider width="large" />
+</Flex>
+```
+
+### With Text
+
+```tsx
+<Flex align="center" gap="density-lg">
+ <Divider />
+ <Text kind="label/semibold/md">Text</Text>
+ <Divider />
+</Flex>
+```
+
+### Vertical Divider
+
+```tsx
+<Divider orientation="vertical" />
+```
+
+### Composed
+
+```tsx
+<DividerRoot paddingY="2">
+ <DividerElement orientation="horizontal" width="medium" />
+</DividerRoot>
+```
+
+## Props
+
+type SpacingScaleUnion
+
+Prefer semantic density tokens that adapt to the active density theme (compact, standard, spacious):
+"density-xxs" | "density-xs" | "density-sm" | "density-md" | "density-lg" | "density-xl" | "density-2xl" | "density-3xl" | "density-4xl" | "density-5xl"
+
+| Token | Compact | Standard | Spacious |
+| ----------- | ------- | -------- | -------- |
+| density-xxs | 1px | 2px | 4px |
+| density-xs | 2px | 4px | 6px |
+| density-sm | 4px | 6px | 8px |
+| density-md | 6px | 8px | 12px |
+| density-lg | 8px | 12px | 16px |
+| density-xl | 12px | 16px | 24px |
+| density-2xl | 16px | 24px | 32px |
+| density-3xl | 24px | 32px | 48px |
+| density-4xl | 32px | 48px | 64px |
+| density-5xl | 48px | 64px | 80px |
+
+Raw scale values (4px base unit — use only when density tokens don't fit):
+"0" | "0.25" | "0.5" | "0.75" | "1" | "1.5" | "2" | "2.5" | "3" | "3.5" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "14" | "16" | "18" | "20" | "24" | "28" | "32" | "36" | "40" | "44" | "48" | "52" | "56" | "60" | "64" | "72" | "80" | "96" | "250" | "inherit" | "px"
+
+| Prop | Type | Default | Description |
+| ------------- | -------------------------------- | -------------- | ------------------------------------------------ |
+| asChild | `boolean` | `false` | Whether to render the divider as a child element |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the divider element |
+| padding | `SpacingScaleUnion` | - | Sets padding. |
+| paddingBottom | `SpacingScaleUnion` | - | Sets bottom padding. |
+| paddingLeft | `SpacingScaleUnion` | - | Sets left padding. |
+| paddingRight | `SpacingScaleUnion` | - | Sets right padding. |
+| paddingTop | `SpacingScaleUnion` | - | Sets top padding. |
+| paddingX | `SpacingScaleUnion` | - | Sets horizontal padding. |
+| paddingY | `SpacingScaleUnion` | - | Sets vertical padding. |
+| width | `"small" \| "medium" \| "large"` | `"small"` | The width/thickness of the divider element |
diff --git a/.agents/skills/kaizen-ui/references/components/Dropdown.md b/.agents/skills/kaizen-ui/references/components/Dropdown.md
new file mode 100644
index 0000000..2409235
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Dropdown.md
@@ -0,0 +1,433 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Dropdown
+
+Use Dropdowns to allow users to select one or multiple options, navigate through links, or take
+actions. Dropdowns are often used for navigation, filters, or contextual actions.
+
+## Examples
+
+### Basic Dropdown With Links
+
+```tsx
+<Dropdown
+ items={[
+ { children: 'Item 1', href: '/item-1' },
+ { children: 'Item 2', href: '/item-2' },
+ { children: 'Item 3', href: '/item-3' }
+ ]}
+ // replace default anchor with a custom link component using the renderLink prop
+ // renderLink={(item) => <Link href={item.href}>{item.children}</Link>}
+>
+ Actions
+</Dropdown>
+```
+
+### Basic Dropdown With Handlers
+
+Use when you need a simple list of actions triggered from a button.
+
+```tsx
+<Dropdown
+ items={[
+ { children: 'Edit', onSelect: handleSelect },
+ { children: 'Duplicate', onSelect: handleSelect },
+ { children: 'Delete', danger: true, onSelect: handleSelect }
+ ]}
+>
+ Actions
+</Dropdown>
+```
+
+### With Item Select Callback Dropdown
+
+Use the aggregate onItemSelect callback when every item shares the same selection logic — easier to wire into a router, analytics, or a reducer than per-item onSelect handlers. Reach for per-item onSelect when each item needs distinct behavior.
+
+```tsx
+<Dropdown
+ items={[
+ { children: 'Edit', value: 'edit' },
+ { children: 'Duplicate', value: 'duplicate' },
+ { children: 'Delete', value: 'delete', danger: true }
+ ]}
+ onItemSelect={handleItemSelect}
+>
+ Actions
+</Dropdown>
+```
+
+### With Icons Dropdown
+
+Use slotStart and slotEnd to add leading or trailing icons that reinforce each item's meaning.
+
+```tsx
+<Dropdown
+ items={[
+ {
+ children: 'Edit',
+ slotStart: <Document />,
+ onSelect: handleSelect
+ },
+ {
+ children: 'Duplicate',
+ slotStart: <CopyDoc />,
+ slotEnd: <InfoCircle />,
+ onSelect: handleSelect
+ },
+ {
+ children: 'Delete',
+ danger: true,
+ slotStart: <Trash />,
+ onSelect: handleSelect
+ }
+ ]}
+>
+ Actions
+</Dropdown>
+```
+
+### With Sections Dropdown
+
+Use when dropdown items are logically grouped into categories that benefit from visual separation.
+
+```tsx
+<Dropdown
+ items={[
+ {
+ slotHeading: 'Navigation',
+ items: [
+ { children: 'Dashboard', onSelect: handleSelect },
+ { children: 'Settings', onSelect: handleSelect }
+ ]
+ },
+ {
+ slotHeading: 'Account',
+ items: [
+ { children: 'Profile', onSelect: handleSelect },
+ { children: 'Sign Out', danger: true, onSelect: handleSelect }
+ ]
+ }
+ ]}
+>
+ Menu
+</Dropdown>
+```
+
+### With Sub Menu Dropdown
+
+Use when certain actions have nested options that should be discoverable without cluttering the main list.
+
+```tsx
+<Dropdown
+ items={[
+ { children: 'Cut', onSelect: handleSelect },
+ { children: 'Copy', onSelect: handleSelect },
+ {
+ kind: 'sub',
+ children: 'Share',
+ items: [
+ { children: 'Email', onSelect: handleSelect },
+ { children: 'Slack', onSelect: handleSelect }
+ ]
+ }
+ ]}
+>
+ Edit
+</Dropdown>
+```
+
+### With Dividers Dropdown
+
+Insert a divider entry to visually separate destructive or unrelated actions inside a flat list.
+
+```tsx
+<Dropdown
+ items={[
+ { children: 'Open', onSelect: handleSelect },
+ { children: 'Open in New Tab', onSelect: handleSelect },
+ { kind: 'divider' },
+ { children: 'Rename', onSelect: handleSelect },
+ { children: 'Move', onSelect: handleSelect },
+ { kind: 'divider' },
+ { children: 'Delete', danger: true, onSelect: handleSelect }
+ ]}
+>
+ File
+</Dropdown>
+```
+
+### Checkbox Dropdown
+
+Use when the user needs to toggle multiple independent options from a single dropdown.
+
+```tsx
+<Dropdown
+ items={[
+ {
+ children: 'Show Labels',
+ kind: 'checkbox',
+ defaultChecked: true
+ },
+ {
+ children: 'Show Tooltips',
+ kind: 'checkbox'
+ },
+ {
+ children: 'Compact Mode',
+ kind: 'checkbox'
+ }
+ ]}
+>
+ View Options
+</Dropdown>
+```
+
+### Radio Dropdown
+
+Use when the user must pick exactly one option from a group of mutually exclusive choices.
+
+```tsx
+<Dropdown
+ items={[
+ {
+ kind: 'radio',
+ name: 'theme',
+ slotHeading: 'Theme',
+ defaultValue: 'auto',
+ items: [
+ { children: 'Auto', value: 'auto' },
+ { children: 'Light', value: 'light' },
+ { children: 'Dark', value: 'dark' }
+ ]
+ }
+ ]}
+>
+ Theme
+</Dropdown>
+```
+
+### Check Radio Dropdown
+
+Set radioKind to 'check' when you want a single checkmark on the selected option instead of radio dots — common for compact filter or theme pickers.
+
+```tsx
+<Dropdown
+ items={[
+ {
+ kind: 'radio',
+ radioKind: 'check',
+ name: 'status',
+ slotHeading: 'Status',
+ defaultValue: 'ready',
+ items: [
+ { children: 'Ready', value: 'ready' },
+ { children: 'Pending', value: 'pending' },
+ { children: 'Completed', value: 'completed' }
+ ]
+ }
+ ]}
+>
+ Status
+</Dropdown>
+```
+
+### Mixed Dropdown
+
+Combine action items, checkbox toggles, and radio groups in a single dropdown by nesting them in sections.
+
+```tsx
+<Dropdown
+ items={[
+ {
+ slotHeading: 'Actions',
+ items: [
+ { children: 'Edit', onSelect: handleSelect },
+ { children: 'Duplicate', onSelect: handleSelect },
+ { children: 'Delete', danger: true, onSelect: handleSelect }
+ ]
+ },
+ {
+ slotHeading: 'Settings',
+ items: [
+ {
+ kind: 'checkbox',
+ children: 'Show notifications',
+ defaultChecked: true
+ },
+ {
+ kind: 'checkbox',
+ children: 'Auto-save',
+ defaultChecked: false
+ }
+ ]
+ },
+ {
+ kind: 'radio',
+ slotHeading: 'Theme',
+ name: 'mixed-theme',
+ defaultValue: 'system',
+ items: [
+ { children: 'System', value: 'system' },
+ { children: 'Light', value: 'light' },
+ { children: 'Dark', value: 'dark' }
+ ]
+ }
+ ]}
+>
+ More
+</Dropdown>
+```
+
+### Filterable Dropdown
+
+Use when the dropdown contains many items and the user benefits from searching to find their selection quickly.
+
+```tsx
+<Dropdown
+ filterable
+ items={[
+ { children: 'United States', onSelect: handleSelect },
+ { children: 'Canada', onSelect: handleSelect },
+ { children: 'United Kingdom', onSelect: handleSelect },
+ { children: 'Germany', onSelect: handleSelect },
+ { children: 'Japan', onSelect: handleSelect }
+ ]}
+>
+ Select Country
+</Dropdown>
+```
+
+### Icon Only Trigger Dropdown
+
+Use an icon child with showChevron={false} for kebab/overflow menus where space is constrained. Always supply an aria-label.
+
+```tsx
+<Dropdown
+ showChevron={false}
+ aria-label="More actions"
+ items={[
+ { children: 'Edit', onSelect: handleSelect },
+ { children: 'Duplicate', onSelect: handleSelect },
+ { children: 'Delete', danger: true, onSelect: handleSelect }
+ ]}
+>
+ <MenuIcon />
+</Dropdown>
+```
+
+### Size Dropdown
+
+Match the trigger size to the surrounding controls. Pass density to override the menu's default density independently from the trigger size.
+
+```tsx
+<Flex gap="2" align="center" wrap="wrap">
+ <Dropdown size="small" items={['Item 1', 'Item 2', 'Item 3']}>
+ Small
+ </Dropdown>
+ <Dropdown size="medium" items={['Item 1', 'Item 2', 'Item 3']}>
+ Medium
+ </Dropdown>
+ <Dropdown size="large" items={['Item 1', 'Item 2', 'Item 3']}>
+ Large
+ </Dropdown>
+</Flex>
+```
+
+### Positioning Dropdown
+
+Combine `side` (`top` | `bottom` | `left` | `right`) and `align` (`start` | `center` | `end`) to override the default `bottom`/`start` placement when the menu would clip against a scroll container or viewport edge.
+
+```tsx
+<Dropdown side="right" align="end" items={['Item 1', 'Item 2', 'Item 3']}>
+ Open
+</Dropdown>
+```
+
+### Server Actions Dropdown
+
+Wrap composed primitives in a <form> and pass formAction/formMethod on each DropdownItem so the menu submits to different endpoints without JavaScript.
+
+```tsx
+<form>
+ <DropdownRoot>
+ <DropdownTrigger>Task Actions</DropdownTrigger>
+ <DropdownContent>
+ <DropdownItem formAction="/api/tasks/complete" formMethod="post">
+ Mark as Complete
+ </DropdownItem>
+ <DropdownItem formAction="/api/tasks/reassign" formMethod="post">
+ Reassign
+ </DropdownItem>
+ <DropdownItem danger formAction="/api/tasks/delete" formMethod="post">
+ Delete Task
+ </DropdownItem>
+ </DropdownContent>
+ </DropdownRoot>
+</form>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the dropdown trigger, content, and item rendering.
+
+```tsx
+<DropdownRoot>
+ <DropdownTrigger asChild>
+ <Button>Open</Button>
+ </DropdownTrigger>
+ <DropdownContent>
+ <DropdownItem
+ // onSelect={handleSelect}
+ >
+ Item 1
+ </DropdownItem>
+ <DropdownItem
+ // onSelect={handleSelect}
+ >
+ Item 2
+ </DropdownItem>
+ <DropdownItem
+ danger
+ // onSelect={handleSelect}
+ >
+ Delete
+ </DropdownItem>
+ </DropdownContent>
+</DropdownRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `string \| ({ href: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: "default"; formAction: string; formMethod: "get" \| "post"; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ defaultChecked: boolean; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; kind: "checkbox"; danger: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; slotControl: ReactNode }) \| ({ items: string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: never; danger: boolean; required: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string })[]; defaultValue: string; disabled: boolean; name: string; value: string; kind: "radio"; required: boolean; error: boolean; onValueChange: (value: string) => void; slotHeading: ReactNode; radioKind: "radio" \| "check" }) \| ({ kind: "sub"; children: ReactNode; items: ({ href: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: "default"; formAction: string; formMethod: "get" \| "post"; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ defaultChecked: boolean; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; kind: "checkbox"; danger: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; slotControl: ReactNode }) \| ({ items: string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: never; danger: boolean; required: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string })[]; defaultValue: string; disabled: boolean; name: string; value: string; kind: "radio"; required: boolean; error: boolean; onValueChange: (value: string) => void; slotHeading: ReactNode; radioKind: "radio" \| "check" }) \| { kind: "divider"; width: "small" \| "medium" \| "large"; filterValue: never } \| Omit<DropdownSectionEntry, "items"> & { items: (DropdownDefaultItemEntry \| DropdownCheckboxItemEntry \| DropdownDividerItemEntry)[]; }[]; filterValue: string; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; open: boolean; defaultOpen: boolean; onOpenChange: (open: boolean) => void; density: "compact" \| "standard" \| "spacious"; sideOffset: number; alignOffset: number }) \| ({ items: ({ href: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: "default"; formAction: string; formMethod: "get" \| "post"; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ defaultChecked: boolean; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; kind: "checkbox"; danger: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; slotControl: ReactNode }) \| ({ kind: "sub"; children: ReactNode; items: ({ href: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: "default"; formAction: string; formMethod: "get" \| "post"; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ defaultChecked: boolean; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; kind: "checkbox"; danger: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; slotControl: ReactNode }) \| ({ items: string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: never; danger: boolean; required: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string })[]; defaultValue: string; disabled: boolean; name: string; value: string; kind: "radio"; required: boolean; error: boolean; onValueChange: (value: string) => void; slotHeading: ReactNode; radioKind: "radio" \| "check" }) \| { kind: "divider"; width: "small" \| "medium" \| "large"; filterValue: never } \| Omit<DropdownSectionEntry, "items"> & { items: (DropdownDefaultItemEntry \| DropdownCheckboxItemEntry \| DropdownDividerItemEntry)[]; }[]; filterValue: string; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; open: boolean; defaultOpen: boolean; onOpenChange: (open: boolean) => void; density: "compact" \| "standard" \| "spacious"; sideOffset: number; alignOffset: number }) \| { kind: "divider"; width: "small" \| "medium" \| "large"; filterValue: never }[]; children: never; kind: "section"; filterValue: never; slotHeading: ReactNode }) \| { kind: "divider"; width: "small" \| "medium" \| "large"; filterValue: never }[]` | - | The items to render in the dropdown. |
+| align | `"center" \| "start" \| "end"` | `"start"` | The alignment of the dropdown content relative to the trigger. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| defaultFilterValue | `string` | - | This sets the default value of the dropdown search input. |
+| defaultOpen | `boolean` | `false` | The open state of the dropdown when it is initially rendered. Use when you do not need to control its open state. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| disabled | `boolean` | - | When true, prevents the user from interacting with the dropdown. |
+| filterable | `boolean` | `false` | Whether the dropdown is filterable. |
+| filterMatchFn | `"disable" \| ((matchTerm: string, value: string) => boolean)` | - | The function to use to match items against the search value. |
+| filterValue | `string` | - | The controlled value of the dropdown search input. Must be used in conjunction with `onFilterChange`. |
+| id | `string` | - | A stable identifier used to derive the dropdown content id and CSS anchor name. Provide this when rendering in SSR-sensitive trees to ensure the generated ids remain consistent between server and client. |
+| modal | `boolean` | `false` | The modality of the dropdown. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers. Modality is disabled by default to minimize performance impact. |
+| onCloseAutoFocus | `(event: Event) => void` | - | Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`. |
+| onEscapeKeyDown | `(event: KeyboardEvent) => void` | - | Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. |
+| onFilterChange | `(value: string) => void` | - | Callback fired when the search value changes. |
+| onInteractOutside | `(event: Event) => void` | - | Event handler called when an interaction event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| onItemCheckedChange | `(item: { defaultChecked: boolean; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; kind: "checkbox"; danger: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; slotControl: ReactNode }, checked: false \| true \| "indeterminate") => void` | - | Callback fired when a dropdown item's checked state changes. |
+| onItemSelect | `(event: Event, item: ({ href: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: "default"; formAction: string; formMethod: "get" \| "post"; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ defaultChecked: boolean; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; kind: "checkbox"; danger: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; slotControl: ReactNode }) \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: never; danger: boolean; required: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string })) => void` | - | Callback fired when a dropdown item is selected. |
+| onOpenChange | `(open: boolean) => void` | - | Event handler called when the open state of the dropdown changes. |
+| onPointerDownOutside | `(event: Event) => void` | - | Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| open | `boolean` | - | The controlled open state of the dropdown. Must be used in conjunction with `onOpenChange`. |
+| ref | `((instance: HTMLButtonElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLButtonElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| renderLink | `(item: { href: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; kind: "default"; formAction: string; formMethod: "get" \| "post"; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) => ReactNode` | - | Render a custom link component - useful if your framework has a custom link component i.e. Next.js Link. |
+| showChevron | `boolean` | `true` | When true, shows the chevron icon showing the current state of the dropdown. |
+| side | `"right" \| "bottom" \| "left" \| "top"` | `"bottom"` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur. |
+| size | `"small" \| "tiny" \| "medium" \| "large"` | `"medium"` | The size of the dropdown and its trigger. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Flex.md b/.agents/skills/kaizen-ui/references/components/Flex.md
new file mode 100644
index 0000000..d5f975e
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Flex.md
@@ -0,0 +1,97 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Flex
+
+A primitive flex component.
+
+## Notes
+
+- Instead of using this component, just use `div` with Tailwind classes
+
+## Examples
+
+### Basic Flex
+
+Use a basic row layout when items should flow horizontally with consistent spacing.
+
+```tsx
+<Flex gap="2" padding="1" style={{ border: '1px dotted var(--border-color-base)' }}>
+ <Flex padding="1" style={{ flex: 1, border: '1px dotted var(--border-color-base)' }}>
+ Item A
+ </Flex>
+ <Flex padding="1" style={{ flex: 2, border: '1px dotted var(--border-color-base)' }}>
+ Item B
+ </Flex>
+ <Flex padding="1" style={{ flex: 1, border: '1px dotted var(--border-color-base)' }}>
+ Item C
+ </Flex>
+</Flex>
+```
+
+### Column Flex
+
+Use a column layout with centered alignment when stacking items vertically within a constrained width.
+
+```tsx
+<Flex direction="col" align="center" gap="2">
+ <div>Item A</div>
+ <div>Item B</div>
+ <div>Item C</div>
+</Flex>
+```
+
+### Wrapping Flex
+
+Use wrapping when items should flow to the next line rather than overflowing their container.
+
+```tsx
+<Flex gap="2" wrap="wrap">
+ <div>Item A</div>
+ <div>Item B</div>
+ <div>Item C</div>
+ <div>Item D</div>
+ <div>Item E</div>
+</Flex>
+```
+
+## Props
+
+type SpacingScaleUnion
+
+Prefer semantic density tokens that adapt to the active density theme (compact, standard, spacious):
+"density-xxs" | "density-xs" | "density-sm" | "density-md" | "density-lg" | "density-xl" | "density-2xl" | "density-3xl" | "density-4xl" | "density-5xl"
+
+| Token | Compact | Standard | Spacious |
+| ----------- | ------- | -------- | -------- |
+| density-xxs | 1px | 2px | 4px |
+| density-xs | 2px | 4px | 6px |
+| density-sm | 4px | 6px | 8px |
+| density-md | 6px | 8px | 12px |
+| density-lg | 8px | 12px | 16px |
+| density-xl | 12px | 16px | 24px |
+| density-2xl | 16px | 24px | 32px |
+| density-3xl | 24px | 32px | 48px |
+| density-4xl | 32px | 48px | 64px |
+| density-5xl | 48px | 64px | 80px |
+
+Raw scale values (4px base unit — use only when density tokens don't fit):
+"0" | "0.25" | "0.5" | "0.75" | "1" | "1.5" | "2" | "2.5" | "3" | "3.5" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "14" | "16" | "18" | "20" | "24" | "28" | "32" | "36" | "40" | "44" | "48" | "52" | "56" | "60" | "64" | "72" | "80" | "96" | "250" | "inherit" | "px"
+
+| Prop | Type | Default | Description |
+| ------------- | -------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| align | `"center" \| "start" \| "end" \| "baseline" \| "stretch"` | `"stretch"` | Sets the alignment of child items along the block axis. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| direction | `"col" \| "row" \| "column" \| "row-reverse" \| "col-reverse" \| "column-reverse"` | `"row"` | Sets the direction in which child items are placed in the flex container. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more. |
+| gap | `SpacingScaleUnion` | - | Sets spacing between flex and grid items. |
+| justify | `"center" \| "start" \| "end" \| "normal" \| "stretch" \| "between" \| "around" \| "evenly"` | `"start"` | Sets distribution of space between and around content items along the main axis. See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more. |
+| padding | `SpacingScaleUnion` | - | Sets padding. |
+| paddingBottom | `SpacingScaleUnion` | - | Sets bottom padding. |
+| paddingLeft | `SpacingScaleUnion` | - | Sets left padding. |
+| paddingRight | `SpacingScaleUnion` | - | Sets right padding. |
+| paddingTop | `SpacingScaleUnion` | - | Sets top padding. |
+| paddingX | `SpacingScaleUnion` | - | Sets horizontal padding. |
+| paddingY | `SpacingScaleUnion` | - | Sets vertical padding. |
+| wrap | `"wrap" \| "nowrap" \| "wrap-reverse"` | `"nowrap"` | Sets the wrapping behavior of the flex container. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more. |
diff --git a/.agents/skills/kaizen-ui/references/components/FormField.md b/.agents/skills/kaizen-ui/references/components/FormField.md
new file mode 100644
index 0000000..8edee1e
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/FormField.md
@@ -0,0 +1,195 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# FormField
+
+Also known as: Form Group, Fieldset, Form Input
+
+A component for displaying a form field with label, description, helper text, and validation messages.
+FormField automatically adapts to different container widths. For horizontal layouts (`labelPosition="left"`),
+it will switch to vertical layout on small screens.
+
+## Examples
+
+### Basic Form Field
+
+```tsx
+<FormField slotLabel="Email Address" slotHelp="We will not share your email.">
+ <TextInput
+ type="email"
+ pattern="^[^\s@]+@[^\s@]+\.[^\s@]+$"
+ placeholder="[email protected]"
+ required
+ />
+</FormField>
+```
+
+### Text Area Form Field
+
+```tsx
+<FormField slotLabel="Description" slotHelp="Your description will be used to generate a report.">
+ <TextArea placeholder="Enter your description" required />
+</FormField>
+```
+
+### Select Form Field
+
+```tsx
+<FormField
+ slotLabel="Preferred Contact Method"
+ slotHelp="Your preferred contact method for communication."
+>
+ <Select items={['Phone', 'Email', 'Telegram', 'WhatsApp']} />
+</FormField>
+```
+
+### Checkbox Form Field
+
+```tsx
+<FormField slotLabel="Accept Terms" slotHelp="I agree to the terms and conditions.">
+ <Checkbox />
+</FormField>
+```
+
+### Switch Form Field
+
+```tsx
+<FormField
+ slotLabel="Enable Notifications"
+ slotHelp="You'll receive email notifications for important updates."
+>
+ <Switch />
+</FormField>
+```
+
+### Upload Form Field
+
+```tsx
+<Upload
+ renderInput={inputNode => (
+ <FormField
+ name="documents"
+ slotLabel="Upload Documents"
+ slotHelp="Files will be deleted after 30 days."
+ >
+ {inputNode}
+ </FormField>
+ )}
+ required
+/>
+```
+
+### Error Form Field
+
+Use when the field fails validation and the user needs guidance to correct it.
+
+```tsx
+<FormField slotLabel="Email Address" slotError="Please enter a valid email address." status="error">
+ <TextInput placeholder="[email protected]" />
+</FormField>
+```
+
+### Success Form Field
+
+Use to confirm the field value has been validated successfully.
+
+```tsx
+<FormField slotLabel="Email Address" slotSuccess="Looks good!" status="success">
+ <TextInput placeholder="[email protected]" />
+</FormField>
+```
+
+### Required Form Field
+
+When set, renders an asterisk next to the label. If the wrapped input has `:required`, the form field will automatically render the required indicator.
+
+```tsx
+<Flex>
+ <FormField slotLabel="Email Address">
+ <TextInput
+ type="email"
+ // :required is true so FormField will render the required indicator
+ // (preferred over setting required on FormField)
+ required
+ placeholder="[email protected]"
+ />
+ </FormField>
+ <FormField
+ slotLabel="Full Name"
+ // sets required on KUI form controls rendered within
+ required
+ >
+ <TextInput placeholder="Jane Doe" />
+ </FormField>
+</Flex>
+```
+
+### With Info Form Field
+
+Use when the field label alone is insufficient and users benefit from an info popover.
+
+```tsx
+<FormField
+ slotLabel="API Key"
+ slotInfo="Your API key is used to authenticate requests."
+ slotHelp="Found in your account settings."
+>
+ <TextInput placeholder="sk-..." />
+</FormField>
+```
+
+### Left Label Form Field
+
+Top-aligned labels(default) enhance clarity, provide space for longer labels, and improve scannability on various screen sizes. Left-aligned labels should be used for dense forms to save space or for multi-column layouts. Note that left aligned labels will automatically switch to vertical layout if there is insufficient space.
+
+```tsx
+<FormField labelPosition="left" slotLabel="Username" slotHelp="Choose a unique username.">
+ <TextInput placeholder="jdoe" />
+</FormField>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the form field layout and context.
+
+```tsx
+<FormFieldRoot
+ context={{
+ id: 'demo-field',
+ status: 'error',
+ name: 'demo-field',
+ required: true,
+ 'aria-labelledby': 'demo-field-label',
+ 'aria-describedby': 'demo-field-helper'
+ }}
+>
+ <FormFieldContentGroup>
+ <FormFieldLabelGroup>
+ <label htmlFor="demo-field" id="demo-field-label">
+ Label
+ </label>
+ </FormFieldLabelGroup>
+ <TextInput placeholder="Composed field" />
+ </FormFieldContentGroup>
+ <FormFieldHelper id="demo-field-helper">Helper text for the field.</FormFieldHelper>
+</FormFieldRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| children | `string \| number \| bigint \| false \| true \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| Iterable<React.ReactNode> \| React.ReactPortal \| Promise<AwaitedReactNode> \| ((args: { id: string; name: string; status: "error" \| "success"; aria-describedby: string; aria-labelledby: string; aria-details: string; required: boolean }) => React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>)` | - | The children of the form field. Can be a render function that receives form field context. |
+| id | `string` | - | The ID of the form field (for connecting label and input). The value of this attribute must be unique. If not provided, a unique ID will be generated for you. |
+| labelPosition | `"left" \| "top"` | `"top"` | The position for the form field label and (optional) info icon. |
+| name | `string` | - | Name of the element. Used to identify fields in form submits. |
+| required | `boolean` | - | When true, indicates that the user is required to fill out this field. Used to determine whether or not the asterisk is shown next to the label. By default, this will automatically determine if the form field contains a `:required` input, otherwise it will be manually controlled. |
+| slotError | `ReactNode` | - | The content to render as the error message. Visible when status is `"error"`. |
+| slotHelp | `ReactNode` | - | The content to render as the help message (visible when status is not `"error"` or `"success"`). |
+| slotInfo | `ReactNode` | - | The content to render inside of the info icon popover. |
+| slotLabel | `ReactNode` | - | The content to render as the label. This is required for accessibility. It's recommended |
+| slotSuccess | `ReactNode` | - | The content to render as the success message. Visible when status is `"success"`. |
+| status | `"error" \| "success"` | - | The status of the form field. Determines the visual state of the field. |
diff --git a/.agents/skills/kaizen-ui/references/components/Grid.md b/.agents/skills/kaizen-ui/references/components/Grid.md
new file mode 100644
index 0000000..69753e8
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Grid.md
@@ -0,0 +1,142 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Grid
+
+A primitive grid component.
+
+## Examples
+
+### Basic Grid
+
+Use auto-flowing columns for responsive layouts where items should wrap based on available space.
+
+```tsx
+<Grid colMinWidth="250px" gap="4">
+ <div>Item 1</div>
+ <div>Item 2</div>
+ <div>Item 3</div>
+</Grid>
+```
+
+### Fixed Columns Grid
+
+Use a fixed column count when the layout should not reflow regardless of viewport width.
+
+```tsx
+<Grid cols={3} gap="4">
+ <div>Column A</div>
+ <div>Column B</div>
+ <div>Column C</div>
+</Grid>
+```
+
+### Responsive Columns Grid
+
+Use responsive breakpoint columns when you need explicit control over column counts at each viewport size. Autoflowing columns is usually preferred over this.
+
+```tsx
+<Grid cols={{ sm: 1, md: 2, lg: 3 }} gap="4">
+ <div>Column A</div>
+ <div>Column B</div>
+ <div>Column C</div>
+</Grid>
+```
+
+### Static Columns Grid
+
+Pair `colMinWidth` with `colBehavior="static"` for uniform card grids where stretching the last row would look awkward.
+
+```tsx
+<Grid colMinWidth="200px" colBehavior="static" gap="4">
+ <div>Card 1</div>
+ <div>Card 2</div>
+ <div>Card 3</div>
+</Grid>
+```
+
+### Column Flow Grid
+
+Combine `rows` with `flow="col"` for column-major layouts where items fill top-to-bottom before wrapping to the next column.
+
+```tsx
+<Grid rows={3} flow="col" gap="2">
+ <div>1</div>
+ <div>2</div>
+ <div>3</div>
+ <div>4</div>
+ <div>5</div>
+ <div>6</div>
+</Grid>
+```
+
+### Dense Flow Grid
+
+Use `flow="dense"` with mixed `GridItem` spans to backfill gaps left by larger items, producing a tightly packed masonry-style layout.
+
+```tsx
+<Grid cols={4} flow="dense" gap="2">
+ <GridItem cols={2}>Wide A</GridItem>
+ <GridItem>B</GridItem>
+ <GridItem rows={2}>Tall C</GridItem>
+ <GridItem cols={3}>Wide D</GridItem>
+ <GridItem>E</GridItem>
+ <GridItem>F</GridItem>
+</Grid>
+```
+
+### Composed
+
+Use GridItem when individual cells need to span multiple columns or be placed at specific grid positions.
+
+```tsx
+<Grid cols={3} gap="4">
+ <GridItem cols={2}>Spanning two columns</GridItem>
+ <GridItem>Single column</GridItem>
+ <GridItem colStart={2} colEnd={4}>
+ Columns 2–3
+ </GridItem>
+</Grid>
+```
+
+## Props
+
+type SpacingScaleUnion
+
+Prefer semantic density tokens that adapt to the active density theme (compact, standard, spacious):
+"density-xxs" | "density-xs" | "density-sm" | "density-md" | "density-lg" | "density-xl" | "density-2xl" | "density-3xl" | "density-4xl" | "density-5xl"
+
+| Token | Compact | Standard | Spacious |
+| ----------- | ------- | -------- | -------- |
+| density-xxs | 1px | 2px | 4px |
+| density-xs | 2px | 4px | 6px |
+| density-sm | 4px | 6px | 8px |
+| density-md | 6px | 8px | 12px |
+| density-lg | 8px | 12px | 16px |
+| density-xl | 12px | 16px | 24px |
+| density-2xl | 16px | 24px | 32px |
+| density-3xl | 24px | 32px | 48px |
+| density-4xl | 32px | 48px | 64px |
+| density-5xl | 48px | 64px | 80px |
+
+Raw scale values (4px base unit — use only when density tokens don't fit):
+"0" | "0.25" | "0.5" | "0.75" | "1" | "1.5" | "2" | "2.5" | "3" | "3.5" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "14" | "16" | "18" | "20" | "24" | "28" | "32" | "36" | "40" | "44" | "48" | "52" | "56" | "60" | "64" | "72" | "80" | "96" | "250" | "inherit" | "px"
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| colBehavior | `"grow" \| "static"` | `"grow"` | Determines column behavior when using `colMinWidth`. - `"grow"` (default): Columns expand to fill available space when there aren't enough items to fill a row - `"static"`: Columns maintain their minimum width, leaving empty space if needed Has no effect without `colMinWidth`. |
+| colMinWidth | `string \| number` | - | Minimum width for auto-flowing columns. When set, creates responsive columns that automatically wrap based on available space. Overrides the `cols` prop when provided. Accepts CSS units (e.g., "250px", "15rem") or numbers (converted to px). |
+| cols | `number \| { base?: number; xs?: number; sm?: number; md?: number; lg?: number; xl?: number; xxl?: number; }` | - | Number of grid columns when working with row flow directions. This prop is ignored when `colMinWidth` is set. |
+| flow | `string` | - | Grid auto-flow. See https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow for more details. |
+| gap | `SpacingScaleUnion` | - | Sets spacing between flex and grid items. |
+| padding | `SpacingScaleUnion` | - | Sets padding. |
+| paddingBottom | `SpacingScaleUnion` | - | Sets bottom padding. |
+| paddingLeft | `SpacingScaleUnion` | - | Sets left padding. |
+| paddingRight | `SpacingScaleUnion` | - | Sets right padding. |
+| paddingTop | `SpacingScaleUnion` | - | Sets top padding. |
+| paddingX | `SpacingScaleUnion` | - | Sets horizontal padding. |
+| paddingY | `SpacingScaleUnion` | - | Sets vertical padding. |
+| rows | `number \| { base?: number; xs?: number; sm?: number; md?: number; lg?: number; xl?: number; xxl?: number; }` | - | Number of grid rows when working with column flow directions. |
diff --git a/.agents/skills/kaizen-ui/references/components/Group.md b/.agents/skills/kaizen-ui/references/components/Group.md
new file mode 100644
index 0000000..bb812d0
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Group.md
@@ -0,0 +1,101 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Group
+
+Group is a utility component that joins items together visually.
+
+## Examples
+
+### Basic Group
+
+Use a flush group to visually join sibling items without any spacing or dividers between them.
+
+```tsx
+<Group>
+ <Badge>Item A</Badge>
+ <Badge>Item B</Badge>
+ <Badge>Item C</Badge>
+</Group>
+```
+
+### Gap Group
+
+Use a gap group when joined items need visible spacing between them while remaining a logical unit.
+
+```tsx
+<Group kind="gap">
+ <Badge>Item A</Badge>
+ <Badge>Item B</Badge>
+ <Badge>Item C</Badge>
+</Group>
+```
+
+### Border Group
+
+Use a border group when items lack their own borders and need a visible separator to distinguish each entry.
+
+```tsx
+<Group kind="border">
+ <Badge>Item A</Badge>
+ <Badge>Item B</Badge>
+ <Badge>Item C</Badge>
+</Group>
+```
+
+### With Badges Group
+
+Use flush with components that already have borders (Badges, Tags, Buttons) to conjoin them into a single visual unit with a 1px overlap.
+
+```tsx
+<Group kind="flush">
+ <Badge kind="outline">Item 1</Badge>
+ <Badge kind="outline">Item 2</Badge>
+ <Badge kind="outline">Item 3</Badge>
+</Group>
+```
+
+### With Tags Group
+
+Use Group to lay out a removable filter chip as a label tag joined to a dismiss tag so each has its own click target while reading as one unit.
+
+```tsx
+<Group kind="flush">
+ <Tag onClick={handleTagClick}>Filter Name</Tag>
+ <Tag aria-label="Remove filter" onClick={handleTagRemove}>
+ <Close />
+ </Tag>
+</Group>
+```
+
+### With Input And Button Group
+
+Use to attach an action trigger (dropdown, generate, refresh) directly to a TextInput so the pair reads as one input control.
+
+```tsx
+<Group kind="flush">
+ <TextInput placeholder="Enter value" />
+ <Button aria-label="Open options" kind="secondary">
+ <ChevronDown />
+ </Button>
+</Group>
+```
+
+### Single Child Group
+
+Border radius is preserved with a single child, so groups can wrap collections of unknown length (e.g. server-fetched lists) without special-casing the empty / one-item case.
+
+```tsx
+<Group kind="flush">
+ <Badge kind="outline">Single Item</Badge>
+</Group>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------- | ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| kind | `"gap" \| "flush" \| "border"` | `"flush"` | The kind of divider to render for the group. By default groups are rendered as "flush" groups with no divider. Use `gap` to render a group with a gap between items. Use `border` to render a group with a border between items. Use this when the group items don't have a border or clear ending. |
diff --git a/.agents/skills/kaizen-ui/references/components/Hero.md b/.agents/skills/kaizen-ui/references/components/Hero.md
new file mode 100644
index 0000000..0d45db0
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Hero.md
@@ -0,0 +1,153 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Hero
+
+A Hero is a large page banner that combines important messaging and calls to action with large imagery.
+
+Has responsive padding based on the component width.
+
+## Notes
+
+- By default content is left aligned which is preferred for most use cases. To center or right
+ align content, you can use `text-center` or `text-right` on the Hero component.
+
+## Examples
+
+### Basic Hero
+
+Use for prominent page banners that communicate key messaging without media.
+
+```tsx
+<Hero
+ slotHeading="Welcome to the Platform"
+ slotBody="Get started by exploring available models, tools, and resources."
+/>
+```
+
+### With Subheading Hero
+
+Use when a secondary label above the heading provides additional context like a category or publisher name.
+
+```tsx
+<Hero
+ slotSubheading="Getting Started"
+ slotHeading="Build with NVIDIA"
+ slotBody="Access pre-trained models, SDKs, and APIs to accelerate your AI projects."
+/>
+```
+
+### With Actions Hero
+
+Use when the hero needs prominent call-to-action buttons below the body text.
+
+```tsx
+<Hero
+ slotSubheading="New Release"
+ slotHeading="Model Hub"
+ slotBody="Discover, customize, and deploy foundation models."
+ slotActions={
+ <>
+ <Button kind="secondary">Learn More</Button>
+ <Button color="brand">Get Started</Button>
+ </>
+ }
+/>
+```
+
+### With Media Hero
+
+Pass `slotMedia` for a hero with a background image, then set `mediaTheme` to `dark` (default) or `light` so the heading and body text contrast against it.
+
+```tsx
+<Hero
+ mediaTheme="dark"
+ slotHeading="Deep Learning Institute"
+ slotBody="Hands-on training for developers, data scientists, and researchers."
+ slotMedia={<Media />}
+/>
+```
+
+### Custom Heading Hero
+
+Use when the heading needs richer content than a string. slotHeading accepts any ReactNode, so you can compose layout primitives, badges, or icons inline.
+
+```tsx
+<Hero
+ slotSubheading="Kaizen Design System"
+ slotHeading={
+ <Flex direction="col" gap="density-md">
+ <span>Kaizen UI Foundations</span>
+ <Flex gap="density-md" wrap="wrap">
+ <Badge kind="solid">Accessible</Badge>
+ <Badge kind="solid">Responsive</Badge>
+ <Badge kind="solid">CSS Only</Badge>
+ </Flex>
+ </Flex>
+ }
+ slotBody="A CSS-only implementation of the NVIDIA Design Language."
+/>
+```
+
+### Aligned Hero
+
+Use the text-center or text-right utility class on the Hero when the design calls for non-default alignment. Left alignment is preferred for most cases.
+
+```tsx
+<Hero
+ className="text-center"
+ slotSubheading="Getting Started"
+ slotHeading="Centered Hero"
+ slotBody="Hero content is left-aligned by default. Apply the text-center or text-right utility class to the Hero to override the alignment."
+ slotActions={
+ <>
+ <Button kind="secondary">Learn More</Button>
+ <Button color="brand">Get Started</Button>
+ </>
+ }
+/>
+```
+
+### Custom Styling Hero
+
+Use the Hero CSS variables (--padding, --max-width, --text-color) to customize spacing, width, or text color while keeping the rest of the component's styling.
+
+```tsx
+<Hero
+ style={{ '--padding': '0', '--max-width': '100%' }}
+ slotHeading="Edge-to-Edge Hero"
+ slotBody="Override the --padding, --max-width, and --text-color CSS variables to fine-tune hero spacing and width without forking the component."
+ slotActions={<Button color="brand">Get Started</Button>}
+/>
+```
+
+### Composed
+
+```tsx
+<HeroRoot>
+ <HeroContent>
+ <HeroSubheading>Subheading</HeroSubheading>
+ <HeroHeading>Hero Heading</HeroHeading>
+ <HeroBody>Hero body content with a description of the page or feature.</HeroBody>
+ <HeroFooter>
+ <Button color="brand">Primary Action</Button>
+ </HeroFooter>
+ </HeroContent>
+</HeroRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------------ | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **slotBody** \* | `ReactNode` | - | The slot for the body content of the component. Renders below the heading and above the action slots. Has text styling that is consistent across all widths. |
+| **slotHeading** \* | `ReactNode` | - | The slot for the heading of the component. The largest and main text of the hero. Renders below the subheading, and above the body and action slots. Has responsive text styles based on the component width. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| mediaTheme | `"light" \| "dark"` | - | Indicates whether the Hero media is visually light or dark. Applies the appropriate NV theme class ("nv-light" or "nv-dark") to optimize text contrast and readability. For example, if the media is a black image you should set `mediaTheme="dark"`. If the media is a white image you should set `mediaTheme="light"`. |
+| slotActions | `ReactNode` | - | The slot for the action area of the hero component. Renders below the body at the bottom of the hero. |
+| slotMedia | `ReactNode` | - | Slot for media content to render as the background of the hero. If `slotMedia` is set you should also set `mediaTheme` to ensure text and components are readable. |
+| slotSubheading | `ReactNode` | - | The slot for the optional subheading of the component. Renders above the heading in smaller text. Has responsive text styles based on the component width. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/HorizontalNav.md b/.agents/skills/kaizen-ui/references/components/HorizontalNav.md
new file mode 100644
index 0000000..a3c70c7
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/HorizontalNav.md
@@ -0,0 +1,145 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# HorizontalNav
+
+The HorizontalNav component is a customizable navigation bar designed to display a list of links in a horizontal layout.
+It allows users to navigate between different sections of an application or website.
+
+## Notes
+
+- Never render nav items as disabled or aria-disabled for role-gated destinations. Remove inaccessible items from the items array entirely.
+
+## Examples
+
+### Basic Horizontal Nav
+
+Use for top-level site navigation where users move between major sections.
+
+```tsx
+<HorizontalNav
+ defaultValue="home"
+ items={[
+ { value: 'home', href: '/', children: 'Home' },
+ { value: 'about', href: '/about', children: 'About' },
+ { value: 'contact', href: '/contact', children: 'Contact' }
+ ]}
+/>
+```
+
+### With Icons Horizontal Nav
+
+Use when icons help users quickly identify navigation destinations.
+
+```tsx
+<HorizontalNav
+ defaultValue="home"
+ items={[
+ {
+ value: 'home',
+ href: '/',
+ children: (
+ <>
+ <Icon /> Home
+ </>
+ )
+ },
+ {
+ value: 'about',
+ href: '/about',
+ children: (
+ <>
+ <Icon /> About
+ </>
+ )
+ }
+ ]}
+/>
+```
+
+### With Button Item Horizontal Nav
+
+Use `asChild: true` on an item to render a non-anchor element (e.g. a button that opens a modal) while keeping it in the tab order.
+
+```tsx
+<HorizontalNav
+ defaultValue="home"
+ items={[
+ { value: 'home', href: '/', children: 'Home' },
+ { value: 'about', href: '/about', children: 'About' },
+ {
+ value: 'settings',
+ asChild: true,
+ children: <button type="button">Settings</button>
+ }
+ ]}
+/>
+```
+
+### With Custom Link Horizontal Nav
+
+Use `renderLink` to swap the underlying anchor for a framework router component (Next.js `Link`, React Router `Link`, etc.) so navigation stays client-side.
+
+```tsx
+<HorizontalNav
+ defaultValue="home"
+ items={[
+ { value: 'home', href: '/', children: 'Home' },
+ { value: 'about', href: '/about', children: 'About' }
+ ]}
+ renderLink={item => <Link {...item} />}
+/>
+```
+
+### With Disabled Item Horizontal Nav
+
+Use when a nav destination exists but is temporarily unavailable.
+
+```tsx
+<HorizontalNav
+ defaultValue="home"
+ items={[
+ { value: 'home', href: '/', children: 'Home' },
+ {
+ value: 'settings',
+ href: '/settings',
+ children: 'Settings',
+ disabled: true
+ },
+ { value: 'about', href: '/about', children: 'About' }
+ ]}
+/>
+```
+
+### Composed
+
+```tsx
+<HorizontalNavRoot defaultValue="home">
+ <HorizontalNavList>
+ <HorizontalNavLink value="home" href="/">
+ Home
+ </HorizontalNavLink>
+ <HorizontalNavLink value="about" href="/about">
+ About
+ </HorizontalNavLink>
+ <HorizontalNavLink value="contact" href="/contact">
+ Contact
+ </HorizontalNavLink>
+ </HorizontalNavList>
+</HorizontalNavRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **items** \* | `{ asChild: boolean; children: ReactNode; disabled: boolean; href: string; target: string; rel: string; value: string }[]` | - | Array of navigation items to render in the horizontal nav |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| defaultValue | `string` | - | The value of the horizontal nav when initially rendered. Use when you do not need to control the state of the horizontal nav. |
+| onValueChange | `(value: string) => void` | - | Callback fired when the value of the horizontal nav changes. |
+| renderLink | `(item: { asChild: boolean; children: ReactNode; disabled: boolean; href: string; target: string; rel: string; value: string }) => ReactNode` | - | Custom renderer for individual navigation links. Useful for rendering a framework specific link component. |
+| value | `string` | - | The controlled value of the horizontal nav. Must be used in conjunction with `onValueChange`. Use this when you need to control the value of the horizontal nav with external state. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Inline.md b/.agents/skills/kaizen-ui/references/components/Inline.md
new file mode 100644
index 0000000..06a08f7
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Inline.md
@@ -0,0 +1,56 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Inline
+
+A primitive span component.
+
+## Notes
+
+- Instead of using this component, just use `span` with Tailwind classes
+
+## Examples
+
+### Basic Inline
+
+```tsx
+<Inline padding="2" style={{ border: '1px dotted var(--border-color-base)' }}>
+ Inline text
+</Inline>
+```
+
+## Props
+
+type SpacingScaleUnion
+
+Prefer semantic density tokens that adapt to the active density theme (compact, standard, spacious):
+"density-xxs" | "density-xs" | "density-sm" | "density-md" | "density-lg" | "density-xl" | "density-2xl" | "density-3xl" | "density-4xl" | "density-5xl"
+
+| Token | Compact | Standard | Spacious |
+| ----------- | ------- | -------- | -------- |
+| density-xxs | 1px | 2px | 4px |
+| density-xs | 2px | 4px | 6px |
+| density-sm | 4px | 6px | 8px |
+| density-md | 6px | 8px | 12px |
+| density-lg | 8px | 12px | 16px |
+| density-xl | 12px | 16px | 24px |
+| density-2xl | 16px | 24px | 32px |
+| density-3xl | 24px | 32px | 48px |
+| density-4xl | 32px | 48px | 64px |
+| density-5xl | 48px | 64px | 80px |
+
+Raw scale values (4px base unit — use only when density tokens don't fit):
+"0" | "0.25" | "0.5" | "0.75" | "1" | "1.5" | "2" | "2.5" | "3" | "3.5" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "14" | "16" | "18" | "20" | "24" | "28" | "32" | "36" | "40" | "44" | "48" | "52" | "56" | "60" | "64" | "72" | "80" | "96" | "250" | "inherit" | "px"
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| padding | `SpacingScaleUnion` | - | Sets padding. |
+| paddingBottom | `SpacingScaleUnion` | - | Sets bottom padding. |
+| paddingLeft | `SpacingScaleUnion` | - | Sets left padding. |
+| paddingRight | `SpacingScaleUnion` | - | Sets right padding. |
+| paddingTop | `SpacingScaleUnion` | - | Sets top padding. |
+| paddingX | `SpacingScaleUnion` | - | Sets horizontal padding. |
+| paddingY | `SpacingScaleUnion` | - | Sets vertical padding. |
diff --git a/.agents/skills/kaizen-ui/references/components/InputShell.md b/.agents/skills/kaizen-ui/references/components/InputShell.md
new file mode 100644
index 0000000..21480ec
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/InputShell.md
@@ -0,0 +1,193 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# InputShell
+
+Internal utility component. Use this to wrap any element that needs to be styled as an input.
+
+## Examples
+
+### Basic Input Shell
+
+```tsx
+<InputShell>
+ <input type="text" placeholder="Enter text" />
+</InputShell>
+```
+
+### With Icons Input Shell
+
+Slot icons or other content directly before/after the input — children are laid out in a row by default.
+
+```tsx
+<InputShell>
+ <Bell />
+ <input type="text" placeholder="Search..." />
+ <Close />
+</InputShell>
+```
+
+### Textarea Input Shell
+
+Wrap a native textarea to get the same shell styling and focus redirect as text inputs.
+
+```tsx
+<InputShell>
+ <textarea placeholder="Enter a longer message" />
+</InputShell>
+```
+
+### Select Input Shell
+
+Wrap a native select. Use a disabled hidden empty option with `required` to show placeholder text.
+
+```tsx
+<InputShell>
+ <select required defaultValue="" name="example-select">
+ <option value="" disabled hidden>
+ Select an option
+ </option>
+ <option value="1">Option 1</option>
+ <option value="2">Option 2</option>
+ <option value="3">Option 3</option>
+ </select>
+</InputShell>
+```
+
+### Button As Input Shell
+
+Add `data-input-slot` to a button to style triggers (popovers, modals, custom pickers) like a form field. Use `data-has-selected-value="false"` to apply placeholder styling.
+
+```tsx
+<InputShell>
+ <button data-input-slot data-has-selected-value="false" type="button">
+ Select a value...
+ </button>
+</InputShell>
+```
+
+### Floating Input Shell
+
+Use the floating kind for borderless, transparent inputs in toolbars, inline editing, or embedded contexts.
+
+```tsx
+<InputShell kind="floating">
+ <input type="text" placeholder="Floating input" />
+</InputShell>
+```
+
+### Sizes Input Shell
+
+Match the shell to its surroundings: `small` for table cells or dense forms, `medium` (default) for typical form fields, and `large` for hero search bars.
+
+```tsx
+<div className="flex flex-col gap-2">
+ <InputShell size="small">
+ <input type="text" placeholder="Small" />
+ </InputShell>
+ <InputShell size="medium">
+ <input type="text" placeholder="Medium" />
+ </InputShell>
+ <InputShell size="large">
+ <input type="text" placeholder="Large" />
+ </InputShell>
+</div>
+```
+
+### Vertical Layout Input Shell
+
+Use vertical layout when slotted content needs to stack above or below the input rather than sit beside it.
+
+```tsx
+<InputShell layout="vertical">
+ <span>Label above</span>
+ <input type="text" placeholder="Vertical layout" />
+</InputShell>
+```
+
+### Status Input Shell
+
+Set `data-status="success"` or `data-status="error"` on the inner input for explicit validation feedback. Use `withValidation` instead when you want native `:user-valid` / `:user-invalid` to drive the styling.
+
+```tsx
+<InputShell>
+ <input data-status="error" defaultValue="invalid-value" />
+</InputShell>
+```
+
+### With Validation Input Shell
+
+Use when native HTML constraints (`required`, `pattern`, etc.) should drive success/error styling automatically via `:user-valid` and `:user-invalid`.
+
+```tsx
+<InputShell withValidation>
+ <input type="email" placeholder="[email protected]" required />
+</InputShell>
+```
+
+### Disabled Input Shell
+
+The shell picks up disabled styling automatically when the inner element has the `disabled` attribute. Use `data-disabled="true"` on the shell itself for purely visual disabled state.
+
+```tsx
+<InputShell>
+ <input disabled defaultValue="Disabled input" />
+</InputShell>
+```
+
+### Read Only Input Shell
+
+For read-only data display. Only `input` and `textarea` support `readOnly` — for select-based fields, render an `input` with the resolved value instead.
+
+```tsx
+<InputShell>
+ <input readOnly defaultValue="Read-only value" />
+</InputShell>
+```
+
+### Disable Focus Redirect Input Shell
+
+Disable the click-to-focus behavior when the shell contains its own interactive elements (buttons, links) that should receive their own clicks.
+
+```tsx
+<InputShell disableFocusRedirect>
+ <input type="text" placeholder="Click shell — focus stays put" />
+</InputShell>
+```
+
+### As Child Input Shell
+
+Render the shell as a custom element (typically a `label` wrapping a file input). Pair with `disableFocusRedirect` so the label — not the shell — handles activating the input.
+
+```tsx
+<InputShell asChild disableFocusRedirect>
+ <label>
+ <input type="file" />
+ </label>
+</InputShell>
+```
+
+### Composed
+
+Compose `InputDismissButton` (and other slot content like icons) inside `InputShell` for clearable inputs. The dismiss button auto-hides when the input is empty; wire up `onClick` to clear the value yourself.
+
+```tsx
+<InputShell>
+ <Bell />
+ <input type="text" defaultValue="users matching 'admin'" />
+ <InputDismissButton />
+</InputShell>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| disableFocusRedirect | `boolean` | `false` | When true, the input will not redirect focus to the input when clicked. |
+| kind | `"flat" \| "floating"` | `"flat"` | The kind of input to render. - "flat" - renders with a border and background - "floating" - renders borderless with no background |
+| layout | `"horizontal" \| "vertical"` | `"horizontal"` | The layout direction for slotted content. - "horizontal" - children are laid out in a row (default) - "vertical" - children are laid out in a column with auto height and block padding |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the input to render. Available sizes are "small", "medium", and "large". |
+| withValidation | `boolean` | - | When true, the input will automatically display success/error state based on `:user-valid` and `:user-invalid` styles |
diff --git a/.agents/skills/kaizen-ui/references/components/Label.md b/.agents/skills/kaizen-ui/references/components/Label.md
new file mode 100644
index 0000000..e184c70
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Label.md
@@ -0,0 +1,61 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Label
+
+A label component for forms and inputs. If you're using this component for a form field, just
+use the FormField component instead. This component is mostly intended for internal use.
+
+## Examples
+
+### Basic Label
+
+Use when labeling a form input to provide accessible context for the control.
+
+```tsx
+<Label htmlFor="email">Email Address</Label>
+```
+
+### Disabled Label
+
+Use when the associated input is disabled to visually communicate the inactive state.
+
+```tsx
+<Label htmlFor="email" disabled>
+ Email Address
+</Label>
+```
+
+### Small Label
+
+Use in compact layouts or alongside small-sized inputs where space is limited.
+
+```tsx
+<Label htmlFor="email" size="small">
+ Email Address
+</Label>
+```
+
+### Label With Icon
+
+Use when the label needs an inline help affordance. Label accepts arbitrary children so an icon or tooltip can sit alongside the text.
+
+```tsx
+<Label htmlFor="email">
+ Email Address
+ <Tooltip slotContent="We use this to send account confirmations.">
+ <InfoCircle />
+ </Tooltip>
+</Label>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------- | -------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| disabled | `boolean` | - | Sets the label into a disabled state. Adjusting styles and removing click events. |
+| htmlFor | `string` | - | The id of the element the label is associated with. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the label. |
diff --git a/.agents/skills/kaizen-ui/references/components/List.md b/.agents/skills/kaizen-ui/references/components/List.md
new file mode 100644
index 0000000..6e876e1
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/List.md
@@ -0,0 +1,69 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# List
+
+A flexible list component that supports unordered, ordered, and icon lists.
+
+## Examples
+
+### Basic List
+
+```tsx
+<List items={['Design tokens', 'Components', 'Patterns']} />
+```
+
+### Ordered List
+
+Use when items follow a specific sequence such as instructions or steps.
+
+```tsx
+<List kind="ordered" items={['Install the package', 'Import the component', 'Render it']} />
+```
+
+### With Custom Marker List
+
+Override per-item markers with a JSX node (icon) or a string. Items left as plain strings keep the default marker for the list kind.
+
+```tsx
+<List
+ items={[
+ 'Design tokens',
+ {
+ children: 'Components',
+ slotMarker: <ChevronRight />
+ },
+ { children: 'Patterns', slotMarker: '•' }
+ ]}
+/>
+```
+
+### Composed
+
+```tsx
+<ListRoot kind="unordered">
+ <ListItem>
+ <ListItemMarker />
+ Design tokens
+ </ListItem>
+ <ListItem>
+ <ListItemMarker />
+ Components
+ </ListItem>
+ <ListItem>
+ <ListItemMarker />
+ Patterns
+ </ListItem>
+</ListRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------ | ------------------------------------------------------------ | ------------- | ---------------------------------------------------------------- |
+| **items** \* | `string \| { children: ReactNode; slotMarker: ReactNode }[]` | - | Array of list item objects with flexible content and attributes. |
+| kind | `"ordered" \| "unordered"` | `"unordered"` | The type of list to display. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Menu.md b/.agents/skills/kaizen-ui/references/components/Menu.md
new file mode 100644
index 0000000..b67b30f
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Menu.md
@@ -0,0 +1,288 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Menu
+
+A static menu component that displays a list of items.
+
+Note: if you're looking for a menu that can be used as a dropdown, see the `Dropdown` component.
+This is the menu component itself and does not have behaviour to hide/show itself.
+
+## Examples
+
+### Basic Menu
+
+Use when you need a static, always-visible list of selectable actions or navigation items.
+
+```tsx
+<Menu
+ items={[
+ {
+ children: 'Dashboard'
+ // onSelect: handleSelect
+ },
+ {
+ children: 'Settings'
+ // onSelect: handleSelect
+ },
+ {
+ children: 'Help'
+ // onSelect: handleSelect
+ }
+ ]}
+/>
+```
+
+### With Icons Menu
+
+Use when menu items benefit from leading icons to improve scannability and recognition.
+
+```tsx
+<Menu
+ items={[
+ { children: 'Profile', slotStart: <Icon />, onSelect: handleSelect },
+ {
+ children: 'Notifications',
+ slotStart: <Icon />,
+ onSelect: handleSelect
+ },
+ {
+ children: 'Logout',
+ slotStart: <Icon />,
+ danger: true,
+ onSelect: handleSelect
+ }
+ ]}
+/>
+```
+
+### With Sections Menu
+
+Use when items belong to distinct categories that benefit from labeled group headings.
+
+```tsx
+<Menu
+ items={[
+ {
+ slotHeading: 'File',
+ items: [
+ { children: 'New', onSelect: handleSelect },
+ { children: 'Open', onSelect: handleSelect },
+ { children: 'Save', disabled: true, onSelect: handleSelect }
+ ]
+ },
+ {
+ slotHeading: 'Edit',
+ items: [
+ { children: 'Undo', onSelect: handleSelect },
+ { children: 'Redo', onSelect: handleSelect },
+ { children: 'Delete', danger: true, onSelect: handleSelect }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Dividers Menu
+
+Use divider entries to visually separate unrelated groups of items without adding a section heading.
+
+```tsx
+<Menu
+ items={[
+ { children: 'Edit Profile', onSelect: handleSelect },
+ { children: 'View Settings', onSelect: handleSelect },
+ { kind: 'divider' },
+ { children: 'Help & Support', onSelect: handleSelect },
+ { kind: 'divider' },
+ { children: 'Sign Out', danger: true, onSelect: handleSelect }
+ ]}
+/>
+```
+
+### Checkbox Menu
+
+Use when the menu allows toggling multiple independent boolean options.
+
+```tsx
+<Menu
+ items={[
+ {
+ children: 'Auto-save',
+ kind: 'checkbox',
+ defaultChecked: true
+ },
+ {
+ children: 'Spell Check',
+ kind: 'checkbox'
+ },
+ {
+ children: 'Word Wrap',
+ kind: 'checkbox'
+ }
+ ]}
+/>
+```
+
+### Radio Menu
+
+Use when the user must select exactly one option from a mutually exclusive group within the menu.
+
+```tsx
+<Menu
+ items={[
+ {
+ kind: 'radio',
+ name: 'sort',
+ slotHeading: 'Sort By',
+ defaultValue: 'name',
+ items: [
+ { children: 'Name', value: 'name' },
+ { children: 'Date', value: 'date' },
+ { children: 'Size', value: 'size' }
+ ]
+ }
+ ]}
+/>
+```
+
+### Filterable Menu
+
+Use when the menu has many items and the user benefits from filtering by typing.
+
+```tsx
+<Menu
+ filterable
+ items={[
+ { children: 'Apple', onSelect: handleSelect },
+ { children: 'Banana', onSelect: handleSelect },
+ { children: 'Cherry', onSelect: handleSelect },
+ { children: 'Date', onSelect: handleSelect },
+ { children: 'Elderberry', onSelect: handleSelect }
+ ]}
+/>
+```
+
+### With Empty State Menu
+
+Use `data-empty-message` to customize the message shown when a filterable menu has no matching items.
+
+```tsx
+<Menu
+ filterable
+ defaultFilterValue="no matches"
+ data-empty-message="No items match your search"
+ items={['Edit Profile', 'View Settings', 'Sign Out']}
+/>
+```
+
+### Mixed Items Menu
+
+Use when a single menu needs to combine actions, toggleable settings, and a mutually exclusive selection — group items of the same kind together.
+
+```tsx
+<Menu
+ items={[
+ {
+ slotHeading: 'Actions',
+ items: [
+ { children: 'Edit Profile', onSelect: handleSelect },
+ { children: 'View Settings', onSelect: handleSelect }
+ ]
+ },
+ {
+ slotHeading: 'Preferences',
+ items: [
+ { kind: 'checkbox', children: 'Email Notifications' },
+ { kind: 'checkbox', children: 'Push Notifications' }
+ ]
+ },
+ {
+ name: 'theme',
+ kind: 'radio',
+ defaultValue: 'system',
+ slotHeading: 'Theme',
+ items: [
+ { children: 'System', value: 'system' },
+ { children: 'Light', value: 'light' },
+ { children: 'Dark', value: 'dark' }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Form Actions Menu
+
+Use `formAction` and `formMethod` inside a `<form>` to submit menu actions to different endpoints with no client-side JavaScript required.
+
+```tsx
+<form>
+ <Menu
+ items={[
+ {
+ children: 'Approve',
+ formAction: '/api/actions/approve',
+ formMethod: 'post'
+ },
+ {
+ children: 'Reject',
+ formAction: '/api/actions/reject',
+ formMethod: 'post'
+ },
+ {
+ children: 'Request Changes',
+ formAction: '/api/actions/request-changes',
+ formMethod: 'post'
+ }
+ ]}
+ />
+</form>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the menu layout, mixing sections with different item types.
+
+```tsx
+<MenuRoot>
+ <MenuSection slotHeading="Actions">
+ <MenuItem
+ // onSelect={handleSelect}
+ >
+ New File
+ </MenuItem>
+ <MenuItem
+ // onSelect={handleSelect}
+ >
+ Open File
+ </MenuItem>
+ </MenuSection>
+ <MenuSection slotHeading="Preferences">
+ <MenuCheckboxItem defaultChecked>Auto-save</MenuCheckboxItem>
+ <MenuRadioGroup name="view" slotHeading="View Mode" defaultValue="grid">
+ <MenuRadioGroupItem value="grid">Grid</MenuRadioGroupItem>
+ <MenuRadioGroupItem value="list">List</MenuRadioGroupItem>
+ </MenuRadioGroup>
+ </MenuSection>
+</MenuRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `string \| ({ kind: "section"; slotHeading: ReactNode; children: never; items: ({ kind: "default"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; value: string; formAction: string; formMethod: "get" \| "post" }) \| ({ kind: "checkbox"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; defaultChecked: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotControl: ReactNode }) \| { kind: "divider"; width: "small" \| "medium" \| "large"; filterValue: never }[]; filterValue: never }) \| ({ kind: "default"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; value: string; formAction: string; formMethod: "get" \| "post" }) \| ({ kind: "checkbox"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; defaultChecked: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotControl: ReactNode }) \| ({ name: string; kind: "radio"; radioKind: "radio" \| "check"; slotHeading: ReactNode; items: { kind: never; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; value: string; danger: boolean; required: boolean }[]; defaultValue: string; disabled: boolean; value: string; required: boolean; error: boolean; onValueChange: (value: string) => void }) \| ({ kind: never; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; value: string; danger: boolean; required: boolean }) \| { kind: "divider"; width: "small" \| "medium" \| "large"; filterValue: never }[]` | - | The items to render in the menu. |
+| defaultFilterValue | `string` | - | This sets the default value of the menu search input. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| filterable | `boolean` | `false` | Whether the menu is filterable. |
+| filterMatchFn | `"disable" \| ((matchTerm: string, value: string) => boolean)` | - | The function to use to match items against the search value. |
+| filterValue | `string` | - | The controlled value of the menu search input. Must be used in conjunction with `onFilterChange`. |
+| onFilterChange | `(value: string) => void` | - | Callback fired when the search value changes. |
+| onItemCheckedChange | `(item: { kind: "checkbox"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; defaultChecked: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotControl: ReactNode }, checked: false \| true \| "indeterminate") => void` | - | Callback fired when a menu item's checked state changes |
+| onItemSelect | `(event: Event, item: ({ kind: "default"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; value: string; formAction: string; formMethod: "get" \| "post" }) \| ({ kind: "checkbox"; filterValue: string; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; defaultChecked: boolean; checked: false \| true \| "indeterminate"; error: boolean; onCheckedChange: (checked: false \| true \| "indeterminate") => void; slotControl: ReactNode }) \| ({ kind: never; children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string; value: string; danger: boolean; required: boolean })) => void` | - | Callback fired when a menu item is selected |
+| ref | `React.RefObject<HTMLMenuElement> \| ((instance: HTMLMenuElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; }))` | - | |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Modal.md b/.agents/skills/kaizen-ui/references/components/Modal.md
new file mode 100644
index 0000000..86f8fa1
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Modal.md
@@ -0,0 +1,212 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Modal
+
+A modal dialog that can be triggered by a button or other element. Uses the native `<dialog>`
+element for progressive enhancement, providing built-in backdrop styling, focus management,
+and support for `form method="dialog"` for native close behavior.
+
+## Examples
+
+### Basic Modal
+
+Use when you need to interrupt the user for a confirmation or brief task that requires focused attention.
+
+```tsx
+<Modal
+ slotTrigger={<Button>Open Modal</Button>}
+ slotHeading="Confirm Action"
+ slotFooter={
+ <>
+ <ModalCloseButton kind="tertiary">Cancel</ModalCloseButton>
+ <Button color="brand">Confirm</Button>
+ </>
+ }
+>
+ Are you sure you want to proceed with this action?
+</Modal>
+```
+
+### Fullscreen Modal
+
+Use when the modal content needs maximum screen real estate, such as previews or complex editors.
+
+```tsx
+<Modal
+ className="size-full"
+ slotTrigger={<Button>Open Fullscreen</Button>}
+ slotHeading="Fullscreen Modal"
+ slotFooter={
+ <>
+ <ModalCloseButton kind="tertiary">Close</ModalCloseButton>
+ <Button color="brand">Save</Button>
+ </>
+ }
+>
+ Content that benefits from maximum screen space.
+</Modal>
+```
+
+### Non Dismissible Modal
+
+Use when the user must complete an action before continuing, preventing dismissal via escape or backdrop click.
+
+```tsx
+<Modal
+ dismissible={false}
+ slotTrigger={<Button>Open Required Modal</Button>}
+ slotHeading="Required Action"
+ slotFooter={<Button color="brand">Acknowledge</Button>}
+>
+ You must complete this action before continuing.
+</Modal>
+```
+
+### Multi Step Modal
+
+Use for wizards or forms where accidental backdrop dismissal would lose user progress. Disables `closeOnClickOutside` and uses `ml-auto` on the cancel button to push it away from a left-aligned back button.
+
+```tsx
+<Modal
+ closeOnClickOutside={false}
+ slotTrigger={<Button>Configure Deployment</Button>}
+ slotHeading="Step 2 of 3 — Resources"
+ slotFooter={
+ <>
+ <Button kind="secondary">Back</Button>
+ <ModalCloseButton className="ml-auto" kind="tertiary">
+ Cancel
+ </ModalCloseButton>
+ <Button color="brand">Next</Button>
+ </>
+ }
+>
+ Choose the resources for this deployment. Your progress is preserved across steps.
+</Modal>
+```
+
+### Form Modal
+
+Use when the modal contains a form that should wrap the content for native form submission.
+
+```tsx
+<Modal
+ slotTrigger={<Button>Open Form</Button>}
+ slotHeading="Submit Feedback"
+ renderContent={({ children }) => <form onSubmit={handleSubmit}>{children}</form>}
+ slotFooter={
+ <>
+ <ModalCloseButton kind="tertiary">Cancel</ModalCloseButton>
+ <Button type="submit" color="brand">
+ Submit
+ </Button>
+ </>
+ }
+>
+ Form content goes here
+</Modal>
+```
+
+### Native Form Modal
+
+Use for server-rendered actions that must work without JavaScript. The body is wrapped in a real `<form action>` while `formMethod="dialog"` on the cancel and X close buttons closes the modal without submitting.
+
+```tsx
+<Modal
+ slotTrigger={<Button color="danger">Delete Item</Button>}
+ slotHeading="Confirm Deletion"
+ attributes={{
+ ModalCloseButton: {
+ type: 'submit',
+ formMethod: 'dialog',
+ formNoValidate: true
+ }
+ }}
+ renderContent={({ children }) => (
+ <form action="/api/delete-item" method="post">
+ {children}
+ </form>
+ )}
+ slotFooter={
+ <>
+ <input type="hidden" name="itemId" value="123" />
+ <Button type="submit" formMethod="dialog" formNoValidate kind="tertiary">
+ Cancel
+ </Button>
+ <Button type="submit" color="danger">
+ Delete
+ </Button>
+ </>
+ }
+>
+ Are you sure you want to delete this item? This action cannot be undone.
+</Modal>
+```
+
+### Anchor Trigger Modal
+
+Use `slotAnchorTrigger` paired with `id` for progressive enhancement: JavaScript opens the modal in place, while users without JavaScript navigate to the anchor's `href` as a fallback page.
+
+```tsx
+<Modal
+ id="modal-anchor-trigger-example"
+ slotAnchorTrigger={<Anchor href="/settings">Open Settings</Anchor>}
+ slotHeading="Settings"
+ slotFooter={
+ <>
+ <ModalCloseButton kind="tertiary">Cancel</ModalCloseButton>
+ <Button color="brand">Save</Button>
+ </>
+ }
+>
+ Adjust your preferences below.
+</Modal>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the modal layout and behavior.
+
+```tsx
+<ModalRoot>
+ <ModalTrigger asChild>
+ <Button>Open Modal</Button>
+ </ModalTrigger>
+ <ModalContent>
+ <ModalHeading>Composed Heading</ModalHeading>
+ <ModalMain>Composed modal content using primitives directly.</ModalMain>
+ <ModalFooter>
+ <ModalCloseButton kind="tertiary">Cancel</ModalCloseButton>
+ <Button color="brand">Save</Button>
+ </ModalFooter>
+ </ModalContent>
+</ModalRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, treats the immediate child as the host element, merging this component's props with the child's props. The child's children will be slotted into the component's defined content placement. |
+| closeButtonProps | `{ form?: string; slot?: string; style?: React.CSSProperties; title?: string; defaultValue?: string \| number \| readonly string[]; ref?: React.Ref<HTMLButtonElement>; key?: React.Key; defaultChecked?: boolean; suppressContentEditableWarning?: boolean; suppressHydrationWarning?: boolean; accessKey?: string; autoCapitalize?: "off" \| "none" \| "on" \| "sentences" \| "words" \| "characters" \| (string & {}); autoFocus?: boolean; contentEditable?: Booleanish \| "inherit" \| "plaintext-only"; contextMenu?: string; dir?: string; draggable?: Booleanish; enterKeyHint?: "search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"; hidden?: boolean; id?: string; lang?: string; nonce?: string; spellCheck?: Booleanish; tabIndex?: number; translate?: "yes" \| "no"; radioGroup?: string; role?: React.AriaRole; about?: string; content?: string; datatype?: string; inlist?: any; prefix?: string; property?: string; rel?: string; resource?: string; rev?: string; typeof?: string; vocab?: string; autoCorrect?: string; autoSave?: string; color?: "brand" \| "neutral" \| "danger"; itemProp?: string; itemScope?: boolean; itemType?: string; itemID?: string; itemRef?: string; results?: number; security?: string; unselectable?: "off" \| "on"; popover?: "" \| "auto" \| "manual"; popoverTargetAction?: "toggle" \| "show" \| "hide"; popoverTarget?: string; inert?: boolean; inputMode?: "search" \| "text" \| "none" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal"; is?: string; exportparts?: string; part?: string; "aria-activedescendant"?: string; "aria-atomic"?: Booleanish; "aria-autocomplete"?: "none" \| "list" \| "inline" \| "both"; "aria-braillelabel"?: string; "aria-brailleroledescription"?: string; "aria-busy"?: Booleanish; "aria-checked"?: boolean \| "true" \| "false" \| "mixed"; "aria-colcount"?: number; "aria-colindex"?: number; "aria-colindextext"?: string; "aria-colspan"?: number; "aria-controls"?: string; "aria-current"?: boolean \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"; "aria-describedby"?: string; "aria-description"?: string; "aria-details"?: string; "aria-disabled"?: Booleanish; "aria-dropeffect"?: "link" \| "none" \| "copy" \| "execute" \| "move" \| "popup"; "aria-errormessage"?: string; "aria-expanded"?: Booleanish; "aria-flowto"?: string; "aria-grabbed"?: Booleanish; "aria-haspopup"?: boolean \| "dialog" \| "menu" \| "true" \| "false" \| "grid" \| "listbox" \| "tree"; "aria-hidden"?: Booleanish; "aria-invalid"?: boolean \| "true" \| "false" \| "grammar" \| "spelling"; "aria-keyshortcuts"?: string; "aria-label"?: string; "aria-labelledby"?: string; "aria-level"?: number; "aria-live"?: "off" \| "assertive" \| "polite"; "aria-modal"?: Booleanish; "aria-multiline"?: Booleanish; "aria-multiselectable"?: Booleanish; "aria-orientation"?: "horizontal" \| "vertical"; "aria-owns"?: string; "aria-placeholder"?: string; "aria-posinset"?: number; "aria-pressed"?: boolean \| "true" \| "false" \| "mixed"; "aria-readonly"?: Booleanish; "aria-relevant"?: "text" \| "additions" \| "additions removals" \| "additions text" \| "all" \| "removals" \| "removals additions" \| "removals text" \| "text additions" \| "text removals"; "aria-required"?: Booleanish; "aria-roledescription"?: string; "aria-rowcount"?: number; "aria-rowindex"?: number; "aria-rowindextext"?: string; "aria-rowspan"?: number; "aria-selected"?: Booleanish; "aria-setsize"?: number; "aria-sort"?: "none" \| "ascending" \| "descending" \| "other"; "aria-valuemax"?: number; "aria-valuemin"?: number; "aria-valuenow"?: number; "aria-valuetext"?: string; dangerouslySetInnerHTML?: { __html: string \| TrustedHTML; }; onCopy?: React.ClipboardEventHandler<HTMLButtonElement>; onCopyCapture?: React.ClipboardEventHandler<HTMLButtonElement>; onCut?: React.ClipboardEventHandler<HTMLButtonElement>; onCutCapture?: React.ClipboardEventHandler<HTMLButtonElement>; onPaste?: React.ClipboardEventHandler<HTMLButtonElement>; onPasteCapture?: React.ClipboardEventHandler<HTMLButtonElement>; onCompositionEnd?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionEndCapture?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionStart?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionStartCapture?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionUpdate?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionUpdateCapture?: React.CompositionEventHandler<HTMLButtonElement>; onFocus?: React.FocusEventHandler<HTMLButtonElement>; onFocusCapture?: React.FocusEventHandler<HTMLButtonElement>; onBlur?: React.FocusEventHandler<HTMLButtonElement>; onBlurCapture?: React.FocusEventHandler<HTMLButtonElement>; onChange?: React.FormEventHandler<HTMLButtonElement>; onChangeCapture?: React.FormEventHandler<HTMLButtonElement>; onBeforeInput?: React.InputEventHandler<HTMLButtonElement>; onBeforeInputCapture?: React.FormEventHandler<HTMLButtonElement>; onInput?: React.FormEventHandler<HTMLButtonElement>; onInputCapture?: React.FormEventHandler<HTMLButtonElement>; onReset?: React.FormEventHandler<HTMLButtonElement>; onResetCapture?: React.FormEventHandler<HTMLButtonElement>; onSubmit?: React.FormEventHandler<HTMLButtonElement>; onSubmitCapture?: React.FormEventHandler<HTMLButtonElement>; onInvalid?: React.FormEventHandler<HTMLButtonElement>; onInvalidCapture?: React.FormEventHandler<HTMLButtonElement>; onLoad?: React.ReactEventHandler<HTMLButtonElement>; onLoadCapture?: React.ReactEventHandler<HTMLButtonElement>; onError?: React.ReactEventHandler<HTMLButtonElement>; onErrorCapture?: React.ReactEventHandler<HTMLButtonElement>; onKeyDown?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyDownCapture?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyPress?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyPressCapture?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyUp?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyUpCapture?: React.KeyboardEventHandler<HTMLButtonElement>; onAbort?: React.ReactEventHandler<HTMLButtonElement>; onAbortCapture?: React.ReactEventHandler<HTMLButtonElement>; onCanPlay?: React.ReactEventHandler<HTMLButtonElement>; onCanPlayCapture?: React.ReactEventHandler<HTMLButtonElement>; onCanPlayThrough?: React.ReactEventHandler<HTMLButtonElement>; onCanPlayThroughCapture?: React.ReactEventHandler<HTMLButtonElement>; onDurationChange?: React.ReactEventHandler<HTMLButtonElement>; onDurationChangeCapture?: React.ReactEventHandler<HTMLButtonElement>; onEmptied?: React.ReactEventHandler<HTMLButtonElement>; onEmptiedCapture?: React.ReactEventHandler<HTMLButtonElement>; onEncrypted?: React.ReactEventHandler<HTMLButtonElement>; onEncryptedCapture?: React.ReactEventHandler<HTMLButtonElement>; onEnded?: React.ReactEventHandler<HTMLButtonElement>; onEndedCapture?: React.ReactEventHandler<HTMLButtonElement>; onLoadedData?: React.ReactEventHandler<HTMLButtonElement>; onLoadedDataCapture?: React.ReactEventHandler<HTMLButtonElement>; onLoadedMetadata?: React.ReactEventHandler<HTMLButtonElement>; onLoadedMetadataCapture?: React.ReactEventHandler<HTMLButtonElement>; onLoadStart?: React.ReactEventHandler<HTMLButtonElement>; onLoadStartCapture?: React.ReactEventHandler<HTMLButtonElement>; onPause?: React.ReactEventHandler<HTMLButtonElement>; onPauseCapture?: React.ReactEventHandler<HTMLButtonElement>; onPlay?: React.ReactEventHandler<HTMLButtonElement>; onPlayCapture?: React.ReactEventHandler<HTMLButtonElement>; onPlaying?: React.ReactEventHandler<HTMLButtonElement>; onPlayingCapture?: React.ReactEventHandler<HTMLButtonElement>; onProgress?: React.ReactEventHandler<HTMLButtonElement>; onProgressCapture?: React.ReactEventHandler<HTMLButtonElement>; onRateChange?: React.ReactEventHandler<HTMLButtonElement>; onRateChangeCapture?: React.ReactEventHandler<HTMLButtonElement>; onSeeked?: React.ReactEventHandler<HTMLButtonElement>; onSeekedCapture?: React.ReactEventHandler<HTMLButtonElement>; onSeeking?: React.ReactEventHandler<HTMLButtonElement>; onSeekingCapture?: React.ReactEventHandler<HTMLButtonElement>; onStalled?: React.ReactEventHandler<HTMLButtonElement>; onStalledCapture?: React.ReactEventHandler<HTMLButtonElement>; onSuspend?: React.ReactEventHandler<HTMLButtonElement>; onSuspendCapture?: React.ReactEventHandler<HTMLButtonElement>; onTimeUpdate?: React.ReactEventHandler<HTMLButtonElement>; onTimeUpdateCapture?: React.ReactEventHandler<HTMLButtonElement>; onVolumeChange?: React.ReactEventHandler<HTMLButtonElement>; onVolumeChangeCapture?: React.ReactEventHandler<HTMLButtonElement>; onWaiting?: React.ReactEventHandler<HTMLButtonElement>; onWaitingCapture?: React.ReactEventHandler<HTMLButtonElement>; onAuxClick?: React.MouseEventHandler<HTMLButtonElement>; onAuxClickCapture?: React.MouseEventHandler<HTMLButtonElement>; onClick?: React.MouseEventHandler<HTMLButtonElement>; onClickCapture?: React.MouseEventHandler<HTMLButtonElement>; onContextMenu?: React.MouseEventHandler<HTMLButtonElement>; onContextMenuCapture?: React.MouseEventHandler<HTMLButtonElement>; onDoubleClick?: React.MouseEventHandler<HTMLButtonElement>; onDoubleClickCapture?: React.MouseEventHandler<HTMLButtonElement>; onDrag?: React.DragEventHandler<HTMLButtonElement>; onDragCapture?: React.DragEventHandler<HTMLButtonElement>; onDragEnd?: React.DragEventHandler<HTMLButtonElement>; onDragEndCapture?: React.DragEventHandler<HTMLButtonElement>; onDragEnter?: React.DragEventHandler<HTMLButtonElement>; onDragEnterCapture?: React.DragEventHandler<HTMLButtonElement>; onDragExit?: React.DragEventHandler<HTMLButtonElement>; onDragExitCapture?: React.DragEventHandler<HTMLButtonElement>; onDragLeave?: React.DragEventHandler<HTMLButtonElement>; onDragLeaveCapture?: React.DragEventHandler<HTMLButtonElement>; onDragOver?: React.DragEventHandler<HTMLButtonElement>; onDragOverCapture?: React.DragEventHandler<HTMLButtonElement>; onDragStart?: React.DragEventHandler<HTMLButtonElement>; onDragStartCapture?: React.DragEventHandler<HTMLButtonElement>; onDrop?: React.DragEventHandler<HTMLButtonElement>; onDropCapture?: React.DragEventHandler<HTMLButtonElement>; onMouseDown?: React.MouseEventHandler<HTMLButtonElement>; onMouseDownCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseEnter?: React.MouseEventHandler<HTMLButtonElement>; onMouseLeave?: React.MouseEventHandler<HTMLButtonElement>; onMouseMove?: React.MouseEventHandler<HTMLButtonElement>; onMouseMoveCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseOut?: React.MouseEventHandler<HTMLButtonElement>; onMouseOutCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseOver?: React.MouseEventHandler<HTMLButtonElement>; onMouseOverCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseUp?: React.MouseEventHandler<HTMLButtonElement>; onMouseUpCapture?: React.MouseEventHandler<HTMLButtonElement>; onSelect?: React.ReactEventHandler<HTMLButtonElement>; onSelectCapture?: React.ReactEventHandler<HTMLButtonElement>; onTouchCancel?: React.TouchEventHandler<HTMLButtonElement>; onTouchCancelCapture?: React.TouchEventHandler<HTMLButtonElement>; onTouchEnd?: React.TouchEventHandler<HTMLButtonElement>; onTouchEndCapture?: React.TouchEventHandler<HTMLButtonElement>; onTouchMove?: React.TouchEventHandler<HTMLButtonElement>; onTouchMoveCapture?: React.TouchEventHandler<HTMLButtonElement>; onTouchStart?: React.TouchEventHandler<HTMLButtonElement>; onTouchStartCapture?: React.TouchEventHandler<HTMLButtonElement>; onPointerDown?: React.PointerEventHandler<HTMLButtonElement>; onPointerDownCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerMove?: React.PointerEventHandler<HTMLButtonElement>; onPointerMoveCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerUp?: React.PointerEventHandler<HTMLButtonElement>; onPointerUpCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerCancel?: React.PointerEventHandler<HTMLButtonElement>; onPointerCancelCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerEnter?: React.PointerEventHandler<HTMLButtonElement>; onPointerLeave?: React.PointerEventHandler<HTMLButtonElement>; onPointerOver?: React.PointerEventHandler<HTMLButtonElement>; onPointerOverCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerOut?: React.PointerEventHandler<HTMLButtonElement>; onPointerOutCapture?: React.PointerEventHandler<HTMLButtonElement>; onGotPointerCapture?: React.PointerEventHandler<HTMLButtonElement>; onGotPointerCaptureCapture?: React.PointerEventHandler<HTMLButtonElement>; onLostPointerCapture?: React.PointerEventHandler<HTMLButtonElement>; onLostPointerCaptureCapture?: React.PointerEventHandler<HTMLButtonElement>; onScroll?: React.UIEventHandler<HTMLButtonElement>; onScrollCapture?: React.UIEventHandler<HTMLButtonElement>; onScrollEnd?: React.UIEventHandler<HTMLButtonElement>; onScrollEndCapture?: React.UIEventHandler<HTMLButtonElement>; onWheel?: React.WheelEventHandler<HTMLButtonElement>; onWheelCapture?: React.WheelEventHandler<HTMLButtonElement>; onAnimationStart?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationStartCapture?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationEnd?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationEndCapture?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationIteration?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationIterationCapture?: React.AnimationEventHandler<HTMLButtonElement>; onToggle?: React.ToggleEventHandler<HTMLButtonElement>; onBeforeToggle?: React.ToggleEventHandler<HTMLButtonElement>; onTransitionCancel?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionCancelCapture?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionEnd?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionEndCapture?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionRun?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionRunCapture?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionStart?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionStartCapture?: React.TransitionEventHandler<HTMLButtonElement>; asChild?: boolean; disabled?: boolean; name?: string; value?: string \| number \| readonly string[]; formAction?: string \| ((formData: FormData) => void \| Promise<void>); formEncType?: string; formMethod?: string; formNoValidate?: boolean; formTarget?: string; type?: "button" \| "submit" \| "reset"; size?: "small" \| "tiny" \| "medium" \| "large"; }` | - | Props to pass to the close button. This can be used to customize the close button's behavior for progressive enhancement scenarios. |
+| closeOnClickOutside | `boolean` | - | |
+| defaultOpen | `boolean` | `false` | Initial open state when the dialog is uncontrolled. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| dismissible | `boolean` | `true` | Controls whether the modal is dismissible. Use this to disable the built in closing mechanisms. When set to `false` this will: - Hide the close button - Disable the escape key closing the modal - Disable clicking outside the modal from closing it |
+| forceMount | `boolean` | - | |
+| hideCloseButton | `boolean` | - | When true, hides the modal's close button. Useful for modals that should not be dismissible. |
+| modal | `boolean` | `true` | When `true`, the dialog is opened via `HTMLDialogElement.showModal()`, rendering a top-layer backdrop and trapping focus. When `false`, the dialog is opened via `HTMLDialogElement.show()` as a non-modal dialog. |
+| onEscapeKeyDown | `(event: KeyboardEvent) => void` | - | |
+| onInteractOutside | `(event: MouseEvent) => void` | - | Event handler called when an interaction event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| onOpenAutoFocus | `(event: Event) => void` | - | |
+| onOpenChange | `(open: boolean) => void` | - | Callback invoked whenever the dialog's open state changes, in both controlled and uncontrolled modes. Consecutive transitions to the same value are deduped, so the callback fires at most once per state change. |
+| onPointerDownOutside | `(event: MouseEvent) => void` | - | Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| open | `boolean` | - | Controlled open state. When provided, the hook operates in controlled mode and `defaultOpen` is ignored. The consumer is responsible for updating this value in response to {@link UseDialogOptions.onOpenChange} callbacks. |
+| renderContent | `(props: { children: React.ReactNode; }) => React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>` | - | A render function that wraps the modal content. This is useful for injecting elements like forms. When provided, this will force `asChild` on the ModalContent component. |
+| slotAnchorTrigger | `ReactNode` | - | The content to render in the modal anchor trigger. This provides progressive enhancement by using an anchor that opens the modal when JavaScript is enabled and navigates to a fallback URL when it is disabled. |
+| slotFooter | `ReactNode` | - | The content to render in the modal footer. Handles spacing its children for you, and by default aligns the children to the right. |
+| slotHeading | `ReactNode` | - | The content to render in the modal heading. If not provided, the modal will render empty space to make room for the close button. |
+| slotTrigger | `ReactNode` | - | The content to render in the modal trigger. This trigger will open the modal when clicked. |
diff --git a/.agents/skills/kaizen-ui/references/components/Notification.md b/.agents/skills/kaizen-ui/references/components/Notification.md
new file mode 100644
index 0000000..008e89b
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Notification.md
@@ -0,0 +1,157 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Notification
+
+A notification component that displays important messages and alerts to users.
+It provides a flexible layout with support for icons, headings, subheadings, close buttons and footers.
+
+The component uses a grid-based layout through NotificationContent to organize its elements:
+
+- Icon on the left (optional)
+- Header content in the middle containing heading and subheading
+- Close button on the right (optional)
+- Footer below (optional)
+
+## Examples
+
+### Basic Notification
+
+Use for persistent informational messages that provide context the user may need to act on.
+
+```tsx
+<Notification status="info" slotSubheading="Check your inbox for details.">
+ New message received
+</Notification>
+```
+
+### Dismissible Notification
+
+Pass `onClose` to render the dismiss button — use whenever the user should be able to clear the notification themselves.
+
+```tsx
+<Notification
+ status="success"
+ slotSubheading="Your model is ready for inference."
+ onClose={handleClose}
+>
+ Deployment complete
+</Notification>
+```
+
+### Statuses Notification
+
+Set `status` to convey severity: `info` for context, `success` for confirmation, `warning` for caution, and `error` for critical failures that need a next step.
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <Notification status="info" slotSubheading="Added 50K labeled images to the dataset.">
+ New training data available
+ </Notification>
+ <Notification
+ status="success"
+ slotSubheading="Inference endpoint active at api.nvidia.com/v1/chat."
+ >
+ Model deployed successfully
+ </Notification>
+ <Notification
+ status="warning"
+ slotSubheading="GPU 0: 92% memory utilization — consider reducing batch size."
+ >
+ High GPU memory usage detected
+ </Notification>
+ <Notification
+ status="error"
+ slotSubheading="Service temporarily unavailable — engineers investigating."
+ >
+ Inference endpoint unavailable
+ </Notification>
+</Flex>
+```
+
+### With Footer Notification
+
+Pass `slotFooter` with action buttons when the notification needs an inline follow-up action like view, retry, or dismiss.
+
+```tsx
+<Notification
+ status="warning"
+ slotSubheading="3 resources are over budget this month."
+ slotFooter={
+ <>
+ <Button kind="secondary" size="small">
+ View Details
+ </Button>
+ <Button kind="tertiary" size="small">
+ Dismiss
+ </Button>
+ </>
+ }
+>
+ Budget alert
+</Notification>
+```
+
+### With Icon Notification
+
+Override `slotIcon` when a domain-specific glyph communicates the message better than the default status icon.
+
+```tsx
+<Notification
+ status="info"
+ slotIcon={<Bell />}
+ slotSubheading="Version 2.1.0 is available."
+ onClose={handleClose}
+>
+ Update available
+</Notification>
+```
+
+### Inline Notification
+
+Use `kind="inline"` when the notification renders alongside content (e.g. inline form validation) rather than as a stacked toast-style block.
+
+```tsx
+<Notification kind="inline" status="error" slotSubheading="This field is required.">
+ Validation error
+</Notification>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the notification grid layout and element placement.
+
+```tsx
+<NotificationRoot status="success">
+ <NotificationContent>
+ <NotificationIcon status="success" />
+ <NotificationHeader>
+ <NotificationHeading>Composed notification</NotificationHeading>
+ <NotificationSubheading>
+ Using primitives for full layout control.
+ </NotificationSubheading>
+ </NotificationHeader>
+ <NotificationFooter>
+ <Button kind="secondary" size="small">
+ View
+ </Button>
+ </NotificationFooter>
+ </NotificationContent>
+</NotificationRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| children | `ReactNode` | - | The main heading text or element to display in the notification. This is required and serves as the primary message. |
+| kind | `"inline" \| "stacked"` | `"stacked"` | Notification variants. - `stacked`: Displays a notification with a header, subheading, and footer stacked vertically - `inline`: Displays a notification with a header, subheading, and footer in a single line |
+| onClose | `() => void` | - | Optional callback function that is called when the close button is clicked. If provided, displays a close button in the notification. |
+| ref | `((instance: HTMLDivElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLDivElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| slotCloseIcon | `ReactNode` | `<Icon name="close" />` | Optional custom close icon element to replace the default close button icon. Only displayed when onClose handler is provided. |
+| slotFooter | `ReactNode` | - | Optional footer content to display at the bottom of the notification. Can contain actions, links or additional information. |
+| slotIcon | `ReactNode` | - | Optional icon element to display on the left side of the notification. Typically used to indicate the notification type or status. |
+| slotSubheading | `ReactNode` | - | Optional subheading text or element to display below the main heading. Provides additional context or details about the notification. |
+| status | `"error" \| "warning" \| "success" \| "info"` | `"info"` | Notifications include 4 statuses that convey semantic meaning: - `info`: Provides additional information that may require action - `success`: Confirms to the user that they have completed an action or task - `warning`: Cautions the user on something urgent to avoid an issue - `error`: Communicates a critical issue that needs attention and provides a next step |
diff --git a/.agents/skills/kaizen-ui/references/components/PageHeader.md b/.agents/skills/kaizen-ui/references/components/PageHeader.md
new file mode 100644
index 0000000..a297b51
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/PageHeader.md
@@ -0,0 +1,152 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# PageHeader
+
+The page header describes the current page and displays a title, breadcrumbs, and page-level actions
+
+## Notes
+
+- Do not place back-navigation buttons ("Back to [list]") in slotActions. Back navigation belongs in slotBreadcrumbs via the Breadcrumbs component.
+
+- Use kind="flat" for list/browse views and dashboards. The "floating" variant is for detail pages.
+
+## Examples
+
+### Basic Page Header
+
+Use at the top of a page to describe its purpose with a title and optional description.
+
+```tsx
+<PageHeader
+ slotSubheading="Subheading"
+ slotHeading="Page Title"
+ slotDescription="A brief description of what this page contains."
+/>
+```
+
+### Floating Page Header
+
+Use on detail pages where the header should read as a card and stand apart from page content.
+
+```tsx
+<PageHeader
+ kind="floating"
+ slotSubheading="Subheading"
+ slotHeading="Page Title"
+ slotDescription="A brief description of what this page contains."
+/>
+```
+
+### With Breadcrumbs Page Header
+
+Use for back-navigation and location context on nested pages. Back navigation belongs here, never in slotActions.
+
+```tsx
+<PageHeader
+ slotBreadcrumbs={
+ <Breadcrumbs
+ items={[
+ { children: <a href="/">Home</a> },
+ { children: <a href="/models">Models</a> },
+ 'Llama 3.1 405B'
+ ]}
+ />
+ }
+ slotSubheading="NVIDIA"
+ slotHeading="Llama 3.1 405B"
+ slotDescription="A large language model optimized for dialogue and instruction-following tasks."
+/>
+```
+
+### With Actions Page Header
+
+Use when the page has primary actions like create, deploy, or export that belong in the header.
+
+```tsx
+<PageHeader
+ slotHeading="Clusters"
+ slotDescription="Manage your compute clusters and infrastructure."
+ slotActions={
+ <>
+ <Button kind="secondary">Export</Button>
+ <Button color="brand">Create Cluster</Button>
+ </>
+ }
+/>
+```
+
+### With Non Stretching Actions Page Header
+
+Wrap actions in a Flex container when the buttons should keep their natural size instead of stretching to fill the footer on narrow viewports.
+
+```tsx
+<PageHeader
+ slotHeading="Page Title"
+ slotSubheading="Subheading"
+ slotDescription="A brief description of what this page contains."
+ slotActions={
+ <Flex gap="density-md" align="end">
+ <Button kind="secondary">Secondary</Button>
+ <Button color="brand">Primary</Button>
+ </Flex>
+ }
+/>
+```
+
+### With Custom Heading Page Header
+
+Pass JSX into slotHeading when the title needs an inline adornment such as a status badge or a custom heading element.
+
+```tsx
+<PageHeader
+ slotSubheading="Subheading"
+ slotHeading={
+ <Flex gap="density-md" align="center">
+ <h1>Page Title</h1>
+ <Badge>Coming soon</Badge>
+ </Flex>
+ }
+ slotDescription="A brief description of what this page contains."
+>
+ <Badge kind="solid">Language</Badge>
+</PageHeader>
+```
+
+### Composed
+
+```tsx
+<PageHeaderRoot>
+ <PageHeaderContainer kind="floating">
+ <PageHeaderContent>
+ <PageHeaderHeader>
+ <PageHeaderSubheading>Subheading</PageHeaderSubheading>
+ <PageHeaderHeading>Page Title</PageHeaderHeading>
+ <PageHeaderDescription>
+ A brief description of what this page contains.
+ </PageHeaderDescription>
+ </PageHeaderHeader>
+ <PageHeaderMain>Additional content area</PageHeaderMain>
+ </PageHeaderContent>
+ <PageHeaderFooter>
+ <Button color="brand">Action</Button>
+ </PageHeaderFooter>
+ </PageHeaderContainer>
+</PageHeaderRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| children | `ReactNode` | - | The children of the PageHeader. Renders below `slotDescription` with a large gap. Use for additional content such as Tags, Badges, Progress Bars, etc. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| kind | `"flat" \| "floating"` | `"flat"` | PageHeader variants. - `floating`: A PageHeader rendered in a container with a background and padding, creating separation from surrounding content. - `flat`: A PageHeader rendered with no padding, border, or background color. Ideal for lightweight experiences where content blends seamlessly. |
+| ref | `((instance: HTMLDivElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLDivElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| slotActions | `ReactNode` | - | Slot for the PageHeader footer. Handles spacing its children for you, and by default aligns the children to the right. Also handles responsive behaviour by stretching footer items on smaller screens to fill the width of the container. |
+| slotBreadcrumbs | `ReactNode` | - | Slot for the breadcrumbs of the PageHeader. Renders above `slotSubheading` |
+| slotDescription | `ReactNode` | - | Slot for the description of the PageHeader. With `body-regular-md` text styles |
+| slotHeading | `ReactNode` | - | Slot for the heading of the PageHeader. With `body-bold-2xl` text styles, rendered below `slotSubheading` and above `slotDescription`. |
+| slotSubheading | `ReactNode` | - | Slot for the subheading of the PageHeader. With `label-light-xl` text styles, rendered above `slotHeading`. |
diff --git a/.agents/skills/kaizen-ui/references/components/Pagination.md b/.agents/skills/kaizen-ui/references/components/Pagination.md
new file mode 100644
index 0000000..8df7de3
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Pagination.md
@@ -0,0 +1,209 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Pagination
+
+A pagination component that provides different styles of navigation for paginated content.
+
+## Notes
+
+- Only render Pagination when totalItems > pageSize. When the dataset fits on a single page, Pagination is unnecessary — conditionally render it.
+
+## Examples
+
+### Basic Pagination
+
+Use for large datasets where users may need to jump to a specific page by number.
+
+```tsx
+<Pagination totalItems={100} defaultPage={1} defaultPageSize={10} />
+```
+
+### Tabs Pagination
+
+Use for moderate-sized datasets where users benefit from seeing clickable page numbers.
+
+```tsx
+<Pagination kind="tabs" totalItems={100} defaultPage={1} defaultPageSize={10} />
+```
+
+### Simple Pagination
+
+Use for linear navigation where only previous and next actions are needed.
+
+```tsx
+<Pagination kind="simple" totalItems={100} defaultPage={1} defaultPageSize={10} />
+```
+
+### With Controls Pagination
+
+Use when users need to adjust page size and see the current item range.
+
+```tsx
+<Pagination displayControls totalItems={100} defaultPage={1} defaultPageSize={10} />
+```
+
+### Controlled Pagination
+
+Pass `page` + `onPageChange` (and `pageSize` + `onPageSizeChange`) when pagination state lives outside the component — e.g. synced with URL params, a query cache, or a server response.
+
+```tsx
+<Pagination
+ totalItems={100}
+ page={1}
+ pageSize={10}
+ onPageChange={handlePageChange}
+ onPageSizeChange={handlePageSizeChange}
+/>
+```
+
+### With Custom Range Text Pagination
+
+Pass `rangeTextFormatFn` to override the default `"1-10 of 100 items"` label. Receives `{ firstItemIndex, lastItemIndex, totalItems, pageSize }` and returns a `ReactNode`. Requires `displayControls`.
+
+```tsx
+<Pagination
+ displayControls
+ totalItems={100}
+ defaultPage={1}
+ defaultPageSize={10}
+ rangeTextFormatFn={range =>
+ `Showing ${range.firstItemIndex}–${range.lastItemIndex} of ${range.totalItems} results`
+ }
+/>
+```
+
+### Tabs As Links Pagination
+
+Pass custom `items` with `href` to render each page tab as an anchor — ideal for SSR navigation where the URL is the source of truth instead of React state.
+
+```tsx
+<Pagination
+ kind="tabs"
+ totalItems={100}
+ defaultPage={1}
+ defaultPageSize={10}
+ items={Array.from({ length: 10 }, (_, i) => ({
+ value: i + 1,
+ children: i + 1,
+ href: `?page=${i + 1}`
+ }))}
+/>
+```
+
+### Form Submission Pagination
+
+Set `action="form"` and wrap in a `<form>` to render the arrow buttons, page input, and page size select as native submit controls. Parse the submission with `parsePaginationFormData(formData, { submitter, totalItems })` to support progressive enhancement (works without JS) and server-driven pagination.
+
+```tsx
+<form
+ onSubmit={event => {
+ event.preventDefault()
+ const submitter = (event.nativeEvent as SubmitEvent).submitter
+ const formData = new FormData(event.currentTarget)
+ parsePaginationFormData(formData, { submitter, totalItems: 100 })
+ }}
+>
+ <Pagination
+ action="form"
+ displayControls
+ totalItems={100}
+ defaultPage={1}
+ defaultPageSize={10}
+ />
+</form>
+```
+
+### Cursor Based Pagination
+
+Override `name` and `value` on individual arrow buttons via `attributes` when integrating with cursor-based APIs that submit opaque cursors instead of page numbers.
+
+```tsx
+<form>
+ <Pagination
+ kind="simple"
+ action="form"
+ totalItems={100}
+ page={2}
+ pageSize={10}
+ attributes={{
+ PaginationArrowButtonPrevious: {
+ name: 'cursor',
+ value: 'prev_abc123'
+ },
+ PaginationArrowButtonNext: {
+ name: 'cursor',
+ value: 'next_xyz789'
+ }
+ }}
+ />
+</form>
+```
+
+### Tabs Form Submission Pagination
+
+When pairing `kind="tabs"` with `action="form"`, supply custom `items` rendered as `<Button type="submit" name="page">` so each tab submits its page number — the default tab triggers cannot auto-convert to form buttons.
+
+```tsx
+<form>
+ <Pagination
+ kind="tabs"
+ action="form"
+ totalItems={50}
+ defaultPage={1}
+ defaultPageSize={10}
+ items={Array.from({ length: 5 }, (_, i) => ({
+ value: i + 1,
+ asChild: true,
+ children: (
+ <Button type="submit" name="page" value={i + 1} kind="tertiary">
+ {i + 1}
+ </Button>
+ )
+ }))}
+ />
+</form>
+```
+
+### Composed
+
+```tsx
+<PaginationRoot totalItems={100} defaultPage={1} defaultPageSize={10}>
+ <PaginationNavigationGroup>
+ <PaginationArrowButton direction="first" />
+ <PaginationArrowButton direction="previous" />
+ <PaginationPageInput />
+ <PaginationPageCountText
+ // pageCountTextFormatFn={(pageMeta) => `of ${pageMeta.total}`}
+ />
+ <PaginationArrowButton direction="next" />
+ <PaginationArrowButton direction="last" />
+ </PaginationNavigationGroup>
+</PaginationRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **displayControls** \* | `true \| false` | `false` | Whether to display the controls (page size select and associated item range text) |
+| **totalItems** \* | `number` | - | The total number of items. Used to calculate the number of pages and the item range text. |
+| action | `"form"` | - | The action mode for the pagination component. - `undefined`: Default behavior using React state management (controlled/uncontrolled). - `"form"`: Enables native form submission. Child components will render as submit buttons with appropriate `name` and `value` attributes, skipping internal React state updates. Useful for server-driven pagination where the URL is the source of truth. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| defaultPage | `number` | `1` | The initial value of the page. This is used when first rendering the component but does not maintain control over state changes after initial rendering. |
+| defaultPageSize | `number` | `10` | The initial value of the page size. This is used when first rendering the component but does not maintain control over state changes after initial rendering. |
+| items | `never \| Omit<TabItem, "value"> & { value: number; }[]` | - | |
+| kind | `"input" \| "tabs" \| "simple"` | `"input"` | The kind of pagination to render. Determines what components are displayed. - `simple`: A basic previous and next button - meant for linear navigation, providing users the ability to move forwards or backwards in a sequence. - `input`: An input for navigating to a specific page between first, next, previous, and last buttons - meant for large datasets where users may want to jump to a specific page - `tabs`: A list of page numbers as tabs between first, next, previous, and last buttons - meant for moderate-sized datasets allowing users to skim through a range |
+| onPageChange | `(page: number) => void` | - | Callback fired when the page changes. |
+| onPageSizeChange | `(pageSize: number) => void` | - | Callback fired when the page size changes. |
+| page | `number` | - | The value of the page. This is used to control which item is open in a controlled component setup. If not provided, the component will be uncontrolled and manage its own state internally. |
+| pageMeta | `{ first: number; last: number; total: number }` | - | Override metadata for the page range. Useful for overriding the default page range bounds. |
+| pageSize | `number` | - | The value of the page size. This is used to control which item is open in a controlled component setup. If not provided, the component will be uncontrolled and manage its own state internally. |
+| pageSizeOptions | `number[]` | `[10, 25, 50, 100]` | The available page sizes for the page size select |
+| rangeMeta | `{ firstItemIndex: number; lastItemIndex: number; totalItems: number; pageSize: number }` | - | Override meta data for the item range. Useful for overriding the default item range bounds. |
+| rangeTextFormatFn | `(rangeMeta: { firstItemIndex: number; lastItemIndex: number; totalItems: number; pageSize: number }) => ReactNode \| never` | - | Optional custom format function for the range text that is rendered when `displayControls` is true. |
+| renderedItemCount | `never \| 7 \| 5 \| 6 \| 8 \| 9 \| 10` | - | |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Panel.md b/.agents/skills/kaizen-ui/references/components/Panel.md
new file mode 100644
index 0000000..8fbed72
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Panel.md
@@ -0,0 +1,113 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Panel
+
+A panel is a simple container used to wrap content and actions for a given component in a
+card-like format with a background, border, and padding.
+
+## Notes
+
+- Panel manages its own internal padding. Do not add Tailwind padding classes (p-4, p-5, etc.) to className — they stack with the internal padding and create visual doubling.
+
+## Examples
+
+### Basic Panel
+
+Use to wrap related content and actions in a card-like container with a background, border, and padding.
+
+```tsx
+<Panel slotHeading="Panel Title">Panel content goes here.</Panel>
+```
+
+### With Icon Panel
+
+Use when an icon helps identify the panel's purpose at a glance.
+
+```tsx
+<Panel slotHeading="Configuration" slotIcon={<Icon />}>
+ Manage your settings and preferences.
+</Panel>
+```
+
+### With Footer Panel
+
+Use when the panel has actions that apply to its content, such as save or cancel buttons.
+
+```tsx
+<Panel
+ slotHeading="Job Details"
+ slotIcon={<Icon />}
+ slotFooter={
+ <>
+ <Button kind="secondary">Cancel</Button>
+ <Button color="brand">Save</Button>
+ </>
+ }
+>
+ Fill in the details for your new job.
+</Panel>
+```
+
+### High Elevation Panel
+
+Use when you need increased contrast between the panel and the page background, such as in layered UIs.
+
+```tsx
+<Panel slotHeading="Overlay Panel" elevation="high">
+ This panel uses a raised background for increased contrast.
+</Panel>
+```
+
+### Compact Density Panel
+
+Use to override panel spacing locally when a single panel needs to be denser than the surrounding ThemeProvider density.
+
+```tsx
+<Panel
+ density="compact"
+ slotHeading="Storage"
+ slotIcon={<Icon />}
+ slotFooter={<Button color="brand">Save</Button>}
+>
+ Tightens internal padding and footer spacing for dense layouts.
+</Panel>
+```
+
+### Content Only Panel
+
+Use for simple content containers where a heading is unnecessary.
+
+```tsx
+<Panel>Content without a heading or footer.</Panel>
+```
+
+### Composed
+
+```tsx
+<PanelRoot elevation="mid">
+ <PanelHeader>
+ <PanelIcon>
+ <Icon />
+ </PanelIcon>
+ <PanelHeading>Panel Title</PanelHeading>
+ </PanelHeader>
+ <PanelContent>Panel content goes here.</PanelContent>
+ <PanelFooter>
+ <Button color="brand">Action</Button>
+ </PanelFooter>
+</PanelRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ----------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| density | `"compact" \| "standard" \| "spacious"` | - | The density of the panel |
+| elevation | `"high" \| "low" \| "higher" \| "mid"` | `"mid"` | The elevation of the panel. This changes the background color in dark mode to indicate hierarchy. In light mode background color only changes for `low` elevation. Set this if you want increased contrast between the panel and the page background. - `high`: --background-color-surface-raised - `higher`: --background-color-surface-overlay - `mid`: --background-color-surface-base - `low`: --background-color-surface-sunken |
+| slotFooter | `ReactNode` | - | The slot for the footer of the panel. Automatically handles spacing and aligns content to the end of the container. |
+| slotHeading | `ReactNode` | - | The slot for the heading of the panel. This is rendered at the top of the panel with `label/bold/xl` typography styles. |
+| slotIcon | `ReactNode` | - | Icon to be displayed in the panel. This is rendered to the left of the heading if provided and handles sizing and color for the icon automatically. |
diff --git a/.agents/skills/kaizen-ui/references/components/Popover.md b/.agents/skills/kaizen-ui/references/components/Popover.md
new file mode 100644
index 0000000..26deba8
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Popover.md
@@ -0,0 +1,162 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Popover
+
+Displays rich content in a portal, triggered by a button click. Use a popover
+to display specific information, options, or actions related to an element on
+the page.
+
+Built on the native Popover API and CSS Anchor Positioning for progressive
+enhancement. The trigger uses `popovertarget` so toggling works without
+JavaScript. Positioning is handled entirely in CSS via `anchor-name` /
+`position-anchor`.
+
+## Examples
+
+### Basic Popover
+
+Use when you need to show supplementary information triggered by a button click without navigating away.
+
+```tsx
+<Popover slotContent={<p>Additional context about this item.</p>}>
+ <Button>More Info</Button>
+</Popover>
+```
+
+### Positioning Popover
+
+Combine `side` (`top` | `bottom` | `left` | `right`) and `align` (`start` | `center` | `end`) to control where the popover renders relative to its trigger. Override the defaults when the trigger sits near a viewport edge or sibling content would otherwise overlap.
+
+```tsx
+<Popover side="right" align="end" slotContent={<p>Right side, end aligned</p>}>
+ <Button>Open</Button>
+</Popover>
+```
+
+### With Chevron Popover
+
+Add `AnimatedChevron` inside the trigger to give a visual hint that the button toggles an open/closed surface.
+
+```tsx
+<Popover slotContent={<p>Additional context about this item.</p>}>
+ <Button kind="secondary">
+ Open Popover
+ <AnimatedChevron />
+ </Button>
+</Popover>
+```
+
+### With Rich Content Popover
+
+Compose layout primitives inside `slotContent` to render rich, structured content like profile cards. Keep the content focused — avoid overcrowding the popover.
+
+```tsx
+<Popover
+ side="right"
+ align="start"
+ slotContent={
+ <Stack gap="density-md" className="w-[260px] p-4">
+ <Stack direction="row" gap="density-md" align="center">
+ <Avatar fallback="JD" size="large" />
+ <Stack gap="density-sm">
+ <Stack direction="row" gap="density-sm" align="center">
+ <Text kind="label/bold/md">John Doe</Text>
+ <Badge color="green" kind="solid">
+ Active
+ </Badge>
+ </Stack>
+ <Text kind="body/regular/sm">Product Designer</Text>
+ </Stack>
+ </Stack>
+ <Stack direction="row" gap="density-sm">
+ <Button kind="secondary" size="small">
+ View Profile
+ </Button>
+ <Button kind="primary" color="brand" size="small">
+ Message
+ </Button>
+ </Stack>
+ </Stack>
+ }
+>
+ <Button>View Team Member</Button>
+</Popover>
+```
+
+### Modal Popover
+
+Use when the popover content requires focused interaction and should prevent access to the rest of the page.
+
+```tsx
+<Popover
+ modal
+ slotContent={
+ <div>
+ <p>This popover traps focus and dims the background.</p>
+ <Button>Action</Button>
+ </div>
+ }
+>
+ <Button>Open Modal Popover</Button>
+</Popover>
+```
+
+### With Anchor Popover
+
+Use `PopoverAnchor` when the popover should position against an element other than the trigger — for example, a row in a table where the action button lives in a different cell.
+
+```tsx
+<PopoverRoot>
+ <Stack direction="row" gap="density-xl" align="center">
+ <PopoverTrigger asChild>
+ <Button>Trigger</Button>
+ </PopoverTrigger>
+ <PopoverAnchor>
+ <Text kind="body/regular/md">Content anchors here</Text>
+ </PopoverAnchor>
+ </Stack>
+ <PopoverContent>
+ <p>This popover positions against the anchor, not the trigger.</p>
+ </PopoverContent>
+</PopoverRoot>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the popover trigger and content layout.
+
+```tsx
+<PopoverRoot>
+ <PopoverTrigger asChild>
+ <Button>Trigger</Button>
+ </PopoverTrigger>
+ <PopoverContent>
+ <p>Composed popover content using primitives directly.</p>
+ </PopoverContent>
+</PopoverRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | ---------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **slotContent** \* | `ReactNode` | - | The content rendered within the popover |
+| align | `"center" \| "start" \| "end"` | `"center"` | The alignment of the popover content relative to the trigger. |
+| defaultOpen | `boolean` | - | The open state of the popover when it is initially rendered. Use when you do not need to control its open state. |
+| disabled | `boolean` | - | Disables the popover trigger |
+| id | `string` | - | A stable identifier used to derive the popover content id and CSS anchor name. Provide this when rendering in SSR-sensitive trees to ensure the generated ids remain consistent between server and client. |
+| modal | `boolean` | `false` | The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers. Modality is disabled by default to minimize performance impact. |
+| onCloseAutoFocus | `(event: Event) => void` | - | Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`. |
+| onEscapeKeyDown | `(event: KeyboardEvent) => void` | - | Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. |
+| onInteractOutside | `(event: Event) => void` | - | Event handler called when an interaction event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| onOpenAutoFocus | `(event: Event) => void` | - | Event handler called when focus moves into the component after opening. It can be prevented by calling `event.preventDefault`. |
+| onOpenChange | `(open: boolean) => void` | - | Event handler called when the open state of the popover changes. |
+| onPointerDownOutside | `(event: Event) => void` | - | Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| open | `boolean` | - | The controlled open state of the popover. Must be used in conjunction with `onOpenChange`. |
+| positionAnchor | `string` | - | The CSS anchor name to position this popover against. This should match the `anchorName` prop on the corresponding `PopoverTrigger` or `PopoverAnchor`. When not provided, uses the auto-generated anchor name from `PopoverRoot` context. |
+| side | `"right" \| "bottom" \| "left" \| "top"` | `"bottom"` | The preferred side of the trigger to render against when open. Will be reversed when collisions occur. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/ProgressBar.md b/.agents/skills/kaizen-ui/references/components/ProgressBar.md
new file mode 100644
index 0000000..44b0f04
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/ProgressBar.md
@@ -0,0 +1,65 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# ProgressBar
+
+Use a progress bar to visually communicate processes that involve long wait times, such as
+downloading, uploading, submitting, or loading data.
+
+## Examples
+
+### Basic Progress Bar
+
+Use a determinate progress bar when the completion percentage is known.
+
+```tsx
+<ProgressBar aria-label="65% complete" value={65} />
+```
+
+### Indeterminate Progress Bar
+
+Use an indeterminate progress bar when the duration of a process is unknown.
+
+```tsx
+<ProgressBar kind="indeterminate" aria-label="Loading..." />
+```
+
+### Sizes Progress Bar
+
+Match the bar to its surroundings: `small` for inline or table row indicators, `medium` (default) for section-level progress, and `large` for prominent file uploads or page-level loading.
+
+```tsx
+<div className="flex flex-col gap-4">
+ <ProgressBar aria-label="30% complete" value={30} size="small" />
+ <ProgressBar aria-label="55% complete" value={55} size="medium" />
+ <ProgressBar aria-label="80% complete" value={80} size="large" />
+</div>
+```
+
+### Labeled Progress Bar
+
+Pair the progress bar with a visible text label using `aria-labelledby` when users benefit from seeing the operation name and percentage alongside the bar.
+
+```tsx
+<div className="w-full">
+ <div className="mb-1 flex justify-between">
+ <span id="progress-bar-label">Uploading documents</span>
+ <span aria-hidden="true">50%</span>
+ </div>
+ <ProgressBar aria-labelledby="progress-bar-label" value={50} />
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ----------------- | ---------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **aria-label** \* | `string \| never` | - | Defines a string value that labels the current element. |
+| **value** \* | `number \| never` | `0` | A `number` that indicates the current progress based on a percentage to 100. Numbers \>= 100 will show a full bar. i.e., if you wish the progress bar to be halfway filled, the number would be `50`. |
+| aria-labelledby | `never \| string` | - | Identifies the element (or elements) that labels the current element. |
+| kind | `"determinate" \| "indeterminate"` | `"determinate"` | The kind of progress bar. Can be either `determinate` which is static and shows the current progress, or `indeterminate` which is animated and does not show progress. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the progress bar. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/RadioGroup.md b/.agents/skills/kaizen-ui/references/components/RadioGroup.md
new file mode 100644
index 0000000..f4070f6
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/RadioGroup.md
@@ -0,0 +1,222 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# RadioGroup
+
+A set of radio buttons where no more than one of the options can be selected at a time.
+
+**Progressive Enhancement:** Uses native `<input type="radio">` elements which provide
+built-in keyboard navigation (arrow keys), mutual exclusion, and form submission without
+JavaScript.
+
+## Examples
+
+### Basic Radio Group
+
+```tsx
+<RadioGroup
+ name="color"
+ defaultValue="blue"
+ items={[
+ { children: 'Red', value: 'red' },
+ { children: 'Blue', value: 'blue' },
+ { children: 'Green', value: 'green' }
+ ]}
+/>
+```
+
+### With Icons Radio Group
+
+Use icons in `children` to give each option a visual anchor when the label alone is ambiguous.
+
+```tsx
+<RadioGroup
+ name="backup-frequency"
+ defaultValue="weekly"
+ items={[
+ {
+ children: (
+ <>
+ <CheckCircle />
+ Daily
+ </>
+ ),
+ value: 'daily'
+ },
+ {
+ children: (
+ <>
+ <Clock />
+ Weekly
+ </>
+ ),
+ value: 'weekly'
+ },
+ {
+ children: (
+ <>
+ <Calendar />
+ Monthly
+ </>
+ ),
+ value: 'monthly'
+ }
+ ]}
+/>
+```
+
+### Horizontal Radio Group
+
+Use horizontal orientation when the option labels are short and fit on a single row.
+
+```tsx
+<RadioGroup
+ name="size"
+ defaultValue="medium"
+ orientation="horizontal"
+ items={[
+ { children: 'Small', value: 'small' },
+ { children: 'Medium', value: 'medium' },
+ { children: 'Large', value: 'large' }
+ ]}
+/>
+```
+
+### With Danger Item Radio Group
+
+Use the `danger` flag on an item to warn users about a destructive or irreversible choice.
+
+```tsx
+<RadioGroup
+ name="action"
+ defaultValue="keep"
+ items={[
+ { children: 'Keep data', value: 'keep' },
+ { children: 'Archive data', value: 'archive' },
+ { children: 'Delete permanently', value: 'delete', danger: true }
+ ]}
+/>
+```
+
+### Error Radio Group
+
+Use the group-level `error` prop to surface form validation failures across every item — pair with a `FormField` to render the error message.
+
+```tsx
+<RadioGroup
+ name="payment-method"
+ error
+ items={[
+ { children: 'Credit Card', value: 'credit-card' },
+ { children: 'Debit Card', value: 'debit-card' },
+ { children: 'PayPal', value: 'paypal' }
+ ]}
+/>
+```
+
+### With Disabled Item Radio Group
+
+Disable individual items with the per-item `disabled` flag when only some options are unavailable in the current context.
+
+```tsx
+<RadioGroup
+ name="plan"
+ defaultValue="basic"
+ items={[
+ { children: 'Basic', value: 'basic' },
+ { children: 'Pro', value: 'pro' },
+ { children: 'Enterprise', value: 'enterprise', disabled: true }
+ ]}
+/>
+```
+
+### Disabled Radio Group
+
+Use when the selection is locked by external conditions and cannot be changed.
+
+```tsx
+<RadioGroup
+ name="locked"
+ defaultValue="on"
+ disabled
+ items={[
+ { children: 'On', value: 'on' },
+ { children: 'Off', value: 'off' }
+ ]}
+/>
+```
+
+### Label Start Radio Group
+
+Use start label placement when end-aligning radio indicators improves visual scanning.
+
+```tsx
+<RadioGroup
+ name="align"
+ defaultValue="left"
+ labelSide="start"
+ items={[
+ { children: 'Left', value: 'left' },
+ { children: 'Center', value: 'center' },
+ { children: 'Right', value: 'right' }
+ ]}
+/>
+```
+
+### Hidden Indicator Radio Group
+
+Use hidden indicators with card-style items when the selection state is communicated by the card styling.
+
+```tsx
+<RadioGroup
+ name="plan-tier"
+ defaultValue="pro"
+ showIndicator={false}
+ items={[
+ { children: 'Free', value: 'free' },
+ { children: 'Pro', value: 'pro' },
+ { children: 'Enterprise', value: 'enterprise' }
+ ]}
+/>
+```
+
+### Composed
+
+Use the composed primitives when you need full control over item layout or custom content around each radio input.
+
+```tsx
+<RadioGroupRoot name="gpu" defaultValue="4090" orientation="horizontal">
+ <RadioGroupItem>
+ <RadioGroupInput value="4090" />
+ RTX 4090
+ </RadioGroupItem>
+ <RadioGroupItem>
+ <RadioGroupInput value="4080" />
+ RTX 4080
+ </RadioGroupItem>
+ <RadioGroupItem>
+ <RadioGroupInput value="3090" />
+ RTX 3090
+ </RadioGroupItem>
+</RadioGroupRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **items** \* | `Pick<RadioGroupInputProps, "disabled" \| "value" \| "danger" \| "required"> & { children: React.ReactNode; attributes?: { RadioGroupItem?: NativeElementAttributes<"label", React.ForwardRefExoticComponent<Omit<RadioGroupItemProps, "ref"> & React.RefAttributes<HTMLLabelElement>>>; RadioGroupInput?: NativeElementAttributes<"input", React.ForwardRefExoticComponent<Omit<RadioGroupInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>>; }; }[]` | - | The items to render in the radio group. |
+| defaultValue | `string` | - | The value of the radio group when it is initially rendered. Use when you do not need to control the value of the radio group. |
+| disabled | `boolean` | - | If true, the radio group will be disabled. |
+| error | `boolean` | - | If true, the radio group will show an error state |
+| labelSide | `"start" \| "end"` | `"end"` | Which side of the radio input the label renders on. |
+| name | `string` | - | Shared HTML `name` for all radios in the group. When omitted, uses `name` from a wrapping `FormField` when present. |
+| onValueChange | `(value: string) => void` | - | Event handler called when the value of the radio group changes. |
+| orientation | `"horizontal" \| "vertical"` | `"vertical"` | The orientation of the radio group. Determines the layout of the radio items. |
+| required | `boolean` | - | When true, indicates that the user must check a radio item before the owning form can be submitted. |
+| showIndicator | `boolean` | `true` | Whether to show the circular radio indicator on each item. When `false`, inputs stay in the DOM for accessibility and forms but are visually hidden—pair with card styling on items. |
+| value | `string` | - | The controlled value of the radio group. Must be used in conjunction with `onValueChange`. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/RangeSlider.md b/.agents/skills/kaizen-ui/references/components/RangeSlider.md
new file mode 100644
index 0000000..fc7d710
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/RangeSlider.md
@@ -0,0 +1,166 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# RangeSlider
+
+Also known as: Range Input, Input Range
+
+A range slider component allows users to select a range of values (two thumbs).
+
+Range sliders reflect a range of values along a bar, from which users may select
+a range between two values. They are ideal for filtering by price ranges,
+selecting time windows, or any scenario requiring a min/max selection.
+
+## Examples
+
+### Basic Range Slider
+
+```tsx
+<RangeSlider defaultValue={[25, 75]} aria-label="Price range" />
+```
+
+### With Step Marks Range Slider
+
+Use step marks to show discrete positions and help users pick precise range boundaries.
+
+```tsx
+<RangeSlider defaultValue={[20, 80]} step={10} stepPosition="end" aria-label="Budget range" />
+```
+
+### With Formatted Steps Range Slider
+
+Use stepFormatFn to render step labels in a domain-specific format like currency, percentages, or units.
+
+```tsx
+<RangeSlider
+ defaultValue={[200, 800]}
+ min={0}
+ max={1000}
+ step={100}
+ stepPosition="end"
+ stepFormatFn={value => `$${value}`}
+ aria-label="Price range"
+/>
+```
+
+### With Custom Steps Range Slider
+
+Use customSteps when the meaningful values are non-uniform, like pricing tiers or named breakpoints.
+
+```tsx
+<RangeSlider
+ defaultValue={[100, 400]}
+ min={0}
+ max={500}
+ step={50}
+ stepPosition="end"
+ customSteps={[0, 100, 250, 500]}
+ aria-label="Pricing tier range"
+/>
+```
+
+### Custom Range Range Slider
+
+Use custom min/max/step when the default 0–100 range does not match the domain.
+
+```tsx
+<RangeSlider
+ defaultValue={[200, 800]}
+ min={0}
+ max={1000}
+ step={100}
+ stepPosition="end"
+ aria-label="Price filter"
+/>
+```
+
+### With Min Distance Range Slider
+
+Use minStepsBetweenThumbs to enforce a minimum gap between the two thumbs, preventing collapsed selections.
+
+```tsx
+<RangeSlider
+ defaultValue={[20, 80]}
+ step={5}
+ stepPosition="end"
+ minStepsBetweenThumbs={4}
+ aria-label="Date range"
+/>
+```
+
+### Disabled Range Slider
+
+Use when the range selection is locked and cannot be changed.
+
+```tsx
+<RangeSlider defaultValue={[30, 70]} disabled aria-label="Locked range" />
+```
+
+### Vertical Range Slider
+
+Use vertical orientation for controls like equalizer bands or vertical filtering.
+
+```tsx
+<RangeSlider
+ defaultValue={[20, 60]}
+ orientation="vertical"
+ stepPosition="start"
+ step={20}
+ aria-label="Level range"
+/>
+```
+
+### With Form Name Range Slider
+
+Set name to submit the range as two repeated form fields, supporting both hydrated and no-JS form submissions via the native fallback inputs.
+
+```tsx
+<RangeSlider
+ name="priceRange"
+ defaultValue={[100, 300]}
+ min={0}
+ max={500}
+ step={25}
+ stepPosition="end"
+ aria-label="Price range"
+/>
+```
+
+### Composed
+
+Use the composed primitives when you need full control over track, range, thumb, and step label layout.
+
+```tsx
+<RangeSliderRoot defaultValue={[25, 75]} min={0} max={100} step={25} aria-label="Custom range">
+ <RangeSliderTrack>
+ <RangeSliderRange />
+ </RangeSliderTrack>
+ <RangeSliderThumb aria-label="Minimum" />
+ <RangeSliderThumb aria-label="Maximum" />
+ <RangeSliderSteps position="end" />
+</RangeSliderRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------------- | ----------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| customSteps | `number[]` | - | Custom array of step values to display. When provided, overrides both step and stepInterval. |
+| defaultValue | `[number, number]` | - | The value of the slider when initially rendered. Use when you do not need to control the state of the slider. |
+| disabled | `boolean` | `false` | When `true`, prevents the user from interacting with the slider. |
+| form | `string` | - | The ID of the form that the slider belongs to. If omitted, the slider will be associated with a parent form if one exists. |
+| max | `number` | `100` | The maximum value for the range. |
+| min | `number` | `0` | The minimum value for the range. |
+| minStepsBetweenThumbs | `number` | - | The minimum permitted steps between multiple thumbs. |
+| name | `string` | - | The name of the slider. Submitted with its owning form as part of a name/value pair. |
+| onValueChange | `(value: [number, number]) => void` | - | Event handler called when the value changes. |
+| onValueCommit | `(value: [number, number]) => void` | - | Event handler called when the value changes at the end of an interaction. Useful when you only need to capture a final value e.g. to update a backend service. |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider. |
+| step | `number` | `1` | The stepping interval. |
+| stepFormatFn | `(value: number) => string` | - | Callback function to format the step value before displaying it. |
+| stepInterval | `number` | - | The interval at which to display step markers. When not provided, uses the slider's step value. |
+| stepPosition | `"start" \| "end"` | `undefined` | The position of the step markers. |
+| value | `[number, number]` | - | The controlled value of the slider. Must be used in conjunction with `onValueChange`. |
diff --git a/.agents/skills/kaizen-ui/references/components/SegmentedControl.md b/.agents/skills/kaizen-ui/references/components/SegmentedControl.md
new file mode 100644
index 0000000..1a1f14f
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/SegmentedControl.md
@@ -0,0 +1,146 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# SegmentedControl
+
+A segmented control allows users to select one option in a set of related options that takes
+effect on selection. This component is built as a radio group, and uses `name` to group the radio
+buttons together.
+
+## Examples
+
+### Basic Segmented Control
+
+```tsx
+<SegmentedControl items={['Apple', 'Banana', 'Cherry']} />
+```
+
+### Default Value Segmented Control
+
+Use when a specific option should be pre-selected on initial render.
+
+```tsx
+<SegmentedControl items={['Apple', 'Banana', 'Cherry']} defaultValue="Banana" />
+```
+
+### Object Items Segmented Control
+
+Use object items when the display label differs from the underlying value, or when you need to forward extra props (like `aria-label` or `disabled`) to individual radio inputs.
+
+```tsx
+<SegmentedControl
+ items={[
+ { value: 'grid', children: 'Grid' },
+ { value: 'list', children: 'List' },
+ { value: 'table', children: 'Table' }
+ ]}
+/>
+```
+
+### Size Segmented Control
+
+Match the control size to surrounding inputs. Defaults to `medium`; pick `tiny` or `small` for dense toolbars and `large` for prominent actions.
+
+```tsx
+<Flex gap="2" direction="col" align="start">
+ <SegmentedControl items={['Day', 'Week', 'Month']} size="tiny" />
+ <SegmentedControl items={['Day', 'Week', 'Month']} size="small" />
+ <SegmentedControl items={['Day', 'Week', 'Month']} size="medium" />
+ <SegmentedControl items={['Day', 'Week', 'Month']} size="large" />
+</Flex>
+```
+
+### With Icons Segmented Control
+
+Use icon-only options for compact toolbars. Always supply `aria-label` on each item so screen-reader users get an accessible name.
+
+```tsx
+<SegmentedControl
+ defaultValue="list"
+ items={[
+ {
+ value: 'list',
+ 'aria-label': 'List view',
+ children: <Menu />
+ },
+ {
+ value: 'calendar',
+ 'aria-label': 'Calendar view',
+ children: <Calendar />
+ },
+ {
+ value: 'docs',
+ 'aria-label': 'Document view',
+ children: <Document />
+ }
+ ]}
+/>
+```
+
+### Full Width Segmented Control
+
+Use when the control should stretch to fill its container, such as in a toolbar or settings panel.
+
+```tsx
+<SegmentedControl className="w-full" items={['Day', 'Week', 'Month']} />
+```
+
+### In Form Segmented Control
+
+SegmentedControl renders a native radio group, so the selected option is submitted with the surrounding form under the `name` prop — no extra glue code required.
+
+```tsx
+<form onSubmit={handleSubmit}>
+ <SegmentedControl name="view" items={['Grid', 'List', 'Table']} />
+</form>
+```
+
+### Controlled Segmented Control
+
+Reach for controlled mode when selection state lives outside the component — e.g. when syncing with URL params, a form library, or driving other UI from the active segment.
+
+```tsx
+;() => {
+ const [selected, setSelected] = useState('Banana')
+ return (
+ <SegmentedControl
+ items={['Apple', 'Banana', 'Cherry']}
+ value={selected}
+ onValueChange={setSelected}
+ />
+ )
+}
+```
+
+### Composed
+
+Use the composed primitives when you need full control over individual items, such as wrapping each input in custom layout or interleaving non-radio content.
+
+```tsx
+<SegmentedControlRoot>
+ <SegmentedControlItem>
+ <SegmentedControlInput defaultChecked value="grid" />
+ Grid
+ </SegmentedControlItem>
+ <SegmentedControlItem>
+ <SegmentedControlInput value="list" />
+ List
+ </SegmentedControlItem>
+</SegmentedControlRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `string \| ({ value: string; ref: React.RefObject<HTMLInputElement> \| ((instance: HTMLInputElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })); key: string \| number \| bigint; accept: string; alt: string; autoComplete: "" \| "off" \| "on" \| string & {} \| "tel" \| "email" \| "name" \| "additional-name" \| "address-level1" \| "address-level2" \| "address-level3" \| "address-level4" \| "address-line1" \| "address-line2" \| "address-line3" \| "bday-day" \| "bday-month" \| "bday-year" \| "cc-csc" \| "cc-exp" \| "cc-exp-month" \| "cc-exp-year" \| "cc-family-name" \| "cc-given-name" \| "cc-name" \| "cc-number" \| "cc-type" \| "country" \| "country-name" \| "current-password" \| "family-name" \| "given-name" \| "honorific-prefix" \| "honorific-suffix" \| "new-password" \| "one-time-code" \| "organization" \| "postal-code" \| "street-address" \| "transaction-amount" \| "transaction-currency" \| "username" \| "tel-area-code" \| "tel-country-code" \| "tel-extension" \| "tel-local" \| "tel-local-prefix" \| "tel-local-suffix" \| "tel-national" \| "home tel" \| "home email" \| "home tel-area-code" \| "home tel-country-code" \| "home tel-extension" \| "home tel-local" \| "home tel-local-prefix" \| "home tel-local-suffix" \| "home tel-national" \| "mobile tel" \| "mobile email" \| "mobile tel-area-code" \| "mobile tel-country-code" \| "mobile tel-extension" \| "mobile tel-local" \| "mobile tel-local-prefix" \| "mobile tel-local-suffix" \| "mobile tel-national" \| "work tel" \| "work email" \| "work tel-area-code" \| "work tel-country-code" \| "work tel-extension" \| "work tel-local" \| "work tel-local-prefix" \| "work tel-local-suffix" \| "work tel-national" \| "name webauthn" \| "additional-name webauthn" \| "address-level1 webauthn" \| "address-level2 webauthn" \| "address-level3 webauthn" \| "address-level4 webauthn" \| "address-line1 webauthn" \| "address-line2 webauthn" \| "address-line3 webauthn" \| "bday-day webauthn" \| "bday-month webauthn" \| "bday-year webauthn" \| "cc-csc webauthn" \| "cc-exp webauthn" \| "cc-exp-month webauthn" \| "cc-exp-year webauthn" \| "cc-family-name webauthn" \| "cc-given-name webauthn" \| "cc-name webauthn" \| "cc-number webauthn" \| "cc-type webauthn" \| "country webauthn" \| "country-name webauthn" \| "current-password webauthn" \| "family-name webauthn" \| "given-name webauthn" \| "honorific-prefix webauthn" \| "honorific-suffix webauthn" \| "new-password webauthn" \| "one-time-code webauthn" \| "organization webauthn" \| "postal-code webauthn" \| "street-address webauthn" \| "transaction-amount webauthn" \| "transaction-currency webauthn" \| "username webauthn" \| "tel webauthn" \| "email webauthn" \| "tel-area-code webauthn" \| "tel-country-code webauthn" \| "tel-extension webauthn" \| "tel-local webauthn" \| "tel-local-prefix webauthn" \| "tel-local-suffix webauthn" \| "tel-national webauthn" \| "home tel webauthn" \| "home email webauthn" \| "home tel-area-code webauthn" \| "home tel-country-code webauthn" \| "home tel-extension webauthn" \| "home tel-local webauthn" \| "home tel-local-prefix webauthn" \| "home tel-local-suffix webauthn" \| "home tel-national webauthn" \| "mobile tel webauthn" \| "mobile email webauthn" \| "mobile tel-area-code webauthn" \| "mobile tel-country-code webauthn" \| "mobile tel-extension webauthn" \| "mobile tel-local webauthn" \| "mobile tel-local-prefix webauthn" \| "mobile tel-local-suffix webauthn" \| "mobile tel-national webauthn" \| "work tel webauthn" \| "work email webauthn" \| "work tel-area-code webauthn" \| "work tel-country-code webauthn" \| "work tel-extension webauthn" \| "work tel-local webauthn" \| "work tel-local-prefix webauthn" \| "work tel-local-suffix webauthn" \| "work tel-national webauthn" \| "billing name" \| "billing name webauthn" \| "billing additional-name" \| "billing additional-name webauthn" \| "billing address-level1" \| "billing address-level1 webauthn" \| "billing address-level2" \| "billing address-level2 webauthn" \| "billing address-level3" \| "billing address-level3 webauthn" \| "billing address-level4" \| "billing address-level4 webauthn" \| "billing address-line1" \| "billing address-line1 webauthn" \| "billing address-line2" \| "billing address-line2 webauthn" \| "billing address-line3" \| "billing address-line3 webauthn" \| "billing bday-day" \| "billing bday-day webauthn" \| "billing bday-month" \| "billing bday-month webauthn" \| "billing bday-year" \| "billing bday-year webauthn" \| "billing cc-csc" \| "billing cc-csc webauthn" \| "billing cc-exp" \| "billing cc-exp webauthn" \| "billing cc-exp-month" \| "billing cc-exp-month webauthn" \| "billing cc-exp-year" \| "billing cc-exp-year webauthn" \| "billing cc-family-name" \| "billing cc-family-name webauthn" \| "billing cc-given-name" \| "billing cc-given-name webauthn" \| "billing cc-name" \| "billing cc-name webauthn" \| "billing cc-number" \| "billing cc-number webauthn" \| "billing cc-type" \| "billing cc-type webauthn" \| "billing country" \| "billing country webauthn" \| "billing country-name" \| "billing country-name webauthn" \| "billing current-password" \| "billing current-password webauthn" \| "billing family-name" \| "billing family-name webauthn" \| "billing given-name" \| "billing given-name webauthn" \| "billing honorific-prefix" \| "billing honorific-prefix webauthn" \| "billing honorific-suffix" \| "billing honorific-suffix webauthn" \| "billing new-password" \| "billing new-password webauthn" \| "billing one-time-code" \| "billing one-time-code webauthn" \| "billing organization" \| "billing organization webauthn" \| "billing postal-code" \| "billing postal-code webauthn" \| "billing street-address" \| "billing street-address webauthn" \| "billing transaction-amount" \| "billing transaction-amount webauthn" \| "billing transaction-currency" \| "billing transaction-currency webauthn" \| "billing username" \| "billing username webauthn" \| "billing tel" \| "billing tel webauthn" \| "billing email" \| "billing email webauthn" \| "billing tel-area-code" \| "billing tel-area-code webauthn" \| "billing tel-country-code" \| "billing tel-country-code webauthn" \| "billing tel-extension" \| "billing tel-extension webauthn" \| "billing tel-local" \| "billing tel-local webauthn" \| "billing tel-local-prefix" \| "billing tel-local-prefix webauthn" \| "billing tel-local-suffix" \| "billing tel-local-suffix webauthn" \| "billing tel-national" \| "billing tel-national webauthn" \| "billing home tel" \| "billing home tel webauthn" \| "billing home email" \| "billing home email webauthn" \| "billing home tel-area-code" \| "billing home tel-area-code webauthn" \| "billing home tel-country-code" \| "billing home tel-country-code webauthn" \| "billing home tel-extension" \| "billing home tel-extension webauthn" \| "billing home tel-local" \| "billing home tel-local webauthn" \| "billing home tel-local-prefix" \| "billing home tel-local-prefix webauthn" \| "billing home tel-local-suffix" \| "billing home tel-local-suffix webauthn" \| "billing home tel-national" \| "billing home tel-national webauthn" \| "billing mobile tel" \| "billing mobile tel webauthn" \| "billing mobile email" \| "billing mobile email webauthn" \| "billing mobile tel-area-code" \| "billing mobile tel-area-code webauthn" \| "billing mobile tel-country-code" \| "billing mobile tel-country-code webauthn" \| "billing mobile tel-extension" \| "billing mobile tel-extension webauthn" \| "billing mobile tel-local" \| "billing mobile tel-local webauthn" \| "billing mobile tel-local-prefix" \| "billing mobile tel-local-prefix webauthn" \| "billing mobile tel-local-suffix" \| "billing mobile tel-local-suffix webauthn" \| "billing mobile tel-national" \| "billing mobile tel-national webauthn" \| "billing work tel" \| "billing work tel webauthn" \| "billing work email" \| "billing work email webauthn" \| "billing work tel-area-code" \| "billing work tel-area-code webauthn" \| "billing work tel-country-code" \| "billing work tel-country-code webauthn" \| "billing work tel-extension" \| "billing work tel-extension webauthn" \| "billing work tel-local" \| "billing work tel-local webauthn" \| "billing work tel-local-prefix" \| "billing work tel-local-prefix webauthn" \| "billing work tel-local-suffix" \| "billing work tel-local-suffix webauthn" \| "billing work tel-national" \| "billing work tel-national webauthn" \| "shipping name" \| "shipping name webauthn" \| "shipping additional-name" \| "shipping additional-name webauthn" \| "shipping address-level1" \| "shipping address-level1 webauthn" \| "shipping address-level2" \| "shipping address-level2 webauthn" \| "shipping address-level3" \| "shipping address-level3 webauthn" \| "shipping address-level4" \| "shipping address-level4 webauthn" \| "shipping address-line1" \| "shipping address-line1 webauthn" \| "shipping address-line2" \| "shipping address-line2 webauthn" \| "shipping address-line3" \| "shipping address-line3 webauthn" \| "shipping bday-day" \| "shipping bday-day webauthn" \| "shipping bday-month" \| "shipping bday-month webauthn" \| "shipping bday-year" \| "shipping bday-year webauthn" \| "shipping cc-csc" \| "shipping cc-csc webauthn" \| "shipping cc-exp" \| "shipping cc-exp webauthn" \| "shipping cc-exp-month" \| "shipping cc-exp-month webauthn" \| "shipping cc-exp-year" \| "shipping cc-exp-year webauthn" \| "shipping cc-family-name" \| "shipping cc-family-name webauthn" \| "shipping cc-given-name" \| "shipping cc-given-name webauthn" \| "shipping cc-name" \| "shipping cc-name webauthn" \| "shipping cc-number" \| "shipping cc-number webauthn" \| "shipping cc-type" \| "shipping cc-type webauthn" \| "shipping country" \| "shipping country webauthn" \| "shipping country-name" \| "shipping country-name webauthn" \| "shipping current-password" \| "shipping current-password webauthn" \| "shipping family-name" \| "shipping family-name webauthn" \| "shipping given-name" \| "shipping given-name webauthn" \| "shipping honorific-prefix" \| "shipping honorific-prefix webauthn" \| "shipping honorific-suffix" \| "shipping honorific-suffix webauthn" \| "shipping new-password" \| "shipping new-password webauthn" \| "shipping one-time-code" \| "shipping one-time-code webauthn" \| "shipping organization" \| "shipping organization webauthn" \| "shipping postal-code" \| "shipping postal-code webauthn" \| "shipping street-address" \| "shipping street-address webauthn" \| "shipping transaction-amount" \| "shipping transaction-amount webauthn" \| "shipping transaction-currency" \| "shipping transaction-currency webauthn" \| "shipping username" \| "shipping username webauthn" \| "shipping tel" \| "shipping tel webauthn" \| "shipping email" \| "shipping email webauthn" \| "shipping tel-area-code" \| "shipping tel-area-code webauthn" \| "shipping tel-country-code" \| "shipping tel-country-code webauthn" \| "shipping tel-extension" \| "shipping tel-extension webauthn" \| "shipping tel-local" \| "shipping tel-local webauthn" \| "shipping tel-local-prefix" \| "shipping tel-local-prefix webauthn" \| "shipping tel-local-suffix" \| "shipping tel-local-suffix webauthn" \| "shipping tel-national" \| "shipping tel-national webauthn" \| "shipping home tel" \| "shipping home tel webauthn" \| "shipping home email" \| "shipping home email webauthn" \| "shipping home tel-area-code" \| "shipping home tel-area-code webauthn" \| "shipping home tel-country-code" \| "shipping home tel-country-code webauthn" \| "shipping home tel-extension" \| "shipping home tel-extension webauthn" \| "shipping home tel-local" \| "shipping home tel-local webauthn" \| "shipping home tel-local-prefix" \| "shipping home tel-local-prefix webauthn" \| "shipping home tel-local-suffix" \| "shipping home tel-local-suffix webauthn" \| "shipping home tel-national" \| "shipping home tel-national webauthn" \| "shipping mobile tel" \| "shipping mobile tel webauthn" \| "shipping mobile email" \| "shipping mobile email webauthn" \| "shipping mobile tel-area-code" \| "shipping mobile tel-area-code webauthn" \| "shipping mobile tel-country-code" \| "shipping mobile tel-country-code webauthn" \| "shipping mobile tel-extension" \| "shipping mobile tel-extension webauthn" \| "shipping mobile tel-local" \| "shipping mobile tel-local webauthn" \| "shipping mobile tel-local-prefix" \| "shipping mobile tel-local-prefix webauthn" \| "shipping mobile tel-local-suffix" \| "shipping mobile tel-local-suffix webauthn" \| "shipping mobile tel-national" \| "shipping mobile tel-national webauthn" \| "shipping work tel" \| "shipping work tel webauthn" \| "shipping work email" \| "shipping work email webauthn" \| "shipping work tel-area-code" \| "shipping work tel-area-code webauthn" \| "shipping work tel-country-code" \| "shipping work tel-country-code webauthn" \| "shipping work tel-extension" \| "shipping work tel-extension webauthn" \| "shipping work tel-local" \| "shipping work tel-local webauthn" \| "shipping work tel-local-prefix" \| "shipping work tel-local-prefix webauthn" \| "shipping work tel-local-suffix" \| "shipping work tel-local-suffix webauthn" \| "shipping work tel-national" \| "shipping work tel-national webauthn" \| `section-${string} name` \| `section-${string} name webauthn`\|`section-${string} additional-name` \| `section-${string} additional-name webauthn`\|`section-${string} address-level1` \| `section-${string} address-level1 webauthn`\|`section-${string} address-level2` \| `section-${string} address-level2 webauthn`\|`section-${string} address-level3` \| `section-${string} address-level3 webauthn`\|`section-${string} address-level4` \| `section-${string} address-level4 webauthn`\|`section-${string} address-line1` \| `section-${string} address-line1 webauthn`\|`section-${string} address-line2` \| `section-${string} address-line2 webauthn`\|`section-${string} address-line3` \| `section-${string} address-line3 webauthn`\|`section-${string} bday-day` \| `section-${string} bday-day webauthn`\|`section-${string} bday-month` \| `section-${string} bday-month webauthn`\|`section-${string} bday-year` \| `section-${string} bday-year webauthn`\|`section-${string} cc-csc` \| `section-${string} cc-csc webauthn`\|`section-${string} cc-exp` \| `section-${string} cc-exp webauthn`\|`section-${string} cc-exp-month` \| `section-${string} cc-exp-month webauthn`\|`section-${string} cc-exp-year` \| `section-${string} cc-exp-year webauthn`\|`section-${string} cc-family-name` \| `section-${string} cc-family-name webauthn`\|`section-${string} cc-given-name` \| `section-${string} cc-given-name webauthn`\|`section-${string} cc-name` \| `section-${string} cc-name webauthn`\|`section-${string} cc-number` \| `section-${string} cc-number webauthn`\|`section-${string} cc-type` \| `section-${string} cc-type webauthn`\|`section-${string} country` \| `section-${string} country webauthn`\|`section-${string} country-name` \| `section-${string} country-name webauthn`\|`section-${string} current-password` \| `section-${string} current-password webauthn`\|`section-${string} family-name` \| `section-${string} family-name webauthn`\|`section-${string} given-name` \| `section-${string} given-name webauthn`\|`section-${string} honorific-prefix` \| `section-${string} honorific-prefix webauthn`\|`section-${string} honorific-suffix` \| `section-${string} honorific-suffix webauthn`\|`section-${string} new-password` \| `section-${string} new-password webauthn`\|`section-${string} one-time-code` \| `section-${string} one-time-code webauthn`\|`section-${string} organization` \| `section-${string} organization webauthn`\|`section-${string} postal-code` \| `section-${string} postal-code webauthn`\|`section-${string} street-address` \| `section-${string} street-address webauthn`\|`section-${string} transaction-amount` \| `section-${string} transaction-amount webauthn`\|`section-${string} transaction-currency` \| `section-${string} transaction-currency webauthn`\|`section-${string} username` \| `section-${string} username webauthn`\|`section-${string} tel` \| `section-${string} tel webauthn`\|`section-${string} email` \| `section-${string} email webauthn`\|`section-${string} tel-area-code` \| `section-${string} tel-area-code webauthn`\|`section-${string} tel-country-code` \| `section-${string} tel-country-code webauthn`\|`section-${string} tel-extension` \| `section-${string} tel-extension webauthn`\|`section-${string} tel-local` \| `section-${string} tel-local webauthn`\|`section-${string} tel-local-prefix` \| `section-${string} tel-local-prefix webauthn`\|`section-${string} tel-local-suffix` \| `section-${string} tel-local-suffix webauthn`\|`section-${string} tel-national` \| `section-${string} tel-national webauthn`\|`section-${string} home tel` \| `section-${string} home tel webauthn`\|`section-${string} home email` \| `section-${string} home email webauthn`\|`section-${string} home tel-area-code` \| `section-${string} home tel-area-code webauthn`\|`section-${string} home tel-country-code` \| `section-${string} home tel-country-code webauthn`\|`section-${string} home tel-extension` \| `section-${string} home tel-extension webauthn`\|`section-${string} home tel-local` \| `section-${string} home tel-local webauthn`\|`section-${string} home tel-local-prefix` \| `section-${string} home tel-local-prefix webauthn`\|`section-${string} home tel-local-suffix` \| `section-${string} home tel-local-suffix webauthn`\|`section-${string} home tel-national` \| `section-${string} home tel-national webauthn`\|`section-${string} mobile tel` \| `section-${string} mobile tel webauthn`\|`section-${string} mobile email` \| `section-${string} mobile email webauthn`\|`section-${string} mobile tel-area-code` \| `section-${string} mobile tel-area-code webauthn`\|`section-${string} mobile tel-country-code` \| `section-${string} mobile tel-country-code webauthn`\|`section-${string} mobile tel-extension` \| `section-${string} mobile tel-extension webauthn`\|`section-${string} mobile tel-local` \| `section-${string} mobile tel-local webauthn`\|`section-${string} mobile tel-local-prefix` \| `section-${string} mobile tel-local-prefix webauthn`\|`section-${string} mobile tel-local-suffix` \| `section-${string} mobile tel-local-suffix webauthn`\|`section-${string} mobile tel-national` \| `section-${string} mobile tel-national webauthn`\|`section-${string} work tel` \| `section-${string} work tel webauthn`\|`section-${string} work email` \| `section-${string} work email webauthn`\|`section-${string} work tel-area-code` \| `section-${string} work tel-area-code webauthn`\|`section-${string} work tel-country-code` \| `section-${string} work tel-country-code webauthn`\|`section-${string} work tel-extension` \| `section-${string} work tel-extension webauthn`\|`section-${string} work tel-local` \| `section-${string} work tel-local webauthn`\|`section-${string} work tel-local-prefix` \| `section-${string} work tel-local-prefix webauthn`\|`section-${string} work tel-local-suffix` \| `section-${string} work tel-local-suffix webauthn`\|`section-${string} work tel-national` \| `section-${string} work tel-national webauthn`\|`section-${string} billing name` \| `section-${string} billing name webauthn`\|`section-${string} billing additional-name` \| `section-${string} billing additional-name webauthn`\|`section-${string} billing address-level1` \| `section-${string} billing address-level1 webauthn`\|`section-${string} billing address-level2` \| `section-${string} billing address-level2 webauthn`\|`section-${string} billing address-level3` \| `section-${string} billing address-level3 webauthn`\|`section-${string} billing address-level4` \| `section-${string} billing address-level4 webauthn`\|`section-${string} billing address-line1` \| `section-${string} billing address-line1 webauthn`\|`section-${string} billing address-line2` \| `section-${string} billing address-line2 webauthn`\|`section-${string} billing address-line3` \| `section-${string} billing address-line3 webauthn`\|`section-${string} billing bday-day` \| `section-${string} billing bday-day webauthn`\|`section-${string} billing bday-month` \| `section-${string} billing bday-month webauthn`\|`section-${string} billing bday-year` \| `section-${string} billing bday-year webauthn`\|`section-${string} billing cc-csc` \| `section-${string} billing cc-csc webauthn`\|`section-${string} billing cc-exp` \| `section-${string} billing cc-exp webauthn`\|`section-${string} billing cc-exp-month` \| `section-${string} billing cc-exp-month webauthn`\|`section-${string} billing cc-exp-year` \| `section-${string} billing cc-exp-year webauthn`\|`section-${string} billing cc-family-name` \| `section-${string} billing cc-family-name webauthn`\|`section-${string} billing cc-given-name` \| `section-${string} billing cc-given-name webauthn`\|`section-${string} billing cc-name` \| `section-${string} billing cc-name webauthn`\|`section-${string} billing cc-number` \| `section-${string} billing cc-number webauthn`\|`section-${string} billing cc-type` \| `section-${string} billing cc-type webauthn`\|`section-${string} billing country` \| `section-${string} billing country webauthn`\|`section-${string} billing country-name` \| `section-${string} billing country-name webauthn`\|`section-${string} billing current-password` \| `section-${string} billing current-password webauthn`\|`section-${string} billing family-name` \| `section-${string} billing family-name webauthn`\|`section-${string} billing given-name` \| `section-${string} billing given-name webauthn`\|`section-${string} billing honorific-prefix` \| `section-${string} billing honorific-prefix webauthn`\|`section-${string} billing honorific-suffix` \| `section-${string} billing honorific-suffix webauthn`\|`section-${string} billing new-password` \| `section-${string} billing new-password webauthn`\|`section-${string} billing one-time-code` \| `section-${string} billing one-time-code webauthn`\|`section-${string} billing organization` \| `section-${string} billing organization webauthn`\|`section-${string} billing postal-code` \| `section-${string} billing postal-code webauthn`\|`section-${string} billing street-address` \| `section-${string} billing street-address webauthn`\|`section-${string} billing transaction-amount` \| `section-${string} billing transaction-amount webauthn`\|`section-${string} billing transaction-currency` \| `section-${string} billing transaction-currency webauthn`\|`section-${string} billing username` \| `section-${string} billing username webauthn`\|`section-${string} billing tel` \| `section-${string} billing tel webauthn`\|`section-${string} billing email` \| `section-${string} billing email webauthn`\|`section-${string} billing tel-area-code` \| `section-${string} billing tel-area-code webauthn`\|`section-${string} billing tel-country-code` \| `section-${string} billing tel-country-code webauthn`\|`section-${string} billing tel-extension` \| `section-${string} billing tel-extension webauthn`\|`section-${string} billing tel-local` \| `section-${string} billing tel-local webauthn`\|`section-${string} billing tel-local-prefix` \| `section-${string} billing tel-local-prefix webauthn`\|`section-${string} billing tel-local-suffix` \| `section-${string} billing tel-local-suffix webauthn`\|`section-${string} billing tel-national` \| `section-${string} billing tel-national webauthn`\|`section-${string} billing home tel` \| `section-${string} billing home tel webauthn`\|`section-${string} billing home email` \| `section-${string} billing home email webauthn`\|`section-${string} billing home tel-area-code` \| `section-${string} billing home tel-area-code webauthn`\|`section-${string} billing home tel-country-code` \| `section-${string} billing home tel-country-code webauthn`\|`section-${string} billing home tel-extension` \| `section-${string} billing home tel-extension webauthn`\|`section-${string} billing home tel-local` \| `section-${string} billing home tel-local webauthn`\|`section-${string} billing home tel-local-prefix` \| `section-${string} billing home tel-local-prefix webauthn`\|`section-${string} billing home tel-local-suffix` \| `section-${string} billing home tel-local-suffix webauthn`\|`section-${string} billing home tel-national` \| `section-${string} billing home tel-national webauthn`\|`section-${string} billing mobile tel` \| `section-${string} billing mobile tel webauthn`\|`section-${string} billing mobile email` \| `section-${string} billing mobile email webauthn`\|`section-${string} billing mobile tel-area-code` \| `section-${string} billing mobile tel-area-code webauthn`\|`section-${string} billing mobile tel-country-code` \| `section-${string} billing mobile tel-country-code webauthn`\|`section-${string} billing mobile tel-extension` \| `section-${string} billing mobile tel-extension webauthn`\|`section-${string} billing mobile tel-local` \| `section-${string} billing mobile tel-local webauthn`\|`section-${string} billing mobile tel-local-prefix` \| `section-${string} billing mobile tel-local-prefix webauthn`\|`section-${string} billing mobile tel-local-suffix` \| `section-${string} billing mobile tel-local-suffix webauthn`\|`section-${string} billing mobile tel-national` \| `section-${string} billing mobile tel-national webauthn`\|`section-${string} billing work tel` \| `section-${string} billing work tel webauthn`\|`section-${string} billing work email` \| `section-${string} billing work email webauthn`\|`section-${string} billing work tel-area-code` \| `section-${string} billing work tel-area-code webauthn`\|`section-${string} billing work tel-country-code` \| `section-${string} billing work tel-country-code webauthn`\|`section-${string} billing work tel-extension` \| `section-${string} billing work tel-extension webauthn`\|`section-${string} billing work tel-local` \| `section-${string} billing work tel-local webauthn`\|`section-${string} billing work tel-local-prefix` \| `section-${string} billing work tel-local-prefix webauthn`\|`section-${string} billing work tel-local-suffix` \| `section-${string} billing work tel-local-suffix webauthn`\|`section-${string} billing work tel-national` \| `section-${string} billing work tel-national webauthn`\|`section-${string} shipping name` \| `section-${string} shipping name webauthn`\|`section-${string} shipping additional-name` \| `section-${string} shipping additional-name webauthn`\|`section-${string} shipping address-level1` \| `section-${string} shipping address-level1 webauthn`\|`section-${string} shipping address-level2` \| `section-${string} shipping address-level2 webauthn`\|`section-${string} shipping address-level3` \| `section-${string} shipping address-level3 webauthn`\|`section-${string} shipping address-level4` \| `section-${string} shipping address-level4 webauthn`\|`section-${string} shipping address-line1` \| `section-${string} shipping address-line1 webauthn`\|`section-${string} shipping address-line2` \| `section-${string} shipping address-line2 webauthn`\|`section-${string} shipping address-line3` \| `section-${string} shipping address-line3 webauthn`\|`section-${string} shipping bday-day` \| `section-${string} shipping bday-day webauthn`\|`section-${string} shipping bday-month` \| `section-${string} shipping bday-month webauthn`\|`section-${string} shipping bday-year` \| `section-${string} shipping bday-year webauthn`\|`section-${string} shipping cc-csc` \| `section-${string} shipping cc-csc webauthn`\|`section-${string} shipping cc-exp` \| `section-${string} shipping cc-exp webauthn`\|`section-${string} shipping cc-exp-month` \| `section-${string} shipping cc-exp-month webauthn`\|`section-${string} shipping cc-exp-year` \| `section-${string} shipping cc-exp-year webauthn`\|`section-${string} shipping cc-family-name` \| `section-${string} shipping cc-family-name webauthn`\|`section-${string} shipping cc-given-name` \| `section-${string} shipping cc-given-name webauthn`\|`section-${string} shipping cc-name` \| `section-${string} shipping cc-name webauthn`\|`section-${string} shipping cc-number` \| `section-${string} shipping cc-number webauthn`\|`section-${string} shipping cc-type` \| `section-${string} shipping cc-type webauthn`\|`section-${string} shipping country` \| `section-${string} shipping country webauthn`\|`section-${string} shipping country-name` \| `section-${string} shipping country-name webauthn`\|`section-${string} shipping current-password` \| `section-${string} shipping current-password webauthn`\|`section-${string} shipping family-name` \| `section-${string} shipping family-name webauthn`\|`section-${string} shipping given-name` \| `section-${string} shipping given-name webauthn`\|`section-${string} shipping honorific-prefix` \| `section-${string} shipping honorific-prefix webauthn`\|`section-${string} shipping honorific-suffix` \| `section-${string} shipping honorific-suffix webauthn`\|`section-${string} shipping new-password` \| `section-${string} shipping new-password webauthn`\|`section-${string} shipping one-time-code` \| `section-${string} shipping one-time-code webauthn`\|`section-${string} shipping organization` \| `section-${string} shipping organization webauthn`\|`section-${string} shipping postal-code` \| `section-${string} shipping postal-code webauthn`\|`section-${string} shipping street-address` \| `section-${string} shipping street-address webauthn`\|`section-${string} shipping transaction-amount` \| `section-${string} shipping transaction-amount webauthn`\|`section-${string} shipping transaction-currency` \| `section-${string} shipping transaction-currency webauthn`\|`section-${string} shipping username` \| `section-${string} shipping username webauthn`\|`section-${string} shipping tel` \| `section-${string} shipping tel webauthn`\|`section-${string} shipping email` \| `section-${string} shipping email webauthn`\|`section-${string} shipping tel-area-code` \| `section-${string} shipping tel-area-code webauthn`\|`section-${string} shipping tel-country-code` \| `section-${string} shipping tel-country-code webauthn`\|`section-${string} shipping tel-extension` \| `section-${string} shipping tel-extension webauthn`\|`section-${string} shipping tel-local` \| `section-${string} shipping tel-local webauthn`\|`section-${string} shipping tel-local-prefix` \| `section-${string} shipping tel-local-prefix webauthn`\|`section-${string} shipping tel-local-suffix` \| `section-${string} shipping tel-local-suffix webauthn`\|`section-${string} shipping tel-national` \| `section-${string} shipping tel-national webauthn`\|`section-${string} shipping home tel` \| `section-${string} shipping home tel webauthn`\|`section-${string} shipping home email` \| `section-${string} shipping home email webauthn`\|`section-${string} shipping home tel-area-code` \| `section-${string} shipping home tel-area-code webauthn`\|`section-${string} shipping home tel-country-code` \| `section-${string} shipping home tel-country-code webauthn`\|`section-${string} shipping home tel-extension` \| `section-${string} shipping home tel-extension webauthn`\|`section-${string} shipping home tel-local` \| `section-${string} shipping home tel-local webauthn`\|`section-${string} shipping home tel-local-prefix` \| `section-${string} shipping home tel-local-prefix webauthn`\|`section-${string} shipping home tel-local-suffix` \| `section-${string} shipping home tel-local-suffix webauthn`\|`section-${string} shipping home tel-national` \| `section-${string} shipping home tel-national webauthn`\|`section-${string} shipping mobile tel` \| `section-${string} shipping mobile tel webauthn`\|`section-${string} shipping mobile email` \| `section-${string} shipping mobile email webauthn`\|`section-${string} shipping mobile tel-area-code` \| `section-${string} shipping mobile tel-area-code webauthn`\|`section-${string} shipping mobile tel-country-code` \| `section-${string} shipping mobile tel-country-code webauthn`\|`section-${string} shipping mobile tel-extension` \| `section-${string} shipping mobile tel-extension webauthn`\|`section-${string} shipping mobile tel-local` \| `section-${string} shipping mobile tel-local webauthn`\|`section-${string} shipping mobile tel-local-prefix` \| `section-${string} shipping mobile tel-local-prefix webauthn`\|`section-${string} shipping mobile tel-local-suffix` \| `section-${string} shipping mobile tel-local-suffix webauthn`\|`section-${string} shipping mobile tel-national` \| `section-${string} shipping mobile tel-national webauthn`\|`section-${string} shipping work tel` \| `section-${string} shipping work tel webauthn`\|`section-${string} shipping work email` \| `section-${string} shipping work email webauthn`\|`section-${string} shipping work tel-area-code` \| `section-${string} shipping work tel-area-code webauthn`\|`section-${string} shipping work tel-country-code` \| `section-${string} shipping work tel-country-code webauthn`\|`section-${string} shipping work tel-extension` \| `section-${string} shipping work tel-extension webauthn`\|`section-${string} shipping work tel-local` \| `section-${string} shipping work tel-local webauthn`\|`section-${string} shipping work tel-local-prefix` \| `section-${string} shipping work tel-local-prefix webauthn`\|`section-${string} shipping work tel-local-suffix` \| `section-${string} shipping work tel-local-suffix webauthn`\|`section-${string} shipping work tel-national` \| `section-${string} shipping work tel-national webauthn`; capture: false \| true \| "user" \| "environment"; checked: boolean; disabled: boolean; form: string; formAction: string \| ((formData: FormData) => void \| Promise<void>); formEncType: string; formMethod: string; formNoValidate: boolean; formTarget: string; height: string \| number; list: string; max: string \| number; maxLength: number; min: string \| number; minLength: number; multiple: boolean; name: string; pattern: string; placeholder: string; readOnly: boolean; required: boolean; size: number; src: string; step: string \| number; type: "number" \| "button" \| "search" \| "time" \| "image" \| "text" \| "hidden" \| "color" \| string & {} \| "checkbox" \| "radio" \| "tel" \| "url" \| "email" \| "date" \| "submit" \| "reset" \| "datetime-local" \| "file" \| "month" \| "password" \| "range" \| "week"; width: string \| number; onChange: (event: React.ChangeEvent<HTMLInputElement>) => void; defaultChecked: boolean; defaultValue: string \| number \| readonly string[]; suppressContentEditableWarning: boolean; suppressHydrationWarning: boolean; accessKey: string; autoCapitalize: "off" \| "none" \| "on" \| "sentences" \| "words" \| "characters" \| string & {}; autoFocus: boolean; className: string; contentEditable: false \| true \| "true" \| "false" \| "inherit" \| "plaintext-only"; contextMenu: string; dir: string; draggable: false \| true \| "true" \| "false"; enterKeyHint: "search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"; hidden: boolean; id: string; lang: string; nonce: string; slot: string; spellCheck: false \| true \| "true" \| "false"; style: React.CSSProperties; tabIndex: number; title: string; translate: "yes" \| "no"; radioGroup: string; role: "article" \| "button" \| "dialog" \| "figure" \| "form" \| "img" \| "link" \| "main" \| "menu" \| "menuitem" \| "option" \| "search" \| "table" \| "switch" \| "none" \| string & {} \| "alert" \| "alertdialog" \| "application" \| "banner" \| "cell" \| "checkbox" \| "columnheader" \| "combobox" \| "complementary" \| "contentinfo" \| "definition" \| "directory" \| "document" \| "feed" \| "grid" \| "gridcell" \| "group" \| "heading" \| "list" \| "listbox" \| "listitem" \| "log" \| "marquee" \| "math" \| "menubar" \| "menuitemcheckbox" \| "menuitemradio" \| "navigation" \| "note" \| "presentation" \| "progressbar" \| "radio" \| "radiogroup" \| "region" \| "row" \| "rowgroup" \| "rowheader" \| "scrollbar" \| "searchbox" \| "separator" \| "slider" \| "spinbutton" \| "status" \| "tab" \| "tablist" \| "tabpanel" \| "term" \| "textbox" \| "timer" \| "toolbar" \| "tooltip" \| "tree" \| "treegrid" \| "treeitem"; about: string; content: string; datatype: string; inlist: any; prefix: string; property: string; rel: string; resource: string; rev: string; typeof: string; vocab: string; autoCorrect: string; autoSave: string; color: string; itemProp: string; itemScope: boolean; itemType: string; itemID: string; itemRef: string; results: number; security: string; unselectable: "off" \| "on"; popover: "" \| "auto" \| "manual"; popoverTargetAction: "toggle" \| "show" \| "hide"; popoverTarget: string; inert: boolean; inputMode: "search" \| "text" \| "none" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal"; is: string; exportparts: string; part: string; aria-activedescendant: string; aria-atomic: false \| true \| "true" \| "false"; aria-autocomplete: "none" \| "list" \| "inline" \| "both"; aria-braillelabel: string; aria-brailleroledescription: string; aria-busy: false \| true \| "true" \| "false"; aria-checked: false \| true \| "true" \| "false" \| "mixed"; aria-colcount: number; aria-colindex: number; aria-colindextext: string; aria-colspan: number; aria-controls: string; aria-current: false \| true \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"; aria-describedby: string; aria-description: string; aria-details: string; aria-disabled: false \| true \| "true" \| "false"; aria-dropeffect: "link" \| "none" \| "copy" \| "execute" \| "move" \| "popup"; aria-errormessage: string; aria-expanded: false \| true \| "true" \| "false"; aria-flowto: string; aria-grabbed: false \| true \| "true" \| "false"; aria-haspopup: false \| true \| "dialog" \| "menu" \| "true" \| "false" \| "grid" \| "listbox" \| "tree"; aria-hidden: false \| true \| "true" \| "false"; aria-invalid: false \| true \| "true" \| "false" \| "grammar" \| "spelling"; aria-keyshortcuts: string; aria-label: string; aria-labelledby: string; aria-level: number; aria-live: "off" \| "assertive" \| "polite"; aria-modal: false \| true \| "true" \| "false"; aria-multiline: false \| true \| "true" \| "false"; aria-multiselectable: false \| true \| "true" \| "false"; aria-orientation: "horizontal" \| "vertical"; aria-owns: string; aria-placeholder: string; aria-posinset: number; aria-pressed: false \| true \| "true" \| "false" \| "mixed"; aria-readonly: false \| true \| "true" \| "false"; aria-relevant: "text" \| "additions" \| "additions removals" \| "additions text" \| "all" \| "removals" \| "removals additions" \| "removals text" \| "text additions" \| "text removals"; aria-required: false \| true \| "true" \| "false"; aria-roledescription: string; aria-rowcount: number; aria-rowindex: number; aria-rowindextext: string; aria-rowspan: number; aria-selected: false \| true \| "true" \| "false"; aria-setsize: number; aria-sort: "none" \| "ascending" \| "descending" \| "other"; aria-valuemax: number; aria-valuemin: number; aria-valuenow: number; aria-valuetext: string; children: ReactNode; dangerouslySetInnerHTML: { __html: string \| TrustedHTML; }; onCopy: (event: React.ClipboardEvent<HTMLInputElement>) => void; onCopyCapture: (event: React.ClipboardEvent<HTMLInputElement>) => void; onCut: (event: React.ClipboardEvent<HTMLInputElement>) => void; onCutCapture: (event: React.ClipboardEvent<HTMLInputElement>) => void; onPaste: (event: React.ClipboardEvent<HTMLInputElement>) => void; onPasteCapture: (event: React.ClipboardEvent<HTMLInputElement>) => void; onCompositionEnd: (event: React.CompositionEvent<HTMLInputElement>) => void; onCompositionEndCapture: (event: React.CompositionEvent<HTMLInputElement>) => void; onCompositionStart: (event: React.CompositionEvent<HTMLInputElement>) => void; onCompositionStartCapture: (event: React.CompositionEvent<HTMLInputElement>) => void; onCompositionUpdate: (event: React.CompositionEvent<HTMLInputElement>) => void; onCompositionUpdateCapture: (event: React.CompositionEvent<HTMLInputElement>) => void; onFocus: (event: React.FocusEvent<HTMLInputElement, Element>) => void; onFocusCapture: (event: React.FocusEvent<HTMLInputElement, Element>) => void; onBlur: (event: React.FocusEvent<HTMLInputElement, Element>) => void; onBlurCapture: (event: React.FocusEvent<HTMLInputElement, Element>) => void; onChangeCapture: (event: React.FormEvent<HTMLInputElement>) => void; onBeforeInput: (event: React.InputEvent<HTMLInputElement>) => void; onBeforeInputCapture: (event: React.FormEvent<HTMLInputElement>) => void; onInput: (event: React.FormEvent<HTMLInputElement>) => void; onInputCapture: (event: React.FormEvent<HTMLInputElement>) => void; onReset: (event: React.FormEvent<HTMLInputElement>) => void; onResetCapture: (event: React.FormEvent<HTMLInputElement>) => void; onSubmit: (event: React.FormEvent<HTMLInputElement>) => void; onSubmitCapture: (event: React.FormEvent<HTMLInputElement>) => void; onInvalid: (event: React.FormEvent<HTMLInputElement>) => void; onInvalidCapture: (event: React.FormEvent<HTMLInputElement>) => void; onLoad: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onError: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onErrorCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void; onKeyDownCapture: (event: React.KeyboardEvent<HTMLInputElement>) => void; onKeyPress: (event: React.KeyboardEvent<HTMLInputElement>) => void; onKeyPressCapture: (event: React.KeyboardEvent<HTMLInputElement>) => void; onKeyUp: (event: React.KeyboardEvent<HTMLInputElement>) => void; onKeyUpCapture: (event: React.KeyboardEvent<HTMLInputElement>) => void; onAbort: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onAbortCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onCanPlay: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onCanPlayCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onCanPlayThrough: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onCanPlayThroughCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onDurationChange: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onDurationChangeCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onEmptied: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onEmptiedCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onEncrypted: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onEncryptedCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onEnded: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onEndedCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadedData: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadedDataCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadedMetadata: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadedMetadataCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadStart: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onLoadStartCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onPause: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onPauseCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onPlay: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onPlayCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onPlaying: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onPlayingCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onProgress: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onProgressCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onRateChange: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onRateChangeCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSeeked: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSeekedCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSeeking: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSeekingCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onStalled: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onStalledCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSuspend: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSuspendCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onTimeUpdate: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onTimeUpdateCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onVolumeChange: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onVolumeChangeCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onWaiting: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onWaitingCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onAuxClick: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onAuxClickCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onClick: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onClickCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onContextMenu: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onContextMenuCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onDoubleClick: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onDoubleClickCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onDrag: (event: React.DragEvent<HTMLInputElement>) => void; onDragCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDragEnd: (event: React.DragEvent<HTMLInputElement>) => void; onDragEndCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDragEnter: (event: React.DragEvent<HTMLInputElement>) => void; onDragEnterCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDragExit: (event: React.DragEvent<HTMLInputElement>) => void; onDragExitCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDragLeave: (event: React.DragEvent<HTMLInputElement>) => void; onDragLeaveCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDragOver: (event: React.DragEvent<HTMLInputElement>) => void; onDragOverCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDragStart: (event: React.DragEvent<HTMLInputElement>) => void; onDragStartCapture: (event: React.DragEvent<HTMLInputElement>) => void; onDrop: (event: React.DragEvent<HTMLInputElement>) => void; onDropCapture: (event: React.DragEvent<HTMLInputElement>) => void; onMouseDown: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseDownCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseEnter: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseLeave: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseMove: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseMoveCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseOut: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseOutCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseOver: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseOverCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseUp: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onMouseUpCapture: (event: React.MouseEvent<HTMLInputElement, MouseEvent>) => void; onSelect: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onSelectCapture: (event: React.SyntheticEvent<HTMLInputElement, Event>) => void; onTouchCancel: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchCancelCapture: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchEnd: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchEndCapture: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchMove: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchMoveCapture: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchStart: (event: React.TouchEvent<HTMLInputElement>) => void; onTouchStartCapture: (event: React.TouchEvent<HTMLInputElement>) => void; onPointerDown: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerDownCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerMove: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerMoveCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerUp: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerUpCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerCancel: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerCancelCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerEnter: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerLeave: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerOver: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerOverCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerOut: (event: React.PointerEvent<HTMLInputElement>) => void; onPointerOutCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onGotPointerCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onGotPointerCaptureCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onLostPointerCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onLostPointerCaptureCapture: (event: React.PointerEvent<HTMLInputElement>) => void; onScroll: (event: React.UIEvent<HTMLInputElement, UIEvent>) => void; onScrollCapture: (event: React.UIEvent<HTMLInputElement, UIEvent>) => void; onScrollEnd: (event: React.UIEvent<HTMLInputElement, UIEvent>) => void; onScrollEndCapture: (event: React.UIEvent<HTMLInputElement, UIEvent>) => void; onWheel: (event: React.WheelEvent<HTMLInputElement>) => void; onWheelCapture: (event: React.WheelEvent<HTMLInputElement>) => void; onAnimationStart: (event: React.AnimationEvent<HTMLInputElement>) => void; onAnimationStartCapture: (event: React.AnimationEvent<HTMLInputElement>) => void; onAnimationEnd: (event: React.AnimationEvent<HTMLInputElement>) => void; onAnimationEndCapture: (event: React.AnimationEvent<HTMLInputElement>) => void; onAnimationIteration: (event: React.AnimationEvent<HTMLInputElement>) => void; onAnimationIterationCapture: (event: React.AnimationEvent<HTMLInputElement>) => void; onToggle: (event: React.ToggleEvent<HTMLInputElement>) => void; onBeforeToggle: (event: React.ToggleEvent<HTMLInputElement>) => void; onTransitionCancel: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionCancelCapture: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionEnd: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionEndCapture: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionRun: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionRunCapture: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionStart: (event: React.TransitionEvent<HTMLInputElement>) => void; onTransitionStartCapture: (event: React.TransitionEvent<HTMLInputElement>) => void })[]` | - | Options to render. Pass a string to use it as both the value and label, or an object with any input props (e.g. `aria-label` for icon-only options). |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| defaultValue | `string` | - | The value of the item that is initially selected. |
+| name | `string` | `React.useId()` | Segmented control is built as a radio group, and uses `name` to group the radio buttons together. If not provided, a random ID will be generated and used as the name. |
+| onValueChange | `(value: string) => void` | - | The callback that fires when the selected value of the segmented control changes. Use `defaultChecked` on `SegmentedControlItem` to pick the initial option. |
+| size | `"small" \| "tiny" \| "medium" \| "large"` | `"medium"` | The size of the segmented control - `tiny`: Perfect for compact, dense layouts. - `small`: Ideal for compact layouts with limited space and less significant actions. - `medium`: Suitable for most use cases. - `large`: Best for important actions. |
+| value | `string` | - | The current selected value of the segmented control. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Select.md b/.agents/skills/kaizen-ui/references/components/Select.md
new file mode 100644
index 0000000..f72014c
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Select.md
@@ -0,0 +1,291 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Select
+
+A Select is a dropdown that allows the user to select a value from a list of options.
+
+## Examples
+
+### Basic Select
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <Select
+ items={['Apple', 'Banana', 'Cherry']}
+ defaultValue="Banana"
+ placeholder="Choose a fruit"
+ />
+ <Select
+ items={['Apple', 'Banana', 'Cherry']}
+ defaultValue={['Apple', 'Banana']}
+ multiple
+ placeholder="Choose multiple fruits"
+ />
+</Flex>
+```
+
+### With Object Items Select
+
+Use object items when the stored value should differ from the visible label — for example, when the value is an ID and the label is human-readable.
+
+```tsx
+<Select
+ items={[
+ { value: '1', children: 'Apple' },
+ { value: '2', children: 'Banana' },
+ { value: '3', children: 'Cherry' }
+ ]}
+ placeholder="Choose a fruit"
+/>
+```
+
+### Rich Item Content Select
+
+Pass `slotStart` / `slotEnd` on an item for leading or trailing icons, or use `children` directly for richer multi-line content (e.g. an icon paired with a primary label and a secondary metadata line). Set `filterValue` whenever `children` is non-string so type-ahead still works.
+
+```tsx
+<Select
+ items={[
+ {
+ value: 'edit',
+ children: 'Edit',
+ slotStart: <Document />
+ },
+ {
+ value: 'schedule',
+ children: 'Schedule',
+ slotStart: <Calendar />
+ },
+ {
+ value: 'report-q1',
+ filterValue: 'Q1 Report.pdf',
+ children: (
+ <Flex direction="col">
+ <Flex gap="1" align="center">
+ <DocumentLine />
+ Q1 Report.pdf
+ </Flex>
+ <Text kind="label/regular/sm">Updated 2 days ago</Text>
+ </Flex>
+ )
+ }
+ ]}
+ placeholder="Choose an option"
+/>
+```
+
+### With Trigger Slots Select
+
+Use slotStart and slotEnd on the Select itself to add leading icons (e.g. a search glyph) or trailing affordances (e.g. an info tooltip) to the trigger.
+
+```tsx
+<Select
+ items={['Apple', 'Banana', 'Cherry']}
+ placeholder="Filter fruit"
+ slotStart={<Filter />}
+ slotEnd={<InfoCircle />}
+/>
+```
+
+### Custom Render Value Select
+
+Use renderValue when the trigger needs richer or differently formatted content than the matching item's children.
+
+```tsx
+<Select
+ items={['Apple', 'Banana', 'Cherry']}
+ defaultValue="Apple"
+ renderValue={value => (value ? `Selected: ${value}` : 'No value selected')}
+/>
+```
+
+### Grouped Items Select
+
+Use when options logically belong to categories that help users scan the list.
+
+```tsx
+<Select
+ items={[
+ { slotHeading: 'Fruits', items: ['Apple', 'Banana'] },
+ { slotHeading: 'Vegetables', items: ['Carrot', 'Lettuce'] }
+ ]}
+ placeholder="Choose an item"
+/>
+```
+
+### Multiple Select
+
+Use when users need to choose more than one option from the list.
+
+```tsx
+<Select items={['Red', 'Green', 'Blue']} multiple placeholder="Pick colors" />
+```
+
+### Multi Tag Select
+
+Pair multiple + allowBackspaceRemoval with a tag-based renderValue when each selected value should appear as a clearly removable chip. The Backspace shortcut is opt-in because the default `N selected` summary has no per-item target.
+
+```tsx
+<Select
+ allowBackspaceRemoval
+ multiple
+ defaultValue={['Apple', 'Banana']}
+ items={['Apple', 'Banana', 'Cherry', 'Orange', 'Pineapple']}
+ renderValue={(value, setValue) =>
+ value.length > 0 &&
+ value.map(v => (
+ <Tag
+ key={v}
+ color="gray"
+ density="compact"
+ onClick={e => {
+ e.stopPropagation()
+ setValue(value.filter(p => p !== v))
+ }}
+ >
+ {v}
+ <Close />
+ </Tag>
+ ))
+ }
+/>
+```
+
+### Dismissible Select
+
+Use when users need a quick way to clear their selection.
+
+```tsx
+<Select items={['Apple', 'Banana', 'Cherry']} dismissible defaultValue="Apple" />
+```
+
+### Floating Trigger Select
+
+Use triggerKind='floating' when the Select sits on top of dense content (e.g. a toolbar) and should not render the default input border or background.
+
+```tsx
+<Select items={['Apple', 'Banana', 'Cherry']} defaultValue="Banana" triggerKind="floating" />
+```
+
+### Size Select
+
+Match the trigger size to surrounding controls. The menu density derives from size by default; override it with the density prop when needed.
+
+```tsx
+<Flex direction="col" gap="2">
+ <Select size="small" items={['Apple', 'Banana']} placeholder="Small" />
+ <Select size="medium" items={['Apple', 'Banana']} placeholder="Medium" />
+ <Select size="large" items={['Apple', 'Banana']} placeholder="Large" />
+</Flex>
+```
+
+### Disabled Select
+
+Use when the selection is locked by external conditions.
+
+```tsx
+<Select items={['Apple', 'Banana']} disabled defaultValue="Apple" />
+```
+
+### Read Only Select
+
+Use readOnly (instead of disabled) when the value should remain visible and copyable but the user cannot open the menu or change the selection — common in review or summary screens.
+
+```tsx
+<Select items={['Apple', 'Banana']} readOnly defaultValue="Apple" />
+```
+
+### Error Status Select
+
+Use to indicate the selection has failed validation.
+
+```tsx
+<Select items={['Apple', 'Banana']} status="error" placeholder="Required" />
+```
+
+### With Form Field Select
+
+Wrap Select in FormField to attach a label, helper text, and validation status that stay in sync with the trigger via context.
+
+```tsx
+<FormField slotLabel="Contact Method" slotHelp="How would you like us to reach you?">
+ <Select items={['Phone', 'Email', 'Both']} placeholder="Select" />
+</FormField>
+```
+
+### In Form Select
+
+Pass a name prop so the Select renders a hidden native <select> that participates in standard form submission — works without JavaScript.
+
+```tsx
+<form>
+ <Flex direction="col" gap="density-md">
+ <Select name="fruit" items={['Apple', 'Banana', 'Cherry']} placeholder="Pick a fruit" />
+ <Button type="submit">Submit</Button>
+ </Flex>
+</form>
+```
+
+### Controlled Select
+
+Use controlled mode when the selection state lives outside the Select — for example, when syncing with form libraries, URL state, or another component.
+
+```tsx
+;() => {
+ const [value, setValue] = useState('Apple')
+ return <Select items={['Apple', 'Banana', 'Cherry']} value={value} onValueChange={setValue} />
+}
+```
+
+### Composed
+
+Use the composed primitives when you need full control over trigger rendering, content layout, or custom items.
+
+```tsx
+<SelectRoot defaultValue="b">
+ <SelectTrigger placeholder="Pick one" />
+ <SelectContent>
+ <SelectItem value="a">Option A</SelectItem>
+ <SelectItem value="b">Option B</SelectItem>
+ <SelectItem value="c">Option C</SelectItem>
+ </SelectContent>
+</SelectRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string }) \| ({ items: string \| ({ children: ReactNode; onSelect: (event: Event) => void; disabled: boolean; value: string; danger: boolean; slotEnd: ReactNode; slotStart: ReactNode; filterValue: string })[]; children: never; kind: "section"; filterValue: never; slotHeading: ReactNode })[]` | - | The items to render in the Select. |
+| allowBackspaceRemoval | `boolean` | `false` | In multi-select mode, pressing `Backspace` while the trigger button is focused removes the last selected value. Defaults to `false` because the default Select trigger shows a `"N item(s) selected"` summary with no per-item control to indicate which value would be removed. Opt in when you have provided a `renderValue` (or other display) that makes the target selection visually obvious. |
+| autoFocusOnHide | `boolean` | `true` | Whether the Select trigger should be focused on hide. |
+| defaultOpen | `boolean` | - | The open state of the Select when it is initially rendered. Use when you do not need to control its open state. |
+| defaultValue | `string \| string[] & string \| string[] \| string & string[]` | - | The value of the select when initially rendered. Use when you do not need to control the state of the select. Use a string for single value selects and an array of strings for multiple value selects. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| disabled | `boolean` | - | The disabled state of the Select. |
+| dismissible | `boolean` | - | When true, renders a dismiss button that will clear the select |
+| hideOnEscape | `boolean` | `true` | Whether the Select content should be hidden when the escape key is pressed. |
+| multiple | `false \| true` | - | When `mutiple` is true the Select allows for multiple values to be selected. |
+| name | `string` | - | The name of the Select. When provided, the native fallback select participates in form submission. |
+| onKeyDown | `(event: React.KeyboardEvent<HTMLButtonElement>) => void` | - | Keyboard event handler invoked on the interactive trigger button. Called before the Select's built-in shortcuts (ArrowDown/ArrowUp open and, when `allowBackspaceRemoval` is enabled, Backspace removal); call `event.preventDefault()` to cancel those shortcuts. |
+| onOpenChange | `(open: boolean) => void` | - | The callback to be called when the Select is opened or closed. |
+| onScrollToBottom | `() => void` | - | Callback function that is called when the menu is scrolled to the bottom. Useful for loading more items. |
+| onValueChange | `(value: string) => void \| (value: string[]) => void` | - | Callback when the selected value of the select changes. |
+| open | `boolean` | - | The controlled open state of the Select |
+| placeholder | `ReactNode` | - | Placeholder text for the Select trigger |
+| readOnly | `boolean` | - | Whether the Select is read-only. A read-only Select will not allow the user to change the selected value or view the menu. |
+| renderValue | `(value: string, setValue: (value: string \| ((prev: string) => string)) => void) => ReactNode \| (value: string[], setValue: (value: string[] \| ((prev: string[]) => string[])) => void) => ReactNode` | - | Controls the rendering of the selected select value in the trigger. By default the select will render the children of the selected item for a single value select. For a multiple value select, the select renders the count of selected items. |
+| required | `boolean` | - | Whether the Select is required |
+| selectRef | `((instance: HTMLSelectElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLSelectElement>` | - | A ref to the internal native `<select>` element used for form integration. Only populated when the `name` prop is provided. |
+| side | `"right" \| "bottom" \| "left" \| "top"` | `"bottom"` | The side the Select menu will be positioned. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the select trigger. By default this will also control the `density` of the `SelectContent` - to override this, use the `density` prop. |
+| slotEnd | `ReactNode` | - | Content to render on the end side of the Select trigger. |
+| slotStart | `ReactNode` | - | Content to render on the start side of the Select trigger. |
+| status | `"error" \| "success"` | - | The status of the input. Use `withValidation` to automatically apply success/error states based on `:user-valid` and `:user-invalid` pseudo classes. |
+| triggerKind | `"flat" \| "floating"` | `"flat"` | The kind of the Select trigger. Used to determine whether or not to render background colors and borders. |
+| value | `string \| string[] & string \| string[] \| string & string[]` | - | The controlled value of the select. Must be used in conjunction with `onValueChange`. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/SidePanel.md b/.agents/skills/kaizen-ui/references/components/SidePanel.md
new file mode 100644
index 0000000..b098d3a
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/SidePanel.md
@@ -0,0 +1,343 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# SidePanel
+
+A dialog pinned to the left or right side of the screen that can be triggered by a button or other
+element. Uses the native `<dialog>` element for progressive enhancement, providing built-in
+backdrop styling, focus management, and support for `form method="dialog"` for native close behavior.
+
+Use a side panel when you need to show supplementary content or actions while maintaining the
+context of the main view. Side panels are ideal for tasks that require user input or displaying
+additional information without navigating away from the current page.
+
+Common use cases include:
+
+- Displaying details about a selected item
+- Forms that need context from the main view
+- Configuration panels
+- Multi-step workflows
+- Preview panels
+
+Consider a Modal instead when:
+
+- The task requires full user attention and blocking interaction with the main content
+- The content needs to be center-focused
+- The interaction is brief and doesn't require context from the main view
+
+## Examples
+
+### Basic Side Panel
+
+Use when you need to show supplementary content while maintaining context of the main view.
+
+```tsx
+<SidePanel
+ slotTrigger={<Button>Open Panel</Button>}
+ slotHeading="Details"
+ slotFooter={
+ <>
+ <SidePanelCloseButton kind="tertiary">Cancel</SidePanelCloseButton>
+ <Button color="brand">Save</Button>
+ </>
+ }
+>
+ Panel content with supplementary information.
+</SidePanel>
+```
+
+### Modal Side Panel
+
+Use when the side panel content requires focused attention and should block interaction with the main page.
+
+```tsx
+<SidePanel
+ modal
+ bordered
+ slotTrigger={<Button>Open Modal Panel</Button>}
+ slotHeading="Important Information"
+ slotFooter={
+ <>
+ <SidePanelCloseButton kind="tertiary">Close</SidePanelCloseButton>
+ <Button color="brand">Acknowledge</Button>
+ </>
+ }
+>
+ This panel requires focused attention with a backdrop overlay.
+</SidePanel>
+```
+
+### Form Side Panel
+
+Use when the side panel wraps a form that needs native form submission behavior.
+
+```tsx
+<SidePanel
+ bordered
+ slotTrigger={<Button>Open Form</Button>}
+ slotHeading="Create Resource"
+ renderContent={({ children }) => <form onSubmit={handleSubmit}>{children}</form>}
+ slotFooter={
+ <>
+ <SidePanelCloseButton kind="tertiary">Cancel</SidePanelCloseButton>
+ <Button type="submit" color="brand">
+ Create
+ </Button>
+ </>
+ }
+>
+ Form fields go here
+</SidePanel>
+```
+
+### Custom Width Side Panel
+
+Use when the default panel width is insufficient for the content being displayed.
+
+```tsx
+<SidePanel
+ bordered
+ slotTrigger={<Button>Open Wide Panel</Button>}
+ slotHeading="Wide Panel"
+ style={{ '--side-panel-width': '500px' }}
+>
+ This panel uses a custom width for content that needs more space.
+</SidePanel>
+```
+
+### With Navigation Side Panel
+
+Use when the panel needs tabs or breadcrumbs sitting between the heading and the main content.
+
+```tsx
+<SidePanel
+ bordered
+ slotTrigger={<Button>Open Panel</Button>}
+ slotHeading="Architecture"
+ slotNavigation={
+ <Tabs
+ defaultValue="layers"
+ items={[
+ { children: 'Layers', value: 'layers' },
+ { children: 'Parameters', value: 'parameters' },
+ { children: 'Performance', value: 'performance' }
+ ]}
+ />
+ }
+ slotFooter={
+ <>
+ <SidePanelCloseButton kind="tertiary">Cancel</SidePanelCloseButton>
+ <Button color="brand">Save</Button>
+ </>
+ }
+>
+ Tab content rendered here.
+</SidePanel>
+```
+
+### Relative Side Panel
+
+Use when the panel should be confined to a parent region rather than overlaying the viewport. The parent must be `position: relative` with `overflow: hidden`.
+
+```tsx
+<div
+ style={{
+ position: 'relative',
+ height: 400,
+ width: 500,
+ overflow: 'hidden',
+ border: '1px dashed currentColor'
+ }}
+>
+ <SidePanel relative slotTrigger={<Button>Open Panel</Button>} slotHeading="Cluster Status">
+ Cluster monitoring and management.
+ </SidePanel>
+</div>
+```
+
+### Default Open Side Panel
+
+Use when the panel's open state is driven by SSR or URL params — render with `defaultOpen` so the panel appears open on the first paint.
+
+```tsx
+<SidePanel
+ defaultOpen
+ bordered
+ slotTrigger={<Button>Edit Task</Button>}
+ slotHeading="Edit Task"
+ slotFooter={
+ <>
+ <SidePanelCloseButton kind="tertiary">Cancel</SidePanelCloseButton>
+ <Button color="brand">Save</Button>
+ </>
+ }
+>
+ Form fields go here.
+</SidePanel>
+```
+
+### Anchor Trigger Side Panel
+
+Use when the panel must open from a regular link for SSR-friendly, no-JS progressive enhancement. Requires `id` plus an `<a href='#id'>` passed via `slotAnchorTrigger`.
+
+```tsx
+<SidePanel
+ id="settings-panel"
+ bordered
+ slotAnchorTrigger={<a href="#settings-panel">Open Settings</a>}
+ slotHeading="Settings"
+ slotFooter={<SidePanelCloseButton kind="tertiary">Close</SidePanelCloseButton>}
+>
+ Settings content here.
+</SidePanel>
+```
+
+### Native Form Dialog Side Panel
+
+Use when the panel hosts a server-action form and cancel must close without submitting. `formMethod="dialog"` lets the native dialog close without JavaScript.
+
+```tsx
+<SidePanel
+ bordered
+ slotTrigger={<Button>Edit Task</Button>}
+ slotHeading="Edit Task"
+ attributes={{
+ SidePanelCloseButton: {
+ type: 'submit',
+ formMethod: 'dialog',
+ formNoValidate: true
+ }
+ }}
+ renderContent={({ children }) => (
+ <form action="/api/update-task" method="post">
+ {children}
+ </form>
+ )}
+ slotFooter={
+ <>
+ <input type="hidden" name="taskId" value="123" />
+ <Button type="submit" formMethod="dialog" formNoValidate kind="tertiary">
+ Cancel
+ </Button>
+ <Button type="submit" color="brand">
+ Save Changes
+ </Button>
+ </>
+ }
+>
+ Form fields go here.
+</SidePanel>
+```
+
+### Below App Bar Side Panel
+
+Use when the page has a fixed AppBar — offset the panel by the AppBar height so it docks beneath the bar instead of overlapping it.
+
+```tsx
+<SidePanel
+ bordered
+ className="top-[var(--nv-app-bar-height)]"
+ slotTrigger={<Button>Open Side Panel</Button>}
+ slotHeading="Heading"
+ slotFooter={<SidePanelCloseButton kind="tertiary">Close</SidePanelCloseButton>}
+>
+ Panel content sits below a fixed AppBar.
+</SidePanel>
+```
+
+### Multi Step Side Panel
+
+Use a multi-step pattern for wizards, guided flows, or any task that progresses through discrete stages. Track the current step in state and use `ml-auto` on the cancel button to push the primary action to the trailing edge.
+
+```tsx
+;() => {
+ const [step, setStep] = useState(0)
+ const totalSteps = 3
+ const isFirstStep = step === 0
+ const isLastStep = step === totalSteps - 1
+ return (
+ <SidePanel
+ bordered
+ slotTrigger={<Button>Open Side Panel</Button>}
+ slotHeading={`Step ${step + 1} of ${totalSteps}`}
+ slotFooter={
+ <>
+ <Button
+ kind="secondary"
+ disabled={isFirstStep}
+ onClick={() => setStep(s => Math.max(0, s - 1))}
+ >
+ Back
+ </Button>
+ <SidePanelCloseButton className="ml-auto" kind="tertiary">
+ Cancel
+ </SidePanelCloseButton>
+ <Button
+ color="brand"
+ onClick={() => setStep(s => Math.min(totalSteps - 1, s + 1))}
+ disabled={isLastStep}
+ >
+ Next
+ </Button>
+ </>
+ }
+ >
+ <Flex direction="col" gap="2">
+ Content for step {step + 1}.
+ </Flex>
+ </SidePanel>
+ )
+}
+```
+
+### Composed
+
+Use composed primitives when you need full control over the side panel layout and behavior.
+
+```tsx
+<SidePanelRoot>
+ <SidePanelTrigger asChild>
+ <Button>Open Panel</Button>
+ </SidePanelTrigger>
+ <SidePanelContent bordered>
+ <SidePanelHeading>Composed Heading</SidePanelHeading>
+ <SidePanelMain>Composed side panel content using primitives directly.</SidePanelMain>
+ <SidePanelFooter>
+ <SidePanelCloseButton kind="tertiary">Cancel</SidePanelCloseButton>
+ <Button color="brand">Save</Button>
+ </SidePanelFooter>
+ </SidePanelContent>
+</SidePanelRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, treats the immediate child as the host element, merging this component's props with the child's props. The child's children will be slotted into the component's defined content placement. |
+| bordered | `boolean` | `false` | When true, adds a border between the main content and the header/footer. This should almost always be `true`. |
+| children | `ReactNode` | - | The content to render in the panel. This will be rendered in the main content area of the panel, between the heading and footer. This includes `text-primary` and `body/regular/md` typography styles. It's also a flex column with `gap` spacing. |
+| closeButtonProps | `{ form?: string; slot?: string; style?: React.CSSProperties; title?: string; defaultValue?: string \| number \| readonly string[]; ref?: React.Ref<HTMLButtonElement>; key?: React.Key; defaultChecked?: boolean; suppressContentEditableWarning?: boolean; suppressHydrationWarning?: boolean; accessKey?: string; autoCapitalize?: "off" \| "none" \| "on" \| "sentences" \| "words" \| "characters" \| (string & {}); autoFocus?: boolean; contentEditable?: Booleanish \| "inherit" \| "plaintext-only"; contextMenu?: string; dir?: string; draggable?: Booleanish; enterKeyHint?: "search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"; hidden?: boolean; id?: string; lang?: string; nonce?: string; spellCheck?: Booleanish; tabIndex?: number; translate?: "yes" \| "no"; radioGroup?: string; role?: React.AriaRole; about?: string; content?: string; datatype?: string; inlist?: any; prefix?: string; property?: string; rel?: string; resource?: string; rev?: string; typeof?: string; vocab?: string; autoCorrect?: string; autoSave?: string; itemProp?: string; itemScope?: boolean; itemType?: string; itemID?: string; itemRef?: string; results?: number; security?: string; unselectable?: "off" \| "on"; popover?: "" \| "auto" \| "manual"; popoverTargetAction?: "toggle" \| "show" \| "hide"; popoverTarget?: string; inert?: boolean; inputMode?: "search" \| "text" \| "none" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal"; is?: string; exportparts?: string; part?: string; "aria-activedescendant"?: string; "aria-atomic"?: Booleanish; "aria-autocomplete"?: "none" \| "list" \| "inline" \| "both"; "aria-braillelabel"?: string; "aria-brailleroledescription"?: string; "aria-busy"?: Booleanish; "aria-checked"?: boolean \| "true" \| "false" \| "mixed"; "aria-colcount"?: number; "aria-colindex"?: number; "aria-colindextext"?: string; "aria-colspan"?: number; "aria-controls"?: string; "aria-current"?: boolean \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"; "aria-describedby"?: string; "aria-description"?: string; "aria-details"?: string; "aria-disabled"?: Booleanish; "aria-dropeffect"?: "link" \| "none" \| "copy" \| "execute" \| "move" \| "popup"; "aria-errormessage"?: string; "aria-expanded"?: Booleanish; "aria-flowto"?: string; "aria-grabbed"?: Booleanish; "aria-haspopup"?: boolean \| "dialog" \| "menu" \| "true" \| "false" \| "grid" \| "listbox" \| "tree"; "aria-hidden"?: Booleanish; "aria-invalid"?: boolean \| "true" \| "false" \| "grammar" \| "spelling"; "aria-keyshortcuts"?: string; "aria-label"?: string; "aria-labelledby"?: string; "aria-level"?: number; "aria-live"?: "off" \| "assertive" \| "polite"; "aria-modal"?: Booleanish; "aria-multiline"?: Booleanish; "aria-multiselectable"?: Booleanish; "aria-orientation"?: "horizontal" \| "vertical"; "aria-owns"?: string; "aria-placeholder"?: string; "aria-posinset"?: number; "aria-pressed"?: boolean \| "true" \| "false" \| "mixed"; "aria-readonly"?: Booleanish; "aria-relevant"?: "text" \| "additions" \| "additions removals" \| "additions text" \| "all" \| "removals" \| "removals additions" \| "removals text" \| "text additions" \| "text removals"; "aria-required"?: Booleanish; "aria-roledescription"?: string; "aria-rowcount"?: number; "aria-rowindex"?: number; "aria-rowindextext"?: string; "aria-rowspan"?: number; "aria-selected"?: Booleanish; "aria-setsize"?: number; "aria-sort"?: "none" \| "ascending" \| "descending" \| "other"; "aria-valuemax"?: number; "aria-valuemin"?: number; "aria-valuenow"?: number; "aria-valuetext"?: string; dangerouslySetInnerHTML?: { __html: string \| TrustedHTML; }; onCopy?: React.ClipboardEventHandler<HTMLButtonElement>; onCopyCapture?: React.ClipboardEventHandler<HTMLButtonElement>; onCut?: React.ClipboardEventHandler<HTMLButtonElement>; onCutCapture?: React.ClipboardEventHandler<HTMLButtonElement>; onPaste?: React.ClipboardEventHandler<HTMLButtonElement>; onPasteCapture?: React.ClipboardEventHandler<HTMLButtonElement>; onCompositionEnd?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionEndCapture?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionStart?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionStartCapture?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionUpdate?: React.CompositionEventHandler<HTMLButtonElement>; onCompositionUpdateCapture?: React.CompositionEventHandler<HTMLButtonElement>; onFocus?: React.FocusEventHandler<HTMLButtonElement>; onFocusCapture?: React.FocusEventHandler<HTMLButtonElement>; onBlur?: React.FocusEventHandler<HTMLButtonElement>; onBlurCapture?: React.FocusEventHandler<HTMLButtonElement>; onChange?: React.FormEventHandler<HTMLButtonElement>; onChangeCapture?: React.FormEventHandler<HTMLButtonElement>; onBeforeInput?: React.InputEventHandler<HTMLButtonElement>; onBeforeInputCapture?: React.FormEventHandler<HTMLButtonElement>; onInput?: React.FormEventHandler<HTMLButtonElement>; onInputCapture?: React.FormEventHandler<HTMLButtonElement>; onReset?: React.FormEventHandler<HTMLButtonElement>; onResetCapture?: React.FormEventHandler<HTMLButtonElement>; onSubmit?: React.FormEventHandler<HTMLButtonElement>; onSubmitCapture?: React.FormEventHandler<HTMLButtonElement>; onInvalid?: React.FormEventHandler<HTMLButtonElement>; onInvalidCapture?: React.FormEventHandler<HTMLButtonElement>; onLoad?: React.ReactEventHandler<HTMLButtonElement>; onLoadCapture?: React.ReactEventHandler<HTMLButtonElement>; onError?: React.ReactEventHandler<HTMLButtonElement>; onErrorCapture?: React.ReactEventHandler<HTMLButtonElement>; onKeyDown?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyDownCapture?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyPress?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyPressCapture?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyUp?: React.KeyboardEventHandler<HTMLButtonElement>; onKeyUpCapture?: React.KeyboardEventHandler<HTMLButtonElement>; onAbort?: React.ReactEventHandler<HTMLButtonElement>; onAbortCapture?: React.ReactEventHandler<HTMLButtonElement>; onCanPlay?: React.ReactEventHandler<HTMLButtonElement>; onCanPlayCapture?: React.ReactEventHandler<HTMLButtonElement>; onCanPlayThrough?: React.ReactEventHandler<HTMLButtonElement>; onCanPlayThroughCapture?: React.ReactEventHandler<HTMLButtonElement>; onDurationChange?: React.ReactEventHandler<HTMLButtonElement>; onDurationChangeCapture?: React.ReactEventHandler<HTMLButtonElement>; onEmptied?: React.ReactEventHandler<HTMLButtonElement>; onEmptiedCapture?: React.ReactEventHandler<HTMLButtonElement>; onEncrypted?: React.ReactEventHandler<HTMLButtonElement>; onEncryptedCapture?: React.ReactEventHandler<HTMLButtonElement>; onEnded?: React.ReactEventHandler<HTMLButtonElement>; onEndedCapture?: React.ReactEventHandler<HTMLButtonElement>; onLoadedData?: React.ReactEventHandler<HTMLButtonElement>; onLoadedDataCapture?: React.ReactEventHandler<HTMLButtonElement>; onLoadedMetadata?: React.ReactEventHandler<HTMLButtonElement>; onLoadedMetadataCapture?: React.ReactEventHandler<HTMLButtonElement>; onLoadStart?: React.ReactEventHandler<HTMLButtonElement>; onLoadStartCapture?: React.ReactEventHandler<HTMLButtonElement>; onPause?: React.ReactEventHandler<HTMLButtonElement>; onPauseCapture?: React.ReactEventHandler<HTMLButtonElement>; onPlay?: React.ReactEventHandler<HTMLButtonElement>; onPlayCapture?: React.ReactEventHandler<HTMLButtonElement>; onPlaying?: React.ReactEventHandler<HTMLButtonElement>; onPlayingCapture?: React.ReactEventHandler<HTMLButtonElement>; onProgress?: React.ReactEventHandler<HTMLButtonElement>; onProgressCapture?: React.ReactEventHandler<HTMLButtonElement>; onRateChange?: React.ReactEventHandler<HTMLButtonElement>; onRateChangeCapture?: React.ReactEventHandler<HTMLButtonElement>; onSeeked?: React.ReactEventHandler<HTMLButtonElement>; onSeekedCapture?: React.ReactEventHandler<HTMLButtonElement>; onSeeking?: React.ReactEventHandler<HTMLButtonElement>; onSeekingCapture?: React.ReactEventHandler<HTMLButtonElement>; onStalled?: React.ReactEventHandler<HTMLButtonElement>; onStalledCapture?: React.ReactEventHandler<HTMLButtonElement>; onSuspend?: React.ReactEventHandler<HTMLButtonElement>; onSuspendCapture?: React.ReactEventHandler<HTMLButtonElement>; onTimeUpdate?: React.ReactEventHandler<HTMLButtonElement>; onTimeUpdateCapture?: React.ReactEventHandler<HTMLButtonElement>; onVolumeChange?: React.ReactEventHandler<HTMLButtonElement>; onVolumeChangeCapture?: React.ReactEventHandler<HTMLButtonElement>; onWaiting?: React.ReactEventHandler<HTMLButtonElement>; onWaitingCapture?: React.ReactEventHandler<HTMLButtonElement>; onAuxClick?: React.MouseEventHandler<HTMLButtonElement>; onAuxClickCapture?: React.MouseEventHandler<HTMLButtonElement>; onClick?: React.MouseEventHandler<HTMLButtonElement>; onClickCapture?: React.MouseEventHandler<HTMLButtonElement>; onContextMenu?: React.MouseEventHandler<HTMLButtonElement>; onContextMenuCapture?: React.MouseEventHandler<HTMLButtonElement>; onDoubleClick?: React.MouseEventHandler<HTMLButtonElement>; onDoubleClickCapture?: React.MouseEventHandler<HTMLButtonElement>; onDrag?: React.DragEventHandler<HTMLButtonElement>; onDragCapture?: React.DragEventHandler<HTMLButtonElement>; onDragEnd?: React.DragEventHandler<HTMLButtonElement>; onDragEndCapture?: React.DragEventHandler<HTMLButtonElement>; onDragEnter?: React.DragEventHandler<HTMLButtonElement>; onDragEnterCapture?: React.DragEventHandler<HTMLButtonElement>; onDragExit?: React.DragEventHandler<HTMLButtonElement>; onDragExitCapture?: React.DragEventHandler<HTMLButtonElement>; onDragLeave?: React.DragEventHandler<HTMLButtonElement>; onDragLeaveCapture?: React.DragEventHandler<HTMLButtonElement>; onDragOver?: React.DragEventHandler<HTMLButtonElement>; onDragOverCapture?: React.DragEventHandler<HTMLButtonElement>; onDragStart?: React.DragEventHandler<HTMLButtonElement>; onDragStartCapture?: React.DragEventHandler<HTMLButtonElement>; onDrop?: React.DragEventHandler<HTMLButtonElement>; onDropCapture?: React.DragEventHandler<HTMLButtonElement>; onMouseDown?: React.MouseEventHandler<HTMLButtonElement>; onMouseDownCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseEnter?: React.MouseEventHandler<HTMLButtonElement>; onMouseLeave?: React.MouseEventHandler<HTMLButtonElement>; onMouseMove?: React.MouseEventHandler<HTMLButtonElement>; onMouseMoveCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseOut?: React.MouseEventHandler<HTMLButtonElement>; onMouseOutCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseOver?: React.MouseEventHandler<HTMLButtonElement>; onMouseOverCapture?: React.MouseEventHandler<HTMLButtonElement>; onMouseUp?: React.MouseEventHandler<HTMLButtonElement>; onMouseUpCapture?: React.MouseEventHandler<HTMLButtonElement>; onSelect?: React.ReactEventHandler<HTMLButtonElement>; onSelectCapture?: React.ReactEventHandler<HTMLButtonElement>; onTouchCancel?: React.TouchEventHandler<HTMLButtonElement>; onTouchCancelCapture?: React.TouchEventHandler<HTMLButtonElement>; onTouchEnd?: React.TouchEventHandler<HTMLButtonElement>; onTouchEndCapture?: React.TouchEventHandler<HTMLButtonElement>; onTouchMove?: React.TouchEventHandler<HTMLButtonElement>; onTouchMoveCapture?: React.TouchEventHandler<HTMLButtonElement>; onTouchStart?: React.TouchEventHandler<HTMLButtonElement>; onTouchStartCapture?: React.TouchEventHandler<HTMLButtonElement>; onPointerDown?: React.PointerEventHandler<HTMLButtonElement>; onPointerDownCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerMove?: React.PointerEventHandler<HTMLButtonElement>; onPointerMoveCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerUp?: React.PointerEventHandler<HTMLButtonElement>; onPointerUpCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerCancel?: React.PointerEventHandler<HTMLButtonElement>; onPointerCancelCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerEnter?: React.PointerEventHandler<HTMLButtonElement>; onPointerLeave?: React.PointerEventHandler<HTMLButtonElement>; onPointerOver?: React.PointerEventHandler<HTMLButtonElement>; onPointerOverCapture?: React.PointerEventHandler<HTMLButtonElement>; onPointerOut?: React.PointerEventHandler<HTMLButtonElement>; onPointerOutCapture?: React.PointerEventHandler<HTMLButtonElement>; onGotPointerCapture?: React.PointerEventHandler<HTMLButtonElement>; onGotPointerCaptureCapture?: React.PointerEventHandler<HTMLButtonElement>; onLostPointerCapture?: React.PointerEventHandler<HTMLButtonElement>; onLostPointerCaptureCapture?: React.PointerEventHandler<HTMLButtonElement>; onScroll?: React.UIEventHandler<HTMLButtonElement>; onScrollCapture?: React.UIEventHandler<HTMLButtonElement>; onScrollEnd?: React.UIEventHandler<HTMLButtonElement>; onScrollEndCapture?: React.UIEventHandler<HTMLButtonElement>; onWheel?: React.WheelEventHandler<HTMLButtonElement>; onWheelCapture?: React.WheelEventHandler<HTMLButtonElement>; onAnimationStart?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationStartCapture?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationEnd?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationEndCapture?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationIteration?: React.AnimationEventHandler<HTMLButtonElement>; onAnimationIterationCapture?: React.AnimationEventHandler<HTMLButtonElement>; onToggle?: React.ToggleEventHandler<HTMLButtonElement>; onBeforeToggle?: React.ToggleEventHandler<HTMLButtonElement>; onTransitionCancel?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionCancelCapture?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionEnd?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionEndCapture?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionRun?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionRunCapture?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionStart?: React.TransitionEventHandler<HTMLButtonElement>; onTransitionStartCapture?: React.TransitionEventHandler<HTMLButtonElement>; asChild?: boolean; disabled?: boolean; name?: string; value?: string \| number \| readonly string[]; formAction?: string \| ((formData: FormData) => void \| Promise<void>); formEncType?: string; formMethod?: string; formNoValidate?: boolean; formTarget?: string; type?: "button" \| "submit" \| "reset"; size?: "small" \| "tiny" \| "medium" \| "large"; }` | - | Props to pass to the close button. This can be used to customize the close button's behavior for progressive enhancement scenarios. |
+| closeOnClickOutside | `boolean` | - | |
+| defaultOpen | `boolean` | `false` | Initial open state when the dialog is uncontrolled. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| disabled | `boolean` | - | Disables the side panel trigger |
+| forceMount | `boolean` | - | |
+| hideCloseButton | `boolean` | - | When true, hides the side panel's close button. Useful for panels that should not be dismissible. |
+| modal | `boolean` | `true` | When `true`, the dialog is opened via `HTMLDialogElement.showModal()`, rendering a top-layer backdrop and trapping focus. When `false`, the dialog is opened via `HTMLDialogElement.show()` as a non-modal dialog. |
+| onEscapeKeyDown | `(event: KeyboardEvent) => void` | - | |
+| onInteractOutside | `(event: MouseEvent) => void` | - | Event handler called when an interaction event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| onOpenAutoFocus | `(event: Event) => void` | - | |
+| onOpenChange | `(open: boolean) => void` | - | Callback invoked whenever the dialog's open state changes, in both controlled and uncontrolled modes. Consecutive transitions to the same value are deduped, so the callback fires at most once per state change. |
+| onPointerDownOutside | `(event: MouseEvent) => void` | - | Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| open | `boolean` | - | Controlled open state. When provided, the hook operates in controlled mode and `defaultOpen` is ignored. The consumer is responsible for updating this value in response to {@link UseDialogOptions.onOpenChange} callbacks. |
+| relative | `boolean` | `false` | When true, positions the side panel absolutely within its closest positioned ancestor instead of fixed to the viewport. The parent element must have `position: relative` and `overflow: hidden` set. |
+| renderContent | `(props: { children: React.ReactNode; }) => React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>` | - | A render function that wraps the side panel content. This is useful for injecting elements like forms. When provided, this will force `asChild` on the SidePanelContent component. |
+| side | `"right" \| "left"` | `"right"` | Which side the panel should appear from |
+| slotAnchorTrigger | `ReactNode` | - | The content to render in the panel anchor trigger. |
+| slotFooter | `ReactNode` | - | The content to render in the panel footer. Handles spacing and aligns content to the end of the container. |
+| slotHeading | `ReactNode` | - | The content to render in the panel heading. If not provided, the panel will render empty space to make room for the close button. Has `label/bold/lg` typography styles and handles icon sizing/color. |
+| slotNavigation | `ReactNode` | - | A slot that is rendered between the heading and main content. This slot is intended to be used for navigation content, such as tabs or breadcrumbs. |
+| slotTrigger | `ReactNode` | - | The content to render in the panel trigger. |
diff --git a/.agents/skills/kaizen-ui/references/components/Skeleton.md b/.agents/skills/kaizen-ui/references/components/Skeleton.md
new file mode 100644
index 0000000..1e8ffc5
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Skeleton.md
@@ -0,0 +1,78 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Skeleton
+
+A skeleton component is a placeholder that mimics the layout of content while it loads, giving users a sense of the structure and reducing perceived wait time.
+Always try and make the skeleton components as simular in size and shape to the dynamic content as you can
+
+## Examples
+
+### Kinds Skeleton
+
+Pick a `kind` to match the shape of the content being loaded: `line` (default) for single-line text, `pill` for tags or badges, and `circle` for avatars or icons.
+
+```tsx
+<Stack gap="density-md">
+ <Skeleton kind="circle" />
+ <Skeleton kind="pill" />
+ <Skeleton kind="line" />
+ <Skeleton kind="line" />
+</Stack>
+```
+
+### Static Skeleton
+
+Set `animated={false}` when the skeleton flashes briefly or sits inside a surface that already conveys a loading state, where the pulse would be visual noise.
+
+```tsx
+<Skeleton kind="line" animated={false} />
+```
+
+### Inline Text Skeleton
+
+By default, the skeleton will inherit the surrounding font size — ideal for swapping in for a heading or label while its data resolves.
+
+```tsx
+<Text kind="title/lg">
+ <Skeleton />
+</Text>
+```
+
+### Sized Skeleton
+
+Override the default dimensions with `className` or `style` so the skeleton matches the exact size of the component it stands in for, like a large `Avatar` or icon.
+
+```tsx
+<Skeleton kind="circle" className="size-12" />
+```
+
+### Content Block Skeleton
+
+Compose multiple skeleton shapes inside layout primitives to mirror the rough size and rhythm of a content block so the page does not jump when real data loads in.
+
+```tsx
+<Stack gap="density-lg" style={{ maxWidth: '320px' }}>
+ <Skeleton kind="circle" />
+ <Skeleton kind="line" style={{ width: '66%' }} />
+ <Stack gap="density-sm">
+ <Skeleton kind="line" />
+ <Skeleton kind="line" />
+ <Skeleton kind="line" />
+ </Stack>
+ <Flex gap="density-sm" wrap="wrap">
+ <Skeleton kind="pill" />
+ <Skeleton kind="pill" />
+ </Flex>
+</Stack>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------- | ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| animated | `boolean` | `true` | If true, the Skeleton will pulse. All skeletons will pulse at the same rhythm |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| kind | `"circle" \| "line" \| "pill"` | `"line"` | The primary kind of skeleton to build a UI that best matches your component. - `line` - a horizontal line with hard corners and a 1.3em height, allowing it to size itself to the container font size dynamically - `pill` - a pill shape with a 64px width and rounded corners - `circle` - a circle with a 32px diameter |
diff --git a/.agents/skills/kaizen-ui/references/components/Slider.md b/.agents/skills/kaizen-ui/references/components/Slider.md
new file mode 100644
index 0000000..f530ebe
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Slider.md
@@ -0,0 +1,146 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Slider
+
+Also known as: Range Input, Input Range
+
+A slider component allows users to select a single value from a range of values.
+
+Sliders reflect a range of values along a bar, from which users may select a single value.
+They are ideal for adjusting settings such as volume, brightness,
+or applying image filters.
+
+## Examples
+
+### Basic Slider
+
+```tsx
+<Slider defaultValue={50} aria-label="Volume" />
+```
+
+### With Step Marks Slider
+
+Use step marks to show discrete positions and help users pick precise values.
+
+```tsx
+<Slider defaultValue={40} step={10} stepPosition="end" aria-label="Brightness" />
+```
+
+### Custom Range Slider
+
+Use custom min/max/step when the default 0–100 range does not match the domain.
+
+```tsx
+<Slider defaultValue={250} min={100} max={500} step={50} stepPosition="end" aria-label="Budget" />
+```
+
+### Disabled Slider
+
+Use when the slider value is locked and cannot be changed.
+
+```tsx
+<Slider defaultValue={30} disabled aria-label="Locked" />
+```
+
+### Vertical Slider
+
+Use vertical orientation for controls like volume faders or equalizer bands.
+
+```tsx
+<Slider
+ defaultValue={60}
+ orientation="vertical"
+ stepPosition="start"
+ step={20}
+ aria-label="Level"
+/>
+```
+
+### With Step Interval Slider
+
+Use stepInterval to space the visible step markers at a coarser interval than the slider's underlying step value, so users can drag with fine precision while still seeing key reference points.
+
+```tsx
+<Slider
+ defaultValue={50}
+ min={0}
+ max={100}
+ step={1}
+ stepInterval={20}
+ stepPosition="end"
+ aria-label="Precision control"
+/>
+```
+
+### With Custom Steps Slider
+
+Use customSteps when the meaningful tick positions are non-uniform or only certain anchor values matter (e.g. quality presets, named breakpoints). It overrides both step and stepInterval for marker placement.
+
+```tsx
+<Slider
+ defaultValue={50}
+ min={0}
+ max={100}
+ step={5}
+ customSteps={[0, 25, 50, 75, 100]}
+ stepPosition="end"
+ aria-label="Quality preset"
+/>
+```
+
+### With Formatted Steps Slider
+
+Use stepFormatFn to render step labels in a domain-specific format like currency, percentages, units, or descriptive words (e.g. Mute / Quiet / Loud). Works with both orientations.
+
+```tsx
+<Slider
+ defaultValue={60}
+ min={0}
+ max={100}
+ step={1}
+ stepInterval={20}
+ stepPosition="end"
+ stepFormatFn={value => `${value}°C`}
+ aria-label="Temperature"
+/>
+```
+
+### With Form Name Slider
+
+Set name to submit the slider value as a standard form field — the underlying native range input participates in form submission with no extra wiring.
+
+```tsx
+<Slider name="volume" defaultValue={50} step={10} stepPosition="end" aria-label="Volume" />
+```
+
+### Composed
+
+Use the composed primitives when you need full control over the slider track, input, and step label layout.
+
+```tsx
+<SliderRoot orientation="horizontal" aria-label="Custom slider">
+ <SliderInput defaultValue={50} min={0} max={100} step={25} />
+ <SliderSteps position="end" />
+</SliderRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| customSteps | `number[]` | - | Custom array of step values to display. When provided, overrides both step and stepInterval. |
+| defaultValue | `number` | - | The value of the slider when initially rendered. Use when you do not need to control the state of the slider. |
+| max | `number` | `100` | The maximum value for the range. |
+| min | `number` | `0` | The minimum value for the range. |
+| onValueChange | `(value: number) => void` | - | Event handler called when the value changes. |
+| onValueCommit | `(value: number) => void` | - | Event handler called when the value changes at the end of an interaction. Useful when you only need to capture a final value e.g. to update a backend service. |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider. |
+| step | `number` | `1` | The stepping interval. |
+| stepFormatFn | `(value: number) => string` | - | Callback function to format the step value before displaying it. |
+| stepInterval | `number` | - | The interval at which to display step markers. When not provided, uses the slider's step value. |
+| stepPosition | `"start" \| "end"` | - | |
+| value | `number` | - | The controlled value of the slider. Must be used in conjunction with `onValueChange`. |
diff --git a/.agents/skills/kaizen-ui/references/components/Spinner.md b/.agents/skills/kaizen-ui/references/components/Spinner.md
new file mode 100644
index 0000000..06d6bbc
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Spinner.md
@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Spinner
+
+Use a spinner when the user is waiting on an operation including loading, downloading, uploading, processing, etc. that's indeterminate.
+Spinners are displayed until content appears or a process is complete. This component should be used when the expected duration is more
+than a second and the completion time is short (up to 5 seconds). A message can be used with a spinner to improve understanding.
+
+## Examples
+
+### Basic Spinner
+
+Use when a process is indeterminate and no visible description is needed. An `aria-label` is required so screen readers announce the loading state.
+
+```tsx
+<Spinner aria-label="Loading" />
+```
+
+### Spinner With Description
+
+Use `slotDescription` when a visible message helps the user understand what is being loaded. The description also satisfies the accessible name, so `aria-label` is not needed.
+
+```tsx
+<Spinner slotDescription="Loading models..." />
+```
+
+### Spinner Sizes
+
+Pick the size to match the surrounding context: `small` (32px) for inline or in-button loading, `medium` (64px, default) for section-level waits, and `large` (128px) for full-page or empty-state loading.
+
+```tsx
+<div className="flex flex-col items-start gap-4">
+ <Spinner size="small" aria-label="Loading" />
+ <Spinner size="medium" aria-label="Loading" />
+ <Spinner size="large" aria-label="Loading" />
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------------------- | --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **slotDescription** \* | `ReactNode \| undefined \| never` | - | An optional message that is displayed below the spinner. If not provided, an `aria-label` must be added instead. |
+| aria-label | `never \| string` | - | Defines a string value that labels the current element. Accessible label for the spinner. If `slotDescription` is provided do not use this prop. |
+| description | `ReactNode` | - | |
+| size | `"small" \| "medium" \| "large"` | `'medium'` | The size of the Spinner - `small` - 32px - `medium` - 64px - `large` - 128px |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Stack.md b/.agents/skills/kaizen-ui/references/components/Stack.md
new file mode 100644
index 0000000..182663d
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Stack.md
@@ -0,0 +1,110 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Stack
+
+A container component for laying out content in a vertical or horizontal stack. This is a wrapper
+around the {@link Flex} component.
+
+## Notes
+
+- DO NOT add a single div to the Stack component, it is expected to have multiple children in a Stack.
+
+## Examples
+
+### Basic Stack
+
+```tsx
+<Stack padding="1" gap="2" style={{ border: '3px dotted var(--border-color-base)' }}>
+ <div>Item A</div>
+ <div>Item B</div>
+ <div>Item C</div>
+</Stack>
+```
+
+### Horizontal Stack
+
+```tsx
+<Stack direction="row" gap="2">
+ <div>Item A</div>
+ <div>Item B</div>
+ <div>Item C</div>
+</Stack>
+```
+
+### With Divider Stack
+
+Use slotDivider to automatically inject a separator between each child without manual repetition.
+
+```tsx
+<Stack gap="2" slotDivider={<Divider />}>
+ <div>Section A</div>
+ <div>Section B</div>
+ <div>Section C</div>
+</Stack>
+```
+
+### Aligned Stack
+
+Use align to position children along the cross-axis (e.g. center) when items have varying widths in a column or heights in a row.
+
+```tsx
+<Stack gap="2" align="center">
+ <div>Short</div>
+ <div>A longer item</div>
+ <div>Mid</div>
+</Stack>
+```
+
+### Justified Stack
+
+Use direction=row with justify=between to push siblings to opposite ends of a bar, the canonical pattern for toolbars and page headers.
+
+```tsx
+<Stack direction="row" justify="between">
+ <div>Leading</div>
+ <div>Trailing</div>
+</Stack>
+```
+
+## Props
+
+type SpacingScaleUnion
+
+Prefer semantic density tokens that adapt to the active density theme (compact, standard, spacious):
+"density-xxs" | "density-xs" | "density-sm" | "density-md" | "density-lg" | "density-xl" | "density-2xl" | "density-3xl" | "density-4xl" | "density-5xl"
+
+| Token | Compact | Standard | Spacious |
+| ----------- | ------- | -------- | -------- |
+| density-xxs | 1px | 2px | 4px |
+| density-xs | 2px | 4px | 6px |
+| density-sm | 4px | 6px | 8px |
+| density-md | 6px | 8px | 12px |
+| density-lg | 8px | 12px | 16px |
+| density-xl | 12px | 16px | 24px |
+| density-2xl | 16px | 24px | 32px |
+| density-3xl | 24px | 32px | 48px |
+| density-4xl | 32px | 48px | 64px |
+| density-5xl | 48px | 64px | 80px |
+
+Raw scale values (4px base unit — use only when density tokens don't fit):
+"0" | "0.25" | "0.5" | "0.75" | "1" | "1.5" | "2" | "2.5" | "3" | "3.5" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "14" | "16" | "18" | "20" | "24" | "28" | "32" | "36" | "40" | "44" | "48" | "52" | "56" | "60" | "64" | "72" | "80" | "96" | "250" | "inherit" | "px"
+
+| Prop | Type | Default | Description |
+| ------------- | -------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| align | `"center" \| "start" \| "end" \| "baseline" \| "stretch"` | `"stretch"` | Sets the alignment of child items along the block axis. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| direction | `"col" \| "row" \| "column" \| "row-reverse" \| "col-reverse" \| "column-reverse"` | `"col"` | Sets the direction in which child items are placed in the flex container. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more. |
+| gap | `SpacingScaleUnion` | - | Sets spacing between flex and grid items. |
+| justify | `"center" \| "start" \| "end" \| "normal" \| "stretch" \| "between" \| "around" \| "evenly"` | `"start"` | Sets distribution of space between and around content items along the main axis. See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more. |
+| padding | `SpacingScaleUnion` | - | Sets padding. |
+| paddingBottom | `SpacingScaleUnion` | - | Sets bottom padding. |
+| paddingLeft | `SpacingScaleUnion` | - | Sets left padding. |
+| paddingRight | `SpacingScaleUnion` | - | Sets right padding. |
+| paddingTop | `SpacingScaleUnion` | - | Sets top padding. |
+| paddingX | `SpacingScaleUnion` | - | Sets horizontal padding. |
+| paddingY | `SpacingScaleUnion` | - | Sets vertical padding. |
+| slotDivider | `ReactNode` | - | If provided, renders `slotDivider` between each child. |
+| wrap | `"wrap" \| "nowrap" \| "wrap-reverse"` | `"nowrap"` | Sets the wrapping behavior of the flex container. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more. |
diff --git a/.agents/skills/kaizen-ui/references/components/StatusIndicator.md b/.agents/skills/kaizen-ui/references/components/StatusIndicator.md
new file mode 100644
index 0000000..c33c5ef
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/StatusIndicator.md
@@ -0,0 +1,83 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# StatusIndicator
+
+A status indicator is a simple circle that is ephemeral and used to signal new changes or, occasionally, status.
+
+## Examples
+
+### Status Indicator Colors
+
+Map the `color` prop to semantic meaning: blue for new/info, red for error, yellow for warning, and green for success or healthy. Also supports custom colors via CSS.
+
+```tsx
+<Flex direction="col" gap="2">
+ <StatusIndicator color="blue" />
+ <StatusIndicator color="red" />
+ <StatusIndicator color="yellow" />
+ <StatusIndicator color="green" />
+ <StatusIndicator className="bg-accent-teal" />
+</Flex>
+```
+
+### Status Indicator Sizes
+
+Scale the `size` prop to match surrounding content — smaller for dense rows and inline use, larger for prominent dashboards or hero areas.
+
+```tsx
+<Flex align="center" gap="2">
+ <StatusIndicator size="small" />
+ <StatusIndicator size="medium" />
+ <StatusIndicator size="large" />
+ <StatusIndicator size="xlarge" />
+ <StatusIndicator size="xxlarge" />
+</Flex>
+```
+
+### Status Indicator On Icon
+
+Anchor the indicator over an icon with a relatively positioned wrapper to flag unread or actionable items like notifications.
+
+```tsx
+<div className="relative w-fit">
+ <Bell />
+ <StatusIndicator className="absolute top-0 right-0" size="medium" />
+</div>
+```
+
+### Status Indicator On Avatar
+
+Overlay an avatar with a green indicator to communicate a user's online or active presence.
+
+```tsx
+<div className="relative w-fit">
+ <Avatar fallback="NV" />
+ <StatusIndicator
+ className="absolute right-0.5 bottom-0.5 translate-x-1/2"
+ color="green"
+ size="medium"
+ />
+</div>
+```
+
+### Status Indicator With Label
+
+Pair the indicator with an inline text label whenever the status must be unambiguous and accessible to assistive tech — color alone is not enough.
+
+```tsx
+<Flex align="center" gap="2">
+ <StatusIndicator color="green" size="medium" />
+ <span>Stable</span>
+</Flex>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------- | --------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| color | `"blue" \| "green" \| "red" \| "yellow"` | `"red"` | The color of the status indicator |
+| size | `"small" \| "medium" \| "large" \| "xlarge" \| "xxlarge"` | `"medium"` | The size of the status indicator |
diff --git a/.agents/skills/kaizen-ui/references/components/StatusMessage.md b/.agents/skills/kaizen-ui/references/components/StatusMessage.md
new file mode 100644
index 0000000..c36bbd4
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/StatusMessage.md
@@ -0,0 +1,109 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# StatusMessage
+
+Use a status message when there is no data or content available. This helps inform users of the
+current status and suggests next steps when appropriate.
+
+## Notes
+
+- The primary CTA in an empty-state StatusMessage goes in slotFooter and should use Button with kind="primary" color="brand".
+
+## Examples
+
+### Basic Status Message
+
+Use when a page or section has no content to display, such as empty search results or a blank state.
+
+```tsx
+<StatusMessage
+ slotMedia={<Icon />}
+ slotHeading="No Results Found"
+ slotSubheading="Try adjusting your search or filter criteria."
+/>
+```
+
+### Small Status Message
+
+Use for small areas of a page or individual components like cards or side panels.
+
+```tsx
+<StatusMessage
+ size="small"
+ slotMedia={<Icon />}
+ slotHeading="No Items"
+ slotSubheading="This list is empty."
+/>
+```
+
+### With Footer Status Message
+
+Use when the empty state has actionable next steps the user can take.
+
+```tsx
+<StatusMessage
+ slotMedia={<Icon />}
+ slotHeading="Forbidden"
+ slotSubheading="You're not authorized to access this page."
+ slotFooter={
+ <>
+ <Button kind="tertiary">Back Home</Button>
+ <Button color="brand">Request Access</Button>
+ </>
+ }
+/>
+```
+
+### With Image Media Status Message
+
+Use an illustration instead of an icon for empty states that benefit from a richer visual; size the image explicitly since `slotMedia` only auto-sizes SVGs.
+
+```tsx
+<StatusMessage
+ slotMedia={
+ <img
+ src="/kaizen-ui-foundations/images/placeholder.png"
+ alt="Empty team illustration"
+ style={{ height: '160px', width: '160px' }}
+ />
+ }
+ slotHeading="No Team Members Yet"
+ slotSubheading="Start building your team by inviting colleagues."
+ slotFooter={<Button color="brand">Invite</Button>}
+/>
+```
+
+### Composed
+
+```tsx
+<StatusMessageRoot size="medium">
+ <StatusMessageMedia>
+ <Icon />
+ </StatusMessageMedia>
+ <StatusMessageHeader>
+ <StatusMessageHeading>No Team Members Yet</StatusMessageHeading>
+ <StatusMessageSubheading>
+ Start building your team by inviting colleagues.
+ </StatusMessageSubheading>
+ </StatusMessageHeader>
+ <StatusMessageFooter>
+ <Button color="brand">Invite</Button>
+ </StatusMessageFooter>
+</StatusMessageRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------------ | --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **slotHeading** \* | `ReactNode` | - | The content to render in the heading. Rendered with `body/bold/2xl` or `body/bold/xl` typography styles depending on the size of the status message. |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| size | `"small" \| "medium"` | `"medium"` | The size of the component. This will affect the size of the headig and subheading and the spacing between elements. - `small`: Use for small areas of a page or individual components (i.e., card, side panel) - `medium`: Use for large areas of the page (i.e., no search results. 404 page) |
+| slotFooter | `ReactNode` | - | The content to render in the footer. Handles the spacing and layout of footer items for you. |
+| slotMedia | `ReactNode` | - | Optional media content to render in the status message. Use this to display an icon or image. This handles sizing and coloring of SVGs automatically. |
+| slotSubheading | `ReactNode` | - | The content to render in the heading. Rendered with `body/regular/md` typography styles. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Stepper.md b/.agents/skills/kaizen-ui/references/components/Stepper.md
new file mode 100644
index 0000000..e659a20
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Stepper.md
@@ -0,0 +1,228 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Stepper
+
+A stepper (progress tracker) that visually represents a user's progress through a series of discrete steps.
+
+## Examples
+
+### Basic Stepper
+
+Use to visually represent progress through a multi-step process like a checkout or wizard flow.
+
+```tsx
+<Stepper
+ activeStep={1}
+ aria-label="Checkout progress"
+ items={[
+ { slotHeading: 'Cart', slotDescription: 'Review your items' },
+ { slotHeading: 'Shipping', slotDescription: 'Enter your address' },
+ { slotHeading: 'Payment', slotDescription: 'Complete purchase' }
+ ]}
+/>
+```
+
+### Vertical Stepper
+
+Use when steps have lengthy descriptions or content, or when the layout requires vertical stacking.
+
+```tsx
+<Stepper
+ layout="vertical"
+ activeStep={1}
+ aria-label="Setup wizard"
+ items={[
+ { slotHeading: 'Account', slotDescription: 'Create your account' },
+ { slotHeading: 'Profile', slotDescription: 'Set up your profile' },
+ { slotHeading: 'Review', slotDescription: 'Confirm your details' }
+ ]}
+/>
+```
+
+### Compact Stepper
+
+Use when space is limited and a minimal dot-based indicator is sufficient.
+
+```tsx
+<Stepper
+ kind="compact"
+ activeStep={1}
+ aria-label="Upload progress"
+ items={[
+ { slotHeading: 'Upload' },
+ { slotHeading: 'Process', slotDescription: 'Step 2 of 3' },
+ { slotHeading: 'Done' }
+ ]}
+/>
+```
+
+### Completed Stepper
+
+Use when all steps are complete by setting activeStep beyond the last index.
+
+```tsx
+<Stepper
+ activeStep={3}
+ aria-label="Completed flow"
+ items={[
+ { slotHeading: 'Step One' },
+ { slotHeading: 'Step Two' },
+ { slotHeading: 'Step Three' }
+ ]}
+/>
+```
+
+### With Error Stepper
+
+Use when a step has failed validation or encountered an error that needs user attention.
+
+```tsx
+<Stepper
+ activeStep={1}
+ aria-label="Deployment progress"
+ items={[
+ { slotHeading: 'Configure' },
+ { slotHeading: 'Validate', status: 'error' },
+ { slotHeading: 'Deploy' }
+ ]}
+/>
+```
+
+### With Content Stepper
+
+Use slotContent to render arbitrary content (such as the form fields for the active step) directly under each step. Only renders in the default (non-compact) kind.
+
+```tsx
+<Stepper
+ activeStep={1}
+ aria-label="Onboarding"
+ items={[
+ {
+ slotHeading: 'Account',
+ slotDescription: 'Account created.'
+ },
+ {
+ slotHeading: 'Profile',
+ slotDescription: 'Tell us about yourself.',
+ slotContent: <div>Profile form fields go here</div>
+ },
+ {
+ slotHeading: 'Review',
+ slotDescription: 'Confirm your details.'
+ }
+ ]}
+/>
+```
+
+### Clickable Nodes Stepper
+
+Use slotStepIndicator to make step nodes interactive (links or buttons) so users can navigate between steps. Completed steps still show the check icon while keeping the indicator clickable underneath.
+
+```tsx
+<Stepper
+ activeStep={1}
+ aria-label="Navigable progress"
+ items={[
+ {
+ slotHeading: 'Cart',
+ slotDescription: 'Review your items.',
+ slotStepIndicator: <a href="#cart">1</a>
+ },
+ {
+ slotHeading: 'Shipping',
+ slotDescription: 'Enter your address.',
+ slotStepIndicator: <a href="#shipping">2</a>
+ },
+ {
+ slotHeading: 'Payment',
+ slotDescription: 'Complete your purchase.',
+ slotStepIndicator: <a href="#payment">3</a>
+ }
+ ]}
+/>
+```
+
+### Compact Vertical Stepper
+
+Use to combine the compact dot indicator with vertical stacking — fits narrow side panels or sidebars where horizontal space is limited.
+
+```tsx
+<Stepper
+ layout="vertical"
+ kind="compact"
+ activeStep={1}
+ aria-label="Upload progress"
+ items={[
+ { slotHeading: 'Upload', slotDescription: 'Steps 1/3 completed.' },
+ { slotHeading: 'Process' },
+ { slotHeading: 'Review' }
+ ]}
+/>
+```
+
+### With Item Attributes Stepper
+
+Use the per-item `attributes` prop to attach analytics tags, custom data attributes, or override accessibility props on a specific step.
+
+```tsx
+<Stepper
+ activeStep={1}
+ aria-label="Deployment progress"
+ items={[
+ {
+ slotHeading: 'Build',
+ slotDescription: 'Compile artifacts.',
+ attributes: {
+ StepperItem: {
+ // @ts-expect-error - data attributes are not typed
+ 'data-analytics-id': 'build-step'
+ }
+ }
+ },
+ {
+ slotHeading: 'Test',
+ slotDescription: 'Run integration tests.',
+ attributes: {
+ StepperItem: {
+ // @ts-expect-error - data attributes are not typed
+ 'data-analytics-id': 'test-step'
+ }
+ }
+ },
+ {
+ slotHeading: 'Deploy',
+ slotDescription: 'Release to production.',
+ attributes: {
+ StepperItem: {
+ // @ts-expect-error - data attributes are not typed
+ 'data-analytics-id': 'deploy-step'
+ }
+ }
+ }
+ ]}
+/>
+```
+
+### Composed
+
+```tsx
+<StepperRoot activeStep={1} layout="horizontal" aria-label="Progress">
+ <StepperItem value={0} slotHeading="Step One" />
+ <StepperItem value={1} slotHeading="Step Two" slotDescription="Current step" />
+ <StepperItem value={2} slotHeading="Step Three" />
+</StepperRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------- |
+| **items** \* | `{ slotHeading: ReactNode; slotDescription: ReactNode; slotContent: ReactNode; slotStepIndicator: ReactNode; status: "error" }[]` | - | The items to render in the stepper. |
+| activeStep | `number` | `0` | The 0-based index of the currently active step. |
+| kind | `"default" \| "compact"` | `"default"` | The kind variant of the stepper. |
+| layout | `"horizontal" \| "vertical"` | `"horizontal"` | The layout direction of the stepper. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Switch.md b/.agents/skills/kaizen-ui/references/components/Switch.md
new file mode 100644
index 0000000..6acbbd0
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Switch.md
@@ -0,0 +1,107 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Switch
+
+Also known as: Toggle, ToggleSwitch
+
+A switch allows users to quickly switch between two states.
+
+Use a switch to allow users to turn something on or off instantly. Switches are only used with
+binary actions with a default setting set. It's commonly used for adjusting settings and
+preferences.
+
+## Notes
+
+- Switch is exclusively for immediate-effect toggles (value takes effect as soon as toggled). If the toggle sits inside a form with a submit button, or the value is only applied on save/submit, use Checkbox instead.
+
+## Examples
+
+### Basic Switch
+
+Use when toggling a binary setting that takes effect immediately.
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <Switch slotLabel="Off" />
+ <Switch defaultChecked slotLabel="On" />
+</Flex>
+```
+
+### Sizes Switch
+
+Use a single size consistently within a group. Default `medium` fits most settings rows; reach for `small` in dense toolbars and `large` for prominent toggles.
+
+```tsx
+<div className="flex flex-col items-start gap-4">
+ <Switch size="small" slotLabel="Small" />
+ <Switch size="medium" slotLabel="Medium" />
+ <Switch size="large" slotLabel="Large" />
+</div>
+```
+
+### Without Label Switch
+
+Use `aria-label` when the switch's purpose is conveyed by surrounding context (e.g. a settings row with its own heading) and a visible label would be redundant.
+
+```tsx
+<Switch aria-label="Enable notifications" onCheckedChange={checked => console.log(checked)} />
+```
+
+### Label Start Switch
+
+Use when aligning labels at the start for consistency in a settings list.
+
+```tsx
+<Switch slotLabel="Dark mode" labelSide="start" />
+```
+
+### Disabled Switch
+
+Use when a setting is locked by permissions or an external condition. Pair with a tooltip or helper text explaining why.
+
+```tsx
+<Tooltip slotContent="Maintenance mode is unavailable while jobs are running">
+ <Switch slotLabel="Maintenance mode" disabled defaultChecked />
+</Tooltip>
+```
+
+### Form Integration Switch
+
+Switch is a native HTML input element defaulting to `type='checkbox'`. Provide `name` and `value` so the switch participates in native form submission.
+
+```tsx
+<Switch name="notifications" value="enabled" slotLabel="Enable notifications" />
+```
+
+### As Radio Group Switch
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <Switch slotLabel="Option 1" type="radio" name="group" />
+ <Switch slotLabel="Option 2" type="radio" name="group" />
+ <Switch slotLabel="Option 3" type="radio" name="group" />
+</Flex>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the switch layout or label rendering.
+
+```tsx
+<SwitchRoot>
+ <SwitchInput aria-label="Enable feature" />
+</SwitchRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------- | -------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| labelSide | `"start" \| "end"` | `"end"` | Which side of the switch to render the label on. Ensure that all switches in a group are consistently aligned. |
+| onCheckedChange | `(checked: boolean) => void` | - | An event handler that's called when the state of the switch changes. |
+| side | `"start" \| "end"` | `"end"` | The side of the switch to render the label on. Ensure that all switches in a group are consistently aligned. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the switch. Use the same size when multiple switches are shown to create a uniform experience. |
+| slotLabel | `ReactNode` | - | A semantic label for the switch. The location of the label can be changed using the `labelSide` property. |
diff --git a/.agents/skills/kaizen-ui/references/components/Table.md b/.agents/skills/kaizen-ui/references/components/Table.md
new file mode 100644
index 0000000..6088119
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Table.md
@@ -0,0 +1,261 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Table
+
+A table organizes sets of data into columns and rows.
+
+## Notes
+
+- On list-view pages, render Table directly inside the main content area without wrapping it in a Panel. Panel adds card-in-page chrome that compresses row width. Panel-wrapping is only appropriate for dashboard table widgets.
+
+## Examples
+
+### Basic Table
+
+Use to display structured data in columns and rows for scanning and comparison.
+
+```tsx
+<Table
+ columns={['Name', 'Role', 'Status']}
+ rows={[
+ { id: '1', cells: ['Alice', 'Engineer', 'Active'] },
+ { id: '2', cells: ['Bob', 'Designer', 'Active'] }
+ ]}
+/>
+```
+
+### Hoverable Rows Table
+
+Use when rows are interactive or clickable and a hover state helps indicate interactivity.
+
+```tsx
+<Table
+ hoverableRows
+ columns={['Name', 'Role', 'Status']}
+ rows={[
+ { id: '1', cells: ['Alice', 'Engineer', 'Active'] },
+ { id: '2', cells: ['Bob', 'Designer', 'Active'] },
+ { id: '3', cells: ['Charlie', 'Manager', 'Inactive'] }
+ ]}
+/>
+```
+
+### Selectable Rows Table
+
+Use when users need to select rows for bulk actions or detail views.
+
+```tsx
+<Table
+ hoverableRows
+ columns={['Name', 'Email', 'Department']}
+ rows={[
+ {
+ id: '1',
+ cells: ['Alice', '[email protected]', 'Engineering'],
+ onRowSelect: handleRowSelect,
+ selected: true
+ },
+ {
+ id: '2',
+ cells: ['Bob', '[email protected]', 'Design'],
+ onRowSelect: handleRowSelect
+ },
+ {
+ id: '3',
+ cells: ['Charlie', '[email protected]', 'Product'],
+ onRowSelect: handleRowSelect
+ }
+ ]}
+/>
+```
+
+### Auto Layout Table
+
+Use when column widths should adapt to their content rather than being evenly distributed.
+
+```tsx
+<Table
+ layout="auto"
+ columns={['ID', 'Description', 'Updated']}
+ rows={[
+ { id: '1', cells: ['NV-001', 'GPU cluster provisioning', '2 hours ago'] },
+ {
+ id: '2',
+ cells: ['NV-002', 'Model training pipeline', '5 minutes ago']
+ }
+ ]}
+/>
+```
+
+### Compact Density Table
+
+Use when displaying dense data where vertical space is at a premium.
+
+```tsx
+<Table
+ density="compact"
+ columns={['Metric', 'Value', 'Change']}
+ rows={[
+ { id: '1', cells: ['Throughput', '1,200 req/s', '+12%'] },
+ { id: '2', cells: ['Latency', '45ms', '-3%'] },
+ { id: '3', cells: ['Error Rate', '0.02%', '-15%'] }
+ ]}
+/>
+```
+
+### Right Aligned Table
+
+Use right alignment for columns of numerical data so digits line up across rows for easier comparison.
+
+```tsx
+<Table
+ align="right"
+ columns={['Region', 'Requests', 'Latency']}
+ rows={[
+ { id: '1', cells: ['us-east-1', '1,204,310', '45ms'] },
+ { id: '2', cells: ['us-west-2', '982,117', '52ms'] },
+ { id: '3', cells: ['eu-central-1', '604,889', '61ms'] }
+ ]}
+/>
+```
+
+### Selectable Columns Table
+
+Use a column or cell object with onColumnSelect / onCellSelect when individual headers or cells need to be keyboard-focusable and interactive, for example to drive sorting or per-cell actions.
+
+```tsx
+<Table
+ columns={[
+ { children: 'Name', onColumnSelect: handleColumnSelect },
+ { children: 'Email', onColumnSelect: handleColumnSelect },
+ 'Role'
+ ]}
+ rows={[
+ {
+ id: '1',
+ cells: [
+ 'Jensen Huang',
+ { children: 'Admin', onCellSelect: handleCellSelect }
+ ]
+ },
+ {
+ id: '2',
+ cells: [
+ 'Cole Palmer',
+ { children: 'User', onCellSelect: handleCellSelect }
+ ]
+ }
+ ]}
+/>
+```
+
+### Rich Cells Table
+
+Use cell objects with a JSX children when a column needs to render rich content like avatars, badges, or inline action buttons rather than plain text.
+
+```tsx
+<Table
+ columns={['User', 'Status', 'Actions']}
+ rows={[
+ {
+ id: '1',
+ cells: [
+ {
+ children: (
+ <Flex gap="density-md" align="center">
+ <Avatar fallback="MW" />
+ <span>Matt Woppler</span>
+ </Flex>
+ )
+ },
+ {
+ children: (
+ <Badge color="green" kind="solid">
+ Active
+ </Badge>
+ )
+ },
+ {
+ children: (
+ <Button kind="secondary" size="small">
+ Edit
+ </Button>
+ )
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Toolbar Table
+
+Pair a Table with a TableToolbar to host primary actions and a bulk-action bar. Toggle showBulkActionsToolbar based on whether any rows are selected to swap between the two states.
+
+```tsx
+<div>
+ <TableToolbar
+ showBulkActionsToolbar
+ slotBulkActions={
+ <>
+ <Text>1 user selected</Text>
+ <Button color="danger" kind="tertiary">
+ Delete
+ </Button>
+ </>
+ }
+ >
+ <Text>1 user</Text>
+ <Button color="brand">Add New</Button>
+ </TableToolbar>
+ <Table
+ columns={['Name', 'Email']}
+ rows={[{ id: '1', cells: ['Jensen Huang', '[email protected]'] }]}
+ />
+</div>
+```
+
+### Composed
+
+```tsx
+<TableRoot hoverableRows>
+ <TableHead>
+ <TableRow>
+ <TableHeaderCell>Name</TableHeaderCell>
+ <TableHeaderCell>Role</TableHeaderCell>
+ <TableHeaderCell>Status</TableHeaderCell>
+ </TableRow>
+ </TableHead>
+ <TableBody>
+ <TableRow>
+ <TableDataCell>Alice</TableDataCell>
+ <TableDataCell>Engineer</TableDataCell>
+ <TableDataCell>Active</TableDataCell>
+ </TableRow>
+ <TableRow>
+ <TableDataCell>Bob</TableDataCell>
+ <TableDataCell>Designer</TableDataCell>
+ <TableDataCell>Active</TableDataCell>
+ </TableRow>
+ </TableBody>
+</TableRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **columns** \* | `string \| ({ children: ReactNode; onColumnSelect: (_: { columnIndex: number; }) => void })[]` | - | Definitions for each column in the table |
+| **rows** \* | `{ id: string; cells: string \| ({ children: ReactNode; onCellSelect: (_: { rowId?: string; columnIndex: number; }) => void })[]; onRowSelect: (_: { rowId?: string; }) => void; selected: boolean }[]` | - | Data for each row in the table |
+| align | `"center" \| "right" \| "left"` | `"left"` | Where to align table content. This will set alignment for all cells in the table. In general, textual data should be left-aligned and numerical data should be right-aligned. Consider how mixing different alignments across columns can affect readability. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard"` | The "density" of the component. This affects the padding/spacing of the component and its children. By default, the component will inherit density from its parent, which is usually `standard`. - Setting to `null` or `undefined` will allow the component to inherit density from its parent. - Setting to `compact` will reduce the padding/spacing of the component and its children. - Setting to `standard` will use the standard padding/spacing of the component and its children. - Setting to `spacious` will increase the padding/spacing of the component and its children. |
+| hoverableRows | `boolean` | `false` | Whether the table should have hover states for rows. |
+| layout | `"auto" \| "fixed"` | `"fixed"` | The layout variant for the table |
+| ref | `React.RefObject<HTMLTableElement> \| ((instance: HTMLTableElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; }))` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Tabs.md b/.agents/skills/kaizen-ui/references/components/Tabs.md
new file mode 100644
index 0000000..f91c906
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Tabs.md
@@ -0,0 +1,159 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Tabs
+
+A high-level tabs component that provides a simple way to create tabbed interfaces.
+Wraps the lower-level composed tab components for ease of use.
+
+## Examples
+
+### Basic Tabs
+
+Use when content is divided into related sections that users switch between.
+
+```tsx
+<Tabs
+ items={[
+ {
+ children: 'Account',
+ slotContent: 'Account settings content',
+ value: 'account'
+ },
+ {
+ children: 'Password',
+ slotContent: 'Password settings content',
+ value: 'password'
+ },
+ {
+ children: 'Notifications',
+ slotContent: 'Notification preferences',
+ value: 'notifications'
+ },
+ {
+ children: 'Disabled',
+ slotContent: 'Disabled tab content',
+ value: 'disabled',
+ disabled: true
+ },
+ {
+ children: 'Another',
+ slotContent: 'Another tab content',
+ value: 'another'
+ }
+ ]}
+/>
+```
+
+### Secondary Tabs
+
+Use for secondary-level tab navigation within a page section. `kind="tertiary"` renders a minimal text-only style for optional or supplementary content.
+
+```tsx
+<Tabs
+ kind="secondary"
+ items={[
+ {
+ children: 'Overview',
+ slotContent: 'Overview content',
+ value: 'overview'
+ },
+ { children: 'Details', slotContent: 'Details content', value: 'details' }
+ ]}
+/>
+```
+
+### With Links Tabs
+
+Use when tabs drive client-side navigation. Adding `href` to items renders the root as a `<nav>`; pass `renderLink` to swap the underlying anchor for a framework router component (Next.js `Link`, React Router `Link`, etc.).
+
+```tsx
+<Tabs
+ items={[
+ { children: 'Home', value: 'home', href: '/' },
+ { children: 'About', value: 'about', href: '/about' },
+ { children: 'Contact', value: 'contact', href: '/contact' }
+ ]}
+ // this renderLink is equivalent to the default behavior of the Tabs component
+ renderLink={item => <a href={item.href}>{item.children}</a>}
+/>
+```
+
+### With Slots Tabs
+
+Use `slotStart` / `slotEnd` to render labels, badges, or action buttons flanking the triggers inside the tabs list.
+
+```tsx
+<Tabs
+ items={[
+ { children: 'Tab 1', slotContent: 'Content 1', value: '1' },
+ { children: 'Tab 2', slotContent: 'Content 2', value: '2' }
+ ]}
+ slotStart={<span className="px-2 font-bold">Section</span>}
+ slotEnd={
+ <button type="button" className="ml-auto">
+ + Add
+ </button>
+ }
+/>
+```
+
+### Controlled Tabs
+
+Use controlled mode when tab content lives outside the `Tabs` component — e.g. when content is large or shared with other UI. Pass `value` + `onValueChange` and render the panels yourself instead of using `slotContent` per item.
+
+```tsx
+;() => {
+ const [value, setValue] = useState('account')
+ return (
+ <Flex direction="col" gap="3">
+ <Tabs
+ items={[
+ { children: 'Account', value: 'account' },
+ { children: 'Notifications', value: 'notifications' },
+ { children: 'Billing', value: 'billing' }
+ ]}
+ value={value}
+ onValueChange={setValue}
+ />
+ {value === 'account' && <Text>Account settings content</Text>}
+ {value === 'notifications' && <Text>Notification preferences content</Text>}
+ {value === 'billing' && <Text>Billing details content</Text>}
+ </Flex>
+ )
+}
+```
+
+### Composed
+
+```tsx
+<TabsRoot defaultValue="tab1">
+ <TabsList>
+ <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+ <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+ </TabsList>
+ <TabsContent value="tab1">Content for tab 1</TabsContent>
+ <TabsContent value="tab2">Content for tab 2</TabsContent>
+</TabsRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `{ asChild: boolean; children: ReactNode; slotContent: ReactNode; value: string; disabled: boolean; href: string }[]` | - | List of tabs to render |
+| activationMode | `"manual" \| "automatic"` | `"manual"` | Whether tabs activate automatically when they receive focus or require Enter/Space. |
+| defaultValue | `string` | `items[0]?.value` | The value of the tabs when initially rendered. Use when you do not need to control the state of the tabs. |
+| hideOverflowButtons | `boolean` | `false` | Hide the overflow scroll buttons |
+| kind | `"primary" \| "secondary" \| "tertiary"` | `"primary"` | Visual style variant of the tabs list |
+| onValueChange | `(value: string) => void` | - | Event handler called when the value changes |
+| ref | `((instance: HTMLDivElement) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; })) \| React.RefObject<HTMLDivElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| renderLink | `undefined \| (item: TabItem & { href: string; }) => ReactNode` | - | Render a custom link component for navigation mode. When provided, the root element will be a <nav>. When omitted, the root element will be a <div>. |
+| slotEnd | `ReactNode` | - | Content to display at the end of the tabs list. |
+| slotStart | `ReactNode` | - | Content to display at the start of the tabs list. |
+| value | `string` | - | The controlled value of the tabs. Must be used in conjunction with `onValueChange`. |
+| visibleRange | `number[]` | - | A range of indices to display, with ellipses for gaps. For example, [1,2,3,8,9,10] would show items 1-3, ellipsis, then 8-10. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Tag.md b/.agents/skills/kaizen-ui/references/components/Tag.md
new file mode 100644
index 0000000..1bf95c3
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Tag.md
@@ -0,0 +1,175 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Tag
+
+Tags are used to categorize, label, or group items using text and optional icons, providing users
+with quick, contextual information.
+
+## Notes
+
+- Tags should be label-only by default. Do not add icons unless the tag represents a typed entity (e.g., a person tag with an avatar).
+
+- Do not use Tag for multi-value table cells in dense data tables — pills compound into visual noise. Use plain text or Anchor components separated by commas instead.
+
+## Examples
+
+### Basic Tag
+
+Use outline tags when you need a lighter visual weight, such as in dense layouts or alongside solid tags for hierarchy.
+
+```tsx
+<Grid cols={2} gap="3" style={{ placeItems: 'center' }}>
+ <Tag color="blue">Tag Text</Tag>
+ <Tag color="blue" kind="outline">
+ Tag Text
+ </Tag>
+ <Tag color="green">Tag Text</Tag>
+ <Tag color="green" kind="outline">
+ Tag Text
+ </Tag>
+ <Tag color="yellow">Tag Text</Tag>
+ <Tag color="yellow" kind="outline">
+ Tag Text
+ </Tag>
+ <Tag color="red" disabled>
+ Tag Text
+ </Tag>
+ <Tag color="red" disabled kind="outline">
+ Tag Text
+ </Tag>
+</Grid>
+```
+
+### With Icon Tag
+
+Use when an icon reinforces the tag's meaning, such as a status or category indicator.
+
+```tsx
+<Tag>
+ <Icon />
+ Tag Text
+</Tag>
+```
+
+### Selected Tag
+
+Use to indicate the tag is actively selected in a filter or multi-select context. Automatically triggered by children that are `:checked` or `[data-state="checked"]` - use a hidden checkbox or radio input to control the state.
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <Tag selected>Selected</Tag>
+ <Tag asChild>
+ <label>
+ <input hidden type="checkbox" /> Checkbox
+ </label>
+ </Tag>
+ <Tag asChild>
+ <label>
+ <input hidden type="radio" /> Radio
+ </label>
+ </Tag>
+</Flex>
+```
+
+### Disabled Tag
+
+Use to communicate that an interactive tag is temporarily unavailable; pair with explanatory copy when the reason is not obvious.
+
+```tsx
+<Tag disabled>Disabled</Tag>
+```
+
+### Read Only Tag
+
+Use when the tag is informational only and should not be interactive, such as metadata labels. Tag will render as a `span` instead of a `button`.
+
+```tsx
+<Tag readOnly>Read Only</Tag>
+```
+
+### Colors Tag
+
+Pick a `color` to communicate semantic meaning — typically `green` for success, `red` for errors, `yellow` for warnings, and `blue` (default) for neutral or informational chips.
+
+```tsx
+<Flex gap="density-md" wrap="wrap">
+ <Tag color="blue">Blue</Tag>
+ <Tag color="gray">Gray</Tag>
+ <Tag color="green">Green</Tag>
+ <Tag color="purple">Purple</Tag>
+ <Tag color="red">Red</Tag>
+ <Tag color="teal">Teal</Tag>
+ <Tag color="yellow">Yellow</Tag>
+</Flex>
+```
+
+### Density Tag
+
+Use `compact` for dense data tables and filter bars, `spacious` for prominent filter chips or hero surfaces, and the default `standard` for general use. Note that density is also inherited from the parent container.
+
+```tsx
+<Flex align="center" gap="density-md">
+ <Tag density="compact">Compact</Tag>
+ <Tag>Standard</Tag>
+ <Tag density="spacious">Spacious</Tag>
+</Flex>
+```
+
+### Dismissible Tag
+
+Use a single tag with a trailing close icon when clicking anywhere on the tag should remove it, such as a list of applied filter chips.
+
+```tsx
+<Tag aria-label="Remove filter">
+ Filter
+ <CloseIcon />
+</Tag>
+```
+
+### Split Tag
+
+Wrap two adjacent tags in `Group` when the label and a secondary action (e.g. dismiss, edit) need separate click targets.
+
+```tsx
+<Group>
+ <Tag>Filter</Tag>
+ <Tag aria-label="Remove filter">
+ <CloseIcon />
+ </Tag>
+</Group>
+```
+
+### As Link Tag
+
+Use `asChild` with an anchor when the tag should navigate; the anchor inherits tag styling while staying keyboard-accessible.
+
+```tsx
+<Tag asChild>
+ <a href="/">Tag as Link</a>
+</Tag>
+```
+
+### Truncated Tag
+
+Tags wrap their content by default. Only wrap text in a `truncate` span when the tag width is constrained and wrapping is unacceptable; pair with a Tooltip so the full label stays reachable.
+
+```tsx
+<Tag title="Tag content that may be too long">
+ <Icon />
+ <span className="truncate">Tag content that may be too long</span>
+</Tag>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------- | ------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| color | `"blue" \| "green" \| "red" \| "yellow" \| "purple" \| "teal" \| "gray"` | `"blue"` | |
+| density | `"compact" \| "standard" \| "spacious"` | - | |
+| kind | `"outline" \| "solid"` | `"solid"` | The kind of tag. Can be either `solid` or `outline`. |
+| readOnly | `boolean` | - | Whether the tag is read-only. This will prevent the tag from being interacted with. When `readOnly` is true, the tag renders as a `<span>` instead of a `<button>`. |
+| selected | `boolean` | - | Whether or not the tag is selected. |
diff --git a/.agents/skills/kaizen-ui/references/components/Text.md b/.agents/skills/kaizen-ui/references/components/Text.md
new file mode 100644
index 0000000..446035f
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Text.md
@@ -0,0 +1,75 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Text
+
+A primitive component for displaying text.
+
+## Examples
+
+### Kinds Text
+
+Pick a `kind` from one of the five families: `display/*` for the largest hero text, `title/*` for headings, `body/*` for prose, `label/*` for short UI labels, and `mono/*` for code or technical identifiers. Each family offers multiple sizes and weights — see the `kind` type for the full set.
+
+```tsx
+<Stack gap="density-md">
+ <Text kind="display/lg">Display Heading</Text>
+ <Text kind="title/md">Section Title</Text>
+ <Text kind="body/regular/md">The quick brown fox jumps over the lazy dog</Text>
+ <Text kind="label/semibold/sm">Form Label</Text>
+ <Text kind="mono/md">console.log("hello")</Text>
+</Stack>
+```
+
+### Custom Styled Text
+
+Reach for the granular fontFamily, fontWeight, fontSize, lineHeight, and fontStyle props as an escape hatch when no predefined kind matches the design.
+
+```tsx
+<Text fontFamily="sans" fontWeight="semibold" fontSize="18" lineHeight="150" fontStyle="italic">
+ Custom typography
+</Text>
+```
+
+### Underlined Text
+
+Add the underline prop on top of any kind to flag inline emphasis like links or highlighted terms without changing the type style.
+
+```tsx
+<Text kind="body/regular/md" underline>
+ Underlined passage
+</Text>
+```
+
+### Inherit Kind Text
+
+Use kind="inherit" when Text is nested inside an element that already defines the type style (e.g. inside another Text or a styled heading) and you only need the Text primitive's other props.
+
+```tsx
+<Text kind="inherit">Inherits parent typography</Text>
+```
+
+### As Child Text
+
+Use asChild to apply Text styling to a semantic HTML element like h1–h6 without adding an extra wrapper.
+
+```tsx
+<Text asChild kind="title/lg">
+ <h1>Semantic Heading</h1>
+</Text>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| fontFamily | `"sans" \| "mono"` | - | The font family of the text. |
+| fontSize | `"10" \| "12" \| "14" \| "16" \| "18" \| "20" \| "22" \| "24" \| "28" \| "32" \| "36" \| "40" \| "44" \| "48" \| "50" \| "56" \| "60" \| "64" \| "72" \| "80"` | - | The font size of the text. |
+| fontStyle | `"normal" \| "italic"` | - | The font style of the text. |
+| fontWeight | `"bold" \| "light" \| "regular" \| "semibold"` | - | The font weight of the text. |
+| kind | `"inherit" \| "body/bold/2xl" \| "body/bold/3xl" \| "body/bold/lg" \| "body/bold/md" \| "body/bold/xl" \| "body/bold/sm" \| "body/bold/xs" \| "body/regular/lg" \| "body/regular/md" \| "body/regular/sm" \| "body/regular/xl" \| "body/regular/2xl" \| "body/regular/3xl" \| "body/regular/xs" \| "body/semibold/2xl" \| "body/semibold/3xl" \| "body/semibold/lg" \| "body/semibold/md" \| "body/semibold/sm" \| "body/semibold/xl" \| "body/semibold/xs" \| "display/2xl" \| "display/xl" \| "display/lg" \| "display/md" \| "display/sm" \| "display/xs" \| "label/bold/2xl" \| "label/bold/3xl" \| "label/bold/lg" \| "label/bold/md" \| "label/bold/sm" \| "label/bold/xl" \| "label/bold/xs" \| "label/light/lg" \| "label/light/xl" \| "label/light/2xl" \| "label/light/3xl" \| "label/light/md" \| "label/light/sm" \| "label/light/xs" \| "label/regular/lg" \| "label/regular/md" \| "label/regular/sm" \| "label/regular/xs" \| "label/regular/xl" \| "label/regular/2xl" \| "label/regular/3xl" \| "label/semibold/lg" \| "label/semibold/md" \| "label/semibold/sm" \| "label/semibold/xl" \| "label/semibold/2xl" \| "label/semibold/3xl" \| "label/semibold/xs" \| "mono/md" \| "mono/sm" \| "mono/lg" \| "mono/xl" \| "mono/2xl" \| "title/2xl" \| "title/xl" \| "title/lg" \| "title/md" \| "title/sm" \| "title/xs"` | `"label/regular/md"` | The kind of text to display. We offer a variety of groupings: - `display` - the largest text on the screen, use for short, important text or numerals - `title` - smaller than `display` - use for medium-emphasis text that remains relatively short - `body` - use for longer passages of text - `label` - use for short labels - `mono` - use for code or technical content Each of these groups has a variety of weights and sizes. If you want it to inherit the text style from its parent, you can use the `inherit` kind. |
+| lineHeight | `"100" \| "125" \| "150" \| "175"` | - | The line-height of the text. |
+| underline | `boolean` | - | Whether or not the text should be underlined. |
diff --git a/.agents/skills/kaizen-ui/references/components/TextArea.md b/.agents/skills/kaizen-ui/references/components/TextArea.md
new file mode 100644
index 0000000..dd1ced9
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/TextArea.md
@@ -0,0 +1,177 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# TextArea
+
+A textarea with additional capabilities such as icons and status.
+
+## Examples
+
+### Basic Text Area
+
+```tsx
+<TextArea defaultValue="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." />
+```
+
+### Controlled Text Area
+
+Controlled mode lets you manage value externally, useful for syncing with form libraries, character counters, or external validation.
+
+```tsx
+;() => {
+ const [value, setValue] = useState('')
+ return <TextArea value={value} onValueChange={setValue} placeholder="Type something" />
+}
+```
+
+### With Placeholder Text Area
+
+Use placeholder to hint at the expected format. Do not use it as a substitute for a label or required helper text.
+
+```tsx
+<TextArea placeholder="Enter a description..." />
+```
+
+### Auto Resize Text Area
+
+Use when the textarea should grow with content up to a max height, avoiding scrollbars for short entries. Override `--max-auto-height` (default 400px) to change the cap.
+
+```tsx
+<TextArea resizeable="auto" placeholder="Start typing..." />
+```
+
+### Manual Resize Text Area
+
+Use when the user should control the textarea height manually via a drag handle in the bottom-right corner.
+
+```tsx
+<TextArea resizeable="manual" placeholder="Drag to resize" />
+```
+
+### Size Text Area
+
+Match the textarea size to surrounding form controls. Default is `medium`.
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <TextArea size="small" placeholder="Small" />
+ <TextArea size="medium" placeholder="Medium" />
+ <TextArea size="large" placeholder="Large" />
+</Flex>
+```
+
+### Status Text Area
+
+Set `status` to drive validation styling manually — `error` for failed validation (pair with helper text on the wrapping FormField) or `success` to confirm a passing value. Reach for `withValidation` when native HTML constraints can drive the state automatically.
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <TextArea status="error" defaultValue="Invalid content" />
+ <TextArea status="success" defaultValue="Looks good" />
+</Flex>
+```
+
+### With Validation Text Area
+
+Set `withValidation` to drive status styling from the browser's native `:user-valid` / `:user-invalid` pseudo-classes — no JS state required. Combine with `required`, `minLength`, `maxLength`, etc.
+
+```tsx
+<TextArea withValidation required placeholder="Will turn red on blur if empty" />
+```
+
+### Disabled Text Area
+
+Use when the field is unavailable due to external state (e.g. permissions). Prefer `readOnly` when the value should still be selectable.
+
+```tsx
+<TextArea disabled defaultValue="Read-only content" />
+```
+
+### Read Only Text Area
+
+Use when the value should remain visible and copyable but cannot be edited — common in review or summary screens.
+
+```tsx
+<TextArea readOnly defaultValue="Read-only value" />
+```
+
+### With Slots Text Area
+
+Use `slotStart` / `slotEnd` to attach affordances like icons or action buttons. Use `mb-auto` / `mt-auto` utilities to anchor slot content to the top or bottom of a multi-line field.
+
+```tsx
+<TextArea
+ placeholder="Add a comment..."
+ slotStart={<Document className="mb-auto" />}
+ slotEnd={
+ <Button className="mt-auto" color="brand" size="small" aria-label="Send">
+ <ChevronRight />
+ </Button>
+ }
+/>
+```
+
+### Vertical Layout Text Area
+
+Use `layout="vertical"` to stack slot content above and below the textarea — ideal for chat composers, comment boxes, or toolbars that need full-width controls.
+
+```tsx
+<TextArea
+ layout="vertical"
+ placeholder="Compose your message..."
+ slotStart={
+ <Badge color="green" kind="solid">
+ Active
+ </Badge>
+ }
+ slotEnd={
+ <Flex gap="2" className="w-full">
+ <Button kind="tertiary" size="small" aria-label="Attach">
+ <Document />
+ </Button>
+ <Button className="ml-auto" color="brand" size="small" aria-label="Send">
+ <ChevronRight />
+ </Button>
+ </Flex>
+ }
+/>
+```
+
+### With Form Field Text Area
+
+Wrap TextArea in FormField to attach a label, helper text, and validation status that stay in sync with the field via context.
+
+```tsx
+<FormField slotLabel="Description" slotHelp="Your description will be used to generate a report.">
+ <TextArea placeholder="Enter your description" required />
+</FormField>
+```
+
+### Composed
+
+Use the composed primitives when you need full control over the shell and textarea element layout — for example, to mix the textarea with sibling buttons inside the same shell.
+
+```tsx
+<InputShell>
+ <TextAreaElement defaultValue="Composed primitives" resizeable="auto" />
+</InputShell>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | ------------------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| disableFocusRedirect | `boolean` | `false` | When true, the input will not redirect focus to the input when clicked. |
+| kind | `"flat" \| "floating"` | `"flat"` | The kind of input to render. - "flat" - renders with a border and background - "floating" - renders borderless with no background |
+| layout | `"horizontal" \| "vertical"` | `"horizontal"` | The layout direction for slotted content. - "horizontal" - children are laid out in a row (default) - "vertical" - children are laid out in a column with auto height and block padding |
+| onValueChange | `(value: string, event: React.ChangeEvent<HTMLTextAreaElement>) => void` | - | Convenience callback, provides the value as the first argument |
+| resizeable | `"auto" \| "manual"` | - | Controls the resize behavior of the text area. - `manual`: The text area can be manually resized vertically. - `auto`: The text area will be automatically resized to fit the content to a max height of `--max-auto-height` (400px by default). Set `--max-auto-height` to control the max height. - `undefined`: The text area will not be resizeable. |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the input to render. Available sizes are "small", "medium", and "large". |
+| slotEnd | `ReactNode` | - | Content to render on the end side of the textarea. By default this is the right, and `layout="vertical"` will have this on the bottom. |
+| slotStart | `ReactNode` | - | Content to render on the start side of the textarea. By default this is the left, and `layout="vertical"` will have this on the top. |
+| status | `"error" \| "success"` | - | The status of the input. Use `withValidation` to automatically apply success/error states based on `:user-valid` and `:user-invalid` pseudo classes. |
+| value | `string` | - | The value of the text area. Must be used in combination with `onChange/onValueChange` to ensure the value can be updated, otherwise this becomes read only. |
+| withValidation | `boolean` | - | When true, the input will automatically display success/error state based on `:user-valid` and `:user-invalid` styles |
diff --git a/.agents/skills/kaizen-ui/references/components/TextInput.md b/.agents/skills/kaizen-ui/references/components/TextInput.md
new file mode 100644
index 0000000..f9bd12a
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/TextInput.md
@@ -0,0 +1,177 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# TextInput
+
+This component is a composition of the `InputShell` and `input` components. The `ref` and HTML attributes are applied to the inner `input` component.
+
+## Notes
+
+- When used as a search input, always include a leading magnifying-glass icon via slotStart for affordance.
+
+## Examples
+
+### Basic Text Input
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <TextInput defaultValue="Hello, world!" />
+ <TextInput type="time" />
+</Flex>
+```
+
+### With Slots Text Input
+
+Use slotStart for affordance icons (e.g. a magnifying glass for search) and slotEnd for trailing hints like result counts or unit labels.
+
+```tsx
+<TextInput slotStart={<Bell />} slotEnd={<span>(7)</span>} defaultValue="admin" />
+```
+
+### Dismissible Text Input
+
+Use when the user needs a quick way to clear the field, such as search inputs.
+
+```tsx
+<TextInput dismissible defaultValue="Clearable value" />
+```
+
+### Read Only Text Input
+
+Use readOnly (instead of disabled) when the value should remain visible, focusable, and copyable but not editable — common in summary or review screens.
+
+```tsx
+<TextInput readOnly value="Read-only value" />
+```
+
+### Disabled Text Input
+
+Use when the field value is locked by external conditions and cannot be changed.
+
+```tsx
+<TextInput disabled defaultValue="Cannot edit" />
+```
+
+### Size Text Input
+
+Match the input size to surrounding controls — small for dense tables/toolbars, large for hero search bars or onboarding forms.
+
+```tsx
+<Stack gap="density-md">
+ <TextInput size="small" placeholder="Small" />
+ <TextInput size="medium" placeholder="Medium" />
+ <TextInput size="large" placeholder="Large" />
+</Stack>
+```
+
+### Status Text Input
+
+Set `status` to drive validation styling manually — `error` for failed validation or `success` to confirm a passing value. Reach for `withValidation` when native HTML constraints can drive the state automatically.
+
+```tsx
+<Stack gap="density-md">
+ <TextInput status="error" defaultValue="invalid-email" />
+ <TextInput status="success" defaultValue="[email protected]" />
+</Stack>
+```
+
+### With Validation Text Input
+
+Use withValidation to drive success/error styling automatically from native HTML constraints (`required`, `pattern`, `type="email"`, etc.) via `:user-valid` and `:user-invalid` — no controlled state needed.
+
+```tsx
+<TextInput withValidation required type="email" placeholder="[email protected]" />
+```
+
+### Date Text Input
+
+Use type="date" or type="datetime-local" to render a calendar button that opens the browser's native picker via `showPicker()`.
+
+```tsx
+<Stack gap="density-md">
+ <TextInput type="date" />
+ <TextInput type="datetime-local" />
+</Stack>
+```
+
+### Time Text Input
+
+Use for time selection with a native picker button. Set step={60} to hide seconds.
+
+```tsx
+<TextInput type="time" step={60} />
+```
+
+### With Form Field Text Input
+
+Wrap in FormField to attach a label, helper text, and required indicator. FormField pipes `id`, `name`, `required`, and validation status into the input via context.
+
+```tsx
+<FormField
+ name="username"
+ slotLabel="Username"
+ slotHelp="3–20 characters, letters and numbers only."
+ required
+>
+ <TextInput placeholder="Enter your username" />
+</FormField>
+```
+
+### Controlled Text Input
+
+Use controlled mode when state lives outside the input — e.g. when syncing with form libraries or URL state.
+
+```tsx
+;() => {
+ const [value, setValue] = useState('')
+ return <TextInput value={value} onValueChange={setValue} placeholder="Type something" />
+}
+```
+
+### Debounced Text Input
+
+Combine with `useDebounce` to throttle expensive work like API calls or filtering driven by the input value.
+
+```tsx
+;() => {
+ const [value, setValue] = useState('')
+ const debounced = useDebounce(value, 500)
+ return (
+ <Stack gap="density-md">
+ <TextInput value={value} onValueChange={setValue} placeholder="Search..." />
+ <Text>Debounced: {debounced}</Text>
+ </Stack>
+ )
+}
+```
+
+### Composed
+
+Drop down to InputShell + a raw `<input>` when you need full control over slot content, ARIA, or non-standard layouts that TextInput's API doesn't expose.
+
+```tsx
+<InputShell>
+ <Bell />
+ <input type="text" placeholder="Composed text input" />
+</InputShell>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | --------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| disableFocusRedirect | `boolean` | `false` | When true, the input will not redirect focus to the input when clicked. |
+| dismissible | `boolean` | - | When set to `true`, the TextInput will render a dismiss button that will clear and focus the input on click |
+| kind | `"flat" \| "floating"` | `"flat"` | The kind of input to render. - "flat" - renders with a border and background - "floating" - renders borderless with no background |
+| layout | `"horizontal" \| "vertical"` | `"horizontal"` | The layout direction for slotted content. - "horizontal" - children are laid out in a row (default) - "vertical" - children are laid out in a column with auto height and block padding |
+| onDismiss | `(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void` | - | Handler to override the default onDismiss functionality |
+| onValueChange | `(value: string, event: React.ChangeEvent<HTMLInputElement>) => void` | - | Convenience callback, provides the value as the first argument |
+| size | `"small" \| "medium" \| "large"` | `"medium"` | The size of the input to render. Available sizes are "small", "medium", and "large". |
+| slotEnd | `ReactNode` | - | Content to render on the end side of the input. By default this is the right, and `layout="vertical"` will have this on the bottom. |
+| slotStart | `ReactNode` | - | Content to render on the start side of the input. By default this is the left, and `layout="vertical"` will have this on the top. For `type="time"`, `type="date"`, and `type="datetime-local"`, a picker button is always rendered first; when `slotStart` is set, it renders after that button. |
+| status | `"error" \| "success"` | - | The status of the input. Use `withValidation` to automatically apply success/error states based on `:user-valid` and `:user-invalid` pseudo classes. |
+| value | `string` | - | The value of the text input. Must be used in combination with `onChange/onValueChange` to ensure the value can be updated, otherwise this becomes read only. |
+| withValidation | `boolean` | - | When true, the input will automatically display success/error state based on `:user-valid` and `:user-invalid` styles |
diff --git a/.agents/skills/kaizen-ui/references/components/ThemeProvider.md b/.agents/skills/kaizen-ui/references/components/ThemeProvider.md
new file mode 100644
index 0000000..eb435cc
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/ThemeProvider.md
@@ -0,0 +1,116 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# ThemeProvider
+
+A comprehensive theme provider that manages both density (spacing) and theme (light/dark) themes
+for all child components. This component:
+
+- Sets density variants that control spacing throughout child components
+- Manages color themes with support for system preference detection
+- Controls motion and animations with support for accessibility preferences
+- Applies theme classes to the provider element for scoped theming (only when explicitly provided or inherited)
+- Provides theme context to all descendant components via React Context
+- Handles system theme changes and updates the UI accordingly
+- Supports nesting with automatic inheritance from parent providers
+
+When nested, child providers inherit density, theme, and defer settings from their parent unless
+explicitly overridden. If no theme is provided and there's no parent context,
+no theme class is applied, allowing manually set theme classes to take precedence.
+This allows for granular theme control in different sections of the application
+while maintaining consistent defaults and not overriding external theme solutions.
+
+## Notes
+
+- If using the ThemeProvider to provide themes for the entire application, you should use the
+ `global` prop to apply the theme classes to the `html` element. This will ensure portal'd components are also themed.
+
+## Examples
+
+### Basic Theme Provider
+
+```tsx
+<ThemeProvider density="compact">Density-aware children</ThemeProvider>
+```
+
+### Basic usage with density control:
+
+```tsx
+<ThemeProvider density="compact">
+ <Modal>
+ <ModalContent>
+ <Panel>
+ <Tag>Content</Tag>
+ </Panel>
+ </ModalContent>
+ </Modal>
+</ThemeProvider>
+```
+
+### Full theme management with theme control:
+
+```tsx
+<ThemeProvider density="standard" theme="system" motion="system">
+ <Header />
+ <MainContent />
+ <Footer />
+</ThemeProvider>
+```
+
+### Forcing a specific theme:
+
+```tsx
+<ThemeProvider theme="dark">
+ <DarkModeSpecificComponent />
+</ThemeProvider>
+```
+
+### Nested providers with inheritance:
+
+```tsx
+<ThemeProvider density="compact" theme="system" motion="system" defer>
+ <GlobalLayout>
+ {// This provider inherits compact density, system theme, system motion, and defer}
+ <ThemeProvider theme="dark" motion="disabled">
+ <Sidebar /> {// Uses compact density (inherited) + dark theme + disabled motion + defer (inherited)}
+ </ThemeProvider>
+
+ {// This provider inherits all settings from parent}
+ <ThemeProvider>
+ <MainContent /> {// Uses compact density + system theme + system motion + defer}
+ </ThemeProvider>
+ </GlobalLayout>
+</ThemeProvider>
+```
+
+### Respecting external theme classes:
+
+```tsx
+{// When no parent context and no explicit theme, allows external classes}
+<div className="nv-dark">
+ <ThemeProvider>
+ <Component /> {// Respects the manually set nv-dark class}
+ </ThemeProvider>
+</div>
+
+{// But explicit theme still takes precedence}
+<div className="nv-dark">
+ <ThemeProvider theme="light">
+ <Component /> {// Applies nv-light, overriding manual class}
+ </ThemeProvider>
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------- | --------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| defer | `boolean` | `false (or inherited from parent)` | Whether to defer the theme change until SSR hydration. This can be useful for integration with other theme provider solutions like `next-themes`. |
+| density | `"compact" \| "standard" \| "spacious"` | `"standard" (or inherited from parent)` | The density variant that controls spacing throughout child components. This affects the density of all child components that would normally have a `spacing` prop. - "spacious": Maximum spacing for accessibility and touch interfaces - "compact": Minimal spacing for information-dense layouts - "standard": Default balanced spacing for general use When nested, inherits from parent ThemeProvider if not specified. |
+| global | `boolean` | `false` | Whether this provider should manage global theme state by applying classes to DOM elements. When true, theme and density changes are applied to the specified target element (html or body). |
+| motion | `"disabled" \| "system"` | `"system" (or inherited from parent)` | The motion preference for animations and transitions. - "disabled": Force disable all animations and transitions - "system": Automatically follow the user's prefers-reduced-motion preference When nested, inherits from parent ThemeProvider if not specified. |
+| target | `"body" \| "html"` | `"html"` | The target element to apply theme classes to when global is true. Only used when global=true. |
+| theme | `"light" \| "dark" \| "system"` | `inherited from parent, or no theme class if no parent` | The theme theme for the application. - "light": Force light theme regardless of system preference - "dark": Force dark theme regardless of system preference - "system": Automatically follow the user's system preference When nested, inherits from parent ThemeProvider if not specified. If no theme is provided and there's no parent context, no theme class is applied, allowing manually set theme classes to take precedence. |
diff --git a/.agents/skills/kaizen-ui/references/components/Toast.md b/.agents/skills/kaizen-ui/references/components/Toast.md
new file mode 100644
index 0000000..76a5f1d
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Toast.md
@@ -0,0 +1,114 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Toast
+
+Use a toast to display small messages without disrupting a user's experience. Toasts are commonly
+used to provide non-critical, contextual feedback following a user's action or process. They're
+low-emphasis and appear temporarily as an overlay.
+
+## Notes
+
+- Do not use Toast for errors, warnings, or any message requiring user action — Toast should auto-dismiss. Use Notification or Banner instead for actionable messages.
+
+## Examples
+
+### Statuses Toast
+
+Set `status` to convey severity: `info` for neutral confirmation, `success` for completed actions, `warning` to caution about a degraded condition, and `error` for failures that need corrective action.
+
+```tsx
+<Flex direction="col" gap="density-md">
+ <Toast status="info">Operation completed</Toast>
+ <Toast status="success">Changes saved</Toast>
+ <Toast status="warning">Connection unstable</Toast>
+ <Toast status="error">Upload failed</Toast>
+</Flex>
+```
+
+### Dismissible Toast
+
+Use when the user should be able to manually dismiss the toast before it auto-hides.
+
+```tsx
+<Toast status="info" onClose={handleClose}>
+ Session expiring soon
+</Toast>
+```
+
+### With Action Toast
+
+Use when the toast should offer an inline action for the user to respond to the message.
+
+```tsx
+<Toast
+ status="error"
+ onClose={handleClose}
+ slotAction={
+ <Button kind="tertiary" size="small">
+ Retry
+ </Button>
+ }
+>
+ Upload failed
+</Toast>
+```
+
+### Working Toast
+
+Use to indicate that a background process is actively running.
+
+```tsx
+<Toast status="working">Processing request</Toast>
+```
+
+### With Custom Icon Toast
+
+Use `slotIcon` to override the default status icon when a domain-specific glyph communicates the message better.
+
+```tsx
+<Toast status="success" slotIcon={<Bell />}>
+ Reminder scheduled
+</Toast>
+```
+
+### With Title Toast
+
+Set the native `title` attribute so the full message is available on hover when the toast text is long enough to truncate.
+
+```tsx
+<Toast status="info" title="Deployment finished in 3m 24s across 4 regions">
+ Deployment finished in 3m 24s across 4 regions
+</Toast>
+```
+
+### Composed
+
+Use composed primitives when you need full control over the toast layout, icon, and actions.
+
+```tsx
+<ToastRoot status="success">
+ <ToastContent>
+ <ToastIcon status="success" />
+ <ToastText>Composed toast message</ToastText>
+ </ToastContent>
+ <ToastActions>
+ <Button kind="tertiary" size="small">
+ Undo
+ </Button>
+ </ToastActions>
+</ToastRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---------- | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| children | `ReactNode` | - | The message to display in the toast. Toast messages should use brief and direct text, no more than 4 words. |
+| onClose | `() => void` | - | A callback to be called when the toast is closed. |
+| slotAction | `ReactNode` | - | Slot for the action to render in the toast. Should consist of a `size="small"` button. |
+| slotIcon | `ReactNode` | - | Slot for the icon to render in the toast. |
+| status | `"neutral" \| "error" \| "warning" \| "success" \| "info" \| "working"` | `"info"` | The status of the toast. The toast can be either info, success, warning, error, neutral, or working. - `info`: Provides additional information that may require action - `success`: Confirms to the user that they have completed an action or task - `warning`: Cautions the user on something urgent to avoid an issue - `error`: Communicates a critical issue that needs attention and provides a next step - `neutral`: Provides general information - `working`: Communicates a process is actively taking place |
diff --git a/.agents/skills/kaizen-ui/references/components/Tooltip.md b/.agents/skills/kaizen-ui/references/components/Tooltip.md
new file mode 100644
index 0000000..12b02b0
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Tooltip.md
@@ -0,0 +1,124 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Tooltip
+
+A tooltip displays additional information when users hover or focus on an element.
+To remove the delay on hover when switching between different tooltips, it is highly recommended
+to wrap your application in a `TooltipProvider` component.
+
+Built on the native Popover API and CSS Anchor Positioning for progressive
+enhancement. Hover and focus interactions are managed with lightweight
+JavaScript; uncontrolled tooltips also render a no-JS click target during SSR.
+
+## Examples
+
+### Basic Tooltip
+
+```tsx
+<Tooltip slotContent="Helpful tooltip text">
+ <button type="button">Hover me</button>
+</Tooltip>
+```
+
+### Positioning Tooltip
+
+Combine `side` (`top` | `bottom` | `left` | `right`) and `align` (`start` | `center` | `end`) to control where the tooltip renders. Override the defaults when the trigger sits near a viewport edge or when wider tooltip content would clip with centered alignment.
+
+```tsx
+<Tooltip align="start" side="bottom" slotContent="Start-aligned tooltip">
+ <button type="button">Aligned start</button>
+</Tooltip>
+```
+
+### Disabled Trigger Tooltip
+
+Wrap a disabled Button to explain why the action is unavailable. Tooltip routes hover and focus through a focusable wrapper since disabled controls don't fire pointer or focus events.
+
+```tsx
+<Tooltip slotContent="You don't have permission to perform this action.">
+ <Button disabled>Save</Button>
+</Tooltip>
+```
+
+### Conditional Tooltip
+
+Toggle the disabled prop to suppress the tooltip without unmounting it. Useful when the tooltip should only appear in certain runtime states (e.g. `disabled={!isReadOnly}`).
+
+```tsx
+<Tooltip disabled slotContent="Hidden while disabled is true">
+ <Button>Always enabled</Button>
+</Tooltip>
+```
+
+### With Icon Trigger Tooltip
+
+Pair a tooltip with an icon-only button to surface an accessible label without consuming layout space. Always provide aria-label on the trigger so assistive tech still announces it.
+
+```tsx
+<Tooltip slotContent="Get help with this feature">
+ <Button aria-label="Help" kind="tertiary" size="small">
+ <InfoCircle />
+ </Button>
+</Tooltip>
+```
+
+### Max Width Tooltip
+
+Apply a max-width utility via className when the tooltip content is long enough to wrap. Prevents the tooltip from stretching across the viewport.
+
+```tsx
+<Tooltip
+ className="max-w-[200px]"
+ slotContent="This is a longer tooltip message that demonstrates how to constrain the maximum width so multi-line content stays readable."
+>
+ <button type="button">Long tooltip</button>
+</Tooltip>
+```
+
+### With Provider Tooltip
+
+Wrap your app in TooltipProvider to remove the hover delay when moving between adjacent tooltips.
+
+```tsx
+<TooltipProvider>
+ <Tooltip slotContent="First tooltip">
+ <button type="button">First</button>
+ </Tooltip>
+</TooltipProvider>
+```
+
+### Composed
+
+Use composed primitives when you need full control over trigger and content rendering.
+
+```tsx
+<TooltipProvider>
+ <TooltipRoot>
+ <TooltipTrigger aria-label="Help">
+ <InfoCircle />
+ </TooltipTrigger>
+ <TooltipContent>Composed tooltip content</TooltipContent>
+ </TooltipRoot>
+</TooltipProvider>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------------- | ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| align | `"center" \| "start" \| "end"` | `"center"` | The preferred alignment against the trigger. May change when collisions occur. |
+| asChild | `boolean` | - | When true, treats the immediate child as the host element, merging this component's props with the child's props. The child's children will be slotted into the component's defined content placement. |
+| defaultOpen | `boolean` | - | The open state of the tooltip when it is initially rendered. Use when you do not need to control its open state. |
+| disabled | `boolean` | - | If true, the tooltip will be disabled and will not appear. Use this to conditionally render a tooltip. |
+| id | `string` | - | A stable identifier used to derive the tooltip content id and CSS anchor name. Provide this when rendering in SSR-sensitive trees to ensure the generated ids remain consistent between server and client. |
+| onEscapeKeyDown | `(event: KeyboardEvent) => void` | - | Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. |
+| onOpenChange | `(open: boolean) => void` | - | Event handler called when the open state of the tooltip changes. |
+| onPointerDownOutside | `(event: Event) => void` | - | Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
+| open | `boolean` | - | The controlled open state of the tooltip. Must be used in conjunction with `onOpenChange`. |
+| openDelayDuration | `number` | `100` | The duration from when the mouse enters a tooltip trigger until the tooltip opens. |
+| positionAnchor | `string` | - | The CSS anchor name to position this tooltip against. This should match the `anchorName` prop on the corresponding `TooltipTrigger`. When not provided, uses the auto-generated anchor name from `TooltipRoot` context. |
+| side | `"right" \| "bottom" \| "left" \| "top"` | `"top"` | The preferred side of the trigger to render the tooltip. |
+| slotContent | `ReactNode` | - | The content of the tooltip. The Tooltip component takes care of the text styling and spacing for you. You may wish to limit the width of the tooltip to ensure readability. |
diff --git a/.agents/skills/kaizen-ui/references/components/TreeNav.md b/.agents/skills/kaizen-ui/references/components/TreeNav.md
new file mode 100644
index 0000000..5c03d7b
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/TreeNav.md
@@ -0,0 +1,307 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# TreeNav
+
+A tree navigation component that lets users move through links at different
+levels, like a directory structure. Uses native `<details>`/`<summary>`
+elements for zero-JS expand/collapse behavior.
+
+Branches containing an active descendant are automatically expanded unless
+they use controlled state (`open` prop) or have an explicit `defaultOpen`.
+
+## Examples
+
+### Basic Tree Nav
+
+Use for hierarchical navigation structures like file trees or nested categories.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'src',
+ children: 'src',
+ defaultOpen: true,
+ items: [
+ { id: 'index', children: 'index.ts', href: '#index' },
+ { id: 'utils', children: 'utils.ts', href: '#utils' }
+ ]
+ },
+ { id: 'readme', children: 'README.md', href: '#readme' }
+ ]}
+/>
+```
+
+### With Icons Tree Nav
+
+Pass `slotIcon` on any item to add an icon to a branch trigger or override the default document icon on a leaf.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'inbox',
+ children: 'Inbox',
+ slotIcon: <Bell />,
+ defaultOpen: true,
+ items: [
+ {
+ id: 'drafts',
+ children: 'Drafts',
+ slotIcon: <CopyDoc />,
+ href: '#drafts'
+ },
+ {
+ id: 'scheduled',
+ children: 'Scheduled',
+ slotIcon: <Calendar />,
+ href: '#scheduled'
+ }
+ ]
+ },
+ {
+ id: 'trash',
+ children: 'Trash',
+ slotIcon: <Trash />,
+ href: '#trash'
+ }
+ ]}
+/>
+```
+
+### With Default Open Tree Nav
+
+Set `defaultOpen` on a branch to render it expanded on initial mount while still allowing the user to collapse it.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'src',
+ children: 'src',
+ defaultOpen: true,
+ items: [
+ { id: 'index', children: 'index.ts', href: '#index' },
+ {
+ id: 'components',
+ children: 'components',
+ items: [{ id: 'button', children: 'Button.tsx', href: '#button' }]
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Active Item Tree Nav
+
+Use when the current location should be highlighted. Branches with active descendants auto-expand.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'docs',
+ children: 'docs',
+ items: [
+ {
+ id: 'getting-started',
+ children: 'Getting Started',
+ href: '#getting-started',
+ active: true
+ },
+ { id: 'api', children: 'API Reference', href: '#api' }
+ ]
+ },
+ { id: 'changelog', children: 'Changelog', href: '#changelog' }
+ ]}
+/>
+```
+
+### With Disabled Items Tree Nav
+
+Set `disabled` on a leaf to make it non-interactive, or on a branch to disable the entire subtree — descendants inherit the disabled state.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'archive',
+ children: 'Archive (read-only)',
+ disabled: true,
+ defaultOpen: true,
+ items: [{ id: 'old', children: 'old-file.ts', href: '#old' }]
+ },
+ {
+ id: 'src',
+ children: 'src',
+ defaultOpen: true,
+ items: [
+ { id: 'app', children: 'App.tsx', href: '#app' },
+ {
+ id: 'deprecated',
+ children: 'deprecated.ts',
+ href: '#deprecated',
+ disabled: true
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Loading State Tree Nav
+
+Set `loading` on an item to replace its icon with a spinner — typically combined with `onOpenChange` or `onSelect` to drive async data fetches.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'api',
+ children: 'api',
+ defaultOpen: true,
+ loading: true,
+ items: [
+ {
+ id: 'routes',
+ children: 'Fetching routes.ts...',
+ href: '#routes',
+ loading: true
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Event Handlers Tree Nav
+
+Use `onSelect` on leaves to react to clicks (analytics, tracking) and `onOpenChange` on branches to react to expand/collapse without taking control of the open state.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'src',
+ children: 'src',
+ defaultOpen: true,
+ onOpenChange: handleOpenChange,
+ items: [
+ {
+ id: 'app',
+ children: 'App.tsx',
+ href: '#app',
+ onSelect: handleSelect
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### Controlled Tree Nav
+
+Pass both `open` and `onOpenChange` to drive branch expansion from external state (Redux, URL, parent component, etc.) instead of letting the component manage it.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'src',
+ children: 'src',
+ open: true,
+ onOpenChange: handleOpenChange,
+ items: [{ id: 'app', children: 'App.tsx', href: '#app' }]
+ },
+ {
+ id: 'lib',
+ children: 'lib',
+ open: false,
+ onOpenChange: handleOpenChange,
+ items: [{ id: 'utils', children: 'utils.ts', href: '#utils' }]
+ }
+ ]}
+/>
+```
+
+### Non Collapsible Branch Tree Nav
+
+Use when a branch should always remain expanded and cannot be collapsed by the user — useful for top-level categories that anchor the navigation.
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'root',
+ children: 'Project Root',
+ collapsible: false,
+ items: [
+ { id: 'package', children: 'package.json', href: '#package' },
+ { id: 'tsconfig', children: 'tsconfig.json', href: '#tsconfig' }
+ ]
+ }
+ ]}
+/>
+```
+
+### With Render Link Tree Nav
+
+Use `renderLink` to swap the built-in `<a>` for a framework router link (Next.js `<Link>`, React Router `<NavLink>`, TanStack Router, etc.).
+
+```tsx
+<TreeNav
+ items={[
+ {
+ id: 'pages',
+ children: 'pages',
+ defaultOpen: true,
+ items: [
+ { id: 'home', children: 'Home', href: '/home' },
+ { id: 'about', children: 'About', href: '/about' }
+ ]
+ }
+ ]}
+ renderLink={item => (
+ <a href={item.href} target="_blank" rel="noopener noreferrer">
+ {item.children}
+ </a>
+ )}
+/>
+```
+
+### Composed
+
+```tsx
+<TreeNavRoot>
+ <TreeNavList>
+ <TreeNavBranch defaultOpen>
+ <TreeNavBranchTrigger>src</TreeNavBranchTrigger>
+ <TreeNavList>
+ <TreeNavLeaf href="#index">index.ts</TreeNavLeaf>
+ <TreeNavBranch defaultOpen>
+ <TreeNavBranchTrigger>components</TreeNavBranchTrigger>
+ <TreeNavList>
+ <TreeNavLeaf href="#button" active>
+ Button.tsx
+ </TreeNavLeaf>
+ </TreeNavList>
+ </TreeNavBranch>
+ </TreeNavList>
+ </TreeNavBranch>
+ <TreeNavLeaf href="#readme">README.md</TreeNavLeaf>
+ </TreeNavList>
+</TreeNavRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- |
+| **items** \* | `{ id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean; asChild: boolean; defaultOpen: boolean; open: boolean; onOpenChange: (open: boolean) => void; collapsible: boolean; loading: boolean; onSelect: (event: React.MouseEvent<HTMLElement, MouseEvent>) => void; items: TreeNavBaseItem[] }[]` | - | |
+| renderLink | `(item: { id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean; asChild: boolean; defaultOpen: boolean; open: boolean; onOpenChange: (open: boolean) => void; collapsible: boolean; loading: boolean; onSelect: (event: React.MouseEvent<HTMLElement, MouseEvent>) => void; items: TreeNavBaseItem[] }) => ReactNode` | - | |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/components/Upload.md b/.agents/skills/kaizen-ui/references/components/Upload.md
new file mode 100644
index 0000000..ab4307b
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/Upload.md
@@ -0,0 +1,216 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Upload
+
+Upload is a wrapper around `input type="file"` that also renders previews for uploaded files and
+provides basic file management.
+
+Note that file validation and actual upload is not handled by this component beyond what the input
+element provides.
+
+## Examples
+
+### Basic Upload
+
+```tsx
+<Upload />
+```
+
+### With Accept Upload
+
+Use when only specific file types should be accepted, and display the constraint to users.
+
+```tsx
+<Upload accept="image/png,application/pdf">Accepts: image/png, application/pdf</Upload>
+```
+
+### Multiple Upload
+
+Use when users need to upload more than one file at a time.
+
+```tsx
+<Upload multiple>Up to 50 MB per file</Upload>
+```
+
+### With Default Value Upload
+
+Use to pre-populate the file list with already-uploaded or in-progress items, e.g. when editing a saved record or resuming an interrupted session.
+
+```tsx
+<Upload
+ multiple
+ defaultValue={[
+ {
+ id: '1',
+ file: new File(['resume content'], 'resume.pdf'),
+ status: 'success',
+ uploadedBytes: 1024
+ },
+ {
+ id: '2',
+ file: new File(['partial'], 'cover-letter.pdf'),
+ status: 'uploading',
+ uploadedBytes: 512
+ },
+ {
+ id: '3',
+ file: new File(['broken'], 'transcript.pdf'),
+ status: 'error',
+ errorMessage: 'Upload failed — please retry.'
+ }
+ ]}
+/>
+```
+
+### Controlled Upload
+
+Controlled mode lets you manage the selected files externally — useful for resetting after submission, syncing with form libraries, or showing custom UI based on file selection.
+
+```tsx
+;() => {
+ const [files, setFiles] = useState<FileUploadItem[]>([])
+ return <Upload multiple value={files} onValueChange={setFiles} />
+}
+```
+
+### With Custom Trigger Content Upload
+
+Override `slotAnchor` and `slotHeaderText` to tailor the trigger copy, and use children to surface inline constraints alongside the call to action.
+
+```tsx
+<Upload
+ multiple
+ accept=".pdf,.doc,.docx"
+ slotAnchor="Browse for documents"
+ slotHeaderText=" or simply drag them in."
+>
+ <span>Supported formats: PDF, Word</span>
+ <span>·</span>
+ <span>Maximum file size: 25 MB</span>
+</Upload>
+```
+
+### With Callbacks Upload
+
+Provide `onFileRetry` to expose a retry button on errored items, and `onFileRemove` to cancel in-flight requests or clean up server-side state when a file is removed.
+
+```tsx
+<Upload
+ multiple
+ defaultValue={[
+ {
+ id: '1',
+ file: new File(['report content'], 'report.pdf'),
+ status: 'error',
+ errorMessage: 'Network error — please retry.'
+ }
+ ]}
+ onFileRetry={item => {
+ console.log('Retry upload for', item.file.name)
+ }}
+ onFileRemove={item => {
+ console.log('Cancel upload for', item.file.name)
+ }}
+/>
+```
+
+### Media List Upload
+
+Use `listKind="media"` for image and video uploads where a compact thumbnail grid is preferred over the default card layout.
+
+```tsx
+<Upload
+ multiple
+ accept="image/*,video/*"
+ listKind="media"
+ slotAnchor="Add media"
+ slotHeaderText=" or drag photos and videos here."
+ defaultValue={[
+ {
+ id: '1',
+ file: new File(['img'], 'vacation.jpg', { type: 'image/jpeg' }),
+ status: 'success'
+ },
+ {
+ id: '2',
+ file: new File(['vid'], 'demo.mp4', { type: 'video/mp4' }),
+ status: 'uploading',
+ uploadedBytes: 1
+ }
+ ]}
+/>
+```
+
+### In Form Field Upload
+
+Use `renderInput` to wrap the trigger in a `FormField` when the upload needs a label, help text, or needs to participate in a larger form layout.
+
+```tsx
+<Upload
+ required
+ renderInput={trigger => (
+ <FormField
+ name="documents"
+ slotLabel="Upload documents"
+ slotHelp="Files will be deleted after 30 days."
+ >
+ {trigger}
+ </FormField>
+ )}
+/>
+```
+
+### Disabled Upload
+
+Use when file upload should be temporarily unavailable based on form or permission state.
+
+```tsx
+<Upload disabled />
+```
+
+### With Validation Upload
+
+Use when native validation cues should appear automatically via :user-valid and :user-invalid pseudo classes.
+
+```tsx
+<Upload required withValidation />
+```
+
+### Composed
+
+Use composed primitives when you need full control over the trigger layout and file list rendering.
+
+```tsx
+<UploadRoot>
+ <UploadTrigger>
+ <UploadInputElement />
+ <UploadDescription>Up to 50 MB</UploadDescription>
+ </UploadTrigger>
+ <UploadContent />
+</UploadRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| accept | `string` | - | MIME types accepted by the file input. |
+| children | `ReactNode` | - | Optional content to render in the trigger. This container has `label/regular/xs` text styles applied. Render additional context to the user here around file size limits, accept types, etc. |
+| defaultValue | `{ id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean } \| { id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean }[]` | - | The value of the upload when initially rendered. Use for uncontrolled state |
+| disabled | `boolean` | `false` | Whether the upload is disabled. Prevents file selection and drag and drop. You can also use this for read-only use cases. |
+| kind | `"flat" \| "floating"` | `"flat"` | The kind of input to render. - "flat" - renders with a border and background - "floating" - renders borderless with no background |
+| listKind | `"media" \| "card"` | `"card"` | Controls the format of the uploaded files. - `media` - use for images and videos, or compact lists - `card` - use for detailed file information |
+| multiple | `false \| true` | - | Whether the upload allows multiple files. |
+| onFileRemove | `(file: { id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean }) => void` | - | A callback triggered when a file is removed. Called with the file item that was removed. The file is still removed from the internal state regardless of whether this callback is provided. |
+| onFileRetry | `(file: { id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean }) => void` | - | A callback to handle file retry. If provided, we will render a retry button over files with a status of `error`. This callback will be called when the retry button is clicked. |
+| onValueChange | `(file: { id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean }) => void \| (files: { id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean }[]) => void` | - | Callback triggered whenever the value of the upload changes. |
+| renderInput | `(slotInput: ReactNode) => ReactNode` | - | A render function to control rendering of the input element. Receives the default trigger component as an argument. Useful for wrapping the input element in another component, such as a `Tooltip` or `FormField` |
+| showPreview | `boolean` | `true` | If false, we will not render the preview for the file. |
+| slotAnchor | `ReactNode` | - | We render an anchor to act as the keyboard anchor for the upload trigger. If you want to render a custom anchor, you can pass it in here. |
+| slotHeaderText | `ReactNode` | - | This is text that is rendered inline with the anchor text. This should be a continuination of the anchor text. |
+| status | `"error" \| "success"` | - | The status of the input. Use `withValidation` to automatically apply success/error states based on `:user-valid` and `:user-invalid` pseudo classes. |
+| value | `{ id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean } \| { id: string; file: File; errorMessage: string; status: "error" \| "success" \| "uploading"; uploadedBytes: number; hidePreview: boolean }[]` | - | The value of the upload. Must be used in conjunction with `onValueChange`. |
+| withValidation | `boolean` | - | When true, the input will automatically display success/error state based on `:user-valid` and `:user-invalid` styles |
diff --git a/.agents/skills/kaizen-ui/references/components/VerticalNav.md b/.agents/skills/kaizen-ui/references/components/VerticalNav.md
new file mode 100644
index 0000000..3385701
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/components/VerticalNav.md
@@ -0,0 +1,194 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# VerticalNav
+
+The VerticalNav component provides a vertical navigation menu that can handle
+both single links and nested link groups using native HTML `<details>`/`<summary>`.
+
+## Notes
+
+- VerticalNav supports a maximum of two levels (parent -> child). Do not add a third nesting level; flatten the structure or use breadcrumbs for deeper hierarchies.
+
+- Omit slotIcon on nav items by default. Only include icons when the design explicitly calls for them.
+
+- Never render nav items as disabled or aria-disabled for role-gated destinations. Remove inaccessible items from the items array entirely.
+
+## Examples
+
+### Basic Vertical Nav
+
+Use for sidebar navigation with a flat list of destinations.
+
+```tsx
+<VerticalNav
+ items={[
+ { id: 'home', children: 'Home', href: '/' },
+ {
+ id: 'settings',
+ children: 'Settings',
+ subItems: [
+ {
+ id: 'profile',
+ active: true,
+ children: 'Profile',
+ href: '/settings/profile'
+ },
+ {
+ id: 'account',
+ children: 'Account',
+ href: '/settings/account'
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### Default Closed Vertical Nav
+
+Set defaultOpen: false on a group to start collapsed — use when the nav has many sections and you want to reduce visual noise on first load.
+
+```tsx
+<VerticalNav
+ items={[
+ {
+ id: 'datacenter',
+ children: 'Data Center',
+ defaultOpen: false,
+ slotIcon: <Icon />,
+ subItems: [
+ {
+ id: 'datacenter-home',
+ children: 'Home',
+ href: '/data-center'
+ },
+ {
+ id: 'datacenter-products',
+ children: 'Products',
+ href: '/data-center/products'
+ }
+ ]
+ },
+ {
+ id: 'omniverse',
+ children: 'Omniverse',
+ defaultOpen: false,
+ slotIcon: <Icon />,
+ subItems: [
+ {
+ id: 'omniverse-apps',
+ children: 'Apps',
+ href: '/omniverse/apps'
+ }
+ ]
+ }
+ ]}
+/>
+```
+
+### Render Link Vertical Nav
+
+Use renderLink to integrate a framework router (Next.js Link, React Router NavLink, etc.) — a single renderer is applied to both primary and secondary items via the asChild pattern, so styling stays consistent.
+
+```tsx
+<VerticalNav
+ items={[
+ { id: 'home', children: 'Home', href: '/' },
+ {
+ id: 'settings',
+ children: 'Settings',
+ href: '/settings',
+ subItems: [
+ {
+ id: 'profile',
+ children: 'Profile',
+ href: '/settings/profile'
+ },
+ {
+ id: 'account',
+ children: 'Account',
+ href: '/settings/account'
+ }
+ ]
+ }
+ ]}
+ renderLink={item => (
+ <a href={item.href} target="_blank" rel="noopener noreferrer">
+ {item.children}
+ </a>
+ )}
+/>
+```
+
+### Custom Footer Vertical Nav
+
+Drop down to the composed primitives when the nav needs extra chrome (header, footer, version badge). Padding lives on the list, so a bordered footer extends edge-to-edge across the full nav width.
+
+```tsx
+<VerticalNavRoot className="flex flex-col">
+ <VerticalNavList className="min-h-0 flex-1">
+ <VerticalNavListItem>
+ <VerticalNavItem href="/data-center">Data Center</VerticalNavItem>
+ </VerticalNavListItem>
+ <VerticalNavListItem>
+ <VerticalNavItem href="/omniverse" active>
+ Omniverse
+ </VerticalNavItem>
+ </VerticalNavListItem>
+ <VerticalNavListItem>
+ <VerticalNavItem href="/settings">Settings</VerticalNavItem>
+ </VerticalNavListItem>
+ </VerticalNavList>
+ <div className="shrink-0 border-t-1 border-t-base px-4 py-3 text-center text-label-regular-sm text-secondary">
+ Version 1.2.3
+ </div>
+</VerticalNavRoot>
+```
+
+### Composed
+
+```tsx
+<VerticalNavRoot>
+ <VerticalNavList>
+ <VerticalNavListItem>
+ <VerticalNavItem href="/" active>
+ Home
+ </VerticalNavItem>
+ </VerticalNavListItem>
+ <VerticalNavListItem>
+ <VerticalNavCollapsibleSection defaultOpen>
+ <VerticalNavItem asChild slotEnd={<Icon />}>
+ <VerticalNavCollapsibleTrigger>Settings</VerticalNavCollapsibleTrigger>
+ </VerticalNavItem>
+ <VerticalNavCollapsibleContent>
+ <VerticalNavSubList>
+ <VerticalNavSubListItem>
+ <VerticalNavItem kind="secondary" href="/settings/profile">
+ Profile
+ </VerticalNavItem>
+ </VerticalNavSubListItem>
+ <VerticalNavSubListItem>
+ <VerticalNavItem kind="secondary" href="/settings/account">
+ Account
+ </VerticalNavItem>
+ </VerticalNavSubListItem>
+ </VerticalNavSubList>
+ </VerticalNavCollapsibleContent>
+ </VerticalNavCollapsibleSection>
+ </VerticalNavListItem>
+ </VerticalNavList>
+</VerticalNavRoot>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **items** \* | `{ defaultOpen: boolean; subItems: { asChild: boolean; id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean }[]; open: boolean; onOpenChange: (open: boolean) => void; asChild: boolean; id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean }[]` | - | Array of navigation items to render in the vertical nav |
+| asChild | `boolean` | - | When true, renders the immediate child instead of the default element, merging this component's props with the child's props. |
+| renderLink | `(item: ({ defaultOpen: boolean; subItems: { asChild: boolean; id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean }[]; open: boolean; onOpenChange: (open: boolean) => void; asChild: boolean; id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean }) \| { asChild: boolean; id: string; children: ReactNode; slotIcon: ReactNode; href: string; active: boolean; disabled: boolean }) => ReactNode` | - | Custom renderer for navigation links. Used for both primary and secondary items. When provided, the result is wrapped in VerticalNavItem with asChild, so the consumer's element gets all styling/behavior. |
+
+`* = required prop`
diff --git a/.agents/skills/kaizen-ui/references/guides/CONFIGURATION.md b/.agents/skills/kaizen-ui/references/guides/CONFIGURATION.md
new file mode 100644
index 0000000..4cdf103
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/guides/CONFIGURATION.md
@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Configuration
+
+## Variables and Theme
+
+The design tokens are supplied as CSS variables, which come from `base.css`. Users may also use `base-external.css` for OSS projects(changes the default font) but the `base.css` file includes:
+
+- a CSS reset(identical to Tailwind's `preflight.css`)
+- the design tokens, light(default, or `.light`, `.nv-light`), and dark theme(via `.dark`, `.nv-dark`, or `@media(prefers-color-scheme: dark)`)
+- fonts, internal icons(not the full set from NVIDIA Brand Assets - just the minimal ones used in the internal-only `<Icon>` component)
+
+This file can come from:
+
+- `@kui/foundations-css`: the original source of this file, internal only package so not useful for external projects
+- `@kui/foundations-react`: cloned from foundations-css to avoid needing to add another dep to have styles
+- CDN
+
+## Tailwind
+
+To use KUI with Tailwind, we offer a Tailwind plugin. Install Tailwind (latest preferred over v3). Next, add the plugin to your Tailwind config.
+
+For Tailwind v4, you'll need to add the KUI Foundations plugin to your global CSS file. Note we do **not** use the standard Tailwind import because we want to disable CSS layers and remove redundant CSS.
+
+An example ideal `src/global.css` configuration:
+
+```css
+@import '@kui/foundations-react/base.css'; /* same as "@kui/foundations-css/base.css", equivalent to "base-external.css" which is for OSS projects */
+@import '@kui/foundations-tailwind-plugin';
+/**
+ * Make sure you set `<html id="style-root">`
+ *
+ * This ensures your generated Tailwind utilities have higher specificity
+ * and override component styles.
+ */
+#style-root {
+ @tailwind utilities;
+}
+
+:root {
+ /* ensure we're using correct NVIDIA colors by default */
+ @apply bg-surface-base text-primary;
+}
+```
+
+You should then find the root `<html>` element in your app and add `id="style-root"` to it, otherwise your generated Tailwind utilities will not work.
diff --git a/.agents/skills/kaizen-ui/references/guides/DESIGN_TOKENS.md b/.agents/skills/kaizen-ui/references/guides/DESIGN_TOKENS.md
new file mode 100644
index 0000000..5e7f254
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/guides/DESIGN_TOKENS.md
@@ -0,0 +1,579 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Design Tokens
+
+Design tokens are theme-aware values for colors, borders, and surfaces. Available via Tailwind utilities or CSS variables, both forms resolve to the same CSS variable. These tokens come from the "base.css" file from the Foundations React package or CDN link
+
+| Example Token | Tailwind utility (only when Tailwind is configured) | CSS variable (for raw CSS or non-Tailwind contexts) |
+| -------------- | --------------------------------------------------- | --------------------------------------------------- |
+| Sunken surface | `bg-surface-sunken` | `--background-color-surface-sunken` |
+| Primary text | `text-primary` | `--color-text-primary` |
+| Base border | `border-base` | `--border-color-base` |
+
+Always use these variables for custom styling — via Tailwind classes or direct CSS variable references.
+
+## Themed Properties
+
+Variables that automatically change per color theme (light/dark) or density theme (standard/compact/spacious).
+
+### NVIDIA Color Theme
+
+Semantic color theme variables. Prefer using these CSS variables so the UI automatically adapts to the current theme.
+
+```css
+--background-color-accent-blue: var(--color-blue-050); /* dark: var(--color-blue-900) */
+--background-color-accent-blue-hover: var(--color-blue-050); /* dark: var(--color-blue-900) */
+--background-color-accent-blue-selected: var(--color-blue-200); /* dark: var(--color-blue-800) */
+--background-color-accent-blue-strong: var(--color-blue-700); /* dark: var(--color-blue-900) */
+--background-color-accent-blue-subtle: var(--color-blue-050); /* dark: var(--color-blue-900) */
+--background-color-accent-blue-subtle-hover: var(
+ --color-blue-200
+); /* dark: var(--color-blue-800) */
+--background-color-accent-blue-subtle-selected: var(
+ --color-blue-600
+); /* dark: var(--color-blue-500) */
+--background-color-accent-gray: var(--color-gray-200); /* dark: var(--color-gray-600) */
+--background-color-accent-gray-hover: var(--color-gray-300); /* dark: var(--color-gray-1000) */
+--background-color-accent-gray-selected: var(--color-gray-700); /* dark: var(--color-gray-200) */
+--background-color-accent-gray-strong: var(--color-gray-700); /* dark: same */
+--background-color-accent-gray-subtle: var(--color-gray-100); /* dark: var(--color-gray-700) */
+--background-color-accent-gray-subtle-hover: var(
+ --color-gray-300
+); /* dark: var(--color-gray-200) */
+--background-color-accent-gray-subtle-selected: var(
+ --color-gray-700
+); /* dark: var(--color-gray-600) */
+--background-color-accent-green: var(--color-green-025); /* dark: var(--color-green-900) */
+--background-color-accent-green-hover: var(--color-green-025); /* dark: var(--color-green-900) */
+--background-color-accent-green-selected: var(--color-green-050); /* dark: var(--color-green-800) */
+--background-color-accent-green-strong: var(--color-green-800); /* dark: var(--color-green-900) */
+--background-color-accent-green-subtle: var(--color-green-100); /* dark: var(--color-green-900) */
+--background-color-accent-green-subtle-hover: var(
+ --color-green-200
+); /* dark: var(--color-green-800) */
+--background-color-accent-green-subtle-selected: var(--color-green-600); /* dark: same */
+--background-color-accent-purple: var(--color-purple-200); /* dark: var(--color-purple-900) */
+--background-color-accent-purple-hover: var(--color-purple-050); /* dark: var(--color-purple-900) */
+--background-color-accent-purple-selected: var(
+ --color-purple-100
+); /* dark: var(--color-purple-800) */
+--background-color-accent-purple-strong: var(
+ --color-purple-700
+); /* dark: var(--color-purple-900) */
+--background-color-accent-purple-subtle: var(
+ --color-purple-050
+); /* dark: var(--color-purple-900) */
+--background-color-accent-purple-subtle-hover: var(
+ --color-purple-100
+); /* dark: var(--color-purple-800) */
+--background-color-accent-purple-subtle-selected: var(
+ --color-purple-600
+); /* dark: var(--color-purple-700) */
+--background-color-accent-red: var(--color-red-100); /* dark: var(--color-red-900) */
+--background-color-accent-red-hover: var(--color-red-050); /* dark: var(--color-red-900) */
+--background-color-accent-red-selected: var(--color-red-100); /* dark: var(--color-red-800) */
+--background-color-accent-red-strong: var(--color-red-700); /* dark: var(--color-red-900) */
+--background-color-accent-red-subtle: var(--color-red-100); /* dark: var(--color-red-900) */
+--background-color-accent-red-subtle-hover: var(--color-red-200); /* dark: var(--color-red-800) */
+--background-color-accent-red-subtle-selected: var(
+ --color-red-600
+); /* dark: var(--color-red-700) */
+--background-color-accent-teal: var(--color-teal-100); /* dark: var(--color-teal-900) */
+--background-color-accent-teal-hover: var(--color-teal-050); /* dark: var(--color-teal-900) */
+--background-color-accent-teal-selected: var(--color-teal-100); /* dark: var(--color-teal-800) */
+--background-color-accent-teal-strong: var(--color-teal-800); /* dark: var(--color-teal-900) */
+--background-color-accent-teal-subtle: var(--color-teal-100); /* dark: var(--color-teal-900) */
+--background-color-accent-teal-subtle-hover: var(
+ --color-teal-200
+); /* dark: var(--color-teal-800) */
+--background-color-accent-teal-subtle-selected: var(
+ --color-teal-600
+); /* dark: var(--color-teal-500) */
+--background-color-accent-yellow: var(--color-yellow-100); /* dark: var(--color-yellow-900) */
+--background-color-accent-yellow-hover: var(--color-yellow-050); /* dark: var(--color-yellow-900) */
+--background-color-accent-yellow-selected: var(
+ --color-yellow-100
+); /* dark: var(--color-yellow-800) */
+--background-color-accent-yellow-strong: var(
+ --color-yellow-700
+); /* dark: var(--color-yellow-900) */
+--background-color-accent-yellow-subtle: var(
+ --color-yellow-100
+); /* dark: var(--color-yellow-900) */
+--background-color-accent-yellow-subtle-hover: var(
+ --color-yellow-200
+); /* dark: var(--color-yellow-800) */
+--background-color-accent-yellow-subtle-selected: var(--color-yellow-600); /* dark: same */
+--background-color-background-contrast: var(--color-gray-900); /* dark: var(--color-gray-000) */
+--background-color-background-default: var(--color-gray-000); /* dark: var(--color-gray-900) */
+--background-color-background-emphasis: var(--color-gray-050); /* dark: var(--color-gray-700) */
+--background-color-background-highlight: var(--color-gray-100); /* dark: var(--color-gray-600) */
+--background-color-background-subtle: var(--color-gray-025); /* dark: var(--color-gray-800) */
+--background-color-component-skeleton: var(--color-gray-100); /* dark: var(--color-gray-800) */
+--background-color-component-skeleton-subtle: var(
+ --color-gray-200
+); /* dark: var(--color-gray-900) */
+--background-color-component-tooltip: var(--color-gray-800); /* dark: same */
+--background-color-component-track: var(
+ --color-translucent-black-100
+); /* dark: var(--color-translucent-white-200) */
+--background-color-component-track-inverse: var(
+ --color-translucent-black-100
+); /* dark: var(--color-translucent-black-400) */
+--background-color-feedback-danger: var(--color-red-300); /* dark: var(--color-red-900) */
+--background-color-feedback-danger-hover: var(--color-red-600); /* dark: same */
+--background-color-feedback-danger-pressed: var(--color-red-700); /* dark: same */
+--background-color-feedback-danger-strong: var(--color-red-500); /* dark: same */
+--background-color-feedback-danger-subtle-hover: var(
+ --color-red-100
+); /* dark: var(--color-red-900) */
+--background-color-feedback-danger-subtle-pressed: var(
+ --color-red-200
+); /* dark: var(--color-red-800) */
+--background-color-feedback-info: var(--color-blue-050); /* dark: var(--color-blue-950) */
+--background-color-feedback-success: var(--color-green-025); /* dark: var(--color-green-950) */
+--background-color-feedback-warning: var(--color-yellow-100); /* dark: var(--color-yellow-950) */
+--background-color-interaction-base: var(
+ --color-gray-000
+); /* dark: var(--color-translucent-black-600) */
+--background-color-interaction-disabled: var(
+ --color-translucent-black-050
+); /* dark: var(--color-translucent-white-100) */
+--background-color-interaction-disabled-checked: var(
+ --color-translucent-black-400
+); /* dark: var(--color-translucent-white-500) */
+--background-color-interaction-hover: var(
+ --color-translucent-black-050
+); /* dark: var(--color-translucent-white-100) */
+--background-color-interaction-inverse: var(--color-gray-900); /* dark: var(--color-gray-000) */
+--background-color-interaction-inverse-hover: var(
+ --color-gray-950
+); /* dark: var(--color-gray-100) */
+--background-color-interaction-inverse-pressed: var(
+ --color-gray-975
+); /* dark: var(--color-gray-200) */
+--background-color-interaction-pressed: var(
+ --color-translucent-black-100
+); /* dark: var(--color-translucent-white-200) */
+--background-color-interaction-primary-base: var(--color-green-300); /* dark: same */
+--background-color-interaction-primary-hover: var(--color-green-400); /* dark: same */
+--background-color-interaction-primary-selected: var(--color-green-500); /* dark: same */
+--background-color-interaction-selected: var(--color-gray-000); /* dark: var(--color-gray-1000) */
+--background-color-surface-base: var(--color-gray-000); /* dark: var(--color-gray-1000) */
+--background-color-surface-blanket: var(--color-translucent-black-700); /* dark: same */
+--background-color-surface-glass: var(
+ --color-translucent-white-800
+); /* dark: var(--color-translucent-black-600) */
+--background-color-surface-navigation: var(--color-gray-000); /* dark: var(--color-gray-1000) */
+--background-color-surface-overlay: var(--color-gray-000); /* dark: var(--color-gray-900) */
+--background-color-surface-raised: var(--color-gray-000); /* dark: var(--color-gray-950) */
+--background-color-surface-sunken: var(--color-gray-025); /* dark: var(--color-gray-975) */
+--border-color-accent-black: var(--color-gray-1000); /* dark: same */
+--border-color-accent-blue: var(--color-blue-600); /* dark: var(--color-blue-300) */
+--border-color-accent-gray: var(--color-gray-700); /* dark: var(--color-gray-300) */
+--border-color-accent-green: var(--color-green-700); /* dark: var(--color-green-300) */
+--border-color-accent-purple: var(--color-purple-600); /* dark: var(--color-purple-300) */
+--border-color-accent-red: var(--color-red-600); /* dark: var(--color-red-300) */
+--border-color-accent-teal: var(--color-teal-600); /* dark: var(--color-teal-300) */
+--border-color-accent-white: var(--color-gray-000); /* dark: same */
+--border-color-accent-yellow: var(--color-yellow-600); /* dark: var(--color-yellow-300) */
+--border-color-base: var(
+ --color-translucent-black-200
+); /* dark: var(--color-translucent-white-200) */
+--border-color-brand: var(--color-brand); /* dark: same */
+--border-color-component-tooltip: var(--color-gray-600); /* dark: same */
+--border-color-disabled: var(
+ --color-translucent-black-400
+); /* dark: var(--color-translucent-white-300) */
+--border-color-feedback-danger: var(--color-red-500); /* dark: same */
+--border-color-feedback-danger-hover: var(--color-red-600); /* dark: same */
+--border-color-feedback-danger-strong: var(--color-red-700); /* dark: same */
+--border-color-feedback-danger-subtle: var(--color-red-500); /* dark: var(--color-red-300) */
+--border-color-feedback-info: var(--color-blue-400); /* dark: same */
+--border-color-feedback-success: var(--color-green-400); /* dark: same */
+--border-color-feedback-warning: var(--color-yellow-400); /* dark: var(--color-yellow-200) */
+--border-color-interaction-base: var(
+ --color-translucent-black-300
+); /* dark: var(--color-translucent-white-200) */
+--border-color-interaction-disabled: var(
+ --color-translucent-black-100
+); /* dark: var(--color-translucent-white-100) */
+--border-color-interaction-hover: var(
+ --color-translucent-black-900
+); /* dark: var(--color-translucent-white-400) */
+--border-color-interaction-inverse: var(--color-gray-900); /* dark: var(--color-gray-000) */
+--border-color-interaction-inverse-hover: var(--color-gray-950); /* dark: var(--color-gray-100) */
+--border-color-interaction-inverse-pressed: var(--color-gray-975); /* dark: var(--color-gray-200) */
+--border-color-interaction-pressed: var(
+ --color-translucent-black-900
+); /* dark: var(--color-translucent-white-400) */
+--border-color-interaction-primary-base: var(--color-green-300); /* dark: same */
+--border-color-interaction-primary-hover: var(--color-green-400); /* dark: same */
+--border-color-interaction-primary-selected: var(--color-green-500); /* dark: same */
+--border-color-interaction-selected: var(--text-color-brand); /* dark: same */
+--border-color-interaction-strong: var(
+ --color-translucent-black-700
+); /* dark: var(--color-translucent-white-700) */
+--nv-current-theme: light; /* dark: dark */
+--text-color-accent-black: var(--color-gray-1000); /* dark: same */
+--text-color-accent-blue: var(--color-blue-700); /* dark: var(--color-blue-300) */
+--text-color-accent-blue-strong: var(--color-blue-700); /* dark: var(--color-blue-200) */
+--text-color-accent-blue-subtle: var(--color-blue-200); /* dark: same */
+--text-color-accent-gray: var(--color-gray-700); /* dark: var(--color-gray-050) */
+--text-color-accent-green: var(--color-green-700); /* dark: var(--color-green-300) */
+--text-color-accent-green-strong: var(--color-green-700); /* dark: var(--color-green-200) */
+--text-color-accent-green-subtle: var(--color-green-200); /* dark: same */
+--text-color-accent-purple: var(--color-purple-700); /* dark: var(--color-purple-200) */
+--text-color-accent-purple-strong: var(--color-purple-700); /* dark: var(--color-purple-200) */
+--text-color-accent-purple-subtle: var(--color-purple-200); /* dark: same */
+--text-color-accent-red: var(--color-red-700); /* dark: var(--color-red-300) */
+--text-color-accent-red-strong: var(--color-red-700); /* dark: var(--color-red-200) */
+--text-color-accent-red-subtle: var(--color-red-200); /* dark: same */
+--text-color-accent-teal: var(--color-teal-700); /* dark: var(--color-teal-300) */
+--text-color-accent-teal-strong: var(--color-teal-700); /* dark: var(--color-teal-200) */
+--text-color-accent-teal-subtle: var(--color-teal-200); /* dark: same */
+--text-color-accent-white: var(--color-gray-000); /* dark: same */
+--text-color-accent-yellow: var(--color-yellow-700); /* dark: var(--color-yellow-300) */
+--text-color-accent-yellow-strong: var(--color-yellow-700); /* dark: var(--color-yellow-200) */
+--text-color-accent-yellow-subtle: var(--color-yellow-200); /* dark: same */
+--text-color-base: var(--color-gray-600); /* dark: var(--color-gray-200) */
+--text-color-brand: var(--color-brand); /* dark: same */
+--text-color-component-nvidia-logo: var(--color-gray-1000); /* dark: var(--color-gray-000) */
+--text-color-disabled: var(--color-gray-400); /* dark: var(--color-translucent-white-300) */
+--text-color-feedback-danger: var(--color-red-500); /* dark: var(--color-red-400) */
+--text-color-feedback-danger-inverse: var(--color-gray-900); /* dark: var(--color-red-300) */
+--text-color-feedback-danger-strong: var(--color-red-700); /* dark: var(--color-red-300) */
+--text-color-feedback-danger-subtle: var(--color-red-600); /* dark: var(--color-red-400) */
+--text-color-feedback-info: var(--color-blue-500); /* dark: same */
+--text-color-feedback-info-inverse: var(--color-gray-900); /* dark: var(--color-blue-300) */
+--text-color-feedback-success: var(--color-green-500); /* dark: var(--color-green-400) */
+--text-color-feedback-success-inverse: var(--color-gray-900); /* dark: var(--color-green-300) */
+--text-color-feedback-warning: var(--color-yellow-500); /* dark: var(--color-yellow-300) */
+--text-color-feedback-warning-inverse: var(--color-gray-900); /* dark: var(--color-yellow-200) */
+--text-color-interaction-disabled-checked: var(
+ --color-translucent-black-300
+); /* dark: var(--color-translucent-black-600) */
+--text-color-interaction-selected: var(
+ --color-gray-000
+); /* dark: var(--color-translucent-white-200) */
+--text-color-inverse: var(--color-gray-000); /* dark: var(--color-gray-1000) */
+--text-color-inverse-brand: var(--color-gray-950); /* dark: var(--text-color-brand) */
+--text-color-placeholder: var(--color-gray-500); /* dark: var(--color-gray-400) */
+--text-color-primary: var(--color-gray-1000); /* dark: var(--color-gray-000) */
+--text-color-secondary: var(--color-gray-600); /* dark: var(--color-gray-300) */
+--text-color-strong: var(--color-gray-900); /* dark: var(--color-gray-000) */
+--text-color-subtle: var(--color-gray-400); /* dark: same */
+```
+
+Tailwind usage: `bg-surface-raised`, `text-accent-blue`.
+
+### Density Theme
+
+KUI offers a standard semantic sizing theme (`standard`) along with `compact` and `spacious` variants. Prefer these over fixed sizes for a consistent spacing system.
+
+```css
+--radius-density-xl: var(--radius-xl); /* compact(var(--radius-lg)), spacious(var(--radius-xl)) */
+--spacing-density-xxs: 2px; /* compact(1px), spacious(4px) */
+--spacing-density-xs: 4px; /* compact(2px), spacious(6px) */
+--spacing-density-sm: 6px; /* compact(4px), spacious(8px) */
+--spacing-density-md: 8px; /* compact(6px), spacious(12px) */
+--spacing-density-lg: 12px; /* compact(8px), spacious(16px) */
+--spacing-density-xl: 16px; /* compact(12px), spacious(24px) */
+--spacing-density-2xl: 24px; /* compact(16px), spacious(32px) */
+--spacing-density-3xl: 32px; /* compact(24px), spacious(48px) */
+--spacing-density-4xl: 48px; /* compact(32px), spacious(64px) */
+--spacing-density-5xl: 64px; /* compact(48px), spacious(80px) */
+```
+
+## Semantic Text Utilities
+
+Tailwind text utilities for typography. Use directly or via the `Text` component's `kind` prop.
+
+Example: `<div className="text-body-regular-md" />` or `<Text kind="body/regular/md" />`.
+
+```tailwindcss
+.text-body-bold-2xl { @apply font-bold text-24 leading-lh-150; }
+.text-body-bold-3xl { @apply font-bold text-32 leading-lh-150; }
+.text-body-bold-lg { @apply font-bold text-16 leading-lh-150; }
+.text-body-bold-md { @apply font-bold text-14 leading-lh-150; }
+.text-body-bold-sm { @apply font-bold text-12 leading-lh-150; }
+.text-body-bold-xl { @apply font-bold text-18 leading-lh-150; }
+.text-body-bold-xs { @apply font-bold text-10 leading-lh-150; }
+.text-body-italic-2xl { @apply italic text-24 leading-lh-150; }
+.text-body-italic-3xl { @apply italic text-32 leading-lh-150; }
+.text-body-italic-lg { @apply italic text-16 leading-lh-150; }
+.text-body-italic-md { @apply italic text-14 leading-lh-150; }
+.text-body-italic-sm { @apply italic text-12 leading-lh-150; }
+.text-body-italic-xl { @apply italic text-18 leading-lh-150; }
+.text-body-italic-xs { @apply italic text-10 leading-lh-150; }
+.text-body-regular-2xl { @apply text-24 leading-lh-150; }
+.text-body-regular-3xl { @apply text-32 leading-lh-150; }
+.text-body-regular-lg { @apply text-16 leading-lh-150; }
+.text-body-regular-md { @apply text-14 leading-lh-150; }
+.text-body-regular-sm { @apply text-12 leading-lh-150; }
+.text-body-regular-xl { @apply text-18 leading-lh-150; }
+.text-body-regular-xs { @apply text-10 leading-lh-150; }
+.text-body-semibold-2xl { @apply font-semibold text-24 leading-lh-150; }
+.text-body-semibold-3xl { @apply font-semibold text-32 leading-lh-150; }
+.text-body-semibold-lg { @apply font-semibold text-16 leading-lh-150; }
+.text-body-semibold-md { @apply font-semibold text-14 leading-lh-150; }
+.text-body-semibold-sm { @apply font-semibold text-12 leading-lh-150; }
+.text-body-semibold-xl { @apply font-semibold text-18 leading-lh-150; }
+.text-body-semibold-xs { @apply font-semibold text-10 leading-lh-150; }
+.text-display-2xl { @apply font-bold text-64 leading-lh-125; }
+.text-display-lg { @apply font-bold text-50 calc(62/50); }
+.text-display-md { @apply font-bold text-44 leading-lh-125; }
+.text-display-sm { @apply font-bold text-40 leading-lh-125; }
+.text-display-xl { @apply font-bold text-56 leading-lh-125; }
+.text-display-xs { @apply font-bold text-36 leading-lh-125; }
+.text-label-bold-2xl { @apply font-bold text-24 leading-lh-125; }
+.text-label-bold-3xl { @apply font-bold text-32 leading-lh-125; }
+.text-label-bold-lg { @apply font-bold text-16 leading-lh-125; }
+.text-label-bold-md { @apply font-bold text-14 calc(17/14); }
+.text-label-bold-sm { @apply font-bold text-12 leading-lh-125; }
+.text-label-bold-xl { @apply font-bold text-18 calc(22/18); }
+.text-label-bold-xs { @apply font-bold text-10 calc(12/10); }
+.text-label-light-2xl { @apply font-light text-24 leading-lh-125; }
+.text-label-light-3xl { @apply font-light text-32 leading-lh-125; }
+.text-label-light-lg { @apply font-light text-16 leading-lh-125; }
+.text-label-light-md { @apply font-light text-14 calc(17/14); }
+.text-label-light-sm { @apply font-light text-12 leading-lh-125; }
+.text-label-light-xl { @apply font-light text-18 calc(22/18); }
+.text-label-light-xs { @apply font-light text-10 calc(12/10); }
+.text-label-regular-2xl { @apply text-24 leading-lh-125; }
+.text-label-regular-3xl { @apply text-32 leading-lh-125; }
+.text-label-regular-lg { @apply text-16 leading-lh-125; }
+.text-label-regular-md { @apply text-14 calc(17/14); }
+.text-label-regular-sm { @apply text-12 leading-lh-125; }
+.text-label-regular-xl { @apply text-18 calc(22/18); }
+.text-label-regular-xs { @apply text-10 calc(12/10); }
+.text-label-semibold-2xl { @apply font-semibold text-24 leading-lh-125; }
+.text-label-semibold-3xl { @apply font-semibold text-32 leading-lh-125; }
+.text-label-semibold-lg { @apply font-semibold text-16 leading-lh-125; }
+.text-label-semibold-md { @apply font-semibold text-14 calc(17/14); }
+.text-label-semibold-sm { @apply font-semibold text-12 leading-lh-125; }
+.text-label-semibold-xl { @apply font-semibold text-18 calc(22/18); }
+.text-label-semibold-xs { @apply font-semibold text-10 calc(12/10); }
+.text-mono-2xl { @apply font-mono text-24 leading-lh-150; }
+.text-mono-lg { @apply font-mono text-16 leading-lh-150; }
+.text-mono-md { @apply font-mono text-14 leading-lh-150; }
+.text-mono-sm { @apply font-mono text-12 leading-lh-150; }
+.text-mono-xl { @apply font-mono text-20 leading-lh-150; }
+.text-title-2xl { @apply font-bold text-36 leading-lh-125; }
+.text-title-lg { @apply font-bold text-28 leading-lh-125; }
+.text-title-md { @apply font-bold text-24 leading-lh-125; }
+.text-title-sm { @apply font-bold text-20 leading-lh-125; }
+.text-title-xl { @apply font-bold text-32 leading-lh-125; }
+.text-title-xs { @apply font-bold text-18 calc(22/18); }
+```
+
+## Primitive Variables
+
+Core static CSS variables (not theme-dependent). Foundation for utility classes and themed properties.
+
+```css
+--spacing: 4px;
+--color-black: #000000;
+--color-white: #ffffff;
+--color-brand: #76b900;
+--color-red-050: #ffe9e9;
+--color-red-100: #ffd7d7;
+--color-red-200: #ffbbbb;
+--color-red-300: #ff8181;
+--color-red-400: #fe3f3f;
+--color-red-500: #e52020;
+--color-red-600: #c21e1e;
+--color-red-700: #961515;
+--color-red-800: #650b0b;
+--color-red-900: #4b0404;
+--color-red-950: #2d0100;
+--color-yellow-050: #feeeb2;
+--color-yellow-100: #fcde7b;
+--color-yellow-200: #f9c500;
+--color-yellow-300: #ef9100;
+--color-yellow-400: #df6500;
+--color-yellow-500: #d73d00;
+--color-yellow-600: #b93100;
+--color-yellow-700: #8d2600;
+--color-yellow-800: #601600;
+--color-yellow-900: #441000;
+--color-yellow-950: #2d0b00;
+--color-green-025: #dafb7d;
+--color-green-050: #cfff40;
+--color-green-100: #bff230;
+--color-green-200: #a5de15;
+--color-green-300: #76b900;
+--color-green-400: #549a00;
+--color-green-500: #3f8500;
+--color-green-600: #327100;
+--color-green-700: #265600;
+--color-green-800: #193800;
+--color-green-900: #142700;
+--color-green-950: #0d1a00;
+--color-teal-050: #adfcf8;
+--color-teal-100: #9aefe5;
+--color-teal-200: #3ae3c9;
+--color-teal-300: #1dbba4;
+--color-teal-400: #139a86;
+--color-teal-500: #0d8473;
+--color-teal-600: #097061;
+--color-teal-700: #04554b;
+--color-teal-800: #033831;
+--color-teal-900: #022723;
+--color-teal-950: #011a19;
+--color-blue-050: #cbf5ff;
+--color-blue-100: #aaccee;
+--color-blue-200: #7cd7fe;
+--color-blue-300: #10b1fb;
+--color-blue-400: #008af9;
+--color-blue-500: #0074df;
+--color-blue-600: #0060c7;
+--color-blue-700: #0046a4;
+--color-blue-800: #002781;
+--color-blue-900: #002050;
+--color-blue-950: #00112c;
+--color-purple-050: #fae9ff;
+--color-purple-100: #f9d4ff;
+--color-purple-200: #f0b9fd;
+--color-purple-300: #cd8ef0;
+--color-purple-400: #c359ef;
+--color-purple-500: #a846db;
+--color-purple-600: #952fc6;
+--color-purple-700: #741d9d;
+--color-purple-800: #4d1368;
+--color-purple-900: #331344;
+--color-purple-950: #1f0f27;
+--color-fuchsia-050: #ffe8f9;
+--color-fuchsia-100: #ffd3f2;
+--color-fuchsia-200: #feb5ee;
+--color-fuchsia-300: #fc79ca;
+--color-fuchsia-400: #e050b7;
+--color-fuchsia-500: #d2308e;
+--color-fuchsia-600: #b62475;
+--color-fuchsia-700: #8c1c55;
+--color-fuchsia-800: #5d1337;
+--color-fuchsia-900: #420d25;
+--color-fuchsia-950: #2d0919;
+--color-gray-000: #ffffff;
+--color-gray-025: #f7f7f7;
+--color-gray-050: #eeeeee;
+--color-gray-100: #e0e0e0;
+--color-gray-1000: #000000;
+--color-gray-200: #cccccc;
+--color-gray-300: #a7a7a7;
+--color-gray-400: #898989;
+--color-gray-500: #757575;
+--color-gray-600: #636363;
+--color-gray-700: #4b4b4b;
+--color-gray-800: #313131;
+--color-gray-900: #222222;
+--color-gray-950: #161616;
+--color-gray-975: #0c0c0c;
+--color-translucent-black-000: #00000000;
+--color-translucent-black-050: #0000000d;
+--color-translucent-black-100: #0000001a;
+--color-translucent-black-120: #0000001f;
+--color-translucent-black-150: #00000026;
+--color-translucent-black-200: #00000033;
+--color-translucent-black-300: #0000004d;
+--color-translucent-black-400: #00000066;
+--color-translucent-black-500: #00000080;
+--color-translucent-black-600: #00000099;
+--color-translucent-black-700: #000000b2;
+--color-translucent-black-800: #000000cc;
+--color-translucent-black-900: #000000e5;
+--color-translucent-white-000: #ffffff00;
+--color-translucent-white-050: #ffffff0d;
+--color-translucent-white-100: #ffffff1a;
+--color-translucent-white-120: #ffffff1f;
+--color-translucent-white-200: #ffffff33;
+--color-translucent-white-250: #ffffff40;
+--color-translucent-white-300: #ffffff4d;
+--color-translucent-white-400: #ffffff66;
+--color-translucent-white-500: #ffffff80;
+--color-translucent-white-600: #ffffff99;
+--color-translucent-white-700: #ffffffb2;
+--color-translucent-white-800: #ffffffcc;
+--color-translucent-white-900: #ffffffe5;
+--font-sans:
+ NVIDIA Sans, NVIDIA Sans Fallback, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+ 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+--font-mono:
+ JetBrains Mono, JetBrains Mono Fallback, ui-monospace, monospace, 'Apple Color Emoji',
+ 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+--text-10: 0.625rem;
+--text-12: 0.75rem;
+--text-14: 0.875rem;
+--text-16: 1rem;
+--text-18: 1.125rem;
+--text-20: 1.25rem;
+--text-22: 1.375rem;
+--text-24: 1.5rem;
+--text-28: 1.75rem;
+--text-32: 2rem;
+--text-36: 2.25rem;
+--text-40: 2.5rem;
+--text-44: 2.75rem;
+--text-48: 3rem;
+--text-50: 3.125rem;
+--text-56: 3.5rem;
+--text-60: 3.75rem;
+--text-64: 4rem;
+--text-72: 4.5rem;
+--text-80: 5rem;
+--font-weight-light: 300;
+--font-weight-regular: 400;
+--font-weight-semibold: 500;
+--font-weight-bold: 700;
+--leading-lh-100: 1;
+--leading-lh-125: 1.25;
+--leading-lh-150: 1.5;
+--leading-lh-175: 1.75;
+--breakpoint-xs: 20rem;
+--breakpoint-sm: 36rem;
+--breakpoint-md: 48rem;
+--breakpoint-lg: 62rem;
+--breakpoint-xl: 75rem;
+--breakpoint-2xl: 100rem;
+--container-3xs: 16rem;
+--container-2xs: 18rem;
+--container-xs: 20rem;
+--container-sm: 24rem;
+--container-md: 28rem;
+--container-lg: 32rem;
+--container-xl: 36rem;
+--container-2xl: 42rem;
+--container-3xl: 48rem;
+--container-4xl: 56rem;
+--container-5xl: 64rem;
+--container-6xl: 72rem;
+--container-7xl: 80rem;
+--border-width-none: 0px;
+--border-width-1: 1px;
+--border-width-2: 2px;
+--border-width-3: 3px;
+--border-width-4: 4px;
+--radius-none: 0px;
+--radius-sm: 2px;
+--radius-md: 4px;
+--radius-lg: 8px;
+--radius-xl: 16px;
+--radius-2xl: 24px;
+--radius-3xl: 32px;
+--radius-round: 9999px;
+--shadow-lg: 0px 8px 12px 0px var(--color-translucent-black-150);
+--shadow-md: 0px 4px 6px 0px var(--color-translucent-black-120);
+--shadow-sm: 0px 2px 4px 0px var(--color-translucent-black-120);
+--animate-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+--animate-spin: spin 1s linear infinite;
+--transition-duration-150: 150ms;
+--transition-duration-200: 200ms;
+--transition-duration-250: 250ms;
+--transition-duration-300: 300ms;
+--ease-out: cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+Available as Tailwind classes: `--color-red-500` → `bg-red-500`, `--text-16` → `text-16`.
diff --git a/.agents/skills/kaizen-ui/references/guides/ICONS.md b/.agents/skills/kaizen-ui/references/guides/ICONS.md
new file mode 100644
index 0000000..0aa4653
--- /dev/null
+++ b/.agents/skills/kaizen-ui/references/guides/ICONS.md
@@ -0,0 +1,794 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Icons
+
+As part of KUI we use the NVIDIA Brand Assets icons for our components.
+
+## Usage
+
+Preferred: these icons are available as React components that render SVGs in the `@nv-brand-assets/react-icons-inline` package.
+
+```tsx
+import { ChevronDown } from "@nv-brand-assets/react-icons-inline";
+
+// default is outline
+<ChevronDown />
+
+// filled/solid icon is available as a variant, prefer for smaller icons
+<ChevronDown variant="fill" />
+```
+
+Some projects might be using the `@nv-brand-assets/react-icons` or `@nv-brand-assets/react-icons-web-font` packages for hosted icons, which provide a `NvidiaGUIIcon` React component that accepts an `iconName` prop (kebab-case version of the icon name).
+
+```tsx
+import { NvidiaGUIIcon } from "@nv-brand-assets/react-icons";
+
+// default is still outline
+<NvidiaGUIIcon iconName="chevron-down" />
+
+// still accepts the "variant" prop for solid icons
+<NvidiaGUIIcon iconName="chevron-down" variant="fill" />
+```
+
+## Available icons
+
+- Accessibility
+- AccountAdd
+- AccountCheck
+- AccountMore
+- AccountRemove
+- Add
+- AddCircle
+- AddressBook
+- Airplane
+- Airport
+- Alarm
+- Anchor
+- AnchorCenter
+- AnchorE
+- AnchorN
+- AnchorNe
+- AnchorNw
+- AnchorS
+- AnchorSe
+- AnchorSw
+- AnchorW
+- Approximately
+- Apps
+- Archive
+- ArrangeColumns
+- ArrangeRows
+- Arrow
+- ArrowDown
+- ArrowDownLeft
+- ArrowDownMax
+- ArrowDownRight
+- ArrowLeft
+- ArrowLeftMax
+- ArrowLeftRight
+- ArrowRight
+- ArrowRightMax
+- ArrowUp
+- ArrowUpDown
+- ArrowUpLeft
+- ArrowUpMax
+- ArrowUpRight
+- AtSymbol
+- Atom
+- AutoRecord
+- AutoRecordOff
+- AwardRibbon
+- AwardTrophy
+- Baby
+- Backspace
+- Bandaid
+- Bank
+- Barcode
+- Battery0
+- Battery0Off
+- Battery100
+- Battery25
+- Battery50
+- Battery75
+- BatteryBoost
+- BatteryCharging
+- Beaker
+- Bed
+- Bell
+- BellOff
+- Bicycle
+- Blackboard
+- Bluetooth
+- BluetoothOff
+- Bold
+- Bone
+- Book
+- Bookmark
+- BookmarkOff
+- Bottle
+- BoundingBox
+- Braille
+- Briefcase
+- Broadcast
+- Brush
+- Bucket
+- Bug
+- BugOff
+- Bus
+- Bush
+- Business
+- Calculator
+- Calendar
+- CalendarEvent
+- Camera
+- Camera360
+- CameraAdd
+- CameraLinked
+- CameraOff
+- CameraSuper
+- Cancel
+- Car
+- Cards
+- CarouselHorizontal
+- CarouselVertical
+- Castle
+- Chart
+- ChartBar
+- ChartBubble
+- ChartFlow
+- ChartHierarchy
+- ChartPerformance
+- ChartPie
+- ChartScatterplot
+- ChartTree
+- ChatMessage
+- ChatMulti
+- ChatNew
+- ChatSingle
+- Chatbot
+- Check
+- CheckCircle
+- CheckMultiCircle
+- CheckmarkBadge
+- ChevronDoubleDown
+- ChevronDoubleLeft
+- ChevronDoubleRight
+- ChevronDoubleUp
+- ChevronDown
+- ChevronDownLeftUpRight
+- ChevronLeft
+- ChevronLeftRight
+- ChevronRight
+- ChevronUp
+- ChevronUpDown
+- ChevronUpLeftDownRight
+- Circle1Q
+- Circle2Q
+- Circle3Q
+- CircleTick
+- City
+- ClapBoard
+- Clipboard
+- Clock
+- Close
+- CloseCircle
+- ClosedCaption
+- Cloth
+- Cloud
+- CloudOff
+- Coaxial
+- Code
+- Cog
+- CogOff
+- Collapse
+- Collection
+- Commit
+- Compass
+- Component
+- Concierge
+- Connection
+- CopyDoc
+- CopyGeneric
+- Cpu
+- CraftKnife
+- Crop
+- Crosshair
+- Crown
+- Cube
+- CubeStack
+- Data
+- Datacenter
+- Db
+- DeliveryTruck
+- Denoise
+- Diamond
+- DiamondOff
+- Die1
+- Die2
+- Die3
+- Die4
+- Die5
+- Die6
+- Dirt
+- Display
+- DisplayCollection
+- DisplayColumn
+- DisplayOff
+- DisplayRow
+- DisplayShare
+- DisplaySurround
+- Displayport
+- Divide
+- Document
+- DocumentCheckmark
+- DocumentNew
+- DocumentPreview
+- Dolly
+- Download
+- DriveCloud
+- DriveCloudOff
+- DriveNetwork
+- DriveNetworkOff
+- DriveRemovable
+- DriveRemovableOff
+- DriveUsb
+- DriveUsbOff
+- Drone
+- Dual
+- Dvi
+- Easel
+- Eject
+- Ekg
+- Elevator
+- Emergency
+- Emissive
+- Engine
+- Enter
+- Envelope
+- EnvelopeOff
+- Equal
+- Equalizer
+- Eraser
+- Error
+- Escalator
+- Ethernet
+- EthernetPort
+- Exit
+- Expand
+- Explode
+- Export
+- ExportFromClipboard
+- ExportToClipboard
+- Eye
+- EyeOff
+- Eyedropper
+- FacialRecognition
+- Factory
+- Faders
+- Family
+- Fan
+- FanLoud
+- FanQuiet
+- Farm
+- FastForward
+- FastReverse
+- Feedback
+- FeelingHappy
+- FeelingNeutral
+- FeelingSad
+- FeelingVeryHappy
+- FeelingVerySad
+- FileReel
+- Film
+- FilmAdd
+- FilmCollection
+- Filter
+- Fingerprint
+- Fire
+- Firecracker
+- Firewall
+- FirewallOff
+- Firework
+- Fit
+- FitToPage
+- Flag
+- FlightStick
+- Floppy
+- Flower
+- Fog
+- FolderClosed
+- FolderOpen
+- Food
+- Footprint
+- Fork
+- Forward
+- Forward10
+- Founders
+- FoundersTier1
+- FoundersTier2
+- FoundersTier3
+- Fps
+- Freehand
+- FuelCan
+- FuelPump
+- Fullscreen
+- FullscreenExit
+- Function
+- GalleryStrip
+- Gamepad
+- GamepadOff
+- GamepadStart
+- Generate
+- Gift
+- Government
+- Gpu
+- GpuCard
+- GpuCardMulti
+- GpuCardOff
+- GpuOff
+- GpuSync
+- Graduate
+- GraphNode
+- GraphNodeConnect
+- GraphNodeDelete
+- Grass
+- Gravel
+- Grid
+- GridOff
+- GripArea
+- GripCorner
+- GripEdgeHorizontal
+- GripEdgeVertical
+- GripMini
+- Group
+- HAlignCenter
+- HAlignLeft
+- HAlignRight
+- HandClosed
+- HandOpen
+- HandPinch
+- HandPoint
+- Hdmi
+- Head
+- Header
+- Headset
+- Health
+- Heart
+- HeartOff
+- Helicopter
+- HelpCircle
+- HighKick
+- HighQuality
+- Highlighter
+- Hill
+- History
+- Hit
+- Home
+- HomeOff
+- HotAirBalloon
+- Hourglass
+- HourglassEnd
+- HourglassMid
+- HourglassStart
+- Hud
+- Hydrant
+- IconCategories
+- IconCategoryMap
+- IconNames
+- IconTagMap
+- IconTags
+- Identification
+- Image
+- Ime
+- Import
+- ImportImage
+- Inbox
+- Infinity
+- InfoCircle
+- Instance
+- Isp
+- IspOff
+- Italic
+- Iterate
+- JoystickClassic
+- Key
+- Keyboard
+- Keyframe
+- Knife
+- Lamp
+- Laptop
+- Laser
+- Lasso
+- Layers
+- LayersOff
+- LayoutColumns
+- LayoutDetail
+- LayoutGrid
+- LayoutList
+- LayoutRows
+- Library
+- LibraryGames
+- License
+- Lifebouy
+- Lifebuoy
+- LightRect
+- LightRotate
+- Lightbulb
+- Lighthouse
+- Lightning
+- LineSegment
+- Link
+- LinkBreak
+- ListBullet
+- ListCheckmark
+- ListNumber
+- Location
+- LocationOff
+- LockClosed
+- LockOpen
+- Loop
+- LoopOff
+- Mac
+- MacOff
+- Magnet
+- MagnifyingGlass
+- MagnifyingGlassMinus
+- MagnifyingGlassPlus
+- Man
+- ManWoman
+- Map
+- MapOff
+- Mapping
+- Markdown
+- Martini
+- MaskInside
+- MaskOutside
+- Material
+- Math
+- Meal
+- MediaOptical
+- Medicine
+- Megaphone
+- Menu
+- Microphone
+- MicrophoneOff
+- Microscope
+- MiniDisplayport
+- MirrorHorizontal
+- MirrorVertical
+- ModeComponent
+- Money
+- MoneyCoin
+- MoneyPaper
+- Moon
+- MoonOff
+- MoreHoriz
+- MoreVert
+- Mosaic
+- Mountain
+- Mouse2B
+- Mouse2BRightClick
+- Mouse3B
+- MouseScrollwheel
+- MouseScrollwheelActive
+- Move
+- MoveGlobal
+- Mud
+- Mug
+- MugBeer
+- Multidrive
+- Network
+- NetworkConnection
+- NetworkPcs
+- NetworkSignal
+- NetworkSignalOff
+- NeuralNetwork
+- News
+- Next
+- NotEqual
+- Notes
+- Numbers
+- NvidiaShield
+- NvidiaShieldStand
+- OpenExternal
+- Os
+- Outbox
+- OutletA
+- OutletB
+- OutletC
+- OutletE
+- OutletG
+- OutletH
+- OutletI
+- OutletJ
+- OutletK
+- OutletL
+- Outpainting
+- Package
+- Palette
+- Paperclip
+- Paperplane
+- Paragraph
+- Park
+- Pause
+- Pawn
+- Pawprint
+- PaymentCard
+- Pen
+- Pencil
+- PerformanceHigh
+- PerformanceLow
+- PerformanceMedium
+- PhoneLaptop
+- PhysicalExit
+- PictureInPicture
+- PillBarStack
+- Pin
+- PinOff
+- Pizza
+- Placesetting
+- Platformer
+- Play
+- PlugReceptacle
+- PlugRecepticle
+- PlugUsb
+- Plugin
+- Podium
+- Power
+- PowerSupplyUnit
+- PrayerRoom
+- Previous
+- Profile
+- ProfileGroup
+- ProfileOff
+- Projector
+- Pulse
+- Puzzle
+- Qrcode
+- Radar
+- Radioactive
+- Ram
+- RankingXp
+- Record
+- RectangleGroup
+- Redo
+- Reference
+- Refresh
+- Remote
+- Rename
+- Render
+- Replay
+- ReplayOff
+- Reply
+- Reset
+- Retry
+- Return
+- Reverse10
+- River
+- Robot
+- RobotArm
+- RobotDelivery
+- RobotTorso
+- RobotWheels
+- Rock
+- Rocket
+- Rotate
+- Rotate3D
+- Rotate90Clockwise
+- Rotate90Counter
+- RotateGlobal
+- Route
+- Ruler
+- Running
+- Sailboat
+- Sand
+- SawWave
+- Scale
+- ScaleBalance
+- ScaleDown
+- ScaleRelative
+- ScaleRelativeOff
+- ScaleReset
+- ScaleUp
+- School
+- Scissors
+- ScmBranch
+- ScmCompare
+- ScmFork
+- ScmMerge
+- ScmPull
+- ScmPullClose
+- ScmPullDraft
+- SdCard
+- Sea
+- Section
+- SectionBottom
+- SectionTop
+- Secure
+- Seed
+- Segmap
+- Segment
+- SelectBrush
+- SelectEllipse
+- SelectPolygon
+- SelectRectangle
+- SendImage
+- Sensor
+- ServiceAccount
+- Shader
+- ShaderBall
+- ShapeCircle
+- ShapeCircleOff
+- ShapeHexagon
+- ShapeOctagon
+- ShapeOctogon
+- ShapeSquare
+- ShapeSquareOff
+- ShapeTriangle
+- Shapes
+- Share
+- Shield
+- ShieldOff
+- Ship
+- ShipWheel
+- ShoppingBag
+- ShoppingBasket
+- ShoppingCart
+- ShoppingCartOpen
+- Shuffle
+- Signature
+- Signpost
+- SinWave
+- Skeleton
+- Skip
+- Skull
+- Sky
+- Sliders
+- Smartphone
+- SmartphoneOff
+- Snow
+- Soccer
+- Sort
+- SortAscending
+- SortDescending
+- Soundwaves
+- Sparkle
+- Speaker
+- SpeakerHigh
+- SpeakerLow
+- SpeakerMedium
+- SpeakerMute
+- SpeakerOff
+- Split
+- SplitFile
+- Spoon
+- SquareWave
+- StackHorizontal
+- Stair
+- Star
+- SteeringWheel
+- StepForward
+- StepReverse
+- Sticker
+- StickerImage
+- StickerShape
+- StickerText
+- StickerZoom
+- Stone
+- Stop
+- Straw
+- Strikethrough
+- StrokeWidth
+- Style
+- Subtract
+- SubtractCircle
+- SuitClub
+- SuitDiamond
+- SuitSpade
+- Suitcase
+- SunHigh
+- SunLow
+- SunOffHigh
+- Svg2BLeftClick
+- Svg3DAxis
+- Svg3SquarePlus
+- Svg4Square
+- Swatches
+- Sword
+- Sync
+- SyncOff
+- SyncWarning
+- Tablet
+- TabletOff
+- Tag
+- TagLabel
+- Teapot
+- Telephone
+- TelephoneOff
+- Teleport
+- Telescope
+- Television
+- TelevisionRetro
+- Text
+- TextAlignCenter
+- TextAlignFull
+- TextAlignLeft
+- TextAlignRight
+- TextFramed
+- Texture
+- Thermometer
+- ThumbDown
+- ThumbUp
+- Ticket
+- Timer
+- Toolbox
+- TrafficCone
+- TransferHorizontal
+- TransferVertical
+- Transform
+- Transparency
+- Trash
+- TrashDelete
+- Tree
+- Trees
+- TriangleWave
+- Trident
+- TringleWave
+- Typography
+- Umbrella
+- Underline
+- Undo
+- Upload
+- Usb
+- VAlignBottom
+- VAlignCenter
+- VAlignTop
+- Vga
+- Videocam
+- VideocamOff
+- Vr
+- Wand
+- Warning
+- Watch
+- WatchParty
+- Water
+- WeatherCloud
+- WeatherFog
+- WeatherLightning
+- WeatherPartialCloudDay
+- WeatherPartialCloudNight
+- WeatherRain
+- WeatherSnow
+- WeatherWind
+- Webcam
+- WebcamOff
+- WebcamSettings
+- Weight
+- WeightBar
+- Wheel
+- Wheelchair
+- Whispermode
+- Wifi
+- WifiOff
+- Window
+- WindowCode
+- WindowGrid
+- WindowStack
+- WindowTerminal
+- WineGlass
+- WirelessModem
+- WirelessModemOff
+- Woman
+- Workspace
+- WorkspaceGroup
+- Workstation
+- WorkstationOff
+- WorkstationSystem
+- WorkstationSystemOff
+- World
+- WorldOff
+- Wrench
+- Yoke
diff --git a/.agents/skills/sync-backend/SKILL.md b/.agents/skills/sync-backend/SKILL.md
new file mode 100644
index 0000000..5771a47
--- /dev/null
+++ b/.agents/skills/sync-backend/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: sync-backend
+description: >-
+ Refresh services/ from upstream, resolve JSON-RPC drift, update contract
+ docs, rebuild cli-bin, and verify. Use when the backend changed or the user
+ asks to sync dhc-modular / services.
+disable-model-invocation: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Sync services (backend)
+
+In this monorepo the backend is the sibling `services/` tree (authoritative
+checked-in source). Never invent a `dhc-modular/` checkout inside `desktop/`.
+
+Follow `.cursor/rules/service-contracts.mdc` and
+`desktop/docs/services-backend.md`.
+
+## Workflow
+
+1. Change `services/` in place. It is the authoritative checked-in source, so
+ there is no upstream import step.
+
+2. From `desktop/`:
+
+ ```bash
+ npm run service-contracts
+ ```
+
+4. Review:
+ - component version changes;
+ - added or removed binaries;
+ - missing notification consumers;
+ - backend requests the bridge does not call.
+
+5. For each changed component, read its `README.md` / `spec.md` and the Go
+ implementation. Go source is the contract.
+
+6. Resolve drift in the bridge and docs, then rebuild:
+
+ ```bash
+ npm run build:modular-binaries -- --force
+ npm run service-contracts:write
+ npm run typecheck
+ npm run test:unit
+ ```
+
+7. Verify:
+
+ ```bash
+ npm run service-contracts:check
+ ```
+
+8. Commit `services/` changes together with desktop integration edits.
diff --git a/.cursor/hooks.json b/.cursor/hooks.json
new file mode 100644
index 0000000..dd70bae
--- /dev/null
+++ b/.cursor/hooks.json
@@ -0,0 +1,16 @@
+{
+ "version": 1,
+ "hooks": {
+ "sessionStart": [
+ {
+ "command": "node .cursor/hooks/session-start.js"
+ }
+ ],
+ "preToolUse": [
+ {
+ "command": "node .cursor/hooks/enforce-commit-signoff.js",
+ "matcher": "Shell"
+ }
+ ]
+ }
+}
diff --git a/.cursor/hooks/enforce-commit-signoff.js b/.cursor/hooks/enforce-commit-signoff.js
new file mode 100644
index 0000000..7f5bd5a
--- /dev/null
+++ b/.cursor/hooks/enforce-commit-signoff.js
@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// preToolUse(Shell): deny a `git commit` that would create a commit with no
+// Signed-off-by trailer. CONTRIBUTING.md requires the DCO sign-off on every
+// commit, and the standard check matches the trailer against the commit author,
+// so an unsigned commit cannot be repaired in review — it has to be rewritten.
+//
+// Requiring -s unconditionally is safe: git does not add a second identical
+// trailer, so `git commit --amend --no-edit -s` is correct whether or not the
+// commit already carried one.
+//
+// Only a segment whose own command is `git commit` is inspected. cherry-pick,
+// revert, rebase, and merge are never matched: a replayed commit must keep its
+// original author's trailer, and merge commits are exempt.
+//
+// This hook gates agent tool calls only. A command typed directly into a
+// terminal is not intercepted, so it is a guardrail, not a security control.
+
+function readStdin() {
+ return new Promise(resolve => {
+ let data = ''
+ process.stdin.setEncoding('utf8')
+ process.stdin.on('data', c => (data += c))
+ process.stdin.on('end', () => resolve(data))
+ })
+}
+
+function allow() {
+ process.stdout.write(JSON.stringify({ permission: 'allow' }))
+ process.exit(0)
+}
+
+function deny(msg) {
+ process.stdout.write(
+ JSON.stringify({
+ permission: 'deny',
+ agent_message: msg,
+ user_message: 'Sign-off hook blocked a git commit without -s.'
+ })
+ )
+ process.exit(0)
+}
+
+// `cd x && git commit -m y` has to be inspected as its own command rather than
+// as one opaque string, so the invocation is split on shell separators.
+const SEPARATORS = /&&|\|\||;|\n|\|/
+
+// Git-level options that may sit between `git` and the subcommand, so
+// `git -C path commit` is still recognized.
+const GIT_COMMIT =
+ /^git\s+(?:(?:-C|-c|--git-dir|--work-tree|--namespace|--exec-path)(?:=|\s+)\S+\s+)*commit(?:\s|$)/
+
+const LONG_SIGNOFF = /(?:^|\s)--signoff(?:\s|$)/
+const NO_SIGNOFF = /(?:^|\s)--no-signoff(?:\s|$)/
+
+// A short-option cluster such as -sm or -asm carries the sign-off too. Matched
+// case-sensitively so -S (GPG signing) is never mistaken for -s.
+function hasShortSignoff(segment) {
+ const clusters = segment.match(/(?:^|\s)-[A-Za-z]+/g) || []
+ return clusters.some(cluster => cluster.includes('s'))
+}
+
+// Only the flag counts. A trailer typed into the message is rejected: a newline
+// is treated as a command separator above, so a hand-written trailer would be
+// seen on a single-line command and missed on a multi-line one, and a commit
+// message that merely mentions "Signed-off-by:" would bypass the gate entirely.
+function isSignedOff(segment) {
+ return LONG_SIGNOFF.test(segment) || hasShortSignoff(segment)
+}
+
+function offendingSegment(command) {
+ for (const raw of command.split(SEPARATORS)) {
+ const segment = raw.trim()
+ if (!GIT_COMMIT.test(segment)) continue
+ if (NO_SIGNOFF.test(segment)) continue
+ if (isSignedOff(segment)) continue
+ return segment
+ }
+ return null
+}
+
+async function main() {
+ const raw = await readStdin()
+ let input
+ try {
+ input = JSON.parse(raw || '{}')
+ } catch {
+ return allow()
+ }
+
+ // preToolUse carries the command at tool_input.command. Reading a
+ // top-level `command` would silently allow everything: that field belongs
+ // to beforeShellExecution, which is a different hook.
+ const toolInput = input.tool_input || input.input || input.arguments || input.args || {}
+ const command = toolInput.command
+ if (typeof command !== 'string' || command.length === 0) return allow()
+
+ const segment = offendingSegment(command)
+ if (segment === null) return allow()
+
+ return deny(
+ `git commit blocked by project hook (commit-sign-off): "${segment}" would ` +
+ `create a commit with no Signed-off-by trailer. CONTRIBUTING.md requires ` +
+ `the DCO sign-off on every commit, and the trailer must match the commit ` +
+ `author, so this cannot be fixed in review. Add -s (for example ` +
+ `\`git commit -s -m "..."\`) and retry; -s is idempotent, so it is also ` +
+ `correct with --amend. Concluding a conflicted merge, or any other commit ` +
+ `that genuinely must not be signed off, needs an explicit --no-signoff. ` +
+ `Never add your own sign-off to a commit authored by someone else.`
+ )
+}
+
+main().catch(err => {
+ process.stderr.write(`[hook enforce-commit-signoff] ${err && err.message}\n`)
+ // Fail-open on internal errors so a buggy hook never hard-blocks the agent.
+ allow()
+})
diff --git a/.cursor/hooks/session-start.js b/.cursor/hooks/session-start.js
new file mode 100644
index 0000000..88b0a31
--- /dev/null
+++ b/.cursor/hooks/session-start.js
@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Runs once per Cursor session. Clears the read-log so read-before-write
+// enforcement only counts reads done inside the current session.
+const fs = require('fs')
+const path = require('path')
+
+const STATE_DIR = path.join('.cursor', 'hooks', 'state')
+
+try {
+ fs.mkdirSync(STATE_DIR, { recursive: true })
+ fs.writeFileSync(path.join(STATE_DIR, 'reads.json'), '{}')
+} catch (err) {
+ process.stderr.write(`[hook session-start] ${err && err.message}\n`)
+}
diff --git a/.cursor/rules/absolute-imports.mdc b/.cursor/rules/absolute-imports.mdc
new file mode 100644
index 0000000..fb10f30
--- /dev/null
+++ b/.cursor/rules/absolute-imports.mdc
@@ -0,0 +1,50 @@
+---
+description: Use the `@/*` path alias instead of relative (`../`) imports across the codebase
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Absolute imports (`@/*` alias)
+
+The `@/*` alias maps to `./src/*` and is configured in the root `tsconfig.json`,
+`tsconfig.node.json`, `tsconfig.web.json`, the Vite configs, and tsx (via the
+root `tsconfig.json` `paths`). It resolves the same way for the Electron main
+process, the preload, the renderer, and for `tsx` scripts in `scripts/`.
+
+## Rules
+
+- **Cross-directory imports MUST use `@/...`.** Anything that would otherwise
+ need `../` to reach a sibling or ancestor directory uses the alias instead.
+ - Bad: `import { foo } from '../../shared/utils/log'`
+ - Bad: `import { Bar } from '../types/cascade-menu'`
+ - Good: `import { foo } from '@/shared/utils/log'`
+ - Good: `import { Bar } from '@/ui/types/cascade-menu'`
+
+- **Same-directory imports use `./`.** Do not rewrite `./sibling` as
+ `@/full/path/sibling` — it adds noise without helping readers. The alias is
+ for when you are crossing directories.
+ - Good: `import { helper } from './helper'`
+ - Bad (unnecessary): `import { helper } from '@/electron/service-bridge/helper'`
+ (from another file in that same folder)
+
+- **Scripts and configs follow the same rule.** `scripts/*.ts` and the
+ `electron.vite.config.*` / `vite.*.config.*` files all import shared code
+ via `@/...`. Never reach into `src/` with `../src/...`.
+ - Bad: `import { cliBinaryFileName } from '../src/shared/constants/app'`
+ - Good: `import { cliBinaryFileName } from '@/shared/constants/app'`
+
+- **Non-`src` assets (e.g. `package.json`) are the
+ only exceptions.** Those live outside `src/` so the alias cannot reach them,
+ and a relative import is correct:
+ - OK: `import { version } from '../package.json'` in `scripts/build-sea.ts`
+
+## Why
+
+Relative imports hide where a dependency actually lives, break as soon as a
+file is moved up/down the tree, and make it easy to accidentally couple the
+renderer to Electron main code (or vice versa). The `@/...` alias is the
+**single canonical form** for referring to any module in `src/` from anywhere
+else in the workspace.
diff --git a/.cursor/rules/agent-onboarding.mdc b/.cursor/rules/agent-onboarding.mdc
new file mode 100644
index 0000000..d0edb1a
--- /dev/null
+++ b/.cursor/rules/agent-onboarding.mdc
@@ -0,0 +1,27 @@
+---
+description: Read PAIR's rules and docs before changing desktop or services code
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Agent onboarding (PAIR monorepo)
+
+Before writing or changing code in this repo, read its rules and docs into
+context and follow them:
+
+- `.cursor/rules/*.mdc` — the always-on architecture and discipline rules,
+ especially `architecture.mdc` (boundaries, ownership, reactive state) and
+ `service-contracts.mdc` (desktop ↔ services contract checks).
+- `CONTRIBUTING.md` — workflow, build, and contribution conventions.
+- The relevant `docs/*` for the area you are touching (e.g.
+ `docs/building.md`, `desktop/docs/architecture.md`,
+ `desktop/docs/services-backend.md`, `desktop/docs/services-parity.md`).
+- `.agents/skills/*` when a matching skill exists (e.g. `kaizen-ui`,
+ `sync-backend`).
+
+`services/` is the backend source of truth in this monorepo; `desktop/` is the
+Electron UI. PAIR relays cluster/engine commands and renders backend state — it
+does not reimplement backend services in TypeScript.
diff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdc
new file mode 100644
index 0000000..44555e6
--- /dev/null
+++ b/.cursor/rules/architecture.mdc
@@ -0,0 +1,114 @@
+---
+description: Core PAIR boundaries for naming, communication, backend ownership, and reactive state
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# PAIR Architecture Rules
+
+## Naming
+
+- User-facing copy and all new code use **engine**, never **backend**.
+- Existing wire types such as `BackendInfo` may retain their contract name.
+- `EngineType` is a closed union. Narrow external strings with
+ `isEngineType()`.
+- PAIR has no plugin or custom-engine concept.
+
+## Runtime ownership
+
+The sibling `services/` tree is the backend source of truth.
+
+- Electron starts only `nvpair-ui-broker`.
+- The broker supervises all runtime workers.
+- PAIR must not reimplement backend services in TypeScript.
+- Never run a worker from both Electron and the broker.
+- Never add a broker-absent fallback.
+
+The binary inventory and launch ownership live in
+`src/shared/constants/modular-binaries.ts`.
+
+## Communication layers
+
+- Renderer service data uses `window.pairApi`.
+- Electron-native operations use `window.windowApi`.
+- Preload transports service calls through `service-bridge:*` IPC.
+- Electron main talks to the broker over stdio JSON-RPC.
+- The `nvpair` terminal command launches the bundled Go `nvpair-tui`, which owns
+ its own broker. PAIR has no Electron-backed console client.
+- Renderer code (`src/ui/`) must not import from `src/electron/`.
+
+The only direct service-data HTTP polling in Electron is `/v1/node-info`.
+Inference HTTP endpoints are for local client-compatible traffic.
+
+## Reactive state
+
+- The service is authoritative.
+- Commands do not return replacement state.
+- Renderer stores fetch snapshots and then consume push events.
+- Components do not create local loading state for engine/model operations.
+- `src/ui/stores/pending-actions.store.ts` is the single optimistic exception.
+- Pending actions always yield to engine state, progress, or error pushes.
+
+## Backend integration
+
+- Backend methods and notifications are implementation details behind
+ `WsInvokeChannelMap` and `WsPushChannelMap`.
+- Handle every PAIR-relevant backend notification.
+- Verify meaningful payload fields, not only method names.
+- Keep backend-coupled defaults in
+ `src/shared/constants/modular-runtime.ts`.
+- Prefer live backend-reported values over constants.
+
+## Engines and routing
+
+`nvpair-engine-manager` owns lifecycle and model operations.
+
+- Engine server ports and proxy ports are persisted by their backend owners.
+- Desired engine state is restored by the backend.
+- Call `engine:prepare-shutdown` before broker teardown.
+- Hide operations the backend cannot perform.
+
+Routing is owned by the proxies, broker, and `nvpair-job-scheduler`. The backend
+combines pending work, compact scanner/manual GPU telemetry, and per-proxy burst
+reservations. PAIR must not pin routes, derive policy from renderer metrics, or
+implement a TypeScript scheduling policy.
+
+For model-bearing inference, each proxy admits only nodes whose per-engine
+inventory advertises the requested model. Manual selection, scheduler priority,
+reservations, and retryable failover operate inside that owner set. Empty or
+non-matching inventory is excluded, and no owner produces a local `502`.
+
+## Security
+
+`nvpair-cluster-manager` owns identity, pairing, trust, and membership. PAIR
+implements **no** security or cryptography.
+
+- PAIR relays cluster commands and renders cluster events.
+- PAIR does not implement cluster cryptography, transport security, or key
+ management.
+- Pairing uses a six-digit convenience PIN, not a strong authenticator.
+- Do not add UI or TypeScript code based on cluster secrets, auth proofs,
+ certificates, or a TypeScript-managed CA.
+
+## IPC
+
+- `IpcChannelMap` is for Electron-native operations and the service bridge
+ envelope.
+- Every `ipcMain.handle` uses `safeHandle()`.
+- Handlers return the typed `IpcResult<T>` envelope and never throw across IPC.
+
+## Documentation
+
+When channels, push events, security flows, runtime processes, or ports change,
+update:
+
+- `docs/architecture.md`;
+- `docs/frontend-api.md`;
+- `docs/services-backend.md`;
+- `docs/services-parity.md`;
+- `system-architecture.mdc`.
+
+Document only the current architecture. Git history records prior designs.
diff --git a/.cursor/rules/backend-constants.mdc b/.cursor/rules/backend-constants.mdc
new file mode 100644
index 0000000..6cced17
--- /dev/null
+++ b/.cursor/rules/backend-constants.mdc
@@ -0,0 +1,54 @@
+---
+description: Prefer backend-reported values over hardcoded constants; keep the remaining backend-coupled constants in one canonical file
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Backend-coupled Constants
+
+PAIR UI is a UI for the `services/` backend. Values the backend owns (ports, endpoints,
+service names, intervals it drives) belong to the backend. Hardcoding them risks
+silent drift the moment the backend changes a default.
+
+## 1. Prefer backend-reported values
+
+Never hardcode a value the backend reports. Source it from the live contract and
+fall back to a constant only before the backend has reported (cold start):
+
+- Engine server port -> `engine:status` / `engine:state-changed` `port`.
+- Ollama proxy port -> `proxy:get-status`.
+- Per-node node-info port -> discovery `AvailableNode.port`.
+
+If a value you need is **not** reported, record the current limitation in
+`docs/services-parity.md`, then hardcode it temporarily per rule 3.
+
+## 2. One canonical file
+
+All hardcoded backend-coupled constants live in
+**`src/shared/constants/modular-runtime.ts`** — ports, local endpoint paths,
+backend-poll intervals, engine-port fallbacks, and log levels.
+
+- Do **not** scatter backend literals (port numbers, `127.0.0.1`, `/v1/...`
+ paths, poll intervals) inline across the codebase.
+- Do **not** encode backend discovery service names or TXT layouts in PAIR.
+ Consume the broker's reported discovery snapshots.
+- Do **not** create sibling constants files for backend values (no `ports.ts`,
+ no per-feature copies). Pure UI timings (animation throttles, tooltip delays,
+ blur grace) are **not** backend-coupled and stay with their component.
+
+## 3. Track backend-owned hardcodes
+
+A constant that exists **only** because the backend doesn't expose the value yet
+must carry a comment linking the current capability status, e.g.:
+
+```ts
+// Hardcoded pending backend exposure — see
+// docs/services-parity.md#current-client-side-responsibilities
+export const MODULAR_CLUSTER_MANAGER_PORT = 14321
+```
+
+When the backend starts reporting the value, source it and **delete** the
+constant (no "just in case" fallback — see `no-legacy-fallbacks.mdc`).
diff --git a/.cursor/rules/build-and-typecheck.mdc b/.cursor/rules/build-and-typecheck.mdc
new file mode 100644
index 0000000..9fc1a14
--- /dev/null
+++ b/.cursor/rules/build-and-typecheck.mdc
@@ -0,0 +1,53 @@
+---
+description: Build, typecheck, and the local gate to run before pushing; rules around .d.ts / tsbuildinfo files
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Build & Typecheck
+
+## Run the full gate before pushing
+
+CI fails the branch on any of these, so run all of them locally first. A red
+pipeline costs a full round trip; these take about a minute. From `desktop/`:
+
+```bash
+npm run typecheck
+npm run lint
+npm run dead-code:check
+npm run test:unit
+npm run service-contracts:check
+```
+
+The first four are exactly what `test:monorepo-gate` runs, in that order;
+`service-contracts:check` is the separate `verify:service-contracts` job. Do not
+report work as pushed or ready for review with any of them unrun.
+
+`dead-code:check` is the one most often missed, because nothing else in the
+local loop catches it — typecheck and lint both pass on an export that has no
+importer. knip flags any exported value or type nothing imports, so a helper
+exported out of habit fails the build. Fix it by:
+
+- deleting it, if it is genuinely unused; or
+- dropping the `export` when it is only referenced inside its own file — a type
+ can annotate an exported function's signature without being exported itself
+ (see `type-discipline.mdc`); or
+- adding a justified entry to `desktop/dead-code-omissions.json`, only for a
+ real false positive such as an export consumed by an external tool.
+
+`npm run dead-code` (no `--check`) writes the same report without failing.
+
+## Typecheck
+
+- **Use `npm run typecheck`** to check types — not `npx tsc --noEmit` directly.
+ The project has split tsconfig targets (`typecheck:node`, `typecheck:web`).
+- **NEVER delete `.d.ts` files.** Some `.d.ts` files are authored sources
+ (e.g. ambient type declarations in `src/`). Bulk-deleting them is destructive
+ and irreversible. If `tsc` reports TS6305 ("Output file has not been built
+ from source"), ignore those errors — they come from stale incremental output
+ and do not affect the build.
+- **Delete `*.tsbuildinfo` only** if incremental caches cause issues. These are
+ safe to remove.
diff --git a/.cursor/rules/commit-sign-off.mdc b/.cursor/rules/commit-sign-off.mdc
new file mode 100644
index 0000000..4306308
--- /dev/null
+++ b/.cursor/rules/commit-sign-off.mdc
@@ -0,0 +1,71 @@
+---
+description: Sign off every commit with git commit -s; the DCO trailer must match the commit author
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Sign off every commit
+
+`CONTRIBUTING.md` requires a `Signed-off-by` trailer on every commit, certifying
+the [Developer Certificate of Origin](https://developercertificate.org/). This
+project uses the DCO instead of a contributor license agreement, so a commit
+without the trailer cannot be accepted and has to be rewritten later.
+
+Always commit with `-s`:
+
+```bash
+git commit -s -m "..."
+```
+
+`-s` is idempotent — git will not add a second identical trailer — so use it
+even when amending: `git commit --amend --no-edit -s` adds the trailer to a
+commit that was made without one.
+
+Use the flag rather than writing the trailer into the message by hand, so the
+address always comes from the configured identity that also authors the commit.
+A trailer typed into the message is not accepted as a substitute.
+
+`.cursor/hooks/enforce-commit-signoff.js` denies a `git commit` that would
+produce an unsigned commit. It inspects `git commit` only, so cherry-pick,
+rebase, revert, and merge are untouched, and it fails open if the hook itself
+errors. It gates agent tool calls, not commands typed into a terminal, so it is
+a guardrail rather than a security control.
+
+## The trailer must match the commit author
+
+The standard DCO check compares each commit's `Signed-off-by` address against
+that commit's **author**, not its committer. A trailer naming anyone else fails
+the check.
+
+- `git commit --amend -s` fixes the most recent commit.
+- `git rebase --signoff <base>` fixes a whole branch of your own commits.
+- Both rewrite history, so the branch needs a force-push afterward.
+
+## Never sign off a commit you did not author
+
+`git cherry-pick -s` adds the **committer's** trailer while preserving the
+original **author**. That produces exactly the mismatch the check rejects, and
+it certifies work that is not yours.
+
+Cherry-pick without `-s` and keep whatever trailer the original author wrote.
+This matters most when importing community commits from GitHub, which is the one
+workstream that replays another person's commits — see workstream C in
+`.cursor/skills/pair-repo-sync/SKILL.md`. Publishing to GitHub does not replay
+commits at all; it commits a cut tree, so no sign-off decision arises there.
+
+## Exemptions
+
+- Merge commits are exempt from the DCO, so concluding a merge needs no `-s`.
+ Concluding a conflicted merge runs `git commit`, which the hook does inspect;
+ pass `--no-signoff` there to record the exemption deliberately.
+- A commit replayed by cherry-pick, rebase, or revert keeps the trailer its
+ author wrote. Do not add one.
+
+## Related
+
+- Contributor-facing policy and the full DCO text: `CONTRIBUTING.md`.
+- Branch and push workflow: `no-push-to-main.mdc`.
+- Cross-remote replay: `repository-sync.mdc`.
diff --git a/.cursor/rules/communication-layers.mdc b/.cursor/rules/communication-layers.mdc
new file mode 100644
index 0000000..1dfaae1
--- /dev/null
+++ b/.cursor/rules/communication-layers.mdc
@@ -0,0 +1,57 @@
+---
+description: Current renderer, Electron, broker, and node communication boundaries
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Communication Layers
+
+## Renderer
+
+- Renderer service calls use `window.pairApi`.
+- Electron-native operations use `window.windowApi`.
+- Renderer code under `src/ui/` must not import from `src/electron/`.
+- Shared request, response, and push types belong under `src/shared/types/`.
+
+## Electron main
+
+- Preload forwards logical service calls through the `service-bridge:*` IPC
+ envelope.
+- `handleServiceBridgeInvoke` is the service dispatch for renderer clients.
+- `ModularSupervisor` communicates with `nvpair-ui-broker` through newline
+ JSON-RPC over stdio.
+- Electron starts only the broker. The broker owns every worker process.
+- Modular notifications update `ModularBridgeState`, which emits typed renderer
+ push events.
+
+## Terminal client
+
+- The `nvpair` command on PATH launches the bundled Go `nvpair-tui`, which
+ spawns and owns its own broker.
+- Electron generates that launcher on packaged builds
+ (`src/electron/nvpair-command.ts`).
+- There is no Electron console client, control socket, or local control server.
+ Do not reintroduce one.
+
+## Backend network traffic
+
+- Node discovery, pairing, trust, workload propagation, error synchronization,
+ and routed inference are backend-owned.
+- PAIR must not implement a parallel node-to-node protocol.
+- Clustered backend peer channels use the trust and transport selected by the
+ backend services; PAIR relays control-plane requests through the broker.
+- Public inference clients connect to local Ollama- or OpenAI-compatible proxy
+ endpoints.
+
+## Documentation
+
+When changing IPC channels, logical service channels, push events, process
+ownership, security flows, or runtime ports, update:
+
+- `docs/architecture.md`;
+- `docs/frontend-api.md`;
+- `docs/services-backend.md`;
+- the relevant `.cursor/rules` files.
diff --git a/.cursor/rules/engines-vs-backends-naming.mdc b/.cursor/rules/engines-vs-backends-naming.mdc
new file mode 100644
index 0000000..0674fdf
--- /dev/null
+++ b/.cursor/rules/engines-vs-backends-naming.mdc
@@ -0,0 +1,19 @@
+---
+description: Use engine terminology in PAIR code and UI
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Engine Naming
+
+- User-facing copy always says **engine**.
+- New TypeScript names use `engine`, not `backend`.
+- Existing backend JSON-RPC method names, binary names, payload fields, and
+ backend service symbols are external contracts; preserve their exact spelling.
+- `EngineType` is a closed union. Narrow strings at process, IPC, persisted
+ data, and network boundaries before using them as engine identifiers.
+- PAIR has no runtime plugin or custom-engine registry. Supported engines come
+ from the backend capability surface and the canonical shared engine list.
diff --git a/.cursor/rules/file-editing.mdc b/.cursor/rules/file-editing.mdc
new file mode 100644
index 0000000..05d19c4
--- /dev/null
+++ b/.cursor/rules/file-editing.mdc
@@ -0,0 +1,57 @@
+---
+description: Read-before-write rule — always Read a file before Write/StrReplace. No shell scripts to mutate code. No exceptions.
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# File Editing
+
+## NEVER use shell commands or scripts to modify code
+
+This is the **hard top-tier rule** of this repo. **Never** use `sed`,
+`awk`, `perl -i`, `tr`, `find -exec`, PowerShell `(Get-Content … | Set-Content)`,
+heredoc-into-file, `echo > file`, or any other shell construct that mutates
+source files. **Always** use the dedicated edit tools: `StrReplace`,
+`Write`, or `EditNotebook`.
+
+Why: shell-based rewrites bypass Cursor's diff UI. The user cannot review,
+accept, or reject the change — it just happens silently. Even a "tiny
+rename" across many files must be done as a series of `StrReplace` calls
+(one per file, or `replace_all: true` within a file) so each edit shows up
+in the diff panel.
+
+- ❌ `sed -i 's/foo/bar/g' src/**/*.ts`
+- ❌ `find src -name '*.ts' -exec sed -i …`
+- ❌ `node -e "require('fs').writeFileSync(…)"`
+- ❌ `cat > file.ts <<'EOF' … EOF`
+- ✅ `StrReplace` with `replace_all: true` for in-file mass-rename
+- ✅ One `StrReplace` per file for cross-file rename (read each first)
+- ✅ `Write` only when creating a new file or wholesale rewriting
+ (after `Read`)
+
+The `Shell` tool is for actual terminal operations (`git`, `npm`,
+`tsc`, `lint`, etc.) only. If you catch yourself reaching for `sed`
+to "save tool calls", **stop** — the user must see every code change.
+
+## ALWAYS read a file before editing it
+
+The user may have edited the file since you last read it. Your memory of
+the file is stale. Before **any** `Write` or `StrReplace` call, call
+`Read` on the target path **in the same turn**.
+
+- `Write` is **destructive** — no old_string check, no safety net. A
+ stale mental model silently erases the user's edits.
+- `StrReplace` self-validates via `old_string`, but when the fuzzy match
+ shows the file has drifted from what you expect, **re-read first**
+ rather than forcing a match.
+- A `preToolUse` hook (see `.cursor/hooks.json`) blocks `Write` on
+ existing files that have not been read this session. Do not work
+ around it — call `Read` and retry.
+
+## No legacy fallbacks
+
+This is a greenfield codebase. Do not add compatibility shims, alternate
+resolution paths, or "just in case" code. See **`no-legacy-fallbacks.mdc`**.
diff --git a/.cursor/rules/imports-discipline.mdc b/.cursor/rules/imports-discipline.mdc
new file mode 100644
index 0000000..8ffd436
--- /dev/null
+++ b/.cursor/rules/imports-discipline.mdc
@@ -0,0 +1,26 @@
+---
+description: Static imports only, no dynamic imports, no convenience re-exports
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Imports
+
+- Always use static `import` statements. **NEVER** use dynamic `await import()`.
+ All dependencies must be resolved at module load time. Dynamic imports cause
+ Vite chunk warnings and make dependency graphs harder to trace.
+- Exception: `?raw` imports are used for bundling markdown as strings
+ (e.g. `import GUIDE from './guide.md?raw'`). These are handled by Vite at
+ build time.
+- **No convenience re-exports of types (or values).** Do not add
+ `export type { Foo } from './other'` at the end of an unrelated module so
+ callers can import `Foo` from the wrong file. Import from the **defining
+ module** (e.g. `import type { Foo } from './types'`). Convenience re-exports
+ are easy to leave stale when types move and they obscure the real source of
+ truth.
+
+See also **`absolute-imports.mdc`** for the `@/*` alias rules (cross-directory
+imports must use `@/...`; same-directory imports use `./`).
diff --git a/.cursor/rules/ipc-patterns.mdc b/.cursor/rules/ipc-patterns.mdc
new file mode 100644
index 0000000..76352cd
--- /dev/null
+++ b/.cursor/rules/ipc-patterns.mdc
@@ -0,0 +1,52 @@
+---
+description: IPC handler patterns — Electron-native ops only, always use safeHandle, never throw
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# IPC Handler Patterns
+
+## IPC is for Electron-native operations only
+
+Most IPC handlers in `src/electron/ipc/` are thin wrappers for things that
+require Electron main process access. The modular service bridge is the one
+intentional data IPC envelope: preload exposes `window.pairApi`, then forwards
+logical service invokes/subscriptions over `service-bridge:*` IPC to Electron
+main, where handlers map to stdio JSON-RPC subprocesses or explicit empty
+responses.
+
+- **Window management**: `window:close`, `window:open-*`, `window:quit`, `window:maximize`, `window:minimize`, `window:is-maximized`, `window:copy-to-clipboard`, `window:copy-image-to-clipboard`, `window:save-debug-logs`
+- **Tray**: `tray:resize`, `tray:show-menu`
+- **Service lifecycle**: `service:get-status`, `service:start`, `service:stop`, `service:restart`, `service:get-log-level`, `service:set-log-level`, `service:open-log-file`, `service:open-log-dir`, `service:get-versions`, `service:open-license`, `service:open-third-party-licenses`
+- **Settings**: `settings:consume-first-run`
+
+## Handlers must never throw
+
+Every `ipcMain.handle` uses `safeHandle()` from `safe-handle.ts` which
+validates the sender and wraps responses in `IpcResult<T>`. IPC handlers
+must never throw — they return `{ success: false, error }` via the envelope.
+
+## Always use safeHandle
+
+```typescript
+// BAD
+ipcMain.handle('my-channel', async (event, payload) => { ... })
+
+// GOOD -- use a channel from IpcChannelMap so payload and return type are checked
+safeHandle('service:get-status', async (_event) => { ... })
+```
+
+## Typed channels
+
+- **Channel contract**: Request/response types for every IPC channel are in `src/shared/types/ipc-channels.ts` (`IpcChannelMap`). When adding a new channel, add its `request` and `response` types there first; then use `safeHandle('channel-name', ...)` so the handler's payload and return type are inferred and checked.
+- Preload APIs should use the same response types so renderer and main stay in sync.
+
+## Service methods drive state
+
+Service state now comes from the modular bridge. Modular subprocess
+notifications update `ModularBridgeState`, then Electron main emits
+`service-bridge:push` IPC messages that preload fans out to `window.pairApi`
+subscribers.
diff --git a/.cursor/rules/model-registry.mdc b/.cursor/rules/model-registry.mdc
new file mode 100644
index 0000000..e66521a
--- /dev/null
+++ b/.cursor/rules/model-registry.mdc
@@ -0,0 +1,57 @@
+---
+description: Electron-main engine model hub (Ollama committed list + LM Studio catalog)
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Model Registry — engine model hub
+
+- The backend has **no model-search RPC**, so the "Add Model" browse is
+ served by a standalone Electron-main module, **`src/electron/model-hub/`**
+ (main process, because the renderer cannot call `huggingface.co` under
+ CSP+CORS). There is **no generic Hugging Face browse and no shared GGUF
+ registry** — each enabled engine has exactly one curated source declared via
+ `EngineCaps.engineHub`.
+- **Ollama** (`ollama-library.ts`): a **locked, committed list**, not a live
+ scrape. `src/electron/model-hub/ollama-models.json` (wire shape
+ `{ scrapedAt, source, count, models: OllamaTagsModel[] }`) is bundled into
+ the main process (`resolveJsonModule` + electron-vite inlining), so
+ `loadOllamaModels()` returns instantly with **no network access at runtime**.
+ Devs regenerate it with `npm run scrape:ollama-models`
+ (`scripts/scrape-ollama-models.ts`) when Ollama's catalog changes, then review
+ the diff and commit. The scraper is the **only** place Ollama scraping lives:
+ two phases — (A) parse the `https://ollama.com/library` index (anchored on
+ each card's `<a class="group w-full">` link, capability chips are
+ `text-indigo-600`, size chips `text-blue-600`, updated timestamp in the stats
+ span `title`), then (B) fetch each `https://ollama.com/library/<base>/tags`
+ page (concurrency 4, anchored on the self-contained mobile card
+ `class="md:hidden"`) for per-tag digest + binary byte size + context window;
+ falls back to `https://ollama.com/api/tags` only if Phase A fails. Cloud-only
+ variants are filtered. Names are used as-is for `ollama pull`. **When Ollama
+ changes their markup, update the parser in the script and re-run it** — the
+ running app is unaffected.
+- **LM Studio** (`lmstudio-catalog.ts`, `lmStudioCatalogCache`): still a **live
+ fetch**. GETs
+ `https://huggingface.co/api/models?author=lmstudio-community&sort=downloads&direction=-1&limit=500`
+ and normalizes each repo to a pull-ready id (e.g.
+ `lmstudio-community/Qwen3-8B-GGUF`, accepted by `lms get`). This is the
+ **only** remaining network call in the model hub, and it is main-process only
+ (6-hour TTL + in-flight guard so PAIR never fetches continuously).
+- Both sources normalize to the shared `EngineHubModel`
+ (`src/shared/types/engine-api.ts`).
+- `index.ts` exposes `getEngineHubModels(engineType)` (Ollama returns the
+ committed list synchronously; LM Studio awaits a cold cache's initial load;
+ returns `{ models }`) and `warmEngineHubs()` (warms **only** LM Studio —
+ Ollama needs none). The `engine:search-hub` handler in `empty-handlers.ts`
+ calls the former; the `overview:ready` handler in `window.ipc.ts` calls the
+ latter. Warm on renderer-ready, **not** on service connect: a catalog fetch
+ started before the window has painted competes with the renderer's own load,
+ and a hanging one leaves an unpainted window behind.
+- The renderer (`src/ui/components/ModelHub/`) fetches an engine's full
+ catalog once (cached per-engine), filters by the search box **locally** on
+ each keystroke, and sorts client-side by Updated / Name / Size. Pulling goes
+ through the backend (`engine:pull-model` → `pull_model`); the hub only
+ produces the pull-ready id.
diff --git a/.cursor/rules/no-legacy-fallbacks.mdc b/.cursor/rules/no-legacy-fallbacks.mdc
new file mode 100644
index 0000000..71b5d20
--- /dev/null
+++ b/.cursor/rules/no-legacy-fallbacks.mdc
@@ -0,0 +1,24 @@
+---
+description: No legacy compatibility paths or dead fallback branches — greenfield codebase
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# No legacy fallbacks
+
+PAIR is a **new app**. Do **not** add:
+
+- Multiple resolution paths “for compatibility” (e.g. `__dirname` variants, alternate folder layouts, `existsSync` chains that try path A then B then C).
+- Deprecated APIs or shims “in case old clients exist.”
+- Comment blocks that say “legacy” or “backward compatibility” unless removing that code is tracked as explicit work.
+- Re-export barrels whose only purpose is to keep old import paths alive.
+
+**Do instead:**
+
+- One **canonical** path, URL, or behavior — the one the build and runtime actually use.
+- If something might break in another environment, **document the requirement** (e.g. “cwd must be repo root for dev”) or fix the script — do not silently branch.
+
+When refactoring, **delete** obsolete paths and imports; do not keep them “just in case.”
diff --git a/.cursor/rules/no-push-to-main.mdc b/.cursor/rules/no-push-to-main.mdc
new file mode 100644
index 0000000..cb5070f
--- /dev/null
+++ b/.cursor/rules/no-push-to-main.mdc
@@ -0,0 +1,54 @@
+---
+description: Never push directly to main; always use a feature branch and GitLab MR
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Never push to main
+
+Agents must **never** push to `main` (or `master`) on any remote — including
+`gitlab` and `origin`.
+
+## Required workflow
+
+1. Create or switch to a **feature branch** (never commit intended work only on
+ `main` if it will be pushed).
+2. Commit on that branch with `git commit -s` — every commit needs a DCO
+ sign-off trailer (see `commit-sign-off.mdc`).
+3. Push the **feature branch** only: `git push -u gitlab HEAD` or
+ `git push -u gitlab <branch-name>`.
+4. Open a **GitLab merge request** into `main`. Do not merge unless the user
+ explicitly asks.
+
+## Explicit bans
+
+- `git push … main`, `git push … HEAD:main`, or any refspec that updates
+ `refs/heads/main` / `refs/heads/master` on a remote.
+- Force-pushing `main` / `master` unless the user **explicitly** requests that
+ exact force update in the current message (and even then, prefer
+ `--force-with-lease` and confirm the target SHA).
+- Treating “commit and push” as permission to push `main`. That phrase means
+ push the **current feature branch**.
+
+## If already on main locally
+
+When the user asks to commit/push and `git branch --show-current` is `main`:
+
+1. Create a feature branch from the commits (or before committing).
+2. Push that branch.
+3. Point the user at an MR URL.
+
+Do **not** push `main` “just this once.”
+
+## Related
+
+- Signing off each commit: `commit-sign-off.mdc`.
+- Dual-remote / public-cut rules: `repository-sync.mdc` and
+ `.cursor/skills/pair-repo-sync/SKILL.md`.
+- Those rules already forbid pushing GitLab `main` to GitHub; this rule forbids
+ pushing **to** GitLab `main` as well.
+- Filling the MR description / `pair-release-intent` block:
+ `.cursor/skills/pair-gitlab-mr/SKILL.md`.
diff --git a/.cursor/rules/platform-helpers.mdc b/.cursor/rules/platform-helpers.mdc
new file mode 100644
index 0000000..5df09b8
--- /dev/null
+++ b/.cursor/rules/platform-helpers.mdc
@@ -0,0 +1,21 @@
+---
+description: Platform detection and display helpers — never use process.platform or NodeJS.Platform directly
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Platform Helpers
+
+- Use `SupportedPlatform` (`'win32' | 'darwin' | 'linux'`) from
+ `src/shared/types/platform.ts` for all platform types.
+ Never use `NodeJS.Platform`.
+- Use `currentPlatform()` from `src/shared/utils/platform.ts` for runtime
+ platform checks. Never `process.platform` directly.
+- Use `PlatformDisplayName` (`'Windows' | 'MacOS' | 'Linux'`) for user-facing
+ display and wire format. Convert via `platformDisplayName()` /
+ `displayNameToPlatform()`.
+- `currentPlatform()` normalizes (never throws) — anything that isn't
+ `'win32'` or `'darwin'` maps to `'linux'`.
diff --git a/.cursor/rules/proxy-inference-routing.mdc b/.cursor/rules/proxy-inference-routing.mdc
new file mode 100644
index 0000000..8414469
--- /dev/null
+++ b/.cursor/rules/proxy-inference-routing.mdc
@@ -0,0 +1,78 @@
+---
+description: Backend-owned proxy routing and inference logging rules
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Proxy and Inference Routing
+
+Routing is owned by `ollama-proxy`, `lmstudio-proxy`,
+`nvpair-job-scheduler`, and `nvpair-ui-broker`.
+
+For model-bearing inference, each proxy first filters a request-local discovery
+snapshot to nodes whose per-engine inventory advertises the requested model.
+Empty and non-matching inventories are ineligible; an empty owner set returns a
+local `502` without contacting an engine. Ollama normalizes the implicit
+`:latest` tag; LM Studio IDs match exactly.
+
+Within that eligible owner set, proxy target precedence is:
+
+1. explicit manual selection;
+2. the scheduler priority list;
+3. deterministic proxy default ordering.
+
+An ineligible manual selection cannot override the capability gate. Retryable
+failover, including an upstream model `404` caused by stale positive inventory,
+continues only through other advertised owners and never broadens to excluded
+nodes.
+
+The scanner and manual-node worker feed compact maximum-GPU telemetry into the
+broker's source-aware cache; scanner observations take precedence. The broker
+ages and relays this feed to `nvpair-job-scheduler`.
+
+The scheduler smooths fresh utilization into pressure 0–3, treats invalid,
+missing, or older-than-10-second telemetry as neutral pressure 1, and ranks by
+`pending + gpuPressure`, then pressure, then stable UUID. It emits
+`schedule:priority` snapshots containing order, pending counts, and pressure.
+Each proxy chooses with `pending + gpuPressure + localReservations`, so
+concurrent bursts do not wait for workload feedback.
+
+## PAIR responsibilities
+
+- Register and pass the scheduler path through the canonical modular binary
+ inventory.
+- Consume proxy readiness, node presence, workload, and error effects.
+- Keep proxies in automatic routing mode.
+- Treat model **Load** as an engine model action, never a route selection.
+
+## Prohibited PAIR behavior
+
+- Do not call `node/select`.
+- Do not implement a TypeScript scheduler or load balancer.
+- Do not derive routing decisions from renderer telemetry.
+- Do not emit a separate proxy-node-switch log.
+- Do not treat GPU pressure as GPU capability, VRAM capacity, or device affinity.
+- Do not mirror scheduler smoothing or proxy load/reservation accounting in
+ TypeScript.
+
+The GPU chart's `inferenceHardwareIds` filter is display-only.
+
+## Inference logging
+
+Never log:
+
+- prompts or chat messages;
+- request bodies;
+- stream chunks;
+- full inference responses;
+- credentials or pairing data.
+
+Log only operational metadata such as engine, model, job ID, node ID, path,
+stream flag, and normalized error text.
+
+Use `getErrorString` or the relevant normalized backend error helper instead of
+serializing raw errors. Keep high-frequency request and routing details below
+the default info level.
diff --git a/.cursor/rules/readme-ownership.mdc b/.cursor/rules/readme-ownership.mdc
new file mode 100644
index 0000000..ea470ce
--- /dev/null
+++ b/.cursor/rules/readme-ownership.mdc
@@ -0,0 +1,22 @@
+---
+description: Keep the root README focused on public app usage
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Public README Scope
+
+- Treat the root `README.md` as the public introduction and user-facing guide
+ for installing, configuring, and using the PAIR app.
+- Update `README.md` when public app behavior, supported user workflows, or
+ user-facing terminology changes.
+- Do not add implementation notes, internal plans, backend update procedures,
+ test commands, build details, release operations, or troubleshooting dumps.
+ Put those in the appropriate focused file under `docs/`.
+- Update an existing canonical document instead of duplicating information.
+- If no suitable document exists, create a focused document under `docs/`.
+- Keep README additions concise, verified against the current UI, and useful to
+ someone evaluating or operating PAIR.
diff --git a/.cursor/rules/renderer-stores.mdc b/.cursor/rules/renderer-stores.mdc
new file mode 100644
index 0000000..8e31416
--- /dev/null
+++ b/.cursor/rules/renderer-stores.mdc
@@ -0,0 +1,53 @@
+---
+description: Renderer store and React component rules
+globs: src/ui/**/*.{ts,tsx}
+alwaysApply: false
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Renderer Stores
+
+Use the existing domain store:
+
+- connection;
+- nodes and discovered nodes;
+- metrics;
+- engine status, models, progress, updates, and pending actions;
+- workloads;
+- errors;
+- cluster invitations;
+- overview-only UI state.
+
+Initialization and teardown belong in `src/ui/stores/init.ts`.
+
+## Selectors
+
+- Select stable scalar or object references when possible.
+- Wrap arrays created from a `Map` with `useShallow`.
+- Do not use `useShallow` directly on `Array.from(map.entries())`; each entry
+ tuple is a new array.
+- For nested map projections, subscribe to a stable generation value and build
+ the projection in `useMemo`.
+
+## State boundary
+
+- Service state comes from `window.pairApi` snapshots and push events.
+- Components do not keep duplicate engine lifecycle or progress state.
+- Engine and model optimism comes only from `pending-actions.store.ts`.
+- Local component state is appropriate for transient view concerns such as
+ open menus, draft form values, or selected tabs.
+
+## Communication
+
+Do not call backend HTTP endpoints directly from renderer code. Use:
+
+- `window.pairApi` for service data and commands;
+- `window.windowApi` for Electron-native operations.
+
+## Window routing
+
+`src/ui/components/App.tsx` selects the application surface from the `window`
+query parameter. Keep new windows in that central router.
diff --git a/.cursor/rules/security.mdc b/.cursor/rules/security.mdc
new file mode 100644
index 0000000..9ba65c0
--- /dev/null
+++ b/.cursor/rules/security.mdc
@@ -0,0 +1,37 @@
+---
+description: Security ownership boundary — the backend owns all cluster trust; PAIR implements none
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Security
+
+PAIR implements **no** security or cryptography. Cluster identity, PIN pairing,
+trusted certificates, membership, removal, and every node-to-node mTLS channel
+are owned entirely by the backend (`nvpair-cluster-manager`, supervised by
+`nvpair-ui-broker`). Do not mirror the backend's trust mechanics in TypeScript
+and do not document them here as if PAIR owned them.
+
+PAIR only:
+
+- relays `cluster:*` and `nodes:*` requests to the broker;
+- consumes and renders the resulting notifications (invite status, membership);
+- persists the public cluster identity through `nvpair-node-settings`.
+
+## UI copy guardrails
+
+- The pairing PIN is a low-entropy convenience code. Never present it as a
+ strong authenticator.
+- Cluster membership is not proof of a vetted, individually-paired peer. Do not
+ build flows that assume it is.
+
+## Prohibited in PAIR code
+
+- any cluster-secret, auth-proof, certificate, or CA generation/handling;
+- renderer access to private key material;
+- reimplementing or wrapping the backend trust fabric in TypeScript;
+- logging PINs, certificates, private keys, inference prompts, or response
+ bodies.
diff --git a/.cursor/rules/service-contracts.mdc b/.cursor/rules/service-contracts.mdc
new file mode 100644
index 0000000..3985fe2
--- /dev/null
+++ b/.cursor/rules/service-contracts.mdc
@@ -0,0 +1,95 @@
+---
+description: Verify desktop ↔ services JSON-RPC contracts and binary inventory parity
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Service contracts
+
+`services/` is the authoritative backend source tree in this monorepo. Edit it
+directly under `services/`; there is no git submodule or external alignment pin.
+
+`npm run build:modular-binaries` compiles shipped binaries from that tree into
+`desktop/cli-bin/`.
+
+## Contract artifacts
+
+- `desktop/docs/service-contract-exceptions.json` — intentionally unintegrated
+ JSON-RPC methods (`ignoredMethods` only; edit by hand with a reason per entry).
+- `desktop/docs/services-api.md` — generated JSON-RPC method surface (do not edit
+ by hand).
+- `desktop/docs/services-parity.md` — concise current capability status.
+- `desktop/docs/services-backend.md` — current integration and update
+ procedure.
+- `desktop/scripts/verify-service-contracts.ts` — drift and generation tool.
+
+Never edit `desktop/docs/services-api.md` by hand.
+
+## Commands
+
+From `desktop/`:
+
+```bash
+npm run service-contracts
+npm run service-contracts:write
+npm run service-contracts:check
+```
+
+- `service-contracts` reports method drift, missing notification consumers, unused
+ backend requests, binary inventory gaps, firewall helper parity, and any
+ hardcoded product/component versions in hand-maintained docs.
+- `service-contracts:write` regenerates `docs/services-api.md` from the current
+ `services/` tree. It reads the component list from `services/versions.json` but
+ renders no version numbers: the release bot rewrites that file after merge
+ without regenerating anything, so embedding them turned the freshness gate red
+ on `main` after every release.
+- `service-contracts:check` fails on unhandled drift, stale generated output, or
+ hardcoded versions in `services-backend.md` / `services-parity.md` (CI gate).
+
+## Backend change workflow
+
+1. Change `services/`.
+2. Run `npm run service-contracts` and review component version changes, emitted
+ notifications, handled requests, and new binary components.
+3. Read the changed module's `README.md` / `spec.md` and the Go implementation.
+4. Update desktop runtime inventory, broker flags, handlers, state projection,
+ frontend contracts, and current documentation as required.
+5. Resolve every missing notification with a consumer or an `ignoredMethods`
+ entry in `service-contract-exceptions.json`.
+6. Verify every meaningful payload field, not only the method name.
+7. Run `npm run service-contracts:write` when Go RPC surfaces changed.
+8. Run `npm run service-contracts:check`, `npm run build:modular-binaries -- --force`,
+ and `npm run typecheck`.
+9. Commit `services/` and desktop integration edits together.
+
+## Version bumps depend on the remote
+
+On GitLab, declare bumps in the merge request `pair-release-intent:v1` block and
+leave `services/versions.json` and root `CHANGELOG.md` alone — `validate:release-intent`
+fails a hand edit without `<!-- pair-release-intent-allow-owned-files -->`, and
+`apply:release-intent` writes both files after merge. See
+`.cursor/skills/pair-gitlab-mr/SKILL.md` and `ci/release-intent/README.md`.
+
+GitHub has no such pipeline, and the cut deletes `ci/`, so a contributor there
+edits both files by hand. The public docs (`services/VERSIONING.md`,
+`services/readme.md`, `CONTRIBUTING.md`, `CHANGELOG.md`) describe the manual path
+as the default and must not mention internal release tooling, instruct readers to
+declare a release in a merge request, or point at `ci/release-intent/`.
+
+## Rules
+
+- Every runtime component in `services/versions.json` must be represented in
+ `desktop/src/shared/constants/modular-binaries.ts`.
+- Do not restate product or component versions in any doc — including the
+ generated `docs/services-api.md`. They live in `services/versions.json` alone,
+ so a release bump cannot leave a doc stale.
+- Electron and the broker must never both launch the same worker.
+- Every ignored method needs a current technical reason.
+- A handled method is not sufficient evidence of payload coverage; inspect the
+ backend struct's JSON fields and the complete PAIR consumer path.
+- Unused backend methods are opportunities, not automatically required features.
+- Keep parity documentation focused on what exists now. Git history records how
+ the integration changed.
diff --git a/.cursor/rules/services-agent-onboarding.mdc b/.cursor/rules/services-agent-onboarding.mdc
new file mode 100644
index 0000000..0ab0d35
--- /dev/null
+++ b/.cursor/rules/services-agent-onboarding.mdc
@@ -0,0 +1,26 @@
+---
+description: Read the backend's rules and docs before changing services code
+alwaysApply: true
+---
+
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Agent onboarding (services)
+
+Before writing or changing code under `services/`, read its rules and docs into
+context and follow them:
+
+- Root `AGENTS.md` (services section) and `services/*/spec.md` — the twelve
+ binaries, build/versioning, and subprocess + JSON-RPC conventions.
+- `.cursor/rules/*` — monorepo rules (especially `service-contracts.mdc` and
+ `services-change-propagation.mdc`).
+- The touched module's `README.md` and `spec.md`. `spec.md` is normative — where
+ a module README and its `spec.md` disagree, `spec.md` wins.
+
+The desktop UI lives in sibling `desktop/` in this monorepo. When a JSON-RPC
+contract, port, or push event changes, update the producing Go service, the
+Electron bridge under `desktop/src/electron/service-bridge/`, and run
+`npm --prefix desktop run service-contracts:check`.
diff --git a/.cursor/rules/services-change-propagation.mdc b/.cursor/rules/services-change-propagation.mdc
new file mode 100644
index 0000000..2742cf1
--- /dev/null
+++ b/.cursor/rules/services-change-propagation.mdc
@@ -0,0 +1,54 @@
+---
+description: Required architecture-boundary and cross-service checks for every DHC change
+alwaysApply: true
+---
+
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# DHC change propagation
+
+## Monorepo layout
+
+- Go services live under `services/`; the Electron desktop app lives under
+ `desktop/`.
+- Wails and external-only `dhc-ui` checkouts are retired for day-to-day work.
+ Trace contract changes through `services/` producers into `desktop/` consumers
+ in this repository.
+
+## Before changing code
+
+1. Trace the relevant runtime path: producer -> shared wire type -> broker/relay
+ -> every consumer -> UI/TUI. Then inspect the applicable tests, docs, build,
+ packaging, and installer surfaces.
+2. Search exact identifiers from the repository root, for example
+ `rg -n -F 'engine:status' .`. If `rg` is unavailable, use
+ `git grep -n -F 'engine:status' -- .` for tracked files. Repeat for the
+ payload field, HTTP route, discovery key, setting, port, and component name.
+ Inspect matches in the producer, `shared/`, `nvpair-ui-broker/`, subscribing
+ workers, `nvpair-tui/`, `tests/`, `desktop/src/`, build/installer scripts,
+ and CI as applicable. Do not assume the first match is the only consumer.
+3. State which components are affected. If a layer is intentionally unchanged,
+ record the evidence that its existing contract still works.
+
+## Required propagation checks
+
+- Contract or payload changes: update every producer and consumer, shared types,
+ protocol docs, and cross-process tests. Update `desktop/` bridge handlers,
+ shared channel types, and run `npm --prefix desktop run service-contracts:check`.
+- Proxy behavior: inspect both `ollama-proxy` and `lmstudio-proxy`; preserve their
+ intentional parity unless the behavior is engine-specific.
+- Discovery or identity changes: inspect `shared/noderec`, node scanner, broker
+ relay, manual nodes, scheduler/proxies, and UI-facing snapshots.
+- New, renamed, or removed binaries/services: update broker supervision, all
+ build and installer scripts, CI, applicable firewall rules for network
+ listeners or mDNS, `versions.json`, `bom.md`, docs, and cross-process test
+ setup.
+- Settings or lifecycle changes: inspect node settings, engine manager, broker
+ startup/shutdown ordering, remote control, persistence, and UI/TUI callers.
+
+Do not call a change complete until focused tests and the affected cross-process
+path pass, and the MR explicitly lists audited components and excluded adjacent
+work.
diff --git a/.cursor/rules/state-and-auto-start.mdc b/.cursor/rules/state-and-auto-start.mdc
new file mode 100644
index 0000000..2326d23
--- /dev/null
+++ b/.cursor/rules/state-and-auto-start.mdc
@@ -0,0 +1,42 @@
+---
+description: Push-driven renderer state and centralized optimistic engine actions
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Reactive State
+
+The modular service is the source of truth. Renderer stores display snapshots
+and push events.
+
+- Fetch an initial snapshot before or while subscribing to domain pushes.
+- Treat engine and model commands as fire-and-forget mutations.
+- Do not populate durable state from mutation responses.
+- Render engine lifecycle from `engines:state-changed`.
+- Render operation progress from `engines:progress-changed` and
+ `engines:progress-cleared`.
+- Keep node, metrics, workloads, discovery, cluster, and error state in their
+ own stores.
+
+## Pending actions
+
+`src/ui/stores/pending-actions.store.ts` is the only optimistic operation state
+for engine and model commands.
+
+- `fireCommand` in `src/ui/api/engine-api.ts` starts pending entries.
+- Components may read pending entries but must not write them.
+- Backend state, progress, and matching errors supersede optimistic state.
+- Pending state is memory-only and must not survive reload.
+- Entries are keyed by node and action so remote and local operations share the
+ same mechanism.
+
+Do not add per-component lifecycle or model loading flags.
+
+## Backend-owned lifecycle preferences
+
+Engine auto-start and lifecycle persistence are owned by
+`nvpair-engine-manager`. PAIR sends commands and reflects reported state; it
+must not maintain a second auto-start source of truth.
diff --git a/.cursor/rules/system-architecture.mdc b/.cursor/rules/system-architecture.mdc
new file mode 100644
index 0000000..44e97f6
--- /dev/null
+++ b/.cursor/rules/system-architecture.mdc
@@ -0,0 +1,244 @@
+---
+description: Current PAIR runtime architecture, communication paths, modular services, and security boundaries
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# System Architecture
+
+`docs/architecture.md` is the rendered current-state reference.
+
+## Process model
+
+PAIR is an Electron application backed by the sibling `services/` tree.
+
+- Electron starts only `nvpair-ui-broker`.
+- The broker supervises every runtime worker.
+- Backend processes communicate with their parent over stdio JSON-RPC.
+- Development binaries live in `cli-bin/`.
+- Packaged binaries live in `process.resourcesPath/cli-bin`.
+
+The canonical inventory is `src/shared/constants/modular-binaries.ts`.
+
+Broker-owned workers:
+
+- `ollama-proxy`;
+- `lmstudio-proxy`;
+- `nvpair-node-scanner`;
+- `nvpair-node-info`;
+- `nvpair-workload-manager`;
+- `nvpair-cluster-manager`;
+- `nvpair-node-settings`;
+- `nvpair-manual-nodes`;
+- `nvpair-engine-manager`;
+- `nvpair-errors`;
+- `nvpair-job-scheduler`.
+
+`nvpair-tui` is bundled but not supervised by Electron or the broker.
+
+Never launch one worker from both Electron and the broker. There is no
+broker-absent fallback.
+
+The Inference Demo's `inference-dispatcher` is the one non-broker executable
+Electron launches. It is not a worker: its source lives in
+`scripts/inference-dispatcher` at the monorepo root, it is absent from
+`services/versions.json` and `modular-binaries.ts`, and it ships in its own
+`tools/` resource directory. See "Inference Demo" below.
+
+The connector remains `connecting` until broker `app:ready` and the required
+Ollama proxy readiness arrive. A startup deadline routes failures to
+Settings > Service with the error and log/restart controls; late readiness
+transitions the existing process tree to connected.
+
+## Communication
+
+### Renderer to service
+
+`window.pairApi` is the only renderer service-control API. It uses
+`window.__PAIR_TRANSPORT__`, the `service-bridge:*` IPC envelope, Electron main
+handlers, and the broker.
+
+Logical invoke and push types live in `src/shared/types/ws-channels.ts`.
+Browser mode is unsupported.
+
+### Renderer to Electron
+
+`window.windowApi` is reserved for:
+
+- window and tray management;
+- clipboard;
+- service lifecycle and logs;
+- updater control;
+- first-run state.
+
+IPC types live in `src/shared/types/ipc-channels.ts`. All handlers use
+`safeHandle()`.
+
+### Terminal
+
+PAIR has no Electron-backed console client. The `nvpair` command on PATH is a
+launcher for the bundled Go `nvpair-tui`, which owns its own broker and worker
+tree. Electron generates that launcher on packaged builds
+(`src/electron/nvpair-command.ts`); the Debian package installs the equivalent
+wrapper at `/usr/bin/nvpair`. Do not add a TypeScript command surface, control
+socket, or local control server.
+
+### Node telemetry
+
+Electron directly polls each discovered node's advertised `/v1/node-info`
+endpoint every two seconds while it is healthy. Consecutive failures back off to
+4, 8, 16, then 30 seconds and reset on success or an endpoint change. This is the
+only service-data HTTP exception because rich telemetry is not exposed by the
+broker JSON-RPC contract.
+
+This renderer-facing metrics path is display-only. Independently, the backend
+scanner provides compact maximum-GPU utilization on the same healthy cadence and
+capped failure backoff; the manual-node worker supplies the same payload shape.
+The broker uses both for scheduling.
+
+### Inference HTTP
+
+Ollama and LM Studio proxies expose local client-compatible HTTP endpoints.
+Chat behaves as a local third-party client. Prompts, messages, chunks, and
+response bodies must never be logged.
+
+## Runtime defaults
+
+Backend-coupled constants belong in
+`src/shared/constants/modular-runtime.ts`.
+
+- Prefer live broker or discovery values.
+- Do not assume a proxy port before the broker reports it.
+- Native chat fallbacks are Ollama `127.0.0.1:11434` and LM Studio
+ `127.0.0.1:1234`.
+- Cluster pairing currently uses port `14321`.
+- Node telemetry path is `/v1/node-info`.
+
+Backend discovery service names and TXT layouts are not PAIR contracts. Consume
+the broker's reported discovery snapshots instead of duplicating those details.
+
+## State flow
+
+The service is authoritative.
+
+1. The UI sends commands.
+2. The broker and workers execute them.
+3. Backend notifications update `ModularBridgeState`.
+4. Typed push events update renderer stores.
+
+Stores fetch domain snapshots on startup and subscribe to push events. Engine
+commands return no state. The centralized pending-actions store is the only
+optimistic engine/model state in the renderer.
+
+Current push channels are declared in `WsPushChannelMap`; do not maintain a
+second handwritten channel list.
+
+## Discovery
+
+`nvpair-node-scanner` is the discovery authority. The broker exposes canonical
+addresses, trust state, model inventory, and per-engine model attribution in
+`AvailableNode`.
+
+Electron merges discovery, proxy presence, engine-manager facts, and node-info
+metrics into the renderer node model.
+
+Manual nodes go through the broker's `node/add`, `node/remove`, and `nodes/list`
+relay. Electron persists and replays user entries.
+
+## Routing
+
+Routing is backend-owned:
+
+1. for model-bearing inference, filter to nodes whose per-engine inventory
+ advertises the requested model;
+2. within that owner set, apply explicit manual selection;
+3. apply `nvpair-job-scheduler` priority;
+4. use deterministic proxy default order.
+
+Empty and non-matching inventories are excluded. If no advertised owner is
+routable, the proxy returns a local `502`; retryable upstream failures continue
+only through other advertised owners.
+
+PAIR does not call `node/select` and must not implement a TypeScript router.
+The broker relays pending workload and source-aware GPU telemetry. The scheduler
+uses EWMA-smoothed fresh utilization to derive pressure 0–3, with neutral
+pressure 1 for invalid, missing, or stale data, then ranks by
+`pending + gpuPressure`, pressure, and UUID. Each proxy minimizes
+`pending + gpuPressure + localReservations` for capable nodes.
+
+## Inference Demo
+
+A fixed sixty-second burst of synthetic traffic sent through the local proxies
+so job activity is visible on Overview.
+
+- Electron main owns the schedule (`src/electron/inference-demo.ts`,
+ `src/electron/inference-demo-schedule.ts`).
+- Each request spawns the bundled `inference-dispatcher`, which behaves as an
+ ordinary third-party HTTP client.
+- Requests target a broker-reported proxy port, never an engine's own port. The
+ backend decides placement; PAIR must not describe the demo as distributing
+ work itself.
+- Progress is broadcast on the `demo:state` Electron push channel
+ (`IpcPushChannelMap`), not the service push bus. State is node-local and is
+ not synchronized.
+- Children run with `stdio: 'ignore'` and with `INFERENCE_DISPATCHER_*` stripped
+ from the environment. Never surface or log prompts or responses.
+
+## Engines
+
+`nvpair-engine-manager` owns lifecycle, port, desired-state, and model
+operations.
+
+- Local lifecycle supports install, start, stop, uninstall, update, and port
+ changes.
+- Remote lifecycle uses the engine manager's remote control methods where
+ available.
+- `engine:prepare-shutdown` stops processes without clearing persisted desired
+ state.
+- Engine and proxy ports are persisted by their backend owners.
+- Running adopted engines reject operations that require process ownership.
+- Per-engine environment and CLI argument overrides are not part of the current
+ contract.
+
+The model hub is Electron-main functionality under `src/electron/model-hub/`.
+It provides curated Ollama and LM Studio catalogs; model operations still go
+through the engine manager.
+
+## Pairing and security
+
+`nvpair-cluster-manager` and the other backend workers own cluster identity,
+PIN pairing, trusted certificates, membership, and every node-to-node channel.
+PAIR implements **no** security or cryptography: it relays pairing and
+membership commands, renders the resulting notifications, and never reads keys
+or builds transport security.
+
+The PIN is a convenience pairing code, not a strong authenticator. See
+`.cursor/rules/security.mdc`.
+
+## Packaging
+
+`npm run build:modular-binaries` builds the backend for the target platform and
+writes `cli-bin/manifest.json`. Packaging rejects stale or unexpected `cli-bin`
+files.
+
+The macOS privileged helper firewall list is derived from
+`needsFirewallAccess` in `MODULAR_RUNTIME_BINARIES`.
+`npm run service-contracts:check` verifies parity with the Swift helper.
+
+Build and release details live in `docs/macos-privileged-helper.md`.
+
+## Documentation
+
+Keep these current when contracts change:
+
+- `docs/architecture.md`;
+- `docs/frontend-api.md`;
+- `docs/services-backend.md`;
+- `docs/services-parity.md`;
+- this rule and `architecture.mdc`.
+
+Do not add migration diaries or completed historical narratives. Git history is
+the history.
diff --git a/.cursor/rules/test-type-discipline.mdc b/.cursor/rules/test-type-discipline.mdc
new file mode 100644
index 0000000..33096e3
--- /dev/null
+++ b/.cursor/rules/test-type-discipline.mdc
@@ -0,0 +1,49 @@
+---
+description: Type-safe modular test patterns and isolation requirements
+globs: tests/**/*.{ts,tsx}
+alwaysApply: false
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Test Discipline
+
+Tests follow the same type and import rules as production code:
+
+- no type casts, `any`, or `unknown` data shapes;
+- static imports only;
+- `@/...` for cross-directory source imports;
+- real shared contract types instead of test-specific copies.
+
+## Typed mocks
+
+Parameterize `vi.fn` with the function type being replaced.
+
+```ts
+const invoke = vi.fn<PreloadServiceTransport['invoke']>()
+```
+
+Use `vi.mocked(realFunction)` for configured module mocks and call assertions.
+Reusable fakes implement the production interface they replace.
+
+## Fixtures
+
+- Use typed `.ts` fixtures.
+- Prefer `satisfies` for object-shape validation.
+- Keep reusable filesystem isolation in `tests/fixtures/tmpdir.ts`.
+- Keep process and network isolation in `tests/fixtures/isolation.ts`.
+
+## Side effects
+
+Mock process, filesystem, network, registry, and Electron boundaries in the test
+runtime. Do not add test-only branches or environment flags to production code.
+
+`PAIR_USER_DATA` is the supported runtime override used by tests to isolate
+application data. Do not add `PAIR_TEST_DISABLE_*` switches.
+
+## Verification
+
+Tests are part of `npm run typecheck` through `tsconfig.test.json`. Run the
+targeted Vitest project and `npm run typecheck` after changing test contracts.
diff --git a/.cursor/rules/type-discipline.mdc b/.cursor/rules/type-discipline.mdc
new file mode 100644
index 0000000..e48c85b
--- /dev/null
+++ b/.cursor/rules/type-discipline.mdc
@@ -0,0 +1,34 @@
+---
+description: Rules for creating, consolidating, and exporting TypeScript types
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Type Discipline
+
+## Reuse canonical types
+
+Before adding an interface or type:
+
+- search for the proposed name and close synonyms;
+- search for its distinctive fields;
+- prefer the shared process, IPC, service-channel, or engine type that already
+ represents the contract;
+- keep renderer/service contracts under `src/shared/types/`.
+
+Do not create a layer-specific copy of an existing payload shape.
+
+## Export only when imported
+
+- Keep file-local types unexported.
+- Inline one-off channel request or response shapes.
+- Remove `export` when the final external import is removed.
+- Import from the defining module; do not add convenience re-exports.
+
+## Consolidate completely
+
+When replacing or moving a type, remove the superseded definition and all of
+its imports in the same change. Do not leave aliases or compatibility shims.
diff --git a/.cursor/rules/type-safety.mdc b/.cursor/rules/type-safety.mdc
new file mode 100644
index 0000000..69ce464
--- /dev/null
+++ b/.cursor/rules/type-safety.mdc
@@ -0,0 +1,19 @@
+---
+description: TypeScript safety rules — no casts, no any, no unknown in signatures
+alwaysApply: true
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Type Safety
+
+- **No type casting.** Never use `as Type`, `as any`, `as unknown`, or `: any`.
+ All types must be explicit and correct. If a cast seems necessary, the types
+ are wrong — fix the types.
+- **No `unknown`** in function signatures or data structures. Use properly
+ typed interfaces.
+
+See also **`type-discipline.mdc`** for rules about creating, consolidating,
+and exporting types.
diff --git a/services/nvpair-cluster-manager/spec.md b/services/nvpair-cluster-manager/spec.md
new file mode 100644
index 0000000..36f35e3
--- /dev/null
+++ b/services/nvpair-cluster-manager/spec.md
@@ -0,0 +1,595 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Microservice: Cluster Manager
+
+## 1. Purpose
+Owns cluster membership — which nodes belong to the same logical cluster — and the interactive join/leave handshake that establishes it. The Cluster Manager invites nodes, receives and responds to invites, removes nodes, and maintains the authoritative local view of cluster members, giving the customer the data to render "who is in my cluster" and the controls to change it. `cluster_id` is the membership identifier this service negotiates around, while the join/leave protocol itself lives here.
+
+Because membership **is** trust, this service is also the **trust fabric** for the cluster: it owns each node's cryptographic identity (a stable keypair), bootstraps mutual-TLS trust during the join handshake, and maintains the **trusted-node store** that backs mTLS on every inter-node interface in the system. `nvpair-workload-manager` and the other inter-node services consume the certs and trust roots this service provisions rather than each rolling their own.
+
+## 2. Scope
+**In scope**
+- Maintain the authoritative local membership set for this node's cluster (who's a member, who has a pending invite).
+- Drive the interactive invite handshake end to end: send an invite to a peer, surface an incoming invite to the local Broker, relay the user's accept/decline, and reconcile both sides' membership on the outcome.
+- Remove a node from the cluster and notify the affected peer so membership stays symmetric.
+- Resolve peer reachability from the broker-relayed consolidated discovery directory, with an explicitly supplied address taking precedence.
+- **Own this node's cryptographic identity**: generate and persist a stable per-node keypair and self-signed certificate (keyed to a stable node UUID, §7.4) on first run.
+- **Bootstrap mTLS trust via an OOB-authenticated pairing**: run an **EAP-NOOB** (RFC 9140) key exchange over the invite handshake, authenticated by a **six-digit PIN** the user carries out of band, to exchange and pin each node's self-signed certificate (§7.4). Persist the resulting **trusted-node store** (UUID → pinned cert) and revoke a pin when a node is removed.
+- **Enforce mTLS on its own inter-node interface** once paired: serve HTTPS with `RequireAnyClientCert`, verify the presented cert against the trusted-node store, and reject untrusted callers (`403`). (The pairing exchange itself runs before any pin exists — see §7.2/§7.4.)
+- **Expose the trust fabric** (local keypair + trusted-node store) so other inter-node services can authenticate with mTLS without rolling their own.
+
+**Out of scope**
+- Owning the user-facing `cluster_id` setting — that remains `nvpair-node-settings`. Cluster Manager does persist its active admission `{clusterId, epoch}` as crash-consistent security state; this is authoritative for authorization/recovery, while the Broker-facing setting remains the UI configuration mirror.
+- Being a full PKI / certificate authority. There is no central CA: each node self-signs its own leaf and trust is established pairwise at join time, authenticated by the EAP-NOOB pairing PIN (§7.4). No CRL/OCSP infrastructure; removal-from-cluster is the revocation mechanism.
+- Workload and error propagation across the cluster — those are `nvpair-workload-manager` and `nvpair-errors`. Membership defined here is the set those services should eventually scope their fan-out to, and the trusted-node store this service owns is what authenticates that traffic, but that wiring is separate work.
+- The pre-existing **bring-your-own** operator TLS for the `nvpair-node-info` HTTP surface (`tls-settings.json`, `--cert`/`--client-ca`, etc.). That is a separate, manually-configured mechanism; the cluster trust fabric here is self-managed and auto-provisioned. Converging the two is a possible follow-up (§4), not part of this contract.
+- Auto-accepting invites. Invites are always interactive by design; there is no auto-join path because the user-entered PIN is the out-of-band step that authenticates the pairing (§7.4).
+
+## 3. Key Use Cases
+- **First run — mint identity**: on first start the Cluster Manager generates this node's stable UUID + keypair and a self-signed certificate, and persists them (§7.4). This identity is reused across restarts and is what every peer pins to authenticate this node.
+- **Create a cluster (founder)**: a node with no cluster (`cluster:get-node-id` returns `clusterId: ""`) calls `cluster:create` to initialize a brand-new cluster of one — minting a fresh, globally-unique `clusterId` (UUID v4) plus a `clusterFriendlyName`, recording itself as the founding member, and reporting the new identity via `cluster:identity-changed` so the Broker persists it to `nvpair-node-settings`. An unclustered node has three ways into a cluster: call `cluster:create` **explicitly** (e.g. to set a `clusterFriendlyName` up front), **just invite a peer** — the first `cluster:invite-node` auto-founds a cluster of one as a side effect (§7.0/§7.2), so no separate create step is required — or **skip both and wait to be invited**, adopting the inviter's cluster on accept. `cluster:create` is therefore optional: it is the explicit form of the same founding the first invite performs implicitly, so a UI does not have to orchestrate "check membership, then create, then invite" itself.
+- **Invite a node (outbound)**: the Broker emits `cluster:invite-node` (`params.address`, optional `params.port`/`params.nodeId`) on `stdin`. If this node isn't clustered yet, the invite **first auto-founds a cluster of one** (the same in-process mint-and-record founding as `cluster:create`, emitting `cluster:identity-changed`) and then proceeds. The Cluster Manager (acting as the EAP-NOOB **Server**) opens a pairing session with the target and runs the EAP-NOOB **Initial Exchange** in-band — both sides carry their full certificate PEM in the EAP-NOOB `ServerInfo`/`PeerInfo` objects (§7.4) — then derives a **six-digit PIN** from the OOB secret and returns `{inviteId, state: "pending", pin}` so the inviter's UI can display the PIN. No trust is established yet. If the target refuses because it is **already clustered**, the Initial Exchange comes back with an explicit rejection and the result is `{inviteId, state: "rejected", reason: "already-clustered"}` — no PIN (and a solo cluster this invite just auto-founded is dropped again). (A well-behaved UI also skips the invite when it can already see the target's `cluster-uuid=` over discovery; this is the authoritative backstop.)
+- **Receive an invite (inbound)**: the pairing's Initial Exchange arrives over the inter-node interface; the Cluster Manager (EAP-NOOB **Peer**) runs it automatically (machine-to-machine, no human yet), stashes the inviter's cert from the transcript (not yet trusted), records a pending-inbound invite, and emits a `cluster:invite-received` notification on `stdout` so the Broker can prompt the local user to enter the PIN shown on the inviting node. A new invite from the same authenticated `fromNodeUuid` **supersedes that sender's older pending inbound invite**: the older session is canceled locally, `cluster:invite-canceled` dismisses its prompt, and a best-effort decline tells the inviter to invalidate the old PIN. Pending invites from different sender UUIDs remain independent. **If this node is already clustered it refuses the pairing up front** — before creating a session, minting a PIN, or emitting `cluster:invite-received` — replying on the pairing channel with `HTTP 409` and `{rejected: true, reason: "already-clustered"}` so the inviter reports `state: "rejected"`. An already-clustered node must **leave** (or be removed) before it can pair again.
+- **Respond to an invite (enter the PIN)**: the user reads the PIN from the inviting node (out of band — in person, phone, chat) and accepts; the Broker sends `cluster:respond-to-invite` (`params.inviteId`, `params.accept`, `params.pin`). The Cluster Manager feeds the PIN to EAP-NOOB (`OOBInputNoob`, §7.4) and then drives the **Completion Exchange** back to the inviter (§7.2); on a verified PIN both sides reach the EAP-NOOB `Registered` state. Each side then reads the peer's now-authenticated cert from the pairing transcript and **pins it into the trusted-node store** (keyed by the peer's UUID), records the peer as a member, and (on the joiner) adopts the cluster's identity. A **wrong PIN** fails the pairing (no pin, no membership) and, mirroring the decline path, the joiner **best-effort notifies the inviter** over the pairing channel (`phase:"fail"`, carrying `reason:"incorrect-pin"`) so the inviter's invite flips to `failed`, its EAP session is torn down (PIN invalidated), and it emits `cluster:invite-failed` — the joiner (EAP Peer) detects the bad MAC first and never drives the Completion round that would otherwise surface the failure on the inviter, so without this signal the inviter would stay `pending` until its TTL expired. A decline works the same way over `phase:"decline"` so the inviter's invite flips to `declined`, its EAP session is torn down (PIN invalidated), and it emits `cluster:invite-declined` — without that signal the inviter would stay `pending` forever and UIs that lazily auto-create a solo cluster for the invite could not abandon it.
+- **Poll invite status**: the inviting Broker calls `cluster:invite-status` (`params.inviteId`) to read the current state (`pending` → `paired` / `declined` / `expired` / `failed`) without waiting on a push. The joiner drives the Completion Exchange back to the inviter when the user enters the PIN (§7.2), so the inviter observes `paired` via this read or the `nodes:changed` push; a decline or a wrong-PIN failure is observable the same way (or via the `cluster:invite-declined` / `cluster:invite-failed` push). A wrong-PIN `failed` also carries `reason:"incorrect-pin"` so the UI can show a specific message.
+- **List cluster members**: the Broker calls `nodes:get-initial` to seed its view with the current membership set (confirmed members plus any pending invites).
+- **Remove a node (= revoke one admission)**: the Broker emits `nodes:remove` (`params.nodeId`); the Cluster Manager first persists signed proof targeting the peer's exact authenticated admission, notifies it while its pin can still authenticate mTLS, then revalidates that the admission did not change before deleting the pin/member. A concurrent newer readmission is preserved. Removal proof, not elapsed time or a bare `403`, is the revocation mechanism.
+- **Edge case — duplicate / retried pairing or removal messages**: a re-delivered message correlated by the same `inviteId` / `nodeUuid` is idempotent — it does not create a second pending entry, re-pin a cert, or double-apply a membership change. A deliberate retry that creates a new `inviteId` is distinct, but on the joiner it supersedes any older pending invite from the same authenticated sender UUID.
+- **Edge case — peer unreachable**: a target that is down or partitioned can't be paired or cleanly removed. The Initial Exchange uses bounded timeouts/retries; an undeliverable invite ends `failed`, and a removal still takes effect locally — the pin is dropped immediately, so the removed node is denied even before it learns it was removed.
+
+## 4. Open Questions / Risks
+- **Membership persistence (closed)**: confirmed members, pins, active admission, removal proofs, and teardown intent survive restart; in-flight pairing sessions remain transient.
+- **`cluster_id` semantics on accept (closed)**: a joiner adopts the inviter's cluster id after the authenticated pairing commits; a founder mints a UUID v4.
+- **Who writes `cluster_id` (closed)**: Cluster Manager emits `cluster:identity-changed`; the Broker persists the UI setting. Cluster Manager separately persists admission state required for authorization and crash recovery.
+- **Authentication — decided**: the inter-node interface is **mTLS over HTTPS**, authenticated against the trusted-node store this service owns (§7.4). The trust model is **self-signed leaf certs pinned at the join handshake**, keyed by a **stable per-node UUID** rather than hostname — see §7.4 for the rationale and the on-disk layout. The pinning is bootstrapped by an **EAP-NOOB (RFC 9140) pairing authenticated by a user-carried PIN** (the in-tree `eap-noob` library). Residual decisions:
+ - **⚠️ Six-digit PIN is temporary security debt — MUST UPGRADE before production cross-node trust**: EAP-NOOB's security depends on the out-of-band secret (`Noob`) being high-entropy, because the in-band Completion Exchange exposes `NoobId = H("NoobId", Noob)` and the MACs over the transcript. A six-digit PIN (~20 bits) is therefore **offline-brute-forceable by an active man-in-the-middle** on the LAN: an attacker who relays the in-band exchange can recover the PIN from `NoobId`, derive the keys, and substitute its own cert. The PIN as specified defends against **passive eavesdroppers and accidental/unauthorized joins**, not a determined active MITM. This is accepted temporarily to ship the flow; it must be replaced with a high-entropy OOB value (a copy/paste pairing code or QR encoding a high-entropy `Noob`, ~16–32 bytes) before the cluster trust is relied on.
+ - **Library delta the PIN needs**: today `eap-noob` random-generates the 16-byte `Noob` and its OOB API exchanges a full `OOBMessage{PeerId, Noob, Hoob}`. The six-digit design needs **one** small additive change — a caller-injected `Noob` on each role (`Server.OOBOutputWith` / `Peer.OOBInputNoob`) — so the human-carried digits are the only OOB input; nothing else is relayed (the joiner already holds `PeerId` and recomputes `Hoob` locally). Concrete API and the exact PIN→16-byte-`Noob` encoding are in §7.4. The delta disappears when the OOB upgrades to a high-entropy pairing code.
+ - **CA-less pinning vs a cluster CA (leaning CA-less)**: pinning each peer's self-signed leaf needs no central authority and matches the no-founder, peer-to-peer model — but it's O(n²) pins and re-pins on rotation. A shared cluster CA (the accepting node, or the cluster founder, signs joiners) would shrink trust to "verify against the cluster CA" but centralizes issuance. Starting CA-less; because certs ride in the EAP-NOOB transcript, swapping the pinned-leaf check for a CA-chain check later needs no wire change.
+ - **Cert lifetime & rotation (open)**: proposed long-lived leaves (1–2 years) with a re-pin path when a node rotates its key (a node whose pin no longer matches is treated as untrusted until re-invited or an explicit re-pin flow runs). Exact lifetime, rotation trigger, and whether rotation can be done without a re-invite are TBD.
+ - **Sharing the trust fabric with other services (open)**: `nvpair-workload-manager` and `nvpair-errors` peer-sync also need mTLS. Intended: they consume the same keypair + trusted-node store this service owns (via a shared on-disk location or a small local query API). The exact handoff (file paths the Broker passes, vs. an IPC call) is unspecified here.
+ - **Convergence with BYO node-info TLS (open)**: whether the auto-provisioned cluster identity should eventually also serve the `nvpair-node-info` HTTPS surface (replacing the operator-supplied `tls-settings.json` certs) or stay separate.
+- **Invite expiry (closed)**: pending invites expire after a default TTL of **5 minutes** with no accept/decline, on **both** sides. Inbound (receiver) expiry drops the tentative pending-inbound member + session, emits `cluster:invite-expired` so the UI dismisses the PIN prompt, and best-effort signals the inviter (`phase:"expire"`) so it tears down immediately rather than waiting for its own TTL. Outbound (inviter) expiry tears down the EAP session, emits `cluster:invite-expired`, and runs provenance-safe invite-created solo cleanup; it is a purely local fallback (it does **not** signal the joiner — the receiver expires its own inbound invite, so both converge on `expired` rather than a timing-dependent `expired`/`canceled`). A newer invite from the same sender still *immediately* supersedes an older pending inbound invite as `canceled` (that is deliberate, not a TTL event). Exact TTL remains tunable later.
+- **Membership-change push (proposed, needs confirmation)**: a `nodes:changed` notification (full member snapshot on every change) would let the Broker keep its view live without polling `nodes:get-initial`. Included below as a proposed addition, not in the user's original list.
+- **Split membership convergence**: periodic roster reconciliation, durable removal-proof replay, and proof-bearing `403` responses converge nodes that were offline or restarted during a removal.
+- **Risk — discovery snapshot staleness**: the resolver map is only as current as the last `discovery:nodes` snapshot, so a departed node may linger as a resolvable target and a freshly added node may appear slowly. A Broker-supplied address bypasses the resolver entirely, so this bounds transitive resolution rather than the invite path.
+
+## 5. Requirements
+
+**Functional**
+- Accept `cluster:get-node-id`, `cluster:set-identity`, `cluster:create`, `nodes:get-initial`, `cluster:invite-node`, `cluster:invite-status`, `cluster:respond-to-invite`, `cluster:cancel-invite`, `nodes:remove`, `cluster:leave`, and `log/set-level` requests from the parent over `stdin` (or a named pipe) and return JSON-RPC results.
+- Self-own the node identity: on `cluster:get-node-id`, return the persisted `nodeUuid` plus the hostname-derived `nodeId`/`name`, cert fingerprint, and current `clusterId` (§7.4). Accept the *cluster* identity (`clusterId`/`clusterFriendlyName`) only via `cluster:set-identity`, and emit `cluster:identity-changed` when a pairing causes the local `clusterId` to change.
+- On `cluster:create` (valid only when unclustered), mint a fresh, globally-unique `clusterId` (random UUID v4 — never caller-supplied, never reused), set `clusterFriendlyName`, record this node as the founding member, emit `cluster:identity-changed`, and return the new identity; reject with `-32004` if the node is already clustered.
+- On `cluster:invite-node`, **first auto-found a cluster of one if this node is unclustered** (the same mint-and-record path as `cluster:create`, emitting `cluster:identity-changed`), then create a pending outbound invite with a unique `inviteId`, run the pairing Initial Exchange (§7.2), and return the `inviteId`, `state` (`pending`), and the six-digit `pin` to display.
+- Drive the pairing as the EAP-NOOB **Server** on `cluster:invite-node`: run the Initial Exchange in-band, embed the local cert PEM in `ServerInfo`, derive the six-digit PIN, and return it for display.
+- On an inbound pairing (EAP-NOOB **Peer**), run the Initial Exchange automatically (embedding the local cert PEM in `PeerInfo`), record a pending inbound invite, and emit `cluster:invite-received` to the Broker; never pin or change membership until the user enters the PIN.
+- On `cluster:respond-to-invite` with the PIN, feed it to EAP-NOOB (`OOBInputNoob`, §7.4), drive the Completion Exchange (§7.2), and on success pin the peer's transcript cert and record membership (joiner also adopts cluster identity). A wrong/expired PIN or a decline establishes no pin and no membership, and clears the pending-inbound member row it recorded for the inviter. On decline, also best-effort POST `phase:"decline"` to the inviter so its outbound invite reaches `declined` and its pairing session is dropped; on a wrong-PIN failure, best-effort POST `phase:"fail"` (with `reason:"incorrect-pin"`) so its outbound invite reaches `failed` the same way.
+- On `nodes:remove`, persist proof for the exact pinned admission, notify the peer, then revalidate the target admission before de-pinning; preserve a concurrently admitted newer incarnation.
+- Maintain a queryable membership set returned by `nodes:get-initial` (confirmed members and pending invites, distinguished by a `state` field).
+- Resolve peer Cluster Managers from the consolidated discovery directory: subscribe to the Broker's discovery relay for `cl` nodes and rebuild the resolver map from each snapshot, so a node can be invited whether it was discovered on the LAN or entered manually. A Broker-supplied address always takes precedence over the resolver.
+- Deduplicate inbound invites and responses by `inviteId` and removals by `nodeUuid` so retries are idempotent (no duplicate pending entries, no re-pinned certs, no double-applied membership changes).
+- Validate inbound payloads; reject malformed envelopes or unknown `method` / endpoint (`400 Bad Request`).
+- Generate and persist a stable per-node UUID + keypair + self-signed certificate on first run; reuse them across restarts (§7.4).
+- Persist the trusted-node store (UUID → pinned cert + metadata); pin a peer's cert on pairing success, drop it on removal, and reload it on startup.
+
+**Non-functional**
+- All inter-node traffic is **mTLS over HTTPS**: the server requires a client certificate and verifies the presented cert against the trusted-node store; an absent or unpinned cert is rejected (`403 Forbidden`). The one exception is the **pairing channel** (`POST /v1/cluster/pairing`), which by definition runs before a pin exists and is instead authenticated by the EAP-NOOB PIN (§7.2/§7.4).
+- The pairing PIN is six digits **for now** — accepted, documented security debt (§4). The design must keep the OOB value swappable for a high-entropy pairing code without changing the local Broker contract.
+- Private key material is stored with owner-only permissions (`0600` file / `0700` dir), matching the per-user config-dir convention `nvpair-node-settings` uses.
+- Membership and trust changes must be idempotent and reconcilable — re-delivery converges to the same state (and same pin) on both nodes.
+- A failed delivery to one peer (invite, response, or removal) must not block local state changes or other peers.
+- Serialize `stdout` writes so frames never interleave.
+
+## 6. Inputs and Outputs
+
+**Inputs** — from the parent over `stdin` / named pipe (JSON-RPC 2.0 requests with `id`, including the local cluster identity supplied via `cluster:set-identity` — see §7.0/§8; the *node* identity is self-generated, §7.4), or from peer nodes via HTTP REST (pairing messages on the pairing channel, removals over mTLS). See §7 for transport details.
+
+`ClusterNode` object (a cluster member or pending invitee):
+```json
+{
+ id: string // logical node id (mDNS instance name / hostname); the membership key. Display/logical identity, NOT the trust principal.
+ nodeUuid: string // stable cryptographic identity; the trusted-node-store key and cert subject (§7.4). Independent of hostname.
+ name: string // human-readable display name (falls back to id)
+ ipAddress: string // reachable address for the inter-node interface
+ port: number // inter-node port (default 14321)
+ clusterId: string // the cluster this membership belongs to
+ state: MembershipState
+ joinedAt: number | null // epoch ms when membership was confirmed; null while pending
+ lastSeen: number | null // epoch ms, last successful contact; null if never
+}
+```
+
+`MembershipState` (enum): `"member" | "pending-outbound" | "pending-inbound"`
+- `member` — join confirmed (both sides agreed).
+- `pending-outbound` — we invited them, awaiting their response.
+- `pending-inbound` — they invited us, awaiting the local user's response.
+
+`Invite` object — the Broker-facing view of a pairing session. The certificates themselves are **not** in this envelope; they travel inside the EAP-NOOB transcript (`ServerInfo`/`PeerInfo`, §7.4) and are only surfaced once authenticated.
+```json
+{
+ inviteId: string // unique per pairing session; the dedup / correlation key
+ fromNodeId: string // inviter logical node id (hostname)
+ fromNodeUuid: string // inviter cryptographic identity (cert subject); what the invitee pins on success
+ fromNodeName: string // inviter display name
+ toNodeId: string | null // invitee logical node id, if known to the inviter
+ clusterId: string // the cluster the invitee would join
+ clusterFriendlyName: string
+ pin: string | null // six-digit PIN — present in the cluster:invite-node RESULT (inviter displays it); never sent to the invitee and never logged
+ state: InviteState
+ createdAt: number // epoch ms
+ respondedAt: number | null // epoch ms when the PIN was entered / declined; null while pending
+}
+```
+
+The `pin` is returned only to the **inviting** node and carried to the joiner **by the user, out of band** — never on the wire, never logged; the joiner supplies it back via `cluster:respond-to-invite`.
+
+`InviteState` (enum): `"pending" | "paired" | "declined" | "canceled" | "expired" | "failed" | "rejected"`
+- `pending` — Initial Exchange done; awaiting the user's PIN entry.
+- `paired` — Completion Exchange succeeded; certs pinned and membership recorded (the success terminal state).
+- `declined` — the invitee's user declined.
+- `canceled` — the **inviter** aborted the invite before it completed (`cluster:cancel-invite`); the pairing session is torn down and the PIN invalidated. On the joiner, set when the inviter's cancel signal arrives.
+- `expired` — TTL elapsed with no PIN entry (see §4).
+- `failed` — pairing could not complete (peer unreachable, wrong PIN → MAC / `NoobId` mismatch, malformed).
+- `rejected` — the target **explicitly refused** the pairing during the Initial Exchange because it is already clustered (it must leave / be removed before it can pair again). No PIN is minted. The `invite-node` result also carries a `reason` (`"already-clustered"`). Distinct from `failed` (a transport/protocol failure) so a UI can show "already paired / node is in a cluster" rather than "invite failed".
+
+Validation: check every inbound envelope before processing. Reject malformed / unknown-`method` payloads on the inter-node interface (`400`); on the local interface, reply with a JSON-RPC `error` for any request carrying an `id`, and drop-and-log only lines that can't be correlated to an `id` — the full result-vs-error contract and code table are in §7.6. Assume the Broker supplies well-formed requests with epoch-millisecond timestamps.
+
+**Outputs** — to the Broker over `stdout` / named pipe (JSON-RPC results to its requests, plus the `cluster:invite-received` notification and the proposed `nodes:changed` notification), or to peers via HTTP REST (pairing messages on the pairing channel, and removals over mTLS). `stdout` writes are serialized so frames never interleave; inter-node delivery is best-effort (bounded timeouts and retries).
+
+## 7. API / Interface Contract
+
+Two interfaces: a **local interface** toward the same-node UI Broker, and an **inter-node interface** toward Cluster Manager instances on other nodes.
+
+### 7.0 Methods and notifications
+
+All traffic is JSON-RPC 2.0. The local interface uses `stdin`/`stdout` (or a named pipe) and — unlike workload-manager — is **request/response** (the Broker needs results: member lists, invite IDs, invite status). Inter-node uses HTTP REST (see §7.2).
+
+| Name | Direction | Kind | Summary |
+|------|-----------|------|---------|
+| `cluster:get-node-id` | Broker → CM | request | Return this node's own identity (`nodeUuid`, `nodeId`, `name`, cert fingerprint, current `clusterId`). |
+| `cluster:set-identity` | Broker → CM | request | Supply/refresh the local *cluster* identity (`clusterId`, `clusterFriendlyName`) from `nvpair-node-settings`. |
+| `cluster:create` | Broker → CM | request | Found a brand-new cluster of one (mints a unique `clusterId`, UUID v4); valid only when unclustered. Returns `{clusterId, clusterFriendlyName}`. |
+| `nodes:get-initial` | Broker → CM | request | Returns the current membership set (`{nodes: ClusterNode[]}`). |
+| `cluster:invite-node` | Broker → CM | request | Start a pairing; runs the Initial Exchange and returns `{inviteId, state, pin}` (PIN to display). |
+| `cluster:invite-status` | Broker → CM | request | Read a pairing's current state by `inviteId`; returns the `Invite`. |
+| `cluster:respond-to-invite` | Broker → CM | request | Submit the PIN (or decline) for a `pending-inbound` invite; returns the updated `Invite`. |
+| `cluster:cancel-invite` | Broker → CM | request | Abort a `pending`-outbound invite (the inviter's counterpart to a joiner decline); tears down the pairing session, invalidates the PIN, and best-effort notifies the joiner. Returns the updated `Invite`. |
+| `nodes:remove` | Broker → CM | request | Remove a *peer* from the cluster; returns `{nodeId, removed}`. Rejects removing self (use `cluster:leave`). |
+| `cluster:leave` | Broker → CM | request | This node leaves its cluster: announces departure, drops all pins/members, resets to unclustered. Returns `{left}`. |
+| `log/set-level` | Broker → CM | request | Standard `nvpair-shared/applog` level control (every subprocess accepts it). |
+| `cluster:invite-received` | CM → Broker | notification | A pairing arrived; carries the `Invite` so the UI can prompt for the PIN. |
+| `cluster:invite-canceled` | CM → Broker | notification | A still-pending inbound invite was canceled by its inviter or superseded by a newer invite from the same sender; carries the `Invite` (`state: "canceled"`) so the joiner's UI can dismiss its PIN prompt. |
+| `cluster:invite-declined` | CM → Broker | notification | Inviter-side: the joiner declined; carries the `Invite` with `state:"declined"` so the UI can clear the PIN / abandon a throwaway solo cluster. |
+| `cluster:invite-failed` | CM → Broker | notification | Inviter-side: the Completion Exchange failed (e.g. a wrong PIN); carries the `Invite` with `state:"failed"` (and `reason:"incorrect-pin"` on a wrong PIN) so the UI can show an "Incorrect PIN" error / abandon a throwaway solo cluster. |
+| `cluster:identity-changed` | CM → Broker | notification | The local `clusterId` changed (e.g. the joiner adopted the inviter's on pairing); payload `{clusterId, clusterFriendlyName}` so the Broker can persist it to `nvpair-node-settings`. |
+| `nodes:changed` _(proposed, §4)_ | CM → Broker | notification | Full membership snapshot pushed on every change. |
+
+- **`cluster:get-node-id` (Broker → CM)**: pure read of *this* node's own identity. Params: none. Result `{nodeUuid, nodeId, name, certFingerprint, clusterId}`. The `nodeUuid` is the self-generated, persisted identity (§7.4); `nodeId`/`name` default to the OS hostname; `clusterId` is `""` until set, created, or adopted — a `""` here is the unclustered signal a UI can surface (e.g. render "not in a cluster" or offer an explicit `cluster:create`). The caller no longer needs to create before inviting: `cluster:invite-node` auto-founds when unclustered (§7.0/§7.2), so this read is informational rather than a required gate on the invite path. Always available (the identity is minted at startup), so the UI can render "this is me" immediately.
+- **`cluster:set-identity` (Broker → CM)**: params `{clusterId?: string, clusterFriendlyName?: string}`. Supplies an **existing** cluster identity that `nvpair-node-settings` already holds (§8) so invites/pairings carry the right `clusterId`. The parent calls this at startup and whenever `nvpair-node-settings` reports a change. Result `{clusterId, clusterFriendlyName}` (the values now in effect). Does **not** touch `nodeUuid` or membership. An active durable admission is authoritative over an empty/stale settings reflection; clearing membership requires `cluster:leave` or authenticated removal. A normal startup restore reuses the durable admission epoch (migrating pre-v2 epoch-zero state to epoch 1), while a retired admission rejects stale non-empty settings even after process restart. Re-clustering must come from `cluster:create` or successful pairing.
+- **`cluster:create` (Broker → CM)**: params `{clusterFriendlyName?: string}` (optional). Valid **only when this node is currently unclustered** (`clusterId == ""`); otherwise `-32004` with `data:{reason:"already-clustered"}` (§7.6). **Always mints a fresh, globally-unique `clusterId` — a random UUID v4** (`crypto/rand`), so every cluster gets a distinct id by construction (collision is effectively impossible; never reused). The caller does **not** supply the `clusterId` here — to *replay* a previously-known id (restore / normal startup) use `cluster:set-identity`, which is the path that takes an existing value from `nvpair-node-settings`. Sets `clusterFriendlyName` (defaulting to the OS hostname if omitted) and records this node as the founding member of a cluster of one. Result `{clusterId, clusterFriendlyName}`. Because the new cluster identity **originates here**, it also emits **`cluster:identity-changed`** so the Broker persists it to `nvpair-node-settings` — the same report-and-persist path as adopt-on-join (§7.0). `cluster:create` is the **explicit** founding path; a node may also found **implicitly** by simply inviting a peer while unclustered (`cluster:invite-node` auto-founds — §7.0/§7.2), so an explicit `create` is now only needed to name the cluster (`clusterFriendlyName`) before the first invite, not as a precondition for inviting.
+- **`nodes:get-initial` (Broker → CM)**: pure read of the local membership set. Params: none. Result: `{nodes: ClusterNode[]}` — wrapped in an object (not a bare array) so summary fields can be added later without breaking clients. An empty list is a normal early state, not an error.
+- **`cluster:invite-node` (Broker → CM)**: params `{address: string, port?: number, nodeId?: string}`. **If this node is unclustered, it first auto-founds a cluster of one** — the same mint-and-record founding as `cluster:create`, run in-process (so there is no check-then-create race across the wire), emitting `cluster:identity-changed` for the Broker to persist — so a caller can invite without a separate create step. It then records a `pending-outbound` invite and runs the EAP-NOOB Initial Exchange with the target (a few in-band round trips). Initial invite publication and session-generation capture are one commit under the teardown boundary: teardown either sees and clears the invite or wins before it is published; an in-flight Initial Exchange cannot reinsert it afterward. On success it derives the six-digit PIN and returns `{inviteId, state: "pending", pin}` — the inviter's UI displays the PIN. If the Initial Exchange can't complete (peer unreachable/incompatible), returns `state: "failed"` and no PIN. If the target **refuses because it is already clustered**, returns `{inviteId, state: "rejected", reason: "already-clustered"}` and no PIN (the target must leave / be removed before it can pair again). After a `pending` return, the inviter holds its EAP-NOOB Server alive (keyed by `inviteId`) and **serves** the joiner-driven Completion Exchange on its pairing endpoint once the remote user enters the PIN (§7.2); the invite flips to `paired` at that point, observable via `cluster:invite-status` or the `nodes:changed` push.
+- **`cluster:invite-status` (Broker → CM)**: params `{inviteId: string}`. Returns the current `Invite` (`pin` omitted/null unless this is the inviter's still-pending session). Unknown `inviteId` → JSON-RPC error `-32001` (§7.6).
+- **`cluster:respond-to-invite` (Broker → CM)**: params `{inviteId: string, accept: boolean, pin?: string}`. Valid only for a `pending-inbound` invite (else `-32001`/`-32002`, §7.6). On `accept` with a well-formed `pin`, feeds the PIN to EAP-NOOB and runs the Completion Exchange; on success pins the inviter's cert, records it as a `member`, and adopts the cluster identity (see §4 open question on who writes `cluster_id`). A wrong/expired PIN returns `state: "failed"` (with `reason: "incorrect-pin"` on a wrong PIN); a decline returns `state: "declined"`; a malformed (non-six-digit) `pin` is rejected with `-32602` before any attempt (§7.6). Returns the updated `Invite`.
+- **`cluster:cancel-invite` (Broker → CM)**: params `{inviteId: string}`. The inviter's counterpart to a joiner decline: aborts a still-`pending` **outbound** invite that this node originated (from `cluster:invite-node`). Valid only for a `pending` outbound invite — an inbound invite (one we received) or a non-`pending` (already terminal) one returns `-32002`, and an unknown/evicted `inviteId` returns `-32001` (§7.6). It **evicts the inviter's EAP-NOOB Server session** (keyed by `inviteId`), which invalidates the PIN: any later joiner-driven Completion POST now hits the `409` unknown-invite branch (§7.2), so a remote user entering the correct PIN can no longer complete the join. It flips the invite to `canceled` and, best-effort, POSTs a `phase:"cancel"` envelope to the joiner's pairing endpoint so the joiner drops its pending-inbound invite and emits `cluster:invite-canceled` (below). The joiner notification is best-effort (bounded timeout); if the joiner is unreachable the inviter-side teardown still prevents the join. Returns the updated `Invite` (`pin` omitted).
+- **`cluster:respond-to-invite` (Broker → CM)**: params `{inviteId: string, accept: boolean, pin?: string}`. Valid only for a `pending-inbound` invite (else `-32001`/`-32002`, §7.6). On `accept` with a well-formed `pin`, feeds the PIN to EAP-NOOB and runs the Completion Exchange; on success pins the inviter's cert, records it as a `member`, and adopts the cluster identity (see §4 open question on who writes `cluster_id`). A wrong PIN returns `state: "failed"` (with `reason: "incorrect-pin"`), clears the pending-inbound member row, and best-effort notifies the inviter (`phase:"fail"`) so the inviter's invite also reaches `failed` and emits `cluster:invite-failed`; a decline returns `state: "declined"` and best-effort notifies the inviter (`phase:"decline"`) so the inviter's invite also reaches `declined` and emits `cluster:invite-declined`; a malformed (non-six-digit) `pin` is rejected with `-32602` before any attempt (§7.6). Returns the updated `Invite`.
+- **`cluster:invite-declined` (CM → Broker)**: emitted on the **inviter** when a joiner decline arrives over the pairing channel. Params: the `Invite` (with `state: "declined"`, no `pin`). If the cluster was invite-created and no confirmed peer / sibling pending outbound invite remains, the CM also leaves (empty `cluster:identity-changed` + empty `nodes:changed`). An intentional solo cluster is left intact.
+- **`cluster:invite-failed` (CM → Broker)**: emitted on the **inviter** when a joiner-signaled completion failure (`phase:"fail"`) arrives over the pairing channel — today only a wrong PIN. Params: the `Invite` (with `state: "failed"`, no `pin`, and `reason: "incorrect-pin"` on a wrong PIN; empty reason for other causes). Tears down the EAP session (invalidating the PIN) and runs the same provenance-safe cleanup as decline (a throwaway invite-created solo cluster is left; an intentional solo cluster is left intact).
+- **`cluster:invite-expired` (CM → Broker)**: emitted when a pending invite exceeds the invite TTL without accept/decline. On the **inviter** (outbound) it is the lost-decline / offline-joiner fallback and runs the same provenance-safe cleanup as decline; on the **receiver** (inbound) it fires when the local user never entered the PIN, dropping the tentative pending-inbound member + session so the UI can dismiss the prompt, and best-effort signaling the inviter over `phase:"expire"`. Params: the `Invite` with `state: "expired"`.
+- **`nodes:remove` (Broker → CM)**: params `{nodeId: string}` (the logical id the UI holds; `nodeUuid` is also accepted). Resolves the member, durably writes an admission-targeted removal proof, then drops it locally, deletes its pin, and notifies the peer (keyed by `nodeUuid` on the wire). If authoritative proof cannot be persisted, the request fails and membership is left intact. Returns `{nodeId, removed: boolean}` (`removed: false` if the node wasn't a member — a no-op). Removing **self** is rejected with `-32602` (`data:{field:"nodeUuid"}`) — self-departure is `cluster:leave`, since a self-targeted peer removal would evict this node everywhere while leaving it locally still clustered.
+- **`cluster:leave` (Broker → CM)**: params: none. The self-initiated counterpart to `nodes:remove`: this node unjoins its own cluster. It announces departure as a signed, admission-targeted self-removal proof pushed over roster reconcile (§7.7) to every reachable member — so they de-pin it and gossip the removal onward to members that are offline — then tears down all local cluster state: drops every pinned peer, clears the member/proof set and current admission, and resets the cluster identity to `""`. The node-global admission counter is retained, so a later join (including to the same cluster) has a strictly newer incarnation. Emits `cluster:identity-changed` (empty `clusterId`, so the Broker persists "unclustered" to `nvpair-node-settings`) and `nodes:changed` (empty set). Returns `{left: boolean}` (`left: false` when already unclustered — idempotent no-op). Departure is best-effort like removal: it takes effect locally even if some peers are unreachable, and the proof reconciles them when they return.
+- **`cluster:invite-received` (CM → Broker)**: emitted once the inbound Initial Exchange completes. Params: the `Invite` (with `state: "pending"`, no `pin`). The Broker prompts the user to enter the PIN shown on the inviting node, then drives `cluster:respond-to-invite`.
+- **`cluster:invite-canceled` (CM → Broker)**: emitted on the **joiner** when the inviter cancels a still-pending inbound invite (a `phase:"cancel"` arrives on the pairing channel, §7.2), or when a newer invite from the same authenticated sender supersedes it. Params: the `Invite` (now `state: "canceled"`, no `pin`). The joiner drops the old pending-inbound invite/session; on supersession it retains the sender's single pending member row for the replacement invite. The Broker uses this event to dismiss the old PIN prompt before handling the replacement `cluster:invite-received`. Idempotent — a duplicate or late cancel for an already-resolved invite is a no-op and emits nothing.
+- **`cluster:identity-changed` (CM → Broker)**: emitted when the local `clusterId` originates **here** rather than from a `cluster:set-identity` call — i.e. in the two cases where this service creates or adopts a cluster identity: (a) `cluster:create` founding a new cluster, and (b) the joiner adopting the inviter's cluster on a successful pair (§4 working model). Params `{clusterId, clusterFriendlyName}`; the Broker persists it to `nvpair-node-settings`. Not emitted for changes the Broker itself drove via `cluster:set-identity` (those already came from node-settings).
+- **`nodes:changed` (CM → Broker, proposed)**: full `{nodes: ClusterNode[]}` snapshot pushed whenever membership changes (accept, decline, removal, peer-initiated removal). Lets the Broker stay live without re-polling `nodes:get-initial`. Marked proposed in §4.
+
+Example `cluster:invite-node` request and result (`stdin` → `stdout`):
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 7,
+ "method": "cluster:invite-node",
+ "params": { "address": "192.168.1.22", "port": 14321, "nodeId": "NODE-B" }
+}
+```
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 7,
+ "result": { "inviteId": "inv-9f3a1c", "state": "pending", "pin": "402199" }
+}
+```
+The inviter's UI shows `402199`; the user reads it to whoever is at node B.
+
+Example `cluster:invite-received` notification (`stdout`) — no PIN and no cert; the UI uses this to prompt "enter the PIN shown on Lab desk A":
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "cluster:invite-received",
+ "params": {
+ "inviteId": "inv-9f3a1c",
+ "fromNodeId": "NODE-A",
+ "fromNodeUuid": "b3d4f8a0-1c2e-4f6a-9b8c-0d1e2f3a4b5c",
+ "fromNodeName": "Lab desk A",
+ "toNodeId": "NODE-B",
+ "clusterId": "cluster-xyz",
+ "clusterFriendlyName": "Lab 3 desks",
+ "pin": null,
+ "state": "pending",
+ "createdAt": 1716998400000,
+ "respondedAt": null
+ }
+}
+```
+
+Example `cluster:respond-to-invite` request (joiner submits the PIN) and result:
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 8,
+ "method": "cluster:respond-to-invite",
+ "params": { "inviteId": "inv-9f3a1c", "accept": true, "pin": "402199" }
+}
+```
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 8,
+ "result": {
+ "inviteId": "inv-9f3a1c",
+ "fromNodeId": "NODE-A",
+ "fromNodeUuid": "b3d4f8a0-1c2e-4f6a-9b8c-0d1e2f3a4b5c",
+ "fromNodeName": "Lab desk A",
+ "toNodeId": "NODE-B",
+ "clusterId": "cluster-xyz",
+ "clusterFriendlyName": "Lab 3 desks",
+ "pin": null,
+ "state": "paired",
+ "createdAt": 1716998400000,
+ "respondedAt": 1716998460000
+ }
+}
+```
+
+### 7.1 Local Interface (UI Broker ↔ Cluster Manager)
+- Transport: `stdin` / `stdout` (or a named pipe); JSON-RPC 2.0 **request/response** plus CM → Broker notifications.
+- **Inbound** (`stdin`): the requests in §7.0 (`cluster:get-node-id`, `cluster:set-identity`, `cluster:create`, `nodes:get-initial`, `cluster:invite-node`, `cluster:invite-status`, `cluster:respond-to-invite`, `cluster:cancel-invite`, `nodes:remove`, `log/set-level`).
+- **Outbound** (`stdout`): JSON-RPC results for each request; `cluster:invite-received` on each inbound invite; `cluster:invite-canceled` when the inviter cancels a pending inbound invite; `cluster:invite-declined` / `cluster:invite-failed` / `cluster:invite-expired` on the inviter when an outbound invite is declined / fails (e.g. wrong PIN) / times out, and `cluster:invite-expired` on the receiver when an unanswered inbound invite times out; `cluster:identity-changed` when a pairing changes the local `clusterId`; `nodes:changed` on each membership change (proposed).
+- Local *cluster* identity (`cluster_id`, `cluster_friendly_name`) is supplied by the parent via the `cluster:set-identity` request, since `nvpair-node-settings` owns it (see §8); `nodeId`/`name` default to the OS hostname. The local *cryptographic* identity (node UUID + keypair + cert, §7.4) is **self-owned** — generated and persisted on first run, read back via `cluster:get-node-id`, never supplied by the parent.
+
+### 7.2 Inter-node Interface (Cluster Manager ↔ Cluster Manager)
+- Port `14321` (TCP), fixed on every node — all peers, whether resolved from discovery or Broker-supplied, are reached here. (`14318` node-info, `14319` errors, `14320` workload-manager are already taken.)
+- Two transport modes on this port, distinguished by endpoint:
+ - **Pairing channel** (`POST /v1/cluster/pairing`) — **plain HTTP**, used only during a pairing (before any pin exists). It carries opaque EAP-NOOB message blobs; authentication comes from the EAP-NOOB exchange + the user-entered PIN, not from TLS. (Even a confidential transport here wouldn't rescue the low-entropy PIN against an active MITM — see §4 debt.)
+ - **Trusted endpoints** (everything else, e.g. `POST /v1/cluster/members/remove`) — **HTTPS over mTLS**: the server presents this node's leaf cert (§7.4) and is configured `RequireAnyClientCert`; a `VerifyPeerCertificate` hook reads the **claimed UUID from the presented client cert's subject `CN` (and URI SAN, §7.4)**, looks up that UUID in the trusted-node store, and requires a **byte-for-byte DER match** against the pinned cert (TLS min 1.2). An absent, unpinned, or mismatched cert → `403 Forbidden` (logged with the presented subject/fingerprint). These endpoints are only reachable by already-paired peers.
+
+**Pairing channel — `POST /v1/cluster/pairing`** (JSON, `/v1` prefix). Each request/response body wraps exactly one EAP-NOOB message:
+```json
+{ "inviteId": "inv-9f3a1c", "phase": "initial|completion", "msg": "<base64 EAP-NOOB blob>" }
+```
+- `msg` is the opaque `Outcome.Send` blob from the `eap-noob` library, relayed verbatim; the receiver feeds it to its `Server`/`Peer` and returns that side's next `Outcome.Send` in the HTTP response. `msg` may be the **empty string** — that is the Completion *kickoff* (see "two HTTP drivers" below), the only case where a request carries no EAP blob.
+- **No out-of-band material is ever transmitted on this channel.** There is no `noob`/`peerId`/`hoob` field: the only OOB secret is the six-digit PIN, and it is human-carried. Each side already holds everything else — the `PeerId` is assigned during the Initial Exchange (the joiner records it from the negotiation message), and `Hoob` is recomputed locally from the transcript, so neither needs to be relayed. The joiner builds its EAP-NOOB OOB input entirely from local state + the typed PIN (§7.4).
+- **`PairingInfo` — the object each side puts in EAP-NOOB `ServerInfo` (inviter) / `PeerInfo` (joiner)** (identical schema both directions). It is folded into the `Hoob` fingerprint and the Completion `MACs`/`MACp` (`eap-noob/mac.go::noobArray`), so the cert and identity are cryptographically bound to the pairing (§7.4). Exact, fixed schema:
+```json
+{
+ "v": 2,
+ "nodeUuid": "b3d4f8a0-1c2e-4f6a-9b8c-0d1e2f3a4b5c",
+ "nodeId": "NODE-A",
+ "name": "Lab desk A",
+ "clusterId": "cluster-xyz",
+ "admissionEpoch": 4,
+ "clusterFriendlyName": "Lab 3 desks",
+ "addr": "192.168.1.10:14321",
+ "cert": "-----BEGIN CERTIFICATE-----\nMIIB...AB\n-----END CERTIFICATE-----\n"
+}
+```
+ - `cert` is the full self-signed leaf PEM (§7.4). `v` is the PairingInfo schema version (`2`); `admissionEpoch` is the durable incarnation being authenticated and later stored with the pin. `addr` is **required on the inviter's `ServerInfo`** (the `host:port` the joiner POSTs back to for the Completion Exchange) and optional on the joiner's `PeerInfo`. The joiner sends `clusterId: ""`/`clusterFriendlyName: ""` while pairing but carries the admission epoch it reserved for this attempt. A `PairingInfo` whose `cert` subject CN ≠ `nodeUuid` is rejected (`400`).
+- **Two fixed roles, two HTTP drivers.** EAP-NOOB is a strictly server-initiated request/response protocol: the **Server always sends the request, the Peer always responds** (`eap-noob/server.go`, `peer.go`). The roles are fixed for the whole pairing — the **inviter is always the EAP-NOOB Server**, the **joiner is always the EAP-NOOB Peer**. But *which side makes the HTTP requests* deliberately differs by phase, so each phase is driven by the side that just had a reason to act and neither side polls. In **both** phases the receiver of an HTTP request feeds `msg` to its `Server`/`Peer` via `Receive(...)`, returns the resulting `Outcome.Send` as the HTTP response body, and the HTTP client loops, POSTing each new local `Outcome.Send`, **until an `Outcome` reports `Done` (terminal: `Success` ⇒ paired, or an error/`EAP-Failure` ⇒ failed).** Each HTTP request/response carries exactly one EAP message.
+ - **Initial Exchange — the inviter (HTTP client) drives, and this lines up naturally with EAP** because the HTTP client is also the side that speaks first (the Server). Triggered by `cluster:invite-node`: the inviter calls `Server.Start()` (Type 1 Discovery) and **POSTs** it to the joiner's `POST /v1/cluster/pairing` with `phase:"initial"`; the joiner's handler validates that first message as Type 1 before reserving an admission epoch, runs `Peer.Receive(msg)`, and returns the peer response. The loop runs Discovery → Negotiation → KeyExchange until both `Outcome.State` reach `Waiting` (the library ends the Initial Exchange with `EAP-Failure` + `Done`, which is the *normal* Initial outcome, **not** an error — both sides are now awaiting OOB). The inviter then calls `Server.OOBOutputWith(noob)` with the PIN-derived `Noob` (§7.4) and **displays the six-digit PIN**; the joiner, on seeing its Peer reach `Waiting`, emits `cluster:invite-received`. Failed first messages delete their session, unpublished sessions expire on the normal invite TTL, and at most 64 joiner sessions may exist at once, bounding unauthenticated memory and durable-counter writes.
+ - **Already-clustered reject.** Before creating a joiner session for the first `phase:"initial"` POST, the joiner checks whether it is already clustered (non-empty `clusterId`). If so it **refuses** rather than run the exchange: it replies `HTTP 409` with the pairing envelope `{rejected: true, reason: "already-clustered"}` (no EAP-NOOB message, no session, no PIN, no `cluster:invite-received`). The inviter recognizes this envelope (distinct from a plain `409` phase/session error) and returns `state: "rejected"` from `cluster:invite-node`. This is the authoritative guard against re-pairing a node that is already in a cluster; a node must **leave** (or be removed) first.
+ - **Completion Exchange — the joiner (HTTP client) drives, which inverts the EAP request direction, so it needs an explicit kickoff.** Triggered by `cluster:respond-to-invite`: the joiner first feeds the PIN to its Peer (§7.4, moving it to `OOBReceived`), then runs this loop against the inviter's `POST /v1/cluster/pairing` with `phase:"completion"`:
+ 1. **Kickoff:** the joiner POSTs with **empty `msg`**. The inviter's handler looks up its still-alive `Server` for this `inviteId` and calls `Server.Start()` (a fresh Type 1 Discovery — the EAP reconnect), returning that blob.
+ 2. The joiner runs `Peer.Receive(blob)` → its Discovery response reports `PeerState = OOBReceived`, which it POSTs. The inviter's `Server.Receive` sees `peerState == OOBReceived` and advances to the Completion sub-flow (NoobID request → the joiner returns the `NoobId` it derived from the PIN → `MACs` → the joiner returns `MACp`).
+ 3. The inviter verifies `MACp` and EAP-NOOB computes `EAP-Success` (`Outcome.Done && Success`), but that frame is not returned yet. The inviter first commits the joiner's pin + admission + membership under the cluster/session teardown boundary. Only a successful local commit releases `EAP-Success`; a stale/abandoned session or changed cluster returns `409` and discards the success frame, so the joiner never reaches `Registered` when the inviter committed nothing. The inviter retains the successful session and cached EAP-Success until the joiner acknowledges its own durable commit, so a lost final HTTP response is retried idempotently. The joiner's `Peer.Receive` of an actually returned `EAP-Success` reaches `Registered`; it persists its provisional self/member/pin set, activates admission as the final durable write, and then posts `phase:"ack"` over the newly established mTLS trust. A post-success local failure posts the same authenticated `phase:"fail"` instead, causing the inviter to roll its provisional peer back; plain unauthenticated signals cannot alter an already-committed pairing.
+
+ This is why `cluster:respond-to-invite` can complete **synchronously** with `state:"paired"` (§7.0): the joiner is the HTTP client, so it observes `Registered` in-line without waiting on any inviter-initiated request.
+ - **Both sides keep their EAP-NOOB instance alive, keyed by `inviteId`, for the whole pairing** — across the Initial round-trips, the (possibly minutes-long) human PIN step, and the Completion round-trips. Each side needs a per-`inviteId` session map because the messages arrive as *separate* HTTP requests; the entry holds the `Server`/`Peer` with its ECDHE state, transcript (`s.in`/`p.in`), and (after the OOB step) the injected `Noob`. The only thing that flips per phase is **who is the HTTP client vs. server**: during Initial the joiner is the HTTP *server*, feeding its session-mapped `Peer` the three inviter-driven POSTs (Discovery → Negotiation → KeyExchange); during Completion the joiner is the HTTP *client*, driving that **same** session entry from the synchronous `respond-to-invite` handler. Entries are evicted on protocol failure, terminal state, or TTL expiry (§4); a process restart mid-pairing drops the session and the invite fails (the user re-invites).
+ - **Decline signal — the joiner (HTTP client) notifies the inviter.** On `cluster:respond-to-invite` with `accept:false`, after local teardown the joiner POSTs `phase:"decline"` (empty `msg`) to the inviter's pairing endpoint, with a few short retries. The inviter flips its outbound invite to `declined`, deletes the Server session (so a late Completion hits 409), and emits `cluster:invite-declined`. Cleanup of the cluster itself uses provenance-safe cleanup: only a solo cluster **auto-founded by `cluster:invite-node` while unclustered** is dissolved, and only when **no sibling pending outbound invite** remains — an intentional solo cluster founded by explicit `cluster:create` is preserved, and a second still-pending invite keeps the cluster id stable for that sibling Completion. If the decline POST is lost, the inviter's invite TTL (default 5 minutes) expires the pending invite and runs the same provenance-safe cleanup. Invite-created provenance is persisted by cluster id; if the inviter restarts, its in-memory pairing sessions are gone and restoring that marked solo identity immediately cleans up the orphan.
+ - **Fail signal — the joiner (HTTP client) notifies the inviter of a wrong PIN.** A wrong PIN is caught by the joiner (EAP Peer) first: it verifies the inviter's `MACs` in the Completion sub-flow and, on the mismatch, ends its side with an EAP-NOOB HMAC-verification failure **before** sending its own `MACp` — so the inviter's Completion handler is never re-entered and would otherwise be left on a stale `pending` invite. To mirror decline, after local teardown (flip to `failed` with `reason:"incorrect-pin"`, drop the pending-inbound member, evict the session) the joiner POSTs `phase:"fail"` (empty `msg`, carrying `reason`) to the inviter's pairing endpoint with a few short retries. The inviter flips its outbound invite to `failed` (stamping the reason), deletes the Server session (so a late Completion hits 409), emits `cluster:invite-failed`, and runs the same provenance-safe solo-cluster cleanup as decline. If the fail POST is lost, the inviter's invite TTL is the backstop.
+ - **Expire signal — the receiver (HTTP client) notifies the inviter of an unanswered invite.** When the receiver's invite TTL (default 5 minutes) elapses with no local accept/decline, the receiver's reaper tears down its own inbound state (flip to `expired`, drop the pending-inbound member, evict the joiner session, emit `cluster:invite-expired` so the UI clears the PIN prompt) and then POSTs `phase:"expire"` (empty `msg`, correlated by `inviteId`) to the inviter's pairing endpoint with a few short retries. The inviter flips its outbound invite to `expired`, deletes the Server session (so a late Completion hits 409), emits `cluster:invite-expired`, and runs the same provenance-safe solo-cluster cleanup as decline. It reuses the shared decline/fail teardown path, so it is idempotent and answered `200` unconditionally. If the expire POST is lost — or the receiver is offline and never sends one — the inviter's own outbound invite TTL is the backstop, so both sides always return to a usable state.
+ - On `Registered`, each side reads the peer's cert and admission epoch from the now-authenticated transcript (`PairingInfo` v2) and pins that exact incarnation. The inviter reaches `Registered` while serving the joiner's final Completion POST: it durably commits the joiner before answering with `EAP-Success`, flips its invite to `paired`, and waits for the joiner's commit acknowledgment before evicting the retry cache, surfacing the member, and fanning the roster out. Duplicate final Completion POSTs return the cached success frame. An unacknowledged cache entry expires without undoing two already-durable memberships.
+ - **Cancel — the inviter (HTTP client) signals the joiner, out of band from EAP.** On `cluster:cancel-invite` the inviter first evicts its own `Server` session (which alone prevents any later Completion — a Completion POST for the now-unknown `inviteId` gets `409`), then POSTs `phase:"cancel"` (no `msg`, correlated by `inviteId`) to the joiner's pairing endpoint. The joiner drops its pending-inbound session/invite/member and emits `cluster:invite-canceled`. This carries no EAP-NOOB message — it is a best-effort teardown signal answered `200` unconditionally (idempotent; a `cancel` for an unknown or already-resolved `inviteId` is a silent no-op), so a lost or late cancel never wedges either side.
+ - **Cancel and the joiner-driven Completion serialize on the per-`inviteId` session.** Both `cluster:cancel-invite` and the inviter's Completion handler take the session mutex and re-read the invite state **inside** the critical section, so exactly one wins and there is no torn outcome. If a Completion has already committed (pinned + recorded the member + flipped to `paired`), the cancel observes the terminal state under the lock and returns `-32002` rather than tearing a finished pairing down; if the cancel wins, the Completion handler sees the invite is no longer `pending` and returns `409` (never an `EAP-Success` blob), so the joiner's Completion fails cleanly instead of a one-sided join. The pending-state check is therefore authoritative only when held with the session lock — an unlocked check would race the pin/commit.
+- Reaching the inviter for Completion: the joiner POSTs to the inviter's listening `host:port` taken from `addr` in the inviter's `ServerInfo` (§7.2 `PairingInfo`), falling back to the inviter's source address seen during the Initial Exchange. (The inviter was the HTTP *client* during Initial, so its TCP source port is not its listening port — hence `addr` is required.) The Initial/Completion traffic is still the un-pinned pairing channel, correlated by `inviteId`; only the post-commit `ack`/`fail` reuses this path over the newly established mTLS pins.
+- Responses: `200 OK` (blob relayed, including the empty-`msg` kickoff); `400` (malformed / EAP-NOOB protocol error, e.g. MAC mismatch or unrecognized `NoobId`); `409` (unknown or expired `inviteId`, a `phase` that doesn't match the session's current state, or final EAP success whose local membership commit was refused after teardown).
+
+**`POST /v1/cluster/members/remove`** (mTLS) — notify a peer it has been **removed** from the cluster (`nodes:remove`'s outbound half). Body: `{nodeUuid, proof}` where `nodeUuid` is the removing node (and must match the client-cert principal) and `proof` is the §7.7 admission-targeted removal proof. The recipient snapshots the exact client DER, cluster admission, and composition generation after initial pin authentication, reads the body, then revalidates all three and the proof under the teardown lock immediately before clearing state. Response `200 OK` (recipient tears down *all* local cluster state — pins, membership, proofs, current admission, and `clusterId` — becoming unclustered, same local outcome as `cluster:leave`); `409` (the request crossed a teardown/rejoin or other composition change); `403` (not a trusted peer, invalid proof, or proof for another admission); `400` (malformed). Self-initiated departure uses `cluster:leave`, not this endpoint.
+
+**`POST /v1/cluster/roster`** (mTLS) — exchange and reconcile cluster rosters for trust fan-out (§7.7). Body: the sender's `Roster` (`{clusterId, members[], removalProofs[], tombstones[]}`; `tombstones` is a legacy compatibility mirror and is never admission-aware self-removal authority). The recipient merges it (transitively pinning every exact admission endorsed by a node it already trusts, durably persisting valid proofs before applying removals) and replies `200 OK` with **its own** `Roster`, which the sender merges in turn — so two peers fully converge in one round trip. If the caller is no longer pinned, `403` carries `{removalProofs:[...]}` when the recipient holds proof targeting that caller; this lets an offline victim verify its removal even though normal roster access is denied. `403` without such proof is only a rejection, not evidence that the caller was removed. `400` means malformed; rosters whose `clusterId` differs from the recipient's are ignored.
+
+- Idempotency: pairing messages are correlated/deduplicated by `inviteId`; removals by `nodeUuid`. Re-pinning a cert already pinned for a UUID is a no-op; a *different* cert presented for an already-pinned UUID is rejected (see §12, key-rotation / impersonation).
+
+Example pairing message (`POST /v1/cluster/pairing`; EAP-NOOB blob truncated):
+```json
+{
+ "inviteId": "inv-9f3a1c",
+ "phase": "initial",
+ "msg": "eyJUeXBlIjoxLCJWZXJzIjpbMV0sLi4ufQ"
+}
+```
+Response (the receiver's next blob): `200 OK` with the same envelope shape and the receiver's `Outcome.Send` in `msg`. The Completion kickoff is the same shape with `"phase":"completion"` and `"msg":""`.
+
+Example removal (`POST /v1/cluster/members/remove`, mTLS):
+```json
+{
+ "nodeUuid": "7a1c9e22-44b0-4d3f-8e10-aa55cc77dd99",
+ "proof": {
+ "tombstone": {
+ "nodeUuid": "victim-uuid",
+ "clusterId": "cluster-uuid",
+ "admissionEpoch": 4,
+ "by": "7a1c9e22-44b0-4d3f-8e10-aa55cc77dd99",
+ "byAdmissionEpoch": 2,
+ "removedAt": 1784678400000,
+ "sigV2": "..."
+ },
+ "signerCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
+ "signerFingerprint": "sha256:..."
+ }
+}
+```
+Response: `200 OK`.
+
+### 7.3 Versioning
+- URL path prefix (`/v1`) on the inter-node interface.
+- JSON-RPC `method` names and HTTP endpoints are namespaced and additive. Wire objects gain optional fields, while security validation may fail closed on evidence that predates the admission-bound schema (for example a timestamp-only removal cannot authorize self-eviction).
+- `ClusterNode` / `Invite` schema changes are backward compatible (new fields optional, unknown fields ignored); breaking changes require a new version (`/v2`).
+- The trust model can evolve behind the same wire shape: the handshake already carries certs, so swapping pinned-leaf verification for a cluster-CA chain check (§4) needs no `/v2`.
+
+### 7.4 Identity, certificates, and the trusted-node store
+
+This subsection answers the two design questions head-on: **how nodes map to certs**, and **where cert material lives on disk**.
+
+**Cryptographic identity = a stable node UUID, not the hostname.** The process owns its own identity: at startup it reads `<config-dir>/cluster/identity.json`, and **if the file is absent (first launch) it generates a fresh random UUID (v4), writes `identity.json` atomically (`0600`), and reuses it forever after** — no parent or external service supplies it. That UUID — not the hostname — is the node's security principal: it is the certificate's subject (`CN=<uuid>`), is also embedded as a URI SAN (`URI:urn:nvpair:node:<uuid>`), and is the key under which the trusted-node store pins the node's cert. Hostname is carried only as a display attribute (a DNS SAN and the `name` field) and is never trusted. The UUID (and the derived `nodeId`/`name`/cert fingerprint) is read back by any client via the **`cluster:get-node-id`** request (§7.0); `nodeId`/`name` default to the OS hostname (`os.Hostname()`), so the only identity input the process needs from a parent is the *cluster* identity (`cluster:set-identity`), never the node identity.
+
+Why UUID over hostname (the alternatives in the original question):
+- **Hostname is mutable** — a user renaming their machine would silently change identity and break every existing pin. A UUID is stable for the life of the install.
+- **Hostname is not unique** — two machines on the LAN can share `DESKTOP-1`; UUID collisions are effectively impossible.
+- **Hostname is trivially spoofable** and is already the (non-security) `nodeId` everywhere else (errors, workloads, discovery). Reusing it as the trust principal would conflate a display label with a credential.
+
+Note the deliberate split: `ClusterNode.id` (hostname) stays the *logical/display* id for consistency with the rest of the system; `ClusterNode.nodeUuid` is the *cryptographic* id. Unifying the whole system onto the UUID is out of scope (open question, §4).
+
+**Each node self-signs its own leaf** (no CA, §2/§4). The keypair (Ed25519 or P-256 — implementation choice) and a long-lived self-signed cert (proposed 1–2 years, §4) are generated on first run and reused across restarts.
+
+**Trust is established by an EAP-NOOB pairing authenticated by a six-digit PIN.** The join handshake runs the in-tree `eap-noob` library (RFC 9140) over the pairing channel (§7.2):
+
+1. **Bind the certs into the exchange.** The inviter (EAP-NOOB **Server**) puts its identity + **full cert PEM** in the EAP-NOOB `ServerInfo`; the joiner (**Peer**) puts the same in `PeerInfo`. Both objects are folded into the `Hoob` fingerprint and the Completion `MACs`/`MACp` (`eap-noob/mac.go::noobArray`), so a successful pairing proves both sides agree on each other's exact cert — no separate encrypted channel is needed to ship them (certs are public; only integrity matters).
+2. **Initial Exchange** (in-band, machine-to-machine): ephemeral ECDH; both reach `Waiting`.
+3. **OOB step = the PIN.** OOB direction is **server-to-peer** (`ServerConfig.Dirs = 2`, `PeerConfig.PreferDir = 2`): the inviter (Server) produces the OOB value and displays it as the PIN; the joiner (Peer) consumes it. The PIN is the **only** thing carried out of band, by the human. Nothing is relayed in-band for the OOB step — the joiner already holds the `PeerId` (assigned during the Initial Exchange) and recomputes `Hoob` locally from the transcript, so it builds its EAP-NOOB OOB input entirely from local state + the typed PIN (see "Library extension" below).
+4. **Completion Exchange** (in-band): MAC verification; both reach `Registered`.
+5. **Pin.** Each side reads the peer's cert out of the now-authenticated `PairingInfo` (§7.2) and pins it (full-cert match, keyed by the peer's UUID) into the trusted-node store. Optionally `Export(...)` a confirmation value to check both derived the same `Kz` before committing the pin.
+
+The user entering the PIN is the out-of-band authorization — there is no silent auto-pin. Thereafter, every inter-node call must present a cert matching the pin for its claimed UUID.
+
+**PIN ↔ `Noob` encoding (strongly defined — both nodes MUST agree byte-for-byte).**
+- The **PIN** is exactly **six ASCII decimal digits** (`"000000".."999999"`, zero-padded, leading zeros significant). The inviter generates it with a uniform CSPRNG (`crypto/rand`) over `[0, 1000000)`.
+- The EAP-NOOB **`Noob` is the fixed 16-byte big-endian encoding of that integer**: a 16-byte buffer, bytes `0..7` zero, bytes `8..15` = `binary.BigEndian.PutUint64(noob[8:], uint64(pinValue))`. (E.g. PIN `"402199"` → `pinValue = 402199` → `noob = 00 00 00 00 00 00 00 00 00 00 00 00 00 06 23 57`.) The base64url JSON form of these 16 bytes is what feeds `Hoob`/`NoobId`/MACs, so identical `pinValue` on both sides ⇒ identical transcript.
+- The **joiner** parses the typed PIN: require exactly six digits, `pinValue = strconv.Atoi`, re-encode the same 16 bytes, and feed that `Noob` to its Peer (see below). A non-six-digit / non-numeric entry is rejected locally before EAP-NOOB (no wasted attempt).
+
+**Library extension (the §4 delta, concretely).** The in-tree `eap-noob` library today random-generates a 16-byte `Noob` (`helpers.go::oobOutput`) and its OOB API exchanges the full `OOBMessage{PeerId, Noob, Hoob}` (`Server.OOBOutput`/`Peer.OOBInput`). Our flow human-carries only the `Noob`, so each side needs one small **additive** entry point that injects a caller-supplied `Noob` and derives the rest internally — no `OOBMessage` is built, transmitted, or parsed by the cluster-manager:
+- **Inviter (Server):** `Server.OOBOutputWith(noob []byte) error` — set `s.noob` to the PIN-derived 16 bytes (instead of `rand.Read`), compute `s.noobID`, and stay in `Waiting`. (It needs only the side effect of registering the `Noob`; nothing is sent.) The CM calls this when it displays the PIN.
+- **Joiner (Peer):** `Peer.OOBInputNoob(noob []byte) error` — set `p.noob`/`p.noobID` from the PIN-derived 16 bytes and move to `OOBReceived`, using the Peer's own already-known `PeerId` and its locally-recomputed `Hoob` (no externally-supplied `Hoob` to verify — for a human-carried low-entropy `Noob` there is no separate `Hoob` channel; the real transcript agreement is checked by the Completion `MACs`/`MACp`). The CM calls this on `cluster:respond-to-invite` with the typed PIN.
+
+ (The existing `Server.OOBOutput()` / `Peer.OOBInput(OOBMessage)` stay untouched for full-`OOBMessage` callers; the two `*Noob`/`*With` variants are purely additive.)
+- This single delta — caller-injected `Noob` on both roles — is the *only* change the cluster-manager requires in `eap-noob`. It vanishes when the OOB upgrades to a high-entropy pairing code (§4), which would carry a real `OOBMessage` and could use the original API.
+
+Two integration notes:
+- **EAP-NOOB association `Store`:** construct `NewServer`/`NewPeer` with a `nil` (in-memory) store. The library's association store is an *ephemeral* per-pairing artifact and is **not** the trusted-node store — the cluster-manager pins certs into its own `trusted/<uuid>.json` files (below) from the authenticated `PairingInfo`, independent of whatever `eap-noob` keeps internally.
+- **`ServerInfo`/`PeerInfo` size:** RFC 9140 suggests ≤ 500 bytes for these objects; a full leaf PEM exceeds that (more so for P-256 than Ed25519). The in-tree library does **not** enforce the cap and the transport is HTTP (no EAP/RADIUS fragmentation), so embedding the PEM works today — this is a deliberate, documented deviation. If the library is ever hardened to enforce the RFC limit, switch the embedded cert to DER/base64 or raise the cap; prefer **Ed25519 leaves** to stay smallest.
+
+> **⚠️ The six-digit PIN is temporary, low-entropy security debt (full analysis in §4):** it guards against passive eavesdroppers and accidental joins but not an active MITM, and must be replaced by a high-entropy pairing code before cluster trust is relied on. That upgrade changes only the OOB encoding and the library's `Noob` source — the EAP-NOOB transcript and pin format are unchanged.
+
+**Revocation = removal.** `nodes:remove` deletes the peer's pin file; there is no CRL/OCSP. A removed node's subsequent handshakes fail closed (`403`).
+
+**On-disk layout** — under the same per-user config directory the other subprocesses use (the dir that holds `settings.json`, `manual-nodes.json`, `tls-settings.json`), in a dedicated `cluster/` subtree. Directories `0700`, key/pin files `0600`, matching `nvpair-node-settings`:
+
+```
+<config-dir>/cluster/
+ identity.json # { "node_uuid": "...", "created_at": <epoch ms> }
+ node.key # this node's private key (PEM, 0600) — never leaves the host
+ node.crt # this node's self-signed leaf (PEM)
+ trusted/ # the trusted-node store: ONE file per pinned peer (dir 0700)
+ <peerNodeUuid>.json # 0600; the pin for one peer (schema below)
+```
+
+**The trusted-node store is a directory, one file per peer, named `<peerNodeUuid>.json`.** The filename *is* the store key (the peer's `nodeUuid` — a v4 UUID, so always a filesystem-safe name on every platform; this is another payoff of keying trust on the UUID rather than a hostname, which would not be a safe filename). Each file holds one pin:
+```json
+{
+ "nodeUuid": "7a1c9e22-44b0-4d3f-8e10-aa55cc77dd99",
+ "nodeId": "NODE-B",
+ "name": "Lab desk B",
+ "clusterId": "cluster-xyz",
+ "certPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
+ "certFingerprint": "sha256:...",
+ "pinnedAt": 1716998460000
+}
+```
+
+Operations on the store map directly to single-file filesystem actions, so an edit to one peer can never corrupt or lose the others:
+- **Pin** (on pairing success): write `trusted/<uuid>.json.tmp` then atomically rename to `trusted/<uuid>.json` (`0600`).
+- **Remove** (`nodes:remove`): `os.Remove("trusted/<uuid>.json")` — a single atomic delete; a missing file is treated as already-removed (idempotent success).
+- **Load** (startup): read `trusted/*.json` into the in-memory `uuid → pin` map, **skipping** `*.tmp` and any file that doesn't parse. On load, verify the file's inner `nodeUuid` (and the `certPem` subject `CN`) matches the filename `<uuid>`; reject/skip-and-log a mismatch so a renamed or tampered file cannot masquerade as another UUID.
+- **Re-pin guard** (§7.2): re-pinning the *same* cert for an existing `<uuid>.json` is a no-op; a *different* cert for an already-present `<uuid>.json` is rejected, not overwritten (explicit re-pin/re-invite required — §12 key rotation).
+
+Writes are serialized (membership changes are rare and human-driven), so readers tolerate seeing a just-added or just-removed file without a global lock; there is no single-file consistent snapshot, which is acceptable for this low-churn store.
+
+`certFingerprint` is **`"sha256:" + lowercase-hex(SHA-256(cert DER))`** (the DER bytes, not the PEM text) — used as a log/display key only; trust decisions always use the full-DER pin match (§7.2), never the fingerprint alone. The same value is returned by `cluster:get-node-id`.
+
+The exact `<config-dir>` is the per-user data dir shared by every component: `%LocalAppData%\Nvidia Corporation\Personal AI Router` on Windows (local, non-roaming), `$XDG_CONFIG_HOME`/`~/.config/Nvidia Corporation/Personal AI Router` on Linux, `~/Library/Application Support/Nvidia Corporation/Personal AI Router` on macOS, with a portable next-to-exe fallback for dev builds, so cluster identity sits beside the other persisted state rather than inventing a new location.
+
+**Reuse by other services.** This keypair and the `trusted/` store are the shared trust fabric. `nvpair-workload-manager` and `nvpair-errors` peer-sync are intended to load the same `node.crt`/`node.key` for their client/server TLS and verify peers against the same `trusted/<uuid>.json` pins. The handoff mechanism (shared paths passed by the Broker vs. a small local query API) is an open question (§4); what this spec fixes is the **format and location** so consumers have a stable contract.
+
+### 7.5 Discovery (peer address resolution)
+
+The Cluster Manager runs no responder or browser of its own. `nvpair-node-scanner` is the single discovery daemon on the node: the Broker registers this service's `cl` service key and listening port with that daemon, the daemon carries the key on this node's one consolidated `_nvpair-node._tcp` record, and the Cluster Manager learns peers by subscribing upward — `discovery:subscribe` filtered to the `cl` service — and consuming the `discovery:nodes` snapshots the Broker relays back.
+
+- **Registered port**: the inter-node listener, **`14321`** (one above `nvpair-workload-manager`'s `14320`; the pairing channel and the mTLS endpoints share it, distinguished by path and by whether the TLS handshake presents a client cert). It reaches the record as the `cl` service key.
+- **The record layout is the daemon's contract, not this service's.** Service type, instance name, SRV port, and TXT keys are owned by the discovery daemon and the shared `nvpair-shared/noderec` wire format; this service reads the directory entries it is handed and never parses a record itself. The record's SRV port is a fixed, non-authoritative constant, so a consumer takes each service's port from TXT and never from SRV. The instance name is the OS hostname (the logical `nodeId`), surfaced on a directory entry as its `name` — display only, never trusted.
+- **TXT keys this service depends on** (all carried on the one consolidated record, alongside the other services' port keys):
+
+| Key | Value | Why |
+|-----|-------|-----|
+| `uuid` | this node's `nodeUuid` (§7.4) | The **node id in the TXT record** — lets a consumer map a discovered node to its stable cryptographic principal *before* pairing, and resolve an invite target given only a UUID. Reaches a directory entry as `hostUuid`. |
+| `cluster-uuid` | current `clusterId`; **omitted entirely** while the node is unclustered | Lets the UI show which discovered nodes are already in a cluster (and which one) without a round-trip, and selects which pin a cluster-scoped dial should present. Reaches a directory entry as `clusterUuid`. |
+| `cl` | this node's inter-node listener port | The per-service port key for the Cluster Manager. A record without it advertises no Cluster Manager, and the entry is filtered out of a `cl` subscription. |
+| `ip` | this node's canonical dialable LAN address | The address the resolver hands back for a peer. |
+| `v` | the record's schema version (`1`) | Disambiguates the record format across wire changes; diagnostics and tests, not mixed-version negotiation. |
+
+- **Resolution** is best-effort and used only to build a `nodeUuid`/`nodeId` → `host:port` map, so an invite targeting a UUID/hostname can be resolved to an address, so a transitively-learned member whose address was never observed can still be reached (§7.7), and so the joiner can corroborate the inviter's `addr` from `PairingInfo` (§7.2). Each snapshot carries the full filtered set and **replaces** the map wholesale rather than applying per-node deltas, so a node absent from the next snapshot stops resolving. The Cluster Manager does **not** expose its own discovery RPC — node selection for invites is the Broker's job (it already owns the discovery relay and manual nodes); a Broker-supplied address always wins over a resolved one, so a node reachable only by manual entry is still invitable. Where the daemon reports nothing (no multicast, or a parent that is not relay-aware), resolution degrades gracefully to Broker-supplied addresses.
+
+### 7.6 Local-interface errors and the result-vs-error contract
+
+Every local call is JSON-RPC 2.0. The contract draws a hard line between a *negative domain outcome* and a *protocol error* so the Broker can branch deterministically: `result` vs `error` **is** the "did it pair / apply?" vs "could I even process this?" signal. This subsection is normative for the Broker integration.
+
+**Rule 1 — negative outcomes are successful `result`s, never errors.** An operation that ran correctly but ended unfavorably returns a normal `result` carrying a terminal `state`/flag:
+- `cluster:invite-node` to an unreachable or incompatible target → `result {inviteId, state:"failed"}` (no `pin`).
+- `cluster:respond-to-invite` with a well-formed but **wrong/expired** PIN → `result {…, state:"failed"}`; a decline (`accept:false`) → `result {…, state:"declined"}`; a peer that drops mid-Completion → `result {…, state:"failed"}`.
+- `nodes:remove` on a node that isn't a member → `result {nodeId, removed:false}`.
+- A peer-notify that fails after a local removal already applied → still `result {nodeId, removed:true}` (best-effort, §12).
+
+A negative outcome is therefore **success at the JSON-RPC layer**; the Broker reads `state`/`removed`, not the presence of an `error`.
+
+**Rule 2 — protocol errors use the JSON-RPC `error` object** `{code, message, data?}`, where optional `data` carries structured detail (`{field}` for bad params; `{inviteId, state}` for a bad transition). Codes:
+
+| Code | Meaning | Raised when |
+|------|---------|-------------|
+| `-32700` | Parse error | the stdin line is not valid JSON (see Rule 3). |
+| `-32600` | Invalid Request | valid JSON, but not a JSON-RPC 2.0 request object. |
+| `-32601` | Method not found | unknown `method` name. |
+| `-32602` | Invalid params | missing/ill-typed/structurally-invalid params: empty `address`; `port` outside `1..65535`; absent `inviteId`; absent `accept`; `accept:true` with a `pin` that fails `^[0-9]{6}$`; an unknown `log/set-level` level; `nodes:remove` with neither `nodeId` nor `nodeUuid`; wrong-typed `cluster:set-identity` fields. |
+| `-32603` | Internal error | an unexpected local failure (e.g. the trusted-store write failed while pinning, identity unreadable). The pairing/membership change did **not** take effect. |
+| `-32001` | Unknown invite | `inviteId` not found or already evicted — `cluster:invite-status`, `cluster:respond-to-invite`, `cluster:cancel-invite`. |
+| `-32002` | Invalid invite state | the invite exists but the call isn't valid for it — `respond-to-invite` on an **outbound** invite (one we sent, not received), `cancel-invite` on an **inbound** invite (one we received, not sent), or either on an invite whose `InviteState` is already terminal (`paired`/`declined`/`canceled`/`expired`/`failed`) rather than `pending`. `data` = `{inviteId, state}`. A second `respond-to-invite` for an already-`paired` invite lands here (the first already transitioned it). |
+| `-32004` | Precondition not met | a call's required precondition isn't satisfied: `cluster:create` while the node is already clustered (`data:{reason:"already-clustered"}`). (`cluster:invite-node` no longer returns `-32004`: an unclustered invite auto-founds a cluster of one rather than rejecting — §7.0/§7.2.) |
+
+App-specific codes live in the JSON-RPC server-error range (`-32000…-32099`); new ones are additive (§7.3). The split for PINs is deliberate: a **malformed** PIN (not six digits) is `-32602` (structurally invalid, no EAP-NOOB attempt is spent); a **well-formed-but-wrong** PIN is a `state:"failed"` *result* (an attempt was made and the peer rejected it). Likewise an unreachable peer is a `failed` *result*, not an error — the request itself was processed.
+
+**Rule 3 — reply unless the message can't be correlated.** If a stdin line is unparseable JSON or lacks a usable `id`, the CM logs and drops it (there is no `id` to address a response to). Any well-formed request object carrying an `id` **always** receives exactly one matching response (`result` or `error`), so the Broker never blocks on a dangling `id`. (This refines §6's "drop-and-log": drop only the uncorrelatable lines; everything with an `id` is answered.)
+
+**Per-method error surface** (anything not listed returns a `result`):
+- `cluster:get-node-id` — none in normal operation (identity is minted at startup or the process exits, §12); only `-32603` if local state is unreadable.
+- `cluster:set-identity` — `-32602` (bad field types). Otherwise `result`.
+- `cluster:create` — `-32602` (bad field types); `-32004` (already clustered). Otherwise `result`.
+- `nodes:get-initial` — none (empty list is a normal `result`).
+- `cluster:invite-node` — `-32602` (bad `address`/`port`/`nodeId`); `-32004` (invited while unclustered — `cluster:create` or accept an invite first); `-32603` (internal). Peer problems → `failed` *result*; an already-clustered target refusing the pairing → `rejected` *result* (with `reason: "already-clustered"`), not an error.
+- `cluster:invite-status` — `-32602` (absent `inviteId`); `-32001` (unknown `inviteId`).
+- `cluster:respond-to-invite` — `-32602` (absent `inviteId`/`accept`, or malformed `pin`); `-32001` (unknown `inviteId`); `-32002` (invite is outbound, or its `InviteState` is already terminal rather than `pending`); `-32603` (internal, e.g. pin-write failure). Wrong PIN / decline / peer-drop → `failed`/`declined` *result*.
+- `cluster:cancel-invite` — `-32602` (absent `inviteId`); `-32001` (unknown/evicted `inviteId`); `-32002` (invite is inbound, or its `InviteState` is already terminal rather than `pending`). A joiner that's unreachable for the best-effort cancel notification is **not** an error — the inviter-side teardown succeeded, so it's a normal `canceled` *result*.
+- `nodes:remove` — `-32602` (neither id provided, or the resolved node is **self** — use `cluster:leave`); `-32603` (internal). Non-member → `removed:false` *result*; peer-notify failure → `removed:true` *result*.
+- `cluster:leave` — none (already-unclustered is a normal `left:false` *result*, not an error).
+- `log/set-level` — `-32602` (unknown level).
+
+**Direction, concurrency, readiness.**
+- **Notifications never carry errors.** `cluster:invite-received`, `cluster:invite-canceled`, `cluster:invite-declined`, `cluster:identity-changed`, and `nodes:changed` are JSON-RPC *notifications* (no `id`, no reply). The CM never sends a *request* to the Broker, so the Broker needs no inbound-request handler — the local channel is Broker-request → CM-response, plus these CM→Broker notifications.
+- **Concurrency.** `cluster:invite-node` and `cluster:respond-to-invite` block on multi-round-trip network I/O (§7.2) for up to the pairing timeout (§10/§12 — bounded, default a few seconds). The CM **processes local requests concurrently** so a slow pairing never stalls reads or other calls; responses are matched by `id` and **may return out of order** (permitted by JSON-RPC). `stdout` frames are still serialized so they never interleave (§5). The Broker's per-request timeout must therefore exceed the pairing timeout for these two methods.
+- **Readiness.** The CM starts reading stdin immediately; a first successful `cluster:get-node-id` is the natural readiness probe (the node identity exists from startup, §7.4). Results and notifications are eventually-consistent — a `nodes:changed` may arrive just before or after the `result` of the call that caused it — so the Broker should reconcile by `inviteId`/`nodeUuid`, not by ordering.
+
+### 7.7 Cluster trust fan-out (roster reconciliation)
+
+Point-to-point pairing alone leaves trust un-propagated: if A pairs B and then A pairs C, B and C have each pinned only A and cannot mTLS each other. The **roster reconciliation** layer closes this so every member transitively trusts every other member, while keeping the human-entered PIN as the sole root of trust.
+
+- **Admission incarnation (the ordering primitive).** Every node owns a durable, node-global monotonic admission counter (`admission.json`). Founding or joining consumes the next epoch and records `{clusterId, epoch}`; restart reuses that active pair and teardown clears only the active pair, never the counter. `PairingInfo` v2 carries the epoch inside the EAP-NOOB-authenticated transcript, and the exact epoch is persisted on `ClusterNode`, `TrustedPin`, and `RosterEntry`. Pre-v2 epoch-zero pins/members (including records with an absent cluster id) map deterministically to epoch 1 in the active cluster and receive a local v2 endorsement. Therefore "newer admission" is a signed/pinned fact rather than a wall-clock comparison: rejoining the same cluster after removal necessarily has a larger epoch, while an old proof remains scoped to the incarnation it removed.
+- **Endorsement (the trust primitive).** On every successful pairing, each side signs an **endorsement** of the other's exact certificate and admission with its own Ed25519 leaf key: a v2 payload of `(introduced nodeUuid, cert fingerprint, clusterId, introduced admission epoch, endorser admission epoch, issuedAt)` under a domain-separation tag, stored alongside that peer's pin. An endorsement is the cryptographic statement "I, this exact admission of a trusted member, vouch that this exact cert admission was authenticated by pairing." Because it is end-to-end signed, it stays verifiable across gossip hops (unlike mTLS, which authenticates only one hop). The legacy v1 signature remains serialized for compatibility but cannot authorize admission-aware removal.
+- **Roster.** A node's roster is `{clusterId, members[], removalProofs[], tombstones[]}`: a self entry plus one entry per pinned peer (carrying that peer's stored endorsements, admission epoch, and last-known reachable address), durable removal-proof envelopes, and a bare-tombstone compatibility mirror.
+- **Reconcile (the merge rule).** On receiving a roster (over the mTLS `POST /v1/cluster/roster` endpoint, so the sender is already a trusted member), a node **transitively pins** every entry whose exact cert admission is endorsed by a node/admission it *already* trusts, iterating to a fixpoint so a freshly-pinned node can in turn vouch for the nodes it endorsed. The endorsement graph it walks **is** the human-authorized pairing graph. The merge is bounded: an entry endorsed only by a node it does not trust is rejected, an endorser or introduced admission mismatch is rejected, and an entry whose cert does not match its claimed fingerprint is rejected. A newer authenticated admission may replace an older same-cert admission; stale gossip can never downgrade it.
+- **Removal fan-out (durable proofs).** A removal first persists a `RemovalProof`: an admission-bound tombstone `(removed nodeUuid, clusterId, removed admission epoch, remover nodeUuid, remover admission epoch, removedAt, signature)`, the original remover certificate/fingerprint, and signed endorsements of that remover from relays. Persistence is authoritative and precedes de-pinning: if it fails, removal fails with membership intact; restart replays a persisted proof against a stale pin/member if the process stopped between those steps. A recipient verifies the original tombstone signature and either the exact directly-pinned remover admission or an endorsement from an exact admission it still trusts. This lets an older member relay proof from a remover the offline victim never pinned. Proof retention has **no TTL**: it remains durable and gossiped until a strictly newer authenticated admission of the removed node has been durably pinned, at which point that older proof is superseded and deleted. `removedAt` is audit metadata only, never ordering authority.
+- **Convergence triggers.** Reconciles are pushed to all members on **pair success** (the inviter fans the new member out; the joiner reconciles with the inviter to learn the rest of the cluster from its reply) and on **removal**, with a periodic **heartbeat** (~30 s) as the catch-up backstop for members that were offline during a change. Peer addresses come from the address recorded at pairing (the observed source IP plus the listening port the joiner advertises in its PairingInfo), falling back to the discovery resolver (§7.5) for a member whose address was never observed.
+- **Self-removal on unanimous rejection plus proof (offline-removed backstop).** A node removed while offline misses the direct notify and every peer has already de-pinned it, so normal roster reconciles receive `403`. A unanimous `403` is **necessary but not sufficient**: a peer that merely left also drops all pins and returns the same status. A rejecting peer therefore includes any durable proof targeting the caller in the `403` body. The caller self-removes only when every current peer rejects, no peer is unreachable, and at least one response carries a fully verified proof for this node's **exact current cluster admission** (direct remover or relay-endorsed unknown remover). A bare `403`, bare/legacy tombstone, wrong cluster/epoch, unknown signer, stale endorser admission, or tampered proof never authorizes self-teardown; instead, after the same cluster/generation recheck, a bare authenticated rejector is de-pinned and removed as a peer that departed or lost its cluster trust. This lets a surviving node converge to a solo roster after its only offline peer voluntarily leaves. The network verdict is revalidated against cluster identity and the in-process composition generation under `rosterMu`; a concurrent different- or same-cluster rejoin invalidates it. Teardown, invite/session reset, initial invite publication, pairing commit, and final EAP-Success release all share that composition boundary, so an in-flight exchange cannot republish state or produce a one-sided Registered pairing after teardown.
+- **Threat model.** Trust is now **transitive**: a compromised member can endorse certs that every other member will then pin, so the blast radius of one bad node is the whole cluster rather than just its direct pairings. This is a deliberate trade-off (re-pairing every pair by hand does not scale) layered on the same "pair only on a network you control" debt as the PIN. Hardening options include a cluster CA with revocation, endorsement quorums, and audit logging.
+
+## 8. Dependencies
+- **Upstream**: a supervising parent — in practice `nvpair-ui-broker`, which spawns the Cluster Manager, drives the §7.0 requests, and consumes its notifications. The process is **supervisor-agnostic**: it runs under any parent that speaks the §7.0 JSON-RPC contract over stdio (or `--ipc`). Since the node identity is self-owned (§7.4), the only thing a parent must supply is the *cluster* identity via `cluster:set-identity` (from `nvpair-node-settings`); without it the node stays unclustered until it pairs.
+- **Downstream**: local UI Broker (consumes results, `cluster:invite-received`, and `nodes:changed`); peer Cluster Manager instances (run pairings over the pairing channel and receive removals over mTLS).
+- **Library**: the in-tree `eap-noob` Go module (RFC 9140) drives the PIN-authenticated key exchange; it needs the one small additive extension noted in §4/§7.4 (caller-injected `Noob` on each role, `Server.OOBOutputWith` / `Peer.OOBInputNoob`).
+- **External / sibling**:
+ - **`nvpair-node-settings`** — owns `cluster_id` / `cluster_friendly_name` / `cluster_auto_sync`. The Cluster Manager reads the local identity (through the Broker) and reports the outcome of a join; it does not write settings directly (open question §4).
+ - **`nvpair-node-scanner` discovery daemon, via the Broker's relay** — advertises this node's `cl` port on the node's single consolidated record and supplies the `discovery:nodes` snapshots the peer resolver is rebuilt from (§7.5). Its snapshots are merged with the addresses the Broker supplies directly (e.g. from `discovery:get-nodes` / manual nodes), which take precedence, so a node reachable only by manual entry can still be invited.
+ - **Multicast-capable network** — required by the discovery daemon's browse, not by this service directly; not required at all when the Broker supplies the target address.
+ - **Per-user config directory** — the on-disk home for this node's keypair/cert and the trusted-node store (§7.4), shared with `nvpair-node-settings` and the TLS settings file.
+- **Consumers of the trust fabric** (inverse dependency): `nvpair-workload-manager` and `nvpair-errors` peer-sync are intended to authenticate against the keypair + trusted-node store this service owns; they depend on its on-disk format/location (§7.4), not the reverse (handoff open, §4).
+
+## 9. Data Ownership
+- **Owned**: the local membership set (members + pending invites), the in-flight invite table, **this node's cryptographic identity (UUID + keypair + self-signed cert), and the trusted-node store** (UUID → pinned peer cert). **Source of truth for cluster membership and for cluster trust from this node's perspective** — distinct from `nvpair-node-settings`, which owns the `cluster_id` value but neither the member list nor any key material.
+- **Source of truth**: yes, for *membership* (which nodes this node considers cluster peers) and for *trust* (which peer certs are pinned). No, for *cluster identity* (`cluster_id`) — that's `nvpair-node-settings`.
+- **Storage**: the identity (`node.key`/`node.crt`/`identity.json`), admission counter/current-or-retired incarnation (`admission.json`), trusted-node store (`trusted/<uuid>.json`), confirmed member set (`members.json`), admission-targeted proof set (`removal-proofs.json`), and teardown intent (`teardown.pending`) are **durable**. Writes are atomic. Create/join commits persist a provisional nonzero self member, peer membership, and peer pin before activating `admission.json`; startup rolls back that recognizable provisional state if a crash occurs before activation. Pairing and roster fan-out persist membership before granting the peer's mTLS pin, and startup removes any orphan pin with no matching durable member. Removal proof persistence occurs under the live composition boundary before de-pinning, and proof replay completes an interrupted peer removal on restart. Teardown writes its intent first; while `teardown.pending` is set, old pins cannot authenticate and no new admission can activate. Startup completes every remaining cleanup step before serving, and any replay/cleanup persistence error aborts startup rather than serving partial authorization. Proofs are retained until a newer authenticated admission supersedes them, not deleted by elapsed time. The in-flight invite/session table is transient and bounded. Private keys never leave the host; only the public cert is transmitted.
+
+## 10. Design Constraints
+- **Performance**: very low event volume — membership changes are human-driven (invites, accepts, removals), not telemetry. No latency SLA; the invite flow is inherently async (gated on a remote user).
+- **Scalability**: ~dozen-node cluster. Membership and invite tables are small; each change touches at most one peer.
+- **Reliability**: best-effort inter-node delivery with bounded timeouts/retries; a local membership change always applies even if the peer notification fails, and re-delivery reconciles idempotently. Serialized `stdout`. No replay — divergent views reconcile via later actions (or a future heartbeat, §4).
+- **Security**: trusted inter-node traffic is mTLS over HTTPS, authenticated against the trusted-node store (§7.4); unpinned/absent client certs are rejected (`403`). Pins are bootstrapped by an EAP-NOOB pairing authenticated by a user-carried PIN (no central CA), keyed by stable node UUID; removal de-pins (the only revocation path). Private keys are stored `0600` and never transmitted; the PIN is never sent on the wire or logged. Payloads carry node IDs/UUIDs, display names, addresses, certs (public), and the `cluster_id` — no inference data or PII. `nodeId` / `nodeUuid` / `inviteId` / `clusterId` are opaque system-generated identifiers. **Known, accepted, temporary weakness (§4): the six-digit pairing PIN is low-entropy and does not resist an active MITM** — it must be upgraded to a high-entropy OOB pairing code before cluster trust is relied on. Other residual exposure: no cert revocation beyond removal; monitor cert expiry.
+- **Compliance**: membership and invite payloads must contain no PII (display names are user-chosen labels, not identities).
+
+## 11. Assumptions
+- A parent supervises the process (in practice `nvpair-ui-broker`, but supervisor-agnostic — §8); on `stdin` EOF the manager shuts down cleanly, with no reconnect or buffering.
+- Cluster identity (`cluster_id` / `cluster_friendly_name`) is owned by `nvpair-node-settings` and arrives via `cluster:set-identity`; the *node* identity (UUID/keypair/cert) is self-owned, generated once on first run, and stable for the life of the install (§7.4).
+- Invites are always interactive — no auto-accept path; entering the PIN is the out-of-band authorization, so pinning is never silent (§4).
+- Small cluster (~dozen nodes), low human-driven change rate — one invite at a time, no bulk join or historical replay.
+- A node leaves the unclustered state in exactly two ways: founding a cluster (explicitly via `cluster:create`, or implicitly as the auto-found side effect of the first `cluster:invite-node` while unclustered — §7.0/§7.2), or adopting the inviter's cluster on accept (the current "join the inviter's cluster" working model — §4).
+- The per-user config dir is writable and private to the user.
+
+## 12. Failure Modes and Mitigations
+- **Peer unreachable during the Initial Exchange** (down, partitioned, suspended): the pairing can't start. → Bounded timeout/retries; the outbound invite ends `failed` and `cluster:invite-status` reports it. No PIN is issued and no membership is created.
+- **Peer unreachable during the Completion Exchange or a removal**: the two sides may disagree about membership. → A wrong PIN or unfinished completion simply leaves both unpaired (fail closed). For removal, the local change applies regardless; re-delivery on reconnect reconciles idempotently (and a future membership heartbeat, §4, would close the gap). Removal is authoritative locally even if the peer never hears it.
+- **Wrong / mistyped PIN (surfaces as a Completion `MACs`/`MACp` mismatch or an unrecognized `NoobId`)**: a typo or a tampered transcript. → EAP-NOOB completion fails; the invite ends `failed` with no pin and no membership. The user can retry by re-inviting (a fresh PIN). A few failed attempts should expire the session (§4) to bound online guessing.
+- **Active MITM on the pairing channel** (the accepted §4 weakness): because the PIN is only ~20 bits and `NoobId`/MACs are in-band, a determined on-path attacker can recover the PIN and substitute its cert. → **Not fully mitigated today** — documented debt; partial mitigations are session expiry and limited PIN attempts. Real fix is the high-entropy pairing code (§4).
+- **Duplicate / retried pairing or removal message**: could create a second pending invite or double-apply a change. → Deduplicate by `inviteId` (pairing) and `nodeUuid` (removals); re-delivery is a no-op that returns the same `2xx`.
+- **Unwanted / spoofed removal on the LAN**: a stranger could send a removal. → `members/remove` requires a pinned client cert over mTLS (`403` otherwise), so only an already-paired peer can trigger it; pairing itself requires the user to enter the PIN.
+- **Presented cert doesn't match the pin (impersonation / stale pin)**: a peer presents a cert that doesn't match what's pinned for its claimed UUID. → Reject the handshake (`403`), log the presented subject/fingerprint vs. the pinned one. A *different* cert for an already-pinned UUID is never silently re-pinned — it requires an explicit re-pin / re-invite flow (§4, key rotation).
+- **Cert expiry**: a peer's (or this node's) leaf expires, breaking handshakes. → Monitor and warn ahead of expiry (§13); rotation re-pins via a re-invite or explicit re-pin path (§4). Clock skew between nodes can cause spurious not-yet-valid / expired errors — leaves are issued with a small backdated `notBefore` to absorb modest skew.
+- **Key material missing or corrupt on startup** (`node.key`/`node.crt` unreadable): the node can't authenticate. → If `identity.json` exists but the keypair is gone/corrupt, fail loudly (don't silently mint a new UUID — that would orphan every existing pin on peers); a genuinely first run (no `identity.json`) mints fresh. Loss of identity requires re-inviting the node.
+- **Malformed payload / unknown method or endpoint**: could propagate garbage. → Validate every envelope; reject (`400`) inter-node or drop-and-log locally; never apply unvalidated changes.
+- **Invite never answered**: a `pending` invite would linger forever on both the inviter and the receiver. → TTL expiry (default 5 minutes) moves it to `expired` on **both** sides — the receiver also signals the inviter (`phase:"expire"`) for immediate teardown, with each side's own TTL as the fallback; `cluster:invite-status` reflects it.
+- **Local interface severed** (Broker exited → `stdin` EOF / `stdout` `EPIPE` / `ERROR_BROKEN_PIPE`): an orphaned manager would have no one to serve. → Treat EOF/`EPIPE` as the shutdown signal: stop the listener and exit cleanly. No reconnect/buffering — a new Broker spawns a fresh manager (which reloads persisted membership if §4 lands on persistence).
+- **Stale discovery snapshot** (departed node still resolvable, or new node not yet in a snapshot): wasted delivery attempts or a not-yet-invitable node. → Replace the resolver map from every `discovery:nodes` snapshot, so a node absent from the next one stops resolving without any expiry logic here; liveness is the discovery daemon's. A Broker-supplied address is the fallback when the resolver is stale or empty.
+
+## 13. Observability
+- **Logging**: pairing lifecycle (initial-exchange started / completed, PIN issued [**never the PIN value**], PIN entered, paired / declined / expired / failed) with `inviteId` and peer; EAP-NOOB protocol errors (`MACs`/`MACp` mismatch, unrecognized `NoobId`); membership changes (join, local removal, peer-initiated removal) with `nodeId`/`nodeUuid`; cert pins added and dropped (with UUID + fingerprint); mTLS rejections (`403`) with the presented subject/fingerprint vs. the pinned one; cert expiry warnings (own and peer leaves); first-run identity generation; inter-node delivery failures including final drop; malformed/protocol-error rejections (`400`); resolver changes applied from a `discovery:nodes` snapshot, and whether a dialed address was resolved or Broker-supplied; startup and clean shutdown on `stdin` EOF / `stdout` `EPIPE`. Never log private key material, full cert PEMs at info level, or the PIN.
+- **Metrics**: pairings started/completed and outcome counts by terminal state; failed-PIN-attempt count (online-guessing signal); pending-pairing count and age (expiry pressure); current member count; pinned-cert count; mTLS handshake failure count and `403` count; days-to-expiry of the nearest-expiring pinned/own cert; inter-node delivery success/failure/retry/drop counts; resolvable peer count and the resolved-vs-Broker-supplied split of dialed addresses.
+- **Alerts**: a spike in failed PIN attempts for a session (possible online guessing); sustained inter-node delivery failures to a peer; elevated `403` / `400` rate (untrusted caller or misconfiguration); a pinned or local cert approaching expiry; persistent membership divergence once a heartbeat exists.
+
+## 14. Sample usage
+On first run, nodes A and B each mint a stable UUID + keypair and a self-signed cert under `<config-dir>/cluster/` (§7.4). Both start unclustered (`cluster:get-node-id` → `clusterId: ""`).
+
+On node A, the user clicks "Create cluster"; A's Broker sends `cluster:create`, which mints a unique UUID v4 `clusterId` (shown here as the illustrative `"cluster-xyz"`, friendly name "Lab 3 desks"), records A as founder, and emits `cluster:identity-changed` (the Broker persists it to `nvpair-node-settings`). A is now a cluster of one and can invite. (Node B does nothing here — it will join A's cluster by accepting the invite.)
+
+On node A, the user opens the cluster view and invites node B (discovered on the LAN or entered manually). The Broker on A sends `cluster:invite-node` with B's address. A's Cluster Manager (EAP-NOOB **Server**) runs the Initial Exchange with B over `POST /v1/cluster/pairing`, embedding A's cert PEM in `ServerInfo`; B (EAP-NOOB **Peer**) auto-responds, embedding its cert in `PeerInfo`. Both reach `Waiting`. A derives the six-digit PIN `402199` and returns `{inviteId: "inv-9f3a1c", state: "pending", pin: "402199"}`; A's UI shows the PIN.
+
+B's Cluster Manager emits `cluster:invite-received`; B's UI prompts "enter the PIN shown on Lab desk A". The user reads `402199` from A's screen (in person / over the phone) and types it on B; B's Broker sends `cluster:respond-to-invite` (`accept: true, pin: "402199"`). B feeds the PIN to EAP-NOOB (`OOBInputNoob`, moving its Peer to `OOBReceived`) and then **drives the Completion Exchange back to A** on the pairing channel: B POSTs an empty-`msg` kickoff, A (resuming its `inviteId`-keyed Server) replies with the reconnect Discovery, and the loop runs Discovery → NoobID → MACs/MACp until A returns `EAP-Success` (B is the HTTP client throughout; A is still the EAP-NOOB Server — §7.2). Both reach `Registered`. Each side reads the other's now-authenticated cert from the transcript and **pins it** (keyed by the peer's UUID); A's invite flips to `paired` and both record each other as `member`.
+
+From here every trusted inter-node call between A and B is mutually authenticated over mTLS — each presents its leaf and is verified against the other's pin. Both Brokers see each other in `nodes:get-initial` (and via the proposed `nodes:changed` push). Later, the user on A removes B: the Broker sends `nodes:remove` (`nodeUuid` of B); A drops B locally, **deletes B's pin** (so any further handshake from B fails `403`), and notifies B via `POST /v1/cluster/members/remove` over mTLS, so B drops A too. If B was offline, the removal and de-pin still apply on A immediately and reconcile when B returns.
+
+> Reminder (§4): the six-digit PIN is a temporary, MITM-vulnerable bootstrap accepted to ship the flow; it must be replaced by a high-entropy pairing code before the cluster trust is relied on in production.
+
+## 15. Process model, CLI, and build wiring
+
+**Process model.** A single Go binary, `nvpair-cluster-manager`, speaking newline-delimited JSON-RPC 2.0 on stdio by default (`--ipc` selects a Unix socket / Windows named pipe, like the other subprocesses). It runs one inter-node HTTP listener on `:14321` (§7.5) serving both the plain-HTTP pairing channel and the mTLS trusted endpoints. On Windows the console window is hidden by the parent via `syscall.SysProcAttr{HideWindow: true, CreationFlags: 0x08000000}` — the same pattern every other subprocess uses (`subprocess_windows.go` / `subprocess_other.go`); the binary itself needs no special handling.
+
+**CLI flags** (minimal, matching repo conventions):
+- `--version` — print `main.Version` (stamped via `-ldflags "-X main.Version=…"` from `versions.json`; never hardcoded — §AGENTS Versioning) and exit.
+- `--ipc <path>` — use a Unix socket / named pipe instead of stdio.
+- `--log-level <level>` — initial `nvpair-shared/applog` level; mutable at runtime via the `log/set-level` JSON-RPC method (§7.0).
+- `--config-dir <path>` (optional override) — where `cluster/` lives; defaults to the shared per-user config dir (§7.4).
+- `--port <n>` (optional override, default `14321`) — the inter-node listener port.
+
+No flag carries the node identity (self-generated, §7.4) or the cluster identity (`cluster:set-identity`, §7.0), keeping the binary self-bootstrapping under any supervisor.
+
+**Build wiring**: `nvpair-cluster-manager` is one of the Go binaries in the product bundle. Adding it requires, in the same change:
+- a `components.nvpair-cluster-manager` entry in `versions.json`, an `installer` bump, and a `product` bump (see `VERSIONING.md`);
+- a build + copy step in **both** `build.bat` and `build.sh` (→ the repo-root `build/bin/` bundle), with the `-X main.Version=…` ldflag;
+- inclusion in the NSIS installer (`installer/nvpair-setup.nsi`) and any firewall-rule list (it opens TCP `14321`), plus `bom.md`;
+- a `product` bump declared in the pull request's release-intent block (see `VERSIONING.md`).
+
+Because it is launched on demand by `nvpair-ui-broker` (which expects workers as sibling files in its working dir, like the other broker-supervised binaries), it must land in the same `build/bin/` directory as the rest.
diff --git a/services/nvpair-engine-manager/MANIFEST.md b/services/nvpair-engine-manager/MANIFEST.md
new file mode 100644
index 0000000..7ae8108
--- /dev/null
+++ b/services/nvpair-engine-manager/MANIFEST.md
@@ -0,0 +1,364 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Engine Manifest Reference
+
+An engine manifest is a single JSON file that tells `nvpair-engine-manager`
+how to detect, install, run, probe, and act on one inference engine. The
+runner is engine-agnostic: **adding an engine is a manifest, not code.**
+
+## Where manifests live
+
+- **Bundled** defaults are compiled into the binary from
+ `nvpair-engine-manager/manifests/*.json` (e.g. `ollama.json`).
+- **User / third-party** manifests are read at runtime from
+ the per-user data dir's `engines/*.json`
+ (`%LocalAppData%\Nvidia Corporation\Personal AI Router\engines\` on Windows,
+ `~/.config/Nvidia Corporation/Personal AI Router/engines/` on Linux,
+ `~/Library/Application Support/Nvidia Corporation/Personal AI Router/engines/` on macOS).
+
+A user manifest **overrides** a bundled one with the same `engine` name,
+so a vendor or operator can ship or tweak an engine without rebuilding. The
+override is a **deep-merge onto the bundled manifest** (override keys win, the
+same key-by-key rules as the shared-defaults merge below), not a wholesale
+replace — so a partial file pins only the fields it sets and keeps inheriting
+everything else (install URLs, actions, fixes) as the bundled manifest is
+upgraded. A user file for an engine with **no** bundled base of the same name
+is loaded standalone (it must then be a complete manifest). This is how
+`engine:set-port` persists a chosen port: it writes the minimal delta
+`{ "engine": "<name>", "runtime": { "port": <n> } }`, which merges onto the
+bundled manifest so only `runtime.port` is pinned. (A standalone
+`LoadRegistry(dirs…)` load still replaces wholesale; the deep-merge applies to
+the per-user `engines/` override layer that the service overlays at startup.)
+
+## Top-level fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `engine` | string | yes | Unique id (the key used in `engine:*` calls). |
+| `display_name` | string | yes | Human-friendly name. |
+| `manifest_version` | int | yes | Must be `1`. A higher value is rejected (asks for behavior this binary lacks). Unknown optional fields within a supported version are ignored, so the schema can grow additively. |
+| `platforms` | object | yes | Map of `"<goos>/<goarch>"` → platform block (e.g. `"windows/amd64"`, `"darwin/arm64"`, `"linux/amd64"`). At least one entry. The runner selects the block matching the host. |
+| `actions` | object | no | Map of action name → action (see below). |
+| `detect` / `install` / `uninstall` / `runtime` | — | no | Optional **shared defaults** inherited by every platform (see below). |
+
+**Shared defaults & per-platform overrides.** The platform-level fields `detect`, `install`, `uninstall`, and `runtime` may also be given once at the top level as shared defaults; each `platforms` entry is then merged onto them. Nested objects (e.g. `runtime`, `runtime.env`) merge key-by-key with the platform value winning, while arrays and scalars are replaced wholesale. So a runtime that's identical across platforms except `cli` is declared once at the top level, and each platform sets only `"runtime": { "cli": "…" }`. Omitting a key inherits the default; setting it (even to a zero value like `"port": 0`) overrides it. A manifest that fully specifies each platform with no top-level defaults behaves exactly as before.
+
+## Platform block
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `detect` | string[] | no | Paths that, if any exists, mean the engine is already installed. Supports OS env refs (`%VAR%`, `$VAR`), a leading `~`, and the `{install_dir}` placeholder. |
+| `install` | object | no | How to obtain the engine (see Install). Omit for engines that are only ever detected/launched. |
+| `uninstall` | object | no | `{ "run": [...] }` — argv to remove a user-mode install (the engine's own uninstaller, or `rm -rf {install_dir}`). Backs `engine:uninstall`; placeholders resolved, OS env refs expanded. |
+| `runtime` | object | yes | How to launch + probe the engine (see Runtime). |
+
+### Install
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `fetch.url` | string | when `fetch` present | Download URL — **HTTPS** (plain `http` only from loopback). |
+| `fetch.sha256` | string | no | Hex SHA-256. When set, the download is verified against it **before** `run` executes; when omitted, the fetch is HTTPS-only and runs with a loud "unpinned" warning (the same weaker guarantee as `script`). Pin it for any real release. |
+| `run` | string[] | no | Argv to execute after download (e.g. run the installer, extract the archive). Placeholders resolved; OS env refs expanded. Requires a `fetch` (the artifact it unpacks). |
+| `script` | string[] | no | **Escape hatch** for vendors that only ship a script installer. Runs **without** checksum verification (logged as unpinned) and replaces `fetch`+`run`. Prefer `fetch`+`run` whenever the vendor publishes a script or artifact: download it first, then execute the local file. **Make failures loud:** a piped bootstrap such as `curl … \| bash` can mask a failed fetch, while a separate fetch prevents the run and reports the error. |
+| `mode` | string | no | `"user"` (default) or `"admin"`. The runner **refuses** `"admin"` (engine-manager is user-mode only); it is a deliberate, flagged exception, not a default. |
+
+### Runtime
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `mode` | string | no | `"process"` (default) — the engine is a foreground process this service spawns and **owns** (liveness = process alive) — or `"command"` — a daemon driven by start/stop commands (liveness = the probe). |
+| `bin` | string | process mode | Path to the engine binary (required in `process` mode). Placeholders + OS env refs resolved. |
+| `args` | string[] | no | Arguments (process mode). |
+| `env` | object | no | Extra environment (merged over the inherited env). Use `{host}`/`{port}` for the listen address, e.g. `"OLLAMA_HOST": "{host}:{port}"`. |
+| `port` | int | no | Fixed port, or `0` to auto-assign a free loopback port. |
+| `bind` | string | no | Listen address, substituted as `{host}`. Empty ⇒ `127.0.0.1` (the safe default); an inference engine that serves the cluster sets `"0.0.0.0"` (Ollama does), overridable per call via `engine:start {bind}`. Probes always target loopback. |
+| `start` | string[][] | command mode | Ordered bring-up commands (each an argv) for `command` mode, e.g. `[["{cli}","server","start","--port","{port}"]]`. |
+| `cli` | string | no | The engine's control-CLI path for this platform, referenced as `{cli}` by start/stop/actions so the manifest's **global** actions resolve to the correct per-OS binary. |
+| `ready` | probe | no | Readiness probe; `start` waits for it before reporting Running. |
+| `stop` | object | no | Process mode: `signal` (`"term"` default, or `"kill"`) + `grace_s` (seconds before force-kill). Command mode: `cmd` (argv) to bring the engine down. |
+| `health` | probe | no | Periodic liveness probe while Running; `interval_s` between checks. |
+
+A **probe** is `{ "http": "<url>", "status": <int>, "timeout_s": <int>, "interval_s": <int> }`
+or `{ "tcp": "<host:port>", ... }`. `status` defaults to `200`. Prefer
+loopback URLs/addresses.
+
+### Actions
+
+Each action is a config-declared operation exposed over `engine:action`.
+Exactly one of `http`, `cmd`, or `remove_path`:
+
+- **`http`** — call the engine's loopback control API. The caller's
+ `params` are sent as the JSON request body; `body_schema` is
+ informational. Requires the engine to be running.
+- **`cmd`** — run a CLI command (e.g. `lms get`). The caller's `params`
+ become placeholders (e.g. `{model}`); stdout is returned (parsed as
+ JSON when it is valid JSON). Does **not** require the engine to be
+ running.
+- **`remove_path`** — delete a filesystem path declared in the manifest.
+ `remove_path.root` and `remove_path.path` are templated (including
+ action `params` as placeholders); the resolved target must stay under
+ the declared root. Symlink escapes and missing targets are rejected.
+ Does **not** require the engine to be running.
+
+An optional **`result`** declares how `engine:models` extracts a normalized
+name list from the action's JSON response: `array` is the top-level array
+field to iterate and `field` is the string field to pull from each element.
+It lets one engine-agnostic path turn each engine's `list_models` shape into a
+flat `[]string` with no per-engine code — Ollama's `/api/tags`
+(`{"models":[{"name":...}]}`) uses `{"array":"models","field":"name"}`, while
+LM Studio's native `/api/v1/models` (`{"models":[{"key":...}]}`) uses
+`{"array":"models","field":"key"}`. A required array that is present but empty
+is an authoritative empty inventory; a missing, null, or wrong-typed array is
+unknown, as is a non-empty unfiltered inventory with no usable names.
+`engine:models` runs every running engine's `list_models` and unions the
+extracted names; it also backs the node's `em` HTTP endpoint
+(`GET /v1/models`) that peers fetch during discovery enrichment.
+
+`result` also takes an optional **`match`** row filter that keeps only array
+elements that pass the filter. Exactly one of `in` or `nonempty` is required:
+
+- `{"field":...,"in":[...]}` — keep elements whose `field` (a JSON string)
+ equals one of `in`.
+- `{"field":...,"nonempty":true}` — keep elements whose `field` is a JSON
+ array with length > 0.
+
+This lets a `loaded_models` action reuse the same extractor as `list_models`
+even when an engine's list endpoint returns *all* models tagged with residency
+rather than a presence-only list. The bundled `loaded_models` actions report
+the models resident in memory (surfaced as `engine:models`'s `loadedByEngine`
+and pushed via `engine:models-changed`): Ollama's `GET /api/ps` is presence-only
+so it needs no `match` (`{"array":"models","field":"name"}`), while LM Studio's
+native `GET /api/v1/models` uses
+`{"array":"models","field":"key","match":{"field":"loaded_instances","nonempty":true}}`.
+A row whose `match.field` is missing or the wrong JSON type fails the match (it's
+excluded). The filter shape lives in the manifest so it can be updated without a
+code change if an engine's API drifts. An engine that declares no `loaded_models`
+action simply contributes no `loadedByEngine` key. The bundled LM Studio list
+and loaded actions require LM Studio 0.4.0 or newer, where the native
+`/api/v1/models` endpoint is available. All of this stays additive:
+`manifest_version` is still `1`.
+
+An optional **`model_resolution`** expands or resolves the `{model}`
+placeholder before the action runs:
+
+- **`"lms-get"`** (cmd actions only) — try the value as given (so an
+ explicit `huggingface.co`/`lmstudio.ai` URL is honored first), then the
+ LM Studio Hub artifact id (`owner/name`), then the Hugging Face repo
+ URL. This works around `lms get` routing a bare `owner/name` to the Hub
+ registry, which 404s the Hugging-Face-hosted community models LM
+ Studio's own Discover tab downloads. A **transient** download failure
+ (a stalled or timed-out transfer) is *not* a resolution failure:
+ rather than advancing to the next source, `lms-get` retries the same
+ command in place (a bounded number of times) — `lms get` resumes a
+ partial download on re-run — so a momentary network hiccup recovers
+ instead of failing the pull. A hard error still surfaces immediately.
+- **`"lms-disk-path"`** (remove_path actions only) — map a logical LM
+ Studio model id (the OpenAI-compatible `/v1/models` id, an
+ `owner/repo` pull key, or an on-disk path) to concrete files under the
+ declared `remove_path.root` via `lms ls --json`. When no indexed file
+ matches, the runner falls back to `{root}/{model}` if that path exists.
+
+An optional **`restart_after`** restarts the engine once the action succeeds.
+Declare it on an action that changes state the engine only reads at startup:
+LM Studio's `delete_model` removes the files, but its server answers
+`/v1/models` from an index built at startup and exposes no rescan operation
+(no CLI command, REST route, or SDK call), so clients keep being offered a
+deleted model until it restarts. It is opt-in per action and deliberately rare —
+Ollama reflects a deletion immediately, so its `delete_model` omits the flag and
+its engine is never bounced.
+
+The rules the runner enforces:
+
+- **A stopped engine stays stopped.** There is no serving state to reconcile,
+ and starting one behind the user's back would be a surprise.
+- **The user's ON/OFF intent is never rewritten.** The bounce goes through
+ `doStop`/`doStart`, not `Restart`, precisely because `Restart` also persists
+ desired-enabled — an action must not turn "delete this model" into "and leave
+ this engine switched on".
+- **The running check and the bounce share `opMu`.** A concurrent `Stop` either
+ wins the lock first (the action then sees a stopped engine and leaves it down)
+ or waits and stops the engine we just brought back. It can never be silently
+ undone.
+- **A failed restart fails the action**, because the action's effect is only
+ observable once the engine is back. The error names the restart
+ (`… failed to restart: …`) so a caller can distinguish "nothing happened" from
+ "the destructive half ran and the engine did not return" — the destructive
+ half is *not* rolled back, so re-issuing the action is the wrong response.
+- **The platform must declare `runtime.ready`.** `Validate` rejects
+ `restart_after` without one: readiness is what makes "the effect is visible by
+ the time this replies" true rather than a race with the engine's own startup.
+- **A remote caller waits on the readiness budget.** Driving such an action on a
+ peer means the peer withholds its response headers until the restart is ready,
+ so `remoteclient.go` routes that path through the readiness-sized client
+ (`waitsForEngineReadiness`) rather than the ordinary 30s one. Cutting the call
+ off would cancel the peer's in-flight handler and let `bringUpCommand` tear the
+ engine back down — for a delete, files gone and engine left stopped.
+
+```json
+"list_models": { "http": { "method": "GET", "path": "/api/v1/models" }, "result": { "array": "models", "field": "key" } },
+"pull_model": { "cmd": ["{cli}", "get", "{model}", "--yes"], "model_resolution": "lms-get" },
+"delete_model": {
+ "model_resolution": "lms-disk-path",
+ "remove_path": { "root": "{models_dir}", "path": "{models_dir}/{model}" },
+ "restart_after": true
+}
+```
+
+Actions target the engine's control plane — **not** inference endpoints
+(those stay with the proxy).
+
+## Placeholders
+
+Resolved by the runner at execution time; any other `{token}` fails
+validation at load:
+
+| Placeholder | Meaning | Available in |
+|---|---|---|
+| `{host}` | Listen address from `runtime.bind` (or a per-call `bind`); `127.0.0.1` when unset | runtime args/env |
+| `{port}` | The chosen runtime port | runtime args/env, start, probes, action paths |
+| `{bin}` | Resolved binary path (process mode) | runtime args/env |
+| `{cli}` | The platform's `runtime.cli` path | runtime start/stop, action `cmd` |
+| `{download}` | Path of the verified download | `install.run` |
+| `{install_dir}` | Per-engine user-scoped install dir | `detect`, `install`, runtime |
+
+A `cmd` action additionally templates the action's own `params` as
+placeholders (e.g. `{model}`), resolved at call time. HTTP actions send
+`params` as the JSON request **body** — they are not substituted into
+`http.path`, which templates only `{port}`.
+
+## Validation
+
+A manifest is rejected at load (with a specific message) when: a required
+field is missing, `manifest_version` is unsupported, a platform key isn't
+`"<goos>/<goarch>"`, `runtime.bin` is empty in process mode (or
+`runtime.start` is empty in command mode), `install.run` has no `fetch`,
+`install.script` is combined with `fetch`/`run`, `install.mode` or
+`runtime.mode` is invalid, an action sets none or more than one of
+`http`/`cmd`/`remove_path`, a `remove_path` action omits `root` or
+`path`, a `result` is set without both `array` and `field` (or a
+`result.match` without both `match.field` and a non-empty `match.in`), or
+a non-action templated string uses an unknown placeholder.
+
+---
+
+## Worked example 1 — Ollama (Linux, user-scoped, no sudo)
+
+A conservative Ollama manifest — user-scoped install (never the official
+`curl | sh`, which would `sudo`-install to `/usr` + systemd), checksum
+**pinned**, server kept on loopback. (The bundled `ollama.json` is shaped
+the same way but ships **unpinned** and defaults `runtime.bind` to
+`0.0.0.0`; see the note after the example.)
+
+```json
+{
+ "engine": "ollama",
+ "display_name": "Ollama",
+ "manifest_version": 1,
+ "platforms": {
+ "linux/amd64": {
+ "detect": ["{install_dir}/bin/ollama"],
+ "install": {
+ "fetch": { "url": "https://ollama.com/download/ollama-linux-amd64.tgz", "sha256": "‹release sha256›" },
+ "run": ["tar", "-xzf", "{download}", "-C", "{install_dir}"],
+ "mode": "user"
+ },
+ "runtime": {
+ "bin": "{install_dir}/bin/ollama",
+ "args": ["serve"],
+ "env": { "OLLAMA_HOST": "{host}:{port}", "LD_LIBRARY_PATH": "{install_dir}/lib/ollama" },
+ "port": 11434,
+ "ready": { "http": "http://127.0.0.1:{port}/", "status": 200, "timeout_s": 30 },
+ "stop": { "signal": "term", "grace_s": 5 },
+ "health": { "http": "http://127.0.0.1:{port}/", "status": 200, "interval_s": 5 }
+ }
+ }
+ },
+ "actions": {
+ "list_models": { "http": { "method": "GET", "path": "/api/tags" } },
+ "pull_model": { "http": { "method": "POST", "path": "/api/pull", "body_schema": { "name": "string" } } }
+ }
+}
+```
+
+> This example **pins** `sha256` (best practice). The bundled `ollama.json`
+> ships **unpinned** — `fetch` has no `sha256`, so install is HTTPS-only and
+> logs a loud "unpinned" warning. Pin it to the SHA-256 of a *versioned*
+> release URL for reproducible, integrity-verified installs ("latest" URLs
+> change checksum per release).
+
+## Worked example 2 — LM Studio (a daemon + control-CLI engine)
+
+LM Studio is shaped very differently from Ollama: its server runs in a
+background daemon driven by the `lms` CLI, model downloads are a CLI
+command (no HTTP endpoint), and its headless installer is a vendor
+script. It is still added with **no code** — using `mode: "command"`, a
+`cmd` action, `{cli}`, and a downloaded installer script:
+
+```json
+{
+ "engine": "lmstudio",
+ "display_name": "LM Studio",
+ "manifest_version": 1,
+ "platforms": {
+ "linux/amd64": {
+ "detect": ["~/.lmstudio/bin/lms"],
+ "install": {
+ "fetch": { "url": "https://lmstudio.ai/install.sh" },
+ "run": ["bash", "{download}"],
+ "mode": "user"
+ },
+ "uninstall": { "run": ["rm", "-rf", "~/.lmstudio"] },
+ "runtime": {
+ "mode": "command",
+ "cli": "~/.lmstudio/bin/lms",
+ "port": 1235,
+ "start": [["{cli}", "server", "start", "--port", "{port}"]],
+ "stop": { "cmd": ["{cli}", "server", "stop"] },
+ "ready": { "http": "http://127.0.0.1:{port}/v1/models", "status": 200, "timeout_s": 60 },
+ "health": { "http": "http://127.0.0.1:{port}/v1/models", "status": 200, "interval_s": 10 }
+ }
+ }
+ },
+ "actions": {
+ "list_models": { "http": { "method": "GET", "path": "/api/v1/models" }, "result": { "array": "models", "field": "key" } },
+ "pull_model": { "cmd": ["{cli}", "get", "{model}", "--yes"], "model_resolution": "lms-get" },
+ "load_model": { "cmd": ["{cli}", "load", "{model}"] }
+ }
+}
+```
+
+What each piece does here:
+- **`mode: "command"`** — no owned process; liveness is the `/v1/models` probe, and `stop.cmd` (`lms server stop`) brings the daemon down.
+- **`cmd` action** — `pull_model` shells out to `lms get {model}` (no HTTP equivalent exists), with `{model}` filled from the call's params.
+- **`model_resolution: "lms-get"`** — `pull_model` tries the model as given, then the Hub artifact id, then the Hugging Face repo URL, so a bare `owner/name` for a Hugging-Face-hosted model (most of LM Studio's catalog) downloads instead of 404ing against the Hub registry.
+- **`{cli}`** — the manifest-global `pull_model` action resolves to the right per-OS binary (`lms.exe` on Windows, `lms` elsewhere).
+- **Installer script** — LM Studio's headless installer is vendor-provided and unpinned. Engine-manager downloads it over HTTPS and executes the saved file as a separate argument, so fetch failures stay visible and paths containing spaces cannot be split by a shell. Windows executes the saved `.ps1` with PowerShell `-File`; it never pipes remote content through `Invoke-Expression`. The vendor script checks the downloaded archive against its published SHA-512 when one is available.
+
+---
+
+## Engine config reference
+
+A condensed map of each engine's manifest-relevant surface, to guide
+authoring. The recurring, high-value controls (and the right targets for a
+future "declared tunables" layer) are: bind host/port, model dir,
+concurrency/parallelism, max-loaded models, context length, keep-alive/TTL,
+GPU selection, and auth.
+
+| Engine | Fit | Headless launch | Config surface | Control |
+|---|---|---|---|---|
+| **Ollama** | strong (env-first) | `ollama serve` (foreground) | env: `OLLAMA_HOST`, `OLLAMA_MODELS`, `OLLAMA_KEEP_ALIVE`, `OLLAMA_NUM_PARALLEL`, `OLLAMA_MAX_LOADED_MODELS`, `OLLAMA_MAX_QUEUE`, `OLLAMA_CONTEXT_LENGTH`, `OLLAMA_FLASH_ATTENTION` | HTTP `/api/tags`, `/api/pull`; CLI `ollama pull/ls/ps/stop` |
+| **llama.cpp** | strong (env+flags) — **reference design** | `llama-server --host 127.0.0.1 --port {port}` (foreground) | flags + `LLAMA_ARG_*` (host/port, ctx-size, n-parallel, cont-batching, flash-attn, device, n-gpu-layers, tensor-split, main-gpu, api-key, models-dir/max) | HTTP `/v1/models`, `/models/load`, `/models/unload`, `/health`, `/slots` |
+| **LM Studio** | command / daemon | `lms daemon up` → `lms server start --port {port}` | small env (`LMS_SERVER_HOST`, `LM_API_TOKEN`); most config is flags/API/settings (`lms load --context-length/--gpu/--ttl`) | HTTP `/api/v1/models[/download\|load\|unload]`; CLI `lms ls/get/load/unload/ps` |
+| **vLLM** | flags-first — **Linux/WSL only** | `vllm serve <model> --host 127.0.0.1 --port {port}` | flags (host/port/api-key); `HF_HOME` for cache. `VLLM_PORT`/`VLLM_HOST_IP` are **not** the API bind | OpenAI `/v1/models`; one model per process (unload = restart) |
+| **Jan** | hybrid (on llama.cpp router) | `jan serve <model> --port {port}` (CLI) | forwards `LLAMA_ARG_*`; perf settings are router-preset-driven | `jan serve` auto-downloads HF repos |
+| **GPT4All** | weak (GUI app) | none (Local API Server toggled in the GUI, `:4891`) | desktop settings / Python SDK — not env | OpenAI `/v1` once enabled in-app |
+
+Caveats worth encoding when authoring these:
+- **Ollama `OLLAMA_MODELS`**: leave it at the default (`~/.ollama`) so models survive an `uninstall` that removes `{install_dir}` — **never** point it inside `{install_dir}`.
+- **llama.cpp** ships prebuilt archives with **published SHA-256s**, so it's an ideal checksum-pinned `fetch`+`run` target (no placeholder SHA needed).
+- **LM Studio** model dir is settings-controlled (no documented relocation env); surface its config as flags/API, not env.
+- **vLLM**: native Windows is unsupported (WSL only); the bind is a flag, not env.
+- **GPT4All**: no first-class headless CLI today — out of scope for a config-only manager unless targeting its Python SDK.
diff --git a/services/nvpair-engine-manager/spec.md b/services/nvpair-engine-manager/spec.md
new file mode 100644
index 0000000..820089b
--- /dev/null
+++ b/services/nvpair-engine-manager/spec.md
@@ -0,0 +1,210 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Microservice: Engine Manager (`nvpair-engine-manager`)
+
+## 1. Purpose
+A declarative, config-driven control plane for **local inference engines** (Ollama today; Intel / llama.cpp / others later). It owns an engine's entire lifecycle *except serving inference* — locate, install, launch, stop, restart, health, and config-declared actions — so one uniform API manages any engine across OSes with no per-engine code. A third party drops in a JSON manifest and their engine's install/launch/controls "just appear" over the same API: the core extensibility story for an open-source product.
+
+## 2. Scope
+**In scope**
+- Detect installation; **user-mode** install (HTTPS download + checksum-verify-when-pinned + run) per OS/arch.
+- Lifecycle: start (with readiness probe), stop, restart, status, periodic health.
+- Config-declared **actions** covering the full model lifecycle — Ollama: `list_models`, `loaded_models`, `pull_model`, `run_model`, `unload_model`, `delete_model`; LM Studio: `list_models`/`list_downloaded`, `loaded_models`, `pull_model`, `load_model`, `chat`, `unload_model`, `delete_model` (`remove_path` with `lms-disk-path` resolution) — mapped to each engine's local control API. `loaded_models` reports the models currently resident in memory (Ollama `GET /api/ps`, LM Studio `GET /api/v1/models` filtered by nonempty `loaded_instances`), name-extracted via the same declarative `result` spec (with an optional `match` row filter).
+- Per-engine stdout/stderr log capture and structured operational error records, surfaced via the errors pipeline.
+- A normalized node-level model list (`engine:models`): union of every running engine's `list_models`, name-extracted via each action's declarative `result` spec, plus the per-engine set of models loaded in memory (`loadedByEngine`, from each engine's `loaded_models` action). A successful explicit empty inventory remains an engine key with `[]`; a missing/malformed/failed inventory omits that engine key instead of being mislabeled as authoritative empty. A watcher polls the loaded set and pushes `engine:models-changed` when it changes (explicit load/unload, JIT auto-load, TTL/idle eviction).
+- Expose all of the above over the `engine:*` JSON-RPC surface to whatever orchestrates the service, plus an optional plain-HTTP LAN endpoint (`--http-port`, `GET /v1/models`) that serves the model list to a peer's discovery daemon (the list moved off the size-limited mDNS TXT onto HTTP).
+
+**Out of scope**
+- **Inference traffic** — stays with `ollama-proxy`; this service never proxies `/api/chat` etc.
+- **Multi-instance per engine and an MCP server** — future-additive, not v1.
+- **The node's error list** — owned by `nvpair-errors`, which holds it as in-memory session state; this service only emits `errors:report` / `errors:clear`.
+
+## 3. Key Use Cases
+- **Install an engine, user-mode**: `engine:install {engine:"ollama"}` downloads the per-OS user-scoped package (Windows/Linux standalone archive extracted into a user dir; macOS app bundle — never an elevated `Setup.exe` or `curl | sh`), checksum-verifies, extracts, re-detects.
+- **Run lifecycle**: `engine:start` / `engine:stop` / `engine:restart` / `engine:status`, with readiness and health probes against the engine's loopback port.
+- **Run a declared action**: `engine:action {engine, action, params}` → the manifest-declared HTTP call to the engine's loopback control API (e.g. `127.0.0.1:{port}/api/pull`). (Methods, notifications, and UI events all use the colon form `engine:*`, matching the POC UI and the `errors:*` notifications.)
+- **Onboard a new engine (no code)**: a vendor adds `engines/<vendor>.json`; the generic runner exposes their lifecycle + actions immediately.
+- **Edge case — already installed**: detect short-circuits install (idempotent).
+- **Edge case — checksum mismatch**: install fails before `run`, is reported, and never executes an unverified payload.
+- **Edge case — readiness timeout / crash**: failed readiness returns to Stopped; a later crash flips health and is reported.
+
+## 4. Open Questions / Risks
+- **`engine:*` method stability**: the Broker forwards the namespace verbatim; evolve it additively and preserve `engine:get-installed` as the installed-engine query.
+- **`severity` / `action` enums**: current wire values are `info|warning|error` and `dismiss|retry|none`; coordinate any future shared-enum expansion without changing existing values.
+- **Risk — auto-restart policy**: off by default (opt-in manifest flag); revisit once a supervisor / Warden-equivalent exists.
+- **Risk — dynamic port assignment**: manifest `port: 0` reserves the option; range/policy TBD (may move to a future supervisor).
+- **Risk — admin-only installers**: `mode: "admin"` is a flagged, refused exception, not the default; product direction is strictly user-mode.
+- **Risk — LAN-open inference bind (interim)**: inference engines default `runtime.bind` to `0.0.0.0` (ordinary engines stay loopback; a per-call `bind` re-pins). This is a deliberate, temporary exception to the loopback-only posture; narrow it once authenticated inference transport exists. The engine-manager `ec` control surface is already protected independently by pin-based mTLS.
+- **Future — declared/tunable env layer**: `runtime.env` is static today. A "declared tunables" layer (manifest-declared knobs, UI/broker-overridable per start) is worth adding; by env-richness the priority is Ollama → llama.cpp/Jan → vLLM (LM Studio / GPT4All are flags/settings-driven, not env). Related: `runtime.env` is process-mode-only — extending it to command-mode start commands is a deliberate, still-open choice. See `MANIFEST.md` → "Engine config reference".
+- **Model deletion where the vendor has no command (LM Studio)**: implemented via the generic **`remove_path`** action kind — a manifest-declared, param-templated path the runner removes with safety rails (must resolve under a declared allowed root, reject `..`/symlink escapes). LM Studio's `delete_model` uses `model_resolution: "lms-disk-path"` to map logical ids to on-disk files via `lms ls --json` before deleting under `{models_dir}`, then `restart_after` to bounce a running server: LM Studio answers `/v1/models` from an index built at startup and exposes no rescan, so clients keep being offered the deleted model until it restarts. Ollama deletes via `DELETE /api/delete` (no restart needed) and ejects via `unload_model` (`POST /api/generate` with `keep_alive: 0`).
+
+## 5. Requirements
+
+**Functional**
+- Load + validate per-engine JSON manifests (bundled + user dir); select the host `<goos>/<goarch>` block; resolve placeholders (`{bin}`, `{cli}`, `{port}`, `{download}`, `{install_dir}`).
+- Support both `process` (owned foreground) and `command` (daemon + control-CLI) runtimes; execute detect / install / uninstall / start / stop / restart / status / health and HTTP **or** CLI actions; emit `engine:*` results and notifications.
+- Emit `errors:report` / `errors:clear` on its stdio for the Broker to forward to `nvpair-errors`.
+
+**Non-functional**
+- Compiles and runs on Windows / macOS / Linux × amd64 / arm64.
+- **User mode, no runtime admin/sudo**; stdio / `--ipc` is the primary control channel, with an optional plain-HTTP model-list listener and a clustered pin-gated mTLS control listener; engines bind loopback by default, but a manifest's `runtime.bind` can open an inference engine to the LAN (Ollama ships `0.0.0.0` to serve the cluster), overridable per-call via `engine:start {bind}`; HTTPS-only downloads, checksum-verified when the manifest pins a `sha256`.
+- Fully testable end-to-end with no real engines, network, or installers in the test path.
+- Small, readable, minimal-dependency.
+
+## 6. Inputs and Outputs
+
+**Inputs** — from the orchestrator (`nvpair-ui-broker`) over stdio / `--ipc`, plus engine manifests from disk. Newline-delimited JSON-RPC 2.0 `engine:*` requests; manifest JSON (`engine`, `display_name`, `manifest_version`, `platforms{<os/arch>{detect, install, runtime}}`, `actions`). Every manifest is validated on load and rejected with a specific, human-readable error if malformed; manifests are read-only to this service.
+
+`EngineStatus` object (returned by `engine:status` and `engine:get-installed`):
+```json
+{
+ engine: string
+ display_name: string
+ installed: boolean
+ running: boolean
+ healthy: boolean
+ port: number
+}
+```
+
+`LogLine` object (entry in `engine:logs`):
+```json
+{ time: string, stream: "stdout" | "stderr", text: string }
+```
+
+Errors are emitted with the `nvpair-shared/errors.ServiceError` wire shape (`id`, `message`, `severity`, `action`, …), mirrored locally in `reporter.go` with identical JSON tags. `id` follows `engine-manager:<class>:<engine>`; the Broker stamps `nodeId` / `timestamp`.
+
+Example request:
+```json
+{"jsonrpc":"2.0","id":1,"method":"engine:install","params":{"engine":"ollama"}}
+```
+
+**Outputs** — JSON-RPC responses/notifications to the orchestrator; spawned engine OS processes; loopback HTTP to the engine's control API; `errors:report` / `errors:clear` notifications the Broker forwards to `nvpair-errors`. Lifecycle is not a hot path; error emits are best-effort (no-op if `nvpair-errors` is down). stdout writes are serialized so frames never interleave.
+
+Example error notification:
+```json
+{"jsonrpc":"2.0","method":"errors:report","params":{"id":"engine-manager:install-failed:ollama","message":"sha256 mismatch","severity":"error"}}
+```
+
+## 7. API / Interface Contract
+The stdio interface toward the local orchestrator (`nvpair-ui-broker`) is the primary surface. In addition, a clustered node serves a cluster-scoped remote-control surface (the `ec` service) directly over pin-based mTLS — engine-manager terminates that mTLS itself (see §7.2), the one place inter-node crypto lives here rather than in the orchestrator.
+
+### 7.0 Methods and notifications
+All traffic is JSON-RPC 2.0, newline-delimited over stdio (default) or `--ipc` (Unix domain socket / Windows named pipe).
+
+Requests (caller → service):
+
+| Method | Params | Result |
+|--------|--------|--------|
+| `engine:get-installed` | — | `{ engines: [EngineStatus] }` |
+| `engine:describe` | `{ engine }` | the engine's manifest |
+| `engine:status` | `{ engine }` | `EngineStatus` |
+| `engine:install` | `{ engine }` | `EngineStatus` (after install) |
+| `engine:uninstall` | `{ engine }` | `EngineStatus` (after removal) |
+| `engine:start` | `{ engine }` | `EngineStatus` (after readiness) |
+| `engine:stop` | `{ engine }` | `EngineStatus` |
+| `engine:restart` | `{ engine }` | `EngineStatus` |
+| `engine:action` | `{ engine, action, params }` | the engine's raw response |
+| `engine:logs` | `{ engine }` | `{ lines: [LogLine] }` |
+| `engine:errors` | — | `{ errors: [ServiceError] }` |
+| `engine:remote-get-installed` | `{ node }` | `{ engines: [EngineStatus] }` from the remote node |
+| `engine:remote-install` | `{ node, engine, start? }` | `{ opId, status }` after the remote install |
+| `engine:remote-pull-model` | `{ node, engine, model?, params? }` | `{ opId, result }` after the remote pull |
+| `engine:remote-load-model` | `{ node, engine, model }` | the remote action result |
+| `engine:remote-unload-model` | `{ node, engine, model }` | the remote action result |
+| `engine:remote-delete-model` | `{ node, engine, model }` | the remote action result |
+| `engine:remote-start` | `{ node, engine, port? }` | `EngineStatus` from the remote node (manifest `runtime.bind`; no per-call bind on the remote path) |
+| `engine:remote-stop` | `{ node, engine }` | `EngineStatus` from the remote node |
+| `shutdown` | — | `null` |
+| `log/set-level` | `{ level }` | `{ level }` |
+
+Notifications (service → caller): `ready{version}`, `engine:state-changed{EngineStatus}`, `engine:models-changed{engine, models}` (pushed when an engine's loaded-in-memory model set changes; `models` is the full `engine:models` shape incl. `loadedByEngine`), `engine:install-progress{engine, stage, percent}`, `engine:pull-progress{engine, op, stage, percent, message}` (live progress for a local model pull driven via `engine:action{action:"pull_model"}` — the local counterpart of `engine:remote-progress`), `engine:remote-progress{opId, node, engine, op, stage, percent, message}` (live progress relayed from a remote install/pull), and `errors:report` / `errors:clear` (consumed by `nvpair-errors` via the Broker). `install` / `start` / `stop` / `restart` / `action` / `remote-*` each run in their own goroutine so the read loop never blocks; their responses arrive when the op completes.
+
+Example `engine:install-progress` (stdout):
+```json
+{"jsonrpc":"2.0","method":"engine:install-progress","params":{"engine":"ollama","stage":"downloading","percent":42}}
+```
+
+Example `engine:pull-progress` (stdout):
+```json
+{"jsonrpc":"2.0","method":"engine:pull-progress","params":{"engine":"ollama","op":"pull","stage":"pulling","percent":62,"message":"pulling"}}
+```
+
+### 7.1 Versioning
+- `engine:*` method names are namespaced and additive — new methods, never breaking changes to existing ones.
+- `manifest_version` gates manifest-schema evolution: unknown optional fields are ignored (backward-compatible growth); a version higher than supported is rejected.
+
+### 7.2 Remote engine management (the `ec` surface)
+With `--control-port` and a clustered `--cluster-dir`, engine-manager serves a cluster-scoped remote-control surface over pin-based mTLS (`nvpair-shared/clustertrust`): it presents this node's cluster leaf, requires a client cert, and `403`s any caller that isn't a byte-for-byte pinned cluster peer. The listener is bound whenever `--control-port` is set and admits callers by live membership — its leaf is resolved per handshake, so an unclustered node presents none and every handshake is refused — so no restart is needed on `cluster:identity-changed`; the broker registers `ec` whenever a cluster dir is configured. Routes under `/v1`: `GET /engines`, streaming `POST /engines/install` and `/models/pull` (chunked NDJSON — zero+ `{"type":"progress"}` frames then one terminal `{"type":"result"}`/`{"type":"error"}` frame), non-streaming `POST /models/{load,unload,delete}`, and non-streaming `POST /engines/{start,stop}` returning `EngineStatus`.
+
+The `engine:remote-*` methods are the client half: engine-manager resolves the target `node` in an `ec` peer directory (fed by its own `discovery:subscribe{services:[ec]}` to the broker relay), dials the peer's `ec` surface with the same pinned identity, relays each streamed progress frame up as `engine:remote-progress` (keyed by a minted `opId`), and settles the request on the terminal frame. Remote install/pull run for the operation's full duration (no broker-imposed timeout); remote stop and model unload/delete are fast request/response, remote Ollama model load uses the readiness-sized response budget, and remote start waits for the engine's bounded readiness result. They error if this node isn't clustered or the target isn't a pinned peer.
+
+## 8. Dependencies
+- **Upstream**: the orchestrator that spawns it and forwards `engine:*` (`nvpair-ui-broker`).
+- **Downstream**: `nvpair-errors` (via the Broker's `errors:report` / `errors:clear` forwarding); the managed engine processes.
+- **External**: engine vendors' download URLs (HTTPS; checksum-pinned when a `sha256` is set, else HTTPS-only with a warning); first-party `nvpair-shared/applog` (logging + `log/set-level`) and `nvpair-shared/clustertrust` (pin-based mTLS). The `nvpair-shared/errors` wire shape is mirrored locally with identical JSON tags. No third-party runtime services.
+
+## 9. Data Ownership
+- **Owned**: the in-memory engine registry (parsed manifests + per-engine runtime state) and per-engine log/error ring buffers — transient only.
+- **Source of truth**: no — `nvpair-errors` owns the node's error list (in memory, for the session); model inventories belong to the engines; manifests on disk are authored elsewhere.
+- **Storage**: in-memory; manifests read from the per-user data dir's `engines/*.json` (`%LocalAppData%\Nvidia Corporation\Personal AI Router` on Windows, `~/.config/Nvidia Corporation/Personal AI Router` on Linux, `~/Library/Application Support/Nvidia Corporation/Personal AI Router` on macOS) plus bundled `manifests/*.json`. No database.
+
+## 10. Design Constraints
+- **Performance**: control plane, not inference; sub-second RPCs except install (network-bound) and start (bounded by the readiness timeout).
+- **Scalability**: a handful of engines per node; one managed instance per engine in v1.
+- **Reliability**: best-effort; readiness + health probes; automatic restart on crash is planned but **not yet implemented** (see §4); install is one-shot and idempotent (detect short-circuits).
+- **Security**: **user mode only — no admin/sudo at runtime** (escalation reserved for product install time); both optional LAN listeners terminate pin-based mTLS and reject unpinned peers — the read-only model-list listener (`em`) because a node's model inventory is cluster data, and the `ec` control listener because its routes are privileged; `em` additionally serves plaintext on loopback only, for this node's own scanner; engines bind loopback by default, but a manifest's `runtime.bind` may open an inference engine to the LAN (Ollama defaults to `0.0.0.0`, overridable per-call); downloads are HTTPS-only (plain HTTP only from loopback) and checksum-verified before execution when the manifest pins a `sha256` (an unpinned fetch is HTTPS-only with a loud warning, like a `script` install).
+- **Compliance**: no PII; payloads carry engine/model identifiers and error messages only.
+
+## 11. Assumptions
+- The orchestrator owns the stdio/IPC pipe and is the only peer; on parent exit (stdin EOF) the service shuts down cleanly — no reconnect or buffering.
+- Manifests are either well-formed (validated) or rejected; authors keep `engine:*` and manifest shapes stable per the versioning rules.
+- Engines bind loopback unless the manifest's `runtime.bind` opts otherwise (inference engines default to `0.0.0.0`; a per-call `bind` overrides); the engine's own startup banner is not trusted — the readiness probe confirms the actual bind.
+- `nvpair-errors` is best-effort; its absence degrades to local logs only.
+
+## 12. Failure Modes and Mitigations
+- **Download / checksum failure on install**: engine stays NotInstalled. → Fail fast before `run`; `engine:install-progress` error + `errors:report` (`engine-manager:install-failed:<engine>`); never execute an unverified payload.
+- **Engine fails its readiness probe**: start never reaches Running. → Bounded ready timeout → back to Stopped; structured error; no half-started state.
+- **Engine process crashes**: engine unavailable. → A watcher flips state, emits `engine:state-changed` + `errors:report` (`engine-manager:exited:<engine>`); the parent's supervisor reports if the *manager itself* dies. (Automatic restart is planned — see §4 — not yet implemented.)
+- **`nvpair-errors` unavailable**: failures absent from the node's error list. → The Broker no-ops the forward; local applog + ring buffers still hold everything.
+- **Invalid / unknown-OS manifest**: that engine is unusable. → Reject at load with a specific error; other engines unaffected.
+
+## 13. Observability
+- **Logging**: structured `slog` to stderr via `nvpair-shared/applog` (captured by the parent's debug panel); per-engine stdout/stderr ring buffers; key events — install fetch/verify/run outcomes, start/ready/stop transitions, health flips, action invocations, every failure.
+- **Metrics**: lightweight in-process counters (installs, starts, failures, health transitions per engine), surfaced via `engine:status` and `engine:errors`; no separate metrics endpoint in v1.
+- **Alerts**: surfaced through the errors pipeline — `errors:report` for install/start/health failures and manager crashes; the UI's error list is the alerting surface for v1.
+
+## 14. Sample usage
+The operator opens the UI; the Broker calls `engine:get-installed`, which returns each manifest's `EngineStatus` (e.g. Ollama `installed:true, running:false`). To set up a missing engine, the Broker sends `engine:install {engine:"ollama"}`: the service downloads the per-OS user-scoped package, checksum-verifies it, runs it user-mode, and re-detects — progress streaming as `engine:install-progress` notifications.
+
+The operator starts it: `engine:start {engine:"ollama"}` resolves the manifest runtime (`OLLAMA_HOST` = `{host}:{port}`, `{host}` from `runtime.bind` defaulting to `0.0.0.0`; per-call `port`/`bind` override either), spawns the process, and waits for the readiness probe before reporting `running:true, healthy:true` in the response and an `engine:state-changed` notification. A periodic health probe keeps the state current; an unexpected exit emits `engine:state-changed` + `errors:report`. If something is already serving the port, `start` **adopts** it instead of spawning a duplicate.
+
+The operator stops it: `engine:stop {engine:"ollama"}` signals a process the service owns. For an **adopted** engine (no owned process), it resolves the PID bound to the port and terminates it only when that process is running the binary we manage — reclaiming an orphan a prior run left on our own managed port; a genuinely foreign listener (a different image on a different port) is declined with an error naming its PID and image. A user-initiated `stop` records the OFF intent regardless (even when the RPC returns an error), so the health loop and restore-on-restart don't flip the engine back on — clients must not treat a stop error as proof the OFF choice was discarded. The cluster `ec` stop endpoint shares this semantics and may return HTTP 500 while OFF is persisted.
+
+The operator pulls a model: `engine:action {engine:"ollama", action:"pull_model", params:{name:"llama3.2"}}` issues the manifest-declared `POST 127.0.0.1:{port}/api/pull`. Because the action is `pull_model`, the request is routed through the streaming pull path (not the buffered `engine:action` reader): each `/api/pull` status line is emitted as an `engine:pull-progress` notification — so a local pull shows live download progress just like a remote pull's `engine:remote-progress` — and the request settles with the pull's terminal result line. Frames are coalesced (only a change in `stage` or `percent` is emitted) so a chatty engine that streams many byte-progress lines per layer doesn't flood subscribers. The engine's terminal `{"status":"success"}` surfaces as a `stage:"success"` frame; a **failed** pull emits a terminal `stage:"error", percent:-1, message:<why>` frame in addition to the JSON-RPC error, so a UI whose synchronous call already timed out on a long download still converges off "pulling". A CLI-driven pull (LM Studio's `lms get`) has no line-level progress, so it emits one `stage:"pulling"` marker and returns the command's result. On `shutdown` (or stdin EOF) the service stops every running engine first, so none are orphaned.
+
+## 15. Current integration / wiring
+
+The engine manager builds standalone (`go build ./...`) and is tested end to
+end over stdio. Current product wiring is:
+
+1. `build.bat` and `build.sh` build the version from `versions.json` and stage
+ the binary in the repository-root `build/bin/` bundle.
+2. `installer/nvpair-setup.nsi` bundles the Windows binary and owns the local
+ subnet firewall rules for its model-list and cluster-control listeners.
+3. `nvpair-ui-broker` supervises the process, relays its `engine:*` JSON-RPC
+ surface, forwards engine events and errors, and registers its applicable
+ discovery services.
+4. The bundled graphical UI, `nvpair-tui`, and other clients use the broker
+ contract rather than owning engine-manager process wiring. Product packaging
+ places the graphical UI alongside the broker and workers in the same
+ installation directory.
+5. `nvpair-engine-manager/README.md`, `nvpair-ui-broker/README.md`, and the
+ cross-process tests are the current architecture, protocol, and
+ integration references.
+
+The retired desktop wiring is intentionally omitted; its implementation record
+remains available in Git history and is not part of the current architecture.
diff --git a/services/nvpair-job-scheduler/spec.md b/services/nvpair-job-scheduler/spec.md
new file mode 100644
index 0000000..ee31151
--- /dev/null
+++ b/services/nvpair-job-scheduler/spec.md
@@ -0,0 +1,446 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Microservice: Job Scheduler (`nvpair-job-scheduler`)
+
+> **Status: implemented.** House spec style (`nvpair-cluster-manager`,
+> `nvpair-workload-manager`, `nvpair-engine-manager`). Current policy decisions and
+> residual risks are recorded in §4.
+
+## 1. Purpose
+Decides **where inference should go**. On every accepted workload, discovery, or
+effective GPU-pressure change, with a periodic timer as reconciliation, the Job
+Scheduler ranks the cluster's nodes by total pending work plus GPU pressure. It
+emits that node-wide order, pending count, and pressure so the Broker can push the
+snapshot to the matching local proxy (`ollama-proxy`, `lmstudio-proxy`). Before
+forwarding, a proxy atomically adds its own not-yet-observed reservations and
+chooses the least-busy capable node; its existing failover walks the remaining
+candidates.
+
+It is a **policy component**, not a data plane: it never sees inference traffic,
+never talks to the proxies directly, and owns no durable state. The initial policy
+uses a deliberately coarse, smoothed GPU signal; richer policies such as VRAM
+capacity, model locality, latency, and affinity can grow later behind the same
+"emit an ordered list" contract.
+
+## 2. Scope
+**In scope**
+- Compute one ordered priority list from the discovered-node set (ranking universe),
+ cluster workload picture, and fresh maximum-GPU utilization.
+- Recompute immediately after a meaningful workload, discovery, or pressure
+ update, and periodically as a reconciliation and telemetry-aging fallback.
+- **Emit** the order and ranks to the Broker (`schedule:priority`) for each
+ engine-specific proxy contract when that engine snapshot changes.
+
+**Out of scope**
+- **Serving/forwarding inference traffic** — the proxies' job; the scheduler only
+ says which order to prefer.
+- **Talking to the proxies / tracking their liveness** — the Broker (which already
+ supervises them) fans lists out, no-ops for an absent proxy, and re-pushes on
+ restart (§7.4). The scheduler holds no proxy-availability state.
+- **Owning the workload catalog** — produced by the proxies, relayed by
+ `nvpair-workload-manager`; the scheduler is a read-only consumer (§4).
+- **mDNS / a network listener** — like `nvpair-engine-manager`, stdio/`--ipc` only, no
+ port. It *reads* the Broker's discovery snapshot but does no browsing/advertising.
+- **Cross-node coordination** — each node's scheduler ranks the cluster from its own
+ view; no election or shared schedule (§4 risk).
+
+## 3. Key Use Cases
+- **Immediate rebalance**: after each accepted workload transition, count all
+ pending (queued+running) workloads per node, sort ascending, and emit if either
+ the order or counts changed. Requests arriving after the feedback reaches a
+ proxy start from that authoritative snapshot.
+- **Simultaneous local burst**: before each auto-routed inference forward, the
+ proxy atomically increments a local reservation for its chosen node. Concurrent
+ requests therefore see one another even before workload feedback completes.
+- **Cross-engine contention**: an Ollama workload and an LM Studio workload both
+ consume the destination node's execution resources, so either one changes both
+ engine outputs.
+- **Periodic reconciliation**: the runtime-adjustable timer recomputes the same
+ order as a safety net even when no fresh event arrives.
+- **Load shifts**: as a node drains it rises toward the top; as it fills it sinks; a
+ newly discovered node starts at count 0 and sorts to the top.
+- **No workload data yet**: all nodes rank equal → the stable tie-break (§7.2) gives
+ a deterministic list, not thrash.
+- **GPU pressure changes**: smooth fresh utilization into coarse pressure bands;
+ invalid, missing, or stale telemetry receives a neutral penalty rather than
+ looking idle.
+- **Proxy down / manual pin**: both handled downstream — the Broker drops/replays
+ the push for an absent proxy (§7.4); a user `node/select` pin outranks the list
+ until cleared (§7.3). Either way the scheduler keeps emitting.
+
+## 4. Decisions / Risks
+- **Workload source (decided — broker fan plus restart baseline).** The Broker fans
+ every accepted `workloads:upsert`/`workloads:remove` to the scheduler, which keeps
+ an active-only in-memory catalog keyed by
+ `(originatedFrom, engine, runId, id)` (the same global identity the broker's store
+ and workload-manager use — the bare `(originatedFrom, id)` collides across
+ concurrent engines and proxy restarts). On scheduler spawn/restart the Broker
+ replays its authoritative active snapshot as ordinary upserts before the
+ discovery baseline, then resumes live fanout. No workload-manager change or new
+ wire method is required.
+- **Node universe (decided — the Broker's discovery stream).** Since the scheduler
+ no longer asks the proxies for node lists (§7.4), it ranks the nodes from the
+ `discovery:nodes-changed` stream the Broker fans to it (with a full snapshot pushed
+ on spawn as the baseline). This includes **idle nodes** (zero workloads) so
+ they rank at the top. Each proxy applies the subset it can route to and ignores
+ the rest (§7.1); a proxy-only manual node absent from discovery is handled as an
+ unlisted fallback (§7.1).
+- **GPU pressure (decided — EWMA, bands, freshness).** The broker feeds the maximum
+ utilization across a node's GPUs. The scheduler uses a 0.35 EWMA, pressure bands
+ 0/1/2/3 at 40%/70%/85%, downward hysteresis at 35%/65%/80%, and a 10-second
+ freshness limit. Invalid, missing, and stale telemetry contributes neutral
+ pressure 1. A fresh stream after a gap starts a new EWMA.
+- **Cold-start / tie-break (decided — pressure then stable identity).** Rank by
+ `pending + gpuPressure`, then lower pressure, then `hostUuid`. A fixed final key
+ makes equal-load nodes deterministic; nodes with no telemetry all receive the
+ same neutral pressure and collapse to UUID order.
+- **Manual pin precedence (decided — manual pin wins).** A user `node/select` pin
+ overrides the list; the list governs only auto routing (§7.3).
+- **`node/set-priority` proxy semantics (decided — GPU-aware reservations).**
+ Both proxies store the ordered nodes and optional ranks. For auto-routed
+ model-bearing inference they atomically minimize
+ `rank.pending + rank.gpuPressure + localReservations` within the best
+ model-eligibility tier,
+ using scheduler order as the tie-break. They retain known unlisted nodes as
+ fallbacks and treat an empty list as default auto order. A nodes-only payload
+ remains valid and supplies a zero baseline for backward compatibility.
+- **Reconciliation interval (decided — 1 s default, runtime get/set).** Default **1 s**
+ (`--interval`), read/changed live via `scheduler:get-interval` /
+ `scheduler:set-interval`, clamped to a **200 ms** floor (§7.5).
+ Workload and discovery events do not wait for this timer; emit-only-on-snapshot-
+ change plus the stable tie-break keep timer recomputes from churning.
+- **Pending-count (decided — node-wide).** *Pending* = `queued` or `running`
+ (`completed`/`failed` excluded; `initializing` never transmitted), regardless of
+ engine. Counted by **`scheduledOn`** (where work runs), not `originatedFrom`. A
+ workload with no `scheduledOn` is unplaced and counts toward no node.
+- **Identity alignment (decided).** Discovery `hostUuid`, proxy candidate ids, and
+ workload `scheduledOn` use the same stable UUID namespace. A malformed or legacy
+ `scheduledOn` matching no discovered node contributes to no rank, so mismatch
+ degrades ranking quality but never misroutes.
+- **Risk — divergent views / thundering herd.** Each node ranks from its own
+ eventually-consistent view, so two may briefly steer work to the same idle node.
+ Acceptable for this feedback policy; local `workload:started` events trigger an
+ immediate rerank, while peer views converge through workload-manager relay.
+- **Reservation reconciliation (decided — snapshot reset).** Each delivered
+ snapshot replaces the proxy's baseline and clears its optimistic deltas; the
+ scheduler snapshot is authoritative. Reservations are taken under one short
+ mutex before forwarding, so requests within one proxy cannot select from the
+ same stale local state. A reservation that fails over is harmless: it pushes the
+ failed first choice down locally, while the re-pointed workload event corrects
+ the next authoritative snapshot.
+- **Risk — stale/lagging remote views.** Peer ranking trails reality by relay
+ latency; workload-manager anti-entropy and periodic scheduler reconciliation make
+ it self-correcting.
+
+## 5. Requirements
+
+**Functional**
+- Accept `scheduler:get-status`, `scheduler:get-interval`, `scheduler:set-interval`,
+ `scheduler:tick`, `log/set-level`, and `shutdown` over `stdin`/`--ipc` and return
+ JSON-RPC results (§7.0).
+- Keep three live in-memory views from Broker streams: the workload catalog
+ (`workloads:*`), GPU telemetry (`scheduler:telemetry`), and the node universe
+ (`discovery:nodes-changed`).
+- After each meaningful input change, and on a fixed reconciliation interval
+ (default 1 s, runtime-adjustable), compute one node-wide GPU-aware order (§7.2)
+ and publish it through both engine outputs. **Emit `schedule:priority` only when
+ its order, pending counts, or pressure changed** (a forced `scheduler:tick`
+ re-emits regardless).
+- Emit `errors:report` / `errors:clear` for the Broker to forward to `nvpair-errors`
+ on an internal fault worth surfacing (§13).
+
+**Non-functional**
+- No network listener, no mDNS, no port — stdio/`--ipc` only.
+- Never addresses a proxy; all delivery/liveness/resync is the Broker's (§7.4).
+- Stateless across restarts; recomputed from live inputs.
+- A fault on one engine must not block the other or crash the loop.
+- Windows / macOS / Linux × amd64 / arm64. Serialize `stdout` so frames never
+ interleave.
+
+## 6. Inputs and Outputs
+
+**Inputs** (Broker → scheduler over `stdin`/`--ipc`): JSON-RPC requests (§7.0) and
+three fanned notification streams — `workloads:*` (workload picture),
+`scheduler:telemetry` (GPU utilization), and `discovery:nodes-changed` (node
+universe), self-accumulated into in-memory views.
+
+It reads only `id`, `engine`, `runId`, `state`, `originatedFrom`, `scheduledOn`
+from the `Workload` object ([WM spec §6](../nvpair-workload-manager/spec.md)), and
+only `hostUuid` from each discovered node
+([broker `discovery:get-nodes`](../nvpair-ui-broker/README.md)). Telemetry carries
+`hostUuid`, maximum `gpuUtilizationPercent`, `telemetryValid`, and `msSince`.
+
+`NodeRank` (internal, surfaced in `scheduler:get-status`):
+```json
+{
+ id: string // stable node hostUuid
+ pending: number // queued+running workloads scheduledOn this node, all engines
+ gpuPressure: number // coarse 0–3 pressure; unknown/stale is neutral 1
+ rank: number // 0-based position (0 = highest priority)
+}
+```
+
+**Outputs** (scheduler → Broker): JSON-RPC results; a `schedule:priority`
+notification per engine when its rank snapshot changes; `errors:report` /
+`errors:clear`. No inference traffic and no requests addressed to other workers.
+
+```json
+{"jsonrpc":"2.0","method":"schedule:priority","params":{"engine":"ollama","nodes":["MY-PC","LAB-DESK-B","GPU-RIG"],"ranks":[{"id":"MY-PC","pending":0,"gpuPressure":0,"rank":0},{"id":"LAB-DESK-B","pending":1,"gpuPressure":1,"rank":1},{"id":"GPU-RIG","pending":3,"gpuPressure":3,"rank":2}]}}
+```
+
+## 7. API / Interface Contract
+
+A single local interface toward the Broker (no inter-node interface). The Broker
+sends requests and fans three streams; the scheduler answers requests and emits
+`schedule:priority` notifications the Broker acts on. It never sends the Broker a
+*request*. Newline-delimited JSON-RPC 2.0 over stdio (default) or `--ipc`.
+
+### 7.0 Methods and notifications
+
+Requests (Broker → scheduler):
+
+| Method | Params | Result |
+|--------|--------|--------|
+| `scheduler:get-status` | — | `{ interval_ms, engines: { ollama: EngineSchedule, lmstudio: EngineSchedule } }` |
+| `scheduler:get-interval` | — | `{ interval_ms }` |
+| `scheduler:set-interval` | `{ interval_ms }` | `{ interval_ms }` — live; clamped to the floor (§7.5); effective next tick |
+| `scheduler:tick` | — | `{ ticked: true }` — force an immediate recompute + re-emit (tests/debug) |
+| `log/set-level` | `{ level }` | `{ level }` |
+| `shutdown` | — | `null` |
+
+`EngineSchedule`:
+```json
+{
+ engine: string // "ollama" | "lmstudio"
+ emitted: [NodeRank] // last order emitted (empty if none yet)
+ lastEmittedAt: number // epoch ms; 0 if never
+}
+```
+
+Notifications:
+
+| Method | Direction | Params | Meaning |
+|--------|-----------|--------|---------|
+| `schedule:priority` | scheduler → Broker | `{ engine, nodes: [string], ranks?: [NodeRank] }` | New GPU-aware priority snapshot; Broker delivers it to the matching proxy. Emitted only on snapshot change (or forced tick). |
+| `errors:report` / `errors:clear` | scheduler → Broker | `ServiceError` / `{ id }` | Errors pipeline (§13). |
+| `workloads:upsert` / `workloads:remove` | Broker → scheduler | (WM shapes) | Workload stream (§6). |
+| `scheduler:telemetry` | Broker → scheduler | `{ hostUuid, gpuUtilizationPercent, telemetryValid, msSince }` | Compact maximum-GPU telemetry stream (§6). |
+| `discovery:nodes-changed` | Broker → scheduler | `[AvailableNode]` | Node-universe stream (§6). |
+
+### 7.1 The `node/set-priority` proxy contract (delivered by the Broker)
+
+The new proxy method the *Broker* calls, carrying the scheduler's order (defined
+proxy-side, §4). The scheduler never calls it — it only emits `schedule:priority`.
+
+- **Params**: `{ nodes: [string], ranks?: [NodeRank] }` — ordered node ids plus
+ their authoritative pending counts and GPU pressure.
+- **Semantics** (proxy): for each auto-routed model-bearing inference request,
+ atomically choose the minimum authoritative pending count plus GPU pressure
+ plus local reservations, then increment that node's reservation before
+ forwarding.
+ Consider only scheduler-listed nodes in the best available model tier; use
+ scheduler order as the tie-break. **Unknown ids are ignored.** A **known node
+ not in the list** remains a lowest-priority fallback, and an **empty list**
+ reverts to the proxy's default auto heuristic.
+- **Result**: the reply shape is defined proxy-side, not here.
+- **Precedence**: a user `node/select` pin overrides the list (§7.3).
+
+### 7.2 Ranking algorithm
+
+Let `D` = current discovered-node `hostUuid`s:
+
+1. **Count**: from the active workload catalog, keep workloads with
+ `state ∈ {queued, running}` and `scheduledOn ∈ D`, regardless of engine; group
+ by `scheduledOn` → `pending[id]`. Every `id ∈ D` not present gets `0` (idle
+ nodes included).
+2. **Pressure**: for each valid sample with effective age
+ `msSince + elapsedSinceReceipt ≤ 10 s`, clamp utilization to 0–100 and update
+ an EWMA with alpha 0.35. Map it to pressure 0 below 40%, 1 below 70%, 2 below
+ 85%, else 3. A band drops only below 35%/65%/80%. Invalid, missing, or stale
+ telemetry yields pressure 1; the first fresh sample after a gap resets the
+ EWMA. The input is the maximum across GPUs, deliberately conservative.
+3. **Sort** `D` ascending by `pending[id] + gpuPressure[id]`, then
+ `gpuPressure[id]`, then `id`.
+4. **Publish** the shared snapshot through
+ `schedule:priority {engine, nodes, ranks}` for each supported engine. Emit only
+ when its order, pending counts, or pressure differ from the last emission (a
+ forced tick re-emits). Delivery, liveness, and restart-resync are the Broker's
+ (§7.4).
+
+`scheduledOn` (not `originatedFrom`) is the key: we care where work runs, not where
+it came from. Engine remains part of workload identity and selects the downstream
+proxy output, but it does not partition the load metric: Ollama and LM Studio
+normally contend for the same node-level GPU, VRAM, CPU, and memory. Until resource
+affinity is observable, total node queue depth is the conservative signal.
+
+### 7.3 Selection-state (proxy side, for reference)
+
+Effective target: `manual pin (node/select)` → else
+`pending + gpuPressure + local reservations within the priority list` → else
+`default auto`. A snapshot delivered while a pin is active is stored but doesn't
+move traffic; clearing the pin activates the most-recent snapshot.
+`node/selection-changed` fires only for the active target.
+
+### 7.4 Emit-and-fan-out
+
+The scheduler emits `schedule:priority` **notifications**; the Broker owns
+everything downstream. This mirrors an existing pattern — the Broker already
+consumes the proxy's `workload:*` and routes it to the workload-manager
+(`routeProxyWorkload`); here it consumes `schedule:priority` and routes it to the
+proxies. **Not** a new "originated request" direction. Broker responsibilities
+(implemented in `nvpair-ui-broker`, §15):
+- **Fan-out**: on `schedule:priority`, call `node/set-priority` on the matching
+ supervised proxy; an absent proxy → logged no-op.
+- **Cache + restart-resync**: keep the last complete snapshot per engine and
+ re-push it when a proxy (re)spawns (the Broker owns the proxy lifecycle +
+ `ready`, so it knows when one came back empty).
+- **Feed and seed the streams**: on scheduler spawn, replay active workloads,
+ replay cached telemetry, then send discovery so the first non-empty ranking has
+ all baselines. Resume live workload, telemetry, and discovery fanout afterward.
+
+### 7.5 Local-interface errors
+
+Standard JSON-RPC 2.0. Negative outcomes are normal `result`s; protocol problems
+use `error`:
+
+| Code | Raised when |
+|------|-------------|
+| `-32700` / `-32600` / `-32601` | unparseable / non-JSON-RPC / unknown method |
+| `-32602` | non-positive/non-numeric `interval_ms`, or unknown `log/set-level` level. Below the 200 ms floor is clamped and returned, not an error. |
+| `-32603` | unexpected internal failure |
+
+The scheduler issues no requests upward, so there are no relay-error paths on its
+side.
+
+### 7.6 Versioning
+- `scheduler:*` / `schedule:*` / `node/set-priority` names are namespaced and
+ additive — new capabilities are new methods.
+- The added `ranks` field is optional: older consumers continue using
+ `{engine,nodes}`, while current proxies use pending counts and GPU pressure for
+ local reservations.
+
+## 8. Dependencies
+- **Upstream**: the supervising parent — `nvpair-ui-broker` in practice
+ (supervisor-agnostic: any parent that speaks §7.0, feeds the three streams, and
+ delivers `schedule:priority` to the proxies).
+- **Downstream (via the Broker)**: `ollama-proxy`/`lmstudio-proxy` (receive
+ `node/set-priority`); `nvpair-errors` (receives `errors:*`). No direct link to any.
+- **Data sources (via the Broker)**: `nvpair-workload-manager` + proxies
+ (workloads), `nvpair-node-scanner` / manual nodes (discovery and GPU telemetry).
+- **External**: `nvpair-shared/applog`, `nvpair-shared/jsonrpc`, `nvpair-shared/errors`. No
+ third-party services, no network stack.
+
+## 9. Data Ownership
+- **Owned**: transient in-memory state only — the accumulated workload catalog,
+ discovered-node view, smoothed telemetry state, and last-emitted rank snapshot
+ per engine. Each proxy owns only its short-lived optimistic reservation deltas.
+- **Source of truth**: no. Workloads → proxies/WM; discovery and telemetry →
+ scanner/manual-nodes; the active routing decision → the proxy; delivery/caching
+ → the Broker. The scheduler owns only the policy computation.
+- **Storage**: none.
+
+## 10. Design Constraints
+- **Performance**: each accepted state change and periodic reconciliation is an
+ O(#nodes + #active workloads) count-and-sort plus at most two small
+ notifications. Terminal workloads are removed from the scheduler catalog.
+- **Scalability**: ~dozen nodes, low workload volume; small state.
+- **Reliability**: best-effort, self-correcting; event-driven updates minimize local
+ lag and the periodic pass reconciles the current view. Serialized `stdout`.
+ Proxy delivery reliability is the Broker's.
+- **Security**: no listener, no inter-node traffic. Payloads carry node ids,
+ workload metadata, and aggregate utilization only (no inference data, no PII);
+ ids are opaque.
+
+## 11. Assumptions
+- The parent owns the pipe; on `stdin` EOF the scheduler exits cleanly (no
+ reconnect/buffering).
+- The parent feeds the three streams and delivers `schedule:priority` to the proxies;
+ without them the scheduler runs but has nothing to rank / nowhere to land.
+- Discovery, proxies, and `scheduledOn` use the same stable `hostUuid` namespace.
+- Small cluster and modest control-plane event volume; immediate O(nodes + active
+ workloads) recomputation is inexpensive.
+
+## 12. Failure Modes and Mitigations
+- **Cold start / stale views**: → The Broker replays active workloads and cached
+ telemetry before the discovery baseline, then live deltas. Missing or stale
+ telemetry receives neutral pressure and stable UUID ordering.
+- **Proxy down / restarted**: not the scheduler's problem. → The Broker no-ops the
+ push and re-pushes the cached snapshot on return (§7.4).
+- **Rank thrash**: → EWMA, coarse bands, downward hysteresis, deterministic
+ tie-break, and emit only on pressure-relevant snapshot changes.
+- **Thundering herd** (§4): → local `workload:started` updates rerank immediately;
+ the periodic pass and peer relay reconcile eventual views.
+- **Interface severed** (`stdin` EOF / `stdout` `EPIPE`): → treat as shutdown; stop
+ the timer and exit. A new Broker spawns a fresh scheduler.
+- **Malformed frame**: → validate every envelope; JSON-RPC `error` for anything with
+ an `id`, drop-and-log uncorrelatable lines; never crash the loop.
+
+## 13. Observability
+- **Logging**: per-recompute outcome (trigger, node count, top ids + counts, emitted
+ vs. unchanged); view sizes; interval changes; startup/clean shutdown. Order
+ *changes* log at `info`.
+- **Status** (via `scheduler:get-status`): current interval and each engine's last
+ emitted ranks and emission time.
+- **Alerts** (errors pipeline): a workload, telemetry, or discovery stream gone
+ silent far longer than expected. Proxy-reachability alerting belongs to the
+ Broker.
+
+## 14. Sample usage
+The Broker spawns `nvpair-job-scheduler`, replays active workloads and telemetry,
+then sends discovery and resumes all three live streams. Discovery seeds
+`GPU-RIG`, `MY-PC`, `LAB-DESK-B`. Pending counts are `3`, `0`, `1` and GPU
+pressures are `3`, `0`, `1`, so combined loads are `6`, `0`, `2`. The scheduler
+emits `["MY-PC","LAB-DESK-B","GPU-RIG"]` for both engines. The Broker delivers
+each via `node/set-priority`; each proxy applies the subset it can route to.
+
+As load and smoothed pressure change, only a new pressure band, pending count, or
+order triggers another snapshot. If `ollama-proxy` is not supervised, the Broker
+drops the push and re-delivers once it is back — the scheduler is unaware.
+
+## 15. Process model, CLI, and build wiring
+
+**Process model.** A single Go binary speaking newline-delimited JSON-RPC 2.0 on
+stdio (`--ipc` for a Unix socket / Windows named pipe). No network listener, no
+mDNS. On Windows the parent hides the console via
+`syscall.SysProcAttr{HideWindow: true, CreationFlags: 0x08000000}`, like every
+other subprocess.
+
+**CLI flags**:
+- `--version` — print `main.Version` (ldflag-stamped from `versions.json`) and exit.
+- `--ipc <path>` — Unix socket / named pipe instead of stdio.
+- `--log-level <level>` — initial `applog` level; mutable via `log/set-level`.
+- `--interval <dur>` (default `1s`) — periodic reconciliation cadence; also
+ `scheduler:get-interval` / `scheduler:set-interval` at runtime. Workload and
+ discovery changes and effective pressure transitions recompute immediately
+ regardless of this setting.
+
+No flag carries node/cluster identity — the scheduler holds none.
+
+**Broker wiring** (`nvpair-ui-broker`):
+- a `--scheduler-path` flag (default `./nvpair-job-scheduler[.exe]`, optional/non-fatal),
+ spawned + supervised (auto-restart with crash surfacing);
+- replay active workloads and cached telemetry on scheduler spawn, send the
+ discovery baseline, then fan all three live streams to the child;
+- consume its `schedule:priority` and fan out to the proxies via `node/set-priority`,
+ caching the last snapshot per engine and re-pushing on proxy (re)spawn (§7.4) —
+ reuses the proxy `workload:*` → workload-manager routing pattern, not a new
+ direction;
+- forward its `errors:*` to `nvpair-errors`.
+
+**Build wiring**: `nvpair-job-scheduler` is one of the Go binaries in the product
+bundle. In the same change:
+- a `components.nvpair-job-scheduler` entry in `versions.json`, plus `installer` and
+ `product` bumps (see `VERSIONING.md`);
+- build + copy in **both** `build.bat` and `build.sh` (→ the repo-root
+ `build/bin/`), with the `-X main.Version=…` ldflag;
+- inclusion in `installer/nvpair-setup.nsi` and `bom.md` (no firewall rule — no
+ listener);
+- a bump declared in the pull request's release-intent block (see
+ `VERSIONING.md`);
+- the root `readme.md` binary inventory / architecture table.
+
+Launched on demand by `nvpair-ui-broker` (which expects workers as siblings in its CWD),
+so it must land in the same `bin/` dir.
diff --git a/services/nvpair-workload-manager/spec.md b/services/nvpair-workload-manager/spec.md
new file mode 100644
index 0000000..c00fb24
--- /dev/null
+++ b/services/nvpair-workload-manager/spec.md
@@ -0,0 +1,258 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Microservice: Workload Manager
+
+> **Implementation note (cluster membership is live):** the inter-node mTLS
+> described below is unconditional — there is no plain-HTTP personality on the
+> `wl` port — and membership is evaluated continuously rather than at startup.
+> The port is bound once and its server certificate is resolved per handshake, so
+> a node that belongs to no cluster presents no leaf and serves nothing, while a
+> node that joins mid-session starts serving pinned peers on the same listener
+> with no rebind and no restart. Outbound, the per-peer pinned client is resolved
+> at the start of every broadcast round, and a non-member broadcasts nothing.
+
+## 1. Purpose
+Tracks inference workloads cluster-wide as they are queued, executed, and retired, giving the customer the data to render cluster state and follow workloads across nodes.
+
+## 2. Scope
+**In scope**
+- Broadcast local workload events to peer nodes; relay peer events to the local Broker.
+- Maintain the broadcast target set from the consolidated discovery directory — subscribe for `wl` nodes through the Broker's discovery relay and rebuild the target set from each snapshot.
+
+**Out of scope**
+- Persistence and long-term memory — the Broker persists and tracks workload state; this service forwards transitions but stores none across sessions.
+
+## 3. Key Use Cases
+- **Broadcast a local event**: the Broker emits a `workload:*` lifecycle event (`workload:submitted`, `workload:started`, `workload:completed`, `workload:errored`) or `workloads:remove` on `stdin`; the Workload Manager broadcasts it to every discovered peer via `POST /v1/workloads/events` over mTLS.
+- **Relay a remote event**: on receiving a peer's `workload:*`, validate and deduplicate (by `(nodeId, Workload.id, state)`), then emit `workloads:upsert` on `stdout` so the Broker updates its catalog. A peer `workloads:remove` (deduplicated by `(nodeId, workloadId)`) is relayed as `workloads:remove` on `stdout`.
+- **Discover peers**: the Broker registers this node's `wl` port with the `nvpair-node-scanner` discovery daemon, which carries it on this node's single consolidated record; the Workload Manager subscribes for `wl` nodes and rebuilds the target set from each `discovery:nodes` snapshot the Broker relays, so a node joins the set when it appears in a snapshot and leaves when it is absent from the next one.
+- **Edge case — duplicate / re-broadcast events**: retries or re-broadcasts arriving more than once are deduplicated (`(nodeId, Workload.id, state)` for lifecycle, `(nodeId, workloadId)` for removals) so the Broker is updated at most once.
+- **Edge case — peer unreachable**: a target that is down, slow, or partitioned (crash, network split, laptop suspend) does not block others — broadcast runs concurrently with per-peer timeouts and bounded retries.
+
+## 4. Open Questions / Risks
+- **`initializing` state (open — needs third-party feedback)**: the enum value has no `workload:*` method, so it is never produced or transmitted as specified. Pending the Broker/inference-proxy team's confirmation whether it is a Broker-local pre-queue state only, or needs a new lifecycle method and broadcast path.
+- **`EngineType` values (open — needs third-party feedback)**: the valid `engine` set is undefined. Pending the inference-engine team's list, `engine` is treated as an opaque pass-through string (must be present and non-empty, value not validated).
+- **Risk — late joiners / no replay**: nodes discovered mid-session only get events broadcast after they appear in the target set; their view is incomplete until later events flow (by design).
+- **Risk — best-effort fan-out**: an unreachable peer misses events; temporary inconsistency until later events arrive or the Broker reconciles by timestamp.
+- **Risk — snapshot staleness**: the target set is only as current as the last `discovery:nodes` snapshot, so a departed node lingers as a target and a new node appears slowly, bounded by the discovery daemon's own liveness handling rather than by anything this service controls.
+- **Risk — dedup granularity**: keying on `(nodeId, Workload.id, state)` means a re-broadcast with the same key but updated metadata (e.g. a corrected `error`) is dropped, not merged.
+
+## 5. Requirements
+
+**Functional**
+- Accept local `workload:*` and `workloads:remove` notifications from the Broker over `stdin` (or a named pipe) and broadcast each to all discovered peers via `POST /v1/workloads/events`.
+- For each validated, deduplicated inter-node `workload:*`, emit `workloads:upsert` to the Broker (translated, not forwarded unchanged); for each inter-node `workloads:remove`, emit `workloads:remove` to the Broker (not re-broadcast).
+- Subscribe to the Broker's discovery relay with `discovery:subscribe` filtered to the `wl` service, and rebuild the broadcast target set from every `discovery:nodes` snapshot: take each peer's dialable address and `wl` port from its directory entry, skip entries advertising no `wl` port or no address, and exclude this node's own entry by `hostUuid` rather than by hostname. A snapshot carries the full filtered set and replaces the target set wholesale, so there are no per-node deltas to apply and a peer absent from a snapshot simply stops being a target.
+- Deduplicate inbound lifecycle events by `(nodeId, Workload.id, state)` and removals by `(nodeId, workloadId)`, using a configurable bounded LRU index (default ~10,000 entries, sized for session-scoped volume at ~dozen-node scale). `nodeId` is part of the key because `Workload.id` is only unique per node (§11) — keying on `id` alone would collide across nodes and silently drop a legitimate peer's event. This matches the `(nodeId, workloadId)` tuple the Broker uses as the global workload identity (§10).
+- Validate inbound payloads; reject malformed envelopes or unknown `method` values (`400 Bad Request`).
+
+**Non-functional**
+- Authenticate all inter-node traffic with mTLS, validating client and server certificates against the trusted node store; reject untrusted clients (`403 Forbidden`).
+- Stay stateless re: workload history — the Broker is the source of truth.
+- A failed broadcast to one peer must not block delivery to other peers or the local Broker.
+- Serialize `stdout` writes so frames never interleave; the Broker orders events per workload by `(nodeId, workloadId)` and timestamps.
+
+## 6. Inputs and Outputs
+
+**Inputs** — from the Broker over `stdin` / named pipe, or from peer nodes via HTTP REST. JSON-RPC 2.0 notification envelopes (`jsonrpc`, `method`, `params`); see §7 for transport details. Lifecycle methods carry `params.workloadInfo` (a `Workload`); `workloads:remove` carries `params.workloadId` (string) and an optional `params.originatedFrom` (string) that disambiguates which node's workload to remove (see §7.3 — additive field; absent on legacy senders, in which case dedup degrades to id-only keying).
+
+`Workload` object:
+```json
+{
+ id: string
+ model: string
+ engine: EngineType
+ state: WorkloadState
+ originatedFrom: string // Owner/origin node of the workload (its identity half of the (originatedFrom, id) global key). Distinct from scheduledOn, the node it was routed to.
+ scheduledOn?: string // Node the workload was routed to / scheduled on (where it actually ran), as opposed to originatedFrom (where it came from). Supplied by the Broker/proxy and passed through opaquely. Optional/additive (§7.3) — absent until a target is chosen (e.g. a still-queued workload:submitted).
+ createdAt: number
+ startedAt: number | null
+ completedAt: number | null
+ error: string | null
+ requesterId: string | null
+}
+```
+
+`WorkloadState` (enum): `"initializing" | "queued" | "running" | "completed" | "failed"`
+- Method → `state`: `workload:submitted` → `queued`, `workload:started` → `running`, `workload:completed` → `completed`, `workload:errored` → `failed`. `initializing` is a pre-queue state with no lifecycle method and is not transmitted (see §4).
+
+Validation: check every inbound envelope before processing. Inter-node and local interfaces both accept the four `workload:*` methods (with `params.workloadInfo`) and `workloads:remove` (with `params.workloadId`). Reject malformed/unknown-`method` payloads on the inter-node interface (`400`); drop-and-log on the local interface (never broadcast). Deduplicate inter-node lifecycle by `(nodeId, Workload.id, state)` and removals by `(nodeId, workloadId)`. Assume the Broker supplies well-formed notifications with epoch-millisecond timestamps.
+
+**Outputs** — to the Broker over `stdout` / named pipe, or to peers via HTTP REST. `workloads:upsert` on `stdout` after a remote `workload:*`; `workloads:remove` on `stdout` after a remote inter-node `workloads:remove`. Inter-node broadcast posts the same JSON-RPC notification to `POST /v1/workloads/events` (`200 OK` on success; see §7.2). No response on the local interface (notifications only); `stdout` writes are serialized so frames never interleave; inter-node delivery is best-effort (concurrent, per-peer timeouts, bounded retries).
+
+## 7. API / Interface Contract
+
+Two interfaces: a **local interface** toward the same-node UI Broker, and an **inter-node interface** toward Workload Manager instances on other nodes.
+
+### 7.0 Methods and notifications
+
+All traffic is JSON-RPC 2.0. The local interface uses `stdin`/`stdout` (or a named pipe); inter-node uses notifications on `POST /v1/workloads/events` (see §7.2). The Broker owns durable state — `workloads:get-initial` is a Broker concern, **not** part of this contract.
+
+| Name | Local (`stdin`) | Inter-node (`POST /v1/workloads/events`) | WM → Broker (`stdout`) |
+|------|------------|----------------------------------------|--------------------------------------|
+| `workload:submitted` | Broker → WM; broadcast | Peer → WM; → `workloads:upsert` | — |
+| `workload:started` | Broker → WM; broadcast | Peer → WM; → `workloads:upsert` | — |
+| `workload:completed` | Broker → WM; broadcast | Peer → WM; → `workloads:upsert` | — |
+| `workload:errored` | Broker → WM; broadcast | Peer → WM; → `workloads:upsert` | — |
+| `workloads:upsert` | — | — | After validated remote `workload:*` |
+| `workloads:remove` | Broker → WM; broadcast | Peer → WM; → `workloads:remove` | After validated remote `workloads:remove` |
+
+- **Inbound `workload:*` (Broker → WM)**: local-origin transitions to broadcast cluster-wide; `params.workloadInfo` is a full `Workload`. No response.
+- **`workloads:upsert` (WM → Broker)**: emitted for remote-origin lifecycle updates — each validated inter-node `workload:*` is translated (not forwarded) into an upsert. Not used on inter-node HTTP or Broker `stdin`. Params: `workloadInfo` copied unchanged from the peer event. Semantics: upsert into the Broker catalog by `Workload.id` (create if absent, replace if present) — the latest metadata/state, not a replay of the method name.
+- **`workloads:remove` (WM → Broker)**: emitted on `stdout` after a validated inter-node removal (same `(nodeId, workloadId)`), deduplicated so retries emit at most once; not re-posted to peers. Local-origin removals arrive on `stdin` and are broadcast over HTTP unchanged. Semantics: remove the workload by `(nodeId, workloadId)` from the Broker's view if present, else no-op. Inter-node handler returns `200 OK` once accepted/relayed (or deduplicated).
+
+Example `workloads:upsert` (`stdout`):
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "workloads:upsert",
+ "params": {
+ "workloadInfo": {
+ "id": "wl-1a2b3c",
+ "model": "llama-3-70b",
+ "engine": "trt-llm",
+ "state": "running",
+ "originatedFrom": "node-B",
+ "createdAt": 1716998400000,
+ "startedAt": 1716998401000,
+ "completedAt": null,
+ "error": null,
+ "requesterId": "req-42"
+ }
+ }
+}
+```
+
+Example `workloads:remove` (identical body inter-node and on `stdout`; `originatedFrom` is the optional disambiguator):
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "workloads:remove",
+ "params": {
+ "workloadId": "wl-1a2b3c",
+ "originatedFrom": "node-B"
+ }
+}
+```
+
+### 7.1 Local Interface (UI Broker ↔ Workload Manager)
+- Transport: `stdin` / `stdout` (or a named pipe); JSON-RPC 2.0 notifications only (no request/response).
+- **Inbound** (`stdin`): local `workload:*` lifecycle notifications and `workloads:remove`, for broadcast.
+ - `workload:submitted` — queued/submitted on this node
+ - `workload:started` — began executing
+ - `workload:completed` — finished successfully
+ - `workload:errored` — failed (may retry on another node)
+- **Outbound** (`stdout`): `workloads:upsert` after each validated remote `workload:*`; `workloads:remove` after each validated remote removal (see §7.0).
+- Params: lifecycle uses `params.workloadInfo`; `workloads:remove` uses `params.workloadId`.
+
+Example notification:
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "workload:submitted",
+ "params": {
+ "workloadInfo": {
+ "id": "wl-1a2b3c",
+ "model": "llama-3-70b",
+ "engine": "trt-llm",
+ "state": "queued",
+ "originatedFrom": "node-A",
+ "createdAt": 1716998400000,
+ "startedAt": null,
+ "completedAt": null,
+ "error": null,
+ "requesterId": "req-42"
+ }
+ }
+}
+```
+
+### 7.2 Inter-node Interface (Workload Manager ↔ Workload Manager)
+- Endpoint: `POST /v1/workloads/events`; port `14320` (TCP), the default this node listens on and registers as its `wl` port. Every peer is reached on the `wl` port carried in its own directory entry, which is `14320` unless that node was started with an override.
+- Protocol: HTTPS REST over mTLS; client and server certificates validated against the trusted node store.
+- Connections are **keep-alive and pooled per peer**, not per event. A sender holds a bounded set of long-lived connections per peer and reaps one after `clustertrust.PeerIdleTimeout`; the listener sets a strictly longer `IdleTimeout` (`clustertrust.PeerListenerIdleTimeout`) so the sender is always the side that discards a doubtful connection. This is normative, not an optimization: a handshake per event both starves the receiver and, without an idle bound on either side, pins a descriptor per connection for the life of the process.
+- A node broadcasts each local `workload:*` and `workloads:remove` to all discovered peers.
+- Body: JSON-RPC 2.0 notification — `workload:*` with `params.workloadInfo`, or `workloads:remove` with `params.workloadId` (and optional `params.originatedFrom`).
+- Responses: `200 OK` (accepted; lifecycle → `workloads:upsert`, removal → `workloads:remove` to the local Broker); `400 Bad Request` (malformed / unknown `method`); `403 Forbidden` (client cert absent or untrusted).
+- Idempotency: lifecycle by `(nodeId, Workload.id, state)`; removal by `(nodeId, workloadId)`.
+
+Example request (`POST /v1/workloads/events`):
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "workload:errored",
+ "params": {
+ "workloadInfo": {
+ "id": "wl-1a2b3c",
+ "model": "llama-3-70b",
+ "engine": "trt-llm",
+ "state": "failed",
+ "originatedFrom": "node-A",
+ "scheduledOn": "node-A",
+ "createdAt": 1716998400000,
+ "startedAt": 1716998401000,
+ "completedAt": 1716998402500,
+ "error": "CUDA out of memory",
+ "requesterId": "req-42"
+ }
+ }
+}
+```
+Response: `200 OK`.
+
+### 7.3 Versioning
+- URL path prefix (`/v1`) on the inter-node interface.
+- JSON-RPC `method` names are namespaced and additive — new event types are new methods, never changes to existing ones.
+- `Workload` schema changes are backward compatible (new fields optional, unknown fields ignored); breaking changes require a new version (`/v2`).
+
+## 8. Dependencies
+- **Upstream**: UI Broker — the parent process that launches the Workload Manager as a child and feeds it local events over `stdin`.
+- **Downstream**: local UI Broker (consumes `workloads:upsert` / `workloads:remove` on `stdout`); peer Workload Manager instances (receive broadcasts via `POST /v1/workloads/events`).
+- **External**:
+ - **mTLS trusted node store** — backs inter-node authentication; supplies certificates and trust anchors and is used to reject untrusted clients (`403`).
+ - **`nvpair-node-scanner` discovery daemon, via the Broker's relay** — the sole source of broadcast targets. It advertises this node's `wl` port on the node's single consolidated record and supplies the `discovery:nodes` snapshots the target set is rebuilt from (§5). The daemon's mDNS service name and TXT layout are its own internal contract; this service reads only the directory entries it is handed and never parses a record itself.
+ - **Multicast-capable network** — required by the discovery daemon's browse, not by this service directly. Where multicast is unavailable the daemon reports no peers, the snapshots are empty, and broadcast has no targets.
+
+## 9. Data Ownership
+- **Owned**: none durable — only transient in-memory state (the bounded dedup index and the discovered/target peer set). `Workload` entities are not owned.
+- **Source of truth**: no — the Broker is authoritative; this service is a stateless relay.
+- **Storage**: none — in-memory state is discarded on exit.
+
+## 10. Design Constraints
+- **Performance**: low event volume (lifecycle transitions, not telemetry); no end-to-end latency SLA, delivery is best-effort. Local forwarding writes serialized frames to `stdout`; inter-node broadcast is concurrent with per-peer timeouts.
+- **Scalability**: ~dozen-node cluster; each local event fans out to all peers. Only in-memory state is the bounded dedup index and target set.
+- **Reliability**: best-effort fan-out, no SLA. Concurrent per-peer broadcast with timeouts; retry transient failures with bounded exponential backoff, drop after max attempts (metric/alert; parameters implementation-defined). Serialized `stdout`; the Broker orders per workload by `(nodeId, workloadId)` and timestamps. No replay — peers reconcile via later events.
+- **Re-sync cadence is a cross-process contract.** The anti-entropy heartbeat re-asserts every *active* local-origin workload on every interval, indefinitely, and every re-assertion is tagged so the receiver's state dedup does not swallow it. A consumer is entitled to treat prolonged silence about a workload it believes active as evidence that the workload is finished or the origin is gone — `nvpair-ui-broker` does exactly that in its staleness sweep, keyed to a multiple of this interval. Lengthening the interval beyond that consumer's budget, or dropping the re-assertion tag, therefore causes peers to retire live work; change both sides together.
+- **Security**: all inter-node traffic mTLS-authenticated against the trusted node store; reject and log untrusted callers (`403`) with the presented identity; monitor cert expiry; keep the trust store hot-reloadable. Payloads carry workload metadata only (model, state, node IDs, errors) — no request/response data or PII. `requesterId`, `nodeId`, and `Workload.id` are opaque system-generated identifiers (not PII).
+- **Compliance**: workload information must contain no PII.
+
+## 11. Assumptions
+- The Broker is always the parent process: it spawns the Workload Manager, writes `workload:*` / `workloads:remove` to `stdin`, and consumes `workloads:upsert` / `workloads:remove` from `stdout`. If the Broker exits, the manager shuts down cleanly — no reconnect or buffering.
+- The Broker is the source of truth; local notifications are well-formed JSON-RPC with epoch-ms timestamps.
+- Small cluster (~dozen nodes), low event volume; peers mutually authenticated via mTLS. New nodes get only events broadcast after discovery — no historical replay.
+- Each node assigns `Workload.id` from a monotonic per-node counter (e.g. creation-time Unix ms); cross-node ordering comes from the Broker via the `(nodeId, workloadId)` tuple and timestamps.
+
+## 12. Failure Modes and Mitigations
+- **Peer unreachable/slow during broadcast** (partition, crash, suspend, GC pause): that peer's Broker misses the event, causing temporary inconsistency. → Concurrent broadcast with per-peer timeouts so one peer can't block others or the local Broker; bounded exponential-backoff retries, drop after max attempts with a metric/alert; peers reconcile via later events.
+- **Connection exhaustion under burst** (observed in the field): a per-event connection makes every lifecycle event pay a full mTLS handshake, and an unreaped idle connection pins a descriptor for the process lifetime. At inference-burst rates this starves the sender and the receiving listener until handshakes fail outright, and the events lost are disproportionately terminal ones — which the ~two-interval terminal retention cannot recover once the window passes. → Pool connections per peer with a bound on both total and idle connections per host, reap idle connections on both ends (§7.2), and drain response bodies so a connection is actually reusable. Note the residual: fan-out concurrency itself is still per-event, so a heartbeat round with many active workloads issues many simultaneous requests per peer.
+- **mTLS handshake failure / untrusted or expired cert**: that peer is isolated from broadcasts (`403`). → Reject and log with the presented identity; monitor and alert ahead of cert expiry; keep the trust store hot-reloadable so rotations apply without restart.
+- **Duplicate / re-broadcast events**: the Broker could see the same transition repeatedly, corrupting counts/state. → Deduplicate by `(nodeId, Workload.id, state)` (removals by `(nodeId, workloadId)`) before emitting, so the Broker updates at most once.
+- **Malformed payload / unknown `method`**: could crash the parser or propagate garbage. → Validate every envelope; reject (`400`) inter-node or drop-and-log locally; never forward unvalidated payloads.
+- **Local interface severed** (Broker exited → `stdin` EOF / `stdout` `EPIPE` / `ERROR_BROKEN_PIPE`): an orphaned manager would accept peer events with nowhere to forward them. → Treat EOF/`EPIPE` as the shutdown signal: stop the listener and exit cleanly. No reconnect/buffering — a new Broker spawns a new (stateless) manager. The small load lets the OS pipe buffer absorb serialized `stdout` writes.
+- **Out-of-order delivery for the same workload (local)**: the Broker could see an inconsistent progression (e.g. `completed` before `started`). → Serialize `stdout` writes; the Broker orders per workload via `(nodeId, workloadId)` (monotonic IDs) and timestamps.
+- **Stale discovery snapshot** (departed node still targeted, or new node not yet in a snapshot): wasted attempts to dead nodes, or new nodes missing events. → Rebuild the target set from every `discovery:nodes` snapshot, so a peer absent from the next snapshot stops being a target without any expiry logic here; liveness is the discovery daemon's, which probes a node before evicting it so a transient miss does not flap the set. New joiners catch up via later events (no replay).
+
+## 13. Observability
+- **Logging**: mTLS/cert rejections with presented identity (`403`) and malformed/unknown-`method` rejections (`400`); per-peer broadcast failures including final drop; deduplicated/dropped inbound events; target-set changes applied from a `discovery:nodes` snapshot (peers added, peers removed, resulting total); startup and clean shutdown on `stdin` EOF / `stdout` `EPIPE`.
+- **Metrics**: inbound rate (local and inter-node) and outbound broadcast rate; per-peer success/failure counts, latency, retry and final-drop counts; dedup hit rate; discovered/active peer count; mTLS handshake failure count.
+- **Alerts**: sustained broadcast failures to a peer; elevated `400` / `403` rate (misconfiguration or untrusted caller).
+
+## 14. Sample usage
+A request on node A is routed to its local inference proxy, which emits a `workload:submitted` notification (`params.workloadInfo` = a `Workload`). The Broker forwards it to the Workload Manager, which broadcasts it to all discovered peers over HTTPS/mTLS using trusted-store certificates.
+
+Each recipient (nodes K1…KN) validates and deduplicates the broadcast, then emits `workloads:upsert` on `stdout` so its local Broker updates its cluster-wide catalog.
+
+Having seen both originating workloads and remote `workloads:upsert` / `workloads:remove`, each Broker tracks all workloads and states. When a workload is retired, the Broker sends `workloads:remove` on `stdin`; the Workload Manager broadcasts it, and each recipient emits `workloads:remove` on `stdout` after validating the inter-node signal.