@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/flow/flow.md

@@ -0,0 +1,139 @@
+# Flow
+
+**Category:** display  
+**Description:** The declarative, AI-first flow surface — render a node/edge graph from plain serializable data.
+
+## When to use
+
+- Rendering a graph from data — the common case and the agent-emittable surface
+- Flowcharts, DAGs, pipelines, and mind-maps from plain nodes/edges arrays
+
+## When NOT to use
+
+- A scripted, sequenced walkthrough — use FlowStory
+- Heavy graph editing (undo/redo, resize/rotate) — out of scope
+
+## Anti-patterns
+
+### Declarative serializable data is what an agent can emit and what stays in sync with props.
+
+**Bad:** `Imperatively building the graph with graph.addNode(...)`  
+**Good:** `<Flow nodes={…} edges={…} />`  
+**Why:** Declarative serializable data is what an agent can emit and what stays in sync with props.
+
+## Related components
+
+- **FlowStory** (alternative): Scripted, captioned storyline animation.
+- **FlowNode** (contains): Renders a node per entry.
+- **FlowEdge** (contains): Renders an edge per entry.
+
+## Accessibility rationale
+
+role="application" canvas; nodes are focusable groups; controls are real i18n-labeled buttons.
+
+## Props
+
+| Name            | Type                                                    | Required | Default | Description                                                                                                          |
+| --------------- | ------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `nodes`         | `FlowNode[]`                                            | Yes      | —       | Initial nodes (serializable).                                                                                        |
+| `edges`         | `FlowEdge[]`                                            | Yes      | —       | Initial edges (serializable).                                                                                        |
+| `onNodesChange` | `(nodes: FlowNode[]) => void`                           | No       | —       | Called with the next nodes when they change (drag, add, remove).                                                     |
+| `onEdgesChange` | `(edges: FlowEdge[]) => void`                           | No       | —       | Called with the next edges when they change.                                                                         |
+| `onConnect`     | `(connection: Connection) => void`                      | No       | —       | Called when two handles are connected to form a new edge.                                                            |
+| `nodeTypes`     | `Record<string, NodeRenderer>`                          | No       | —       | Custom node renderers keyed by node.type.                                                                            |
+| `fitView`       | `boolean`                                               | No       | true    | When true, fits the graph to the viewport on mount.                                                                  |
+| `background`    | `boolean \| FlowBackgroundProps`                        | No       | false   | Background pattern — true for the default dots, or a config object.                                                  |
+| `controls`      | `boolean`                                               | No       | false   | Whether to show the controls.                                                                                        |
+| `minimap`       | `boolean`                                               | No       | false   | When true, shows the minimap overlay.                                                                                |
+| `layout`        | `'grid' \| 'layered' \| ((nodes, edges) => FlowNode[])` | No       | —       | Optional dependency-free layout.                                                                                     |
+| `interactive`   | `boolean`                                               | No       | true    | When false (view mode), nodes cannot be selected, dragged, or connected and handles are hidden; pan/zoom still work. |
+| `className`     | `string`                                                | No       | —       | Additional CSS class names merged onto the root element.                                                             |
+
+## Tokens
+
+- `--cascivo-color-bg`
+- `--cascivo-color-surface`
+- `--cascivo-color-accent`
+
+## Examples
+
+### Declarative pipeline
+
+A flow from plain serializable data, with background, controls, and an animated edge.
+
+```jsx
+;() => (
+  <Flow
+    style={{ height: 280 }}
+    background
+    controls
+    nodes={[
+      { id: 'a', position: { x: 0, y: 60 }, data: { label: 'Client' } },
+      { id: 'b', position: { x: 240, y: 60 }, data: { label: 'Gateway' } },
+      { id: 'c', position: { x: 480, y: 60 }, data: { label: 'Service' } },
+    ]}
+    edges={[
+      { id: 'ab', source: 'a', target: 'b', animated: true, label: 'request' },
+      { id: 'bc', source: 'b', target: 'c' },
+    ]}
+  />
+)
+```
+
+### Layered layout
+
+Let the dependency-free layered layout arrange a small DAG.
+
+```jsx
+;() => (
+  <Flow
+    style={{ height: 300 }}
+    layout="layered"
+    background
+    minimap
+    nodes={[
+      { id: 'a', position: { x: 0, y: 0 }, data: { label: 'Ingest' } },
+      { id: 'b', position: { x: 0, y: 0 }, data: { label: 'Transform' } },
+      { id: 'c', position: { x: 0, y: 0 }, data: { label: 'Validate' } },
+      { id: 'd', position: { x: 0, y: 0 }, data: { label: 'Load' } },
+    ]}
+    edges={[
+      { id: 'ab', source: 'a', target: 'b' },
+      { id: 'ac', source: 'a', target: 'c' },
+      { id: 'bd', source: 'b', target: 'd' },
+      { id: 'cd', source: 'c', target: 'd' },
+    ]}
+  />
+)
+```
+
+## Boundaries
+
+| Area      | Level    | Note                                         |
+| --------- | -------- | -------------------------------------------- |
+| rendering | flexible | Custom node renderers via nodeTypes.         |
+| layout    | flexible | grid \| layered \| bring-your-own positions. |
+| chrome    | flexible | Optional background / controls / minimap.    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Flow component (display). The declarative, AI-first flow surface — render a node/edge graph from plain serializable data.
+
+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).
+
+Flow is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-bg, --cascivo-color-surface, --cascivo-color-accent
+
+Accessibility: role "application", WCAG 2.1-AA, keyboard: Tab (focus nodes)/Enter/Space (select)/Drag (pan/move)/Wheel (zoom). Keep it AA.
+Flexible: rendering, layout, chrome.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/form.md

@@ -0,0 +1,104 @@
+# Form
+
+**Category:** inputs  
+**Description:** Typed signal-based form store (createForm/useForm) with sync/async validation and a thin Form element wrapper
+
+## When to use
+
+- Collecting and submitting a set of related field values together
+- Running sync or async validation (including Standard Schema like zod/valibot/arktype) before invoking onValid
+- Tracking per-field touched state and errors via the signal-based store from useForm/createForm
+
+## When NOT to use
+
+- A single standalone value with no submission step — render a bare Input
+- Inline editing of one read-only value — use Editable
+
+## Anti-patterns
+
+### The store centralizes values, errors, touched, and submitting as signals; rolling your own reintroduces the re-render and validation-timing bugs the store solves
+
+**Bad:** `<form onSubmit={...}> with hand-rolled useState per field`  
+**Good:** `const form = useForm({ initialValues, validate }); <Form form={form} onValid={...}>`  
+**Why:** The store centralizes values, errors, touched, and submitting as signals; rolling your own reintroduces the re-render and validation-timing bugs the store solves
+
+## Related components
+
+- **Input** (contains): Form wraps field controls like Input, wiring value/onChange/onBlur/error from form.field()
+- **FileUploader** (contains): File attachments can participate in a Form submission
+
+## Accessibility rationale
+
+Renders a native <form> with noValidate so validation messages come from the component (surfaced per field via Input error/role="alert") rather than inconsistent browser bubbles, while Enter-to-submit and the form role are preserved by the platform element.
+
+## Props
+
+| Name        | Type                                   | Required | Default | Description                                                      |
+| ----------- | -------------------------------------- | -------- | ------- | ---------------------------------------------------------------- |
+| `form`      | `FormStore<T>`                         | Yes      | —       | The form store holding values, validation, and submission state. |
+| `onValid`   | `(values: T) => void \| Promise<void>` | Yes      | —       | Called with the values when the form passes validation.          |
+| `children`  | `ReactNode`                            | Yes      | —       | Content rendered inside the component.                           |
+| `className` | `string`                               | No       | —       | Additional CSS class names merged onto the root element.         |
+
+## Tokens
+
+- `--cascivo-space-4`
+
+## Examples
+
+### Basic form with validation
+
+```jsx
+function Demo() {
+  const form = useForm({
+    initialValues: { email: '' },
+    validate: (v) => (v.email.includes('@') ? {} : { email: 'Invalid email' }),
+  })
+  const email = form.field('email')
+  return (
+    <Form form={form} onValid={console.log}>
+      <Input
+        label="Email"
+        value={email.value}
+        onChange={(e) => email.onChange(e.currentTarget.value)}
+        onBlur={email.onBlur}
+        error={email.error}
+      />
+      <Button type="submit">Save</Button>
+    </Form>
+  )
+}
+```
+
+## Boundaries
+
+| Area                      | Level    | Note                                                                                                  |
+| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| validation strategy       | flexible | Use schema, validate, or both; schema runs first and validate only if the schema passes               |
+| field control composition | flexible | Any control can be wired via form.field(name); children are free-form                                 |
+| submit semantics          | strict   | onValid only fires when validation produces no errors; submission is guarded by the submitting signal |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Form component (inputs). Typed signal-based form store (createForm/useForm) with sync/async validation and a thin Form element wrapper
+
+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).
+
+Form is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-4
+
+Accessibility: role "form", WCAG 2.2-AA, keyboard: Tab/Enter. Keep it AA.
+
+Do not change (strict): submit semantics — onValid only fires when validation produces no errors; submission is guarded by the submitting signal
+Flexible: validation strategy, field control composition.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/header-panel.md

@@ -0,0 +1,96 @@
+# HeaderPanel
+
+**Category:** navigation  
+**Description:** Non-modal panel anchored below the shell header at the inline-end edge — hosts notifications, app switcher, user settings
+
+## When to use
+
+- Hosting a non-modal panel anchored under the shell header (notifications, switcher, settings)
+- Showing supplementary content triggered by a ShellHeader icon action
+- Light-dismiss content that should not block the rest of the app
+
+## When NOT to use
+
+- Content that must block interaction until resolved — use Modal
+- A small contextual menu attached to a trigger — use Dropdown or Popover
+
+## Anti-patterns
+
+### HeaderPanel is non-modal and light-dismissable; blocking flows need modal semantics
+
+**Bad:** `Using HeaderPanel for a blocking confirmation`  
+**Good:** `<Modal> or <AlertDialog> for decisions that must block`  
+**Why:** HeaderPanel is non-modal and light-dismissable; blocking flows need modal semantics
+
+## Related components
+
+- **ShellHeader** (pairs-with): Opened by a ShellHeader action whose active state mirrors the panel open state
+- **Switcher** (contains): A Switcher commonly lives inside a HeaderPanel
+
+## Accessibility rationale
+
+role="region" with the label prop names the panel as a landmark; Escape closes it and focus is managed so keyboard users can dismiss it without a mouse
+
+## Props
+
+| Name        | Type                | Required | Default | Description                                              |
+| ----------- | ------------------- | -------- | ------- | -------------------------------------------------------- |
+| `open`      | `boolean`           | Yes      | —       | Controlled open state                                    |
+| `onClose`   | `() => void`        | Yes      | —       | Called on close button click or light-dismiss            |
+| `label`     | `string`            | Yes      | —       | Accessible label for the region (shown as header title)  |
+| `children`  | `ReactNode`         | Yes      | —       | Content rendered inside the component.                   |
+| `labels`    | `HeaderPanelLabels` | No       | —       | i18n overrides                                           |
+| `className` | `string`            | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-shell-header-block-size`
+- `--cascivo-shell-panel-inline-size`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-shadow-md`
+- `--cascivo-motion-enter`
+
+## Examples
+
+### Notification panel
+
+Pair with a ShellHeader action: action active=open, onAction toggles open
+
+```jsx
+<HeaderPanel open={open} onClose={() => setOpen(false)} label="Notifications">
+  <p>3 unread messages</p>
+</HeaderPanel>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                  |
+| ----------- | -------- | --------------------------------------------------------------------- |
+| content     | flexible | Children are arbitrary panel content                                  |
+| token names | strict   | Surface, shadow, and sizing must resolve to --cascivo-\* shell tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo HeaderPanel component (navigation). Non-modal panel anchored below the shell header at the inline-end edge — hosts notifications, app switcher, user settings
+
+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).
+
+HeaderPanel is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-shell-header-block-size, --cascivo-shell-panel-inline-size, --cascivo-color-surface, --cascivo-color-border, --cascivo-shadow-md, --cascivo-motion-enter
+
+Accessibility: role "region", WCAG 2.2-AA, keyboard: Escape/Tab. Keep it AA.
+
+Do not change (strict): token names — Surface, shadow, and sizing must resolve to --cascivo-* shell tokens
+Flexible: content.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/header.md

@@ -0,0 +1,104 @@
+# Header
+
+**Category:** navigation  
+**Description:** App top bar with brand, primary navigation links, and an actions slot
+
+## When to use
+
+- Providing a simple marketing or app top bar with brand, links, and actions
+- Anchoring primary navigation across pages of a site
+- Keeping the bar visible while scrolling (sticky)
+
+## When NOT to use
+
+- Dense console apps with dropdown nav, global icon actions, and a hamburger — use ShellHeader
+- Section headings within page content — use Heading
+
+## Anti-patterns
+
+### Header is intentionally simple; console patterns belong to ShellHeader which provides them natively
+
+**Bad:** `Building complex multi-menu console chrome on top of Header`  
+**Good:** `<ShellHeader> for console-grade navigation`  
+**Why:** Header is intentionally simple; console patterns belong to ShellHeader which provides them natively
+
+## Related components
+
+- **ShellHeader** (alternative): ShellHeader is the console-grade header with dropdowns and icon actions
+
+## Accessibility rationale
+
+role="banner" marks the page header landmark; the active link is marked aria-current="page", and links/actions are real focusable controls so keyboard users can navigate the bar
+
+## Props
+
+| Name        | Type                                                  | Required | Default | Description                                                    |
+| ----------- | ----------------------------------------------------- | -------- | ------- | -------------------------------------------------------------- |
+| `brand`     | `React.ReactNode`                                     | No       | —       | Product name or logo area, typically wraps a link              |
+| `links`     | `{ label: string; href: string; active?: boolean }[]` | No       | —       | Primary navigation links; active link gets aria-current="page" |
+| `actions`   | `React.ReactNode`                                     | No       | —       | Right-aligned slot for buttons or an avatar                    |
+| `sticky`    | `boolean`                                             | No       | false   | When true, the header sticks to the top on scroll.             |
+| `className` | `string`                                              | No       | —       | Additional CSS class names merged onto the root element.       |
+
+## Tokens
+
+- `--cascivo-header-bg`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-focus-ring`
+- `--cascivo-z-raised`
+
+## Examples
+
+### Basic
+
+```jsx
+<Header brand="cascivo" links={[{ label: 'Docs', href: '/docs' }]} />
+```
+
+### With actions
+
+```jsx
+<Header brand="cascivo" actions={<Button size="sm">Sign in</Button>} />
+```
+
+### Sticky
+
+```jsx
+<Header sticky brand="cascivo" links={links} />
+```
+
+## Boundaries
+
+| Area              | Level    | Note                                                             |
+| ----------------- | -------- | ---------------------------------------------------------------- |
+| links and actions | flexible | Brand, links, and actions slots are optional and composable      |
+| token names       | strict   | Surface, border, and z-index 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 Header component (navigation). App top bar with brand, primary navigation links, and an actions slot
+
+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).
+
+Header is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-header-bg, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-bg-subtle, --cascivo-focus-ring, --cascivo-z-raised
+
+Accessibility: role "banner", WCAG 2.2-AA, keyboard: Tab. Keep it AA.
+
+Do not change (strict): token names — Surface, border, and z-index must resolve to --cascivo-* tokens
+Flexible: links and actions.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/heading.md

@@ -0,0 +1,107 @@
+# Heading
+
+**Category:** display  
+**Description:** Section heading with semantic level decoupled from visual size
+
+## When to use
+
+- Titling a page or section as part of the document outline
+- Keeping the semantic heading level correct while choosing the visual size independently
+
+## When NOT to use
+
+- Emphasizing inline or body text — use Text with a weight
+- Long-form rendered content — let Prose style its own headings
+
+## Anti-patterns
+
+### Skipping heading levels breaks the document outline screen-reader users rely on to navigate
+
+**Bad:** `<Heading level={4} size="2xl"> chosen only to look big, skipping h2/h3`  
+**Good:** `Keep levels sequential; use size to control scale within the correct level`  
+**Why:** Skipping heading levels breaks the document outline screen-reader users rely on to navigate
+
+## Related components
+
+- **Text** (alternative): Text is for body copy; Heading is for outline structure
+- **Prose** (alternative): Prose styles headings inside authored long-form content
+
+## Accessibility rationale
+
+Renders a real <h1>–<h6> from the level prop so the heading appears in the accessibility tree at the correct level; visual size is decoupled so styling never forces an incorrect level
+
+## Props
+
+| Name    | Type                                    | Required | Default                                                  | Description                                           |
+| ------- | --------------------------------------- | -------- | -------------------------------------------------------- | ----------------------------------------------------- |
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6`            | No       | 2                                                        | Heading level (1–6) mapping to h1–h6.                 |
+| `size`  | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | No       | derived from level (1→2xl, 2→xl, 3→lg, 4→md, 5→sm, 6→sm) | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+
+## Tokens
+
+- `--cascivo-font-display`
+- `--cascivo-font-semibold`
+- `--cascivo-leading-tight`
+- `--cascivo-tracking-tight`
+- `--cascivo-color-text`
+- `--cascivo-text-base`
+- `--cascivo-text-lg`
+- `--cascivo-text-xl`
+- `--cascivo-text-2xl`
+- `--cascivo-text-3xl`
+
+## Examples
+
+### Default
+
+```jsx
+<Heading>Section title</Heading>
+```
+
+### Page title
+
+```jsx
+<Heading level={1}>Page title</Heading>
+```
+
+### Decoupled size
+
+Keep the document outline correct while controlling the visual scale
+
+```jsx
+<Heading level={2} size="2xl">
+  Visually large, semantically h2
+</Heading>
+```
+
+## Boundaries
+
+| Area           | Level    | Note                                                         |
+| -------------- | -------- | ------------------------------------------------------------ |
+| size           | flexible | size may override the level-derived default for visual scale |
+| level sequence | strict   | Levels must not skip — maintain a valid heading hierarchy    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Heading component (display). Section heading with semantic level decoupled from visual size
+
+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).
+
+Heading is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-display, --cascivo-font-semibold, --cascivo-leading-tight, --cascivo-tracking-tight, --cascivo-color-text, --cascivo-text-base, --cascivo-text-lg, --cascivo-text-xl, --cascivo-text-2xl, --cascivo-text-3xl
+
+Accessibility: role "heading", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): level sequence — Levels must not skip — maintain a valid heading hierarchy
+Flexible: size.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/hover-card.md

@@ -0,0 +1,108 @@
+# HoverCard
+
+**Category:** overlay  
+**Description:** Hover-triggered popover with configurable open/close delay
+
+## When to use
+
+- Showing a rich preview (avatar, summary, links) when a user hovers or focuses a trigger
+- Supplementary, non-essential context the user can ignore without losing functionality
+- Cases needing an open/close delay so brief mouse passes do not flicker the card
+
+## When NOT to use
+
+- Short plain-text hints — use Tooltip
+- Content the user must interact with or that should trap focus — use Popover or Modal
+- Touch-primary flows where there is no hover — prefer a tap-triggered Popover
+
+## Anti-patterns
+
+### Hover surfaces are transient and unreachable by touch and many keyboard paths, so essential controls get lost
+
+**Bad:** `Putting required actions (buttons users must click) inside HoverCardContent`  
+**Good:** `Use a Popover triggered by click so the surface is reliably reachable`  
+**Why:** Hover surfaces are transient and unreachable by touch and many keyboard paths, so essential controls get lost
+
+## Related components
+
+- **Tooltip** (alternative): Use Tooltip for brief text labels rather than rich preview content
+- **Popover** (alternative): Use Popover for click-triggered, interactive, focus-managed content
+
+## Accessibility rationale
+
+The trigger opens on both mouseenter and focus (and closes on mouseleave/blur) so keyboard users get the same preview, and the content is marked role="complementary" to signal it is supplementary rather than a required dialog; the open/close delays prevent accidental flicker.
+
+## Props
+
+| Name         | Type              | Required | Default | Description                                                 |
+| ------------ | ----------------- | -------- | ------- | ----------------------------------------------------------- |
+| `children`   | `React.ReactNode` | Yes      | —       | A HoverCardTrigger and HoverCardContent pair.               |
+| `openDelay`  | `number`          | No       | 300     | Delay (ms) before the card opens on hover/focus.            |
+| `closeDelay` | `number`          | No       | 100     | Delay (ms) before the card closes after hover/focus leaves. |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-md`
+- `--cascivo-shadow-md`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Profile preview
+
+```jsx
+<HoverCard>
+  <HoverCardTrigger>
+    <a href="/users/ada">@ada</a>
+  </HoverCardTrigger>
+  <HoverCardContent>
+    <Avatar name="Ada Lovelace" />
+    <p>Wrote the first program.</p>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Custom delays
+
+```jsx
+<HoverCard openDelay={500} closeDelay={200}>
+  <HoverCardTrigger>Definition</HoverCardTrigger>
+  <HoverCardContent>A longer explanation shown on hover or focus.</HoverCardContent>
+</HoverCard>
+```
+
+## Boundaries
+
+| Area             | Level    | Note                                                                                       |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------ |
+| token names      | strict   | Surface, border, radius, shadow, and motion must resolve to the listed --cascivo-\* tokens |
+| open/close delay | flexible | openDelay and closeDelay are tunable per instance (defaults 300/100ms)                     |
+| content          | flexible | HoverCardContent accepts arbitrary children                                                |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo HoverCard component (overlay). Hover-triggered popover with configurable open/close delay
+
+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).
+
+HoverCard is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-md, --cascivo-shadow-md, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "complementary", WCAG 2.2-AA, keyboard: Tab/Escape. Keep it AA.
+
+Do not change (strict): token names — Surface, border, radius, shadow, and motion must resolve to the listed --cascivo-* tokens
+Flexible: open/close delay, content.
+
+Do not invent props, tokens, or global viewport media queries.
+```