@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/code-snippet.md

@@ -0,0 +1,118 @@
+# CodeSnippet
+
+**Category:** display  
+**Description:** Displays code (inline, single-line, or multi-line) with an optional copy button, lightweight built-in syntax highlighting for bash/css/js/ts, and an optional terminal-window look
+
+## When to use
+
+- Showing a command, token, or path the user is expected to copy
+- Displaying a short read-only code block in docs or UI
+- Inline code references inside flowing text (inline variant)
+
+## When NOT to use
+
+- An editable code input — use a textarea or code editor
+- Whole source files needing folding, diagnostics, or many languages — use a dedicated viewer; the built-in highlighter is a presentational scan for bash/css/js/ts only
+
+## Anti-patterns
+
+### The inline variant is a single in-text chip; multi-line content belongs in the multi variant
+
+**Bad:** `<CodeSnippet variant="inline" code={"line1\nline2"} />`  
+**Good:** `<CodeSnippet variant="multi" code={"line1\nline2"} />`  
+**Why:** The inline variant is a single in-text chip; multi-line content belongs in the multi variant
+
+## Related components
+
+- **CopyButton** (pairs-with): CodeSnippet embeds the same clipboard behavior for its copy affordance
+
+## Accessibility rationale
+
+Code is rendered in semantic <code>/<pre>. The copy button is a real button with an aria-label that flips between the copy and copied messages so the action and its result are announced. Line numbers are aria-hidden so they are not read as content.
+
+## Props
+
+| Name              | Type                                 | Required | Default | Description                                                                               |
+| ----------------- | ------------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------- |
+| `code`            | `string`                             | Yes      | —       | The code to display (and copy).                                                           |
+| `variant`         | `'inline' \| 'single' \| 'multi'`    | No       | single  | inline = a <code> span; single = one-line <pre>; multi = multi-line <pre>.                |
+| `language`        | `'bash' \| 'css' \| 'js' \| 'ts'`    | No       | —       | Enables built-in syntax highlighting for the block variants; inline is never highlighted. |
+| `terminal`        | `boolean`                            | No       | false   | Renders terminal-window chrome (title bar with dots). Block variants only.                |
+| `title`           | `string`                             | No       | —       | Optional label shown in the terminal title bar.                                           |
+| `showLineNumbers` | `boolean`                            | No       | —       | Show line numbers (multi only; ignored when language is set).                             |
+| `showCopyButton`  | `boolean`                            | No       | —       | Show the copy-to-clipboard button. Defaults true for single/multi, false for inline.      |
+| `labels`          | `{ copy?: string; copied?: string }` | No       | —       | Overrides for the component’s user-visible strings (i18n).                                |
+| `className`       | `string`                             | No       | —       | Additional CSS class names merged onto the root element.                                  |
+
+## Tokens
+
+- `--cascivo-font-mono`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-surface`
+- `--cascivo-radius-control`
+
+## Examples
+
+### Install command
+
+```jsx
+<CodeSnippet code="npx cascivo add button" language="bash" />
+```
+
+### Inline
+
+```jsx
+<p>
+  Run <CodeSnippet variant="inline" code="pnpm build" /> first.
+</p>
+```
+
+### Terminal block
+
+Multi-line shell transcript with terminal-window chrome.
+
+```jsx
+<CodeSnippet
+  variant="multi"
+  language="bash"
+  terminal
+  title="deploy.sh"
+  code={'pnpm build\npnpm deploy'}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                 |
+| ----------- | -------- | -------------------------------------------------------------------- |
+| variant     | strict   | inline \| single \| multi — controls the wrapping element and layout |
+| copy button | flexible | Shown by default for single/multi; togglable via showCopyButton      |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo CodeSnippet component (display). Displays code (inline, single-line, or multi-line) with an optional copy button, lightweight built-in syntax highlighting for bash/css/js/ts, and an optional terminal-window look
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+CodeSnippet is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-mono, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-bg-subtle, --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-surface, --cascivo-radius-control
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): variant — inline | single | multi — controls the wrapping element and layout
+Flexible: copy button.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/code.md

@@ -0,0 +1,103 @@
+# Code
+
+**Category:** display  
+**Description:** Inline code span for identifiers, commands, and short snippets
+
+## When to use
+
+- Marking up an inline identifier, command, path, or token within prose
+- Distinguishing literal code from surrounding text with a monospace span
+
+## When NOT to use
+
+- Multi-line code blocks with syntax highlighting — use a <pre> block
+- Keyboard shortcuts the user should press — use Kbd
+
+## Anti-patterns
+
+### Code marks literal code; key presses are semantically Kbd
+
+**Bad:** `<Code>Press Cmd+K</Code>`  
+**Good:** `<Kbd>⌘</Kbd> <Kbd>K</Kbd>`  
+**Why:** Code marks literal code; key presses are semantically Kbd
+
+## Related components
+
+- **Kbd** (alternative): Kbd is for keys to press, not code to read
+- **Prose** (pairs-with): Prose styles inline <code> automatically in authored content
+
+## Accessibility rationale
+
+Renders a native <code> element so assistive tech can expose the content as code; relies on monospace and surface, not color alone, to distinguish it
+
+## Props
+
+| Name   | Type           | Required | Default | Description                                           |
+| ------ | -------------- | -------- | ------- | ----------------------------------------------------- |
+| `size` | `'sm' \| 'md'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+
+## Tokens
+
+- `--cascivo-font-mono`
+- `--cascivo-color-text`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-indicator`
+- `--cascivo-text-xs`
+- `--cascivo-text-sm`
+
+## Examples
+
+### Default
+
+```jsx
+<Code>npx cascivo add button</Code>
+```
+
+### In a sentence
+
+Sits inline with surrounding text
+
+```jsx
+<Text>
+  Run <Code>vp check</Code> before committing.
+</Text>
+```
+
+### Small
+
+```jsx
+<Code size="sm">--cascivo-color-accent</Code>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                         |
+| ----------- | -------- | ---------------------------------------------------------------------------- |
+| size        | flexible | sm fits dense UI; md matches body text                                       |
+| token names | strict   | Font and surface must resolve to --cascivo-font-mono and --cascivo-\* tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Code component (display). Inline code span for identifiers, commands, and short snippets
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Code is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-mono, --cascivo-color-text, --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-indicator, --cascivo-text-xs, --cascivo-text-sm
+
+Accessibility: role "code", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Font and surface must resolve to --cascivo-font-mono and --cascivo-* tokens
+Flexible: size.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/collapsible.md

@@ -0,0 +1,104 @@
+# Collapsible
+
+**Category:** display  
+**Description:** A single disclosure region toggled open and closed by its trigger
+
+## When to use
+
+- Hiding a single secondary block until the user asks for it
+- Progressive disclosure of details, advanced options, or supplementary text
+- Toggling one region whose state you may want to control externally
+
+## When NOT to use
+
+- Several mutually related sections — use Accordion instead
+- Transient overlays anchored to a trigger — use Dropdown or Popover
+
+## Anti-patterns
+
+### Accordion manages single/multiple-open semantics and shared keyboard navigation
+
+**Bad:** `Stacking many Collapsibles to emulate an accordion`  
+**Good:** `Use Accordion when sections are a related set`  
+**Why:** Accordion manages single/multiple-open semantics and shared keyboard navigation
+
+## Related components
+
+- **Accordion** (alternative): Multi-region disclosure; Collapsible is the single-region case
+
+## Accessibility rationale
+
+The trigger is a native button exposing aria-expanded and aria-controls; the region is labelled by the trigger, so screen readers announce the disclosure state and target
+
+## Props
+
+| Name           | Type                      | Required | Default | Description                                         |
+| -------------- | ------------------------- | -------- | ------- | --------------------------------------------------- |
+| `open`         | `boolean`                 | No       | —       | Controlled open state                               |
+| `defaultOpen`  | `boolean`                 | No       | false   | Initial open state for uncontrolled use             |
+| `onOpenChange` | `(open: boolean) => void` | No       | —       | Called whenever the open state should change        |
+| `trigger`      | `ReactNode`               | Yes      | —       | Content rendered inside the built-in trigger button |
+| `disabled`     | `boolean`                 | No       | false   | Disables the trigger button                         |
+| `children`     | `ReactNode`               | No       | —       | Content of the collapsible region                   |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-control`
+- `--cascivo-focus-ring`
+- `--cascivo-space-3`
+- `--cascivo-duration-200`
+- `--cascivo-ease-out`
+
+## Examples
+
+### Uncontrolled
+
+```jsx
+<Collapsible trigger="Show details">
+  <p>Hidden content revealed on toggle.</p>
+</Collapsible>
+```
+
+### Open by default
+
+```jsx
+<Collapsible defaultOpen trigger="Details">
+  <p>Visible initially.</p>
+</Collapsible>
+```
+
+## Boundaries
+
+| Area           | Level    | Note                                                                 |
+| -------------- | -------- | -------------------------------------------------------------------- |
+| open state     | flexible | Controlled or uncontrolled via open / defaultOpen                    |
+| trigger markup | strict   | Always rendered as a native button for keyboard and a11y correctness |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Collapsible component (display). A single disclosure region toggled open and closed by its trigger
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Collapsible is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-radius-control, --cascivo-focus-ring, --cascivo-space-3, --cascivo-duration-200, --cascivo-ease-out
+
+Accessibility: role "region", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): trigger markup — Always rendered as a native button for keyboard and a11y correctness
+Flexible: open state.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/color-picker.md

@@ -0,0 +1,101 @@
+# ColorPicker
+
+**Category:** inputs  
+**Description:** Interactive color selection widget with saturation/lightness area, hue and alpha sliders
+
+## When to use
+
+- Letting a user choose an arbitrary color via a visual saturation/lightness area plus hue control
+- Brand or theme customization UIs where an exact color value (hex) is captured
+- Forms that need an optional alpha channel alongside the color
+
+## When NOT to use
+
+- Choosing from a small fixed palette only — use a swatch RadioGroup instead
+- A single accent toggle where a few preset chips suffice
+
+## Anti-patterns
+
+### A free-form picker invites off-brand values when only a fixed set is allowed
+
+**Bad:** `<ColorPicker /> with no presets for a brand palette of 4 fixed colors`  
+**Good:** `<RadioGroup> of color swatches`  
+**Why:** A free-form picker invites off-brand values when only a fixed set is allowed
+
+## Related components
+
+- **Slider** (contains): Hue and alpha channels are range sliders
+- **Input** (pairs-with): The hex text field lets users paste an exact value
+
+## Accessibility rationale
+
+The saturation/lightness area is a focusable role="slider" with arrow-key nudging and an aria-valuetext reporting the current hex; hue and alpha are native range inputs that inherit platform slider semantics and announcements.
+
+## Props
+
+| Name            | Type                      | Required | Default | Description                                                        |
+| --------------- | ------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `value`         | `string`                  | No       | —       | Controlled hex color value                                         |
+| `defaultValue`  | `string`                  | No       | #3b82f6 | The initial value when uncontrolled.                               |
+| `onValueChange` | `(value: string) => void` | No       | —       | Called with the new value when it changes.                         |
+| `presets`       | `string[]`                | No       | —       | Preset swatch colors                                               |
+| `alpha`         | `boolean`                 | No       | true    | When true, enables alpha (opacity) selection.                      |
+| `label`         | `string`                  | No       | —       | Text label for the control.                                        |
+| `disabled`      | `boolean`                 | No       | false   | When true, disables the control and removes it from the tab order. |
+| `size`          | `'sm' \| 'md' \| 'lg'`    | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-radius-md`
+- `--cascivo-radius-full`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<ColorPicker defaultValue="#3b82f6" onValueChange={setColor} />
+```
+
+### With presets
+
+```jsx
+<ColorPicker presets={['#ef4444', '#3b82f6', '#10b981']} alpha={false} />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                       |
+| ----------- | -------- | -------------------------------------------------------------------------- |
+| color model | flexible | Values are stored as hex; consumers can convert to rgb/hsl/oklch as needed |
+| token names | strict   | Surfaces, borders and focus ring must resolve to --cascivo-\* tokens       |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ColorPicker component (inputs). Interactive color selection widget with saturation/lightness area, hue and alpha sliders
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+ColorPicker is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-radius-md, --cascivo-radius-full, --cascivo-focus-ring
+
+Accessibility: role "slider", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowUp/ArrowDown. Keep it AA.
+
+Do not change (strict): token names — Surfaces, borders and focus ring must resolve to --cascivo-* tokens
+Flexible: color model.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/combobox.md

@@ -0,0 +1,125 @@
+# Combobox
+
+**Category:** inputs  
+**Description:** Filterable single-select with an animated custom listbox, built on the dropdown open/close machine
+
+## When to use
+
+- Single-select from a long list where type-to-filter makes finding an option faster
+- Form fields where the value is one of many known options (country, assignee, repository)
+
+## When NOT to use
+
+- Short option lists (≈2–7) where filtering adds no value — use Select or SegmentedControl
+- Selecting multiple values — use MultiSelect
+- Triggering actions or commands — use Dropdown or CommandMenu
+
+## Anti-patterns
+
+### Combobox has role="combobox" with a listbox of selectable values and onChange semantics — actions belong in a menu
+
+**Bad:** `Using Combobox to fire actions like "Delete" or "Export"`  
+**Good:** `Use Dropdown for actions; Combobox is for picking a value`  
+**Why:** Combobox has role="combobox" with a listbox of selectable values and onChange semantics — actions belong in a menu
+
+### Without filtering the list becomes an unusable scroll; either keep search on or switch to a different selection pattern
+
+**Bad:** `Setting searchable={false} on a 200-item list`  
+**Good:** `undefined`  
+**Why:** Without filtering the list becomes an unusable scroll; either keep search on or switch to a different selection pattern
+
+## Related components
+
+- **Select** (alternative): Use for short lists that do not need type-to-filter
+- **MultiSelect** (alternative): Use when more than one value can be selected
+- **CommandMenu** (alternative): Use the Cmd+K palette for command/navigation search rather than value selection
+
+## Accessibility rationale
+
+Trigger exposes role="combobox" with aria-expanded, aria-controls, aria-haspopup="listbox", and aria-activedescendant pointing at the active option so screen readers track focus through arrow navigation without moving DOM focus off the input; error state is wired via aria-invalid + aria-describedby and announced with role="alert"
+
+## Props
+
+| Name           | Type                                   | Required | Default | Description                                                        |
+| -------------- | -------------------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `options`      | `ComboboxOption[]`                     | Yes      | —       | The selectable options.                                            |
+| `value`        | `string`                               | No       | —       | The controlled value.                                              |
+| `defaultValue` | `string`                               | No       | —       | The initial value when uncontrolled.                               |
+| `onChange`     | `(value: string \| undefined) => void` | No       | —       | Called when the value changes.                                     |
+| `clearable`    | `boolean`                              | No       | false   | When true, shows a control to clear the selected value.            |
+| `searchable`   | `boolean`                              | No       | true    | When true, shows a search/filter input.                            |
+| `label`        | `string`                               | No       | —       | Text label for the control.                                        |
+| `hint`         | `string`                               | No       | —       | Supplementary hint text shown with the control.                    |
+| `error`        | `string`                               | No       | —       | Error message shown when the value is invalid.                     |
+| `size`         | `'sm' \| 'md' \| 'lg'`                 | No       | 'md'    | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `disabled`     | `boolean`                              | No       | false   | When true, disables the control and removes it from the tab order. |
+| `labels`       | `ComboboxLabels`                       | No       | —       | Overrides for the component’s user-visible strings (i18n).         |
+| `className`    | `string`                               | No       | —       | Additional CSS class names merged onto the root element.           |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-surface-overlay`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-accent`
+- `--cascivo-color-danger`
+- `--cascivo-radius-input`
+- `--cascivo-radius-md`
+- `--cascivo-radius-sm`
+- `--cascivo-shadow-lg`
+- `--cascivo-motion-enter`
+- `--cascivo-z-dropdown`
+
+## Examples
+
+### Basic combobox
+
+```jsx
+<Combobox
+  label="Country"
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'de', label: 'Germany' },
+    { value: 'fr', label: 'France' },
+  ]}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+## Boundaries
+
+| Area                       | Level    | Note                                                                                     |
+| -------------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| searchable                 | flexible | Filtering can be toggled off for short lists via searchable={false}                      |
+| controlled vs uncontrolled | flexible | Supports value + onChange or defaultValue                                                |
+| token names                | strict   | Listbox/field styling resolves to semantic --cascivo-color-_ / --cascivo-radius-_ tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Combobox component (inputs). Filterable single-select with an animated custom listbox, built on the dropdown open/close machine
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Combobox is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-surface-overlay, --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-text-subtle, --cascivo-color-accent, --cascivo-color-danger, --cascivo-radius-input, --cascivo-radius-md, --cascivo-radius-sm, --cascivo-shadow-lg, --cascivo-motion-enter, --cascivo-z-dropdown
+
+Accessibility: role "combobox", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Enter/Escape/Tab. Keep it AA.
+
+Do not change (strict): token names — Listbox/field styling resolves to semantic --cascivo-color-* / --cascivo-radius-* tokens
+Flexible: searchable, controlled vs uncontrolled.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/command-menu.md

@@ -0,0 +1,121 @@
+# CommandMenu
+
+**Category:** overlay  
+**Description:** Cmd+K command palette with fuzzy search over grouped commands
+
+## When to use
+
+- Giving power users a global Cmd/Ctrl+K palette to search and run actions or navigate
+- Exposing many commands across grouped categories that benefit from fuzzy search
+- Multi-step flows where selecting an item drills into a nested page of further commands
+
+## When NOT to use
+
+- Picking a form value from a list — use Combobox
+- A small set of actions tied to a specific trigger button — use Dropdown
+
+## Anti-patterns
+
+### CommandMenu is a modal command palette whose items run onSelect callbacks or open sub-pages; it has no controlled form value
+
+**Bad:** `Using CommandMenu as a form field to capture a selected value`  
+**Good:** `Use Combobox for value selection inside a form`  
+**Why:** CommandMenu is a modal command palette whose items run onSelect callbacks or open sub-pages; it has no controlled form value
+
+### Each item must do exactly one thing — run an action (onSelect) or push a nested page (page)
+
+**Bad:** `Items with both onSelect and page set, or neither`  
+**Good:** `undefined`  
+**Why:** Each item must do exactly one thing — run an action (onSelect) or push a nested page (page)
+
+## Related components
+
+- **Combobox** (alternative): Use for filtering and selecting a form value rather than running commands
+- **Dropdown** (alternative): Use for a small action menu anchored to a button instead of a global palette
+- **Modal** (contained-by): Renders inside a native modal dialog with backdrop dismiss
+
+## Accessibility rationale
+
+The search input is role="combobox" with aria-controls, aria-expanded, aria-autocomplete="list" and aria-activedescendant so navigation is announced without moving DOM focus from the input; it renders in a native <dialog> for focus trapping, the empty/loading state uses role="status", and footer hints are aria-hidden as redundant decoration
+
+## Props
+
+| Name            | Type                      | Required | Default                   | Description                                                           |
+| --------------- | ------------------------- | -------- | ------------------------- | --------------------------------------------------------------------- |
+| `open`          | `boolean`                 | Yes      | —                         | Whether the component is open (controlled).                           |
+| `onOpenChange`  | `(open: boolean) => void` | Yes      | —                         | Called with the next open state when it changes.                      |
+| `groups`        | `CommandGroup[]`          | Yes      | —                         | The grouped commands to display.                                      |
+| `placeholder`   | `string`                  | No       | Type a command or search… | Placeholder text shown when the field is empty.                       |
+| `emptyLabel`    | `string`                  | No       | No results found          | Text shown when no commands match the query.                          |
+| `hotkey`        | `boolean`                 | No       | true                      | Global Cmd/Ctrl+K toggles the menu via onOpenChange                   |
+| `label`         | `string`                  | No       | Command menu              | Text label for the control.                                           |
+| `loading`       | `boolean`                 | No       | false                     | Shows a loading spinner in place of the empty state (for async items) |
+| `onQueryChange` | `(query: string) => void` | No       | —                         | Fires on every query keystroke — use to fetch async items             |
+| `className`     | `string`                  | No       | —                         | Additional CSS class names merged onto the root element.              |
+
+## Tokens
+
+- `--cascivo-color-surface-overlay`
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-text-subtle`
+- `--cascivo-radius-modal`
+- `--cascivo-radius-sm`
+- `--cascivo-shadow-xl`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Basic command menu
+
+```jsx
+<CommandMenu
+  open={open}
+  onOpenChange={setOpen}
+  groups={[
+    {
+      heading: 'Actions',
+      items: [
+        { id: 'new', label: 'New file', shortcut: ['⌘', 'N'], onSelect: createFile },
+        { id: 'search', label: 'Search docs', keywords: ['find'], onSelect: openSearch },
+      ],
+    },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                    |
+| ----------- | -------- | --------------------------------------------------------------------------------------- |
+| hotkey      | flexible | Global Cmd/Ctrl+K binding can be disabled via hotkey={false} for custom triggering      |
+| async items | flexible | onQueryChange + loading allow fetching items per keystroke                              |
+| token names | strict   | Palette styling resolves to semantic --cascivo-color-\* / --cascivo-radius-modal tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo CommandMenu component (overlay). Cmd+K command palette with fuzzy search over grouped commands
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+CommandMenu is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface-overlay, --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-text-subtle, --cascivo-radius-modal, --cascivo-radius-sm, --cascivo-shadow-xl, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "combobox", WCAG 2.2-AA, keyboard: Cmd/Ctrl+K/ArrowDown/ArrowUp/Home/End/Enter/Escape. Keep it AA.
+
+Do not change (strict): token names — Palette styling resolves to semantic --cascivo-color-* / --cascivo-radius-modal tokens
+Flexible: hotkey, async items.
+
+Do not invent props, tokens, or global viewport media queries.
+```