@orkestrel/scaffold 0.0.35 → 0.0.36

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.

package/dist/host/agents/skills/enterprise-bootstrap/references/bootstrap-reference.md

@@ -79,8 +79,6 @@ CDN (5.3.8 is the current — and final — 5.3.x patch before 5.4):
 <div class="row gx-5 gy-3">Independent horizontal/vertical gutters</div>
 ```
 
-Mobile first: write for the smallest screen, add `sm`/`md`/`lg`/`xl`/`xxl` modifiers upward. Test every breakpoint you claim.
-
 ## Color Modes (light / dark / custom)
 
 The 5.3 color-mode system replaces the old per-component dark variants.
@@ -90,7 +88,7 @@ The 5.3 color-mode system replaces the old per-component dark variants.
 - `data-bs-theme="light|dark"` on `<html>` sets the mode globally; on any element it scopes the mode to that subtree (nested scopes win over ancestors). Default is light.
 - Mode switching works by re-pointing root CSS variables — components never change their own rules. Core variables swapped per mode: `--bs-body-bg`, `--bs-body-color`, `--bs-emphasis-color`, `--bs-secondary-color`, `--bs-secondary-bg`, `--bs-tertiary-color`, `--bs-tertiary-bg`, `--bs-border-color`, `--bs-heading-color`, `--bs-link-color`.
 - Each theme color also gets a mode-adaptive triplet — `--bs-{color}-text-emphasis`, `--bs-{color}-bg-subtle`, `--bs-{color}-border-subtle` — surfaced as `.text-{color}-emphasis`, `.bg-{color}-subtle`, `.border-{color}-subtle`. These are the workhorses for status UI that must read in both modes.
-- **The triplet is a recipe, not a guarantee.** `text-{color}-emphasis` on `bg-{color}-subtle` is _designed_ to pass, and it usually does in stock Bootstrap — but the values are tokens, and a compatible skin redefines them. Resolve the actual computed values from the compiled cascade the page loads (the shipped CSS, dependency stylesheets included) and measure each pairing once per theme before you rely on it. A class with no rule of its own may still inherit one; documentation memory decides nothing.
+- **The triplet is a recipe, not a guarantee.** `text-{color}-emphasis` on `bg-{color}-subtle` is _designed_ to pass, and it usually does in stock Bootstrap — but the values are tokens, and a compatible skin redefines them. Resolve the actual computed values from the compiled cascade the page loads (the shipped CSS, dependency stylesheets included) and measure each pairing once per theme before you rely on it. A class with no rule of its own may still inherit one; never accept a value from documentation.
 - Deprecated by this system: `.navbar-dark`, `.dropdown-menu-dark`, `.btn-close-white`, `.carousel-dark` → put `data-bs-theme="dark"` on the component or an ancestor instead.
 
 ### Author rules
@@ -337,19 +335,28 @@ Dropdowns, tooltips, and popovers require Popper — load `bootstrap.bundle.min.
 
 ### Baseline (every screen)
 
-- Skip link (`.visually-hidden-focusable`) to `<main>`; landmarks (`nav`, `main`, `aside`); heading order `h1 → h2 → h3` without skips.
-- `aria-label` on icon-only controls; `aria-current="page"` on active nav; `aria-selected` on active tabs; `aria-expanded` + `aria-controls` on disclosure triggers; `aria-describedby` for help/errors.
-- Visible focus everywhere — keep Bootstrap's rings; use the `.focus-ring` helper on custom interactive elements instead of removing outlines.
-- Meaning never by color alone: pair status color with text, an icon, or a visually-hidden word.
-- Body text contrast ≥ 4.5:1 (3:1 for large text and UI graphics). Bootstrap's own docs warn parts of the default palette can fall short — verify your combinations; don't assume framework colors pass.
+Hold the baseline in [SKILL.md](../SKILL.md) → Accessibility baseline. Its Bootstrap-specific parts:
+
+- Skip link: `.visually-hidden-focusable` to `<main>`. Landmarks: `nav`, `main`, `aside`. Heading order `h1 → h2 → h3` without skips.
+- Keep Bootstrap's focus rings; use the `.focus-ring` helper on custom interactive elements instead of removing outlines.
+- `.visually-hidden` for screen-reader-only text; `.visually-hidden-focusable` for skip links. Never combine the two.
+- Verify every color pairing against the shipped cascade. Bootstrap's own docs warn that parts of the default palette fall short.
+
+**Measuring the bars:**
+
+- Hold the bars from [SKILL.md](../SKILL.md) → Surfaces, color, contrast: **≥ 4.5:1** for everything information-bearing, **≥ 3:1** for textless marks and state chrome. WCAG 2.2 permits 3:1 for large text; this package does not — size grants no lower tier.
+- Measure in **both themes**, from the compiled cascade, never from the token names. A pairing that passes in light routinely fails in dark, and a skin's values are its own.
+- Focus rings and hover fills are UI graphics: they are in scope for the 3:1 bar.
+- Disabled controls are exempt from the bars by the spec. That exemption covers legibility, not meaning — see [Destructive actions](#destructive-actions) for the one disabled state that still has to change color.
+
+**The instrument.** Bootstrap paints in translucent layers: a card header and footer are a 3% tint of the body color over the card's own background. A reader that stops at the first painted ancestor and drops its alpha treats that tint as full-strength paint, and is then wrong in **both** directions — it green-lights a pairing nobody can read, and it red-flags one that reads fine. Use a reader that:
 
-**Measuring the bars (the part that gets skipped):**
+- collects every painted layer from the element upward to the first opaque one, then composites them top over bottom (Porter-Duff `over`) onto that opaque base;
+- composites a translucent foreground over that result before taking the ratio, rather than reading the declared color;
+- measures both themes in one run, since the theme swap re-points the tokens under every layer;
+- carries a negative control drawn from outside the population it covers — a pairing known to fail — and voids the run if that control passes.
 
-- Measure in **both themes**, from the compiled cascade, not from the token names. A pairing that passes in light routinely fails in dark, and a skin's values are its own.
-- **≥ 4.5:1** for everything information-bearing — including `small`, captions, meta lines, and timestamps. Small size is not a licence for a lower tier; `text-body-tertiary` is decoration, `text-body-secondary` is the floor for text a user must read.
-- **≥ 3:1** for textless marks and state indicators — status glyphs, rings, dividers that carry meaning — and for the hover/focus chrome that signals state. Focus rings and hover fills are UI graphics: they are in scope, and they are the ones nobody measures.
-- Disabled controls are exempt from the bars by the spec. That exemption is about legibility, not about meaning: see [Destructive actions](#destructive-actions) for the one disabled state that still has to change color.
-- `.visually-hidden` for SR-only text; `.visually-hidden-focusable` for skip links (never combine the two).
+Wire the reader into the suite once it has settled a question.
 
 ### WCAG 2.2 deltas that bite dense app UI
 
@@ -398,7 +405,7 @@ The Bootstrap implementation — a responsive offcanvas that renders inline abov
 	<header class="navbar bg-body-tertiary border-bottom sticky-top">
 		<div class="container-fluid">
 			<button
-				class="btn btn-outline-secondary d-lg-none"
+				class="btn btn-secondary d-lg-none"
 				type="button"
 				data-bs-toggle="offcanvas"
 				data-bs-target="#appSidebar"
@@ -506,20 +513,20 @@ Give header cells an **opaque background** (`bg-body-secondary` or a table varia
 ### Wizards & multi-step forms
 
 - Show step progress: current position, total, and step names ("Step 2 of 4 — Billing"); `list-group-numbered` or a simple nav renders it honestly.
-- Validate per-step before advancing — failing forward compounds; failing at the end is worse.
+- Validate per step before advancing; never let a step advance carrying invalid data.
 - Back never loses data. Persist partial state (save-and-resume) for anything beyond ~3 steps or that crosses sessions.
 - Never re-ask what a previous step collected (Redundant Entry, 3.3.7) — carry it forward or offer "same as above".
 - Last step: a review summary with per-section edit links, then one clearly-named commit action ("Create account", not "Submit").
 
 ### The five states
 
-Design **all five** for every data surface: ideal (populated), empty, loading, partial, error. A component isn't done until all five exist — empty and error are where trust is won or lost.
+Design **all five** for every data surface: ideal (populated), empty, loading, partial, error. A component isn't done until all five exist.
 
 - **Skeleton vs spinner:** skeleton (`placeholder` + `placeholder-glow`) when you know the content's shape and it fills a region — tables, cards, detail panes — because it holds layout and shortens perceived wait. Spinner for short, indeterminate, or in-control waits (inside a button, a small inline fetch).
 - **Thresholds (guidance):** under ~1s show nothing — a flashed loader is worse than none; ~1–10s show a spinner or skeleton; beyond ~10s show determinate progress (percent or step) so it doesn't feel hung.
 - **Optimistic vs pessimistic:** apply UI immediately and reconcile (rolling back loudly on failure) for reversible high-frequency actions — toggles, stars, reorders. Await confirmation for money, audited records, and anything a rollback would confuse.
-- **Empty states** invite the next action (button + one line of why), and filtered-empty differs from never-had-data.
-- **Every error state carries a keyboard-reachable retry** and preserves surrounding context — a body fetch failure must not blow away the toolbar and filters.
+- **Empty states** invite the next action (button + one line of why). Never-had-data and filtered-empty are different states with different escapes — never ship one generic "nothing here".
+- **Every error state states what failed and how to fix it**, carries a keyboard-reachable retry in place, and preserves surrounding context — a body fetch failure must not blow away the toolbar and filters.
 
 ### Feedback discipline
 
@@ -540,9 +547,9 @@ Match friction to reversibility × blast radius:
 2. **Confirm dialog** for irreversible-but-scoped operations. Restate the specific consequence ("This permanently deletes 3 invoices"), verb-labeled buttons ("Delete invoices" / "Cancel" — never Yes/No), destructive action visually separated from safe; `alertdialog` semantics; focus lands on the safe action.
 3. **Type-to-confirm** (type the entity name) only for high-blast-radius irreversible operations — delete an org, drop a dataset.
 
-Don't type-gate a single-row delete; don't one-tap a tenant wipe. Overused confirmations train the click-through reflex that defeats them.
+Don't type-gate a single-row delete; don't one-tap a tenant wipe. Confirm only where this ladder calls for it — a confirmation on every action gets clicked through.
 
-**A disabled destructive control stops looking destructive.** `btn-danger` at full saturation reads as armed and available whatever the `disabled` attribute says — the loudest control on the screen is the one the user cannot use, and the contrast exemption for disabled controls does not excuse it. While the action is unavailable, neutralize the variant (drop to the neutral/outline variant, or let the disabled state mute the fill) so the color stops promising an action, and say _why_ it is unavailable in text the assistive layer reaches: `aria-describedby` pointing at the reason, with `title` only as the pointer-user convenience on top. A `title` alone is not an explanation — it never reaches a keyboard or screen-reader user, and it disappears on touch.
+**Neutralize a disabled destructive control.** `btn-danger` at full saturation reads as armed whatever the `disabled` attribute says, and the contrast exemption for disabled controls does not excuse it. While the action is unavailable, drop to the neutral or outline variant (or let the disabled state mute the fill) so the color stops promising an action, and say _why_ it is unavailable in text the assistive layer reaches: `aria-describedby` pointing at the reason, with `title` only as the pointer-user convenience on top. Never use `title` alone — it never reaches a keyboard or screen-reader user, and it disappears on touch.
 
 ## RTL
 
@@ -570,7 +577,7 @@ Bootstrap has **no** combobox/autocomplete, date picker, multi-select tags input
 
 - **Reach for native first:** `<input type="date">`, `<datalist>` for light autocomplete, `<select multiple>` where acceptable. Native widgets bring keyboard and AT behavior free.
 - **Reach for an established accessible library second** when the product genuinely needs the richer widget (combobox with async search, spreadsheet grid, drag-reorder tree). Budget for auditing it against the APG contract.
-- **Hand-roll last**, only with the APG contract in hand ([Accessibility](#accessibility) → Pattern contracts) and time to implement the _keyboard_ half — the visual half is the easy 20%.
+- **Hand-roll last**, only with the APG contract in hand ([Accessibility](#accessibility) → Pattern contracts) and budget for the _keyboard_ half, which is most of the work.
 - Never fake it: a `.dropdown-menu` posing as a select, a `<div>` grid with click handlers, or a scroll-anchor "wizard" each break keyboard and AT users in ways a demo never shows.
 
 ## Common Layout Patterns