@nurix/etna 0.19.66 → 0.19.67

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

@@ -1,29 +0,0 @@
-# Step 5 — The ship gate
-
-The project ships with its project-local artifacts — `design.md` (the resolved fork, with provenance line, brief bindings, recorded deviations), its derived `design.tokens.css`, and `product.md` — and its memory server-side. 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), at this step only, 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** through `record`, 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, Tier-1 results, every Tier-2 flag with its disposition, and the validator's warn list. No scores, no self-grades. Write it to memory — `record` with `report: { kind: "gate", summary }` — and, if the run's surviving edits changed the project's `design.md`, push the new text in the same `record` so the server canonical stays current.

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

@@ -1,195 +0,0 @@
----
-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/apollo/skills/design/references/ux-patterns/ai-layer.md

@@ -1,49 +0,0 @@
----
-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/apollo/skills/design/references/ux-patterns/attributes-lifecycle.md

@@ -1,43 +0,0 @@
----
-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/apollo/skills/design/references/ux-patterns/container-choice.md

@@ -1,44 +0,0 @@
----
-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"}
-]}
-```

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

@@ -1,46 +0,0 @@
----
-id: creation-paths
-class: b2
-sourced: 2026-07-12
-source: "b2b-ux-patterns ch.9"
-license: open
----
-# Pass: creation paths & data entry
-
-**Inputs:** per object's birth inventory — `manualCreate`, `bulkOnboarding`, `bornFromTransformation`, `bornFromTemplate`, `recurs`, `externalSourceOfTruth`; per create surface — `creationFrequency` (high | low), `fieldCount` (few | many), `interdependentFields`, `bornComplete`, `sequentialDependencies`, `isGridPrimaryWrite`, `requiredRelationMayBeMissing`, `duplicateProneCreate`, `serverTruthValidation`; per edit surface — `editRegime` (inline | explicit-mode | canvas), `concurrentEditors`, `isConfigObject`.
-**Owns:** `creationPaths`, `requiredMechanics`, `clarifications`.
-**Output artifact:** the per-object creation-path catalog — which of form / import / conversion / clone / recurrence / sync a record is born through, each with its container and shape — plus the edit regime, persistence policy, validation contract, and config draft/publish lifecycle.
-
-## The rule
-
-**A hand-typed form is one creation path among equals.** The birth inventory declares which paths an object needs, and each is a first-class surface, not an afterthought. *Import* is bulk creation as a flow — upload, map columns to fields, per-row validation preview, a dedupe/upsert key, then a background job whose completion carries a per-row error report, never a blanket success. *Conversion* is born-from transformation (Lead → Account + Contact + Opportunity): it previews what will be created and how fields map, creates several records atomically, and never routes its output through a create form. *Clone* is born-from-existing — templates, duplicate, save-as-template — carrying contextual defaults forward. *Recurrence* materializes instances on a schedule. *Sync ingestion* lands external records carrying their origin provenance. Only when none of these apply is a record hand-typed.
-
-**Create container follows creation frequency, field count, and source-context retention** — the same workflow-first logic as detail containers. High-frequency objects created mid-task get a **quick-create** that captures only the required fields and returns the user to their flow, and are **created thin then edited fat** — capture the minimum viable record (often just a name), commit immediately, fill the rest in place over time. Low-frequency, high-ceremony objects with many interdependent required fields get a **full-page create**. Objects with referential-integrity requirements at birth (an invoice line needs an amount, a payment needs a currency) are **born complete** through a gated form — never create-thin. In the grid archetype the table is the write surface, so creation is an **inline row**. And whenever a demoted object is a required or common relation of a promoted one, the create/edit form offers **nested create-in-context** ("+ New Account" inside the Lead form) — the load-bearing mechanism that makes promotion/demotion usable; without it, users are forced back to the create-elsewhere flow the demotion was meant to kill.
-
-**Creation shape forks on dependency, not size.** Genuinely sequential, dependent, high-stakes decisions get a **multi-step wizard** with per-step validation gates. Many fields with *no* ordering dependency get a **single long form with sticky section nav** — the anti-wizard, skimmable and non-linear; artificial gating on independent fields is a failure. Accelerate every path with smart defaults and contextual prefill (owner defaults to the current user; a record created from a filtered board inherits the column's status), and add **duplicate detection on create** — fuzzy-match identifying fields and surface "this may already exist" with a link to the existing record — wherever an object has multiple entry points.
-
-**Edit regime and persistence are declared together.** Inline edit-in-place and always-editable canvases require **autosave with a saved indicator**; surfaces with an explicit Save button require a **dirty-state guard** that warns on navigation and never silently discards. Assume multiple people touch every record: a save landing on a record that changed underneath surfaces a **concurrent-edit conflict prompt** (show what changed; offer merge / overwrite / discard) — never a silent clobber. Server-truth checks (uniqueness, quota, referential validity) run as **async validation** inline. Configuration-like objects — automations, templates, dashboards, pipelines — get a **draft/publish lifecycle**: an editable draft that does not take effect while the published version keeps running, an explicit publish, and an unpublished-changes indicator; editing live config in place is the failure mode. When a manual-create surface has no frequency reading, its container cannot be chosen: clarify.
-
-```json decision-table
-{"pass": "creation-paths", "rows": [
-  {"when": {"bulkOnboarding": true}, "then": {"creationPaths": {"mustInclude": ["import"]}, "requiredMechanics": {"mustInclude": ["csv-column-mapping", "per-row-validation-preview", "dedupe-upsert-key", "background-job-partial-failure-report"], "mustNotInclude": ["blanket-success-report"]}}, "reason": "bulk-onboarding-is-import"},
-  {"when": {"bornFromTransformation": true}, "then": {"creationPaths": {"mustInclude": ["conversion"]}, "requiredMechanics": {"mustInclude": ["conversion-preview-mapping", "atomic-multi-record-create"], "mustNotInclude": ["conversion-through-create-form"]}}, "reason": "transformation-is-conversion"},
-  {"when": {"bornFromTemplate": true}, "then": {"creationPaths": {"mustInclude": ["clone"]}, "requiredMechanics": {"mustInclude": ["template-clone-duplicate", "contextual-defaults-retained"]}}, "reason": "born-from-existing-is-clone"},
-  {"when": {"recurs": true}, "then": {"creationPaths": {"mustInclude": ["recurrence"]}, "requiredMechanics": {"mustInclude": ["recurrence-materializes-instances"]}}, "reason": "a-repeating-object-is-a-recurrence-path"},
-  {"when": {"externalSourceOfTruth": true}, "then": {"creationPaths": {"mustInclude": ["sync"]}, "requiredMechanics": {"mustInclude": ["sync-ingestion-provenance"]}}, "reason": "external-system-is-a-sync-path"},
-  {"when": {"manualCreate": true, "creationFrequency": "high"}, "then": {"creationPaths": {"mustInclude": ["form"]}, "requiredMechanics": {"mustInclude": ["quick-create-modal", "create-thin-then-edit-fat"]}}, "reason": "high-frequency-quick-create-thin"},
-  {"when": {"manualCreate": true, "creationFrequency": "low", "interdependentFields": true}, "then": {"creationPaths": {"mustInclude": ["form"]}, "requiredMechanics": {"mustInclude": ["full-page-create"]}}, "reason": "low-frequency-high-ceremony-is-full-page"},
-  {"when": {"bornComplete": true}, "then": {"requiredMechanics": {"mustInclude": ["born-complete-gated-form"], "mustNotInclude": ["create-thin-then-edit-fat"]}}, "reason": "referential-integrity-forces-born-complete"},
-  {"when": {"isGridPrimaryWrite": true}, "then": {"requiredMechanics": {"mustInclude": ["inline-row-create"]}}, "reason": "grid-writes-in-the-row"},
-  {"when": {"requiredRelationMayBeMissing": true}, "then": {"requiredMechanics": {"mustInclude": ["nested-create-in-context"]}}, "reason": "demotion-needs-inline-parent-create"},
-  {"when": {"sequentialDependencies": true}, "then": {"requiredMechanics": {"mustInclude": ["multi-step-wizard"]}}, "reason": "dependent-steps-gate"},
-  {"when": {"sequentialDependencies": false, "fieldCount": "many"}, "then": {"requiredMechanics": {"mustInclude": ["single-long-form-section-nav"], "mustNotInclude": ["multi-step-wizard"]}}, "reason": "no-dependency-no-wizard"},
-  {"when": {"duplicateProneCreate": true}, "then": {"requiredMechanics": {"mustInclude": ["duplicate-detection-on-create"]}}, "reason": "fuzzy-match-before-create"},
-  {"when": {"serverTruthValidation": true}, "then": {"requiredMechanics": {"mustInclude": ["async-validation-pending", "inline-blur-validation", "submit-gate-summary", "server-error-field-mapping"]}}, "reason": "server-truth-runs-async-and-maps-to-fields"},
-  {"when": {"editRegime": ["inline", "canvas"]}, "then": {"requiredMechanics": {"mustInclude": ["autosave-saved-indicator"]}}, "reason": "inline-and-canvas-autosave"},
-  {"when": {"editRegime": "explicit-mode"}, "then": {"requiredMechanics": {"mustInclude": ["explicit-save-dirty-state-guard"], "mustNotInclude": ["silent-discard-on-navigate"]}}, "reason": "deliberate-edits-guard-dirty-state"},
-  {"when": {"concurrentEditors": true}, "then": {"requiredMechanics": {"mustInclude": ["concurrent-edit-conflict-prompt"], "mustNotInclude": ["silent-clobber"]}}, "reason": "assume-multiple-editors"},
-  {"when": {"isConfigObject": true}, "then": {"requiredMechanics": {"mustInclude": ["draft-publish-lifecycle", "unpublished-changes-indicator"], "mustNotInclude": ["edit-live-config-in-place"]}}, "reason": "config-drafts-then-publishes"},
-  {"when": {"manualCreate": true, "creationFrequency": "__absent__"}, "then": {"clarifications": ["creation-frequency-unspecified"]}, "reason": "create-container-needs-a-frequency-reading"}
-]}
-```

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

@@ -1,42 +0,0 @@
----
-id: dashboards
-class: b2
-sourced: 2026-07-12
-source: "b2b-ux-patterns ch.15"
-license: open
----
-# Pass: dashboards
-
-**Inputs:** per canvas — `dashboardJob` (monitoring | narrative | work-router), `multiJobCanvas`, `cachedDecisionData`, `viewerScopedMetrics`, `promotionRole` (manager | operator), `pushDigest`; per tile — `tile`, `monitoringTile`, `thresholdDeclared`, `trendTileRequested`, `sourceHistoryClass` (overwrite | sampled | logged).
-**Owns:** `archetypes`, `requiredStates`, `requiredMechanics`, `clarifications`.
-**Output artifact:** for each surface a product calls a "dashboard," which of the three archetypes it actually is, the five-part contract every tile obeys, and the data properties (Sampled trends, freshness, config-object thresholds) the surface renders.
-
-## The rule
-
-**"Dashboard" is not one archetype — it is three, with different jobs, metrics, and consumers.** *The monitoring glance* answers "is anything on fire?" in under five seconds and lets the user leave; **success = the user leaves quickly**; it renders **judgment, not data** — green/amber/red against declared thresholds, states instead of precise values, anomaly-first ordering, pre-attentive color-plus-icon (never color alone). A wall of raw numbers on a monitoring surface is an abdication. *The narrative report* tells what happened this period and why, usually to someone other than the operator; **success = the reader trusts and can retell the story**; period comparisons and targets-vs-actuals everywhere, trend context on every number, an explicit as-of timestamp and reporting-timezone declaration, and the house-knowledge corrective behind the significance gate. *The work router in dashboard clothes* is really the Home/work router — my tasks, approvals waiting, the ranked next-best-action queue; **success = click-through, not dwell**; it is a queue and is already specified by that archetype — recognize it and never mix it onto a monitoring or narrative canvas.
-
-**The mixing rule: one canvas serves one of the three jobs.** If a page must carry more than one (a home page with a status strip above a worklist), zone them explicitly — separate regions with separate refresh and interaction contracts — rather than interleaving tiles of different species.
-
-**Every number is a door — a number alone is decoration.** The full tile contract, required of every tile: (1) **the number**, formatted per its field type, no precision theater; (2) **a comparison** — vs target, prior period, or cohort — without which the reader cannot tell if the number is good; (3) **a trend** — sparkline or delta, shape not just position; (4) **a state** — good/warn/bad, which requires a declared threshold, so no threshold means no state and no place on a monitoring surface; (5) **a door** — clicking lands on the exact filtered record set or analytics view that *produced* the number. A stat tile is a saved view rendered as an aggregate, and the door is a reconciliation requirement: the count behind the door must equal the number on the tile, or trust in the whole surface dies. Browse-index stat cards obey the same five-part contract, scoped to the index's current filter.
-
-**Dashboards are where three lifecycle declarations become visible.** Trend tiles are the UI output of the **Sampled** history class — a field declared Overwrite has no trend to show, and an empty trend tile is a history-class declaration failure, not a chart bug. **Freshness is mandatory** — every tile group carries "updated N minutes ago" and degraded tiles fail individually, so one dead query never blanks the board. **Targets and thresholds are config objects** — owned, versioned, auditable — not constants buried in tile definitions. The whole surface renders f(data, viewer): a scope switcher (me / my team / org) rather than separate dashboards per rung, tiles gated by role and plan.
-
-**Promotion follows frequency × criticality, not habit** — dashboards go high for managers and low for operators, whose landing surface is the queue or index with the glance strip at most zoned above it; defaulting every sidebar item to a dashboard is the dashboard-first fallacy. The 2026 push inversion turns the monitoring dashboard from the ritually-visited wall into the drill-down destination behind a pushed digest — design the digest → dashboard → door → records chain unbroken, and ship auto-narration only behind the significance gate. A monitoring tile with no declared threshold cannot render a state: clarify. A trend tile over an Overwrite field has no trend to show: clarify.
-
-```json decision-table
-{"pass": "dashboards", "rows": [
-  {"when": {"dashboardJob": "monitoring"}, "then": {"archetypes": {"mustInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["judgment-not-data", "declared-thresholds", "state-color-plus-icon", "anomaly-first-ordering"], "mustNotInclude": ["wall-of-raw-numbers", "color-alone-encoding"]}}, "reason": "monitoring-renders-judgment"},
-  {"when": {"dashboardJob": "narrative"}, "then": {"archetypes": {"mustInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["period-comparison", "targets-vs-actuals", "trend-on-every-number", "as-of-timestamp", "reporting-timezone-declaration"]}}, "reason": "narrative-tells-a-trusted-story"},
-  {"when": {"dashboardJob": "work-router"}, "then": {"archetypes": {"mustInclude": ["queue"], "mustNotInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["viewer-scoped-worklist", "click-through-not-dwell"], "mustNotInclude": ["mixed-onto-monitoring-canvas"]}}, "reason": "work-router-is-a-queue-not-a-dashboard"},
-  {"when": {"tile": true}, "then": {"requiredMechanics": {"mustInclude": ["tile-number-formatted", "tile-comparison", "tile-trend", "tile-state-threshold", "tile-door-reconciled"], "mustNotInclude": ["number-alone", "unreconciled-door"]}}, "reason": "every-number-is-a-door"},
-  {"when": {"multiJobCanvas": true}, "then": {"requiredMechanics": {"mustInclude": ["zone-explicitly-separate-regions"], "mustNotInclude": ["interleave-tile-species"]}}, "reason": "one-canvas-one-job"},
-  {"when": {"cachedDecisionData": true}, "then": {"requiredStates": {"mustInclude": ["stale", "degraded"]}, "requiredMechanics": {"mustInclude": ["freshness-updated-n-min", "degraded-tiles-fail-individually"]}}, "reason": "decisions-get-made-on-cached-numbers"},
-  {"when": {"viewerScopedMetrics": true}, "then": {"requiredMechanics": {"mustInclude": ["scope-switcher-me-team-org", "role-plan-gated-tiles"]}}, "reason": "dashboard-renders-f-data-viewer"},
-  {"when": {"promotionRole": "manager"}, "then": {"requiredMechanics": {"mustInclude": ["dashboard-sidebar-promotion"]}}, "reason": "dashboards-are-high-for-managers"},
-  {"when": {"promotionRole": "operator"}, "then": {"requiredMechanics": {"mustInclude": ["glance-strip-zoned-above-queue"], "mustNotInclude": ["dashboard-first-fallacy"]}}, "reason": "operators-land-on-a-queue-not-a-dashboard"},
-  {"when": {"pushDigest": true}, "then": {"requiredMechanics": {"mustInclude": ["subscribe-to-metric-digest", "digest-to-dashboard-to-door-chain", "auto-narration-behind-significance-gate"]}}, "reason": "push-inversion-precedes-the-visit"},
-  {"when": {"trendTileRequested": true, "sourceHistoryClass": "sampled"}, "then": {"requiredMechanics": {"mustInclude": ["sparkline-from-sampled-class"]}}, "reason": "trend-tiles-render-the-sampled-class"},
-  {"when": {"monitoringTile": true, "thresholdDeclared": false}, "then": {"clarifications": ["threshold-unspecified"]}, "reason": "no-threshold-no-state-no-monitoring-tile"},
-  {"when": {"trendTileRequested": true, "sourceHistoryClass": "overwrite"}, "then": {"clarifications": ["trend-needs-sampled-class"]}, "reason": "overwrite-field-has-no-trend-to-show"}
-]}
-```

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

@@ -1,42 +0,0 @@
----
-id: modes
-class: b2
-sourced: 2026-07-12
-source: "b2b-ux-patterns ch.5"
-license: open
----
-# Pass: user modes
-
-**Inputs:** per role × dataset — `mode` (monitoring | triage | procedural | exception | approval | investigation | exploration | authoring | reconciliation | comparison | batch-mutation | configuration | collaboration | reporting | learning | supervision), `sameDataMultipleModes`.
-**Owns:** `archetypes`, `requiredMechanics`.
-**Output artifact:** the mode inventory per dataset — which directly selects the page archetype (conformed to the pinned seven-archetype roster: browse, queue, grid, record-detail, dashboard, creation-flow, settings) and the feature requirements per surface.
-
-## The rule
-
-A mode is a behaviorally distinct way of using the product; it earns a place only if it demands different UI — different layout, affordances, success metric. **Modes are not persona traits:** the same user on the same data switches modes hour to hour (monitoring at 9:00, triage at 9:15, procedural until lunch, an exception at 2:00, approvals at 4:00). Never map persona → mode and design one surface per persona; inventory which modes each role enters per dataset and let one dataset serve several modes — a leads list must support monitoring (stat glance), triage (route verbs, bulk bar), and batch mutation (grid selection) without becoming three pages.
-
-**Mode selects archetype — not the object.** When a screen feels wrong despite showing the right object, the usual cause is a mode mismatch: an index built for browsing handed to a team that triages, or a settings *page* given to what is actually a configuration *mode* needing preview and rollback. Distinctions the table encodes: investigation has a fixed question (timeline, trail, drill); exploration has none yet (pivot, segment — the question is the output). Triage routes without resolving; procedural resolves and takes the next. Approval judges someone else's finished output; supervision (the fastest-growing mode of 2025–26) steers an autonomous worker mid-flight — pause, redirect, resume — and is neither monitoring (no intervention), approval (finished artifact), nor exception handling (single-user improvisation after the playbook fails). Exception handling is exactly where UX quality matters most, because the designed flows have run out.
-
-Richer surface forms noted in `page-archetype` (conversational inbox, split-pane console, canvas builder, report builder, wizard, log explorer, merge/diff views) are realizations of these roster mappings, not extra archetypes.
-
-```json decision-table
-{"pass": "modes", "rows": [
-  {"when": {"mode": "monitoring"}, "then": {"archetypes": {"mustInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["glanceable-status", "declared-thresholds-config"]}}, "reason": "nothing-on-fire-glance"},
-  {"when": {"mode": "triage"}, "then": {"archetypes": {"mustInclude": ["queue"], "mustNotInclude": ["browse"]}, "requiredMechanics": {"mustInclude": ["route-verbs-on-rows", "bulk-triage-bar", "keyboard-velocity", "unread-new-markers"]}}, "reason": "route-not-resolve"},
-  {"when": {"mode": "procedural"}, "then": {"archetypes": {"mustInclude": ["queue", "record-detail"]}, "requiredMechanics": {"mustInclude": ["take-next-auto-advance", "transition-required-fields"]}}, "reason": "assembly-line-to-done"},
-  {"when": {"mode": "exception"}, "then": {"archetypes": {"mustInclude": ["record-detail"]}, "requiredMechanics": {"mustInclude": ["reason-capture-required", "logged-history-class", "escalation-path"]}}, "reason": "break-glass-audited"},
-  {"when": {"mode": "approval"}, "then": {"archetypes": {"mustInclude": ["queue", "record-detail"]}, "requiredMechanics": {"mustInclude": ["judgment-diff-summary", "approve-reject-rationale"]}}, "reason": "verdict-is-the-work-product"},
-  {"when": {"mode": "investigation"}, "then": {"archetypes": {"mustInclude": ["record-detail", "browse"]}, "requiredMechanics": {"mustInclude": ["event-timeline", "drill-through", "cheap-back-navigation"]}}, "reason": "fixed-question-trail"},
-  {"when": {"mode": "exploration"}, "then": {"archetypes": {"mustInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["pivot-group-segment", "save-analysis"]}}, "reason": "question-is-the-output"},
-  {"when": {"mode": "authoring"}, "then": {"archetypes": {"mustInclude": ["creation-flow"]}, "requiredMechanics": {"mustInclude": ["full-screen-focus", "autosave-indicator", "draft-persistence"]}}, "reason": "chrome-recedes"},
-  {"when": {"mode": "reconciliation"}, "then": {"archetypes": {"mustInclude": ["record-detail"]}, "requiredMechanics": {"mustInclude": ["side-by-side-diff", "per-delta-resolve", "field-by-field-picker"]}}, "reason": "difference-oriented"},
-  {"when": {"mode": "comparison"}, "then": {"requiredMechanics": {"mustInclude": ["parallel-columns", "period-over-period"]}}, "reason": "choose-a-winner"},
-  {"when": {"mode": "batch-mutation"}, "then": {"archetypes": {"mustInclude": ["grid"]}, "requiredMechanics": {"mustInclude": ["multi-select", "bulk-action-bar", "bulk-preview-before-commit", "per-row-partial-failure-report"]}}, "reason": "blast-radius-defines-the-mode"},
-  {"when": {"mode": "configuration"}, "then": {"archetypes": {"mustInclude": ["settings"]}, "requiredMechanics": {"mustInclude": ["draft-publish-lifecycle", "impact-preview", "blast-radius-header"]}}, "reason": "rare-consequential-preview-hungry"},
-  {"when": {"mode": "collaboration"}, "then": {"archetypes": {"mustInclude": ["record-detail"]}, "requiredMechanics": {"mustInclude": ["activity-composer", "mentions-assignment", "unread-new-markers"]}}, "reason": "conversation-attached-to-data"},
-  {"when": {"mode": "reporting"}, "then": {"archetypes": {"mustInclude": ["dashboard"]}, "requiredMechanics": {"mustInclude": ["view-aware-export", "scheduled-delivery", "as-of-timestamp"]}}, "reason": "goal-lives-outside-the-product"},
-  {"when": {"mode": "learning"}, "then": {"requiredMechanics": {"mustInclude": ["empty-state-teaching", "sample-data-path", "setup-checklist"]}}, "reason": "scaffolding-experts-never-see"},
-  {"when": {"mode": "supervision"}, "then": {"archetypes": {"mustInclude": ["queue", "record-detail"]}, "requiredMechanics": {"mustInclude": ["run-timeline-pause-redirect-resume", "live-plan-visibility", "escalation-to-approval"]}}, "reason": "steering-not-disposal"},
-  {"when": {"sameDataMultipleModes": true}, "then": {"requiredMechanics": {"mustInclude": ["multi-mode-single-surface"], "mustNotInclude": ["one-page-per-persona"]}}, "reason": "modes-switch-hourly"}
-]}
-```