@orkestrel/scaffold 0.0.33 → 0.0.36

package/dist/host/agents/orchestration.md

@@ -139,7 +139,7 @@ when the role file already pins it.
 | Creative design and alternatives         | `planner`                       | `planner`                     | Opus 5 (native / bridge)      |
 | Design-fit review and audit              | `reviewer`                      | `reviewer`                    | Opus 5 (native / bridge)      |
 | Objective analysis and correctness audit | `analyst`                       | `analyst`                     | GPT-5.6 Sol (bridge / native) |
-| Nontrivial implementation (objective)    | `codex` route `implementer`     | `implementer`                 | GPT-5.6 Sol (bridge / native) |
+| Nontrivial implementation (objective)    | `sol`                           | `implementer`                 | GPT-5.6 Sol (bridge / native) |
 | Nontrivial implementation (subjective)   | `implementer`                   | `implementer` route `opus`    | Opus 5 (native / bridge)      |
 | Bounded primary-source research          | `researcher`                    | `researcher`                  | Grok → Luna → Sonnet          |
 | Repository reconnaissance                | `scout`                         | `scout`                       | Grok → Luna → Sonnet          |
@@ -160,9 +160,8 @@ when the role file already pins it.
   has stepped past Grok. Record which step you are on.
 - `orkestrel` stays native because it carries the package catalog in its own role file. Sending its
   job to a bench means shipping that catalog across, which costs more than the bench saves.
-- One gap is open and recorded rather than improvised: the Sol implementer is still `codex` route
-  `implementer` while its Codex mirror has a named `opus` bridge. Closing it means deciding where
-  the shared Sol transport contract lives once two bridges follow it.
+- `codex` is the shared Sol transport contract, not a route. `analyst` and `sol` are the named
+  bridges; both bind that contract by reference and pin only their route and sandbox.
 - Opus and Sol roles use high effort. Native cheap-tier roles use low or medium. Bridge drivers use
   the cheapest tier that can run a CLI.
 - Never route orchestration or acceptance across a bridge.
@@ -202,6 +201,10 @@ Every role honours this floor. No dispatch may widen it.
   same class of defect through a new door, the search is following the frame rather than the
   defect. Bound the scope, then fan out independent lenses over disjoint slices in one pass.
   Parallelism is worth more here for the framing it breaks than for the wall-clock it saves.
+- Two lanes is the adversarial pass's FLOOR, not its shape. Where a subject has more seams than
+  two lanes can attack, fan out one lens per seam over disjoint slices, keep every lens blind and
+  clean-contexted, and number every slice's claims in one shared sequence. Change the lenses in a
+  successor round rather than repeating them.
 - Decompose by required context and independently verifiable acceptance criteria, not by task type.
 - Send instructions down fully specified. Return findings smaller than the context consumed.
 - Parallelize independent work. Serialize dependencies and shared-file contention.
@@ -366,10 +369,11 @@ The harness bridge names the concrete mechanism for each of these.
 - Send a decision taken mid-campaign to every unit already in flight whose brief it invalidates. An
   executor cannot see a change made after it was dispatched, so it writes the state its brief
   described and the defect surfaces as its own.
-- Treat brief and report files as unit evidence, not deliverables. Never commit them, and sweep
-  them when the campaign that produced them is accepted.
+- Treat the `tmp/` brief and report pair as ephemeral launch copies. **Bench laws** rule 4 owns
+  what is kept and what is swept; follow it there rather than deciding here.
 - Promote anything that must outlive the campaign into a durable artifact before the sweep — a
-  commit message, a guide, a rule, a retrospective. What is only in a swept file did not survive.
+  commit message, a guide, a rule, a retrospective. What is only in a swept file did not survive,
+  and a debrief that must quote the record verbatim has nothing to quote.
 
 ### Where campaign artifacts live
 
@@ -491,11 +495,17 @@ command that outlives the turn that started it. Every law here binds all of them
 - Write a multi-step chain to a script file and run the file. A chain composed inside one shell
   argument cannot be read back, corrected, or re-run, and the record of what actually ran is the
   argument text in a transcript rather than a file on disk.
+- On a Windows host this binds every program-carrying command, not only long ones. Heredocs,
+  `node -e`, `node -p`, `&&` chaining, and any argument carrying `${...}` trip the Git Bash
+  approval classifier and turn an unattended run into a manual approval prompt. Write the program
+  to a file, invoke the file, and keep each shell call one plain command.
 - Detach anything that must survive its launching shell with `setsid`. A backgrounded flow the
   harness reaps mid-step leaves the work half done and the exit status missing, and the reap looks
   identical to the step failing.
-- Size the cap from the observed high mark of comparable commands, plus an independently budgeted
-  gate allowance, plus explicit slack. Never size it from the estimate alone.
+- Size the cap yourself, from the observed high mark of comparable commands, plus an
+  independently budgeted gate allowance, plus explicit slack. Never size it from the estimate
+  alone. Never delegate it: a bridge starts with a clean context, holds no record of prior runs,
+  and can only guess. A cap-killed exec is indistinguishable from a real failure.
 - Run the first use of any CLI flag, subcommand, quoting form, or stdin combination in a throwaway
   probe. Never inside a dispatched unit or a publish chain.
 - A launch is not a launch until its record grows past its header. Confirm the log advanced beyond
@@ -575,9 +585,11 @@ transport.
 4. **Ephemeral streams, durable records.** A journal proves a bench is alive and recovers an
    interrupted session. Keep journals under `tmp/`, never commit them, and sweep them at acceptance
    after the final gate evidence is recorded. The **brief**, the returned **distillate**, the
-   **audit verdict**, and the **acceptance evidence** are not streams. Commit each one as its unit
-   is dispatched and as it returns, because each encodes knowledge that costs real money to
-   re-derive and none of it is reproducible from the diff.
+   **audit verdict**, and the **acceptance evidence** are not streams. Copy each into
+   `.orkestrel/<package>/` and commit it as its unit is dispatched and as it returns, then sweep
+   only the `tmp/` copy. None of it is reproducible from the diff, and a debrief has no primary
+   source without it. This rule owns retention for the whole contract; **Dispatch anatomy**
+   points here rather than answering it.
 
 ### Recovering a dark bench
 
@@ -641,6 +653,10 @@ and propagates as files rather than as a cascade.
   prove that target's gates still green. `repair` restores `tests/setupPolicy.ts` and
   `tests/policy.test.ts`, so a vendored-only release can turn a green target red. A target bumps
   only when its own published surface moved.
+- Keep a target's own Claude permissions in `.claude/settings.local.json`, never in the vendored
+  `.claude/settings.json`. `repair` restores the vendored copy, so a `defaultMode` or an `allow`
+  entry added there is reverted without warning and the operator loses grants they set
+  deliberately. Change the vendored file only here, in the host inventory.
 - Never edit a vendored file inside a target. `repair` restores it, so the edit is reverted and
   reports as drift in `scaffold audit`. In this repository those same files are the published
   `dist/host` surface, so editing one forces a bump, a publish, and a re-propagation across every

package/dist/host/agents/skills/enterprise-bootstrap/SKILL.md

@@ -14,101 +14,99 @@ description: >-
 
 # Enterprise Bootstrap
 
-General-purpose guide for **intentional visual design** executed with **Bootstrap 5.3**: distinctive where it matters, disciplined everywhere else, utilities-first, accessible, and responsive.
+Set a deliberate visual direction, build it from Bootstrap 5.3 components and utilities, and settle
+every claim about the result from what renders.
 
-This package is layered on purpose:
+Open the reference that owns a subject before writing markup. Never guess a class name: an invented
+utility (`.vw-50`, `.pointer-events-none`) has no rule in the shipped CSS and fails silently. Pick
+components from [components.md](references/components.md) → Choosing components, take their markup
+from the same file, and take fine layout from [utilities.md](references/utilities.md). Where
+Bootstrap ships no component for the need — combobox, date picker, tags input, data grid, tree —
+work the native-first ladder in [bootstrap-reference.md](references/bootstrap-reference.md) → When
+not to hand-roll before building one.
 
 | Layer          | File                                                        | Holds                                                                             |
 | -------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Operate        | `SKILL.md` (this file)                                      | Process, decision rules, checklists, portability                                  |
-| Design craft   | [frontend-design.md](references/frontend-design.md)         | Full aesthetic, typography, signature, copy, anti-defaults                        |
+| Operate        | `SKILL.md` (this file)                                      | Process, decision rules, checklist                                                |
+| Design craft   | [frontend-design.md](references/frontend-design.md)         | Aesthetic, typography, signature, interface copy, anti-defaults                   |
 | Components     | [components.md](references/components.md)                   | Bootstrap component markup + enterprise selection notes                           |
 | Utilities      | [utilities.md](references/utilities.md)                     | Class index, helpers, composition notes                                           |
 | Bootstrap deep | [bootstrap-reference.md](references/bootstrap-reference.md) | Color modes, theming/tokens, forms, JS lifecycle, a11y depth, enterprise patterns |
 
-Open the relevant reference instead of guessing class names or watering down the craft — the class indexes exist because invented utilities (`.vw-50`, `.pointer-events-none`) ship silent no-ops.
-
 ---
 
-## Portability (any project / tool / environment)
-
-Product-agnostic. Apply the same way wherever this package is loaded.
+## Portability
 
-1. **No repo assumptions.** Do not assume Vue, React, a skin library, a folder layout, or a named product. Infer stack from the workspace.
-2. **Bootstrap contract.** Target Bootstrap **5.3.x** class names and behaviors. Compatible skins that keep `.btn`, `.card`, `.form-control`, `data-bs-*`, etc. are fine — obey the same contracts.
-3. **Project rules win on code law.** If the repo defines conventions (`AGENTS.md`, lint rules, a design system), follow those for languages, layout, and forbidden patterns. This package owns **UI craft + Bootstrap usage**, not language law.
-4. **Framework-neutral markup.** Prefer semantic HTML + Bootstrap classes. Wire behavior with whatever the project already uses; in SPAs prefer the framework-native Bootstrap wrappers over raw `bootstrap.*` JS (see [bootstrap-reference.md](references/bootstrap-reference.md) → JavaScript lifecycle).
-5. **Distribution.** Keep this folder intact so relative links between files resolve. Install or vendor it wherever your tooling looks for skills/guides — paths are tooling-specific; the content is not.
-6. **CDN or bundler.** Either is fine — see [bootstrap-reference.md](references/bootstrap-reference.md) Quick Start (5.3.8) for CDN; prefer the project's existing Bootstrap package when present.
-7. **When to apply.** Use on UI, Bootstrap, or visual-design work matching the description above. When the user attaches or points at this package, treat it as authoritative for the visual pass.
+1. **Assume no stack.** Infer it from the workspace. Do not assume Vue, React, a skin library, a folder layout, or a named product.
+2. **Target Bootstrap 5.3.x** class names and behaviors. Hold a compatible skin that keeps `.btn`, `.card`, `.form-control`, and `data-bs-*` to the same contracts.
+3. **Follow the project's code law.** Its `AGENTS.md`, lint rules, and design system decide language, layout, and forbidden patterns. This package owns UI craft and Bootstrap usage, not language law.
+4. **Write framework-neutral markup** — semantic HTML plus Bootstrap classes. Wire behavior with what the project already uses; in an SPA prefer the framework-native Bootstrap wrappers over raw `bootstrap.*` JS ([bootstrap-reference.md](references/bootstrap-reference.md) → JavaScript lifecycle).
+5. **Keep this folder intact** so the relative links between its files resolve. Install or vendor it wherever the tooling looks for skills; the paths are tooling-specific, the content is not.
+6. **Use the project's installed Bootstrap** when it has one; otherwise take the CDN snippet from [bootstrap-reference.md](references/bootstrap-reference.md) → Quick start (5.3.8).
+7. **Apply this package** to UI, Bootstrap, and visual-design work matching the description above. When the user points at it, treat it as authoritative for the visual pass.
 
 ---
 
 ## Dual mandate
 
-1. **Design lead** — point of view rooted in the _subject_ (audience, job-to-be-done, vernacular). One justified aesthetic risk; boldness in one place. Full text: [frontend-design.md](references/frontend-design.md).
-2. **Bootstrap engineer** — components + utilities first; custom CSS only when the system cannot express the need; paint via `--bs-*` so light/dark survive.
+1. **Design direction** — take a point of view rooted in the _subject_ (audience, job-to-be-done, vernacular). Take one justified aesthetic risk, in one place.
+2. **Bootstrap execution** — components and utilities first; custom CSS only when the system cannot express the need; paint through `--bs-*` so light and dark both survive.
 
-**Context match:** a marketing page may open with a thesis-hero; an authenticated tool opens with clarity and scan paths. Same craft, different density — in product UI the signature lives in the chrome, never in the data ([frontend-design.md](references/frontend-design.md) → Where the signature lives).
+Match the density to the context: a marketing page may open with a thesis-hero, an authenticated
+tool opens with clarity and scan paths. In product UI put the signature in the chrome, never in the
+data ([frontend-design.md](references/frontend-design.md) → Where the signature lives).
 
 ---
 
 ## Process
 
-Detail and wording live in [frontend-design.md](references/frontend-design.md). Condensed loop:
-
-1. **Ground** — subject, audience, screen's single job (state it). Use known user preferences and prior designs as hints, not templates.
-2. **Plan** — token system: **color** (4–6 named values), **type** (display / body / utility), **layout** (prose + ASCII if useful), **signature** (one memorable element).
-3. **Critique the plan** — if swapping the logo would make it "any SaaS," revise. Avoid clustered AI defaults unless the brief asks: cream+#F4F1EA+serif+terracotta; near-black+acid green/vermilion; broadsheet hairlines / zero radius / dense columns. Brief wins when it pins a direction.
-4. **Build** — Bootstrap from components/utilities; map plan tokens onto theme variables or a thin skin — no scattered one-off hex (token discipline: [bootstrap-reference.md](references/bootstrap-reference.md) → Theming & design tokens). Watch selector specificity (utility vs custom canceling).
-5. **Critique again** — remove one accessory (Chanel). Contrast, focus, `prefers-reduced-motion`, mobile, all five states present. Critique the render, not the markup.
+Design craft — subject grounding, hero and thesis, typography, structure, motion, restraint, and
+interface copy — lives in [frontend-design.md](references/frontend-design.md). Read it before
+setting a direction. The loop:
 
-Brainstorm privately; show higher-confidence directions.
+1. **Ground** — name the subject, the audience, and the screen's single job, and state them. Use known user preferences and prior designs as hints, not templates.
+2. **Plan** — build a token system: **color** (4–6 named values), **type** (display / body / utility), **layout** (prose plus ASCII if useful), **signature** (one memorable element).
+3. **Critique the plan** — if swapping the logo would make it "any SaaS", revise. Avoid the clustered AI defaults unless the brief asks for them: cream + #F4F1EA + serif + terracotta; near-black + acid green or vermilion; broadsheet hairlines, zero radius, dense columns. The brief wins when it pins a direction.
+4. **Build** — compose Bootstrap components and utilities; map the plan's tokens onto theme variables or a thin skin, with no scattered one-off hex ([bootstrap-reference.md](references/bootstrap-reference.md) → Theming & design tokens). Watch selector specificity: a utility and a custom rule that cancel each other show up as padding and margin bugs.
+5. **Critique the render** — remove one accessory. Check contrast, focus, `prefers-reduced-motion`, mobile, and all five states. Critique what rendered, not the markup.
 
-**Rendered proof.** A claim about a screen is settled by what the browser paints, never by the markup that was supposed to paint it — source-reading review passes a component that renders nothing. The review input is captures at both viewports and both themes plus an accessibility snapshot; source only corroborates the mechanism. For the full review-round campaign built on that evidence, use the `orkestrel-polish-surface` skill instead of improvising one here.
-
----
+Brainstorm privately; show a direction only once it satisfies the brief and the quality floor
+([frontend-design.md](references/frontend-design.md) → Process).
 
-## Design principles
+**Rendered proof.** Settle every claim about a screen from a capture, never from source alone;
+`.agents/orchestration.md` owns this law where it is present. The review input here is captures at
+both viewports and both themes plus an accessibility snapshot; source only corroborates the
+mechanism. For a full review-round campaign built on that evidence, use the
+`orkestrel-polish-surface` skill instead of improvising one here.
 
-- **Subject first** — distinctive choices from the product's world, not a generic kit.
-- **Hero / thesis when it fits** — open with the most characteristic thing. Big-number+gradient-stat blocks are the template answer — use only if truly best.
-- **Signature + restraint** — one memorable element; quiet discipline around it.
-- **Structure is information** — eyebrows, `01/02/03`, dividers only when order/taxonomy is real.
-- **Typography carries personality** — deliberate pairing and scale; characterful display, restrained.
-- **Motion with purpose** — Bootstrap transitions first; one orchestrated moment if earned; less motion often beats "AI sparkle."
-- **Match complexity to vision** — maximalist = elaborate execution; minimal = precision.
-- **Copy is design** — see Writing below and frontend-design.
+**Mechanical proof.** Three instruments settle what a capture cannot. Pair each one with a negative
+control drawn from outside the population it covers, and treat an instrument whose control passes as
+broken; `.claude/rules/quality.md` owns this law where it is present:
 
-### Writing (interface copy)
-
-- Name what the user controls, not internals ("Notifications," not "Webhook config").
-- Active voice; controls say what happens ("Save changes," not "Submit").
-- Same verb across button → toast → confirm ("Publish" / "Published").
-- Errors: what failed + how to fix; no vague apologies.
-- Empty states: invite the next action.
-- Plain verbs, sentence case, no filler; one job per element (label vs example).
-- Where the surrounding context already names the object, the visible label is one word and the full phrase rides in `aria-label` — the button reads "Stop", the accessible name says what it stops.
-- One glyph means one thing across the whole surface: a check that means "finished" here must not mean "selected" there.
+- **Contrast, composited.** Read every pairing through a reader that composites the painted layers, in both themes ([bootstrap-reference.md](references/bootstrap-reference.md) → Measuring the bars).
+- **Authored classes against the shipped cascade.** Extract every class authored in the templates and components, and fail the run on one that has no rule in the compiled CSS the page loads. Assert a population floor so an extractor that quietly matched nothing cannot pass, and control it with a class you know is absent.
+- **One glyph, one meaning.** Register each status glyph against the meaning it carries. No meaning takes two glyphs, no glyph serves two meanings, and every registered glyph resolves in the icon set actually shipped.
 
 ---
 
 ## Bootstrap operating principles
 
-1. **Mobile first** — smallest screen first, then `sm` / `md` / `lg` / `xl` / `xxl`
-2. **Semantic HTML** — `nav`, `main`, `section`, heading order
-3. **Work down the styling ladder below** — component classes, then utilities, then Bootstrap's own extension points
-4. **Test responsiveness** — every breakpoint you claim
-5. **Verify against the shipped cascade** — resolve every treatment in the CSS actually loaded (Bootstrap plus every skin and dependency stylesheet the page pulls in), never against docs memory. A class with no rule of its own may still inherit one, and a token pair that passes in stock Bootstrap can fail under a compatible skin. Measure, don't assume — including the `*-subtle` / `*-emphasis` recipes, once per theme.
+1. **Mobile first** — smallest screen first, then `sm` / `md` / `lg` / `xl` / `xxl`.
+2. **Semantic HTML** — `nav`, `main`, `section`, heading order.
+3. **Work down the styling ladder below** — component classes, then utilities, then Bootstrap's own extension points.
+4. **Test every breakpoint you claim.**
+5. **Reach for Bootstrap's own transitions before writing custom animation**, spend one orchestrated moment at most, and wrap any custom animation in `prefers-reduced-motion: no-preference` ([bootstrap-reference.md](references/bootstrap-reference.md) → Reduced motion).
+6. **Resolve every treatment in the shipped cascade** — Bootstrap plus every skin and dependency stylesheet the page pulls in — never from docs memory. A class with no rule of its own may still inherit one, and a token pair that passes in stock Bootstrap can fail under a compatible skin. Measure the `*-subtle` / `*-emphasis` recipes too, once per theme, with a reader that composites the translucent layers ([bootstrap-reference.md](references/bootstrap-reference.md) → Measuring the bars).
 
 ### The styling ladder
 
-Work down these rungs in order. Reach a lower rung only when the one above genuinely cannot express the need.
+Work down these rungs in order. Reach a lower rung only when the one above genuinely cannot express
+the need.
 
-1. **The component's own classes, in its documented structure.** Build the element the way Bootstrap defines it: the right elements, the right nesting, the right class names, the required ARIA. A card is `.card` wrapping `.card-body` wrapping `.card-title` — not a `div` with borrowed padding. The best result is an element styled entirely by correct component classes, because variants, states, colour modes, and responsive behaviour all hang off that structure.
-2. **Bootstrap utilities, for refinement.** Spacing, flex, display, sizing, text, borders, colour. This is where the creative range is — compose utilities rather than reaching past them. Use only classes that exist in [utilities.md](references/utilities.md); an invented one ships a silent no-op.
+1. **The component's own classes, in its documented structure.** Use the right elements, nesting, class names, and required ARIA: a card is `.card` wrapping `.card-body` wrapping `.card-title`, not a `div` with borrowed padding. Variants, states, color modes, and responsive behavior all hang off that structure.
+2. **Bootstrap utilities, for refinement.** Spacing, flex, display, sizing, text, borders, color. Compose utilities rather than reaching past them, and use only classes that exist in [utilities.md](references/utilities.md).
 3. **Bootstrap's own extension points.** Component `--bs-{component}-*` variables and the utilities API, when a real gap remains after rungs 1 and 2.
-4. **Anything beyond Bootstrap's conventions is the developer's call, not yours.** Stop at rung 3, and say plainly what rung 4 would require. Leaving that decision with the developer keeps the surface conventional, reviewable, and themeable.
+4. **Anything beyond Bootstrap's conventions is the developer's call, not yours.** Stop at rung 3 and say plainly what rung 4 would require.
 
 Never open at rung 4. Specifically, do not reach first for:
 
@@ -116,138 +114,100 @@ Never open at rung 4. Specifically, do not reach first for:
 - a `<style>` block in a page or component;
 - a new stylesheet rule for something a utility already does.
 
-Each of those ends the cascade for that element: it outranks the utilities, it ignores `--bs-*` retheming, and it does not change across breakpoints or colour modes. Fighting utilities with high-specificity custom rules is the usual source of padding and margin cancel bugs.
+Each ends the cascade for that element: it outranks the utilities, it ignores `--bs-*` retheming, and
+it does not change across breakpoints or color modes.
 
 ### Hierarchy & actions
 
-| Intent      | Typical choice                                           |
-| ----------- | -------------------------------------------------------- |
-| Primary     | `btn btn-primary` — **one** clear primary per region     |
-| Secondary   | `btn-outline-*` matching the surface                     |
-| Destructive | `btn-danger` + the confirmation ladder below             |
-| Tertiary    | `btn-link` or text links                                 |
-| Status      | `badge` / `alert` / `*-emphasis` — **never color alone** |
-
-A status mark with **no text** is an icon glyph, never a `badge`: stock Bootstrap ships `.badge:empty { display: none }`, so an empty badge used as a dot never renders at all ([components.md](references/components.md) → Badge).
+| Intent      | Typical choice                                                      |
+| ----------- | ------------------------------------------------------------------- |
+| Primary     | `btn btn-primary` — **one** clear primary per region                |
+| Secondary   | `btn-secondary` — solid, so the surface underneath cannot change it |
+| Destructive | `btn-danger` + the confirmation ladder                              |
+| Tertiary    | `btn-link` or text links                                            |
+| Status      | `badge` / `alert` / `*-emphasis` — **icon + color + word**          |
+
+**Outline buttons are the decorative tier.** They paint no background of their own, so they borrow
+whatever surface they sit on and their contrast is surface- and theme-dependent by construction:
+against stock Bootstrap the whole `btn-outline-*` family misses 4.5:1 across the dark theme and on
+light tinted surfaces — cards, subtle alerts. Give any action that carries information or
+consequence the solid variant. Solid variants paint their own background and measure identically on
+every surface, and the stock fills sit at the 4.5:1 bar with nothing to spare. Re-measure a solid
+variant whenever anything layers over it — an `opacity-*` utility, a translucent overlay, a skin's
+own tint.
+
+A status mark with **no text** is an icon glyph, never a `badge`
+([components.md](references/components.md) → Badge).
 
 ### Surfaces, color, contrast
 
-- **Contrast bars, measured in both themes:** **≥ 4.5:1** for anything information-bearing — `small`, captions, and meta text included — and **≥ 3:1** for textless marks, state indicators, and the hover/focus chrome that carries state. Verify even Bootstrap's own palette; the docs admit some defaults fall short.
-- `text-body-tertiary` fails the AA bar for information-bearing small text — tier such text `text-body-secondary` or better, and keep tertiary for genuinely decorative marks.
+- **Contrast bars, measured in both themes:** **≥ 4.5:1** for anything information-bearing — `small`, captions, and meta text included — and **≥ 3:1** for textless marks, state indicators, and the hover/focus chrome that carries state. Verify Bootstrap's own palette too; the docs admit some defaults fall short. Read both themes — a pairing that passes light routinely fails dark.
+- **Information-bearing status text takes the `-emphasis` pair.** Plain `text-success` and `text-danger` miss the bar across the dark theme and on light tinted surfaces, and `text-warning` is theme-asymmetric — unreadable on light, comfortable on dark. Never make a plain semantic color the encoding; use it only as decoration beside an encoding that already passes.
+- `text-body-tertiary` carries no information anywhere: it measures under 4.5:1 on every surface in both themes. Tier text a user must read `text-body-secondary` or better, and keep tertiary for genuinely decorative marks.
+- **A subtle fill degrades everything inside it one notch.** Inside `alert-*` and the `*-subtle` backgrounds, outline buttons and plain semantic text fail even in light — so information-bearing text there is `-emphasis` and every button is solid.
+- **A primary fill destroys every semantic color.** On `.active`, `.bg-primary`, and `text-bg-*` surfaces every tone class measured lands under the bar in both themes, the `-emphasis` family included, because the fill supplies its own contrast color and the tone class overrides it with one tuned for a different background. Carry no tone class inside such a fill; let the surface's contrast color take the text, keep the status encoded by icon and word, and verify by capturing the selected state ([components.md](references/components.md) → Selection fills).
 - Disabled controls are exempt from the bars, but a disabled **destructive** control must not keep full danger saturation — at full strength it still reads as armed. Neutralize the variant while it is disabled and carry the reason on the control with `aria-describedby` (plus `title` for pointer users), never `title` alone.
-- Prefer `bg-body`, `bg-body-secondary`, `bg-body-tertiary` over raw `bg-white`/`bg-light` — they track `data-bs-theme`.
-- Pairings: `text-bg-*`, `*-subtle`, `*-emphasis`, `text-body` / `text-body-secondary`. (`text-muted` is deprecated — use `text-body-secondary`.)
-- On **dark surfaces**, scope `data-bs-theme="dark"` rather than reaching for the deprecated `*-dark` component variants; gray-on-dark outlines often fail contrast.
-- Support `data-bs-theme="light"` and `dark` when the product offers both — drive custom paint from `var(--bs-…)`. Mechanics: [bootstrap-reference.md](references/bootstrap-reference.md) → Color modes.
+- Prefer `bg-body`, `bg-body-secondary`, `bg-body-tertiary` over raw `bg-white` / `bg-light`, and drive custom paint from `var(--bs-…)` — they track `data-bs-theme`, a hard-coded hex does not.
+- Pairings: `text-bg-*`, `*-subtle`, `*-emphasis`, `text-body` / `text-body-secondary`. `text-muted` is deprecated — use `text-body-secondary`.
+- On **dark surfaces**, scope `data-bs-theme="dark"` rather than the deprecated component variants `navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, and `carousel-dark`; gray-on-dark outlines often fail contrast.
+- Support `data-bs-theme="light"` and `dark` when the product offers both. Mechanics: [bootstrap-reference.md](references/bootstrap-reference.md) → Color modes.
 
 ### Density, layout, responsive
 
-- Enterprise density: `table-sm`, `btn-sm` / `btn-group-sm`, compact toolbars — but keep every interactive target **≥ 24×24px** (WCAG 2.2); pad hit areas rather than shrinking them.
-- Offer density (comfortable/compact) as a user toggle driven by one token, not ad-hoc `-sm` sprinkling.
-- Cards earn their keep: `.card` when grouping helps; otherwise spacing + type.
-- Prefer `gap-*` on parents over margin spam on every child.
-- Wide data: ranked responsive strategies (priority columns → horizontal scroll → card-ify) in [bootstrap-reference.md](references/bootstrap-reference.md) → Dense data tables.
-- Toolbars: `btn-toolbar` + `overflow-auto` — don't crush icons below target size.
-- Below `sm`, collapse captioned buttons to their icons (accessible names retained) **before** the brand or page title starts truncating — identity survives, chrome shrinks.
-- App frame: sidebar via responsive `offcanvas-{bp}` (inline desktop, drawer mobile) — full pattern in [bootstrap-reference.md](references/bootstrap-reference.md) → App shell.
-- Print: chrome `d-print-none`; keep the data printable.
-
-### States & feedback (decision rules)
-
-- **Every data surface ships five states:** ideal, empty, loading, partial, error. Not done until all five exist.
-- **Loading:** skeleton (`placeholder`) when the layout is known — it holds the frame; spinner for short or in-control waits (inside the button). Under ~1s show nothing; past ~10s show determinate progress.
-- **Empty:** no-data-yet invites the first action; no-results-for-filters offers "Clear filters." Never one generic "nothing here."
-- **Errors:** what failed + how to fix + a keyboard-reachable retry, in place — never a toast, never a wiped layout.
-- **Channel rule:** toast = transient success; inline alert = contextual; banner = persistent page-level condition; modal = blocking decision. Full matrix: [bootstrap-reference.md](references/bootstrap-reference.md) → Feedback discipline.
-- **Destructive ladder:** undo > confirm dialog (verb-labeled buttons, consequence restated) > type-to-confirm (only high blast radius). Prefer undoable over interrupting.
-
-### Views & navigation
-
-- In-page view switching → real **tabs** (`nav-tabs` / `nav-pills` / `nav-underline` + tab panes / equivalent state), not scroll-only hash links dressed as tabs.
-- Active items: `aria-current="page"` or `aria-selected`. Exactly **one** `aria-current` per selection — per nav, per list, per table; two is no selection at all.
-- A mark laid on a selected/active fill must survive it: a `text-bg-*`-family mark on a `.active` fill of the same color is overridden and vanishes, while `text-body-emphasis` keeps reading. Same trap for `btn-check` filter labels ([components.md](references/components.md) → Selection fills).
-- Icon-only controls: `aria-label` (and `title` when helpful).
-- Breadcrumbs only for real hierarchy; command palette only on top of visible nav.
-
-### Forms (decision rules)
-
-- Visible labels (top-aligned by default) or `.form-floating` — never placeholder-only.
-- Validate on **blur**, re-validate error fields on input, everything on submit; keep submit **enabled**.
-- Long forms pair a focusable error summary with inline `.invalid-feedback` per field (`aria-describedby`, `aria-invalid`).
-- Bootstrap's client-side validation styles aren't exposed to assistive tech — accessible flows use the server-side classes or native validation. Mechanics + canonical JS: [bootstrap-reference.md](references/bootstrap-reference.md) → Forms in production.
-- Units/money: `.input-group` + `.input-group-text` (+ `.has-validation` when feedback present).
-- Multi-step: per-step validation, back without loss, never re-ask collected data.
-
-### Component cheat sheet
-
-| Problem             | Start with                                                                |
-| ------------------- | ------------------------------------------------------------------------- |
-| App frame           | `navbar` + responsive `offcanvas-{bp}` sidebar + `container-fluid`        |
-| Page sections       | spaced headings or `card`                                                 |
-| Actions             | `btn`, `btn-group`, `btn-toolbar`, `d-grid gap-2`                         |
-| In-page views       | `nav-tabs` / `nav-pills` / `nav-underline` + panes                        |
-| Data                | `table` + `table-responsive` (+ patterns in the deep reference)           |
-| Filters / secondary | `offcanvas`, `dropdown`, `collapse`                                       |
-| Long help           | `accordion` and/or scrollable `modal`                                     |
-| Forms               | `form-control`, `form-select`, `form-floating`, `input-group`, validation |
-| Feedback            | `alert`, `toast`, `badge`, `progress`, `spinner`, `placeholder`           |
-| Steps / schemas     | `list-group` / `list-group-numbered`                                      |
-| Value pickers       | `form-select` / native inputs — never a dropdown posing as an input       |
-
-Markup: [components.md](references/components.md). Fine layout: [utilities.md](references/utilities.md).
+- Enterprise density: `table-sm`, `btn-sm` / `btn-group-sm`, compact toolbars — but keep every interactive target **≥ 24×24px**, measured on the rendered box rather than assumed from the class (WCAG 2.2); pad hit areas rather than shrinking them.
+- Where information density is the screen's job, take the `-sm` family across a control row together — `btn-sm` with `form-control-sm`, `form-select-sm`, `input-group-sm` — so the row shares one height. Never mix control sizes within one row.
+- Cards earn their keep: `.card` when grouping helps; otherwise spacing and type.
+- Swap conditional chrome in place. A bulk-action bar or an alert that shoves the toolbar down shifts the layout mid-task.
+- App shell, dense tables, filter bars, and the ranked responsive strategies for wide data: [bootstrap-reference.md](references/bootstrap-reference.md) → Enterprise patterns. Spacing, toolbar, truncation, and print composition: [utilities.md](references/utilities.md) → Composition habits.
+
+### States & feedback
+
+- **Every data surface ships five states:** ideal, empty, loading, partial, error. It is not done until all five exist. Loading thresholds, empty and error specifics, and the channel matrix for toast / inline alert / banner / modal: [bootstrap-reference.md](references/bootstrap-reference.md) → The five states, Feedback discipline.
+- **Build a blocking decision on the native `<dialog>`.** `showModal()` brings focus containment, Esc, an inert background, and top-layer stacking from the platform, with no instance to construct and none to leak on unmount. Dress it with Bootstrap chrome inside ([components.md](references/components.md) → Modal). Reach for `.modal` and its JS only when the project already drives its dialogs that way.
+- **Destructive actions:** prefer undoable over interrupting. Ladder and confirmation contracts: [bootstrap-reference.md](references/bootstrap-reference.md) → Destructive actions.
+
+### Forms
+
+- Give every field a visible label (top-aligned by default) or `.form-floating` — never placeholder-only.
+- Validate on **blur**, re-validate error fields on input, re-check everything on submit, and keep submit **enabled**. Never disable submit as a validation strategy.
+- Pair a focusable error summary with inline `.invalid-feedback` per field (`aria-describedby`, `aria-invalid`).
+- Layout, validation mechanics and their assistive-tech limitation, input groups, autosave, and multi-step rules: [bootstrap-reference.md](references/bootstrap-reference.md) → Forms in production, Wizards & multi-step forms.
 
 ### When custom CSS is justified
 
-This is rung 4 of the styling ladder, so it is the developer's decision. Propose it, name what it buys, and do not take it unprompted. Exhaust rungs 1–3 first: correct component structure, then utilities, then the extension points — component `--bs-{component}-*` variables for restyling, the utilities API for missing utility steps ([bootstrap-reference.md](references/bootstrap-reference.md) → Theming).
-
-When the developer does authorize it:
-
-- Name in Bootstrap vocabulary
-- Colors from `var(--bs-…)` / theme tokens so light and dark both work
-- Logical properties (`margin-inline-start`, not `margin-left`) so RTL works
-- Minimal surface area; document why
-- A stylesheet rule, never a `style` attribute or a `<style>` block — those cannot be themed, overridden, or made responsive
-
-### Anti-patterns
-
-- Templated "AI" looks when the brief left the axis free (see frontend-design)
-- Purple-gradient / glow / emoji / pill-soup decoration without subject reason
-- Faux widgets that break focus and theme behavior — a `div` pretending to be a select, grid, or tab
-- Hand-rolling combobox/datepicker/data-grid when native or an accessible library exists ([bootstrap-reference.md](references/bootstrap-reference.md) → When not to hand-roll)
-- Scroll anchors posing as tabs
-- Color-only status
-- An empty `.badge` used as a dot — `.badge:empty { display: none }` means it never rendered
-- Assuming an unfilled `.badge` is transparent — compatible skins may give it a default background; a muted badge states its fill (`bg-*-subtle`, `bg-transparent`)
-- A colored mark dropped onto a selected/active fill of the same family — the fill wins and the mark disappears
-- Disabled destructive controls left at full danger saturation
-- Treatments accepted from docs memory instead of the compiled cascade
-- Layout-shifting conditional chrome (bulk bars or alerts that shove the toolbar — swap in place)
-- Nested bordered divs instead of real `card` structure
-- Hard-coded hex that ignores `data-bs-theme`
-- Deprecated dark variants (`navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, `carousel-dark`, `text-muted`) in new code
-- Inventing utility classes not in [utilities.md](references/utilities.md) — they fail silently
-- Disabling submit as a validation strategy; blocking paste in password/OTP fields
-- Errors delivered as toasts or hover tooltips
-- One infinite stack of pastel cards for documentation (prefer accordion/sections)
+This is rung 4 of the styling ladder, so it is the developer's decision. Propose it, name what it
+buys, and do not take it unprompted. Exhaust rungs 1–3 first: correct component structure, then
+utilities, then the extension points — component `--bs-{component}-*` variables for restyling, the
+utilities API for missing utility steps ([bootstrap-reference.md](references/bootstrap-reference.md)
+→ Theming).
+
+When the developer authorizes it:
+
+- Name it in Bootstrap vocabulary.
+- Take colors from `var(--bs-…)` and theme tokens so light and dark both work.
+- Use logical properties (`margin-inline-start`, not `margin-left`) so RTL works.
+- Keep the surface area minimal and document why.
+- Write a stylesheet rule, never a `style` attribute or a `<style>` block.
 
 ---
 
 ## Accessibility baseline
 
-- Skip link to main; landmarks; `h1` → `h2` order
-- `aria-label` on icon-only controls; targets ≥ 24×24px
-- `aria-current` / `aria-selected` on active nav/tabs — exactly one `aria-current` per selection
-- `aria-expanded` / `aria-controls` for disclosure
-- `aria-describedby` for help and errors; `aria-invalid` on failed fields
-- Live regions match the message: an async status mark is `role="status"`; an alert-styled notice is `role="alert"`
-- A form whose host already names the request associates with that name (`aria-labelledby`) instead of repeating the prompt as its own label
-- Visible focus (keep Bootstrap rings; `.focus-ring` helper for custom elements — never `outline: none`)
-- Focus not obscured by sticky chrome (`scroll-margin-top`); focus moved deliberately on SPA route change, failed submit, and row delete
-- Meaning not by color alone; contrast verified
-- Drag interactions have a non-drag alternative
-- Modals: `aria-labelledby`; let Bootstrap trap/restore focus; dispose instances in SPAs on unmount
-
-WCAG 2.2 deltas, APG pattern contracts, reduced motion, and SPA focus recipes: [bootstrap-reference.md](references/bootstrap-reference.md) → Accessibility.
+- Skip link to main; landmarks; `h1` → `h2` order.
+- `aria-label` on icon-only controls; targets ≥ 24×24px.
+- `aria-current` / `aria-selected` on active nav and tabs — exactly one `aria-current` per selection.
+- `aria-expanded` / `aria-controls` for disclosure.
+- `aria-describedby` for help and errors; `aria-invalid` on failed fields.
+- Live regions match the message: an async status mark is `role="status"`; an alert-styled notice is `role="alert"`.
+- A form whose host already names the request associates with that name (`aria-labelledby`) instead of repeating the prompt as its own label.
+- Visible focus — keep the Bootstrap rings, use the `.focus-ring` helper for custom elements, and never write `outline: none`.
+- Focus not obscured by sticky chrome (`scroll-margin-top`); focus moved deliberately on SPA route change, failed submit, and row delete.
+- Meaning never by color alone; contrast verified.
+- Every drag interaction has a non-drag alternative.
+- Dialogs carry `aria-labelledby`; let the platform or Bootstrap trap and restore focus rather than scripting it; dispose Bootstrap instances in SPAs on unmount.
+
+WCAG 2.2 deltas, APG pattern contracts, reduced motion, and SPA focus recipes:
+[bootstrap-reference.md](references/bootstrap-reference.md) → Accessibility.
 
 ---
 
@@ -255,31 +215,23 @@ WCAG 2.2 deltas, APG pattern contracts, reduced motion, and SPA focus recipes: [
 
 ```
 Progress:
-- [ ] Portability: followed project code law; no wrong-stack assumptions
+- [ ] Project code law followed; no wrong-stack assumptions
 - [ ] Subject, audience, single job stated
-- [ ] Design plan: palette, type, layout, one signature (critiqued vs AI defaults)
-- [ ] Bootstrap shell from components.md; utilities from utilities.md (no invented classes)
-- [ ] Styling ladder held: component structure, then utilities, then extension points — no `style` attribute, no `<style>` block, no custom rule doing a utility's job
-- [ ] Plan tokens mapped to theme / --bs-* (no hex scatter); light/dark if both ship
-- [ ] Copy: user language, consistent verbs, useful empty/error/loading
+- [ ] Design plan critiqued against the AI defaults: palette, type, layout, one signature
+- [ ] Shell from components.md, utilities from utilities.md; no invented class
+- [ ] Styling ladder held: no `style` attribute, no `<style>` block, no custom rule doing a utility's job
+- [ ] Plan tokens mapped to theme / --bs-* (no hex scatter); light and dark both shipped where both are offered
+- [ ] Copy in user language, verbs consistent, empty/error/loading text useful
 - [ ] Five states per data surface: ideal / empty / loading / partial / error
-- [ ] Contrast measured in both themes: ≥ 4.5:1 information-bearing (small included), ≥ 3:1 marks and state chrome; meaning not color-alone
+- [ ] Contrast composited and measured in both themes: ≥ 4.5:1 information-bearing (small included), ≥ 3:1 marks and state chrome; meaning not color-alone
+- [ ] Tiers held: `-emphasis` for information-bearing status, solid buttons for real actions, no tone class inside a filled surface
 - [ ] Every treatment resolved in the shipped cascade, not from docs memory
-- [ ] Keyboard: focus visible, not obscured, targets ≥ 24px, icon labels
-- [ ] Reduced motion respected; drag has non-drag alternative
+- [ ] Authored classes checked against that cascade; one glyph per meaning; every instrument's control failed
+- [ ] Keyboard: focus visible, not obscured, targets ≥ 24px, icon controls named
+- [ ] Reduced motion respected; every drag has a non-drag path
 - [ ] Forms: labels visible, blur validation, error summary + inline, submit enabled
-- [ ] Responsive spot-check (claimed breakpoints); RTL-safe (start/end only)
-- [ ] States: hover/focus/disabled/invalid/active
-- [ ] SPA hygiene: JS instances disposed on unmount (or framework wrappers used)
-- [ ] Remove one unnecessary accessory
+- [ ] Claimed breakpoints spot-checked; RTL-safe (start/end only)
+- [ ] States present: hover / focus / disabled / invalid / active
+- [ ] SPA hygiene: JS instances disposed on unmount, or framework wrappers used
 - [ ] Rendered proof: captures at both viewports and both themes + an accessibility snapshot
 ```
-
----
-
-## Key takeaways
-
-- **Layered package** — craft and Bootstrap recipes live in the reference files; this file is the decision loop.
-- **Distinctive** = subject + one signature + restraint — in product UI, signature in the chrome, discipline in the data.
-- **Bootstrap** = reliable shipping across breakpoints, themes, and writing directions — extend through its variables and APIs, not against them.
-- **Done** = design critique **and** production states **and** the accessibility bar — each proven by what rendered, in any environment.