@nurix/etna 0.20.4 → 0.20.6

package/data/catalog/rules/frontend.md

@@ -4,12 +4,14 @@ Tailwind v4 + shadcn-based UI conventions for **web** apps — styling, the `@nu
 
 - **Build every UI through the `design` skill** — never hand-roll layouts; the page archetypes, the `design.md` identity system with its token artifact (`design.tokens.css`), and chrome wiring live in the skill.
 - **The brief's stated theme binds** — dark boots dark when the brief says so (recorded in the project's `design.md`); light is the default only when the brief is silent.
-- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`). **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`).
+- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`). **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`). *A recorded deviation from canonical shadcn, where primitives are vendored into `components/ui/` and edited in place: this workspace consumes a published library instead, and vendoring would fork it. Deliberate — the design skill does not "converge" it.*
 - Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin `react` / `react-dom` / `react/jsx-runtime` / `react/jsx-dev-runtime` to the app's single copy via `resolve.alias` — `@nurix/*` ship nested react, and two copies means two hook dispatchers.
 - Tailwind v4 is CSS-only — no `tailwind.config.js`, no PostCSS.
-- CSS entry `globals.css`, imports in order: `@import "./fonts.css"` (`@fontsource` registrations) → the project's `design.tokens.css` (derived from the repo-base `design.md` by the design skill's validator — **never** hand-edited) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
-- Tokens: CSS vars in `:root, :root[data-theme="light"]` and `:root[data-theme="dark"]` (both specificity 0,2,0 — armor a later bare `:root` can't defeat), consumed as semantic Tailwind tokens (`bg-card`, `text-foreground`). `globals.css` carries the active `@custom-variant dark` line; the theme attribute is `data-theme`. The library bundles `class-variance-authority`, `clsx`, `tailwind-merge` — don't re-add them.
-- Spacing in 2/4/6/8; `object-cover`; `truncate`; color through tokens — **never** hardcoded hex in components.
+- **The CSS entry is whatever the manifest names**, not a fixed filename — `globals.css`, `index.css` and `styles.css` are each conventional in different framework guides, so resolve it rather than grep for one. Imports in order: `@import "./fonts.css"` (`@fontsource` registrations) → the project's `design.tokens.css` (derived from the repo-base `design.md` by the design skill's validator — **never** hand-edited) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
+- **Dark mode is the `.dark` class on the root element**, bound as `@custom-variant dark (&:is(.dark *))` in the CSS entry — **never** a `data-theme` attribute. `@nurix/components` compiles `.dark` blocks into its distributed CSS and a consumer cannot re-key them, so an app on the attribute renders half-flipped: its own tokens invert, every library surface stays light. The switcher is three parts — a pre-paint inline script in the HTML shell (a mounted provider runs too late and the page flashes), `color-scheme: light dark`, and the persisted-preference module.
+- Tokens: raw values in `:root:not(.dark)` and `:root.dark` — **both specificity (0,2,0), and that armor is load-bearing.** Tailwind compiles `@theme` into `@layer theme` and any unlayered declaration beats a layered one, so the library's unlayered `:root`/`.dark` defeats an app's `@theme` outright and *ties* a bare `:root`/`.dark`, leaving the winner to import order. Values are then consumed as semantic Tailwind tokens (`bg-card`, `text-foreground`) through an `@theme inline` mapping layer. The library bundles `class-variance-authority`, `clsx`, `tailwind-merge` — don't re-add them.
+- **Never retune a Tailwind scale key `@nurix/components` consumes** — `--text-xs`, `--text-sm`, `--text-base`, `--text-lg`, `--text-xl`, `--text-2xl`. Its components carry raw scale utilities and its stylesheet declares no `font-size`, so those compile against *this app's* `@theme`: redefining `--text-sm` moves every button, menu item and table cell in the library at once, with nothing to report it. Change type by changing ramp tokens.
+- Spacing in 2/4/6/8; `object-cover`; `truncate`; color through tokens — **never** hardcoded hex in components, and **never a literal font size**. The type ramp and the family rules are the design skill's [`references/type-system.md`](../skills/design/references/type-system.md); `text-sm` is a scale step and is fine, `text-[13px]` is a component overruling the system.
 
 ## Component Search Order
 

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "dfcdee7d275f",
+    "fingerprint": "5e362f34919c",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.14.1",
+  "version": "3.14.2",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -25,5 +25,5 @@
     }
   ],
   "docsRoot": "docs",
-  "digest": "b3304fa7a078"
+  "digest": "410e5186a8b8"
 }

package/data/harnesses/code/rules/frontend.md

@@ -4,12 +4,14 @@ Tailwind v4 + shadcn-based UI conventions for **web** apps — styling, the `@nu
 
 - **Build every UI through the `design` skill** — never hand-roll layouts; the page archetypes, the `design.md` identity system with its token artifact (`design.tokens.css`), and chrome wiring live in the skill.
 - **The brief's stated theme binds** — dark boots dark when the brief says so (recorded in the project's `design.md`); light is the default only when the brief is silent.
-- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`). **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`).
+- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`). **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`). *A recorded deviation from canonical shadcn, where primitives are vendored into `components/ui/` and edited in place: this workspace consumes a published library instead, and vendoring would fork it. Deliberate — the design skill does not "converge" it.*
 - Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin `react` / `react-dom` / `react/jsx-runtime` / `react/jsx-dev-runtime` to the app's single copy via `resolve.alias` — `@nurix/*` ship nested react, and two copies means two hook dispatchers.
 - Tailwind v4 is CSS-only — no `tailwind.config.js`, no PostCSS.
-- CSS entry `globals.css`, imports in order: `@import "./fonts.css"` (`@fontsource` registrations) → the project's `design.tokens.css` (derived from the repo-base `design.md` by the design skill's validator — **never** hand-edited) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
-- Tokens: CSS vars in `:root, :root[data-theme="light"]` and `:root[data-theme="dark"]` (both specificity 0,2,0 — armor a later bare `:root` can't defeat), consumed as semantic Tailwind tokens (`bg-card`, `text-foreground`). `globals.css` carries the active `@custom-variant dark` line; the theme attribute is `data-theme`. The library bundles `class-variance-authority`, `clsx`, `tailwind-merge` — don't re-add them.
-- Spacing in 2/4/6/8; `object-cover`; `truncate`; color through tokens — **never** hardcoded hex in components.
+- **The CSS entry is whatever the manifest names**, not a fixed filename — `globals.css`, `index.css` and `styles.css` are each conventional in different framework guides, so resolve it rather than grep for one. Imports in order: `@import "./fonts.css"` (`@fontsource` registrations) → the project's `design.tokens.css` (derived from the repo-base `design.md` by the design skill's validator — **never** hand-edited) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
+- **Dark mode is the `.dark` class on the root element**, bound as `@custom-variant dark (&:is(.dark *))` in the CSS entry — **never** a `data-theme` attribute. `@nurix/components` compiles `.dark` blocks into its distributed CSS and a consumer cannot re-key them, so an app on the attribute renders half-flipped: its own tokens invert, every library surface stays light. The switcher is three parts — a pre-paint inline script in the HTML shell (a mounted provider runs too late and the page flashes), `color-scheme: light dark`, and the persisted-preference module.
+- Tokens: raw values in `:root:not(.dark)` and `:root.dark` — **both specificity (0,2,0), and that armor is load-bearing.** Tailwind compiles `@theme` into `@layer theme` and any unlayered declaration beats a layered one, so the library's unlayered `:root`/`.dark` defeats an app's `@theme` outright and *ties* a bare `:root`/`.dark`, leaving the winner to import order. Values are then consumed as semantic Tailwind tokens (`bg-card`, `text-foreground`) through an `@theme inline` mapping layer. The library bundles `class-variance-authority`, `clsx`, `tailwind-merge` — don't re-add them.
+- **Never retune a Tailwind scale key `@nurix/components` consumes** — `--text-xs`, `--text-sm`, `--text-base`, `--text-lg`, `--text-xl`, `--text-2xl`. Its components carry raw scale utilities and its stylesheet declares no `font-size`, so those compile against *this app's* `@theme`: redefining `--text-sm` moves every button, menu item and table cell in the library at once, with nothing to report it. Change type by changing ramp tokens.
+- Spacing in 2/4/6/8; `object-cover`; `truncate`; color through tokens — **never** hardcoded hex in components, and **never a literal font size**. The type ramp and the family rules are the design skill's [`references/type-system.md`](../skills/design/references/type-system.md); `text-sm` is a scale step and is fine, `text-[13px]` is a component overruling the system.
 
 ## Component Search Order
 

package/data/harnesses/discover/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "discover",
   "name": "discover",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "0bf7a6a6f479"
+  "digest": "15abe8b51cd9"
 }

package/data/harnesses/discover/rules/ingestion.md

@@ -292,6 +292,50 @@ the elements needing redaction change as you navigate.
 > redaction was real; the *frame* was never examined. **Never write a zero-PII assertion you did not verify
 > by looking at the image** — and prefer "redacted: <what>" over a blanket claim.)
 
+### 5.6 Reconstructing an ALGORITHM — differential testing, in separated layers
+
+§5.4 says what a *catalog* capture must dump. This is the extra bar for the harder case: a dimension
+that reconstructs **behaviour** — a scoring formula, a ranking function, a pricing calculation, a
+matcher, a state machine. A word list can be checked by reading it. An algorithm cannot: it is only
+`complete` once it has been **run against the live product on inputs chosen to break it**.
+
+**The rule.** A reconstructed algorithm is `partial` until:
+
+1. It is **executable** and committed to the corpus, not merely described in prose.
+2. It has been **differentially tested against the live product** on a real corpus plus deliberately
+   adversarial inputs — not only on the examples it was derived from.
+3. The test **separates the estimator from the feature extraction**, and the per-layer pass rates are
+   recorded separately. One aggregate number is not enough.
+4. The inputs and the product's own observed outputs are frozen in `raw/` (or beside the
+   implementation) as **re-runnable fixtures**, so a later run can repeat the comparison.
+
+**Why the layer split is the load-bearing part.** Almost every reconstruction has two independent
+places to be wrong — the *computation* and the *inputs fed to it*. Tested together they are
+indistinguishable, and the aggregate score points at whichever one you already suspect:
+
+- **Layer A — the estimator.** Feed the algorithm **the product's own reported feature values** and
+  check it reproduces the product's own output. This tests the mathematics alone.
+- **Layer B — the feature extraction.** Compare **your** computed features against the product's
+  reported features. This tests tokenisation / parsing / counting alone.
+- **Layer C — end-to-end.** Both together. C failing while A passes localises the fault to B in one
+  step, with no re-derivation of a formula that was already right.
+
+**A residual that survives a correct layer B is a finding about the TARGET, not an error in the
+reconstruction** — and it is often the most valuable thing the dimension produces. Chase it; do not
+tune it away. And when the target's behaviour is a defect, **do not silently replicate it** to make
+the numbers match: implement the correct behaviour by default and put bug-parity behind an explicit,
+documented flag. A reconstruction that quietly reproduces a bug teaches the next reader the bug.
+
+> (Origin: hemingway — the run shipped a "validated" reference implementation of the app's readability
+> scorer whose **formula was exactly right** and whose **tokenizer agreed with the target on only 41 of
+> 62 real inputs**. A single end-to-end comparison read as *"the model is wrong"* and would have sent
+> the run back to re-derive a correct formula. Splitting the test localised it immediately: layer A was
+> **62/62** from the first run, and `Δletters = 0` in 20 of the 21 layer-B divergences pinned the fault
+> to word/sentence segmentation, which was then reverse-engineered to **61/62**. The one residual that
+> survived a correct tokenizer was **a defect in the product** — a literal `...` silently deletes the
+> preceding text from every statistic — which no static lane could have found and which only appeared
+> because adversarial inputs were included.)
+
 ---
 
 ## 6. The shared-surface seam rule (bundle ↔ session ↔ wire-capture)
@@ -509,6 +553,11 @@ Downloading a public binary (CRX/`.asar`/`.ipa`/`.apk`) and reading its manifest
 
 A capture is complete when: `_summary.md` exists with full provenance frontmatter + honest `status`; **every Finding is backed by a `raw/` artifact — an inline value is NOT sufficient (§5.3)**; the dimension's **§5.4 dump manifest is satisfied verbatim**; `raw/` artifacts carry `_meta` (with `verbatim:` and, if bounded, `sampling:`); redaction pass run; `gaps` recorded (never fabricated).
 
+> **Algorithm reconstructions have an extra bar (§5.6):** if the dimension reconstructed *behaviour*
+> rather than a catalog, it is `partial` until the implementation is executable, differentially tested
+> against the live product with the **estimator and feature extraction scored as separate layers**, and
+> the inputs + observed outputs are frozen as re-runnable fixtures. Record the per-layer pass rates.
+
 > **Self-check before writing `status: complete`:** count the verbatim artifacts in `raw/`. If that count is **zero**, the dimension is `partial` no matter how good the prose is — you have written an essay, not a capture. If a Finding names a number, a path, a version, or a field, open the file that contains it; if no such file exists, write it now (§5.3).
 
 **Summary-first + bounded, visible fan-out (never go silent long enough to look dead).** Write a `status: partial` `_summary.md` with whatever is mined so far **before** any long-tail fetch loop (downloading many chunks, crawling many pages, deep pagination), then enrich it in place and flip to `complete`. **Bound** every fan-out — cap it by count / total bytes / wall-time (e.g. ≤40 items or ≤90 s) and record the remainder as a `gap` rather than fetching exhaustively; emit a progress note per batch. A collector that fetches everything before writing anything can run many times longer than its siblings and read as hung to the orchestrator, forcing a needless salvage. Partial-but-finalized beats complete-but-silent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
   "type": "module",
   "bin": {
@@ -42,5 +42,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "dfcdee7d275f"
+  "etnaFingerprint": "5e362f34919c"
 }