@nurix/etna 0.18.19 → 0.18.21

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

@@ -0,0 +1,428 @@
+# Personality — the look pipeline
+
+`design-tokens artifact → --check → --emit`. A look travels as a **design-tokens artifact** — three
+DTCG JSON files whose grammar, payload, and resolution rules are the frozen transport schema,
+[SCHEMA.md](../data/design-tokens/SCHEMA.md). [`derive-personality.mjs`](../scripts/derive-personality.mjs)
+is the reference consumer: `--check` is the coverage gate that must pass before `--emit` writes
+`personality.css`, `globals.css`, and the `<html>` attributes. The emitted files *are* the state —
+no sidecar cache, no intermediate document. (The design.md format exists only as the library's
+curated documentation corpus, `data/design-md/library/`; the machine path reads token files.)
+
+The look comes entirely from the cascade. A surface composes in semantic tokens (`bg-card`,
+`text-foreground`) and reads its personality from the CSS variables emission writes. Swap the
+artifact, re-emit, and every surface re-skins with zero JSX edits — the invariant the exemplars are
+validated against.
+
+Every CSS and comment excerpt in this document is pasted from a real emission of the shipped Nurix
+default (`data/design-tokens/nurix/`); gate transcripts are from real runs, with scratch paths
+shown as `<artifact-dir>`.
+
+## 1. The pipeline — artifact in, CSS out
+
+```
+design-tokens artifact ──▶ derive-personality.mjs --check ──▶ (green) ──▶ --emit <outdir>
+  design.tokens.json           the coverage gate (rules 1–12):             src/styles/personality.css
+  design.tokens.dark.json?     26 primitives + 2 dials + density tier      src/styles/globals.css
+  design.resolver.json         + 34 color roles + typography 3+6,          index-html-attributes.txt
+                               each assigned or hinted, or exit 1
+```
+
+```
+derive-personality.mjs <artifact-dir> [--check | --emit <outdir>] [--theme light|dark]
+```
+
+**The artifact.** Three files in one directory: `design.tokens.json` (the base set — primitives,
+color roles, typography, and the file-level `$extensions["com.nurix.design"]` payload carrying
+`product`, `provenance`, the dials, and the lever manifest), `design.tokens.dark.json` (only when
+the look has dark values), and `design.resolver.json`. The script resolves them in the resolver's
+deterministic order — concatenate the set files, overlay the selected theme context, resolve aliases
+after overlay — then validates or emits. File shapes, `$type` grammar, and payload spec live in
+[SCHEMA.md](../data/design-tokens/SCHEMA.md); this document covers what emission does with a
+resolved artifact.
+
+**`--check` never best-efforts.** It runs the schema's rules 1–12 and exits non-zero naming every
+offending path, so the fix is mechanical; the `tokens` phase gate (and the verify/pre-ship sweeps)
+stay shut until it is green. Over the shipped default, from the skill root,
+`node scripts/derive-personality.mjs data/design-tokens/nurix --check` prints:
+
+```
+check PASSED (data/design-tokens/nurix): rules 1–11 OK — 26 primitives, 34 color roles, typography 3+6, payload/manifest/parse-back OK — provenance=default, style=nurix, theme=light
+```
+
+Rule 12 (the emission precondition) is enforced at emit time; `--check` surfaces it as the
+outstanding-hint count (§3). A failing artifact names its gaps — this run is against a scratch copy
+of the default with one color token deleted:
+
+```
+check FAILED (<artifact-dir>): 1 issue(s)
+  - rule 4 — color.warning: missing
+```
+
+**`--emit <outdir>`** runs only over a passing artifact and refuses while any token carries a hint
+(§3). It writes three files: `<outdir>/src/styles/personality.css`, `<outdir>/src/styles/globals.css`,
+and `<outdir>/index-html-attributes.txt` — the attribute set the project's `index.html` `<html>` tag
+must carry. In real use `<outdir>` is the project root.
+
+### The emitted header is the cache record
+
+There is no sidecar state file. The header comment of the emitted `personality.css` carries the
+active personality — dials, theme, and the artifact citation with its provenance — and the `<html>`
+attributes carry the same state in markup:
+
+```css
+/* src/styles/personality.css — operator-UI personality tokens (emitted; do not hand-edit).
+ *
+ * Active personality — code is the cache. These values and the <html data-*>
+ * attributes in index.html are emitted from the design-tokens artifact. To change
+ * the look, edit design.tokens.json and re-run derive-personality.mjs --emit.
+ *   style:     nurix   (<html data-style="nurix">)   — the project's own personality (rosterless)
+ *   density:   standard   (<html data-density="standard">)
+ *   verbosity: default   (<html data-verbosity="default">)
+ *   feedback:  subtle   (<html data-feedback="subtle">)
+ *   theme:     light   (<html data-theme="light">)   — light is the default; dark is opt-in
+ *   artifact:  design.tokens.json (resolved via design.resolver.json)   — provenance: default, sourced 2026-07-04
+ *
+ * Semantic-token doctrine: components name purpose (bg-card, text-foreground, border-border);
+ * this file resolves those names to values. Components never use dark: prefixes or literal colors.
+ */
+```
+
+Recovery therefore reads two things: the token artifact (the source) and the emitted attributes
+(the active state). `index-html-attributes.txt` from the same run:
+
+```html
+<!-- Personality state lives in these <html data-*> attributes — code is the cache.
+     The design-tokens artifact is the source. To change the look, edit design.tokens.json
+     and re-run derive-personality.mjs --emit; to nudge one axis, edit an attribute here. -->
+<html
+  lang="en"
+  data-style="nurix"
+  data-density="standard"
+  data-verbosity="default"
+  data-feedback="subtle"
+  data-theme="light"
+>
+```
+
+## 2. Derivation — token paths to emitted CSS variables
+
+Leaf names are law: a `primitive.*` or `color.*` token maps 1:1 to the CSS variable of the same
+name, without the leading `--`.
+
+| Artifact source | Emitted target | Rule |
+| --- | --- | --- |
+| `primitive.<name>` (24 static) | `[data-style="<slug>"] { --<name>: … }` | 1:1 by leaf name |
+| `primitive.density-gap` / `density-inset` | governed refs `var(--density-base-gap/inset)` in `[data-style]` | the density tier writes the base (§4) |
+| `color.<name>` (34) | `:root, :root[data-theme="light"] { --<name>: … }` | 1:1 by leaf name |
+| dark set `color.<name>` | `[data-theme="dark"] { --<name>: … }` | only when the dark file ships (§5) |
+| payload `product` | `<html data-style="<slug>">` | slugified (lowercase, non-alphanumeric runs → `-`) |
+| payload `verbosity` / `feedback` / `density-tier` | `<html data-verbosity / data-feedback / data-density>` | dial → attribute |
+| payload `product-traits` | read by the front gate; **not** emitted to CSS | — |
+| `primitive.font-sans` / `font-mono`, `font-weight-normal` | `[data-style]` **and** literals in `@theme inline` | §4, two-weight discipline / no self-reference |
+| `typography.family.*` / `typography.ramp.*` | data for emitters and exemplars | reaches CSS only through the primitives it aliases |
+| — (derived at emit) | `--ease-enter`, `--ease-exit`, `--stagger-delay` | computed from `ease-default` + `duration-unit` |
+
+**The preserved-css rule.** For every emitted value the emitters prefer the token's
+`$extensions["com.nurix.design"].css` — the exact source string — so output is byte-stable across
+convert/emit round trips (an aliased token takes its target's `.css`). Absent `.css`, the schema's
+deterministic serialization applies: `dimension`/`duration` as `<value><unit>`; `number`/`fontWeight`
+as the plain number; `cubicBezier` as `cubic-bezier(x1, y1, x2, y2)`; `fontFamily` as the families
+joined with `", "`, multi-word names double-quoted; `color` as the `hex` field when srgb, else
+`oklch(…)`. The parse-back check (rule 9) guarantees the two forms agree before anything is emitted.
+
+**Derived, never stored.** Three temporal variables are computed at emit from `ease-default` and
+`duration-unit` — they are not tokens, not authored, and not gated (do not add them to an artifact):
+
+- `--ease-exit: var(--ease-default)` — departure mirrors the neutral curve.
+- `--ease-enter` — the emphasized-decelerate arrival curve `cubic-bezier(0.16, 1, 0.3, 1)` (fast
+  in, settles clean); `ease-default` is reused verbatim when it is already a decelerate curve
+  (y1 ≥ 0.9).
+- `--stagger-delay` — `duration-unit × 0.15`, rounded, clamped 0–40ms; a snappier tempo staggers
+  less.
+
+Emitted into the `[data-style]` block, directly after `ease-default`:
+
+```css
+  --ease-default: cubic-bezier(0.4,0,0.2,1);
+  --ease-enter: cubic-bezier(0.16, 1, 0.3, 1);   /* derived from ease-default */
+  --ease-exit: var(--ease-default);              /* derived: departure mirrors the neutral curve */
+  --stagger-delay: 8ms;                          /* derived: duration-unit × 0.15, clamped 0–40ms */
+```
+
+**Dial semantics.** The payload's two behavioral dials become `<html>` attributes, and
+`personality.css` carries one block per dial value setting the behavioral variables the lifecycle
+and interaction layers read:
+
+```css
+/* ── Behavioral dials (D4) — orthogonal to the visual primitives. ── */
+[data-verbosity="full"]    { --label-display: inline-flex; --helper-text-display: block; --tooltip-delay: 800ms; }
+[data-verbosity="default"] { --label-display: inline-flex; --helper-text-display: block; --tooltip-delay: 500ms; }
+[data-verbosity="compact"] { --label-display: none;        --helper-text-display: none;  --tooltip-delay: 200ms; }
+[data-verbosity="expert"]  { --label-display: none;        --helper-text-display: none;  --tooltip-delay: 0ms; }
+
+[data-feedback="subtle"]   { --feedback-press-scale: 0.99; --focus-ring-width: 2px; --focus-ring-offset: 1px; }
+[data-feedback="minimal"]  { --feedback-press-scale: 1;    --focus-ring-width: 1px; --focus-ring-offset: 0px; }
+```
+
+- `--label-display` / `--helper-text-display` — `compact`/`expert` verbosity collapse form labels
+  and helper text; `full`/`default` keep them. Field chrome reads these, not a JS branch.
+- `--tooltip-delay` — tightens with verbosity (`800ms → 0ms`).
+- `--feedback-press-scale`, `--focus-ring-width`, `--focus-ring-offset` — `minimal` feedback
+  flattens the press and thins the focus ring; `subtle` keeps the operator-default ring.
+
+The lifecycle pattern ([lifecycle.md](./lifecycle.md)) consumes the dials directly — empty-state
+richness scales with verbosity, confirmation depth rides feedback; focus and overlay discipline read
+the ring variables ([interaction.md](./interaction.md)). A component that must branch structurally
+on a dial reads the `<html>` attribute — it never duplicates the state. Density (`data-density`) is
+spatial chrome, not behavior — it composes with the dials, never replaces them (§4).
+
+## 3. Hints — provisional values that pass the gate but block emission
+
+Where a value needs judgment, the token carries a **valid provisional `$value`** plus
+`$extensions["com.nurix.design"].hint` — the intent in plain words (the full convention, with the
+JSON shape, is SCHEMA.md's hint section; payload fields are always concrete — hints exist only on
+tokens). Every gated token is in exactly one state:
+
+| State | Marker | `--check` | `--emit` |
+| --- | --- | --- | --- |
+| **assigned** | real value, no `hint` key | passes | emits |
+| **hinted** | `hint` key present | passes | **refuses**, naming every hinted path |
+| **missing** | token absent | fails, naming the key | — |
+
+A hinted artifact is checkable — the pass line counts the outstanding hints (this run: a scratch
+copy of the default with a hint added to `primitive.contrast-boost`):
+
+```
+check PASSED (<artifact-dir>): rules 1–11 OK — 26 primitives, 34 color roles, typography 3+6, payload/manifest/parse-back OK — provenance=default, style=nurix, theme=light, 1 hint(s) outstanding (emit will refuse)
+```
+
+— but not emittable. `--emit` over the same artifact:
+
+```
+emit REFUSED (<artifact-dir>): 1 unresolved hint(s) — rule 12: every gated token must be concrete before emission.
+  - primitive.contrast-boost: hint: nudge borders up a step so the dense table grid reads as a grid
+  Resolve each with judgment: set the real $value, delete the hint key, record the rationale in $description — then re-run --emit.
+```
+
+Resolving a hint is exactly that three-step: set the real `$value`, delete the `hint` key, record
+the rationale in the token's `$description` — so the resolved artifact stays self-explaining and
+re-derivable. Judgment is recorded, never silent.
+
+## 4. The substrate contracts — living with `@nurix/components`
+
+`@nurix/components/dist/styles.css` ships its own bare-`:root` token defaults and its own `@theme`
+radius scale. Two cascade contracts keep the personality in charge; both are hardened with the
+emitted in-CSS comments below and enforced by the code-and-token rules (`cod-*`) in
+[hard-rules.md](./hard-rules.md). The library's actual consumption is enumerated in
+[the substrate audit](../../../docs/brainstorm/design/u1-audit-report.md).
+
+**CASCADE CONTRACT 1 — the specificity/attribute pair.** The color tokens are emitted under a
+doubled selector, and `<html>` must carry `data-theme="light"`:
+
+```css
+/* ── Semantic + substrate color tokens — light theme. ──
+ * CASCADE CONTRACT 1: the doubled selector out-specifies the library's bare
+ * :root defaults in @nurix/components/styles.css — but ONLY because <html> carries
+ * data-theme="light". A bare :root here loses to the later library import. All 34
+ * tokens are set (D6): no consumed token falls back to a shadcn-gray default. */
+:root,
+:root[data-theme="light"] {
+```
+
+*Failure mode:* a bare `:root { --background: … }` is specificity `(0,1,0)` — the library's own
+`:root { --background: … }` is also `(0,1,0)` and imported *later*, so it wins and every surface
+silently reverts to shadcn gray. The `:root[data-theme="light"]` arm is `(0,2,0)` and out-wins — but
+only if `data-theme="light"` is actually on `<html>`; drop the attribute and the arm never matches,
+leaving only the losing bare `:root`. Both halves are load-bearing together.
+
+**CASCADE CONTRACT 2 — the four-step import order.** The emitted `globals.css` opens:
+
+```css
+/* src/styles/globals.css — Tailwind v4 glue + @theme inline mappings (emitted). */
+
+/* CASCADE CONTRACT 2: this four-step order is LOAD-BEARING. The library's
+ * styles.css ships its own :root token defaults and its own @theme radius scale;
+ * our @theme MUST come AFTER the import to win the radius scale and own every
+ * mapping. rules/frontend.md states the same order — co-authority. */
+@import "./personality.css";          /* 1. token source (must be first) */
+@import "tailwindcss";                /* 2. framework */
+@import "@nurix/components/styles.css"; /* 3. library (before our @theme) */
+
+@theme inline {                       /* 4. consumer theme — AFTER the library, so it wins */
+```
+
+*Failure mode:* put `@theme inline` (or the whole consumer theme) *before* the library import and
+the library's own `@theme` radius scale (`--radius-lg: var(--radius)`, its own offsets) comes later
+and wins — the personality `--radius` stops driving the scale and archetype radius switching breaks.
+`rules/frontend.md` states this same order — co-authority, not a restatement to
+drift from. `@theme inline` inlines each value into the generated utilities (so `bg-card` compiles
+to `background-color: var(--card)`).
+
+**The gray-fallback trap — all 34 roles, always.** Beyond the 15 semantic color tokens it maps
+(888 semantic-token class uses), the library consumes **16 more shadcn tokens** — `--popover(-foreground)`,
+`--secondary(-foreground)`, `--chart-1..5`, and the `--sidebar` family — that silently fall back to
+the shadcn-gray defaults inside `dist/styles.css` when unset: popovers, menus, secondary buttons,
+sidebars, and charts render visibly off-palette next to personality surfaces. The artifact's
+substrate group carries 17 roles covering them, and emission sets all 34 color roles every time.
+`--color-destructive-foreground` is mapped explicitly in `@theme` because the library leaves it
+unmapped.
+
+**Coverage — every token the library consumes is emitted.**
+
+| Library consumes | How | Emitted at |
+| --- | --- | --- |
+| `--radius` (283 `rounded-*`) | direct primitive + `@theme` radius scale | `[data-style]` · `@theme` |
+| shadow (`shadow-xs/sm/md/lg`, 58) | `--shadow-*` alpha rides `--shadow-intensity` | `@theme` |
+| font weight (`font-medium/semibold/bold/normal`, 139) | two-weight map to `--font-weight-strong` | `@theme` |
+| tracking (`tracking-*`, 13) | `--tracking-tight/tighter → --heading-tracking` | `@theme` |
+| spacing (all `p-*`/`gap-*`) | `--spacing` density remap | `@theme` |
+| `font-mono` (9) / `font-sans` | literal font stacks | `@theme` |
+| 15 semantic colors (888 uses) | direct token values | `:root[data-theme=light]` |
+| `--success`, `--warning` | direct token values (library ignores today — upstream gaps) | `:root[data-theme=light]` |
+| `--destructive-foreground` (unmapped by library) | explicit `--color-destructive-foreground` map | `@theme` |
+| 17 substrate (`popover`/`secondary`/`chart-1..5`/`sidebar` family) | direct token values | `:root[data-theme=light]` |
+| `--sidebar-width` / `--sidebar-width-icon` | SidebarProvider `style` prop | shell (below) |
+
+**Density — global tier composed with a per-surface relative step.** Two composed levels, pure
+cascade, no JS. The payload's `density-tier` becomes `data-density` on `<html>`, and the emitted
+blocks write only the **base** multipliers; a surface carries `data-density-step` (from its
+surface-catalog `density-modifier`, [surface-catalog.md](../data/operator-pack/surface-catalog.md),
+emitted by `scaffold.mjs`) and re-derives one relative step off whatever tier the app runs:
+
+```css
+/* ── Density: global tier → base multipliers (D31). ──
+ * The tier writes ONLY the base; --density-gap/inset resolve from it (above),
+ * so a per-surface step can re-derive relative to the tier. */
+[data-density="dense"]    { --density-base-gap: 0.85; --density-base-inset: 0.85; }
+[data-density="standard"] { --density-base-gap: 1;    --density-base-inset: 1; }
+[data-density="spacious"] { --density-base-gap: 1.15; --density-base-inset: 1.15; }
+
+/* ── Per-archetype density modifier (D31) — relative step on the tier, pure cascade, no JS. ──
+ * A surface element carries data-density-step; it re-derives one step off the
+ * inherited base. Reads --density-base-* (never itself) so it composes with the
+ * tier and never absolutely overrides it. The recomputed --density-gap flows into
+ * the library's p-*/gap-* through the @theme --spacing remap. */
+[data-density-step="tighter"] { --density-gap: calc(var(--density-base-gap) * 0.85); --density-inset: calc(var(--density-base-inset) * 0.85); }
+[data-density-step="looser"]  { --density-gap: calc(var(--density-base-gap) * 1.15); --density-inset: calc(var(--density-base-inset) * 1.15); }
+```
+
+A log-stream inside a `standard` app resolves one step denser without pinning an absolute value.
+Both levels reach the library's internals through one `@theme` line — every library `p-*`/`gap-*`
+is `calc(var(--spacing) × N)`, and `--density-gap` resolves per element (respecting a
+`data-density-step` ancestor):
+
+```css
+  /* density remap — the single line that scales ALL library spacing. Every p-*/gap-*
+   * is calc(var(--spacing) × N); driving --spacing off --density-gap flows the tier
+   * AND the per-surface density step into the library's internals. */
+  --spacing: calc(0.25rem * var(--density-gap));
+```
+
+**The two-weight discipline.** Operator UI carries exactly two font weights; the `@theme` map folds
+the library's whole weight vocabulary onto them:
+
+```css
+  /* font weight — two-weight discipline: medium/semibold/bold all resolve to the
+   * single emphasis weight; operator UI carries no third weight. normal is emitted
+   * as a literal because its theme key and the primitive share a name (no self-ref). */
+  --font-weight-normal: 400;
+  --font-weight-medium: var(--font-weight-strong);
+  --font-weight-semibold: var(--font-weight-strong);
+  --font-weight-bold: var(--font-weight-strong);
+```
+
+Fonts follow the same no-self-reference rule: `--font-sans`/`--font-mono` are emitted into `@theme`
+as literal stacks (a font is not a runtime-toggled token, and the theme key shares the primitive's
+name), while `personality.css` carries the same variables for direct `var()` use.
+
+**Sidebar width — the style-prop seam.** The library hardcodes `--sidebar-width` /
+`--sidebar-width-icon` as inline styles, overridable only via the provider's `style` prop — the one
+layout primitive that cannot reach the library through `@theme`. The shell wires the personality
+primitives in:
+
+```tsx
+<SidebarProvider
+  style={{
+    "--sidebar-width": "var(--sidebar-width-expanded)",
+    "--sidebar-width-icon": "var(--sidebar-width-collapsed)",
+  } as React.CSSProperties}
+>
+```
+
+**Upstream gaps — expected, never worked around.** Some values live in `@nurix/components` JS, not
+CSS, so they do not follow tokens until the library adopts them. This is user-owned upstream work —
+never patched with brittle per-instance overrides:
+
+- **Chart palettes** — the d3 family hardcodes oklch/hex and ignores `--chart-1..5`; color props are
+  per-instance overridable, but the defaults are upstream. Emit `--chart-1..5` regardless, so
+  adoption is a drop-in.
+- **Status literals** — `changes-list` and `statistics` hardcode emerald/amber/sky rather than
+  `--success`/`--warning`.
+- **Motion & icon stroke** — `duration: .2/.3` and `strokeWidth: 2/1.75` are JS numbers;
+  `--duration-*` and `--icon-stroke` reach consumer-emitted markup but not library internals.
+- **Filled-control foreground** — `text-white` pinned on filled primary/destructive; the mapped
+  `--destructive-foreground` waits on the library reading it.
+
+The stance: emit the complete token surface so the library "just works" the moment it adopts each
+token; do not build an override layer that fights the library and rots.
+
+## 5. Dark and themes — the base set is light
+
+The base token set **is** the light rendering — light is never omitted, and the resolver's `light`
+context is always the empty overlay. A look with dark values ships `design.tokens.dark.json` —
+exactly the `color` group, all 34 roles, nothing else — named by the resolver's `dark` context and
+overlaid per the resolution order. When it ships, emission adds a `[data-theme="dark"]` block
+remapping all 34 roles:
+
+```css
+/* ── Dark theme — OPT-IN ONLY (this look ships a dark overlay). ──
+ * design.tokens.dark.json remaps all 34 color tokens; <html data-theme="dark">
+ * opts in. Light stays the default. */
+[data-theme="dark"] {
+```
+
+For a light-only artifact (the shipped default is one), the emitted file carries a placeholder
+comment instead:
+
+```css
+/* ── Dark theme — OPT-IN ONLY. ──
+ * Emitted only when the artifact ships a design.tokens.dark.json dark overlay.
+ * Light stays the default; this block never appears for a light-only project.
+[data-theme="dark"] {
+  --background: ...; --foreground: ...; ... all 34 tokens remapped ...
+} */
+```
+
+`--theme dark` selects the dark context and sets `<html data-theme="dark">` in the emitted
+attributes (the header's `theme:` line follows). The default is `light`; requesting dark from a
+light-only artifact fails cleanly —
+`node scripts/derive-personality.mjs data/design-tokens/nurix --check --theme dark` prints:
+
+```
+check FAILED (data/design-tokens/nurix): 1 issue(s)
+  - rule 1 — resolver: --theme dark requested but the resolver carries no dark context
+```
+
+The library's `dark:` utilities are class-based; a dark-shipping project redefines the variant to
+follow the attribute. `globals.css` carries the instruction as a comment, enabled only when dark
+ships:
+
+```css
+/* dark variant — emitted ONLY when the project ships dark; redefines the library's
+ * class-based dark to follow data-theme so the library's dark: utilities honor our
+ * convention. Absent for a light-only project.
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *)); */
+```
+
+Components never use `dark:` prefixes or literal colors regardless — the semantic tokens remap and
+every surface follows (the semantic-token doctrine in the emitted header).
+
+## 6. Precedence and provenance — which artifact gets emitted
+
+Look resolution is project-first: a `project` or `extracted` artifact wins outright; a `library`
+entry serves only when the brief names or resembles the product and the user confirms; the Nurix
+default (`data/design-tokens/nurix/`) is worn when nothing else speaks. The origin is the payload's
+`provenance` field, and the emitted header's `artifact:` line records it alongside the `sourced`
+date — so the emitted CSS always says where its look came from. The full precedence table, payload
+spec, and per-value provenance convention (`$description`) are
+[SCHEMA.md](../data/design-tokens/SCHEMA.md).

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

@@ -0,0 +1,138 @@
+# Structure derivation
+
+The second create phase. Runs after intake, before scaffold. Two steps, in order: the **object pass**, then **archetype assignment**. The output is one small, durable file — `docs/design/structure.md` — that every later phase reads and `scaffold.mjs` consumes.
+
+The pass is never skipped. A small brief earns a proportionally small pass — a two-entity brief gets a two-entity map — but it always runs. Skipping straight to layout is the characteristic structural failure: screens that look plausible and model the domain wrongly. The structure phase gate requires a populated map before scaffold opens; an empty pass fails it.
+
+## The object pass
+
+Extract the domain model from the brief. Record, per the map schema below:
+
+- **Entities** — the nouns the operator works with (Ticket, Customer, Agent, Device). Extract what the brief and its domain support; do not fabricate entities the domain lacks, and do not promote an attribute to an entity.
+- **Attributes** — the fields each entity carries.
+- **Relationships and cardinalities** — how entities connect, recorded as `{to, cardinality}` (`one-to-one`, `one-to-many`, `many-to-one`, `many-to-many`).
+- **Lifecycle states** — the ordered states an entity moves through (new → open → pending → resolved → closed). Omit for stateless entities.
+- **Unit of work** — the one entity the operator's day turns on (the ticket, the case, the job). It anchors the home surface.
+- **Core loop** — the verb sequence the operator runs on the unit of work (triage → assign → work → resolve → close).
+
+Two modeling traps, both fatal to structure:
+
+- **Metrics are not entities.** CAC, open-ticket-count, and p95-latency are instances of one Metric object, not entity rows. They render on a dashboard; they never earn their own list surface.
+- **One entity, one home.** An entity's data and actions gather on one surface, cross-linked from everywhere else — never scattered across screens.
+
+## The temporal probe
+
+Runs inside the object pass — temporal semantics are model facts, not styling facts, and the brief states none of them. Probe five questions:
+
+- **Intermediate states** — does an action pass through pending / saving / processing / awaiting-approval before its terminal state?
+- **Read-model lag** — is there delay between write and read visibility? Where yes, staleness is marked honestly downstream.
+- **Deletion semantics** — archive, trash, hard delete, or regulatory retention? Each is a different surface and a different affordance.
+- **History** — is prior state auditable or required? Its answer surfaces as a model fact — a History/audit entity, a timeline, or a versioned attribute.
+- **Failure paths** — validation, server error, disconnection, concurrent edit.
+
+Four answers land in the map's `temporal` block (`intermediate-states`, `read-model-lag`, `deletion`, `failure-paths`); history's answer lands wherever the model puts it (an entity, an attribute, a surface). The probe is what makes the lifecycle phase's states bindable — the tool spends most of its life in states the brief never mentions.
+
+## Archetype assignment
+
+Each entity and workflow claims surfaces from the closed six-archetype catalog. `data/operator-pack/surface-catalog.md` is canonical for the choosing rules, the per-archetype density modifier, and the exemplar pointer; the assignment reads them. Orientation:
+
+| archetype | claimed when |
+| --- | --- |
+| `list-detail` | a high-cardinality collection worked one item at a time — the unit of work's home |
+| `dashboard` | a read-first overview answering a few standing questions across entities (Metric instances) |
+| `entity-detail` | one rich entity's attributes, relationships, and actions gathered on a single surface |
+| `create-edit` | minting or editing one entity — a stepper that mirrors edit; templates prefill |
+| `log-stream` | append-only, high-volume, time-ordered events — read and filter, rarely edit |
+| `command-center` | a live multi-pane monitor over several entities at once, with drill-down |
+
+Membership is closed. New archetypes enter only as pack data, ledger-recorded — never invented per run.
+
+**Navigation derives from the object model, never decorated on.** Top-level nav entries are the primary entities and their home surfaces; secondary entities are reached through their parent's detail surface, not promoted. The unit of work is the home. Cap top-level entries at what stays countable on one hand — nav categories the model does not carry are a structural defect, not a convenience.
+
+## The map: `docs/design/structure.md`
+
+The derivation's whole output. Human prose above the block; the fenced `yaml structure` block is the machine contract — `scaffold.mjs` reads it, so the field names are law. Scaffold generates routes, navigation wiring, and per-surface state-shell stubs from `surfaces[]`, and keys fixture wiring off `entities[]`.
+
+```yaml structure
+unit-of-work: <entity>
+core-loop: <verb → verb → verb>
+entities:
+  - name: <Entity>
+    attributes: [<field>, ...]
+    lifecycle: [<state>, ...]        # omit for stateless entities
+    relationships:
+      - { to: <Entity>, cardinality: one-to-one | one-to-many | many-to-one | many-to-many }
+temporal:
+  intermediate-states: [<state>, ...]
+  read-model-lag: <none | description>
+  deletion: <archive | trash | hard | retained>
+  failure-paths: [validation, server-error, disconnection, concurrent-edit, ...]
+surfaces:
+  - name: <Surface>
+    archetype: list-detail | dashboard | entity-detail | create-edit | log-stream | command-center
+    route: /<path>
+    entity: <Entity>
+    density-modifier: <integer step; positive = denser; mirrors the catalog's per-archetype modifier>
+    states: [loading, empty, error, partial]   # applicable subset; data surfaces carry all four
+```
+
+## OOUX structural diagnostics
+
+Four judged diagnostics for a wrong object model (after Sophia Prater's OOUX vocabulary). Run them over the map and over any UI under review; each is a one-line detection question:
+
+- **Shapeshifter** — is one entity rendered inconsistently across surfaces? (Does a Ticket's status pill look different in the queue than in the detail?)
+- **Masked** — is an entity hidden inside another's UI, with no surface of its own? (Is Customer only ever a string on a Ticket, never its own object?)
+- **Broken** — is an entity's data or actions split across surfaces with no complete home? (Are a Device's config and its telemetry on two unrelated screens?)
+- **Isolated** — is an entity unreachable from the navigation and from its relationships? (Can the operator reach an Agent from anywhere?)
+
+These are judgment, not machine rules — no waiver, no score. A finding is raised, ranked, and fixed at the model layer, never patched at the surface.
+
+## Worked example — a ticket queue
+
+Brief: *"A support ticket queue. Agents triage incoming tickets, assign them, work them to resolution, and close them. Tickets come from customers."*
+
+```yaml structure
+unit-of-work: Ticket
+core-loop: triage → assign → work → resolve → close
+entities:
+  - name: Ticket
+    attributes: [subject, body, status, priority, channel, requester, assignee, created_at, updated_at]
+    lifecycle: [new, open, pending, resolved, closed]
+    relationships:
+      - { to: Customer, cardinality: many-to-one }
+      - { to: Agent, cardinality: many-to-one }
+  - name: Customer
+    attributes: [name, email, org]
+    relationships:
+      - { to: Ticket, cardinality: one-to-many }
+  - name: Agent
+    attributes: [name, email, role, availability]
+    relationships:
+      - { to: Ticket, cardinality: one-to-many }
+temporal:
+  intermediate-states: [assigning, saving-reply, pending-customer]
+  read-model-lag: none            # single-writer per ticket
+  deletion: archive               # tickets are retained for audit, never hard-deleted
+  failure-paths: [validation, server-error, disconnection, concurrent-edit]
+surfaces:
+  - name: Ticket Queue
+    archetype: list-detail
+    route: /tickets
+    entity: Ticket
+    density-modifier: 1
+    states: [loading, empty, error, partial]
+  - name: Ticket Detail
+    archetype: entity-detail
+    route: /tickets/:id
+    entity: Ticket
+    density-modifier: 0
+    states: [loading, empty, error, partial]
+  - name: New Ticket
+    archetype: create-edit
+    route: /tickets/new
+    entity: Ticket
+    density-modifier: -1
+    states: [loading, error]
+```
+
+Navigation: top-level is **Tickets** — the unit of work's home. Customer and Agent are reached through Ticket Detail, not promoted to top-level nav (derived, not decorated). History — the audit of status changes and replies — surfaces as a timeline on the detail, not a fifth temporal key. OOUX pass: the status pill renders identically on queue and detail (no Shapeshifter), and Customer links out to its own detail rather than living only as a string (no Masked).