@nurix/etna 0.18.20 → 0.18.22

package/data/harnesses/code/skills/design/data/operator-pack/surface-catalog.md

@@ -4,7 +4,7 @@ The closed set of six operator surface archetypes. Structure derivation (D28) ru
 
 Each entry carries five things: **choosing rules** (the object shapes, cardinalities, and lifecycle signals that select it), a **density modifier** (one relative step on the global tier), **composition** (the parts the surface holds and their arrangement, plus the lifecycle states that matter most here), a **navigation slot**, and an **exemplar pointer**.
 
-**Density.** The global tier — spacious · standard · dense — resolves at look time from the design.md / product-type traits (D31) and rewrites the spacing scale through the density primitive and the D6 `--spacing` remap. Each archetype then applies a single relative step on that tier: one step looser, at tier, or one step denser. Steps clamp at the scale ends (spacious … standard … dense) and never name an absolute value — an absolute override is banned (D31). Structure derivation records the relative step in each surface's `density-modifier` as a signed integer (positive = denser, `+1` / `0` / `-1`); the scaffold emits it as `data-density-step="tighter"` (+1) or `data-density-step="looser"` (-1), no attribute at 0. Modifiers compose with the behavioral dials (D4), never replace them.
+**Density.** The global tier — spacious · standard · dense — resolves at look time from the token artifact's payload / product-type traits (D31) and rewrites the spacing scale through the density primitive and the D6 `--spacing` remap. Each archetype then applies a single relative step on that tier: one step looser, at tier, or one step denser. Steps clamp at the scale ends (spacious … standard … dense) and never name an absolute value — an absolute override is banned (D31). Structure derivation records the relative step in each surface's `density-modifier` as a signed integer (positive = denser, `+1` / `0` / `-1`); the scaffold emits it as `data-density-step="tighter"` (+1) or `data-density-step="looser"` (-1), no attribute at 0. Modifiers compose with the behavioral dials (D4), never replace them.
 
 **Exemplars load just-in-time.** Every entry points at one token-pure compiling exemplar under `data/operator-pack/exemplars/<slug>.tsx`. The exemplar is read at that archetype's emission phase gate during the surfaces phase (D23) — emitting a surface of archetype X without exemplar X in context is a gate violation (D20). Exemplars are never boot-loaded.
 

package/data/harnesses/code/skills/design/references/create.md

@@ -4,7 +4,7 @@ Create is the only workflow where taste is *made*: personality synthesis, struct
 
 | Phase | Gate (must pass to open the next) | Produces |
 | --- | --- | --- |
-| intake | `phase-gate.mjs intake` | confirmed intent digest; resolved `design.md` at project root |
+| intake | `phase-gate.mjs intake` | confirmed intent digest; resolved design-tokens artifact at project root |
 | structure | `phase-gate.mjs structure` | `docs/design/structure.md` — the entity/surface map |
 | scaffold | `phase-gate.mjs scaffold` | project shell: routes, nav, state-shells, fixture wiring |
 | tokens | `phase-gate.mjs tokens` | `personality.css` + `globals.css`, full token surface |
@@ -17,13 +17,14 @@ The gate closing each phase runs the D21 rule classes decidable at that boundary
 ## intake
 
 **Purpose.** Recognize the brief, decide pack coverage, extract intent, resolve the look.
-**In → out.** the brief · the design.md library · router data → a confirmed intent digest · a `design.md` at project root (brand document + lever manifest).
-**Work.** Front gate: a project-declared identity (product-type traits) wins; otherwise the signal checklist (audience is employees / agents / analysts; the metric is task throughput, not conversion; the surfaces are queues / tables / forms / monitors), router data as a lookup assist. Build a structured intent digest — entity list, archetype guesses, density tier, substrate — every inference marked as inferred, present it once for confirmation, and ask only strategic unknowns whose answers change the design. Resolve the look design.md-first: the project's own `design.md` wins; a library entry serves on propose-confirm (proposed from resemblance, never applied silently); zero input wears the Nurix default. Materialize the resolved document at project root against [SCHEMA.md](../data/design-md/SCHEMA.md).
-**Gate — `phase-gate.mjs intake`.** The digest is confirmed and a schema-valid `design.md` exists at project root. A brief no pack covers is refused here — cleanly, with a redirect — never derived.
+**In → out.** the brief · the design.md library · `data/combinations/product-router.csv` (+ `typography.csv` · `palettes.csv` · `styles.csv` when the look is authored fresh) → a confirmed intent digest · a design-tokens artifact at project root (`design.tokens.json` + `design.resolver.json` — the look + lever manifest).
+**Work.** Front gate: a project-declared identity (product-type traits) wins; otherwise the signal checklist (audience is employees / agents / analysts; the metric is task throughput, not conversion; the surfaces are queues / tables / forms / monitors), with `data/combinations/product-router.csv` — loaded at every intake — as the recognition assist and the digest's density/archetype priors. Build a structured intent digest — entity list, archetype guesses, density tier, substrate — every inference marked as inferred, present it once for confirmation, and ask only strategic unknowns whose answers change the design. Resolve the look project-first: the project's own artifact wins; a library entry serves on propose-confirm (proposed from resemblance, never applied silently); zero input wears the Nurix default. When the look resolves to authoring a fresh artifact — not a library copy, not the default — load `typography.csv`, `palettes.csv`, and `styles.csv` (pairings, palettes, movement vocabulary) before composing it; the consumption contract is [combinations/Readme.md](../data/combinations/Readme.md). Materialize the resolved artifact at project root against [SCHEMA.md](../data/design-tokens/SCHEMA.md).
+**Gate — `phase-gate.mjs intake`.** The digest is confirmed and a schema-valid token artifact exists at project root. A brief no pack covers is refused here — cleanly, with a redirect — never derived.
 **Avoid.**
 - Deriving on silently inferred facts instead of presenting the digest for one confirmation.
 - Blanket-interviewing when the brief already declares its identity — ask only strategic unknowns.
 - Attempting a marketing / storefront / mobile-native brief instead of refusing on pack coverage.
+- Authoring a fresh look without `typography.csv` / `palettes.csv` / `styles.csv` in context — a gate violation.
 
 ## structure
 
@@ -50,15 +51,16 @@ The gate closing each phase runs the D21 rule classes decidable at that boundary
 
 ## tokens
 
-**Purpose.** Emit the complete token surface from the resolved `design.md`.
-**In → out.** `design.md` → `src/styles/personality.css` + `src/styles/globals.css`.
-**Work.** Derivation is hybrid: deterministic where the document states a value, judgment-with-recorded-rationale for gaps. The **coverage gate** `derive-personality.mjs design.md --check` fails — exit non-zero, naming the missing keys — if any of the 26 visual primitives, the 2 behavioral dials, or the emission tokens is unassigned and un-hinted. Only once it is green does `derive-personality.mjs design.md --emit src/styles/` write both files, defining the full surface — 26 primitives, 17 semantic tokens, and the 17 substrate tokens no consumable value is left to fall back to gray on — and hardening both cascade contracts (selector specificity, import order) with explanatory comments. See [personality.md](./personality.md).
+**Purpose.** Emit the complete token surface from the resolved artifact.
+**In → out.** the design-tokens artifact → `src/styles/personality.css` + `src/styles/globals.css`.
+**Work.** Derivation is hybrid: deterministic where the artifact states a value, judgment-with-recorded-rationale for gaps (a resolved hint records its rationale in the token's `$description`). Before any typography hint is resolved, `data/combinations/typography.csv` is in context; before any color hint, `palettes.csv` — the table is the floor for the resolution, and an off-table pairing or palette is allowed only with its stated reason recorded in the token's `$description`. The **coverage gate** `derive-personality.mjs <project-dir> --check` fails — exit non-zero, naming the missing paths — if any of the 26 visual primitives, the 2 behavioral dials, or the emission tokens is unassigned and un-hinted. Only once it is green does `derive-personality.mjs <project-dir> --emit <project-dir>` write both files (into `<project-dir>/src/styles/`), defining the full surface — 26 primitives, 17 semantic tokens, and the 17 substrate tokens no consumable value is left to fall back to gray on — and hardening both cascade contracts (selector specificity, import order) with explanatory comments. See [personality.md](./personality.md).
 **Gate — `phase-gate.mjs tokens`.** The coverage gate passed and both files carry the full token surface with the cascade-contract comments intact.
 **Avoid.**
 - Emitting before the coverage gate passes.
 - Leaving any of the 17 substrate tokens to fall back to shadcn-gray defaults.
 - Hardcoding a literal color, spacing, or radius instead of routing through a token.
 - Dropping the cascade-contract comments from the emitted CSS.
+- Resolving a typography or color hint without its combination table in context, or going off-table without the reason in the token's `$description`.
 
 ## fixtures
 
@@ -82,9 +84,12 @@ The gate closing each phase runs the D21 rule classes decidable at that boundary
 
 > **Just-in-time exemplar.** Each archetype's token-pure exemplar ([exemplars/](../data/operator-pack/exemplars/)) loads just-in-time at that archetype's emission gate — never at boot — because imitation proximity is highest when the exemplar sits in context at the moment of composition. Composing a surface of archetype X without exemplar X in context is a **gate violation**. Imitate the composition; the look comes from the project's personality.
 
+> **Just-in-time combination tables.** `data/combinations/charts.csv` loads at the emission gate of any surface that composes a chart; `icons.csv` loads once, at the first surface-composition gate — icon picks happen throughout. Each table is the floor for its picks: an off-table chart type or icon is allowed only with its stated reason in a code comment adjacent to the deviating pick. An unrecorded off-table pick is a **gate violation**. Contract: [combinations/Readme.md](../data/combinations/Readme.md).
+
 **Gate — `phase-gate.mjs surfaces`.** For each surface the archetype exemplar was in context, all lifecycle states are filled, and the per-surface structural rules pass (states presence, token coverage).
 **Avoid.**
 - Composing archetype X without exemplar X in context — a gate violation.
+- Composing a chart or picking an icon without its combination table in context — a gate violation.
 - Writing states as an afterthought instead of into the pre-created shells.
 - Emitting a look disjoint from the resolved personality — literals or off-scale values instead of the cascade.
 - Modals where side panels belong; a workflow a pointer alone can complete (floor P3 / P6).
@@ -110,7 +115,7 @@ Two disciplines protect what must never silently change.
 - API / data-contract shapes
 - generated files (never written into — the is-generated guard)
 
-Changing any of these requires it to be the *named subject* of a finding; they are never collateral edits. Per-project preservation extensions, if ever needed, are entries in the project's `design.md` — data, not config machinery.
+Changing any of these requires it to be the *named subject* of a finding; they are never collateral edits. Per-project preservation extensions, if ever needed, are entries in the project's token artifact payload — data, not config machinery.
 
 **Diff-scope discipline.** An improve run edits only the files its findings name; a run that touches a file outside its findings fails. Create writes the whole app — the discipline governs improve. See [improve.md](./improve.md).
 
@@ -120,7 +125,7 @@ Changing any of these requires it to be the *named subject* of a finding; they a
 | --- | --- | --- |
 | 0 | Compile. | Always — never skipped. |
 | 1 | Static whole-app checks — `preship-sweep.mjs`: the full catalog over all files, plus the mandatory procedures (viewport sweep at 375 / 768 / 1024 / 1440, copy self-audit, scope cross-check against the brief). | Every run. |
-| 2 | Deterministic render rung — `render-rung.mjs`: key surfaces rendered headlessly, the detector re-running its render-only rules (real overflow at the four viewports, effective and pixel-measured contrast, rendered token drift, actual target geometry, and the `cod-12` runtime perf budgets LCP < 2.5s and CLS < 0.1 collected via `PerformanceObserver`; INP and frame time need the interactive rung); findings through the same fix-or-classify loop. | By default when a headless browser is importable; degrades to a one-line notice otherwise. |
+| 2 | Deterministic render rung — `render-rung.mjs`: key surfaces rendered headlessly, re-running the catalog's render-only rules (real overflow at the four viewports, effective and pixel-measured contrast, rendered token drift, actual target geometry, and the `cod-12` runtime perf budgets LCP < 2.5s and CLS < 0.1 collected via `PerformanceObserver`; INP and frame time need the interactive rung); findings through the same fix-or-classify loop. | By default when a headless browser is importable; degrades to a one-line notice otherwise. |
 | 3 | Interactive dev-server / browser audit of the user's own environment. | Consent-gated — asked for, never assumed. |
 
 Model-judged screenshot self-critique is **not a rung** — no machine verdict rests on the model's own read of a screenshot. Pixel instruments (`inst-*`) supply evidence *inside* judged findings, never verdicts.

package/data/harnesses/code/skills/design/references/diagnosis.md

@@ -65,7 +65,7 @@ Neither kind outranks the other by *kind*. Severity ranks them; provenance only
 
 ## No numeric scores — a measurable before→after instead
 
-The engine never emits a score. No 0–4, no 0–100, no percentage grade — runtime scores are false precision the best practitioners avoid; the catalog's own detector output is defect *evidence*, not a number to average. Comparability comes from two things that do not pretend to a decimal: the severity rank orders the list, and the **mandatory measurable before→after** on every finding says exactly what changes.
+The engine never emits a score. No 0–4, no 0–100, no percentage grade — runtime scores are false precision the best practitioners avoid; the catalog's own machine-check output is defect *evidence*, not a number to average. Comparability comes from two things that do not pretend to a decimal: the severity rank orders the list, and the **mandatory measurable before→after** on every finding says exactly what changes.
 
 Machine-backed → numeric (`620ms → ≤500ms`; `12px → 14px`). Judged → a concrete before/after state (`AI draft renders identically to human messages → AI draft carries a disclosure chip and a muted treatment`). Banned always: "feels off," "make it cleaner," any adjective standing in for a change. `cod-13` is this contract; `self-integrity.mjs` checks that every finding carries a before→after.
 

package/data/harnesses/code/skills/design/references/hard-rules.md

@@ -2,7 +2,7 @@
 
 The hard-prose channel: every machine ban, deterministic threshold, and mandatory procedure the skill enforces, one imperative line each. This file loads into context before any design output.
 
-The backticked anchor id is the shared key: the same id names the `rules.csv` row, the detector rule key, the fixture pair, and a finding's provenance. Machine rules are absolute — a violation is fixed now, or classified as inapplicable in `docs/memory/design-decay.md`; never ignored silently. No waivers, no inline suppressions. Lines tagged `· render` are decided on the rendered surface at the render rung (pixels or DOM), not from source at edit time. Judged dimensions are diagnosed, not gated — the index at the foot points at where their judgment lives.
+The backticked anchor id is the shared key: the same id names the `rules.csv` row, the check-engine rule key, the fixture pair, and a finding's provenance. Machine rules are absolute — a violation is fixed now, or classified as inapplicable in `docs/memory/design-decay.md`; never ignored silently. No waivers, no inline suppressions. Lines tagged `· render` are decided on the rendered surface at the render rung (pixels or DOM), not from source at edit time. Judged dimensions are diagnosed, not gated — the index at the foot points at where their judgment lives.
 
 ## Typography
 
@@ -44,7 +44,7 @@ The backticked anchor id is the shared key: the same id names the `rules.csv` ro
 - `spc-02` Adjacent spacing values ≥ 25% apart.
 - `spc-03` Tap/click targets ≥ 24×24px (SC 2.5.8); ≥ 44px touch-primary; dense data rows 28px; undersized only via the ≥ 8px spacing exception (`int-11`). · render
 - `spc-04` Numeric columns right-align, text left-aligns; ban center-aligned data columns.
-- `spc-06` Corners on a fixed radius scale (2/4/6/8/12/9999), one scale per page.
+- `spc-06` Corners on a fixed radius scale (0/2/4/6/8/12/16/24/9999 — 0 = flat archetypes, 9999 = full/pill; a project's token artifact may declare a narrower scale, enforced by the drift check), one scale per page.
 - `spc-07` Dense table rows: 12px vertical cell padding + hairline dividers; buttons compact to 28px; mono numbers on every figure.
 - `spc-08` Full-viewport height uses `min-h-[100dvh]`; never `h-screen` or `100vh`.
 - `spc-09` Ban calc-percentage layout arithmetic (`calc(33% - 1rem)`); CSS Grid instead.
@@ -106,11 +106,11 @@ The backticked anchor id is the shared key: the same id names the `rules.csv` ro
 
 ## Mandatory procedures (never skip)
 
-- `proc-01` Extract levers into a `design.md` before any improve run on a foreign UI.
+- `proc-01` Extract levers into a design-tokens artifact before any improve run on a foreign UI.
 - `proc-02` Ask the reader question before any introspect run — one question, every run, never a stored default.
 - `proc-03` Run the object pass (six-archetype catalog) before screens; a small brief earns a small pass, never a skipped one.
 - `proc-04` Declare the density tier per surface archetype before emission (global tier + per-archetype modifiers).
-- `proc-05` Name the taste anchor before look decisions: project `design.md` > library entry > Nurix default.
+- `proc-05` Name the taste anchor before look decisions: project artifact > library entry > Nurix default.
 - `proc-06` Run the self-critique pass against the brief and the ban list before declaring a create run done.
 - `proc-07` Resolve the design system and persist it (`personality.css`) before any UI code.
 - `proc-08` Token-lock at emission: after resolution, no value lands outside the emitted token file.

package/data/harnesses/code/skills/design/references/improve.md

@@ -1,6 +1,6 @@
 # Improve — the engine
 
-> Loaded when the front gate routes to improve. Pairs with [diagnosis.md](diagnosis.md) (the finding source and format) and reuses [create.md](create.md)'s per-edit detector loop on apply. Improve is every change to a UI that **already exists**; [create.md](create.md) owns the case where nothing does.
+> Loaded when the front gate routes to improve. Pairs with [diagnosis.md](diagnosis.md) (the finding source and format) and closes at the same machine-check wall create's gates enforce. Improve is every change to a UI that **already exists**; [create.md](create.md) owns the case where nothing does.
 
 Improve is one engine, not a set of commands. Every improvement — a review, a polish, a full redesign, a typography-only pass — is the same engine run at a different point on three axes. The familiar verbs are parameter bindings, not sibling workflows: there is no `review.md`, no `redesign.md`.
 
@@ -29,20 +29,20 @@ A narrower or wider pass — one surface, one other dimension — is the same ta
 
 A design skill improves a UI **using the levers already in it**. Emitting design disjoint from the surrounding UI is a failure, not a style choice.
 
-The project's `design.md` is the **lever manifest** — its `lever-manifest` block (fonts, color tokens, spacing scale, radius scale, shadow levels, motion durations/easings, icon family, accent count). Read it **first**, before any diagnosis or edit.
+The project's design-tokens artifact carries the **lever manifest** — the `lever-manifest` in its `$extensions["com.nurix.design"]` payload (spacing scale, radius scale, shadow levels, motion durations/easings, icon family, accent count) plus the token-carried allowlists (the 34 color roles, the font stacks). Read it **first**, before any diagnosis or edit.
 
 ### When the UI wasn't built by this skill: extract first
 
-No `design.md` at project root ⇒ recover one from the code before touching anything.
+No token artifact (`design.tokens.json`) at project root ⇒ recover one from the code before touching anything.
 
 1. **Scan the source for what IS** — the fonts actually in use, the literal color values that recur, the spacing steps, the radii, the durations, the icon family and stroke.
-2. **Write them into a `design.md`** at project root with frontmatter `provenance: extracted`, `sourced: <date>`, populated `lever-manifest` and `design-primitives` blocks.
+2. **Write them into a design-tokens artifact** at project root — `design.tokens.json` + `design.resolver.json` per [SCHEMA.md](../data/design-tokens/SCHEMA.md), payload `provenance: extracted`, `sourced: <date>`, populated lever manifest and primitives.
 3. **Extraction records what IS, never what should be.** A UI running five fonts extracts five fonts. The reduction to two is a tier-two finding (below) — not an extraction edit.
-4. Run the coverage gate over it (`derive-personality.mjs --check`) exactly as over any other `design.md`.
+4. Run the coverage gate over it (`derive-personality.mjs <project-dir> --check`) exactly as over any other artifact.
 
 ### The jail is mechanical
 
-An improve run may emit only values inside the manifest's vocabulary — on-scale spacings, manifest fonts, manifest colors, manifest radii and durations. This is not advice. The detector's drift check reads the manifest (`detector.mjs <file> --manifest design.md`) and fails any edit that emits a value outside it, with the same fix-or-classify wall create runs into. There is no waiver.
+An improve run may emit only values inside the manifest's vocabulary — on-scale spacings, manifest fonts, manifest colors, manifest radii and durations. This is not advice. The verify sweep's drift check reads the manifest (`preship-sweep.mjs --files <touched...> --manifest design.tokens.json`) and fails any run that emitted a value outside it, with the same fix-or-classify wall create's gates run into. There is no waiver.
 
 ## Tier-two escalation: when the levers themselves are wrong
 
@@ -68,18 +68,20 @@ Diagnose-only depth stops here: the ranked list is the deliverable. Rendering it
 
 ## Apply depth: the same wall as create
 
-Every apply-depth edit passes through the **same per-edit detector loop create uses**: the default-on hook fires the detector plus the drift check on the write, injects the imperative fix-or-classify directive on any violation, and re-nudges until resolved. No improve edit is exempt. An apply run is create's emission discipline pointed at files that already exist.
+Every apply-depth run closes at the **same machine-check wall create's gates enforce**: after the last edit, run the scoped verify sweep over every file the run touched (`preship-sweep.mjs --files <touched...> --manifest design.tokens.json`), resolve every fix-or-classify finding it reports, and don't present results until it comes back clean. The wall is script-shaped — no hook fires it for you, and no run is exempt. An apply run is create's emission discipline pointed at files that already exist.
+
+When a finding names a chart, load `data/combinations/charts.csv` before fixing it; when a finding names an icon, `icons.csv` — the table is the floor for the replacement pick, and an off-table pick states its reason in the finding body. Contract: [combinations/Readme.md](../data/combinations/Readme.md). (The look tables never load here — emission is jailed to the lever manifest.)
 
 ## Diff-scope discipline
 
 An improve run edits **only the files its findings name**. A run that writes a file outside its findings fails the pre-ship scope cross-check (`preship-sweep.mjs`).
 
-The universal preservation list holds regardless of scope or depth — never silently changed: route slugs, navigation labels, form-field names and order, analytics/event identifiers, API and data-contract shapes, and generated files. Per-project additions to this list, if ever needed, are entries in the project's `design.md` — data, not run configuration.
+The universal preservation list holds regardless of scope or depth — never silently changed: route slugs, navigation labels, form-field names and order, analytics/event identifiers, API and data-contract shapes, and generated files. Per-project additions to this list, if ever needed, are entries in the project's token artifact payload — data, not run configuration.
 
 ## Run shape
 
 1. **Read the lever manifest.** Extract one from the code first if absent.
 2. **Diagnose** scoped to the run's scope, causes-first; rank; split `within-levers` from `lever-change`.
 3. **Diagnose-only** → deliver the ranked findings and stop.
-4. **Apply** → edit only the files the findings name, each through the detector loop, jailed to the manifest.
+4. **Apply** → edit only the files the findings name, then close at the verify sweep over the touched files, jailed to the manifest.
 5. **Escalate** → report the tier-two findings and offer the consented lever-authority follow-up.

package/data/harnesses/code/skills/design/references/introspect.md

@@ -9,7 +9,7 @@ Introspect produces a causal explanation, not a fix. The badness a user reports
 ## The run
 
 1. **Ask the reader.** One question, before anything else (below).
-2. **Diagnose** with `diagnosis.md`: passes run causes-first — Structure → Behavior → Perception — producing severity-ranked canonical findings. Introspect invents no diagnosis of its own.
+2. **Diagnose** with `diagnosis.md`: passes run causes-first — Structure → Behavior → Perception — producing severity-ranked canonical findings. Introspect invents no diagnosis of its own. When the audited UI renders charts, `data/combinations/charts.csv` loads into the pass — chart findings read against it, and an off-table judgment states its reason in the finding body.
 3. **Explain** each finding as a causal chain narrated the other way: from where the badness is felt (Perception) down to where its cause lives (Structure or Behavior).
 4. **Render** every finding in the reader's register.
 5. **File** the dated report; **offer** the improve handoff.