@nurix/etna 0.19.42 → 0.19.43

package/data/harnesses/apollo/skills/design/references/ux-patterns/page-archetype.md

@@ -0,0 +1,48 @@
+---
+id: page-archetype
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.7"
+license: open
+---
+# Pass: page archetype
+
+**Inputs:** per surface — `primaryJob` (lookup | triage | process | edit-bulk | monitor | narrate-period | route-work | author | configure | approve | investigate | explore | reconcile), `ordering` (priority | sla | age | user-controlled | none), `ownership` (claimable | assigned | individual | shared), `collaboration`, `viewTypeRequested` (table | board | cards | calendar | timeline | map), `hasStatusField`, `hasDateField`, `unitOfWork` (record | machine-proposal | thread), and for existing products `existingArchetype` + `structuralChangeAllowed`.
+**Owns:** `archetypes`, `requiredMechanics`, `requiredStates`, `clarifications`.
+**Output artifact:** one archetype per surface from the pinned seven-archetype roster — **browse, queue, grid, record-detail, dashboard, creation-flow, settings** — plus the projections the view may offer.
+
+## The rule
+
+**"Index" is three archetypes with opposite success metrics** — collapsing them is the most common structural error in B2B design. *Browse*: read-to-find; success = found it; ordering is the user's convenience; core machinery is sort/filter/search and saved views. *Queue*: process-to-empty; success = the list is empty (celebrate it); ordering is urgency (SLA, age, priority); claim semantics, clocks, and take-next are the archetype, not decorations. *Grid*: edit-in-place; success = data corrected; rows don't open — cells edit. The dominant mode of the primary role on the dataset picks the member; one object may need two members for two roles (a queue for agents, a browse for managers). Prioritized, claimable work is a queue — never a passive browse table. A queue-shaped job with no declared ownership model cannot be laid out: clarify.
+
+**View-type is a projection axis, never an archetype.** Board, calendar, timeline, map, cards, and table re-project the *same filtered dataset* on status, time, geography, or identity; a projection is available exactly when the dataset has a field of the projecting type (a board needs a status field, and dragging a card *is* a state transition, subject to the same legality rules as any verb). Filters belong to the view — switching projection never changes which records are present.
+
+**Roster conformance for the richer forms:** the home/work router ("My work", approvals waiting, mentions) is a viewer-scoped queue, not a dashboard. The agent-output review queue is a queue ordered by confidence tier whose unit of work is a machine proposal plus its evidence pack. The conversational inbox is a queue whose record is a thread. Composers, canvas builders, wizards, and report builders are creation-flow; log/trace exploration is browse over events with drill into record-detail; merge and reconciliation are record-detail work with side-by-side mechanics.
+
+**Existing products:** when the incumbent structure may not change, keep the recorded archetype and layer the needed mechanics onto it (a saved view as a queue lens, claim affordances on the existing table) rather than demanding a new page.
+
+```json decision-table
+{"pass": "page-archetype", "rows": [
+  {"when": {"primaryJob": "lookup"}, "then": {"archetypes": {"mustInclude": ["browse"], "mustNotInclude": ["queue"]}, "requiredMechanics": {"mustInclude": ["sort-filter-search", "saved-views-first-class"]}}, "reason": "read-to-find"},
+  {"when": {"ordering": ["priority", "sla", "age"], "ownership": ["claimable", "assigned"], "structuralChangeAllowed": "__absent__"}, "then": {"archetypes": {"mustInclude": ["queue"], "mustNotInclude": ["browse"]}, "requiredMechanics": {"mustInclude": ["claim-assignment", "sla-age-clock", "take-next-auto-advance", "keyboard-velocity", "bulk-triage-bar"]}, "requiredStates": {"mustInclude": ["empty-cleared"]}}, "reason": "prioritized-claimable-work-is-a-queue"},
+  {"when": {"ordering": ["priority", "sla", "age"], "ownership": ["claimable", "assigned"], "structuralChangeAllowed": true}, "then": {"archetypes": {"mustInclude": ["queue"], "mustNotInclude": ["browse"]}, "requiredMechanics": {"mustInclude": ["claim-assignment", "sla-age-clock", "take-next-auto-advance", "keyboard-velocity", "bulk-triage-bar"]}, "requiredStates": {"mustInclude": ["empty-cleared"]}}, "reason": "prioritized-claimable-work-is-a-queue"},
+  {"when": {"ordering": ["priority", "sla", "age"], "ownership": "__absent__"}, "then": {"clarifications": ["ownership-model-unspecified"]}, "reason": "queue-needs-an-ownership-model"},
+  {"when": {"ownership": "claimable", "collaboration": "concurrent"}, "then": {"requiredStates": {"mustInclude": ["unassigned", "claimed-by-me", "claimed-by-other", "stale"]}, "requiredMechanics": {"mustInclude": ["ownership-conflict"]}}, "reason": "concurrent-claims-need-claim-states"},
+  {"when": {"primaryJob": "edit-bulk"}, "then": {"archetypes": {"mustInclude": ["grid"]}, "requiredMechanics": {"mustInclude": ["inline-cell-edit", "type-aware-editors", "fill-down-range-select"]}}, "reason": "edit-in-place-is-its-own-archetype"},
+  {"when": {"viewTypeRequested": ["table", "board", "cards", "calendar", "timeline", "map"]}, "then": {"archetypes": {"mustNotInclude": ["table", "board", "cards", "calendar", "timeline", "map"]}, "requiredMechanics": {"mustInclude": ["view-switcher-projection", "filters-stable-across-projections"]}}, "reason": "view-type-is-a-projection"},
+  {"when": {"viewTypeRequested": "board", "hasStatusField": true}, "then": {"requiredMechanics": {"mustInclude": ["board-drag-is-transition"]}}, "reason": "drag-is-a-state-transition"},
+  {"when": {"viewTypeRequested": "board", "hasStatusField": false}, "then": {"clarifications": ["projection-field-missing"]}, "reason": "board-needs-a-status-field"},
+  {"when": {"viewTypeRequested": "calendar", "hasDateField": false}, "then": {"clarifications": ["projection-field-missing"]}, "reason": "calendar-needs-a-date-field"},
+  {"when": {"primaryJob": "route-work"}, "then": {"archetypes": {"mustInclude": ["queue"], "mustNotInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["viewer-scoped-work-router", "deep-links-to-records"]}}, "reason": "work-router-is-a-viewer-scoped-queue"},
+  {"when": {"unitOfWork": "machine-proposal"}, "then": {"archetypes": {"mustInclude": ["queue"]}, "requiredMechanics": {"mustInclude": ["review-queue-confidence-tiers", "evidence-pack", "batch-approve-within-tier"]}}, "reason": "agent-output-review-queue"},
+  {"when": {"unitOfWork": "thread"}, "then": {"archetypes": {"mustInclude": ["queue", "record-detail"]}, "requiredMechanics": {"mustInclude": ["three-pane-inbox", "inline-composer", "audience-split-verbs"]}}, "reason": "conversational-inbox-is-a-thread-queue"},
+  {"when": {"primaryJob": "author"}, "then": {"archetypes": {"mustInclude": ["creation-flow"]}}, "reason": "authoring-gets-creation-flow"},
+  {"when": {"primaryJob": "configure"}, "then": {"archetypes": {"mustInclude": ["settings"]}}, "reason": "configuration-lands-on-settings"},
+  {"when": {"primaryJob": ["monitor", "narrate-period"]}, "then": {"archetypes": {"mustInclude": ["dashboard"]}}, "reason": "glance-and-report-are-dashboard"},
+  {"when": {"primaryJob": "investigate"}, "then": {"archetypes": {"mustInclude": ["browse", "record-detail"]}, "requiredMechanics": {"mustInclude": ["event-stream-explorer", "facet-filters", "aggregate-to-event-drill"]}}, "reason": "events-not-records"},
+  {"when": {"structuralChangeAllowed": false}, "then": {"requiredMechanics": {"mustInclude": ["layer-mechanics-on-existing-surface"]}}, "reason": "preserve-existing-structure"},
+  {"when": {"structuralChangeAllowed": false, "existingArchetype": "browse"}, "then": {"archetypes": {"mustInclude": ["browse"], "mustNotInclude": ["queue", "grid"]}}, "reason": "existing-archetype-retained"},
+  {"when": {"structuralChangeAllowed": false, "existingArchetype": "queue"}, "then": {"archetypes": {"mustInclude": ["queue"], "mustNotInclude": ["browse", "grid"]}}, "reason": "existing-archetype-retained"},
+  {"when": {"structuralChangeAllowed": false, "existingArchetype": "grid"}, "then": {"archetypes": {"mustInclude": ["grid"], "mustNotInclude": ["browse", "queue"]}}, "reason": "existing-archetype-retained"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/promotion-demotion.md

@@ -0,0 +1,37 @@
+---
+id: promotion-demotion
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.6"
+license: open
+---
+# Pass: promotion & demotion
+
+**Inputs:** per object × role — `frequency` (high | medium | low: how often this role touches it), `criticality`, `isParent`, `demotionContractMet`, `perRoleVariance`.
+**Owns:** `requiredMechanics`, `clarifications`.
+**Output artifact:** a per-persona sidebar — which objects earn top-level prominence and which are reachable only through other objects — plus a landing type per promoted item (chosen in the `page-archetype` pass). This pass covers exactly one IA decision: promotion/demotion; navigation mechanics are out of scope.
+
+## The rule
+
+**Prominence = frequency × criticality, computed per role. Parenthood is not the driver.** Parent/child position in the schema is a data-integrity fact; it says nothing about how often a human opens the object. The canonical counterexample: in a CRM, Account is the parent of Leads, Contacts, and Opportunities — and it is demoted; reps live in Leads, Opportunities, and Tasks. If you find yourself promoting an object because "it's the parent," ask instead who opens it, how often, and what breaks if they can't — that answer sets the sidebar. Without a frequency reading per role, prominence cannot be computed: clarify.
+
+**Prominence is per persona × plan.** An object demoted for a rep is promoted for the ops admin who lives in it; the same schema yields different sidebars per role. Plan-gated items change what each tenant's sidebar contains (whether locked items render hidden or as upsell is `viewer-context`'s call). Agents and agent surfaces now compete for promoted slots like any object.
+
+**The demotion contract** — demotion is only safe when two guarantees hold, or it punishes users:
+1. **Creatable in context** — every demoted object is creatable from inside the flows of promoted objects that reference it (nested create-in-context: "+ New Account" inside the Lead form). If a rep must abandon a half-filled form to create the parent first, the demotion has failed.
+2. **Reachable in context** — every demoted object is readable from the promoted objects it relates to, via related lists and parent links on their detail pages. The demoted object gives up its sidebar entry, not its existence.
+
+Test every demotion: *can a user create it and reach it without ever visiting a dedicated page for it?* If yes, demote freely; if no, promote it or fix the contract first.
+
+**Anti-patterns encoded below:** the schema-mirror sidebar (promoting every top-level object because it exists — the sidebar is a frequency map, not an ER diagram); parent-first promotion; one static sidebar for all roles; demotion without the contract.
+
+```json decision-table
+{"pass": "promotion-demotion", "rows": [
+  {"when": {"frequency": "high"}, "then": {"requiredMechanics": {"mustInclude": ["sidebar-promotion"]}}, "reason": "frequency-times-criticality-wins-sidebar"},
+  {"when": {"frequency": "low"}, "then": {"requiredMechanics": {"mustInclude": ["demote-reachable-in-context", "nested-create-in-context", "related-list-reachability"], "mustNotInclude": ["sidebar-promotion"]}}, "reason": "low-frequency-demotes-with-contract"},
+  {"when": {"frequency": "low", "isParent": true}, "then": {"requiredMechanics": {"mustNotInclude": ["parent-first-promotion"]}}, "reason": "parenthood-is-not-navigational"},
+  {"when": {"demotionContractMet": false, "frequency": "low"}, "then": {"requiredMechanics": {"mustInclude": ["nested-create-in-context", "related-list-reachability"]}}, "reason": "demotion-contract-before-demotion"},
+  {"when": {"perRoleVariance": true}, "then": {"requiredMechanics": {"mustInclude": ["per-persona-sidebar"], "mustNotInclude": ["single-shared-sidebar"]}}, "reason": "prominence-per-persona-times-plan"},
+  {"when": {"frequency": "__absent__"}, "then": {"clarifications": ["role-frequency-unspecified"]}, "reason": "prominence-needs-a-frequency-reading"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/settings.md

@@ -0,0 +1,42 @@
+---
+id: settings
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.16"
+license: open
+---
+# Pass: settings
+
+**Inputs:** per settings surface — `isSettingsPage`, `scope` (personal | workspace | org), `settingKind` (leaf-preference | config-object), `riskClass` (preference | behavior-config | structural-destructive), `subject`, `multiScopeSetting`, `nodeCount` (under-30 | over-30), `governedSurfaceLink`, `buildTimeGeneration`, `productSurfaceInTree`.
+**Owns:** `archetypes`, `requiredStates`, `requiredMechanics`, `clarifications`.
+**Output artifact:** the settings area treated as a **shadow meta-product** — the scope/subject/risk taxonomy, config-objects-not-forms, the interaction tier per risk class, the inheritance cascade, findability, and the AI governance subjects — reusing the whole playbook recursively rather than being hand-designed as a tree of forms.
+
+## The rule
+
+**Settings is not a page tree — it is the product's shadow meta-product**, used by a different persona (admins/builders), at a different frequency (rare), in a different mode (Configuration: deliberate, consequential, preview-hungry). Most of it should reuse the playbook, not be designed as forms.
+
+**Config is objects, not forms.** A large share of "settings" are **config objects with full lifecycles** — webhooks/API keys (an index + detail with delivery logs), roles & permission sets (entity details with related-user lists and an impact surface), pipelines/stages/custom fields (a schema builder — the object model exposed as product), automations (canvas-builder with draft-vs-publish), templates/snippets/brand kits (standing-context assets), notification/SLA policies (config objects with versions and audit). Each has an index, a detail, a create flow, a state machine (draft / enabled / disabled), versioning, and Logged history. **Only leaf preferences — true toggles — are forms.** Designing settings as "a tree of forms" is the root mistake.
+
+**Three orthogonal axes, and the navigation rule.** *Scope* — who it affects: personal / workspace / organization. *Subject* — what it configures: identity & access, data model, automation, notifications, integrations, branding, billing & plan, compliance & audit, and AI & agent policy. *Risk class* — how it takes effect: instant toggle, draft-publish config object, or structural migration. **Navigate by scope first, then subject** — scope maps directly to permissions and to the user's mental question, "am I changing this for me, or for everyone?" **Blast radius is declared, not inferred**: every settings page carries a blast-radius declaration in its header ("Affects only you" / "Affects everyone in Acme Corp") — a required element, the settings-land equivalent of the environment banner — paired with distinct per-scope chrome. Configuration belongs on a full surface, never a context-losing modal.
+
+**Risk class dictates the interaction tier.** *Preferences* (personal, reversible, instant): autosave silently, no confirm — friction here is pure tax. *Behavior config* (affects others, reversible): explicit save plus a changelog entry, and the setting's own Logged history answers "who changed this and when." *Structural & destructive* (schema changes, role edits, SSO, retention, deletion): the full ceremony — **draft → impact preview → publish**, where the impact preview is the load-bearing step ("this role change affects 34 users"; "changing this field type will truncate 1,204 values"); add maker-checker where policy demands, isolate the irreversible in a type-to-confirm **danger zone**, and log everything to the org audit trail. Tier-3 changes deserve the test-before-live discipline of the AI layer's agent CI (simulate the rule against yesterday's traffic before publishing).
+
+**The inheritance cascade — the most underserved settings pattern.** Any setting existing at more than one scope forms a cascade (org default → team override → user override), and the UI must solve the resolved-value problem: show the **effective value** the viewer gets, show **where it came from** ("inherited from Organization" vs "overridden here"), and offer **reset to inherit** as a first-class action distinct from "set to the same value." Once a cascade exists, impersonation/view-as is the only honest debugger. **Findability**: settings search is mandatory past ~30 nodes (admins remember words, not the tree), every setting has a stable deep link, and the in-context gear links bidirectionally between a governed surface and the setting that governs it. **The AI subjects (2026)**: build-time generation compiles NL to an inspectable artifact editable before commit — never a black box; the agent governance console (identities, model-routing, data masking, permission scoping, the AI-action audit view) is a new org-scope subject. Anti-patterns forbidden: the junk drawer, features hiding in settings (saved views, dashboards, templates are product surfaces, not settings), modal settings, and the invisible cascade. A settings page whose scope is undeclared cannot be placed or permissioned: clarify.
+
+```json decision-table
+{"pass": "settings", "rows": [
+  {"when": {"isSettingsPage": true}, "then": {"archetypes": {"mustInclude": ["settings"]}, "requiredMechanics": {"mustInclude": ["blast-radius-declaration-header", "navigate-scope-first-then-subject", "per-scope-chrome"], "mustNotInclude": ["modal-settings", "settings-as-tree-of-forms"]}}, "reason": "blast-radius-declared-not-inferred"},
+  {"when": {"settingKind": "config-object"}, "then": {"requiredMechanics": {"mustInclude": ["config-object-full-surface-set", "config-state-machine", "config-versioning", "config-logged-history"], "mustNotInclude": ["config-as-leaf-form"]}}, "reason": "config-is-objects-not-forms"},
+  {"when": {"settingKind": "leaf-preference"}, "then": {"requiredMechanics": {"mustInclude": ["leaf-toggle-form"]}}, "reason": "only-true-toggles-are-forms"},
+  {"when": {"riskClass": "preference"}, "then": {"requiredMechanics": {"mustInclude": ["autosave-silent-no-confirm"], "mustNotInclude": ["confirm-on-preference"]}}, "reason": "preference-autosaves-friction-is-tax"},
+  {"when": {"riskClass": "behavior-config"}, "then": {"requiredMechanics": {"mustInclude": ["explicit-save", "changelog-entry", "logged-history"]}}, "reason": "behavior-config-logs-who-changed"},
+  {"when": {"riskClass": "structural-destructive"}, "then": {"requiredMechanics": {"mustInclude": ["draft-impact-preview-publish", "impact-preview", "danger-zone-type-to-confirm", "org-audit-logged"], "mustNotInclude": ["optimistic-apply", "edit-live-in-place"]}}, "reason": "structural-changes-earn-full-ceremony"},
+  {"when": {"multiScopeSetting": true}, "then": {"requiredMechanics": {"mustInclude": ["effective-value-shown", "inherited-from-indicator", "reset-to-inherit"], "mustNotInclude": ["invisible-cascade"]}}, "reason": "a-cascade-must-be-readable"},
+  {"when": {"nodeCount": "over-30"}, "then": {"requiredMechanics": {"mustInclude": ["settings-search", "stable-deep-links"]}}, "reason": "search-mandatory-past-thirty-nodes"},
+  {"when": {"governedSurfaceLink": true}, "then": {"requiredMechanics": {"mustInclude": ["in-context-gear-bidirectional-link"]}}, "reason": "shadow-product-stays-connected-to-product"},
+  {"when": {"subject": "ai-agent-policy"}, "then": {"requiredMechanics": {"mustInclude": ["agent-governance-console", "model-routing-policy", "data-masking-before-llm", "ai-action-audit-view"]}}, "reason": "ai-governance-is-an-org-scope-subject"},
+  {"when": {"buildTimeGeneration": true}, "then": {"requiredMechanics": {"mustInclude": ["nl-compiles-to-inspectable-artifact", "edit-before-commit"], "mustNotInclude": ["opaque-black-box"]}}, "reason": "compile-to-the-inspectable-artifact"},
+  {"when": {"productSurfaceInTree": true}, "then": {"requiredMechanics": {"mustNotInclude": ["features-hiding-in-settings"]}}, "reason": "product-surfaces-are-not-settings"},
+  {"when": {"isSettingsPage": true, "scope": "__absent__"}, "then": {"clarifications": ["setting-scope-unspecified"]}, "reason": "navigate-by-scope-first-so-scope-is-required"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/standard-pages.md

@@ -0,0 +1,46 @@
+---
+id: standard-pages
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.12"
+license: open
+---
+# Pass: standard pages
+
+**Inputs:** per meta-object page — `standardPage` (settings | profile | notifications | audit-object | audit-global | user-management | roles-permissions | seats-licenses | billing | integrations); plus signals — `notificationDelivery`, `ssoScimProvisioning`, `complianceBuyer`, `recordLevelAccess`, `externalSystemMapping`.
+**Owns:** `archetypes`, `requiredMechanics`, `clarifications`.
+**Output artifact:** the settings/profile/notifications/audit/admin/integration pages every B2B product ships regardless of domain — each generated by the earlier passes as an index, detail, or form over a meta-object (users, roles, notifications, audit events, connections), not hand-designed. The full settings scope/subject/risk taxonomy is the `settings` pass; this pass names the pages and their contracts.
+
+## The rule
+
+**Standard pages are not exempt from the method — they are the method applied to meta-objects.** Each is an index, a detail page, or a form over users, roles, notifications, audit events, or connections, and carries the same archetype, state matrix, and viewer-context obligations as any domain surface.
+
+**Profile is a detail page** over the User object where viewer = subject: identity fields, avatar, credentials/security (password, 2FA, sessions), and pointers into personal-scope settings.
+
+**The notifications page is a derived index, not a primary object.** Asset-level verbs (watch, subscribe, assign, @mention) combined with the viewer's relationships produce notification records; the page is their index — reverse-chronological, read/unread, filterable by type, each item deep-linking to the record and moment that produced it. For operational products this index doubles as a **work-router** ("what needs me"), so treat its ordering and grouping with index-level seriousness. Beside it lives the **notification preferences matrix** (personal scope): event types × delivery channels, with batching cadence per cell (instant / hourly / daily digest / off) plus a global mute — load-bearing, because getting batching wrong is a top reason users disengage.
+
+**Audit has two surfaces, both outputs of the Logged history class at different scopes.** Per-object history is the record-scoped timeline on every detail page. The **global audit log** is an org-scope, append-only index of who-did-what-when across security-relevant actions — logins, permission changes, deletions, exports, setting changes, and every impersonation session (impersonation is always logged, no exceptions) — filterable by actor/action/object/time, searchable, exportable; for SOC2/enterprise buyers it is a purchase criterion, not an afterthought.
+
+**Admin pages are indexes and forms over the org's meta-objects.** User management (invite — noting SSO/SCIM may provision users externally, so the invite form is not the only entry point — role assignment, deactivation) must trigger an **ownership-transfer flow** on deactivation: reassign the departing user's records before the account closes, or orphaned records are guaranteed. Roles & permissions is the admin surface for the access layers, paired with **impersonation/view-as** — once record- and field-level access exist, "log in as this user" is the only practical way to debug what a person actually sees. Seats & licenses render "X of Y seats used," pending invites, and reclaim-on-deactivation. Billing is brief here; customer-facing usage/billing surfaces are deferred.
+
+**Integrations resolve to objects, never a free-floating layer.** External data always maps to objects and fields: a connect flow (OAuth or keys, workspace scope), a **field-mapping editor** (their "Company" ↔ your "Account," with sync direction and frequency per mapping), and **connection health** (status, last successful sync, error counts, per-connection sync logs as an index of sync events); synced fields carry their origin declaration wherever they render. When a standard-page request omits which meta-object it is over, its contract cannot be derived: clarify.
+
+```json decision-table
+{"pass": "standard-pages", "rows": [
+  {"when": {"standardPage": "settings"}, "then": {"archetypes": {"mustInclude": ["settings"]}, "requiredMechanics": {"mustInclude": ["three-scope-split", "per-scope-edit-permissions"]}}, "reason": "settings-is-a-scope-tree"},
+  {"when": {"standardPage": "profile"}, "then": {"archetypes": {"mustInclude": ["record-detail"]}, "requiredMechanics": {"mustInclude": ["viewer-equals-subject", "credentials-security-section"]}}, "reason": "profile-is-a-detail-page-over-user"},
+  {"when": {"standardPage": "notifications"}, "then": {"archetypes": {"mustInclude": ["browse", "queue"]}, "requiredMechanics": {"mustInclude": ["notification-index-deep-links", "read-unread-state", "notification-preferences-matrix", "global-mute"]}}, "reason": "notifications-is-a-derived-index-and-router"},
+  {"when": {"notificationDelivery": true}, "then": {"requiredMechanics": {"mustInclude": ["event-type-by-channel-matrix", "per-cell-batching-cadence"]}}, "reason": "batching-matrix-is-load-bearing"},
+  {"when": {"standardPage": "audit-global"}, "then": {"archetypes": {"mustInclude": ["browse"]}, "requiredMechanics": {"mustInclude": ["append-only-audit-log", "impersonation-always-logged", "filter-actor-action-object-time", "audit-exportable"]}}, "reason": "global-audit-is-a-compliance-index"},
+  {"when": {"standardPage": "audit-object"}, "then": {"archetypes": {"mustInclude": ["record-detail"]}, "requiredMechanics": {"mustInclude": ["record-scoped-history-timeline"]}}, "reason": "per-object-history-is-the-detail-timeline"},
+  {"when": {"standardPage": "user-management"}, "then": {"archetypes": {"mustInclude": ["browse", "creation-flow"]}, "requiredMechanics": {"mustInclude": ["ownership-transfer-on-deactivation", "role-assignment"], "mustNotInclude": ["orphaned-records-on-deactivation"]}}, "reason": "deactivation-must-transfer-ownership"},
+  {"when": {"ssoScimProvisioning": true}, "then": {"requiredMechanics": {"mustInclude": ["external-provisioning-entry-point"], "mustNotInclude": ["invite-form-only-entry-point"]}}, "reason": "sso-scim-provisions-outside-the-invite-form"},
+  {"when": {"standardPage": "roles-permissions"}, "then": {"archetypes": {"mustInclude": ["record-detail"]}, "requiredMechanics": {"mustInclude": ["permission-impact-surface", "impersonation-view-as"]}}, "reason": "roles-need-a-view-as-debugger"},
+  {"when": {"recordLevelAccess": true}, "then": {"requiredMechanics": {"mustInclude": ["impersonation-view-as", "impersonation-banner", "impersonation-audit-logged"]}}, "reason": "view-as-is-the-only-honest-access-debugger"},
+  {"when": {"standardPage": "seats-licenses"}, "then": {"requiredMechanics": {"mustInclude": ["seats-used-of-total", "pending-invites", "reclaim-on-deactivation"]}}, "reason": "seats-render-as-metered-usage"},
+  {"when": {"standardPage": "integrations"}, "then": {"requiredMechanics": {"mustInclude": ["connect-flow", "field-mapping-editor", "connection-health-log"]}}, "reason": "integrations-resolve-to-objects-and-fields"},
+  {"when": {"externalSystemMapping": true}, "then": {"requiredMechanics": {"mustInclude": ["field-mapping-editor", "sync-direction-per-mapping", "synced-field-provenance"]}}, "reason": "external-mapping-is-object-mapped"},
+  {"when": {"complianceBuyer": true}, "then": {"requiredMechanics": {"mustInclude": ["append-only-audit-log", "audit-exportable"]}}, "reason": "audit-log-is-a-purchase-criterion"},
+  {"when": {"standardPage": "__absent__"}, "then": {"clarifications": ["standard-page-subject-unspecified"]}, "reason": "contract-derives-from-the-meta-object"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/state-matrix.md

@@ -0,0 +1,41 @@
+---
+id: state-matrix
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.11"
+license: open
+---
+# Pass: state matrix & onboarding
+
+**Inputs:** per surface — `isListSurface`, `dataFetch`, `fetchLatency`, `compositePage`, `consumesCachedData`, `streamingView`, `optimisticMutation`, `queueSuccessIsEmpty`, `firstRunSurface`; per onboarding technique — `onboardingTechnique`, `onboardingScope` (application-level | empty-state).
+**Owns:** `requiredStates`, `requiredMechanics`, `clarifications`.
+**Output artifact:** the state matrix every page carries **orthogonal to its archetype** — loading, three distinct empties, degraded, stale, recovery — plus optimistic-UI rollback and the two-home classification of every onboarding technique. Archetypes describe pages as if data always arrives; this pass specifies what renders when data hasn't, can't, or shouldn't be trusted.
+
+## The rule
+
+**Loading is skeletons, not spinners.** Gray placeholder shapes matched to the eventual layout — matched geometry (row height, card size) so the layout doesn't jump when data lands; composite pages skeleton per region, not whole-page. Spinners are acceptable only for actions without a known destination shape.
+
+**An empty region means three unrelated things, and each demands different treatment** — collapsing them into one "No results" string is the most common state bug in B2B. **First-run empty** — no data has ever existed here — is an onboarding surface: teach the object's value, offer both a create path and a sample-data path; it is the highest-attention real estate a new account sees. **Filtered-to-zero** — data exists but the filter excludes all of it — is a compact message that restates the active filters with one-click "clear filters"; showing first-run marketing copy to a power user whose saved view returned zero reads as data loss. **Failed-to-load** — the fetch errored — is an honest error with a retry affordance, visually distinct from both empties; silence or a generic empty makes users believe their data is gone. A list surface must carry all three, distinctly.
+
+**Degraded and stale are honest surfaces.** On composite pages, each independently-fetched region owns its own loading and error boundary: one failed widget shows an inline "couldn't load — retry" while the rest of the page stays live — the whole page never dies for one bad call. People make decisions on cached numbers, so consumed data carries a **freshness cue** — "updated 2m ago," an as-of timestamp on financial figures, a live/paused indicator on streaming views, and a manual refresh; serve cached instantly, revalidate in the background, and say so. A queue whose success metric is an empty list carries a distinct **cleared-empty** state — celebrated, not a failure.
+
+**Optimistic UI makes its rollback visible.** Mutations apply to the UI instantly and reconcile in the background; on failure the rollback is *visible* — a toast naming what failed, the value reverting in view, and a retry that preserves the user's input. Never silently revert (the user believes the edit stuck) and never silently lose the edit. This pairs with the reversible-action undo rule: reversible actions get optimistic-apply + undo; only genuinely irreversible ones get a blocking confirm.
+
+**Onboarding has exactly two homes, no third — classify every technique into one.** *Application-level* patterns live in the product's chrome, span sessions, and concern the whole workspace: the setup checklist (persistent, dismissible, progress-tracked, surviving across sessions until completed), product tours/coach-marks (sparing, dismissible, contextually triggered — never a forced first-login gauntlet), and sample/demo data (pre-seeded realistic records with a path to delete or convert). *Empty-state* patterns live inside a specific page's first-run empty: empty-state-as-teacher — the page explaining itself with an inline example or template gallery and both "create real" and "load sample" paths. The classification matters because the lifecycles differ: application-level patterns end when the account activates; empty-state patterns recur forever — every new module, team, or newly permissioned object presents a first-run empty to somebody. An onboarding technique whose home is undeclared cannot be placed: clarify.
+
+```json decision-table
+{"pass": "state-matrix", "rows": [
+  {"when": {"dataFetch": true}, "then": {"requiredStates": {"mustInclude": ["loading"]}, "requiredMechanics": {"mustInclude": ["skeleton-matched-geometry", "per-region-skeleton"], "mustNotInclude": ["spinner-with-known-shape"]}}, "reason": "loading-is-skeletons-not-spinners"},
+  {"when": {"isListSurface": true}, "then": {"requiredStates": {"mustInclude": ["empty-first-run", "empty-filtered", "failed-to-load"]}, "requiredMechanics": {"mustInclude": ["distinct-empty-treatments", "clear-filters-affordance", "retry-on-failed-load"], "mustNotInclude": ["single-no-results-string"]}}, "reason": "three-empties-are-distinct"},
+  {"when": {"compositePage": true}, "then": {"requiredStates": {"mustInclude": ["degraded"]}, "requiredMechanics": {"mustInclude": ["per-region-error-boundary", "inline-retry-per-region"], "mustNotInclude": ["whole-page-dies-for-one-call"]}}, "reason": "degraded-isolates-per-region"},
+  {"when": {"consumesCachedData": true}, "then": {"requiredStates": {"mustInclude": ["stale"]}, "requiredMechanics": {"mustInclude": ["freshness-cue-as-of-timestamp", "manual-refresh", "revalidate-in-background"]}}, "reason": "decisions-get-made-on-cached-numbers"},
+  {"when": {"streamingView": true}, "then": {"requiredMechanics": {"mustInclude": ["live-paused-indicator"]}}, "reason": "streaming-declares-live-or-paused"},
+  {"when": {"optimisticMutation": true}, "then": {"requiredMechanics": {"mustInclude": ["optimistic-apply", "visible-rollback-toast", "retry-preserves-input"], "mustNotInclude": ["silent-revert", "silent-edit-loss"]}}, "reason": "rollback-must-be-visible"},
+  {"when": {"queueSuccessIsEmpty": true}, "then": {"requiredStates": {"mustInclude": ["empty-cleared"]}}, "reason": "a-cleared-queue-is-celebrated"},
+  {"when": {"firstRunSurface": true}, "then": {"requiredStates": {"mustInclude": ["empty-first-run"]}, "requiredMechanics": {"mustInclude": ["empty-state-as-teacher", "create-real-path", "load-sample-path"]}}, "reason": "first-run-is-the-page-teaching-itself"},
+  {"when": {"fetchLatency": true}, "then": {"requiredMechanics": {"mustInclude": ["skeleton-matched-geometry"], "mustNotInclude": ["layout-jump-on-load"]}}, "reason": "skeleton-geometry-prevents-jank"},
+  {"when": {"onboardingScope": "application-level"}, "then": {"requiredMechanics": {"mustInclude": ["setup-checklist-persistent", "dismissible-contextual-tours", "sample-data-with-convert-or-delete"]}}, "reason": "app-level-onboarding-spans-sessions"},
+  {"when": {"onboardingScope": "empty-state"}, "then": {"requiredMechanics": {"mustInclude": ["empty-state-as-teacher"]}}, "reason": "empty-state-onboarding-is-page-scoped"},
+  {"when": {"onboardingTechnique": true, "onboardingScope": "__absent__"}, "then": {"clarifications": ["onboarding-home-unspecified"]}, "reason": "every-technique-classifies-into-one-of-two-homes"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/table-mechanics.md

@@ -0,0 +1,48 @@
+---
+id: table-mechanics
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.10"
+license: open
+---
+# Pass: table mechanics
+
+**Inputs:** per index surface — `revisitedWithIntent`, `sharedViewScope` (personal | team), `wideObject`, `heavyDailyUse`, `groupBySegment`, `crossCuttingHealthNumbers`, `gridEditable`, `bulkVerbs`, `rowActions`, `hasStatusField`, `viewerRelationships`, `largeDataset`, `listLength` (paginated | infinite | virtualized), `financialRecordKeeping`, `sharedMutableList`, `exportNeeded`.
+**Owns:** `requiredMechanics`, `clarifications`.
+**Output artifact:** the parts list every index-family archetype (browse, queue, grid) assembles — saved views, column management, sticky chrome, grouping, in-table editing, bulk and row affordances, scannability, viewer-relative decoration, list-length strategy, real-time behavior, and export — while the archetype decides which parts appear and the success metric.
+
+## The rule
+
+Tables render **f(data, viewer)** — the same rows are decorated differently per viewer — and which row actions exist is a function of object state and role, never a fixed toolbar. The machinery below is shared across browse, queue, and grid; each archetype assembles it differently.
+
+**View state.** A **saved view** is a named, persistent object — filter + sort + columns + grouping + view-type — with an owner, a sharing scope, pinnability, and an optional default flag, for any index a user visits more than once with the same intent; distinguish personal (private workspace) from team (governed shared lens) from day one, because retrofitting governance onto ungoverned shared views is painful. Wide objects need **column management** (show/hide, drag-reorder, resize, freeze) with the identity column frozen left, and **sticky chrome** (pinned header on vertical scroll, pinned totals footer when grouped). Heavy daily users get a **density toggle** (compact/comfortable, wrap-vs-truncate).
+
+**Aggregation lives in the table, not only on analytics pages.** When the natural reading is "by segment" (pipeline by stage, tickets by assignee), use **grouping with per-group and grand-total summary rows**. **Stat cards above the table** are the complement, not a substitute: totals *of the visible segments* belong in the table via grouping; rates, trends, and cross-cutting health numbers belong in stat cards.
+
+**Editing and acting on rows.** In the grid archetype the table is the primary write surface: **inline cell editing** with type-aware editors (dropdown, date picker, user picker, checkbox), Tab/Enter/arrow traversal, optimistic commit; and **range operations** (rectangular select, copy/paste, drag-fill). Per-cell editability is decided by field-level access and the field's declarations — the same column is editable for one viewer, static for another. Bulk work gets **row checkboxes with a floating action bar** carrying the legal batch verbs, and keeps two semantics distinct: **select-visible** (this page) versus **select-all-matching** the filter (offered explicitly, "Select all 1,204 matching") — the first must never masquerade as the second — with **per-row partial-failure** reporting, never a blanket success. Rows carry **hover actions** (2–3 highest-frequency verbs) and an **overflow/context menu** (the full legal set for that row's state).
+
+**Scannability and viewer decoration.** **Conditional formatting and status chips** are the pre-attentive layer — color-coded badges, priority icons, SLA-countdown colors, progress bars — rendering the state machine consistently everywhere the record appears; never encode with color alone, always pair with text or an icon. The index also carries **viewer-relative decoration** joined from the viewer's own relationships: mine, watched, unread/new, assigned-to-me (the default operational lens).
+
+**List length, real-time, and export.** The **list-length strategy** is a deliberate choice that silently dictates selection semantics, exportability, and jump-to-position: pagination (stable, addressable — right for financial/record-keeping lists), infinite scroll (fluid — right for feeds and triage), or virtualization (the grid's default). Whatever the strategy, export-all and select-all operate on the *filtered set*, not the loaded window. Shared lists mutate under the user: never reflow under the cursor — new/changed records arrive behind an **"N new records" pill**, others' edits get a **fading soft highlight**, and scroll position and selection survive updates. **View-aware export** respects active filters, visible columns, and sort, with large exports as background jobs and scheduled recurring delivery — extraction is a security-relevant, audit-logged verb. When a large dataset's list-length strategy is undeclared, selection and export semantics are undecidable: clarify.
+
+```json decision-table
+{"pass": "table-mechanics", "rows": [
+  {"when": {"revisitedWithIntent": true}, "then": {"requiredMechanics": {"mustInclude": ["saved-views-first-class"]}}, "reason": "revisited-index-earns-saved-views"},
+  {"when": {"sharedViewScope": "team"}, "then": {"requiredMechanics": {"mustInclude": ["personal-vs-team-view-scope", "view-sharing-governance"]}}, "reason": "shared-views-are-governed-lenses"},
+  {"when": {"wideObject": true}, "then": {"requiredMechanics": {"mustInclude": ["column-management", "frozen-identity-column", "sticky-header-chrome"]}}, "reason": "wide-objects-need-column-control"},
+  {"when": {"heavyDailyUse": true}, "then": {"requiredMechanics": {"mustInclude": ["density-toggle"]}}, "reason": "daily-users-trade-whitespace-for-rows"},
+  {"when": {"groupBySegment": true}, "then": {"requiredMechanics": {"mustInclude": ["grouping-with-summary-rows"]}}, "reason": "by-segment-reading-groups-in-table"},
+  {"when": {"crossCuttingHealthNumbers": true}, "then": {"requiredMechanics": {"mustInclude": ["stat-cards-above-table"]}}, "reason": "rates-and-trends-are-stat-cards"},
+  {"when": {"gridEditable": true}, "then": {"requiredMechanics": {"mustInclude": ["inline-cell-edit", "type-aware-editors", "range-operations-fill"]}}, "reason": "grid-is-the-write-surface"},
+  {"when": {"bulkVerbs": true}, "then": {"requiredMechanics": {"mustInclude": ["bulk-selection-floating-bar", "select-all-matching-distinct-from-visible", "per-row-partial-failure-report"], "mustNotInclude": ["visible-masquerades-as-all", "blanket-success-report"]}}, "reason": "bulk-keeps-visible-and-all-distinct"},
+  {"when": {"rowActions": true}, "then": {"requiredMechanics": {"mustInclude": ["hover-actions", "overflow-context-menu"]}}, "reason": "common-actions-without-a-round-trip"},
+  {"when": {"hasStatusField": true}, "then": {"requiredMechanics": {"mustInclude": ["conditional-formatting-status-chips"], "mustNotInclude": ["color-alone-encoding"]}}, "reason": "pre-attentive-never-color-alone"},
+  {"when": {"viewerRelationships": true}, "then": {"requiredMechanics": {"mustInclude": ["viewer-relative-decoration", "unread-new-markers"]}}, "reason": "index-renders-f-data-viewer"},
+  {"when": {"listLength": "paginated"}, "then": {"requiredMechanics": {"mustInclude": ["addressable-pages", "select-all-on-page"]}}, "reason": "pagination-is-stable-and-addressable"},
+  {"when": {"listLength": "virtualized"}, "then": {"requiredMechanics": {"mustInclude": ["windowed-virtualization"]}}, "reason": "virtualization-scrolls-large-sets"},
+  {"when": {"financialRecordKeeping": true}, "then": {"requiredMechanics": {"mustInclude": ["addressable-pages"], "mustNotInclude": ["infinite-scroll-for-records"]}}, "reason": "record-keeping-wants-stable-pages"},
+  {"when": {"sharedMutableList": true}, "then": {"requiredMechanics": {"mustInclude": ["n-new-records-pill", "others-edit-soft-highlight", "preserve-scroll-and-selection"], "mustNotInclude": ["reflow-under-cursor"]}}, "reason": "never-reflow-a-shared-list-under-the-user"},
+  {"when": {"exportNeeded": true}, "then": {"requiredMechanics": {"mustInclude": ["view-aware-export", "export-operates-on-filtered-set", "background-job-large-export", "export-audit-logged"]}}, "reason": "export-is-a-security-relevant-verb"},
+  {"when": {"largeDataset": true, "listLength": "__absent__"}, "then": {"clarifications": ["list-length-strategy-unspecified"]}, "reason": "selection-and-export-semantics-need-a-strategy"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/verbs.md

@@ -0,0 +1,45 @@
+---
+id: verbs
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.3"
+license: open
+---
+# Pass: verbs & actions
+
+**Inputs:** per verb — `verbKind` (transition | edit | association | collaboration | communication | conversion | break-glass | approval-gated), `reversible`, `outwardFacing`, `bulk`, `blastRadius` (single-record | many-records | external-fanout), `thresholdVariant`.
+**Owns:** `requiredMechanics`, `requiredStates`, `containers` (confirmation surfaces only), `clarifications`.
+**Output artifact:** the verb matrix — object × state × role → available actions — the single inventory that generates every button, quick action, bulk action, row action, context-menu entry, and empty-state CTA. No surface invents its own buttons; each shows a slice of the matrix (header: the 1–3 highest frequency × criticality verbs for this state and role; row hover: 2–3 highest-frequency; bulk bar: the bulk-capable set; context menu: the full legal set). A verb keeps the same name, icon, and semantics on every surface.
+
+## The rule
+
+**Actions = f(object, state, role).** There is no fixed button set: transitions read directly off the state-machine graph (Refund only on succeeded, Void only on open), and role gates which legal verbs this viewer may perform, including threshold variants (refund up to $500; above that the verb becomes approval-gated).
+
+**Reversibility dictates confirmation UX.** Reversible → optimistic commit + undo toast; confirm dialogs destroy flow and train users to click through them. Irreversible or outward-facing (leaves the building: send to customer, charge a card) → explicit confirmation scaled to stakes, up to typed confirmation. Undo requires the data model to be able to restore — soft-delete and the Logged class exist to guarantee it; decide reversibility in the model, then let the confirmation follow. If reversibility is undeclared on a mutating verb, clarify before choosing either treatment.
+
+**Verb classes with hard invariants:**
+- **Communication** — internal note and customer-facing send are *different verbs*, never a toggle buried in one composer: distinct affordance, distinct color, distinct confirmation weight. Sending to the wrong audience is a severity-1 failure.
+- **Conversion** — born-from transformations (Lead → Account + Contact + Opportunity) create several records atomically and need a preview of what will be created and how fields map; conversion output never passes through a create form.
+- **Break-glass** — overrides require reason capture at invocation and Logged history on everything touched; never bulk-capable — reason capture is per-incident by definition.
+- **Approval-gated** — invocation submits, never executes: the object enters a pending-approval state and an approver receives Approve/Reject with required rationale in their queue.
+- **Collaboration** — watch, assign, comment are ordinary asset-level verbs in the matrix; only their output (viewer-relative relationship data) is special.
+
+**Bulk variants** get preview-before-commit when blast radius is large ("38 leads → owner: Priya") and per-row partial-failure reporting after ("34 updated, 4 failed" with reasons) — never a blanket success.
+
+```json decision-table
+{"pass": "verbs", "rows": [
+  {"when": {"verbKind": "transition"}, "then": {"requiredMechanics": {"mustInclude": ["state-gated-availability", "verb-consistency-across-surfaces"]}}, "reason": "transitions-read-off-the-graph"},
+  {"when": {"verbKind": "edit"}, "then": {"requiredMechanics": {"mustInclude": ["inline-edit-default"]}}, "reason": "edit-verbs-are-rarely-buttons"},
+  {"when": {"verbKind": "communication"}, "then": {"requiredMechanics": {"mustInclude": ["audience-split-verbs", "distinct-send-affordances"], "mustNotInclude": ["audience-toggle-single-composer"]}}, "reason": "audience-safety-is-a-verb-split"},
+  {"when": {"verbKind": "conversion"}, "then": {"requiredMechanics": {"mustInclude": ["conversion-preview-mapping", "atomic-multi-record-create"]}}, "reason": "conversion-shows-what-it-creates"},
+  {"when": {"verbKind": "break-glass"}, "then": {"requiredMechanics": {"mustInclude": ["reason-capture-required", "logged-history-class"], "mustNotInclude": ["bulk-capability"]}}, "reason": "override-without-audit-is-liability"},
+  {"when": {"verbKind": "approval-gated"}, "then": {"requiredMechanics": {"mustInclude": ["submit-not-execute", "approver-queue-routing", "approve-reject-rationale"]}, "requiredStates": {"mustInclude": ["pending-approval"]}}, "reason": "invocation-submits-not-executes"},
+  {"when": {"verbKind": "collaboration"}, "then": {"requiredMechanics": {"mustInclude": ["ordinary-verb-treatment", "viewer-context-render-outputs"]}}, "reason": "collaboration-verbs-are-ordinary"},
+  {"when": {"thresholdVariant": true}, "then": {"requiredMechanics": {"mustInclude": ["threshold-conditional-approval"]}}, "reason": "threshold-splits-direct-and-gated"},
+  {"when": {"reversible": true, "outwardFacing": false}, "then": {"requiredMechanics": {"mustInclude": ["optimistic-commit", "undo-toast"], "mustNotInclude": ["confirm-dialog"]}, "containers": {"forbidden": ["center-modal"]}}, "reason": "undo-preserves-flow"},
+  {"when": {"reversible": false}, "then": {"requiredMechanics": {"mustInclude": ["explicit-confirmation-scaled"]}, "containers": {"acceptable": ["center-modal"]}}, "reason": "irreversible-confirms"},
+  {"when": {"outwardFacing": true}, "then": {"requiredMechanics": {"mustInclude": ["explicit-confirmation-scaled"]}}, "reason": "outward-facing-confirms"},
+  {"when": {"bulk": true}, "then": {"requiredMechanics": {"mustInclude": ["bulk-preview-before-commit", "per-row-partial-failure-report"]}}, "reason": "blast-radius-needs-preview"},
+  {"when": {"verbKind": ["transition", "edit"], "reversible": "__absent__"}, "then": {"clarifications": ["reversibility-unspecified"]}, "reason": "reversibility-decides-confirmation-ux"}
+]}
+```

package/data/harnesses/apollo/skills/design/references/ux-patterns/viewer-context.md

@@ -0,0 +1,40 @@
+---
+id: viewer-context
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.4"
+license: open
+---
+# Pass: access & viewer context
+
+**Inputs:** `denialKind` (role | plan), `entitlementKind` (boolean | metered), `fieldLevelSecurity`, `requiredFieldHidden`, `existenceLeakRisk`, `viewerKind` (human | agent), `concurrentViewers`, `collaboration`, `environmentSeparation`.
+**Owns:** `requiredMechanics`, `clarifications`.
+**Output artifact:** the access model (who can see and do what, at which tier) and the viewer-context rules — what changes per viewer even among users with identical permissions. The governing axiom: **every render is a function of (data, viewer)**; no page, form, table, or button set is universal.
+
+## The rule
+
+**Access is a union, not a role lookup:** role baseline + additive permission sets + record-level sharing (ownership, hierarchy rollup, territory) + field-level security. Two users with the same role legitimately see different rows, fields, and actions — normal operation, not an edge case. Field-level security silently reshapes every surface: a hidden field vanishes from detail, form, column picker, filter builder, export, and API — so forms and tables render from schema + viewer access, never a hard-coded field list. The classic trap: a field *required* for the object but *hidden* from a role makes creation impossible for that persona — validate layouts per role. "Read-only" is often an access artifact, not a page property.
+
+**Role-denied and plan-denied render differently.** Role-denied → hidden (or disabled where discoverability matters); never sell a user a feature their admin withheld. Plan-denied → visible but locked with an upgrade path; metered entitlements get the quota render ("4 of 5 seats used") with its own upgrade door. Conflating the two produces invisible revenue or unusable noise.
+
+**The existence contract:** denied must never render as empty — users conclude the data is missing and re-create it. Decide per object whether a forbidden record admits existence (explicit no-access, ideally with a request path) or denies it (not-found, the GitHub-404 move) when even revealing existence leaks information.
+
+**Collaboration is personalization of data display**, not a feature layer: ownership decoration, watch state and fresh-activity markers, viewer-relative filters ("Assigned to me" is typically the most-used view — a default, not a user-built filter), read/unread state, presence and edit-conflict warnings. Notification records are ordinary child objects emitted by watch/assign/mention verbs; their delivery matrix lives in `standard-pages`.
+
+**Agent principals join the union** with their own permissions and audit trail, carrying a delegated-subject chain ("acting for whom") on every read and write — effective access is the intersection of the agent's grants and its delegating subject's, never a stale copy. "Delegated to my agents" is a distinct filter from "Assigned to me". Impersonation/view-as (with a persistent banner and full audit logging) is the only honest debugger once record- and field-level access exist; a test-vs-live environment fork needs a loud persistent banner — acting in the wrong environment is one of the costliest B2B errors.
+
+```json decision-table
+{"pass": "viewer-context", "rows": [
+  {"when": {"denialKind": "role"}, "then": {"requiredMechanics": {"mustInclude": ["hidden-or-disabled-affordance"], "mustNotInclude": ["visible-locked-upsell"]}}, "reason": "role-denied-hides"},
+  {"when": {"denialKind": "plan", "entitlementKind": "boolean"}, "then": {"requiredMechanics": {"mustInclude": ["visible-locked-upsell"], "mustNotInclude": ["hidden-or-disabled-affordance"]}}, "reason": "plan-denied-sells"},
+  {"when": {"denialKind": "plan", "entitlementKind": "metered"}, "then": {"requiredMechanics": {"mustInclude": ["metered-quota-render", "upgrade-door"]}}, "reason": "metered-entitlement-render"},
+  {"when": {"fieldLevelSecurity": true}, "then": {"requiredMechanics": {"mustInclude": ["schema-driven-rendering", "per-viewer-field-filtering"], "mustNotInclude": ["hard-coded-field-list"]}}, "reason": "fls-reshapes-every-surface"},
+  {"when": {"requiredFieldHidden": true}, "then": {"requiredMechanics": {"mustInclude": ["per-role-layout-validation"]}}, "reason": "required-hidden-field-blocks-persona"},
+  {"when": {"existenceLeakRisk": true}, "then": {"requiredMechanics": {"mustInclude": ["not-found-render"], "mustNotInclude": ["denied-renders-as-empty"]}}, "reason": "existence-itself-leaks"},
+  {"when": {"existenceLeakRisk": false, "denialKind": "role"}, "then": {"requiredMechanics": {"mustInclude": ["explicit-no-access-render", "request-access-path"], "mustNotInclude": ["denied-renders-as-empty"]}}, "reason": "denied-never-reads-empty"},
+  {"when": {"viewerKind": "agent"}, "then": {"requiredMechanics": {"mustInclude": ["agent-principal-access-union", "delegated-subject-chain", "agent-audit-trail", "delegated-to-my-agents-filter"]}}, "reason": "agent-is-a-governed-principal"},
+  {"when": {"collaboration": "concurrent"}, "then": {"requiredMechanics": {"mustInclude": ["viewer-relative-filters", "assigned-to-me-default", "read-unread-state"]}}, "reason": "render-is-f-data-viewer"},
+  {"when": {"concurrentViewers": true}, "then": {"requiredMechanics": {"mustInclude": ["presence-indicators", "edit-conflict-warning"]}}, "reason": "live-viewer-context"},
+  {"when": {"environmentSeparation": true}, "then": {"requiredMechanics": {"mustInclude": ["environment-banner"]}}, "reason": "wrong-environment-costliest-error"}
+]}
+```

package/data/harnesses/apollo/skills/design/scripts/README-validator.md

@@ -0,0 +1,27 @@
+# validate-design-md.mjs — the design.md system's validator + token emitter
+
+**CLI:** `node validate-design-md.mjs <file|folder> [--mode admission|build|ship] [--json] [--emit]`
+File mode validates one design.md. Folder mode validates every `.md` in the tree (skipping `SCHEMA.md`) plus `index.csv` integrity.
+`admission` and `build` run the same checks; `ship` adds the dmv-11 drift check against a `design.tokens.css` beside the input file.
+`--json` prints `{file, fails:[{id,detail}], warns:[{id,detail}]}` (array in folder mode). Exit 0 on pass (warns allowed), 1 on any FAIL.
+
+**Emit:** `--emit` (single file) compiles the token artifact from the `yaml design-values` block to stdout — deterministic, byte-stable;
+redirect to `design.tokens.css`. Shape: `:root, :root[data-theme="light"]` + `:root[data-theme="dark"]` blocks (specificity armor, both
+0,2,0) carrying the 36 color roles as `--<role>`; the light block also carries `--font-display/sans/mono` (registered names quoted, with
+fallback stacks), `--text-<step>-size/-line/-weight` (+ `-family/-tracking/-features`), `--radius-*`, `--shadow-*`, `--duration-*`,
+`--ease-*`, and layout vars (`--space-base`, `--sidebar-width[-collapsed]`, `--topbar-height`, `--side-panel-width[-wide]`, `--content-max-width`).
+
+**Fails (close the gate):** dmv-01 frontmatter strict, per-tier keys, id = filename · dmv-02 the 12 sections in order, non-empty,
+plus trailing design-values block · dmv-03 value block parses as YAML · dmv-04 coverage: 36 roles × both themes, ramp, register-scope,
+elevation, motion base, iconography, charts, layout · dmv-05 contrast on every declared pairing (body ≥ 4.5:1; primary/accent/
+destructive/sidebar-primary fills ≥ 3:1, warn under 4.5) · dmv-06 no image reference anywhere · dmv-07 index.csv ↔ files, both
+directions, no duplicates · dmv-08 registered font names + fallback stacks · dmv-09 no claude.md (any case) · dmv-10 project tier:
+`primitives: nurix|native` + `source-package` · dmv-11 (ship) emitted artifact byte-matches recompilation.
+
+**Warns (recorded, never close):** dmw-01 background in the anti-cream band (L 0.84–0.97, C < 0.06, hue 40–100) · dmw-02 neutral
+surfaces pure gray (C < 0.005) or over-tinted (C > 0.015) · dmw-03 untinted black shadow above 0.15 alpha · dmw-04 ease-in entrance
+or duration over its element-class budget · dmw-05 display face granted a data register · dmw-06 dark ladder steps < ~0.04 L or hue
+drift · dmw-07 accent chroma delta between themes > 0.06.
+
+Stdlib-only: vendors its own YAML-subset parser and oklch → sRGB → WCAG-contrast math. The exact contrast pair table, thresholds,
+and emission order live in the script's header comment.