@nurix/etna 0.20.37 → 0.20.39

package/data/harnesses/code/skills/brainstorm/references/session-schema.md

@@ -1,194 +1,157 @@
-# Session schema — the single format authority
+# Session schema — the on-disk contract
 
-Load when: bootstrapping a session, writing any working-surface file, dispatching the twin, or
-interpreting detector output. The detector (`scripts/detector.mjs`) is the mechanical half of this
-contract: every rule below carrying a rule ID is machine-checked; everything else is the twin's
-semantic judgment.
+Load when: bootstrap; writing a capture entry or a dispatch line you are unsure of; relaying a detector finding. The twin reads it on every dispatch.
 
-## Folder layout
+This is the format `scripts/detector.mjs` parses, and the twin, the replay evals and the maintenance census all key on its rule ids. A line that drifts from it fails a rule or, worse, is silently not seen, so match the shapes below exactly: field names, the em dash ` — `, the arrow ` → `, the middle dot ` · `. **Every datetime is UTC in one shape, `YYYY-MM-DDTHH:MMZ`, taken from `date -u +%Y-%m-%dT%H:%MZ`:** the detector compares stamps as strings, so a local-time or differently shaped stamp makes a fresh compose read as stale, or a stale one as fresh.
 
-An open session is `docs/research/{topic}-brainstorm/` (kebab-case topic slug):
+## Layout
 
-| Path | Holds | Writer |
-| --- | --- | --- |
-| `state.md` | anchor + aspect map | twin |
-| `thesis.md` | composed claim → argument → what changed | twin |
-| `forks.md` | open questions with close conditions | twin |
-| `ledger.md` | commitments | twin |
-| `basis/` | frozen entry material | facilitator, once, at intake |
-| `fragments/` | harvest-native fragments, drafted in destination format; created on first real content | twin |
-| `ops/` | the untracked capture layer, deleted at stop | — |
-| `ops/.gitignore` | `*` — `ops/` **never** enters git [BS-OPS-01/02] | facilitator |
-| `ops/capture.md` | the facilitator's raw append ledger | facilitator |
-| `ops/sync-log.md` | the paired twin-dispatch log | both (see below) |
-| `ops/manifest.md` | the harvest manifest | twin, in the stop pipeline |
-
-On a passed harvest the folder **moves** to `docs/history/brainstorms/{topic}/`, `ops/` deleted
-first. The move is the completion marker; the user then deletes or commits the folder. A folder
-under `docs/research/` is by definition unfinished.
-
-**Write protocol (one writer per file; the sync log is paired):** the facilitator bootstraps `ops/` at intake, appends to
-`ops/capture.md`, and writes the initial `basis/` copy plus the sync-log *dispatch* lines —
-**nothing else, ever**. The twin writes every other file, at gates. The user may hand-edit anything;
-the twin diffs each file against its own last compose before rewriting and folds foreign edits in
-as first-class user signal.
-
-## state.md
+```
+docs/research/{topic}-brainstorm/
+├── state.md            twin
+├── thesis.md           twin
+├── forks.md            twin
+├── ledger.md           twin
+├── fragments/{name}.md twin, created on first real content
+├── basis/              facilitator, at intake; frozen
+└── ops/                untracked; deleted at the move
+    ├── .gitignore      facilitator, at bootstrap: the single line *
+    ├── capture.md      facilitator, every turn
+    ├── sync-log.md     dispatch lines: facilitator · result lines: twin
+    └── manifest.md     twin, at stop
+```
+
+On a passing harvest the folder moves to `docs/history/brainstorms/{topic}/` without `ops/`, and `state.md` reads `Status: harvested`.
+
+## `state.md`
 
 ```markdown
 # State
 
-- Status: open | stopping | harvested
-- Posture: mid-probe on the sync-layer aspect, three forks open
+- Status: open
+- Posture: mid-probe on the persistence aspect, two forks open
 - Started: 2026-07-08
-- Sitting: single | multi
-- Last compose: 2026-07-08T14:30Z | never
+- Sitting: single
+- Last compose: 2026-07-08T14:30Z
 
 ## Aspect map
 
-- persistence — how session state survives restarts → F1, D3
+- persistence — how cache state survives restarts → F1, D1
 - onboarding — the first-run experience → thesis
-- risks — failure modes and mitigations → none yet
+- risks — failure modes and mitigations → F2, fragment:domain-model
 ```
 
-- `Status` moves **only** forward: `open → stopping → harvested` — the twin sets `stopping` when the
-  stop pipeline begins and `harvested` at the move [BS-STATE-01].
-- The aspect map is derived per idea from the basis and edited by the user. Each aspect carries
-  `→` refs to the content covering it: fork IDs (`F#`), ledger IDs (`D#`), `thesis`,
-  `fragment:{name}`, or `none yet` (an open coverage gap — informational mid-session
-  [BS-ASPECT-01], blocking at the manifest gate [BS-ASPECT-02]). Ref *presence* is the detector's
-  half; whether the content actually covers the aspect is the twin's.
-
-## thesis.md
+| Field | Values |
+| --- | --- |
+| `Status` | `open` → `stopping` → `harvested`, forward only: the twin sets `stopping` when the stop pipeline begins and `harvested` at the move |
+| `Posture` | one line a resuming reader can act on: where the conversation is and what is next; a parked session says so here |
+| `Started` | ISO date |
+| `Sitting` | `single` · `multi` |
+| `Last compose` | the ISO datetime of the last thesis compose, equal to the thesis stamp; `never` before the first |
 
-```markdown
-# {Topic} — thesis
+Each aspect line is `- {name} — {gloss} → {refs}`, refs comma-separated: `F<n>` (a fork, open or resolved by a decision), `D<n>`, `fragment:{name}` (a file under `fragments/`), `thesis`, or `none yet`.
 
-Current as of: 2026-07-08T14:30Z
+## `thesis.md`
 
-## Claim
-## Argument
-## What changed
-```
+A title, then `Current as of: <ISO datetime>`, then the sections `## Claim`, `## Argument`, `## What changed`, in that order.
 
-Composed prose, rewritten whole at every compose, **never** appended. The three sections and the
-stamp are mandatory [BS-THESIS-01]; the stamp must equal `state.md`'s `Last compose`
-[BS-COMPOSE-01]. At the manifest gate, `Last compose` must be later than the newest
-`ops/capture.md` entry — a compose over unsynced capture is stale [BS-COMPOSE-02].
-
-## forks.md
+## `forks.md`
 
 ```markdown
-## F3 — Should reads wait for a compose? [open]
+## F2 — What happens on catalog API timeout? [open]
 
-Full self-contained prose in the user's framing.
+The cache can serve stale on timeout or propagate the error; the basis is silent on it.
 
-- Raised by: user | twin (S4) | probe | harvest
-- Closes when: a pick between wait-for-fresh and read-stale-with-warning
+- Raised by: twin (S1)
+- Closes when: an accepted failure behavior — stale-serve with a warning, or error propagation
 ```
 
-- IDs `F1, F2, …` unique, never reused [BS-FORK-01]. Status marker: `[open]` or
-  `[parked → {destination}]`. Every fork carries `Closes when:` [BS-FORK-01].
-- `Raised by: twin (S#)` must cite a reconciled sync-log entry [BS-SYNC-02].
-- **The twin deletes a resolved fork's entry** — the resolving ledger entry's `Resolves:` field is
-  the record. `forks.md` holds only open and parked forks; a ledger `Resolves: F3`
-  coexisting with an open F3 is an inconsistency [BS-FORK-02]. Parked forks survive to the
-  manifest, which must route each one [BS-MANIFEST-01].
-- The manifest gate requires zero `[open]` forks [BS-FORK-03].
+The heading's bracket is `[open]` or `[parked → {destination path}]`. `Raised by:` is `user`, `facilitator`, or `twin (S<n>)` citing the reconciled sync that raised it; a blindspot fork's body opens `Blindspot:`. A fork resolved by a decision leaves the file; the decision's `Resolves:` keeps its id.
 
-## ledger.md
+## `ledger.md`
 
 ```markdown
-## D4 — Sessions initialize in dump or interview
-
-- Decision: every session opens in dump or interview; probe and converge are mid-session moves.
-- Why: a first-time user cannot be asked to pick a posture they have no vocabulary for.
-  Declined: free initial posture — observed cold-starts stall in probe; re-evaluate if
-  session-replay evals show experienced users fighting the default.
-- How to apply: the facilitator's start calibration offers only the two entry moves.
-- Resolves: F2
+## D1 — Cache keys are per-tenant
+
+- Decision: every cache key embeds the tenant id; no shared entries.
+- Why: cross-tenant reads are a trust break, and memory cost is acceptable at current tenant
+  counts. Declined: shared keys with tenant checks at read time — a single missed check leaks
+  data; re-evaluate if memory pressure forces it.
+- How to apply: the cache module's key builder prefixes the tenant slug.
+- Resolves: F3
 ```
 
-- IDs `D1, D2, …` unique, append-only [BS-LEDGER-01]. `Decision`, `Why`, `How to apply` are
-  mandatory; `Resolves:` when the commitment closes forks. Amendments and reversals are
-  annotations plus a new entry ("Reversed by D9" on the old; D9 names what it reverses) — never a
-  rewrite. Declined options live inside `Why` per [doctrine.md](doctrine.md).
-
-## ops/capture.md
+`Decision`, `Why` and `How to apply` are required and non-empty; `Resolves` is optional. Ids are unique and never reused.
 
-The facilitator's per-turn append. Lowest possible bar: raw, unpolished, everything
-session-relevant from *both* sides (user substance and facilitator substance — diagnoses, informed
-rejections, definitions, reasoning chains), including residue judged not worth pillar filing.
-Format:
+## `ops/capture.md`
 
 ```markdown
+# Capture
+
 ---
-### T14 · 2026-07-08T14:22Z
+### T2 · 2026-07-08T14:20Z
 
-<raw notes for this turn>
+facilitator: flagged the trust concern on shared entries — a missed tenant check at read time is
+a leak, not a bug. recommended per-tenant keys; user accepted (→ D1). residue: user mentioned a
+"warm-on-deploy" idea in passing, not pursued.
 ```
 
-Turn IDs `T#` ascend, each with an ISO timestamp — the timestamp compose-freshness checks against
-[BS-COMPOSE-02]. **Never** distill here; distillation is the twin's.
-
-## ops/sync-log.md
+Entries are separated by `---`, headed `### T<n> · <ISO datetime>`, numbered in order, and labelled by speaker inside (`user (dump):`, `facilitator:`). The heading's datetime is what the manifest gate compares against the last compose.
 
-Paired-written, one pair per twin dispatch:
+## `ops/sync-log.md`
 
 ```
-S4 | gate: on-demand | dispatched: 2026-07-08T14:25Z | scope: full reconcile + compose
-S4 → reconciled | 2026-07-08T14:29Z | 4 edits · 2 new forks · 6 open · untouched: risks
+S1 | gate: start | dispatched: 2026-07-08T14:05Z | scope: bootstrap reconcile
+S1 → reconciled | 2026-07-08T14:08Z | 2 edits · 1 new fork · 2 open · untouched: risks
 ```
 
-The **facilitator** writes the dispatch line as it dispatches; the **twin** appends the result
-line (`reconciled` or `failed`) on return — **never** one author for both sides. Every dispatch
-line must acquire a result line; only the newest entry may be unpaired (in flight) [BS-SYNC-01].
-A `failed` result is surfaced to the user at the next turn break and re-run at the next gate.
+The facilitator writes the first line as it dispatches; the twin appends the second on return, `reconciled` or `failed | <ts> | <reason>`. Gates: `start` · `on-demand` · `pause` · `stop`. Ids run `S1, S2, …` across the session.
 
-## ops/manifest.md
-
-Created by the stop pipeline; gates the harvest apply:
+## `ops/manifest.md`
 
 ```markdown
 # Harvest manifest — {topic}
 
 Round: 1
-Status: proposed | approved | applied
+Status: proposed
 
 | # | What | Source | Destination | Action |
 |---|------|--------|-------------|--------|
-| 1 | consolidated source of truth | thesis + fragments + ledger | docs/features/{x}.md | create |
-| 2 | parked fork F7 | forks.md | docs/architecture/open-questions.md | append |
+| 1 | consolidated source of truth | thesis + ledger | docs/features/widget-cache.md | create |
+| 3 | parked fork F2 | forks.md | docs/architecture/open-questions.md | append |
 
 ## Uselessness test
 
-- Result: pass | fail
-- Cold-reader allowed paths: <the destination docs above>
-- Gaps: none | <named gaps → next Round>
+- Result: pass
+- Cold-reader allowed paths: docs/features/widget-cache.md, docs/architecture/open-questions.md
+- Gaps: none
 ```
 
-Every parked fork and every fragment must have a row [BS-MANIFEST-01]. `Status: approved` is set
-only after the user approves; gap fixes re-enter as a new `Round` with the same approval
-requirement. After apply, no destination doc may link into the session folder [BS-HARVEST-01];
-the move to history requires a recorded passing uselessness test [BS-USELESS-01].
-
-## Detector
+`Status` runs `proposed` → `approved` → `applied`. Every parked fork's id and every fragment's file name appear in a row's What or Source. Destinations are repository-relative paths. A gap round increments `Round`.
 
-`node scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]`
+## The detector
 
-- `session` (default) — the always-on integrity rules; run at any gate.
-- `manifest` — adds the convergence gates (zero open forks, full aspect coverage, fresh compose);
-  the twin may not construct a manifest while any of these fail.
-- `move` — adds the post-apply gates (manifest applied, uselessness pass recorded, no links into
-  scaffolding); the folder may not move while any fail.
+`node <skill>/scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]` exits `0` clean, `1` with violations listed by rule id, `2` on unusable input. Gates are cumulative: `manifest` runs the session rules too, `move` runs all. A real run always prints per-rule lines and a `clean` or `failing` summary; **empty output means the detector never ran**, which is a failed gate, never a pass.
 
-| Exit | Meaning |
-| --- | --- |
-| `0` | clean |
-| `1` | violations, listed with rule IDs |
-| `2` | unusable input |
-
-A run always prints output — per-rule lines plus a `clean`/`failing` summary, or a usage/error
-message. **Exit 0 with empty output means the detector never executed** — a failure, **never** a
-pass. Rules degrade gracefully: with no git context, `BS-OPS-02` reports `skipped` and never blocks.
-Rule IDs are stable — the twin, the evals, and the maintenance census key on them.
+| Rule | Gate | Fails when |
+| --- | --- | --- |
+| `BS-STATE-01` | session | `state.md` missing, or a field absent or invalid |
+| `BS-STATE-02` | session | no `## Aspect map`, or no parseable aspect |
+| `BS-ASPECT-01` | session | an aspect ref names no such fork, decision or fragment |
+| `BS-THESIS-01` | session | the thesis lacks its stamp or a mandated section |
+| `BS-COMPOSE-01` | session | the thesis stamp differs from `Last compose` |
+| `BS-FORK-01` | session | duplicate fork id, no `Closes when:`, or a park without destination |
+| `BS-FORK-02` | session | a decision resolves a fork still open |
+| `BS-LEDGER-01` | session | duplicate decision id, or Decision, Why or How to apply empty |
+| `BS-OPS-01` | session | `ops/.gitignore` missing or not `*` |
+| `BS-OPS-02` | session | any `ops/` file tracked by git (skipped outside git) |
+| `BS-SYNC-01` | session | a dispatch other than the newest has no result line |
+| `BS-SYNC-02` | session | a `twin (S<n>)` attribution cites a sync that never reconciled |
+| `BS-ASPECT-02` | manifest | an aspect has no content (`none yet`) |
+| `BS-COMPOSE-02` | manifest | the newest capture entry is newer than the last compose |
+| `BS-FORK-03` | manifest | any fork is open |
+| `BS-MANIFEST-01` | manifest | a parked fork or a fragment has no manifest row |
+| `BS-HARVEST-01` | move | a destination is missing, or links into the session folder |
+| `BS-USELESS-01` | move | no passing uselessness test with `Gaps: none`, or the manifest is not `applied` |
+
+When you relay a finding, name the rule id and what it means for the user, in plain words: "the last compose predates the newest capture (`BS-COMPOSE-02`), so the twin syncs before the manifest".

package/data/harnesses/code/skills/design/components/charts.md

@@ -2,75 +2,153 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Three tiers, all consuming the canonical `ChartSeries[]` / `ChartPoint` data contract (re-exported from `@nurix/components/charts`) and resolving color through tokens — no chart takes hex literals as its primary color path.
+Components: Spark, Chart, ChartErrorCard, StatusTimeline, plus the chart kernel helpers
 
-- **Tier 0 — marks only:** `spark`
-- **Tier 1 — inline charts:** `bar-graph`, `line-graph`, `pie-graph`, `progress-bar`, `sparkline`, plus the standalone families `funnel`, `gauge`, `heatmap`, `radar`, `ring`; shared chrome in `chart-primitives`
-- **Tier 2 — composable dashboard shells:** the `charts` subpath (visx-based)
+Four entry points, all resolving colour through the `--chart-*` tokens — no chart takes a hex literal as its colour path:
 
-> The old `chart` subpath (a dead recharts wrapper) was removed with the 2026-07 chart adoption — it no longer exists; the `charts` family below replaced it.
+- **Tier 0 — marks only:** `Spark` (`element/spark`) — an axis-less inline trend.
+- **Tier 1 — spec-native charts:** `Chart` (`block/chart`) — one component rendering fourteen families from a serializable `{ config, theme?, data? }` spec.
+- **Status strip:** `StatusTimeline` (`compound/status-timeline`) — one stacked bar per day, no axis; not a bar chart.
+- **Kernel:** `lib/chart-kernel` (+ `/arc`, `/colors`, `/line`) — the data contract, colour policy, formatters and geometry, for a bespoke mark neither `Chart` nor `Spark` draws.
 
 ## Spark
 
-Tier-0 inline mark — no axes, no chrome. Import from `@nurix/components/element/spark`.
+Tier-0 trend mark for a stat card or a caption — no axes, no legend, no tooltip, never a tab stop. Import from `@nurix/components/element/spark`. Install the `spark` peer family first: `@mantine/charts @mantine/core recharts`, plus `@mantine/hooks` (which `@mantine/core` peers on); no `MantineProvider` or Mantine stylesheet is needed.
 
-**Props:** `series` (`ChartSeries[]` or plain `number[]`), `type` [line|bar|pie], `filled`, `fillOpacity`, `strokeWidth` (line), `gap` (bar), `width`, `height`, `useTokens` (default false: self-contained oklch; true: `--chart-N` tokens)
+**Props:** `values` (`(number | null)[]` — a `null` is a gap, never a zero), `family` [line|area|bar|pie] (default `line`), `width` / `height` (default `100`×`30` px; a class such as `w-full` overrides the width), `color` (any CSS colour, default `currentColor`), `strokeWidth` (line and area, default `1.5`), `gap` (bar, default `2`), `colors` (pie, per slice; default the `--chart-N` palette), `animate` (default `false`), `label`
+
+- The props are a union on `family`: `strokeWidth` on bar, `gap` on line or area, `colors` off pie, and `width` or `color` on pie are type errors. A pie is a `height`×`height` square.
+- It paints in `currentColor`, so a muted caption gives a muted spark; pass `color="var(--chart-1)"` for a token colour.
+- It is `aria-hidden` until `label` names it (then `role="img"`) — a trend beside its number is decorative; a spark standing alone wants a label.
+- A table's sparkline column is `block/table`'s `TableSparkline`, never a hand-embedded `Spark`.
 
 ```tsx
-<Spark series={[4, 6, 5, 9, 7, 12]} type="line" filled width={96} height={24} />
+<Spark values={[4, 6, null, 9, 7, 12]} family="area" color="var(--chart-1)" className="w-full" />
 ```
 
-## Inline charts
+## Chart
+
+The spec-native chart. Import `Chart` from `@nurix/components/block/chart`. Install the `charts` and `animated-number` peer families first: `@visx/curve @visx/event @visx/grid @visx/group @visx/heatmap @visx/pattern @visx/responsive @visx/scale @visx/shape d3-array @number-flow/react`.
+
+**Props:** `config` (what the chart means — `version`, `family`, `title`, `format`, `overlays`, `encode`, and `x` on cartesian families), `theme` (how it is presented — `context`, `motion`, `color`, `chrome`, `interaction`, `labels`), `data` (typed by `config.family`), `loading`, `onHoverChange`, `onRangeChange`, `pinnedIndex` / `defaultPinnedIndex` / `onPinnedIndexChange`, `onValidationIssue`, `replayNonce` (bump to replay enter motion), plus `ref`, `className` and any div prop, landing on the one root in every state.
+
+- **Validation is internal and always on** — `withDefaultVersion` → `migrateSpec` → `validateChartSpec` → `diagnoseChart` → `normalize` on every render. An invalid spec never throws and never renders blank: it renders `ChartErrorCard` (`errors`, `labels`) naming the first violation's JSON Pointer. Warnings render the chart and report through `onValidationIssue`, once per distinct set.
+- **`version` is `CURRENT_VERSION` (2).** A stored spec carries its own `version`; only the JSX boundary defaults a missing one. `migrateSpec` walks a spec forward only, so a spec newer than the installed renderer is rejected, never downgraded.
+- **Every colour field takes a token slot, never a literal:** `chart-1`…`chart-5` (categorical, wrapping after five), `chart-positive`, `chart-negative`, `chart-diverging-mid`, `chart-scale-01`…`chart-scale-05`. `theme.color.palette` reorders the five categorical slots; an explicit series `color` wins over it.
+- **Size comes from the parent.** `Chart` sets only `w-full`. The `cell`/`card` backend stretches into its parent's box; the `dashboard` backend renders nothing until it measures a non-zero ancestor — an unsized parent is a silently empty chart either way.
+- **Emit-loop pre-flight:** `validateChartSpec(spec)` returns `{ ok, value | errors }`; `diagnoseChart(spec)` returns `{ errors, warnings }` over the data values (log scale over non-positive values, a palette wrap, date-like x on a category axis) — treat both as blocking before storing an artifact. `explainSpec(spec)` reports which default supplied each resolved value. `normalize` and `withDefaultVersion` are exported beside them.
+
+### Context
+
+`theme.context` is `cell`, `card` or `dashboard`; it picks density defaults, the capability envelope and the backend. An omitted context resolves from the host — `cell` inside a `data-mode="inline"` or `data-density="compact"` ancestor, otherwise `card`. **A host never implies `dashboard`**, so a dashboard-only family needs `theme: { context: "dashboard" }` or it fails validation with the recorded reason.
 
-Import via `@nurix/components/<subpath>`; each ships a matching skeleton.
+| Context | Chrome | Interaction | Motion (`auto`) | Families admitted |
+| --- | --- | --- | --- | --- |
+| `cell` | none | hover off unless turned on | none, whatever the request | line, area, bar, pie, progress, ring, gauge, stat |
+| `card` | value labels and legend, off by default | hover on, pin off | enter | line, area, bar, pie, progress, ring, gauge, stat |
+| `dashboard` | grid horizontal and both axes on; value labels and legend admissible | hover with a crosshair; `range` opt-in | full | line, area, bar, composed, scatter, funnel, heatmap-calendar, heatmap-matrix, radar |
 
-- `bar-graph` — `BarGraph`, `BarGraphSkeleton`
-- `line-graph` — `LineGraph`, `LineGraphSkeleton` (re-exports `ChartSeries`)
-- `pie-graph` — `PieGraph`, `PieGraphSkeleton` (variants pie|half-pie|doughnut|half-doughnut; doughnut variants take a `center` prop that auto-fits content in the hole)
-- `progress-bar` — `ProgressBar`, `ProgressBarSkeleton` (segmented multi-series bars; distinct from the `progress` subpath's shadcn Progress primitive)
-- `sparkline` — `Sparkline` (legacy; prefer `Spark` for new work)
+### Families and their data
 
-## Standalone chart families
+`config.family` is a closed enum, and each family takes exactly one data class. The cartesian families (`line`, `area`, `bar`, `composed`) require `x: { type: "time" | "category" | "linear", grain? }`; `scatter` requires `x: { type: "linear" | "log" | "time", grain? }`. `grain` is `hour`, `day`, `week`, `month`, `quarter` or `year`. `encode` is the one family-shaped key; an unknown key is a rejection naming the legal keys. Shared knobs keep one shape: `sort` is `"none" | "asc" | "desc"` or `{ by, order }`, `stack` is `"none" | "stacked" | "percent"`, `diverging` is `{ baseline?, positiveColor?, negativeColor? }`.
 
-Each on its own subpath with tooltip/legend/skeleton companions and full types:
+Series data is `{ series: [{ id, label, points: [{ x, y, size? }], color? }] }` — `y` may be `null`, `id` is unique and stable, series order is stacking and draw order.
 
-- `funnel` — `Funnel` (+ `FunnelTooltip`, `FunnelLegend`, `FunnelSkeleton`): ordered stage bands. **Props:** `data: FunnelData`, `orientation`, `variant` (default `halo`), `sort` (`asc` renders a pyramid), `showPercentage`/`showValues`/`showLabels`, `showDrop` (inter-stage drop-off annotation), `showTooltip`, `percentBasis` (default `first`), `color`, `layers`
-- `gauge` — `Gauge`, `Bullet`, `GaugeSkeleton`: value on a [min,max] scale. **Props:** `orientation` (arc or horizontal notch track), `value` (null renders the empty state), `min`/`max`, `zones` (threshold color bands), `target` (tick marker), `ticks`, `showTicks`/`showValues`, `valueFormat`, `centerContent` (arc only), `totalNotches`
-- `heatmap` — `Heatmap`, `HeatmapSkeleton`, `HeatmapLegend`, `HeatmapTooltip`, `HeatmapXAxis`/`HeatmapYAxis`/`HeatmapSeparator`: calendar contribution grid. **Props:** `data: HeatmapColumn[]`, `xDomain`, `layout` [fluid|fill], `binSize`, `gap`, `cornerRadius`, `levelColors` (defaults to the `--chart-scale-*` tokens)
-- `heatmap` (same subpath) — `MatrixHeatmap`, `MatrixHeatmapSkeleton`, `MatrixHeatmapLegend`, `MatrixHeatmapTooltip`: x-by-y cell matrix (`MatrixHeatmapData` dense or cell list), quantized onto the token ramp
-- `radar` — `Radar`, `RadarSkeleton`: series polygons over spider axes. **Props:** `data` (`RadarSeries[]` or `ChartSeries[]`), `metrics` (ordered axes; derived when omitted), `levels`, `scaling` [independent|shared] (default `independent` — honest mixed-unit rendering), `maxValue`, `nullMode` [zero|gap], `colors`, `size`
-- `ring` — `Ring`, `RingSkeleton`: concentric segmented progress. **Props:** `data: RingDatum[]` (innermost first), `strokeWidth`, `ringGap`, `startAngle`/`endAngle`, `lineCap`, `trackColor`, `animated`, `interactive`, `size`
+- **`line`** — multi-series lines. `encode`: `curve` [linear|smooth|step|stepAfter|stepBefore], `nulls` [gap|bridge] (default `gap`), `markers`, `diverging`, `endpointLabels`.
+- **`area`** — filled series. `encode`: `curve`, `nulls` [gap|bridge], `markers`, `diverging`, `stack`, `band: { lower, upper }` (series ids drawing a range band).
+- **`bar`** — grouped or stacked bars. `encode`: `mode` [categorical|histogram|pareto], `stack`, `horizontal`, `sort` (by `value`, `label` or a series id), `diverging`, `bins`, `binWidth`. **Histogram:** `mode: "histogram"` bins each point's raw `y` samples, so already-binned counts are binned again; `stack` and `sort` are rejected. **Pareto:** fixed descending with a cumulative-percent line; `sort` is rejected.
+- **`composed`** (dashboard) — mixed marks over one shared scale pair. `encode.series` maps each series id to `{ mark: "line" | "area" | "bar", axis?: "left" | "right" }`, at most two y axes.
+- **`scatter`** (dashboard) — x/y point field. `encode`: `yScale` [linear|log], `bubble` (reads `size`), `colorByValue`, `trend` (least-squares line), `quadrant: { x?, y?, shade? }`.
+- **`radar`** (dashboard) — series polygons over spider axes; spokes are the points' categorical `x`. `encode`: `scaling` [independent|shared], `maxValue`, `nulls` [gap|zero] (default `gap`).
+- **`pie`** (cell, card) — data `{ parts: [{ label, value, color? }] }`. `encode`: `donut`, `half`, `sort`, `maxSlices`, `otherThreshold`, `otherLabel` (Other sorts last), `minAngle`, `center` [total|none].
+- **`progress`** (cell, card) — stacked horizontal segments from `parts`, left to right; no `encode` keys; the goal tick is a `target` overlay.
+- **`funnel`** (dashboard) — ordered stage bands from `parts`, top-down. `encode`: `variant` [halo|solid] (`halo` draws concentric rings at ramping opacity), `colorMode` [single|ramp|categorical], `sort` (`asc` renders a pyramid), `showValue`, `showPercent`, `showDrop`.
+- **`gauge`** (cell, card) — data `{ value, min, max }`, the domain required. `encode`: `shape` [arc|linear|bullet], `fill` [solid|gradient|scale]. Threshold bands are `zone` overlays and the goal tick a `target` overlay — `shape: "bullet"` with zones and a target is the bullet chart. Hover is unavailable (one always-visible scalar).
+- **`ring`** (cell, card) — concentric value-vs-max rings. Data `{ rings: [{ label, value, max, color? }] }`, innermost first. `encode`: `endAngle` (narrow it for an arc-gauge look).
+- **`heatmap-calendar`** (dashboard) — contribution grid. Data `{ cells: [{ date, value }] }` with ISO dates. `encode`: `weekStartDay` (0–6), `levels`, `hideGhostCells`.
+- **`heatmap-matrix`** (dashboard) — x-by-y cell matrix on the token ramp. Data `{ cells: [{ x, y, value }] }`. `encode`: `colorScaleType` [sequential|diverging], `divergingMidpoint`, `nulls` [empty|zero|hatch] (default `empty`), `xOrder` / `yOrder` (`none`, `asc`, `desc`, `{ by, order }` or an explicit list), `aggregate` [sum|mean|max|min|count], `highlight` [none|cell|cross], `showValues`.
+- **`stat`** (cell, card) — a KPI. Data `{ value, delta?, history? }` (`history` is points). `encode.visual: { family: "line" | "bar" | "pie" | "gauge" | "ring" | "progress" }` draws a cell-scale mini-chart from stat's own data. A KPI laid out as a page unit is `Stat` (`element/stat`, see [layout](layout.md)).
 
-## Chart chrome primitives
+```tsx
+import { Chart } from "@nurix/components/block/chart";
+
+<Chart
+  config={{
+    version: 2,
+    family: "line",
+    title: "Revenue",
+    x: { type: "time", grain: "month" },
+    format: { y: { kind: "currency", currency: "USD", compact: true } },
+    encode: { curve: "smooth" },
+    overlays: [{ type: "line", y: 50000, label: "Target", color: "chart-negative" }],
+  }}
+  theme={{ context: "dashboard", chrome: { legend: "bottom" } }}
+  data={{ series: [{ id: "rev", label: "Revenue", points: [{ x: "2026-01-01", y: 42000 }, { x: "2026-02-01", y: 51000 }] }] }}
+/>
+
+<Chart
+  config={{
+    version: 2,
+    family: "gauge",
+    title: "Quota",
+    encode: { shape: "bullet" },
+    overlays: [{ type: "zone", from: 0, to: 60, color: "chart-scale-01" }, { type: "target", value: 80 }],
+  }}
+  data={{ value: 72, min: 0, max: 100 }}
+/>
+```
+
+### Chrome, interaction, overlays and labels
 
-`@nurix/components/chart-primitives` — shared tier-1 chrome: `ChartEmpty` (empty state), `ChartHoverCard` (tooltip surface; `ChartHoverCardRow`), `ChartLegend` (`ChartLegendItem`, `ChartLegendPosition`).
+The shared chart chrome — legend, tooltip, empty and error states — is set by the spec, never composed as children.
 
-## Dashboard charts (`charts` subpath)
+- **`theme.chrome`:** `grid` [none|horizontal|both], `xAxis` / `yAxis` / `yAxisRight` (`{ ticks, tickMode, format, largeNumbers, orientation }` or `false`), `legend` [none|right|bottom|inline], `valueLabels` (`true` or `{ position: "inside" | "outside", endpointOnly, total }`), `background` (a plot-area pattern). `legend` and `valueLabels` are illegal at `cell`; grid, axes and `background` are dashboard-only.
+- **`theme.interaction`:** `hover`, `pin`, `range` [none|xband|box]. `pin` is legal on bar, pie, scatter, funnel and both heatmaps; `xband` on line, area, bar and composed; `box` on scatter only. Not every handler reaches the host from every renderer — dashboard hover reaches `onHoverChange` only from the two heatmaps, pin reaches `onPinnedIndexChange` only from `funnel`, and no renderer emits `onRangeChange`.
+- **`config.overlays`:** `zone` (`from`, `to`, `color`, `label`), `target` (`value`), `line` (`x` or `y`), `dot` (`{ x, y }` or `{ resolve: "max" | "min" | "average", seriesId }`), `annotation` (`x`, `text`, `variant` [point|event]), `projection` (`seriesId`, `horizon`). Each is legal only on the families its envelope lists — `zone` on the cartesian families, scatter and gauge; `target` on line, area, bar, composed, gauge, progress and ring; `projection` on line and area.
+- **`config.format`:** `x`, `y`, `value` channels, each `{ kind: "compact" | "int" | "percent" | "currency" | "unit" | "date", … }` with optional `prefix` / `suffix`.
+- **`theme.motion`:** [none|enter|full|auto] (default `auto`, resolved by context).
+- **`theme.labels`:** every string the chart writes — `empty` ("No data"), `invalid`, `invalidName`, `more`, `didYouMean`, `total`, `loading`, `retry`.
 
-Composable visx-based shells — a shell provides scales/context, marks draw data ink, chrome and overlays compose as children. All from `@nurix/components/charts`.
+## StatusTimeline
 
-**Shells:** `AreaChart`, `BarChart` (`BarOrientation`), `LineChart`, `ScatterChart`, `ComposedChart` — plus standalone loading shells `AreaChartLoading`, `BarChartLoading`, `LineChartLoading`
+An uptime/status strip: one stacked bar per day with a shared day card on hover, focus or pin. No axis — a quantitative time series is `Chart`, a single percentage is `element/progress`. Import `StatusTimeline` and `formatDateRange` from `@nurix/components/compound/status-timeline`.
 
-**Recipes & transforms:** `Bullet`, `Histogram` (+ `computeHistogramBins`, `binsToRows`), `ParetoLine` (+ `computeParetoRows`), `BarSort`, `BarStackMode`
+**Props:** `data: StatusTimelineData[]`, `title` (a muted caption that also names the strip), `height` (px, default `50`), `spacing` [none|sm|md|lg] (default `sm`), `roundedCorners` [none|top|all] (default `top`), `isNormalized` (default `true`), `hasTrack`, `animate` (default `false`), `locale`, `labels`, `loading`, `emptyState`, `renderBar(segment, index, { day, total })`, `renderCard`, `renderEvent`, `render`
 
-**Marks:** `Area`, `RangeArea`, `Bar`, `Line` (`DivergingConfig`), `Scatter`, `SeriesBar`, `SeriesMarkers`, `ValueLabels`; curve factories `curveLinear`, `curveMonotoneX`, `curveNatural`, `curveStep`, `curveStepAfter`, `curveStepBefore` (pass to a mark's `curve` prop — never import `@visx/curve` directly)
+- One record per day: `{ day, summary?, bar: [{ intent, height }], card: [{ intent, value }], events: [{ id, name, type, from, to }] }`. `day` is an ISO date read in local time; `summary` is the card's muted header line; event `type` is `incident`, `report` or `maintenance`.
+- `isNormalized` reads `bar[].height` as a percentage of 100 per day — pass raw counts with `isNormalized={false}`, or every bar mis-fills.
+- Colour comes from `intent` (`neutral`, `info`, `success`, `warning`, `danger`) and the `--intent-*` tokens; retint by redeclaring the tokens, never a per-strip colour map.
+- `loading` renders the skeleton; there is no separate skeleton member.
+- `formatDateRange(from?, to?, { locale, labels })` formats an event's range, collapsing a same-day range.
 
-**Chrome:** `XAxis`, `YAxis`, `BarXAxis`, `BarYAxis`, `Grid`, `Background` (pattern presets), `PatternArea`, `PatternCircles`/`PatternHexagons`/`PatternLines`/`PatternWaves`
+```tsx
+<StatusTimeline
+  title="API uptime"
+  data={[{
+    day: "2026-08-07",
+    summary: "1,204 requests",
+    bar: [{ intent: "success", height: 92 }, { intent: "warning", height: 8 }],
+    card: [{ intent: "success", value: "92%" }, { intent: "warning", value: "8%" }],
+    events: [],
+  }]}
+/>
+```
 
-**Tooltip & legend:** composable subsystems re-exported whole (`./tooltip`, `./legend` internals)
+## Chart kernel
 
-**Overlays:** `ReferenceLine`, `ReferenceArea`, `ReferenceDot`, `Annotation` (`AnnotationVariant`), `ProjectionLine`, `ProfitLossLine` + `ProfitLossLegend`, `ChartBrush`
+The coherence-bearing subset of the chart core, for bespoke visualization code that must match the `Chart` system. Reach for it only for a mark neither `Chart` nor `Spark` draws; needing decimation, scatter geometry, thresholds or interaction scheduling is the signal to use a chart family — those stay unpublished.
 
-**Data contract:** `ChartPoint`, `ChartSeries`, `isChartSeriesArray`, `seriesToRows`
+- **`lib/chart-kernel`:** the data contract types `ChartSeries` (`{ id, label, points, color? }`), `ChartPoint` (`{ x, y }`), `ChartSlice`, `ColorableSeries`; the colour policy `resolveSeriesColors(series, { useTokens })` / `resolveSeriesColor(index, explicitColor?, { useTokens })`; `buildColorScale(min, max, kind)` (`sequential` by default over `--chart-scale-01..05`, or `diverging` over `--chart-negative` / `--chart-diverging-mid` / `--chart-positive`); the formatters `formatCompactNumber`, `formatPercent(ratio, precision)`, `intFmt`, `shortDateFmt`, `weekdayDateFmt`, `monthLongFmt`, `monthShortFmt`, `weekdayLongFmt`, `hmsTimeFmt`; and `isChartDataEmpty(series)`.
+- **`lib/chart-kernel/colors`:** `resolveSeriesColors`, `resolveSeriesColor` at a narrower entry.
+- **`lib/chart-kernel/arc`:** `computeSliceAngles(values, startAngle, totalAngle)`, `arcCentroid`, `buildArcPath({ cx, cy, innerRadius, outerRadius, startAngle, endAngle, padAngle?, cornerRadius? })` (wedge and ring paths), `isFullArc(startAngle, endAngle)`.
+- **`lib/chart-kernel/line`:** `resolveLineDomain(values)`, `createLineScales(config)`, `buildPolylinePoints`, `buildAreaPoints`, `buildLinePath(points, scales, curve, connectNulls)`, `buildAreaPath`, `buildBandAreaPath` — `curve` is `linear`, `smooth`, `step`, `stepAfter` or `stepBefore`.
+- Colour resolves explicit override → `var(--chart-1..5)` → self-contained `oklch` fallbacks; pass `{ useTokens: false }` only for a shell with no theme wiring, or the marks stop re-branding with the host stylesheet.
+- The formatter singletons are fixed to `en-US` at module scope and never follow the runtime locale — a localized axis builds its own `Intl` instance.
 
 ```tsx
-import { LineChart, Line, XAxis, YAxis, Grid, ReferenceLine } from "@nurix/components/charts";
-
-<LineChart series={revenue}>
-  <Grid />
-  <XAxis />
-  <YAxis />
-  <Line curve={curveMonotoneX} />
-  <ReferenceLine y={target} label="Target" />
-</LineChart>
+import { resolveSeriesColors } from "@nurix/components/lib/chart-kernel";
+import { computeSliceAngles, buildArcPath } from "@nurix/components/lib/chart-kernel/arc";
+
+const colors = resolveSeriesColors(slices);
+const angles = computeSliceAngles(slices.map((s) => s.value), 0, Math.PI * 2);
 ```