@cascivo/mcp 0.1.8 → 0.3.3

package/dist/context/chart/bar-chart.md

@@ -0,0 +1,114 @@
+# BarChart
+
+**Category:** chart  
+**Description:** Bar chart with vertical/horizontal orientation, grouped or stacked modes, and multi-series support.
+
+## When to use
+
+- Comparing discrete categorical values across groups
+- Showing grouped or stacked multi-series data per category
+
+## When NOT to use
+
+- Showing trends over continuous time — use LineChart
+- Part-of-whole proportions — use PieChart for ≤5 categories
+
+## Related components
+
+- **LineChart** (alternative): Use for trends over continuous time
+- **Histogram** (alternative): Use to show the distribution of a continuous variable
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name            | Type                                                               | Required | Default  | Description                                                                                                                            |
+| --------------- | ------------------------------------------------------------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `series`        | `BarChartSeries<Datum>[]`                                          | Yes      | —        | Series array. Each series accepts an optional `color` (any CSS color) overriding the positional palette for that series/stacked layer. |
+| `x`             | `(d: Datum) => string`                                             | Yes      | —        | Accessor returning the category label for a datum.                                                                                     |
+| `y`             | `(d: Datum) => number`                                             | Yes      | —        | Accessor returning the numeric value for a datum.                                                                                      |
+| `title`         | `string`                                                           | Yes      | —        | Title text for the component.                                                                                                          |
+| `description`   | `string`                                                           | No       | —        | Supporting description text.                                                                                                           |
+| `orientation`   | `'vertical' \| 'horizontal'`                                       | No       | vertical | Layout orientation of the component.                                                                                                   |
+| `mode`          | `'grouped' \| 'stacked' \| 'percent'`                              | No       | grouped  | 'percent' stacks each category and normalizes it to 100%.                                                                              |
+| `width`         | `number`                                                           | No       | —        | Width of the component.                                                                                                                |
+| `height`        | `number`                                                           | No       | 300      | Height of the component.                                                                                                               |
+| `xTicks`        | `number`                                                           | No       | —        | Approximate number of ticks on the x-axis.                                                                                             |
+| `yTicks`        | `number`                                                           | No       | 5        | Approximate number of ticks on the y-axis.                                                                                             |
+| `xLabelEvery`   | `number`                                                           | No       | —        | Show every Nth category label (always the last) to thin a crowded x-axis.                                                              |
+| `legend`        | `boolean`                                                          | No       | —        | Whether to show the legend.                                                                                                            |
+| `tooltip`       | `boolean`                                                          | No       | —        | Whether to show tooltips on hover.                                                                                                     |
+| `tooltipFormat` | `(p: ChartPoint) => string`                                        | No       | —        | Custom tooltip formatter. The stacked default lists "label · total" + each non-zero layer in its color.                                |
+| `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.                                                                  |
+| `annotations`   | `Annotation[]`                                                     | No       | —        | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line).                                         |
+| `labels`        | `boolean \| { format?: (v: number) => string; position?: string }` | No       | —        | Print each value as a label on the mark (collision-aware, decorative/aria-hidden).                                                     |
+| `onSelect`      | `(point: ChartPoint) => void`                                      | No       | —        | Fired when a point is clicked or activated (Enter/Space) — for drill-down.                                                             |
+| `fill`          | `'solid' \| 'gradient' \| 'pattern'`                               | No       | solid    | Bar fill style — solid, a gradient, or a pattern.                                                                                      |
+| `patternKind`   | `'dots' \| 'lines' \| 'cross'`                                     | No       | —        | Pattern motif when fill="pattern".                                                                                                     |
+
+## 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 bar chart
+
+```jsx
+import { BarChart } from '@cascivo/charts'
+
+const series = [{ id: 'a', label: 'Sales', data: [{x:'Jan',y:100},{x:'Feb',y:150}] }]
+<BarChart series={series} x={d => d.x} y={d => d.y} title="Sales" />
+```
+
+### Stacked bar from row-oriented data
+
+```jsx
+import { BarChart, toStackedSeries } from '@cascivo/charts'
+
+// Pivot { label, segments[] } rows into series + x/y. Per-segment color is preserved.
+const rows = [
+  { label: 'Mon', segments: [
+    { key: 'Done', value: 5, color: 'var(--cascivo-color-success)' },
+    { key: 'Blocked', value: 2, color: 'var(--cascivo-color-destructive)' },
+  ] },
+  { label: 'Tue', segments: [
+    { key: 'Done', value: 8, color: 'var(--cascivo-color-success)' },
+    { key: 'Blocked', value: 1, color: 'var(--cascivo-color-destructive)' },
+  ] },
+]
+// Tooltip shows "Mon · 7" then each non-zero layer in its color.
+<BarChart mode="stacked" tooltip {...toStackedSeries(rows)} title="Throughput" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo BarChart component (chart). Bar chart with vertical/horizontal orientation, grouped or stacked modes, and multi-series 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).
+
+BarChart 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/chart/boxplot.md

@@ -0,0 +1,82 @@
+# Boxplot
+
+**Category:** chart  
+**Description:** Box-and-whisker plot with five-number summary and outlier dots per series.
+
+## When to use
+
+- Comparing the distribution spread, median, and quartiles across groups
+- Surfacing outliers and skew in statistical data
+
+## When NOT to use
+
+- Showing the full shape of a single distribution — use Histogram
+- Comparing single aggregate values — use BarChart
+
+## Related components
+
+- **Histogram** (alternative): Use to show the full frequency shape of one distribution
+- **BarChart** (alternative): Use when only aggregate values matter, not spread
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                                | Required | Default | Description                                                           |
+| ------------- | --------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------- |
+| `series`      | `{ id: string; label: string; values: number[] }[]` | Yes      | —       | Array of series each with raw numeric values                          |
+| `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 boxplot
+
+```jsx
+import { Boxplot } from '@cascivo/charts'
+
+const series = [
+  { id: 'a', label: 'Group A', values: [1,2,3,4,5,6,7,8,9,10] },
+  { id: 'b', label: 'Group B', values: [3,5,6,7,8,8,9,9,10,15] },
+]
+<Boxplot series={series} title="Comparison" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Boxplot component (chart). Box-and-whisker plot with five-number summary and outlier dots per series.
+
+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).
+
+Boxplot 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/chart/bubble-chart.md

@@ -0,0 +1,80 @@
+# BubbleChart
+
+**Category:** chart  
+**Description:** Bubble chart mapping x, y, and size dimensions; radius is area-proportional via sqrt scale.
+
+## When to use
+
+- Plotting three dimensions at once — x, y, and a size-encoded magnitude
+- Comparing entities where relative scale matters alongside position
+
+## When NOT to use
+
+- Showing only a 2D correlation — use ScatterChart
+- Comparing many small magnitudes where size differences are unreadable
+
+## Related components
+
+- **ScatterChart** (alternative): Use when there is no third size dimension to encode
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                                                 | Required | Default | Description                                                                                                                |
+| ------------- | -------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `series`      | `{ name: string; data: { x: number; y: number; size: number }[] }[]` | Yes      | —       | The data series to plot.                                                                                                   |
+| `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.                                                                                                   |
+| `tooltip`     | `boolean`                                                            | No       | —       | Enable hover/keyboard tooltip                                                                                              |
+| `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.                                                      |
+| `glyph`       | `GlyphShape \| ((d, seriesId) => GlyphShape)`                        | No       | —       | Point glyph shape (circle/square/diamond/triangle/cross/star) — a fixed shape or a function to encode a category by shape. |
+
+## 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 bubble chart
+
+```jsx
+import { BubbleChart } from '@cascivo/charts'
+
+const series = [{ name: 'Group A', data: [{x:1,y:2,size:10},{x:3,y:4,size:30}] }]
+<BubbleChart series={series} title="Bubble" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo BubbleChart component (chart). Bubble chart mapping x, y, and size dimensions; radius is area-proportional via sqrt scale.
+
+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).
+
+BubbleChart 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 points)/Home/End (first/last point)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/bullet.md

@@ -0,0 +1,75 @@
+# Bullet
+
+**Category:** chart  
+**Description:** Bullet chart with background range bands, measure bar, and target tick.
+
+## When to use
+
+- Showing a single measure against a target with qualitative range bands
+- Compact dashboard KPIs where space for a full gauge is limited
+
+## When NOT to use
+
+- Displaying a metric without a target or comparative range — use Kpi
+- Showing a simple completion or rated value — use Meter
+
+## Related components
+
+- **Meter** (alternative): Use for a rated value within a range without a target marker
+- **Kpi** (alternative): Use for a single headline metric with a delta
+
+## Accessibility rationale
+
+Renders with role="img" and requires a label prop for screen reader labeling.
+
+## Props
+
+| Name        | Type       | Required | Default | Description                                              |
+| ----------- | ---------- | -------- | ------- | -------------------------------------------------------- |
+| `value`     | `number`   | Yes      | —       | Current measure value                                    |
+| `target`    | `number`   | Yes      | —       | Target marker value                                      |
+| `ranges`    | `number[]` | Yes      | —       | Qualitative range breakpoints (sorted ascending)         |
+| `label`     | `string`   | Yes      | —       | Text label for the control.                              |
+| `min`       | `number`   | No       | 0       | Minimum allowed value.                                   |
+| `max`       | `number`   | No       | —       | Domain maximum (defaults to last range)                  |
+| `width`     | `number`   | No       | 300     | Width of the component.                                  |
+| `height`    | `number`   | No       | 40      | Height of the component.                                 |
+| `className` | `string`   | No       | —       | Additional CSS class names merged onto the root element. |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-color-neutral-200`
+- `--cascivo-color-neutral-300`
+- `--cascivo-color-neutral-400`
+
+## Examples
+
+### Basic bullet chart
+
+```jsx
+import { Bullet } from '@cascivo/charts'
+;<Bullet value={72} target={80} ranges={[40, 70, 100]} label="Revenue %" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Bullet component (chart). Bullet chart with background range bands, measure bar, and target tick.
+
+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).
+
+Bullet is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-color-neutral-200, --cascivo-color-neutral-300, --cascivo-color-neutral-400
+
+Accessibility: role "img", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/calendar.md

@@ -0,0 +1,79 @@
+# Calendar
+
+**Category:** chart  
+**Description:** Calendar heatmap — a week-column grid of day cells colored by value (GitHub-style).
+
+## When to use
+
+- Showing a daily value over weeks/months (activity, contributions)
+- Spotting weekly/seasonal patterns at a glance
+
+## When NOT to use
+
+- Precise daily values — use a LineChart
+- Non-date categories — use Heatmap
+
+## Related components
+
+- **Heatmap** (alternative): Use for arbitrary x/y category grids
+
+## Accessibility rationale
+
+Renders role="img" with a title and a fallback day/value table.
+
+## Props
+
+| Name          | Type               | Required | Default | Description                                                                                                              |
+| ------------- | ------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `data`        | `CalendarDatum[]`  | Yes      | —       | Days: { day: string \| Date, value }.                                                                                    |
+| `title`       | `string`           | Yes      | —       | Title text for the component.                                                                                            |
+| `description` | `string`           | No       | —       | Supporting description text.                                                                                             |
+| `from`        | `string \| Date`   | No       | —       | Range start (defaults to min day).                                                                                       |
+| `to`          | `string \| Date`   | No       | —       | Range end (defaults to max day).                                                                                         |
+| `width`       | `number`           | No       | —       | Width of the component.                                                                                                  |
+| `height`      | `number`           | No       | 160     | 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.                                                               |
+| `visualMap`   | `VisualMapOptions` | No       | —       | Map day value → CVD-safe colour (continuous or piecewise) via a keyboard-operable legend that filters the visible range. |
+
+## Tokens
+
+- `--cascivo-chart-2`
+
+## Examples
+
+### Contribution calendar
+
+```jsx
+import { Calendar } from '@cascivo/charts'
+;<Calendar
+  title="Activity"
+  data={[
+    { day: '2026-01-01', value: 3 },
+    { day: '2026-01-02', value: 7 },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Calendar component (chart). Calendar heatmap — a week-column grid of day cells colored by value (GitHub-style).
+
+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).
+
+Calendar is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-2
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate days)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/candlestick.md

@@ -0,0 +1,104 @@
+# Candlestick
+
+**Category:** chart  
+**Description:** OHLC financial chart — each period a high–low wick and an open↔close body, coloured up/down.
+
+## When to use
+
+- Showing open/high/low/close price movement over time
+- Financial or trading dashboards needing per-period range + direction
+
+## When NOT to use
+
+- A single value trend — use LineChart
+- Non-financial categorical data — use BarChart
+
+## Related components
+
+- **LineChart** (alternative): Use when only the closing price trend matters
+
+## Accessibility rationale
+
+Renders with role="img"; OHLC values are in the fallback table and tooltip.
+
+## Props
+
+| Name          | Type                 | Required | Default | Description                                                                |
+| ------------- | -------------------- | -------- | ------- | -------------------------------------------------------------------------- |
+| `data`        | `CandlestickDatum[]` | Yes      | —       | One candle per period: { t, open, high, low, close, volume? }.             |
+| `title`       | `string`             | Yes      | —       | Chart title (also aria-label).                                             |
+| `description` | `string`             | No       | —       | Supporting description text.                                               |
+| `width`       | `number`             | No       | —       | Width of the component.                                                    |
+| `height`      | `number`             | No       | 320     | Height of the component.                                                   |
+| `yTicks`      | `number`             | No       | 5       | Approximate number of ticks on the y-axis.                                 |
+| `upColor`     | `string`             | No       | —       | Colour for up candles (close ≥ open).                                      |
+| `downColor`   | `string`             | No       | —       | Colour for down candles (close < open).                                    |
+| `volume`      | `boolean`            | No       | false   | Render volume bars beneath the candles.                                    |
+| `tooltip`     | `boolean`            | No       | —       | Enable hover tooltip (OHLC).                                               |
+| `className`   | `string`             | No       | —       | Additional CSS class names merged onto the root element.                   |
+| `plain`       | `boolean`            | No       | false   | Marks only — no axes. For micro/inline charts.                             |
+| `annotations` | `Annotation[]`       | No       | —       | Reference lines/bands/markers over the plot (e.g. a last-price rule).      |
+| `brush`       | `boolean`            | No       | —       | Keyboard-operable Brush below the plot to subset the candles to a window.  |
+| `dataZoom`    | `boolean`            | No       | —       | DataZoom slider below the plot — a Brush whose body also pans the window.  |
+| `zoom`        | `boolean`            | No       | —       | In-plot wheel/drag/keyboard zoom-pan (+/-/0) over the candle index window. |
+| `syncId`      | `string`             | No       | —       | Connect charts sharing this id — they mirror the zoom window.              |
+| `tooltipMode` | `'item' \| 'axis'`   | No       | item    | item (nearest candle) or axis (crosshair + OHLC at the hovered x).         |
+
+## Tokens
+
+- `--cascivo-chart-2`
+- `--cascivo-chart-4`
+- `--cascivo-chart-grid`
+
+## Examples
+
+### OHLC price series
+
+```jsx
+import { Candlestick } from '@cascivo/charts'
+;<Candlestick
+  title="ACME daily"
+  tooltip
+  data={[
+    { t: 'Mon', open: 10, high: 14, low: 9, close: 13 },
+    { t: 'Tue', open: 13, high: 15, low: 11, close: 11 },
+    { t: 'Wed', open: 11, high: 12, low: 8, close: 9 },
+  ]}
+/>
+```
+
+### Zoomable with a last-price rule
+
+```jsx
+<Candlestick
+  title="ACME daily"
+  data={candles}
+  volume
+  zoom
+  dataZoom
+  tooltipMode="axis"
+  annotations={[{ kind: 'line', axis: 'y', value: lastClose, label: '42.77' }]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Candlestick component (chart). OHLC financial chart — each period a high–low wick and an open↔close body, coloured up/down.
+
+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).
+
+Candlestick is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-2, --cascivo-chart-4, --cascivo-chart-grid
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate candles)/+/- (zoom), 0 (reset) when zoom enabled/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/chart/combo-chart.md

@@ -0,0 +1,78 @@
+# ComboChart
+
+**Category:** chart  
+**Description:** Combination bar + line chart on shared or dual y-axes.
+
+## When to use
+
+- Overlaying two related metrics with different scales (e.g. volume bars + rate line)
+- Pairing categorical totals with a continuous trend on a dual y-axis
+
+## When NOT to use
+
+- Both metrics share a scale and type — use BarChart or LineChart
+- More than two series of differing types — clarity breaks down
+
+## Related components
+
+- **BarChart** (alternative): Use when all series are categorical comparisons
+- **LineChart** (alternative): Use when all series are trends on one scale
+
+## Accessibility rationale
+
+Renders with role="img" and requires a title prop for screen reader labeling.
+
+## Props
+
+| Name          | Type                                 | Required | Default | Description                                                                                    |
+| ------------- | ------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `bars`        | `{ label: string; value: number }[]` | Yes      | —       | Bar series data                                                                                |
+| `line`        | `{ x: number; y: number }[]`         | Yes      | —       | Line series data points                                                                        |
+| `title`       | `string`                             | Yes      | —       | Title text for the component.                                                                  |
+| `description` | `string`                             | No       | —       | Supporting description text.                                                                   |
+| `secondAxis`  | `boolean`                            | No       | —       | Render line on a secondary right y-axis                                                        |
+| `width`       | `number`                             | No       | —       | Width of the component.                                                                        |
+| `height`      | `number`                             | No       | 320     | Height of the component.                                                                       |
+| `tooltip`     | `boolean`                            | No       | —       | Enable hover/keyboard tooltip                                                                  |
+| `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.                          |
+| `annotations` | `Annotation[]`                       | No       | —       | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line). |
+
+## Tokens
+
+- `--cascivo-chart-1`
+- `--cascivo-chart-2`
+
+## Examples
+
+### Basic combo chart
+
+```jsx
+import { ComboChart } from '@cascivo/charts'
+
+const bars = [{label:'Jan',value:100},{label:'Feb',value:120},{label:'Mar',value:90}]
+const line = [{x:0,y:50},{x:1,y:70},{x:2,y:60}]
+<ComboChart bars={bars} line={line} title="Sales vs Target" />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ComboChart component (chart). Combination bar + line chart on shared or dual y-axes.
+
+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).
+
+ComboChart is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-chart-1, --cascivo-chart-2
+
+Accessibility: role "img", WCAG 2.1-AA, keyboard: Tab (focus chart)/ArrowLeft/ArrowRight (navigate points)/Home/End (first/last point)/Escape (clear focus). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```