@nurix/etna 0.19.10 → 0.19.12

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

@@ -0,0 +1,28 @@
+# Step 3 — Content: the believable book
+
+Author the demo data **before composing surfaces**. Data credibility is the single largest scoring dimension in blind judging; this step is where builds are won.
+
+## From the corpus
+
+Load the chosen domain's corpus (`data/corpora/<domain>/`): `corpus.md` (vocabulary, number-shape recipes, the invariants block) plus `people.csv` and `companies.csv`.
+
+- Names come from the corpus roster; emails derive from names; roles are domain-correct.
+- Activity strings use the corpus vocabulary — a CRM logs "Intro call with Elena — pricing discussion", never webhook noise.
+- Numbers follow the corpus's shape recipes (log-normal deal values, plausible deltas); dates vary around the corpus's **fixed reference instant**, never around "now".
+- **Acceptance is rendered plausibility against the declared invariants**: aggregates reconcile with their rows; legal ranges hold; forbidden repetition (same surname clusters, identical amounts) never shows. The ship gate checks these mechanically — author to them now.
+- **Edge-case rows (nulls, zeros, outliers) go only into dedicated state fixtures** (`empty*`, `degraded*`), never into the primary dataset.
+
+## Voice
+
+Load the package-bound voice pack (`data/voices/<id>.md` — the package's §9 names it). All authored strings — buttons, empty states, errors, tooltips, confirmations — speak in that voice, with tone varying by situation per the pack's tone map.
+
+## Chart choice
+
+Every data-bearing surface consults the chart-selection engine — **one graph question per consult**:
+
+1. Author the data signature (the judgment half): the question, measures, dimensions, semantic flags (temporal, parts-form-whole, target-exists, …), constraints. Decompose multi-question asks first.
+2. Run `node scripts/select-chart.mjs <signature.json>` and read the typed output: admissible set, eliminations with reason codes, ranking, recommendation, or a refusal code.
+3. **Honor refusals** — a refusal means the question isn't chartable as posed (often: it's a table). Never invent a measure to force a chart.
+4. Record the pick in one line in `decisions.md`. Taking a non-recommended admissible option needs a reason on that line; taking an eliminated option is out of contract.
+
+Chart *styling* is not this step's concern — the package's §8 and the chart-styling axis own it at composition.

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

@@ -0,0 +1,21 @@
+# Package emission — design.md → token artifact
+
+One source, one derivation: the project's `design.md` is canonical; the token artifact is compiled from it and **never hand-edited**. Emit with `node scripts/validate-design-md.mjs <project design.md> --emit > design.tokens.css` (the artifact lives beside `design.md` at the repo base; the app's global stylesheet imports it). Re-emit on every design.md change; the ship gate's drift check byte-compares a fresh emission against the committed artifact.
+
+## Coverage
+
+The artifact is complete by construction — the validator fails the design.md before emission otherwise: every one of the 36 color roles in **both** themes, the full type ramp, the elevation system, the motion base, layout dimensions. Composition consumes tokens and never invents values; switching packages re-skins the whole app.
+
+## Emission constraints
+
+Each prevents a known silent-failure class:
+
+- **Specificity armor.** Theme blocks are `:root, :root[data-theme="light"]` and `:root[data-theme="dark"]` — both specificity (0,2,0) — so a component library's later bare `:root` block cannot silently defeat a theme.
+- **Font binding by derivation.** Font stacks bind to installed packages under **registered family names** (`"Inter Variable"`, not `"Inter"`), each with its declared fallback stack — otherwise the flagship font silently never renders. Install the font packages the design.md declares (e.g. Fontsource) and verify the name matches what the package registers.
+- **Every authored token group reaches a named consumer.** An authored ramp with no emitter vanishes without a trace — wire each group (colors → theme classes/utilities, ramp → text styles, elevation → radius/shadow utilities, motion → duration/easing vars) and let the ship gate's reach check prove it.
+- **Compile the emitted CSS once per change** — a stray utility string inside a CSS comment can defeat a fully green byte-level check.
+- **One linear precedence, later wins:** package defaults → brief bindings → recorded deviations. Values resolve at emission; the runtime cascade carries only contexts (theme, density).
+
+## Stack neutrality
+
+The artifact is plain CSS custom properties — every stack consumes it. Under `primitives: nurix`, Tailwind maps the properties through the theme config; under `native`, the incumbent styling layer reads the same variables. No emission step is React-specific.

package/data/harnesses/code/skills/design/references/existing-apps.md

@@ -0,0 +1,27 @@
+# Improve, judge, and extract on existing apps
+
+The same machinery runs on existing UIs, under a preservation contract.
+
+## Judge — a user-invoked service
+
+A critique of an existing UI against the brief, the project's `design.md`, the archetype checklists, and `taste.md`, producing a **severity-ranked (never scored) report**. Judge is a service the user asks for — never a self-check the skill runs on its own output. Read the actual rendered state (screenshots the user provides, or captures the user asks for); refuse to critique from source alone when the ask is "does it look right", and never imagine what unrendered code looks like. Each finding: severity, the on-screen element, what's wrong, the exact fix.
+
+## Improve — judge + the fix pass
+
+Whole-canvas authority holds, under the **preservation contract**:
+
+1. **Pre-flight findings block** — record the incumbent system with file citations: tokens, fonts, framework, component conventions. When the product already lives on an official design system, that system is respected, never replaced. The primitives switch reads `native` on these runs unless the incumbent already uses `@nurix/components`.
+2. **Preserve/introduce declaration** precedes any change: what stays, what enters, in one block.
+3. **The never-silently-change list** holds regardless of authority: routes and slugs, nav labels, form field names and IDs, brand marks, legal copy. The no-jails law is about *our* generated files; a user's existing brand and IA are theirs. Changing anything on this list requires the user's explicit ask.
+
+Improve runs then proceed through the standard steps as scoped: intake (against the incumbent — the package choice may be "extract", below), structure only where surfaces change, content only where data is fake, compose with the finishing pass, and the ship gate on what was touched.
+
+## Extract — reading an identity package out of a foreign UI
+
+A supported entry path, under **attestation and provenance**:
+
+- Record what the source is and whose it is: own product / public reference / third party.
+- Extract **structure and system, never pixels or assets**: roles, ramps, spacing, elevation, motion posture — into a `tier: project` design.md in the package schema, validator-checked.
+- Write a provenance block into the extracted file (`source-package: extracted@<date>` plus the attestation lines).
+- Record what **is**, never what should be — extraction is documentation, not improvement; the improve pass comes after, separately, if asked.
+- Admission of an extracted package into the shared roster later requires the provenance check to pass; third-party extractions stay project-local.

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

@@ -0,0 +1,36 @@
+# Step 1 — Intake: brief → recorded choices
+
+Read the brief and choose from the menus: one identity package (the design.md system), any axis overrides the brief demands, layout blueprints per surface, and the product domain for content. Every choice is one recorded line.
+
+## Rules
+
+- **The brief's own words outrank any database default.** "Beautiful" means the ceiling, not the safe row.
+- **Adjectives become referents.** When the brief speaks in adjectives ("premium", "editorial"), name the 2–3 real products the brief is pointing at and pick the package whose recorded identity sits in that class — unnamed ambition becomes beige.
+- **The index is a retrieval aid, never a router.** Load `design-md/index.csv` whole (it is small), shortlist 2–3 rows by segment/keyword resemblance, read only the shortlisted files' §1 Visual Theme, then choose reading the brief. After the choice, the chosen package's **full design.md enters context and stays in view through step 4**; unchosen candidates are dropped.
+- **The escape hatch fires mechanically.** No index hit, plus a recorded one-line reason why the closest package fails → author a one-off project design.md in the package schema (`design-md/SCHEMA.md`), `tier: project`, validator-checked like any library entry. This path is expected to be common; flag the file as a curation candidate for the roster.
+- **Set the primitives switch** — write one `primitives: nurix | native` line into the project's `design.md`. Default by the probe: the project resolves `@nurix/components` (check package.json / lockfile / node_modules) → `nurix`; otherwise — existing apps, foreign stacks, no library access — → `native`. Set once here; nothing downstream re-asks. Also write `source-package: <id>@<date>` (or `authored` for escape-hatch one-offs).
+- **Write or update `product.md`**: users and their jobs, roles/permissions, action frequency, risk level, accessibility commitments, brand anti-references. Package choice, UX decisions, motion intensity, and demo data all cite it.
+- **Consult `taste.md`** — its feel/avoid lines bias every choice; user reactions to shipped output update it in place. Missing file = no bias, never a block.
+- **Stated-choice awareness:** if prior package picks are visible in the workspace, name them and say in one line why this pick repeats or differs — awareness, never forced rotation.
+- **Questions go to the user only when the answer changes the design** (theme, audience, density); everything else is inferred and marked inferred.
+
+## The preview block
+
+Step 1 ends with a preview block:
+
+- chosen package + one-line reason
+- the primitives switch position
+- axis overrides (each: axis → entry id → one-line reason)
+- blueprints per surface
+- domain corpus
+- surface map with archetypes
+- planned deviations
+
+When a user is present, pause here **once** for confirm-or-redirect — a wrong pick costs one message now instead of a full build. Autonomous runs proceed. Either way the block becomes the durable header of this run's dated section in `decisions.md`.
+
+## Outputs
+
+- `design.md` (project fork: chosen package + switch line + provenance + brief bindings; deviations accrue as they are recorded)
+- `product.md` written/updated; `taste.md` consulted
+- the preview block, appended to `decisions.md`
+- the chosen package's full design.md held in context

package/data/harnesses/code/skills/design/references/object-pass.md

@@ -0,0 +1,24 @@
+# Step 2 — Structure: the object pass
+
+Derive the object model and surface map using the UX-pattern decision layer (`references/ux-patterns/`). Load **one pass file at a time**, in this order, consulting only the passes the brief makes material:
+
+1. `object-model` — the domain objects and their relationships
+2. `attributes-lifecycle` — attributes, lifecycle states, history requirements
+3. `verbs` — actions per object × state × role
+4. `viewer-context` — how rendering changes by viewer
+5. `modes` — modal contexts the product runs in
+6. `promotion-demotion` — surface prominence by frequency × criticality
+7. `page-archetype` — each surface's archetype from the pinned roster: **browse, queue, grid, record-detail, dashboard, creation-flow, settings**. View-types (table, board, cards, calendar) are projections of an archetype, never archetypes.
+8. `container-choice` — container by workflow (duration, interruption, comparison need), never by size
+9. `creation-paths` — form, import, conversion, clone, recurrence
+10. `table-mechanics` — where tables project a surface
+11. `state-matrix` — loading, the three empties (first-use, no-results, cleared), degraded, stale — per surface
+12. `standard-pages` / `ai-layer` / `dashboards` / `settings` — when the brief has them
+
+Each pass file carries its rule as prose plus a machine-readable decision table; **follow the table's answer**. Disagreement is legitimate craft only when recorded — one line in `decisions.md` naming the pass, the table's answer, yours, and why. An unrecorded divergence is the violation.
+
+When a pass fires a clarification code (an input the table needs that the brief doesn't give), resolve it: infer-and-mark when the answer doesn't change the design, ask when it does.
+
+## Output: the structure document
+
+A single document — entities, surfaces, archetype per surface, projections, container choices, creation paths, and the state matrix per surface. It is an **input** to composition, never a jail: no file it implies is ever marked do-not-edit, and step 4 may revise it with a one-line record.

package/data/harnesses/code/skills/design/references/ship-gate.md

@@ -0,0 +1,29 @@
+# Step 5 — The ship gate
+
+The project ships with its four project-local artifacts — `design.md` (the resolved fork, with provenance line, brief bindings, recorded deviations), `product.md`, `taste.md`, and `decisions.md`. The gate has two tiers, both objective: this is the only runtime check the skill performs, permitted precisely because it is automated and needs no judgment. Nothing here grades taste — anything that needs grading was the build-time harness's burden, not the run's.
+
+## Tier 1 — fails closed
+
+Every check a binary predicate. Run the validator (`node scripts/validate-design-md.mjs <project design.md> --mode ship`) plus the build itself; all of these must hold:
+
+- **No placeholder text or scaffold stubs** anywhere (lorem, TODO, "Coming soon", empty `href="#"` walls).
+- **Data plausibility** against the corpus's declared invariants: aggregates reconcile with their visible rows; legal ranges hold; no degenerate repetition in visible rows (surname clusters, identical amounts).
+- **Accessibility floor, mechanical**: contrast computed on the emitted token pairs in *both* themes; focus visible on every interactive element; `prefers-reduced-motion` respected.
+- **Every declared surface reachable** — each surface in the structure doc has a live route/nav path.
+- **`design.md` present at the repo base** and the token artifact recompiles from it to a byte-match (the validator's drift check).
+- **The pipe checks**:
+  - the token artifact carries 100% coverage and components consume tokens — no raw color/size literals in component code;
+  - fonts bound to installed packages under registered family names (a family that never resolves is a fail);
+  - every authored token group reaches a named consumer — an emitted ramp nobody consumes is a fail;
+  - the emitted CSS actually compiles;
+  - charts and status surfaces consume the package's tokens (a dark dashboard with hardcoded light charts fails here).
+
+A Tier-1 failure blocks the ship; fix and re-run. Binary phrasing is the contract — anything that would need "use sparingly" grading does not belong in this tier.
+
+## Tier 2 — flags, never gates
+
+Sweep `data/tells.csv` (the operator tell list) plus the motion tells (`transition: all`; `ease-in` on an entrance; animation attached to a keyboard-triggered action). Flags cannot fail the build and trigger no in-run judging: each is **fixed or dismissed with one recorded line** in `decisions.md`, and every flag appears in the ship report for the human's eyes — numbers point eyes; they do not replace them. The validator may run this sweep warn-only after compose-step edits; nothing new ever fails the build mid-composition.
+
+## The ship report
+
+Close the run with a compact report: surfaces shipped, the recorded choices (from the run's `decisions.md` section), Tier-1 results, every Tier-2 flag with its disposition, and the validator's warn list. No scores, no self-grades.

package/data/harnesses/code/skills/design/references/ux-patterns/Readme.md

@@ -0,0 +1,195 @@
+---
+id: ux-patterns-index
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns playbook (16 chapters) — distilled"
+license: open
+---
+# B2 — the B2B UX-pattern decision layer
+
+What-to-use-when for every structural UI decision, distilled from the ratified 16-chapter B2B UX playbook. **One decision file per pass**, each carrying its rule twice in one body: prose for the model, then an embedded machine-readable `json decision-table` that is the executable core — the contract runner ([`../../../../evals/design/run-decision-contracts.mjs`](../../../../evals/design/run-decision-contracts.mjs)) parses and evaluates these tables directly, so the tested rule and the followed rule are the same bytes.
+
+The pinned **seven-archetype roster** every pass conforms to: `browse`, `queue`, `grid`, `record-detail`, `dashboard`, `creation-flow`, `settings`. View-types (table, board, cards, calendar, timeline, map) are **projections** of an archetype, never archetypes themselves.
+
+## The 15 passes
+
+Run each at the step of the method that needs it — the order below is the method's order.
+
+| # | Pass | Source | Owns |
+| --- | --- | --- | --- |
+| 1 | [object-model](object-model.md) | ch.1 | `requiredMechanics`, `clarifications` |
+| 2 | [attributes-lifecycle](attributes-lifecycle.md) | ch.2 | `requiredMechanics`, `requiredStates`, `clarifications` |
+| 3 | [verbs](verbs.md) | ch.3 | `requiredMechanics`, `requiredStates`, `containers`, `clarifications` |
+| 4 | [viewer-context](viewer-context.md) | ch.4 | `requiredMechanics`, `clarifications` |
+| 5 | [modes](modes.md) | ch.5 | `archetypes`, `requiredMechanics` |
+| 6 | [promotion-demotion](promotion-demotion.md) | ch.6 | `requiredMechanics`, `clarifications` |
+| 7 | [page-archetype](page-archetype.md) | ch.7 | `archetypes`, `requiredMechanics`, `requiredStates`, `clarifications` |
+| 8 | [container-choice](container-choice.md) | ch.8 | `containers`, `requiredMechanics`, `clarifications` |
+| 9 | [creation-paths](creation-paths.md) | ch.9 | `creationPaths`, `requiredMechanics`, `clarifications` |
+| 10 | [table-mechanics](table-mechanics.md) | ch.10 | `requiredMechanics`, `clarifications` |
+| 11 | [state-matrix](state-matrix.md) | ch.11 | `requiredStates`, `requiredMechanics`, `clarifications` |
+| 12 | [standard-pages](standard-pages.md) | ch.12 | `archetypes`, `requiredMechanics`, `clarifications` |
+| 13 | [ai-layer](ai-layer.md) | ch.13 | `archetypes`, `requiredStates`, `requiredMechanics`, `clarifications` |
+| 14 | [dashboards](dashboards.md) | ch.15 | `archetypes`, `requiredStates`, `requiredMechanics`, `clarifications` |
+| 15 | [settings](settings.md) | ch.16 | `archetypes`, `requiredStates`, `requiredMechanics`, `clarifications` |
+
+(Playbook chapter 14 — the agentic pattern catalog — is consideration material behind pass 13, not a pass of its own.)
+
+## The decision-table contract
+
+Every pass file ends with one fenced `json decision-table` block: `{"pass": "<id>", "rows": [{"when": {...}, "then": {...}, "reason": "<kebab-code>"}]}`.
+
+**Matching semantics (canonical).** A row matches when **every** key in its `when` matches the input: a literal value matches by equality, an array value matches by membership (input ∈ array), and `"__absent__"` matches when the key is missing or null. The engine unions the `then` of every matched row.
+
+**`then` fields.** `archetypes` / `containers` / `creationPaths` / `requiredStates` / `requiredMechanics` each take `{"mustInclude": [...], "mustNotInclude": [...]}` (`containers` may use `"acceptable"` / `"forbidden"`); `clarifications` takes a flat list of missing-input codes.
+
+## Shared input vocabulary
+
+Every `when` key used across the 15 passes, with its legal values. **Any key may also be `"__absent__"`** (the input omits it) — that is how clarification rows fire. Boolean keys take `true` / `false`.
+
+| Key | Legal values | Used by |
+| --- | --- | --- |
+| `relationshipCardinality` | one-to-one · one-to-few · one-to-many · many-to-many | object-model |
+| `childHasOwnLifecycle` | boolean | object-model |
+| `childMeaningfulAlone` | boolean | object-model |
+| `editedAtomicallyWithParent` | boolean | object-model |
+| `associationHasPayload` | boolean | object-model |
+| `glanceContextNeeded` | boolean | object-model |
+| `collaboration` | concurrent · single-writer | object-model, viewer-context, page-archetype |
+| `historySignal` | none · trajectory · compliance · derived-high-frequency | attributes-lifecycle |
+| `disputeLikely` | boolean | attributes-lifecycle |
+| `fieldOrigin` | manual · computed · synced · imported · ai-generated | attributes-lifecycle |
+| `objectHasLifecycle` | boolean | attributes-lifecycle |
+| `transitionRequirements` | boolean | attributes-lifecycle |
+| `timeProperty` | sla · due-escalation · recurrence · snooze · none | attributes-lifecycle |
+| `endOfLife` | reference-after-completion · user-data-deletion · compliance-erasure | attributes-lifecycle |
+| `multipleEntryPoints` | boolean | attributes-lifecycle |
+| `verbKind` | transition · edit · association · collaboration · communication · conversion · break-glass · approval-gated | verbs |
+| `reversible` | boolean | verbs, ai-layer |
+| `outwardFacing` | boolean | verbs, ai-layer |
+| `bulk` | boolean | verbs |
+| `thresholdVariant` | boolean | verbs |
+| `denialKind` | role · plan | viewer-context |
+| `entitlementKind` | boolean · metered | viewer-context |
+| `fieldLevelSecurity` | boolean | viewer-context |
+| `requiredFieldHidden` | boolean | viewer-context |
+| `existenceLeakRisk` | boolean | viewer-context |
+| `viewerKind` | human · agent | viewer-context |
+| `concurrentViewers` | boolean | viewer-context |
+| `environmentSeparation` | boolean | viewer-context |
+| `mode` | monitoring · triage · procedural · exception · approval · investigation · exploration · authoring · reconciliation · comparison · batch-mutation · configuration · collaboration · reporting · learning · supervision | modes |
+| `sameDataMultipleModes` | boolean | modes |
+| `frequency` | high · medium · low | promotion-demotion |
+| `isParent` | boolean | promotion-demotion |
+| `demotionContractMet` | boolean | promotion-demotion |
+| `perRoleVariance` | boolean | promotion-demotion |
+| `primaryJob` | lookup · triage · process · edit-bulk · monitor · narrate-period · route-work · author · configure · approve · investigate · explore · reconcile | page-archetype |
+| `ordering` | priority · sla · age · user-controlled · none | page-archetype |
+| `ownership` | claimable · assigned · individual · shared | page-archetype |
+| `viewTypeRequested` | table · board · cards · calendar · timeline · map | page-archetype |
+| `hasStatusField` | boolean | page-archetype, table-mechanics |
+| `hasDateField` | boolean | page-archetype |
+| `unitOfWork` | record · machine-proposal · thread | page-archetype |
+| `structuralChangeAllowed` | boolean | page-archetype |
+| `existingArchetype` | browse · queue · grid · record-detail · dashboard · creation-flow · settings | page-archetype |
+| `opensRecord` | boolean | container-choice |
+| `contextRetentionNeeded` | boolean | container-choice |
+| `interactionDepth` | quick-read · deep-edit | container-choice |
+| `sharing` | stable-url · sent-outward · none | container-choice |
+| `traversal` | boolean | container-choice |
+| `interruption` | interrupt · continue | container-choice |
+| `contentSize` | small · large | container-choice |
+| `recordReference` | boolean | container-choice |
+| `opensInOverlay` | boolean | container-choice |
+| `isDetailSurface` | boolean | container-choice |
+| `detailBody` | large-independent · modest-cross-skim | container-choice |
+| `longSessionStream` | boolean | container-choice |
+| `customerFacingComposer` | boolean | container-choice |
+| `manualCreate` | boolean | creation-paths |
+| `bulkOnboarding` | boolean | creation-paths |
+| `bornFromTransformation` | boolean | creation-paths |
+| `bornFromTemplate` | boolean | creation-paths |
+| `recurs` | boolean | creation-paths |
+| `externalSourceOfTruth` | boolean | creation-paths |
+| `creationFrequency` | high · low | creation-paths |
+| `fieldCount` | few · many | creation-paths |
+| `interdependentFields` | boolean | creation-paths |
+| `bornComplete` | boolean | creation-paths |
+| `sequentialDependencies` | boolean | creation-paths |
+| `isGridPrimaryWrite` | boolean | creation-paths |
+| `requiredRelationMayBeMissing` | boolean | creation-paths |
+| `duplicateProneCreate` | boolean | creation-paths |
+| `serverTruthValidation` | boolean | creation-paths |
+| `editRegime` | inline · explicit-mode · canvas | creation-paths |
+| `concurrentEditors` | boolean | creation-paths |
+| `isConfigObject` | boolean | creation-paths |
+| `revisitedWithIntent` | boolean | table-mechanics |
+| `sharedViewScope` | personal · team | table-mechanics |
+| `wideObject` | boolean | table-mechanics |
+| `heavyDailyUse` | boolean | table-mechanics |
+| `groupBySegment` | boolean | table-mechanics |
+| `crossCuttingHealthNumbers` | boolean | table-mechanics |
+| `gridEditable` | boolean | table-mechanics |
+| `bulkVerbs` | boolean | table-mechanics |
+| `rowActions` | boolean | table-mechanics |
+| `viewerRelationships` | boolean | table-mechanics |
+| `largeDataset` | boolean | table-mechanics |
+| `listLength` | paginated · infinite · virtualized | table-mechanics |
+| `financialRecordKeeping` | boolean | table-mechanics |
+| `sharedMutableList` | boolean | table-mechanics |
+| `exportNeeded` | boolean | table-mechanics |
+| `isListSurface` | boolean | state-matrix |
+| `dataFetch` | boolean | state-matrix |
+| `fetchLatency` | boolean | state-matrix |
+| `compositePage` | boolean | state-matrix |
+| `consumesCachedData` | boolean | state-matrix |
+| `streamingView` | boolean | state-matrix |
+| `optimisticMutation` | boolean | state-matrix |
+| `queueSuccessIsEmpty` | boolean | state-matrix |
+| `firstRunSurface` | boolean | state-matrix |
+| `onboardingTechnique` | boolean | state-matrix |
+| `onboardingScope` | application-level · empty-state | state-matrix |
+| `standardPage` | settings · profile · notifications · audit-object · audit-global · user-management · roles-permissions · seats-licenses · billing · integrations | standard-pages |
+| `notificationDelivery` | boolean | standard-pages |
+| `ssoScimProvisioning` | boolean | standard-pages |
+| `complianceBuyer` | boolean | standard-pages |
+| `recordLevelAccess` | boolean | standard-pages |
+| `externalSystemMapping` | boolean | standard-pages |
+| `intelligenceTime` | build-time · run-time | ai-layer |
+| `aiWrites` | boolean | ai-layer |
+| `blastRadius` | single-record · many-records · external-fanout | ai-layer |
+| `initiative` | invoked · suggested · initiated | ai-layer |
+| `latency` | live · just-in-time · per-row · scheduled · ambient | ai-layer |
+| `confidenceGateable` | boolean | ai-layer |
+| `correctsHumanOrThirdParty` | boolean | ai-layer |
+| `autonomousAgent` | boolean | ai-layer |
+| `agentPrincipal` | boolean | ai-layer |
+| `durableWait` | boolean | ai-layer |
+| `copilotOutput` | inspectable-reversible · externally-committing | ai-layer |
+| `accumulatedMemory` | boolean | ai-layer |
+| `inputBoundaryTransduction` | boolean | ai-layer |
+| `dashboardJob` | monitoring · narrative · work-router | dashboards |
+| `multiJobCanvas` | boolean | dashboards |
+| `cachedDecisionData` | boolean | dashboards |
+| `viewerScopedMetrics` | boolean | dashboards |
+| `promotionRole` | manager · operator | dashboards |
+| `pushDigest` | boolean | dashboards |
+| `tile` | boolean | dashboards |
+| `monitoringTile` | boolean | dashboards |
+| `thresholdDeclared` | boolean | dashboards |
+| `trendTileRequested` | boolean | dashboards |
+| `sourceHistoryClass` | overwrite · sampled · logged | dashboards |
+| `isSettingsPage` | boolean | settings |
+| `scope` | personal · workspace · org | settings |
+| `settingKind` | leaf-preference · config-object | settings |
+| `riskClass` | preference · behavior-config · structural-destructive | settings |
+| `subject` | identity-access · data-model · automation · notifications · integrations · branding · billing · compliance-audit · ai-agent-policy | settings |
+| `multiScopeSetting` | boolean | settings |
+| `nodeCount` | under-30 · over-30 | settings |
+| `governedSurfaceLink` | boolean | settings |
+| `buildTimeGeneration` | boolean | settings |
+| `productSurfaceInTree` | boolean | settings |
+
+## The load rule
+
+**One pass file per step, never all at once.** The load contract ([09 §Load contracts](../../../../docs/features/design-skill/09-database-structures.md)) is explicit: B2 enters context as *the one pass file the current step needs*; loading all passes at once is forbidden. Consult this Readme to route to the right file, then load only that file at the step that needs it. Clarification codes are surfaced, never guessed around — a `then.clarifications` firing means an input the pass needs is missing, and the step pauses to obtain it rather than proceeding on a default.

package/data/harnesses/code/skills/design/references/ux-patterns/ai-layer.md

@@ -0,0 +1,49 @@
+---
+id: ai-layer
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.13"
+license: open
+---
+# Pass: the AI layer
+
+**Inputs:** per intelligent capability — `intelligenceTime` (build-time | run-time), `aiWrites`, `blastRadius` (single-record | many-records | external-fanout), `reversible`, `outwardFacing`, `initiative` (invoked | suggested | initiated), `latency` (live | just-in-time | per-row | scheduled | ambient), `confidenceGateable`, `correctsHumanOrThirdParty`, `autonomousAgent`, `agentPrincipal`, `durableWait`, `copilotOutput` (inspectable-reversible | externally-committing), `accumulatedMemory`, `inputBoundaryTransduction`.
+**Owns:** `archetypes`, `requiredStates`, `requiredMechanics`, `clarifications`.
+**Output artifact:** for every AI capability, its decision-rights stance (who holds the write), the guardrail envelope (prevention + recovery + glass box), and the write-path bindings that connect it to the lifecycle, verbs, and access passes. Every AI pattern is a transfer of a slice of cognition from human to system; this pass governs the transfer.
+
+## The rule
+
+**Divide first by when the intelligence runs.** *Run-time* intelligence operates within a built system (fills fields, routes rows, drafts text, resolves) and transfers the operator's cognition. *Build-time* intelligence constructs the system itself (NL → tables, views, automations) and transfers the builder's cognition — its guardrail shape is **preview-the-generated-artifact and edit-before-commit**, never per-row confidence, and its compilation target must be inspectable (a node graph, a field list), never an opaque box.
+
+**The three-actor write model is the spine, and the stance is set by blast radius and reversibility — not by model confidence alone.** *System proposes, human disposes* — output lands in a *proposed* state and waits for accept/edit/reject; the default for external, irreversible, or fan-out writes (a customer email, a bulk send). *System acts, human audits after* — the write commits, with the audit trail, rollback, and exception queue as the control; correct for internal, reversible, single-record writes. *System acts silently* — auto-classification, continuous re-enrichment; governance lives in configuration, sampling, and dashboards. The clean formulation: *AI proposes the signal, deterministic rules dispose the record.* Two axes cross the spine: **initiative** (invoked → suggested → initiated) separates next-best-action from anticipation; the **latency ladder** (live → just-in-time → per-row → scheduled → ambient) dictates the affordance — live cue cards streamed mid-call can never be a modal; scheduled jobs surface as a review queue on completion.
+
+**Non-deterministic in, deterministic out.** Free-form material (dictated text, an email thread, a PDF, a receipt) is matched to the declared object model and lands as typed fields — the input-boundary transducer, "parse, don't type," applied at every scope (field, record, row-stream, table, ambient stream). Output generation is grounded in declared assets and post-filtered by deterministic rulebooks. Every AI write carries **origin = ai-generated** with provenance, rides the standard *proposed* state and approval verbs, and is **Logged with dual attribution** (the agent, and the human who accepted or the policy that authorized).
+
+**Guardrails are one orthogonal layer, factored once.** *Prevention*: confidence gating with a numeric threshold where the domain is mature (high-confidence posts through, sub-threshold queues for review); **statistical-significance gating** where the system corrects a human or third-party claim (never assert on a small sample — the reputation guardrail, and the home of the house-knowledge corrective); simulation/eval gating before an agent version deploys. *Recovery*: the undo/rollback backstop under every agent action; the **escalation floor** — no serious autonomous agent ships without a mandatory hand-to-human boundary, and the handoff carries what was already tried so the human resumes mid-stream. *Glass box*: citations, the source anchor stored beside every transduced value, and the **AI-action audit log as a surface distinct from record edit history** (actor = AI, what changed, and what data informed it).
+
+**The agent is a governed actor and the checkpoint is how the flow waits.** An agent principal gets its own identity in the directory, scoped least-privilege permissions, a human sponsor, and a lifecycle — never a borrowed human credential; its effective access is the intersection of its grants and its delegating subject's (see viewer-context). The **durable checkpoint** (axiom 21) — pause, persist, notify, resume — is the portable guardrail node: decision rights choose *when* the human enters; the checkpoint is *how* the flow waits, with state persisting across days and the notification carrying the evidence pack. Design against this primitive, not against inline blocking prompts. Chat is the **home surface** when its output is inspectable and reversible (conversational BI — expose the compiled query as the escape to determinism) and the **escape hatch** when output is externally committing (the human ratifies). Accumulated memory (system-auto-written, cross-session) is audited after and demands its own management surface and memory-provenance show-which. When an AI capability writes but its blast radius is undeclared, the decision-rights stance cannot be set: clarify.
+
+```json decision-table
+{"pass": "ai-layer", "rows": [
+  {"when": {"intelligenceTime": "build-time"}, "then": {"requiredMechanics": {"mustInclude": ["preview-generated-artifact", "edit-before-commit", "inspectable-compilation-target"], "mustNotInclude": ["opaque-black-box", "per-row-confidence-on-build"]}}, "reason": "build-time-previews-the-artifact"},
+  {"when": {"aiWrites": true, "blastRadius": "single-record", "reversible": true, "outwardFacing": false}, "then": {"requiredMechanics": {"mustInclude": ["ai-acts-human-audits-after", "audit-trail", "rollback-backstop", "exception-queue"]}}, "reason": "internal-reversible-single-record-acts"},
+  {"when": {"outwardFacing": true}, "then": {"requiredMechanics": {"mustInclude": ["ai-proposes-human-disposes", "approval-verbs"], "mustNotInclude": ["ai-acts-silently"]}, "requiredStates": {"mustInclude": ["proposed"]}}, "reason": "external-facing-writes-propose"},
+  {"when": {"blastRadius": "external-fanout"}, "then": {"requiredMechanics": {"mustInclude": ["ai-proposes-human-disposes", "approval-verbs"], "mustNotInclude": ["ai-acts-silently"]}, "requiredStates": {"mustInclude": ["proposed"]}}, "reason": "fan-out-writes-propose"},
+  {"when": {"aiWrites": true, "reversible": false}, "then": {"requiredMechanics": {"mustInclude": ["ai-proposes-human-disposes"], "mustNotInclude": ["ai-acts-silently"]}, "requiredStates": {"mustInclude": ["proposed"]}}, "reason": "irreversible-writes-propose"},
+  {"when": {"initiative": "initiated"}, "then": {"requiredMechanics": {"mustInclude": ["anticipation-system-initiated", "statistical-significance-gate"]}}, "reason": "system-initiated-needs-the-significance-gate-most"},
+  {"when": {"initiative": "suggested"}, "then": {"requiredMechanics": {"mustInclude": ["next-best-action-same-recommendation-multi-surface"]}}, "reason": "suggested-is-next-best-action"},
+  {"when": {"latency": "live"}, "then": {"requiredMechanics": {"mustInclude": ["streamed-cue-cards"], "mustNotInclude": ["live-output-in-a-modal"]}}, "reason": "sub-second-cannot-be-a-modal"},
+  {"when": {"latency": "scheduled"}, "then": {"archetypes": {"mustInclude": ["queue"]}, "requiredMechanics": {"mustInclude": ["review-queue-on-completion", "evidence-pack"]}}, "reason": "scheduled-jobs-surface-a-review-queue"},
+  {"when": {"confidenceGateable": true}, "then": {"requiredMechanics": {"mustInclude": ["confidence-threshold-gate", "sub-threshold-review-queue"]}}, "reason": "mature-domain-gates-on-confidence"},
+  {"when": {"correctsHumanOrThirdParty": true}, "then": {"requiredMechanics": {"mustInclude": ["statistical-significance-gate", "house-knowledge-corrective"], "mustNotInclude": ["assert-on-small-sample"]}}, "reason": "reputation-guardrail-never-asserts-on-a-small-sample"},
+  {"when": {"inputBoundaryTransduction": true}, "then": {"requiredMechanics": {"mustInclude": ["parse-dont-type-transducer", "source-anchor-per-value", "typed-fields-out"]}}, "reason": "non-deterministic-in-deterministic-out"},
+  {"when": {"aiWrites": true}, "then": {"requiredMechanics": {"mustInclude": ["origin-ai-generated-provenance", "dual-attribution-logged", "ai-action-audit-log-distinct"]}}, "reason": "ai-writes-carry-provenance-and-dual-attribution"},
+  {"when": {"autonomousAgent": true}, "then": {"requiredMechanics": {"mustInclude": ["escalation-floor-hand-to-human", "handoff-carries-context", "supervisor-layer", "undo-rollback-backstop"], "mustNotInclude": ["no-escalation-boundary"]}}, "reason": "no-autonomous-agent-without-an-escalation-floor"},
+  {"when": {"agentPrincipal": true}, "then": {"requiredMechanics": {"mustInclude": ["agent-own-directory-identity", "scoped-least-privilege", "human-sponsor", "delegated-subject-intersection"], "mustNotInclude": ["borrowed-human-credential"]}}, "reason": "agent-is-a-governed-principal"},
+  {"when": {"durableWait": true}, "then": {"requiredMechanics": {"mustInclude": ["durable-checkpoint-pause-persist-notify-resume", "notification-carries-evidence-pack"], "mustNotInclude": ["inline-blocking-prompt"]}}, "reason": "design-against-the-checkpoint-primitive"},
+  {"when": {"copilotOutput": "inspectable-reversible"}, "then": {"requiredMechanics": {"mustInclude": ["chat-as-home-surface", "expose-compiled-query", "promote-answer-to-artifact"]}}, "reason": "inspectable-reversible-output-lives-in-chat"},
+  {"when": {"copilotOutput": "externally-committing"}, "then": {"requiredMechanics": {"mustInclude": ["chat-as-escape-hatch", "human-ratifies-before-commit", "propose-then-confirm"], "mustNotInclude": ["chat-commits-externally-unratified"]}}, "reason": "externally-committing-output-is-ratified"},
+  {"when": {"accumulatedMemory": true}, "then": {"requiredMechanics": {"mustInclude": ["memory-management-surface", "memory-provenance-show-which", "identity-scoped-memory"]}}, "reason": "auto-written-memory-is-audited-after"},
+  {"when": {"aiWrites": true, "blastRadius": "__absent__"}, "then": {"clarifications": ["ai-write-blast-radius-unspecified"]}, "reason": "decision-rights-stance-needs-blast-radius"}
+]}
+```

package/data/harnesses/code/skills/design/references/ux-patterns/attributes-lifecycle.md

@@ -0,0 +1,43 @@
+---
+id: attributes-lifecycle
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.2"
+license: open
+---
+# Pass: attributes, lifecycle & history
+
+**Inputs:** per field — `historySignal` (none | trajectory | compliance | derived-high-frequency), `fieldOrigin` (manual | computed | synced | imported | ai-generated), `disputeLikely`; per object — `objectHasLifecycle`, `transitionRequirements`, `timeProperty` (sla | due-escalation | recurrence | snooze | none), `endOfLife` (reference-after-completion | user-data-deletion | compliance-erasure), `multipleEntryPoints`.
+**Owns:** `requiredMechanics`, `requiredStates`, `clarifications`.
+**Output artifact:** per-field declarations (type, history class, origin) and per-object declarations (state machine, time properties, end-of-life tier) that every later pass derives from mechanically — chips, timelines, trends, boards, gated buttons, countdowns, trash, and merge are renders of these declarations, never inventions.
+
+## The rule
+
+**Every field declares one of three history classes.** *Overwrite* (the default — update in place, no history; paying history cost on every descriptive field is how products drown their own timelines). *Logged* (every change attributed: old value, new value, actor, timestamp) for fields where the trajectory is the meaning — stage, status, owner, amount — and anything with compliance weight or dispute risk; Logged fields are what make a detail page's history tab worth opening. *Sampled* (sparse snapshots or rollups) for high-frequency derived values — scores, metrics, queue depths; a Sampled field renders as a number with a trace (sparkline, as-of view), never as a change log. An empty timeline is a history-class declaration failure, not a UI failure.
+
+**Origin decides editability and provenance.** Computed fields are never directly editable. Synced fields render their source and last-sync ("Enriched by Clearbit, 3 days ago") and need a conflict resolution when the sync wants to overwrite a human edit. Field types drive four renders at once — cell, input, filter, sort — declared once, derived everywhere; enums declare semantic color and icon here, never color alone.
+
+**The state machine is data:** a status enum, legal transitions, terminal states. The UI derives gated verbs (Refund exists only on succeeded payments), status chips rendered identically everywhere, spatial board projection (a drag is a transition), and per-transition requirements (required fields, approvals, permissions) declared on the transition, not in form code. The status field itself is almost always Logged.
+
+**Time properties mutate records with no user action** — SLA countdowns that re-sort queues, escalation on due-date breach, recurrence materializing instances, snooze as a time-scoped visibility state. Lists holding such objects are not stable; queues sort on the clock.
+
+**Every object declares how it dies**, in order of preference: archive (restorable, filter-exposed) for completed referenceable work; soft-delete with a trash retention window — the data property that permits undo-toast instead of a confirm dialog; hard delete reserved for compliance erasure. Any object with multiple entry points will accumulate duplicates and needs a merge flow whose survivor keeps the Logged history — a merge that discards a Logged trail breaks the audit chain.
+
+```json decision-table
+{"pass": "attributes-lifecycle", "rows": [
+  {"when": {"historySignal": "none"}, "then": {"requiredMechanics": {"mustInclude": ["overwrite-in-place"], "mustNotInclude": ["activity-timeline-entries"]}}, "reason": "descriptive-fields-overwrite"},
+  {"when": {"historySignal": ["trajectory", "compliance"]}, "then": {"requiredMechanics": {"mustInclude": ["logged-field-history", "activity-timeline-entries", "changed-by-attribution"]}}, "reason": "trajectory-is-the-meaning"},
+  {"when": {"historySignal": "derived-high-frequency"}, "then": {"requiredMechanics": {"mustInclude": ["sampled-snapshots", "sparkline-trend"], "mustNotInclude": ["activity-timeline-entries"]}}, "reason": "high-frequency-sampled-not-logged"},
+  {"when": {"disputeLikely": true, "historySignal": "__absent__"}, "then": {"clarifications": ["history-class-unspecified"]}, "reason": "disputes-need-declared-history"},
+  {"when": {"fieldOrigin": "computed"}, "then": {"requiredMechanics": {"mustInclude": ["read-only-derived-render"], "mustNotInclude": ["editable-input"]}}, "reason": "computed-never-editable"},
+  {"when": {"fieldOrigin": "synced"}, "then": {"requiredMechanics": {"mustInclude": ["provenance-render", "sync-conflict-resolution"]}}, "reason": "synced-origin-carries-provenance"},
+  {"when": {"objectHasLifecycle": true}, "then": {"requiredMechanics": {"mustInclude": ["status-enum-semantic-colors", "transition-graph-legal-only", "state-gated-verbs"]}}, "reason": "state-machine-is-data"},
+  {"when": {"transitionRequirements": true}, "then": {"requiredMechanics": {"mustInclude": ["transition-required-fields"]}}, "reason": "requirements-on-transition-not-form"},
+  {"when": {"timeProperty": ["sla", "due-escalation"]}, "then": {"requiredMechanics": {"mustInclude": ["sla-countdown-render", "breach-state-resort"]}, "requiredStates": {"mustInclude": ["stale"]}}, "reason": "clock-mutates-the-record"},
+  {"when": {"timeProperty": "snooze"}, "then": {"requiredMechanics": {"mustInclude": ["snooze-until-resurface"]}}, "reason": "snooze-is-visibility-not-deletion"},
+  {"when": {"endOfLife": "reference-after-completion"}, "then": {"requiredMechanics": {"mustInclude": ["archive-restorable"], "mustNotInclude": ["hard-delete"]}}, "reason": "archive-completed-work"},
+  {"when": {"endOfLife": "user-data-deletion"}, "then": {"requiredMechanics": {"mustInclude": ["soft-delete-trash-retention"], "mustNotInclude": ["hard-delete"]}}, "reason": "soft-delete-enables-undo"},
+  {"when": {"endOfLife": "compliance-erasure"}, "then": {"requiredMechanics": {"mustInclude": ["hard-delete-typed-confirmation"]}}, "reason": "hard-delete-compliance-only"},
+  {"when": {"multipleEntryPoints": true}, "then": {"requiredMechanics": {"mustInclude": ["merge-duplicates-flow", "survivor-history-preserved"]}}, "reason": "multiple-entry-points-guarantee-duplicates"}
+]}
+```

package/data/harnesses/code/skills/design/references/ux-patterns/container-choice.md

@@ -0,0 +1,44 @@
+---
+id: container-choice
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.8"
+license: open
+---
+# Pass: detail surface & container choice
+
+**Inputs:** per record-opening — `opensRecord`, `contextRetentionNeeded`, `interactionDepth` (quick-read | deep-edit), `sharing` (stable-url | sent-outward | none), `traversal`, `interruption` (interrupt | continue), `contentSize` (small | large), `recordReference`, `opensInOverlay`; per detail surface — `isDetailSurface`, `detailBody` (large-independent | modest-cross-skim), `longSessionStream`, `customerFacingComposer`.
+**Owns:** `containers`, `requiredMechanics`, `clarifications`.
+**Output artifact:** the record-detail anatomy (sticky header, body organization, related lists, timeline, composer, context rail) and, for every place a record opens, the container rung it opens at — chosen by workflow, never by information size.
+
+## The rule
+
+**A detail page is a workstation, not a read-only profile.** Every detail surface carries a *sticky record header* — identity, state chip, and the 1–3 highest-frequency legal verbs for the record's current state and this viewer (from the verbs pass), the rest in overflow — pinned so identity never scrolls away. Fields *edit in place* by default (optimistic save with saving/saved/failed feedback); an explicit whole-record edit mode is reserved for interdependent fields that must commit atomically. Related lists are *action surfaces* — inline create, inline edit, row verbs, and a "view all" escape — and they are how demoted objects honor the reachability half of the demotion contract. The activity timeline is *derived*, never designed: Logged fields contribute attributed change entries, Sampled fields contribute trends, comments and notes are ordinary child objects; you declare history classes and the feed renders. A customer-facing composer carries **audience safety** — an internal note and a customer-facing send are different verbs with distinct affordance and color, never a toggle buried in one composer; sending to the wrong audience is a severity-1 failure.
+
+**Body organization forks two ways.** *Tabs* (lazy-loaded, per-section linkable) when sections are large, independently loaded, and rarely needed together — the record is "several pages sharing a header." *Single-scroll with a sticky anchor rail* when the job needs cross-section skimming in one pass and sections are modest. Objects worked in long sessions over a streaming main column (conversation, timeline) earn a persistent **360 / context rail** — the parent summary and key attributes stay put while the narrative moves; the rail is denormalization-for-display doing its job.
+
+**The container ladder — `hovercard → inline-popover → center-modal → side-peek → full-page`.** Information size does not pick the rung; five workflow axes do, size only breaks ties. (1) **Context retention** — if the originating list must stay live behind the opened record (open, close, open the next, compare), it is a **side peek**, however small the record; a modal dims and blocks the hub, a peek keeps it alive. (2) **Read-vs-edit depth** — a quick read wants a peek; deep, multi-field, interdependent editing wants center focus or a full page, because accidental dismissal becomes expensive. (3) **Shareability** — a record that needs a stable, shareable URL can now live in a URL-addressable peek or split pane; a record **sent outward** (an invoice) still defaults to a **full page** despite tiny size. (4) **Traversal** — processing or comparing many records in a row needs next/prev through the *exact filtered, sorted set*, which means a peek or split pane, never a modal and never a full-page round-trip per record. (5) **Interruption** — a center modal *blocks* (correct for confirmations and irreversible commits); a peek *continues* (work proceeds around it). Size is the tiebreaker only when the axes are indifferent: a leaf datum in a popover, a modest record in a peek.
+
+**Container requirements.** Every peek and modal carries an **"open as full page"** escape hatch — users promote up the ladder themselves, so picking the lighter rung costs one click. Closing a peek or modal honors the **return contract**: the originating surface restores *exactly as left* — same scroll, filters, selection. The same object opens at the same rung from the same kind of origin, product-wide — container choice is per-object-per-origin, not per-screen improvisation. When a record must open but no workflow axis is declared, the rung cannot be chosen from size alone: clarify.
+
+```json decision-table
+{"pass": "container-choice", "rows": [
+  {"when": {"contextRetentionNeeded": true}, "then": {"containers": {"acceptable": ["side-peek", "split-pane"], "forbidden": ["center-modal"]}}, "reason": "hub-stays-live-is-a-peek"},
+  {"when": {"interactionDepth": "deep-edit"}, "then": {"containers": {"acceptable": ["full-page", "center-modal"], "forbidden": ["side-peek"]}}, "reason": "deep-edit-wants-committed-focus"},
+  {"when": {"interactionDepth": "quick-read", "contextRetentionNeeded": false, "traversal": false}, "then": {"containers": {"acceptable": ["side-peek", "inline-popover"]}}, "reason": "quick-read-is-a-peek"},
+  {"when": {"sharing": "sent-outward"}, "then": {"containers": {"acceptable": ["full-page"], "forbidden": ["center-modal", "side-peek"]}}, "reason": "sent-records-get-a-page"},
+  {"when": {"sharing": "stable-url"}, "then": {"requiredMechanics": {"mustInclude": ["stable-shareable-url"]}}, "reason": "url-addressable-rungs-are-fine"},
+  {"when": {"traversal": true}, "then": {"containers": {"acceptable": ["side-peek", "split-pane"], "forbidden": ["center-modal", "full-page"]}, "requiredMechanics": {"mustInclude": ["next-prev-through-filtered-set"]}}, "reason": "traverse-the-filtered-set-needs-a-peek"},
+  {"when": {"interruption": "interrupt"}, "then": {"containers": {"acceptable": ["center-modal"]}}, "reason": "blocking-is-the-point"},
+  {"when": {"interruption": "continue"}, "then": {"containers": {"forbidden": ["center-modal"]}}, "reason": "work-continues-around-a-peek"},
+  {"when": {"recordReference": true}, "then": {"containers": {"acceptable": ["hovercard"]}, "requiredMechanics": {"mustInclude": ["hovercard-read-only-no-actions"]}}, "reason": "fk-resolution-is-a-hovercard"},
+  {"when": {"contentSize": "small", "interactionDepth": "quick-read"}, "then": {"containers": {"acceptable": ["inline-popover", "hovercard", "side-peek"]}}, "reason": "smaller-content-sits-lower"},
+  {"when": {"opensInOverlay": true}, "then": {"requiredMechanics": {"mustInclude": ["escape-hatch-open-as-full-page", "return-contract-restore-state", "consistent-rungs-per-object"]}}, "reason": "peek-and-modal-carry-escape-and-return"},
+  {"when": {"isDetailSurface": true}, "then": {"requiredMechanics": {"mustInclude": ["sticky-record-header", "inline-edit-in-place-default", "related-lists-action-surface", "activity-timeline-derived"]}}, "reason": "detail-is-a-workstation"},
+  {"when": {"detailBody": "large-independent"}, "then": {"requiredMechanics": {"mustInclude": ["tabs-lazy-panels"], "mustNotInclude": ["single-scroll-anchor-rail"]}}, "reason": "independent-sections-tab"},
+  {"when": {"detailBody": "modest-cross-skim"}, "then": {"requiredMechanics": {"mustInclude": ["single-scroll-anchor-rail"], "mustNotInclude": ["tabs-lazy-panels"]}}, "reason": "cross-skim-single-scroll"},
+  {"when": {"longSessionStream": true}, "then": {"requiredMechanics": {"mustInclude": ["context-rail-360", "denormalized-parent-summary"]}}, "reason": "durable-context-beside-a-moving-stream"},
+  {"when": {"customerFacingComposer": true}, "then": {"requiredMechanics": {"mustInclude": ["activity-composer-audience-safety"], "mustNotInclude": ["audience-toggle-single-composer"]}}, "reason": "internal-note-and-send-are-different-verbs"},
+  {"when": {"opensRecord": true, "interactionDepth": "__absent__", "contextRetentionNeeded": "__absent__", "sharing": "__absent__", "traversal": "__absent__", "interruption": "__absent__"}, "then": {"clarifications": ["container-workflow-unspecified"]}, "reason": "container-picked-by-workflow-not-size"}
+]}
+```