@orkestrel/scaffold 0.0.64 → 0.0.66

package/README.md

@@ -9,7 +9,7 @@
 npm install --save-dev @orkestrel/scaffold
 ```
 
-The executable needs Node 22.12 or later. Run it without installing anything:
+The executable needs Node 22.18.0 or later. Run it without installing anything:
 
 ```sh
 npx @orkestrel/scaffold --help
@@ -58,6 +58,16 @@ vendored data root, and the generated file set.
 
 ## Notes
 
+The `scaffold new` command generates a workspace that declares an npm floor of 11.6.0 in its
+`devEngines` record. An npm at 10.9.0 or later and earlier than 11.6.0 refuses the `npm install`
+command there with the `EBADDEVENGINES` code, before resolving the dependency graph.
+npm 10.5.0 and npm 10.8.3, the releases measured earlier than 10.9.0, ignore the record and fail
+inside dependency resolution instead.
+No Node release the executable supports bundles an npm earlier than 10.9.0. Read the ambient
+version with the `npm --version` command. Raise it with the `npm install --global npm@11.6.0`
+command before the first install.
+These readings come from a Linux host, on 2026-09-13.
+
 On Windows, run the executable as `npx scaffold …` or `node ./dist/bin/main.js …`. PowerShell
 mangles npm's `--` passthrough, so avoid `npm run scaffold -- …` there.
 

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

@@ -1,225 +1,243 @@
 ---
 name: enterprise-bootstrap
 description: >-
-  Design and build distinctive, production-grade user interfaces with Bootstrap
-  5.3 and intentional frontend craft, in any host project and on any stack. Use
-  for Bootstrap user-interface work — creating, restyling, or
+  Design and build distinctive, production-grade UI with Bootstrap 5.3 on any
+  stack. Use for any Bootstrap interface work — creating, restyling, or
   extending pages, screens, components, layouts, app shells, dashboards, admin
   panels, SaaS tools, data tables, filter bars, forms, wizards, navigation,
   modals, empty/loading/error states, dark mode, marketing surfaces — whenever
   the task touches HTML/CSS/visual design, mentions Bootstrap or its components,
-  or must look professional and avoid templated defaults. Covers aesthetics,
-  typography, color modes, design tokens, accessibility (WCAG 2.2 AA),
-  responsive layout, and enterprise app patterns. The `orkestrel-polish-surface`
-  skill owns a requested verdict, round, or campaign over a surface that already
-  renders, including a review that changes nothing. In that campaign's fix
-  units, use this skill for Bootstrap craft.
+  asks for visual hierarchy, polish, a design system, or spacing/type/color
+  scales, or must look professional rather than like stock Bootstrap. Covers
+  aesthetics, typography, color modes, design tokens, elevation, finishing
+  details, accessibility (WCAG 2.2 AA), responsive layout, and enterprise app
+  patterns. The `orkestrel-polish-surface` skill owns a requested verdict,
+  round, or campaign over a surface that already renders, including a review
+  that changes nothing; in that campaign's fix units, use this skill for
+  Bootstrap craft.
 ---
 
 # Enterprise Bootstrap
 
-Set a deliberate visual direction, build it from Bootstrap 5.3 components and utilities, and settle
-every claim about the result from what renders.
-
-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). Pick an
-input's affordance from [inputs.md](references/inputs.md) by what the person is asked for, not by
-what a schema calls the field. 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`                                                  | 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                           |
-| Inputs         | [inputs.md](references/inputs.md)                           | Affordance per input category, its alternates, its rung, its states               |
-| 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 |
-| Instruments    | [inspection.md](references/inspection.md)                   | Property, population, reading, negative control, and coverage per instrument      |
+Start with the person's task, give it a deliberate visual hierarchy, and build it from Bootstrap
+5.3 components and utilities. Settle claims about the result from what renders.
+
+Open the reference that owns the decision before writing markup. Pick components and their
+structure from [components.md](references/components.md), input affordances from
+[inputs.md](references/inputs.md), and fine layout from [utilities.md](references/utilities.md). Take narrow composition and breakpoint
+behavior from [responsive-layout.md](references/responsive-layout.md) before building the shell.
+Never guess a class name: an invented utility has no shipped rule and fails silently. Where
+Bootstrap ships no component — 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`                                                  | Process, styling ladder, contrast bars, action rank, checklist     |
+| Design craft   | [frontend-design.md](references/frontend-design.md)         | Hierarchy, spacing, type, color, depth, imagery, signature, copy   |
+| Components     | [components.md](references/components.md)                   | Bootstrap markup and enterprise selection notes                    |
+| Inputs         | [inputs.md](references/inputs.md)                           | Affordance, alternates, styling rung, and states per category      |
+| Responsive     | [responsive-layout.md](references/responsive-layout.md)     | Narrow-first layout, task parity, containers, overlays, proof      |
+| Color modes    | [color-modes.md](references/color-modes.md)                 | Inheritance, surface ownership, nested modes, component exceptions |
+| Utilities      | [utilities.md](references/utilities.md)                     | Class index, helpers, composition                                  |
+| Bootstrap deep | [bootstrap-reference.md](references/bootstrap-reference.md) | Theming, forms, lifecycle, accessibility, enterprise patterns      |
+| Instruments    | [inspection.md](references/inspection.md)                   | Mechanical evidence contracts and rendered review criteria         |
+
+Take the operating rules here over a lookup example. Adapt example heading levels, action rank,
+labels, and paint to the host surface. Move an illustrative inline declaration through the styling
+ladder before shipping; its presence in a lookup is not an exemption. A declaration a lookup names
+as a runtime producer is the exception, and only for the property that lookup names.
 
 ---
 
 ## Portability
 
 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.** Take language, layout, and forbidden patterns from its `AGENTS.md` file, its lint rules, and its design system. Take UI craft and Bootstrap usage from here, and never 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 frontmatter description. When the user points at it, treat it as authoritative for the visual pass.
+2. **Target Bootstrap 5.3.x** class names and behaviors. Hold a compatible skin to the same component contracts.
+3. **Follow the project's code law.** Take language, layout, and forbidden patterns from `AGENTS.md`, lint rules, and the design system. Take UI craft and Bootstrap usage from here, never language law. Preserve existing tokens and identity unless the brief authorizes changing them.
+4. **Write framework-neutral markup** — semantic HTML plus Bootstrap classes. Wire behavior with the project's stack; in an SPA prefer framework-native Bootstrap wrappers over competing DOM ownership ([bootstrap-reference.md](references/bootstrap-reference.md) → JavaScript lifecycle).
+5. **Keep this folder intact** so its relative links resolve. Install or vendor it wherever the tooling looks for skills; the paths are tooling-specific, the content is not.
+6. **Use the installed Bootstrap.** Otherwise take the pinned CDN example from [bootstrap-reference.md](references/bootstrap-reference.md) → Quick start. Do not upgrade dependencies as a side effect of a visual pass.
+7. **Apply this skill** to the work in its frontmatter. For a requested verdict, round, or campaign over an already rendering surface, use `orkestrel-polish-surface`; use this skill for the campaign's Bootstrap fixes.
 
 ---
 
 ## The mandate
 
-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** — take components and utilities first, custom CSS only when the system cannot express the need, and paint through `--bs-*` so light and dark both survive.
+1. **Design direction** — ground hierarchy and character in the subject, audience, and job. Preserve an existing signature or introduce a coherent one when the brief calls for it; spend aesthetic risk only where the brief leaves room.
+2. **Bootstrap execution** — take components and utilities first, extend the system only for a real gap, and preserve Bootstrap's adaptive surfaces and component-owned foregrounds. Take color decisions from [color-modes.md](references/color-modes.md); a `--bs-*` prefix alone does not establish mode support.
 
-Match the density to the context: a marketing page can 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).
+A marketing page may lead with a thesis-hero; an authenticated tool leads with the work. Keep its
+signature in the frame and its data conventional enough to scan. A distinctive shell never excuses
+a confusing feature ([frontend-design.md](references/frontend-design.md) → Where the signature lives).
 
 ---
 
 ## Process
 
-Read [frontend-design.md](references/frontend-design.md) before setting a direction; it owns subject
-grounding, hero and thesis, typography, structure, motion, restraint, and interface copy. Then work
-this loop:
-
-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 every data state. Critique what rendered, not the markup.
-
-Show a direction only after it satisfies the brief and the quality floor, and keep every earlier
-draft private ([frontend-design.md](references/frontend-design.md) → Process).
-
-**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. Take captures at every viewport and
-every theme the surface declares, plus an accessibility snapshot, as the review input, and use source only to corroborate
-the mechanism. For a full review-round campaign built on that evidence, use the
-`orkestrel-polish-surface` skill instead of improvising one here.
-
-**Mechanical proof.** Run every instrument in [inspection.md](references/inspection.md) with the
-negative control it names, and treat an instrument whose negative control passes as broken;
-`.claude/rules/quality.md` owns that law where it is present. Those instruments settle what a capture
-cannot: composited contrast, authored classes against the shipped cascade, declared class
-combinations, style escapes, token discipline, a custom rule doing a utility's job, and one glyph per
-meaning. Hold every check the deliverable lists to that shape, whether or not inspection.md names
-it: each states its population, its negative control, and its coverage, and a check that cannot
-name a negative control is recorded as open rather than listed as a check.
+Read [frontend-design.md](references/frontend-design.md) before setting a direction. It owns the
+visual decisions; the loop here owns their order.
+
+1. **Ground** — state the subject, audience, single job, primary action, and existing constraints. Use real content; mark fixture data as such. Start with a feature, not a navigation shell.
+2. **Plan** — record each region's narrow layout, expansion threshold, content/action parity, and overflow policy in a responsive contract. Render the primary task at 320 and 390 CSS px before expanding the shell. Settle reading order and grouping in low fidelity before paint, and hold color until the arrangement reads in grayscale (body surfaces, inherited text, weight, and spacing only). Reuse or define a compact system: **color families and surface ownership**, **type roles and scale**, **spacing and width roles**, **radius and elevation**, **a coherent signature where the brief calls for one**. Set personality through these levers — typeface, primary color, radius family, and copy register — and hold each on every screen. Record changes, not a parallel system. Take each scale's Bootstrap source, shipped steps, and gaps from [bootstrap-reference.md](references/bootstrap-reference.md) → Define the working scales. State the settled layout in prose or a small wireframe before building it.
+3. **Critique the plan** — reject unclear hierarchy, invented functionality, and interchangeable styling. Follow a pinned brief; otherwise take character from the subject rather than clustered AI defaults. Do not manufacture novelty inside an established product.
+4. **Build** — implement the smallest useful flow and its data states, then refine the working feature. Use documented components and shipped utilities; map shared tokens once. Fix conflicting declarations rather than adding specificity. Revise the recorded plan when the render disproves it. Extend the next feature after this one works.
+5. **Critique the render** — complete the primary flow at narrow width first; then read task, hierarchy, grouping, type, contrast, states, and signature in order. Fix the earliest failure first, then re-read the earlier criteria against the fixed render. Remove a needless accessory if one exists; never remove useful information to meet a quota.
+
+Keep exploratory drafts private. Deliver the selected direction, the changes, and their evidence
+limits, not every discarded variation.
+
+**Rendered proof.** Capture the declared viewports, themes, and states, plus an accessibility
+snapshot. Use captures for visual claims and source to explain mechanisms; use interaction tests
+for behavior. `.agents/orchestration.md` owns this law where present. Name the coverage and any
+unverified state. Without a render-capable environment, report visual verification as open, never
+as passed.
+
+**Mechanical proof.** Run applicable instruments in [inspection.md](references/inspection.md) with
+their negative controls. Report population, reading, control result, and coverage. A control the
+reader misses invalidates the run; an expected but empty population fails. Record a genuinely
+absent feature as not applicable with a reason, not as a pass. `.claude/rules/quality.md` owns this
+law where present. Keep qualitative design review separate from instrument results: named criteria
+and captures are evidence, not fabricated mechanical tests or a beauty score.
 
 ---
 
 ## Bootstrap operating principles
 
-1. **Mobile first** — build the smallest screen first, then `sm` / `md` / `lg` / `xl` / `xxl`.
-2. **Semantic HTML** — use `nav`, `main`, and `section`, and hold the heading order.
-3. **Work down the styling ladder that follows** — 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 can 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).
+1. **Mobile first** — unprefixed classes define a complete narrow task; breakpoint classes enhance it when its container has room. Use the contract in [responsive-layout.md](references/responsive-layout.md), not a desktop composition with wrapping added later.
+2. **Semantic HTML** — use landmarks and hold heading order; choose visual size independently of heading level.
+3. **Work down the styling ladder** — component classes, utilities, then Bootstrap's extension points.
+4. **Test behavior, not class presence.** Check 320 and 390 CSS px, a wide view, and immediately below/at/above each used threshold. Drive state and theme transitions; enlarge text and use long content. Distinguish viewport reflow, browser zoom, and text-resize tests.
+5. **Take Bootstrap's transitions first.** Use custom motion only where it serves the task or signature, and respect `prefers-reduced-motion` ([bootstrap-reference.md](references/bootstrap-reference.md) → Reduced motion).
+6. **Resolve treatments in the shipped cascade** — Bootstrap, skins, and dependency stylesheets. A token name or class recipe is not a contrast guarantee. Measure foregrounds, surfaces, and translucent layers in each declared theme and state.
 
 ### The styling ladder
 
-Work down these rungs in order. Reach a rung only when the preceding one cannot express the need.
+Reach a rung only when the preceding one cannot express the need. Cite a rung by its name, never by
+its position.
 
-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. Modifier classes, affordance 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 the component-class and utility tiers.
-4. **Leave anything beyond Bootstrap's conventions to the developer.** Stop at rung 3 and say plainly what rung 4 would require. Take rung 4 unasked only where [inspection.md](references/inspection.md) → When an authored rule is already earned opens it.
+1. **Component rung — documented component structure.** Keep required elements, nesting, modifiers, behavior, and ARIA. Use optional headers, titles, and footers only when the content needs them; a component example is not a mandate to add empty chrome.
+2. **Utility rung — shipped utilities.** Compose spacing, flex, sizing, text, border, and color classes from [utilities.md](references/utilities.md). Verify extensions exist in the loaded build before authoring them.
+3. **Extension rung — Bootstrap extension points.** Use component `--bs-{component}-*` variables or the Sass utilities API for a recurring system gap. Declare the role once, compile where required, and verify the emitted rule.
+4. **Authored rung — developer-authorized custom CSS.** Propose what Bootstrap cannot express and why. Take this rung unasked only under [inspection.md](references/inspection.md) → When an authored rule is already earned.
 
-Never reach first for any of these, because each ends the cascade for that element and then survives
-no `--bs-*` retheming, no breakpoint change, and no color-mode change:
+Resolve a conflict at the rung that owns it. Utilities may carry `!important`, so read the winning
+declaration in the shipped cascade and remove the conflicting class before escalating selector
+specificity. A class selector stays a class selector whatever its name.
 
-- a `style="..."` attribute;
-- a `<style>` block in a page or component;
-- a new stylesheet rule for something a utility already does.
+**Where an authored rule lives.** Put every authored rule in the project's stylesheet and token
+layer. A standalone HTML deliverable carries that stylesheet as one `<style>` block in `<head>` —
+tokens and declared roles, before any markup. That block is the project stylesheet.
 
-### Hierarchy & actions
-
-| 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**          |
+Never write a `style` attribute on authored markup, and never open a second `<style>` block beside
+a component or scoped to one. This rule fixes a location and nothing else: inline CSS and authored
+rules participate in the cascade normally, and a runtime producer named in
+[inspection.md](references/inspection.md) → Style escapes writes its own declaration.
 
-**Give any action that carries information or consequence a solid `btn-*` class, and keep outline
-buttons decorative.** Against stock Bootstrap the whole `btn-outline-*` family misses 4.5:1 across
-the dark theme and on light tinted surfaces — cards, subtle alerts — because an outline button
-paints no background of its own and borrows the surface it sits on.
+**What an authored rule may contain** is a separate rule, and the styling ladder owns it. Reach the
+authored rung only when the component, utility, and extension rungs cannot express the need. Do not
+duplicate a shipped utility, and keep raw values in declared primitive definitions rather than in
+component paint.
 
-**Re-measure a solid fill whenever anything layers over it** — an `opacity-*` utility, a translucent
-overlay, a skin's own tint — because the stock fills sit at the 4.5:1 bar with nothing to spare.
+### Hierarchy & actions
 
-Draw a status mark with **no text** as an icon glyph, never as a `badge`
+| Rank or meaning | Typical choice                                                                                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Primary         | `btn btn-primary` — at most one dominant action per active task region                                                                                             |
+| Secondary       | `btn-outline-secondary` with `--bs-btn-color: var(--bs-emphasis-color)` set once at the theme root (the stock label is 3.3:1 on the dark body), or `btn-secondary` |
+| Tertiary        | `btn btn-link` for an action; a real link for navigation                                                                                                           |
+| Destructive     | Rank first; strong `btn-danger` for the final destructive commit                                                                                                   |
+| Status          | Quiet badge or alert treatment; icon + color + word                                                                                                                |
+
+Choose rank before hue. Do not make every action solid or every destructive action dominant.
+Outline and link-style controls are allowed only when their text, boundary or state cue, and focus
+meet the applicable bars across actual surfaces and states. Use a measured solid variant when the
+quieter one cannot pass. Never use an inert button as decoration.
+
+Re-measure fills under opacity, overlays, or a skin. Keep the destructive confirmation ladder from
+[bootstrap-reference.md](references/bootstrap-reference.md) → Destructive actions; visual rank does
+not lower the required friction. Draw a textless status mark as an icon glyph, not an empty badge
 ([components.md](references/components.md) → Badge).
 
 ### Surfaces, color, contrast
 
-- **Measure these contrast bars 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.
-- **Take the `-emphasis` pair for information-bearing status text.** 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.
-- **Tier text a person must read `text-body-secondary` or better**, and keep `text-body-tertiary` for decorative marks: tertiary measures under 4.5:1 on every surface in both themes, so it carries no information anywhere.
-- **Inside `alert-*` and the `*-subtle` backgrounds, take `-emphasis` for information-bearing text and a solid `btn-*` class for every button.** A subtle fill degrades everything inside it one notch, so outline buttons and plain semantic text fail there even in light.
-- **Carry no tone class inside a primary fill.** 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. 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).
-- Exempt a disabled control from the bars, but never leave a disabled **destructive** control at full danger saturation — at full strength it still reads as armed. Neutralize the danger tone while the control 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`, and drive custom paint from `var(--bs-…)` — they track `data-bs-theme`, a hard-coded hex does not.
-- Take pairings from `text-bg-*`, `*-subtle`, `*-emphasis`, and `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 `*-dark` component classes `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, and take the mechanics from [bootstrap-reference.md](references/bootstrap-reference.md) → Color modes.
+- **Hold these bars — this section owns them.** ≥ 4.5:1 for all information-bearing text, including large text, captions, and metadata; ≥ 3:1 for meaningful textless marks and state/focus chrome. The text floor is deliberately stricter than WCAG's large-text exception. Measure every declared theme and reached state; do not generalize one reading to all surfaces. A ratio quoted anywhere in this skill is a stock Bootstrap reading and bounds that stock theme alone — the bars are the policy, the readings are not.
+- **Inherit ordinary text.** When content owns no background, add no foreground override. Prefer `bg-body`, `bg-body-secondary`, `bg-body-tertiary`, and `bg-*-subtle` for quiet surfaces; do not automatically add a text-color utility to them. Follow [color-modes.md](references/color-modes.md) for exceptions and component-owned colors.
+- **Pair like with like.** Adaptive text on adaptive surfaces (`text-body*` and `text-*-emphasis` on `bg-body*` and `bg-*-subtle`); fixed text on fixed fills (`text-bg-*`, a component's own foreground, or a `data-bs-theme` scope that also carries `text-body` — a scope changes variables only, and plain text inherits the outer mode's painted color). Treat a mixed pair as unproven and measure it in each declared mode: `bg-light` with inherited text, `text-white` on `bg-body`, `text-primary` on the dark body, and a stock `btn-outline-secondary` label in dark mode each fail one stock mode, while inherited text on `bg-primary` fails light and dark alike. Replace `bg-light`, `bg-white`, and `text-dark` on adaptive surfaces because they are fixed ([color-modes.md](references/color-modes.md) → Fixed and adaptive classes).
+- **Clear a deprecated class on its deprecation, not on a contrast reading.** 5.3 deprecates `text-muted`, `navbar-light`, `navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, and `carousel-dark`. `text-muted` still resolves through the adaptive secondary color, so it pairs correctly and is a deprecation to clear; the `navbar-*`, `dropdown-menu-dark`, `btn-close-white`, and `carousel-dark` classes give way to a `data-bs-theme` scope.
+- **Keep supporting text readable.** Start with inherited color, spacing, and weight. Use `text-body-secondary` for a deliberate secondary tier — it clears 4.5:1 on every stock body surface in light and dark — not for every caption. `text-body-tertiary` is body color at 50 % alpha and measures 3.0–4.1:1 on those stock surfaces: decoration or disabled only, never a caption someone reads. Any further readable tier is a declared opaque token, measured on the surface it sits on. Never quiet text with opacity, and do not carry a neutral secondary tier blindly onto a colored fill; inherit its tested foreground first, using a scoped opaque same-hue tier only when needed ([color-modes.md](references/color-modes.md) → Text tiers).
+- **Pair intentional solid surfaces; preserve selected foregrounds.** Let the owning component set its foreground and background, or use a tested solid pair. Do not recolor ordinary children. Keep status encoded by icon and word and capture the selected state.
+- **Inside subtle fills, measure the children against that fill.** Badge, button, and caption recipes need their own readings; a page-background result does not transfer into a card or alert.
+- **Exempt disabled controls from the contrast bars**, but visibly neutralize an unavailable destructive action and explain why with `aria-describedby`; `title` may supplement, never replace, the explanation.
+- **Verify mode transitions and boundaries.** Take adaptive-versus-fixed utilities, nested `data-bs-theme` scopes, badges, tables, and overlay mounts from [color-modes.md](references/color-modes.md). An attribute or variable name is not proof of painted adaptation.
+- **Bound variable backgrounds.** For text over imagery, gradients, or overlays, measure the actual painted background under the text. A flat-color reader or an average image sample cannot settle that claim.
 
 ### Density, layout, responsive
 
-- Take enterprise density from `table-sm`, `btn-sm` / `btn-group-sm`, and 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.
-- Take `.card` where grouping earns it; otherwise carry the grouping with 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.
-- Take the app shell, dense tables, filter bars, and the ranked responsive strategies for wide data from [bootstrap-reference.md](references/bootstrap-reference.md) → Enterprise patterns, and spacing, toolbar, truncation, and print composition from [utilities.md](references/utilities.md) → Composition habits.
+Take [responsive-layout.md](references/responsive-layout.md) as the layout contract. Preserve the
+primary task, reading order, and access to information at every width. A contained horizontal
+table can pass document-overflow checks and still fail the task; inspect both.
+
+- Choose density for the task. Start each gap one step too large, render, and step down; compress where throughput or comparison requires it, not because the default felt cramped. Hold every target to the floor in [bootstrap-reference.md](references/bootstrap-reference.md) → WCAG 2.2 requirements for app UI, which owns the target dimensions.
+- Take compact controls together across a row: `btn-sm`, `form-control-sm`, `form-select-sm`, and `input-group-sm`. Do not shrink body text or targets to force one-row layouts.
+- Keep inter-group gaps larger than internal gaps. Bound forms, rails, and prose by content with a maximum width; let comparison tables use the width they need. Use percentage columns only where elements must scale together — a `col-*` login card or `col-3` sidebar changes width at every breakpoint ([bootstrap-reference.md](references/bootstrap-reference.md) → Breakpoints & layout).
+- Use `.card` where an independent group earns containment. Try spacing and type before more borders, fills, or shadows. Keep elevation tied to layering, not every available box.
+- Stack search, controls, and action groups at the base; expand them only when they fit. Reserve horizontal scrolling for named two-dimensional content, not ordinary toolbars.
+- Reflow before truncating task-critical information. Scale large headings and outer space independently of body text and controls. Swap conditional chrome in place so selection or feedback does not shift the task.
+- Take layout, wide-data strategies, and frame mechanics from [bootstrap-reference.md](references/bootstrap-reference.md) → Enterprise patterns, and class composition from [utilities.md](references/utilities.md) → Composition habits.
 
 ### States & feedback
 
-- **Ship every one of these states on every data surface:** ideal, empty, loading, partial, error. Treat the surface as unfinished until every one exists. Take loading thresholds, empty and error specifics, and the channel matrix for toast / inline alert / banner / modal from [bootstrap-reference.md](references/bootstrap-reference.md) → The data 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.
-- **Make a destructive action undoable rather than interrupting**, and take the ladder and the confirmation contracts from [bootstrap-reference.md](references/bootstrap-reference.md) → Destructive actions.
+- **Ship ideal, empty, loading, partial, and error states on each data surface.** Build them within the feature cycle, not after the polished populated screen. Take the detailed contracts and feedback channels from [bootstrap-reference.md](references/bootstrap-reference.md) → The data states, Feedback discipline.
+- **Distinguish first-use from filtered-empty.** First-use offers a useful create/import action and drops inert chrome; filtered-empty preserves active filters and the clear path. Errors preserve context and offer recovery. Never invent progress or success.
+- **Build a blocking decision on native `<dialog>`** unless the project already uses Bootstrap modals. Preserve platform focus, dismissal, and top-layer behavior; dress the interior with Bootstrap components ([components.md](references/components.md) → Modal).
+- **Prefer undo for reversible actions.** Take interruption and confirmation rules from [bootstrap-reference.md](references/bootstrap-reference.md) → Destructive actions.
 
 ### Forms
 
-- Choose each field's affordance in [inputs.md](references/inputs.md) → The catalog by what the person is asked for, draw every state in that file's fixed set, and obey its cross-category rules — read-only chrome, the locked select, the chosen filter's accent tone, the non-drag path for a file drop.
-- 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`).
-- Take layout, validation mechanics and their assistive-technology limitation, input groups, autosave, and multi-step rules from [bootstrap-reference.md](references/bootstrap-reference.md) → Forms in production, Wizards & multi-step forms.
+- Choose the affordance by what the person is asked for in [inputs.md](references/inputs.md), and draw its fixed state set. Keep read-only/edit geometry stable and preserve the non-drag path for uploads.
+- Give every field a visible label or `.form-floating`, never placeholder-only. Removing redundant labels on displayed data does not apply to inputs. Naming a form does not name its individual controls.
+- Keep label, control, help, and error closer to each other than to the next field group. Use extra columns for genuinely related fields or supporting explanation, not to fill a wide canvas.
+- Validate on blur, re-validate error fields on input, and re-check on submit. Keep submit enabled while fields are invalid; a disabled submit hides what is wrong. While a submit is in flight, mark the control busy and refuse a second submit — that pending block is a different state, and this rule does not bar it. Show a focusable error summary and linked inline feedback (`aria-describedby`, `aria-invalid`).
+- Take validation mechanics, autosave, and multi-step rules from [bootstrap-reference.md](references/bootstrap-reference.md) → Forms in production, Wizards & multi-step forms.
 
 ### When custom CSS is justified
 
-Treat custom CSS as rung 4 and the developer's decision: propose it, name what it buys, and take it
-unprompted only under the exception that follows. 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).
+Exhaust the component, utility, and extension rungs before proposing a custom rule. Name the unmet
+requirement and the smallest rule that would satisfy it. A desire for a signature does not waive the
+styling ladder.
 
-Take an authored rule without asking only where an instrument in
-[inspection.md](references/inspection.md) reports the vendor cascade failing a stated bar, the rule
-cites that reading, the rule restores the bar and does nothing else, and the rule is written over
-tokens. [inspection.md](references/inspection.md) → When an authored rule is already earned states
-the whole condition. Treat anything wider as a proposal.
+Wait for developer authorization. [inspection.md](references/inspection.md) → When an authored rule
+is already earned owns the one exception and every condition that opens it; read that section rather
+than judging a shorter copy here. An unavailable Sass build is not permission to silently invent a
+second CSS system.
 
-When the developer authorizes it, or that exception opens:
+When authorized, or when that exception opens:
 
-- 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.
+- Name the rule in Bootstrap vocabulary and document the gap.
+- Use `var(--bs-…)` for paint and declared scales for type, spacing, radius, and elevation.
+- Use logical properties so RTL survives.
+- Keep the rule in the project's stylesheet, with the smallest scope and no utility duplication.
 
 ---
 
 ## Accessibility baseline
 
-- Give the page a skip link to main, landmarks, and `h1` → `h2` heading order.
-- Name every icon-only control with `aria-label`, and keep every target ≥ 24×24px.
-- Mark active nav and tabs with `aria-current` / `aria-selected` — exactly one `aria-current` per selection.
-- Wire every disclosure with `aria-expanded` and `aria-controls`.
-- Wire help and errors with `aria-describedby`, and mark a failed field `aria-invalid`.
-- Match the live region to the message: `role="status"` for an async status mark, `role="alert"` for an alert-styled notice.
-- Associate a form with the name its host already gives the request (`aria-labelledby`) rather than repeating the prompt as its own label.
-- Keep focus visible: keep the Bootstrap rings, use the `.focus-ring` helper for custom elements, and never write `outline: none`.
-- Keep focus clear of sticky chrome (`scroll-margin-top`), and move focus deliberately on SPA route change, failed submit, and row delete.
-- Never carry meaning by color alone, and verify the contrast.
-- Give every drag interaction a non-drag alternative.
-- Give every dialog `aria-labelledby`, let the platform or Bootstrap trap and restore focus rather than scripting it, and dispose Bootstrap instances in an SPA on unmount.
-
-Take WCAG 2.2 deltas, APG pattern contracts, reduced motion, and SPA focus recipes from
-[bootstrap-reference.md](references/bootstrap-reference.md) → Accessibility.
+- Give the page a skip link, landmarks, and ordered headings; visual size does not dictate heading level.
+- Name icon-only controls and hold every target to the floor in [bootstrap-reference.md](references/bootstrap-reference.md) → WCAG 2.2 requirements for app UI. Preserve visible labels within accessible names.
+- Use `aria-current` for the current navigation item, `aria-selected` for selectable tabs, and native checked state for checkboxes/radios. Do not apply one selection attribute to every widget.
+- Wire disclosures with `aria-expanded` and `aria-controls`; wire help/errors with `aria-describedby` and invalid fields with `aria-invalid`.
+- Match announcements to urgency: polite status for routine async results, alerts for urgent failures. Do not infer urgency solely from an alert's visual styling.
+- Associate a form with its existing visible name through `aria-labelledby` where useful; keep each field's own visible label.
+- Preserve visible focus, clear of sticky chrome. Manage focus on SPA route change, failed submit, and row deletion; use the platform or existing dialog implementation for containment and restoration.
+- Never encode meaning by color alone. Measure contrast, including state cues, against actual surfaces.
+- Preserve content and operation under enlarged text and narrow reflow; do not hide essential content to pass a viewport check.
+- Give drag interactions a non-drag alternative. Respect reduced motion. Give images alternatives appropriate to their role.
+- Dispose Bootstrap instances on SPA unmount, or use the framework-native wrapper's lifecycle.
+
+Take WCAG 2.2 details, APG contracts, and focus recipes from
+[bootstrap-reference.md](references/bootstrap-reference.md) → Accessibility. A passing subset of
+these checks is not a claim of full accessibility conformance.
 
 ---
 
@@ -227,24 +245,33 @@ Take WCAG 2.2 deltas, APG pattern contracts, reduced motion, and SPA focus recip
 
 ```
 Progress:
-- [ ] Every check that follows, inspection.md instrument or not, reports its population, names the negative control that failed, and states its coverage; a check that can name no negative control is listed as open instead
-- [ ] Project code law followed; no wrong-stack assumptions
-- [ ] Subject, audience, single job stated
-- [ ] Design plan critiqued against the AI defaults: palette, type, layout, one signature
-- [ ] Shell from components.md, utilities from utilities.md; no invented class
-- [ ] Input affordances from inputs.md; every state in its fixed set drawn, per field
-- [ ] 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
-- [ ] Every state per data surface: ideal / empty / loading / partial / error
-- [ ] 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 controls named
-- [ ] Reduced motion respected; every drag has a non-drag path
-- [ ] Forms: labels visible, blur validation, error summary + inline, submit enabled
-- [ ] 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 every viewport and every theme the surface declares + an accessibility snapshot
+- [ ] Project code law, installed stack, existing identity, and scope held
+- [ ] Subject, audience, single job, primary action, and real/fixture content identified
+- [ ] Feature hierarchy settled before shell/detail; plan specific to the brief
+- [ ] Color families and surface ownership, type, spacing/width, radius, elevation, and signature declared or reused
+- [ ] Typeface, primary color, radius family, and copy register set once and held; arrangement read in grayscale before hue
+- [ ] Type sizes in `rem` from the scale or its generated steps; no `em` sizes, nested `.small`, or off-scale spacing
+- [ ] Components and utilities resolved in the shipped build; input affordances and states taken from their references
+- [ ] Styling ladder held; no `style` attribute, no component-scoped `<style>` block, no unearned utility duplication; a standalone HTML deliverable carries its one project stylesheet in `<head>`
+- [ ] Tokens mapped through semantics to components; literals confined to declared primitives
+- [ ] Ordinary/subtle content inherits; solid exceptions own their pair; no fixed leaf color conceals a mode failure
+- [ ] Every text/background pair is adaptive-on-adaptive or fixed-on-fixed; fixed fills carry `text-bg-*`, their component's foreground, or a `data-bs-theme` scope with `text-body` on the same element; no `bg-light`, `bg-white`, or `text-dark` on adaptive surfaces
+- [ ] Deprecated classes cleared on their deprecation: `text-muted`, `navbar-light`, `navbar-dark`, `dropdown-menu-dark`, `btn-close-white`, `carousel-dark`
+- [ ] Secondary tier is `text-body-secondary` or a declared opaque token; no opacity or unreadable tertiary tone; secondary text on colored surfaces measured rather than assumed
+- [ ] Every declared mode transition, supported nested scopes, and overlay mounts tested without rebuilding the UI
+- [ ] Primary action clear; supporting content readable; destructive rank and friction both correct
+- [ ] Group spacing unambiguous; widths content-led; type/baseline/line length suitable
+- [ ] All data states built; first-use and filtered-empty distinct; errors recoverable; no invented progress
+- [ ] Images bounded and legible; depth serves layering; accents, tints, and shadows each earn their place; no needless accessories
+- [ ] Contrast measured in every declared theme and reached state against the bars in § Surfaces, color, contrast
+- [ ] Keyboard, labels, announcements, targets, reduced motion, and non-drag paths checked
+- [ ] Forms retain visible labels, blur/submit validation, and summary + inline errors
+- [ ] Responsive contract recorded; primary task works at 320/390 CSS px before wide-screen enhancement
+- [ ] Used breakpoint boundaries, actual container widths, long content, enlarged text, and short-height overlays checked
+- [ ] Essential fields/actions remain reachable; local data scrolling is named, keyboard-operable, and not used to mask page overflow
+- [ ] Navigation open/close/resize and selection/filter preservation tested; RTL covered when claimed
+- [ ] Runtime behavior and SPA lifecycle tested where changed
+- [ ] Rendered review names criteria and captures at declared widths/themes/states, plus accessibility snapshot
+- [ ] Mechanical results name population, negative controls, and coverage; absent features marked not applicable with reason
+- [ ] Untested, unsupported, or failed verification listed as open; no source-only visual pass or full-conformance claim
 ```