@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/chart/sparkline.md

@@ -0,0 +1,69 @@
+# Sparkline
+
+**Category:** chart  
+**Description:** Compact inline sparkline for embedding trend data in dashboards or KPI cards.
+
+## When to use
+
+- Embedding a compact micro-trend inline in text, tables, or KPI cards
+- Conveying direction at a glance where a full chart would be too large
+
+## When NOT to use
+
+- Reading precise values or axes are needed — use LineChart
+- As a standalone primary chart with its own panel
+
+## Related components
+
+- **LineChart** (alternative): Use as a full chart when axes and tooltips are needed
+- **Kpi** (contained-by): Commonly embedded inside a KPI card as a trend indicator
+
+## Accessibility rationale
+
+Renders with role="img" and requires a label prop for screen reader labeling.
+
+## Props
+
+| Name     | Type       | Required | Default | Description                 |
+| -------- | ---------- | -------- | ------- | --------------------------- |
+| `data`   | `number[]` | Yes      | —       | Array of numeric values     |
+| `label`  | `string`   | Yes      | —       | Accessible label            |
+| `width`  | `number`   | No       | 80      | Width of the component.     |
+| `height` | `number`   | No       | 32      | Height of the component.    |
+| `color`  | `string`   | No       | —       | Stroke color (CSS value)    |
+| `endDot` | `boolean`  | No       | —       | Show dot at last data point |
+
+## Tokens
+
+- `--cascivo-chart-1`
+
+## Examples
+
+### Inline sparkline
+
+```jsx
+import { Sparkline } from '@cascivo/charts'
+;<Sparkline data={[10, 20, 15, 30, 25]} label="Trend" endDot />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Sparkline component (chart). Compact inline sparkline for embedding trend data in dashboards or KPI cards.
+
+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).
+
+Sparkline is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/stream.md

@@ -0,0 +1,88 @@
+# Stream
+
+**Category:** chart  
+**Description:** Streamgraph — stacked areas on a centered (silhouette) flowing baseline.
+
+## When to use
+
+- Showing how several series ebb and flow over time as proportions of a whole
+- An organic, aesthetic alternative to a stacked area chart
+
+## When NOT to use
+
+- Reading precise values — use LineChart or AreaChart
+- Few categories with exact comparison — use BarChart
+
+## Related components
+
+- **AreaChart** (alternative): Use a zero-baseline stacked area for precise reading
+
+## Accessibility rationale
+
+Renders role="img" with a title and a fallback data table.
+
+## Props
+
+| Name          | Type                     | Required | Default    | Description                                                           |
+| ------------- | ------------------------ | -------- | ---------- | --------------------------------------------------------------------- |
+| `series`      | `StreamSeries[]`         | Yes      | —          | Series, each with values[] aligned to categories.                     |
+| `categories`  | `(string \| number)[]`   | Yes      | —          | X-axis labels aligned with each series values.                        |
+| `title`       | `string`                 | Yes      | —          | Title text for the component.                                         |
+| `description` | `string`                 | No       | —          | Supporting description text.                                          |
+| `offset`      | `'silhouette' \| 'zero'` | No       | silhouette | silhouette centers the stack (streamgraph); zero is a baseline stack. |
+| `curve`       | `Curve`                  | No       | basis      | Interpolation curve.                                                  |
+| `width`       | `number`                 | No       | —          | Width of the component.                                               |
+| `height`      | `number`                 | No       | 300        | Height of the component.                                              |
+| `legend`      | `boolean`                | No       | —          | Whether to show the legend.                                           |
+| `tooltip`     | `boolean`                | No       | —          | Whether to show tooltips on hover.                                    |
+| `className`   | `string`                 | No       | —          | Additional CSS class names merged onto the root element.              |
+| `plain`       | `boolean`                | No       | false      | When true, renders a minimal variant without chart chrome.            |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Streamgraph
+
+```jsx
+import { Stream } from '@cascivo/charts'
+;<Stream
+  title="Topics over time"
+  categories={['Jan', 'Feb', 'Mar', 'Apr']}
+  series={[
+    { id: 'a', label: 'A', values: [4, 6, 5, 8] },
+    { id: 'b', label: 'B', values: [2, 3, 7, 4] },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Stream component (chart). Streamgraph — stacked areas on a centered (silhouette) flowing baseline.
+
+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).
+
+Stream is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/sunburst.md

@@ -0,0 +1,93 @@
+# Sunburst
+
+**Category:** chart  
+**Description:** Radial hierarchy — concentric rings where each node is an annular segment sized by value.
+
+## When to use
+
+- Showing a part-of-whole hierarchy across multiple levels
+- A radial alternative to a Treemap for nested proportions
+
+## When NOT to use
+
+- A flat set of proportions — use PieChart
+- Precise leaf comparison — use a Treemap or bars
+
+## Related components
+
+- **Treemap** (alternative): Use the rectilinear layout for dense leaves
+
+## Accessibility rationale
+
+Renders role="img" with a title and a fallback path/value table.
+
+## Props
+
+| Name          | Type       | Required | Default | Description                                                       |
+| ------------- | ---------- | -------- | ------- | ----------------------------------------------------------------- |
+| `data`        | `HierNode` | Yes      | —       | Root of the tree; leaves carry value, parents sum their children. |
+| `title`       | `string`   | Yes      | —       | Title text for the component.                                     |
+| `description` | `string`   | No       | —       | Supporting description text.                                      |
+| `size`        | `number`   | No       | —       | Square shorthand (width === height).                              |
+| `width`       | `number`   | No       | —       | Width of the component.                                           |
+| `height`      | `number`   | No       | 300     | Height of the component.                                          |
+| `tooltip`     | `boolean`  | No       | —       | Whether to show tooltips on hover.                                |
+| `className`   | `string`   | No       | —       | Additional CSS class names merged onto the root element.          |
+| `plain`       | `boolean`  | No       | false   | When true, renders a minimal variant without chart chrome.        |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Sunburst
+
+```jsx
+import { Sunburst } from '@cascivo/charts'
+;<Sunburst
+  title="Disk usage"
+  data={{
+    label: 'root',
+    children: [
+      {
+        label: 'src',
+        children: [
+          { label: 'app', value: 40 },
+          { label: 'lib', value: 25 },
+        ],
+      },
+      { label: 'docs', value: 15 },
+    ],
+  }}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Sunburst component (chart). Radial hierarchy — concentric rings where each node is an annular segment sized by value.
+
+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).
+
+Sunburst is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate nodes)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/treemap.md

@@ -0,0 +1,84 @@
+# Treemap
+
+**Category:** chart  
+**Description:** Squarified treemap for visualizing part-to-whole hierarchical data.
+
+## When to use
+
+- Showing part-to-whole proportions across many segments in a compact area
+- Visualising hierarchical magnitude where slice size encodes value
+
+## When NOT to use
+
+- Few segments where a simple split reads better — use PieChart for ≤5
+- Precise value comparison — area encoding is approximate
+
+## Related components
+
+- **PieChart** (alternative): Use for part-of-whole with five or fewer flat segments
+- **Heatmap** (alternative): Use for magnitude across a two-dimensional grid
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                             | Required | Default | Description                                                           |
+| ------------- | ------------------------------------------------ | -------- | ------- | --------------------------------------------------------------------- |
+| `data`        | `{ id: string; label: string; value: number }[]` | Yes      | —       | The hierarchical data to render as nested rectangles.                 |
+| `title`       | `string`                                         | Yes      | —       | Title text for the component.                                         |
+| `description` | `string`                                         | No       | —       | Supporting description text.                                          |
+| `width`       | `number`                                         | No       | —       | Width of the component.                                               |
+| `height`      | `number`                                         | No       | 320     | Height of the component.                                              |
+| `className`   | `string`                                         | No       | —       | Additional CSS class names merged onto the root element.              |
+| `plain`       | `boolean`                                        | No       | false   | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+- `--cascivo-chart-3`
+- `--cascivo-chart-4`
+- `--cascivo-chart-5`
+- `--cascivo-chart-6`
+- `--cascivo-chart-7`
+- `--cascivo-chart-8`
+
+## Examples
+
+### Basic treemap
+
+```jsx
+import { Treemap } from '@cascivo/charts'
+
+const data = [
+  {id:'a',label:'Alpha',value:40},
+  {id:'b',label:'Beta',value:25},
+  {id:'c',label:'Gamma',value:20},
+  {id:'d',label:'Delta',value:15},
+]
+<Treemap data={data} title="Market share" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Treemap component (chart). Squarified treemap for visualizing part-to-whole hierarchical 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).
+
+Treemap is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2, --cascivo-chart-3, --cascivo-chart-4, --cascivo-chart-5, --cascivo-chart-6, --cascivo-chart-7, --cascivo-chart-8
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chat-bubble.md

@@ -0,0 +1,116 @@
+# ChatBubble
+
+**Category:** display  
+**Description:** Message bubble for chat and messaging UIs with avatar, name, and timestamp support
+
+## When to use
+
+- Chat UIs and messaging features showing conversation history
+- Comment threads with a bubble-style layout
+- Customer support widgets displaying agent and user messages
+
+## When NOT to use
+
+- General content cards without a conversational context — use Card
+- Inline comments that do not need a bubble visual treatment
+
+## Anti-patterns
+
+### ChatBubble implies a back-and-forth conversation; use Card for standalone content pieces
+
+**Bad:** `Using ChatBubble for notification cards or feed items`  
+**Good:** `<Card> or <Alert> for non-conversational content`  
+**Why:** ChatBubble implies a back-and-forth conversation; use Card for standalone content pieces
+
+## Related components
+
+- **Card** (alternative): Use for general content display that is not part of a conversation
+- **Avatar** (pairs-with): Pass an Avatar as the avatar prop to identify the message sender
+
+## Accessibility rationale
+
+Pure layout component with role="none". Wrap a list of ChatBubble elements in an element with role="log" and aria-live="polite" to announce new messages to screen readers.
+
+## Props
+
+| Name        | Type               | Required | Default | Description                                              |
+| ----------- | ------------------ | -------- | ------- | -------------------------------------------------------- |
+| `children`  | `React.ReactNode`  | Yes      | —       | Content rendered inside the component.                   |
+| `side`      | `'start' \| 'end'` | No       | start   | Edge the component is anchored to.                       |
+| `avatar`    | `React.ReactNode`  | No       | —       | Avatar element shown beside the message.                 |
+| `name`      | `string`           | No       | —       | Display name of the message sender.                      |
+| `time`      | `string`           | No       | —       | Timestamp text shown with the message.                   |
+| `className` | `string`           | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-content`
+- `--cascivo-radius-overlay`
+- `--cascivo-radius-indicator`
+
+## Examples
+
+### Incoming message
+
+Message from another user, aligned to the start
+
+```jsx
+<ChatBubble side="start" name="Alice" time="10:42 AM">
+  Hey, how are you?
+</ChatBubble>
+```
+
+### Outgoing message
+
+Current user message, aligned to the end with accent background
+
+```jsx
+<ChatBubble side="end" time="10:43 AM">
+  Doing great, thanks!
+</ChatBubble>
+```
+
+### With avatar
+
+Message with an avatar beside the bubble
+
+```jsx
+<ChatBubble side="start" avatar={<Avatar src="/alice.png" size="sm" />} name="Alice">
+  See you tomorrow!
+</ChatBubble>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                      |
+| ------------ | -------- | ------------------------------------------------------------------------- |
+| avatar slot  | flexible | Accepts any ReactNode — Avatar, initials, icon, or nothing                |
+| body content | flexible | children accepts rich content including images, links, and formatted text |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ChatBubble component (display). Message bubble for chat and messaging UIs with avatar, name, and timestamp support
+
+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).
+
+ChatBubble is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-text-subtle, --cascivo-color-accent, --cascivo-color-accent-content, --cascivo-radius-overlay, --cascivo-radius-indicator
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+Flexible: avatar slot, body content.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/checkbox-card.md

@@ -0,0 +1,104 @@
+# CheckboxCard
+
+**Category:** inputs  
+**Description:** Multi-selectable card backed by a native checkbox. Use multiple independent CheckboxCards for multi-select scenarios.
+
+## When to use
+
+- Multi-select where each option needs a title and supporting description (feature toggles, add-ons)
+- Presenting selectable options as larger, scannable click targets rather than a dense checkbox list
+
+## When NOT to use
+
+- A simple labelled boolean in a form — use Checkbox
+- Choosing exactly one option from a set — use RadioCard or Radio
+
+## Anti-patterns
+
+### Each CheckboxCard is an independent native checkbox — nothing enforces a single selection across them
+
+**Bad:** `Using CheckboxCard for mutually exclusive options`  
+**Good:** `Use RadioCard so only one can be selected`  
+**Why:** Each CheckboxCard is an independent native checkbox — nothing enforces a single selection across them
+
+### The description is a single supporting line; long content breaks the card layout and scannability
+
+**Bad:** `Cramming a paragraph of marketing copy into description`  
+**Good:** `undefined`  
+**Why:** The description is a single supporting line; long content breaks the card layout and scannability
+
+## Related components
+
+- **Checkbox** (alternative): Use the plain checkbox when a title/description card is overkill
+- **RadioCard** (alternative): Use for single-select card groups
+
+## Accessibility rationale
+
+Backed by a native <input type="checkbox"> inside a <label>, so the entire card is clickable and role, checked state, Space activation, and label association come from the platform; the SVG glyph is aria-hidden as it is purely decorative
+
+## Props
+
+| Name              | Type                         | Required | Default | Description              |
+| ----------------- | ---------------------------- | -------- | ------- | ------------------------ |
+| `title`           | `ReactNode`                  | Yes      | —       | Card title               |
+| `description`     | `ReactNode`                  | No       | —       | Optional description     |
+| `checked`         | `boolean`                    | No       | —       | Controlled checked state |
+| `defaultChecked`  | `boolean`                    | No       | —       | Uncontrolled default     |
+| `onCheckedChange` | `(checked: boolean) => void` | No       | —       | Change callback          |
+| `disabled`        | `boolean`                    | No       | —       | Disables the card        |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-border`
+- `--cascivo-radius-surface`
+
+## Examples
+
+### Feature toggles
+
+Multi-select feature toggles
+
+```jsx
+<div style={{ display: 'grid', gap: 12 }}>
+  <CheckboxCard
+    title="Automated backups"
+    description="Daily snapshots, 30-day retention"
+    defaultChecked
+  />
+  <CheckboxCard title="Monitoring" description="Metrics + alerting" />
+  <CheckboxCard title="Audit log" description="Requires Team plan" disabled />
+</div>
+```
+
+## Boundaries
+
+| Area                       | Level    | Note                                                                                                |
+| -------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| controlled vs uncontrolled | flexible | Supports both checked + onCheckedChange and defaultChecked                                          |
+| token names                | strict   | Card styling resolves to --cascivo-color-accent / --cascivo-color-border / --cascivo-radius-surface |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo CheckboxCard component (inputs). Multi-selectable card backed by a native checkbox. Use multiple independent CheckboxCards for multi-select scenarios.
+
+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).
+
+CheckboxCard is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-border, --cascivo-radius-surface
+
+Accessibility: role "checkbox", WCAG 2.2-AA, keyboard: Space. Keep it AA.
+
+Do not change (strict): token names — Card styling resolves to --cascivo-color-accent / --cascivo-color-border / --cascivo-radius-surface
+Flexible: controlled vs uncontrolled.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/checkbox.md

@@ -0,0 +1,104 @@
+# Checkbox
+
+**Category:** inputs  
+**Description:** Binary toggle for forms, with indeterminate support
+
+## When to use
+
+- Selecting zero or more options from a list where each choice is independent
+- A single opt-in within a form (accept terms, subscribe) submitted alongside other fields
+- A "select all" control that needs an indeterminate (partial) state
+
+## When NOT to use
+
+- A binary setting that applies immediately on change — use Toggle
+- Choosing exactly one option from a mutually exclusive set — use Radio
+
+## Anti-patterns
+
+### Checkbox signals a form value to be submitted; Toggle signals an immediate on/off state change
+
+**Bad:** `<Checkbox label="Dark mode" /> that flips a setting live`  
+**Good:** `<Toggle label="Dark mode" />`  
+**Why:** Checkbox signals a form value to be submitted; Toggle signals an immediate on/off state change
+
+### Independent checkboxes let the user select both or neither, which a single exclusive choice should not allow
+
+**Bad:** `Two checkboxes for one either/or choice`  
+**Good:** `Use Radio for mutually exclusive options`  
+**Why:** Independent checkboxes let the user select both or neither, which a single exclusive choice should not allow
+
+## Related components
+
+- **Toggle** (alternative): Use for immediate binary settings rather than form values
+- **Radio** (alternative): Use for selecting exactly one from a mutually exclusive set
+- **CheckboxCard** (alternative): Use the card variant when each option needs a title plus description
+
+## Accessibility rationale
+
+Renders a native <input type="checkbox"> wrapped in a <label>, so role, checked/indeterminate state, Space activation, and label association come from the platform; the indeterminate visual is set on the DOM node since it is a property not an attribute
+
+## Props
+
+| Name            | Type                                         | Required | Default | Description                                                        |
+| --------------- | -------------------------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `label`         | `string`                                     | No       | —       | Text label for the control.                                        |
+| `checked`       | `boolean`                                    | No       | —       | Whether the control is checked (controlled).                       |
+| `indeterminate` | `boolean`                                    | No       | false   | When true, renders the mixed/indeterminate state.                  |
+| `disabled`      | `boolean`                                    | No       | false   | When true, disables the control and removes it from the tab order. |
+| `onChange`      | `React.ChangeEventHandler<HTMLInputElement>` | No       | —       | Called when the value changes.                                     |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-accent`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-text-on-accent`
+- `--cascivo-radius-sm`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### With label
+
+```jsx
+<Checkbox label="Accept terms" />
+```
+
+### Indeterminate
+
+```jsx
+<Checkbox label="Select all" indeterminate />
+```
+
+## Boundaries
+
+| Area               | Level    | Note                                                                                    |
+| ------------------ | -------- | --------------------------------------------------------------------------------------- |
+| native input props | flexible | Spreads InputHTMLAttributes — name, value, required, checked, onChange all pass through |
+| token names        | strict   | Control styling resolves to semantic --cascivo-color-\* / --cascivo-radius-sm tokens    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Checkbox component (inputs). Binary toggle for forms, with indeterminate support
+
+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).
+
+Checkbox is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-accent, --cascivo-color-border-strong, --cascivo-color-text-on-accent, --cascivo-radius-sm, --cascivo-focus-ring
+
+Accessibility: role "checkbox", WCAG 2.2-AA, keyboard: Space. Keep it AA.
+
+Do not change (strict): token names — Control styling resolves to semantic --cascivo-color-* / --cascivo-radius-sm tokens
+Flexible: native input props.
+
+Do not invent props, tokens, or global viewport media queries.
+```