@orkestrel/scaffold 0.0.35 → 0.0.37

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

@@ -112,6 +112,8 @@ Variants: `.accordion-flush` (edge-to-edge, no outer borders); omit `data-bs-par
 
 `role="alert"` announces immediately when the element is injected into the DOM — right for errors and warnings. For calm status messages injected dynamically, prefer a polite live region (`role="status"`). Anything that _looks_ like an alert carries the alert role: styling and semantics disagree the moment a notice wears `.alert` chrome with no role, and an accessibility snapshot is what catches it. When to use alert vs toast vs banner: [bootstrap-reference.md](bootstrap-reference.md) → Feedback discipline.
 
+An alert is a subtle fill — apply the subtle-fill degradation rule to everything inside it ([SKILL.md](../SKILL.md) → Surfaces, color, contrast).
+
 ### Badge
 
 ```html
@@ -186,6 +188,8 @@ The current page is `aria-current="page"` and not a link. Use breadcrumbs only f
 
 Icon-only buttons need `aria-label` and a ≥24×24 px target (WCAG 2.2) — `btn-sm` icon clusters in toolbars are the common violation; pad rather than shrink.
 
+Choose the variant by contrast rather than by taste ([SKILL.md](../SKILL.md) → Hierarchy & actions).
+
 ### Button Group
 
 ```html
@@ -400,6 +404,29 @@ Multiple targets: give each panel `.multi-collapse` and point separate triggers
 
 ### Modal
 
+**Build a blocking dialog on the native `<dialog>`.** `showModal()` brings focus containment, Esc, an inert background, and top-layer stacking from the platform — nothing to construct, nothing to dispose when the view unmounts, and no JS instance for a virtual-DOM framework to fight with over the same nodes. Leave the element itself unpainted and put Bootstrap chrome inside it:
+
+```html
+<dialog class="p-0 border-0 bg-transparent" role="alertdialog" aria-labelledby="confirmHeading">
+	<div class="card shadow">
+		<div class="card-header">
+			<h2 id="confirmHeading" class="h5 mb-0">Delete invoice</h2>
+		</div>
+		<div class="card-body">
+			<p class="card-text mb-0">This permanently deletes INV-1042.</p>
+		</div>
+		<div class="card-footer d-flex flex-wrap justify-content-end gap-2">
+			<button type="button" class="btn btn-secondary">Keep</button>
+			<button type="button" class="btn btn-danger">Delete invoice</button>
+		</div>
+	</div>
+</dialog>
+```
+
+`role="alertdialog"` for a destructive confirm, `role="dialog"` otherwise; `aria-labelledby` points at the heading. The element's own `close` event is where the host clears the state that opened it, so Esc and the buttons all close by one path. The scrim is the UA's `::backdrop`, which no Bootstrap class touches — restyling it is a rung-4 decision.
+
+Bootstrap's `.modal` is the answer when the project already drives its dialogs through Bootstrap's JS:
+
 ```html
 <div
 	class="modal fade"
@@ -467,7 +494,7 @@ Bootstrap's modal enforces focus, adds `role="dialog"`/`aria-modal="true"`, clos
 			</ul>
 			<form class="d-flex" role="search">
 				<input class="form-control me-2" type="search" placeholder="Search" aria-label="Search" />
-				<button class="btn btn-outline-success" type="submit">Search</button>
+				<button class="btn btn-success" type="submit">Search</button>
 			</form>
 		</div>
 	</div>
@@ -941,7 +968,7 @@ The textless mark that survives both themes — dots, ticks, rings, pulses — i
 <span class="bi bi-circle fs-6 lh-1 text-body-secondary" role="img" aria-label="Not started"></span>
 ```
 
-- **Color from the emphasis tokens.** `text-*-emphasis` is the mode-adaptive tier built for marks on subtle surfaces; the plain `text-*` colors are tuned for light and thin out in dark. Measure every mark at **≥ 3:1** against the surface it sits on, **in both themes**, against the compiled cascade — a skin's token values are its own.
+- **Color from the emphasis tokens.** `text-*-emphasis` is the mode-adaptive tier built for marks on subtle surfaces; the plain `text-*` colors are tuned for light and thin out in dark. On a filled surface — `.active`, `.bg-primary`, `text-bg-*` — drop the tone class instead and let the fill's contrast color take the glyph ([Selection fills](#selection-fills)). Measure every mark at **≥ 3:1** against the surface it sits on, **in both themes**, against the compiled cascade — a skin's token values are its own.
 - **Filled and hollow say different things** — done vs pending, live vs idle — so pair glyphs that share one advance width (a filled/hollow pair from the same icon family). Mixed widths make a column of marks jitter row to row.
 - **Size with `fs-*` _and_ `lh-1`.** A glyph inherits the row's line-height, so an `fs-*` bump without `lh-1` grows the line box and pushes the row taller than its neighbors.
 - Give the mark an accessible name (`role="img"` + `aria-label`, or a `.visually-hidden` word next to an `aria-hidden` glyph) — a mark whose only meaning is its color and shape is color-only status.
@@ -961,7 +988,7 @@ The textless mark that survives both themes — dots, ticks, rings, pulses — i
 | Long documentation in-product                  | `accordion` or scrollable `modal`                                          | One infinite tinted card stack                 |
 | Dense data                                     | `table` + `table-responsive` (+ `table-sm` when appropriate)               | Non-semantic grids of text                     |
 | Choosing a form value                          | `form-select` (or native input)                                            | A `dropdown` menu posing as an input           |
-| Confirmations / focused tasks                  | `modal` with header, body, footer actions                                  | Nested modals                                  |
+| Confirmations / focused tasks                  | native `<dialog>` with header, body, footer actions                        | Nested modals                                  |
 | Secondary filters on small screens             | `offcanvas`                                                                | Permanent wide sidebars that crush content     |
 | Transient success feedback                     | `toast`                                                                    | `alert()`; toasts for errors                   |
 | Loading a known layout                         | `placeholder` skeleton                                                     | Layout-collapsing centered spinner             |
@@ -977,7 +1004,7 @@ The textless mark that survives both themes — dots, ticks, rings, pulses — i
 
 A selected row, pill, or filter chip repaints everything inside it — marks included. Two traps, both invisible until the selected state is captured in both themes:
 
-- **A mark on an active fill of the same family disappears.** `.active` on a `list-group-item`, `nav-pill`, or `page-item` sets the item's own color, and a `text-bg-primary`-family mark inside it inherits or loses to that fill — the mark is there in the markup and gone on screen. `text-body-emphasis` (or an outline glyph that keeps its own token) survives the fill; verify by capturing the selected row, not by reading the class list.
+- **A mark on an active fill of the same family disappears.** `.active` on a `list-group-item`, `nav-pill`, or `page-item` sets the item's own color, and a `text-bg-primary`-family mark inside it inherits or loses to that fill — present in the markup, gone on screen. Carry no tone class inside the fill ([SKILL.md](../SKILL.md) → Surfaces, color, contrast). Verify by capturing the selected row, not by reading the class list.
 - **`btn-check` filter labels invert in dark.** A `btn-outline-secondary` label reads as "chosen" in light and as "muted" in dark, because the checked fill and the surface swap relative weight. Give chosen filters an accent variant (a real theme color) rather than the neutral outline, so "chosen" reads the same way in both modes.
 
 Exactly one item in a selection carries `aria-current` — the visual fill and the announced state must be the same item.

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

@@ -4,56 +4,126 @@
 > process, and copy guidance — use when setting visual direction.
 > Operate layer: [SKILL.md](../SKILL.md).
 
-Approach this as the design lead at a small studio known for giving every client a visual identity that could not be mistaken for anyone else's. This client has already rejected proposals that felt templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take one real aesthetic risk you can justify.
+Give the surface a visual identity that could not be mistaken for anyone else's, and reject any
+direction that reads as templated. Make deliberate, opinionated choices about palette, typography,
+and layout that are specific to this brief, and take one real aesthetic risk you can justify.
 
 ## Ground it in the subject
 
-If the brief does not pin down what the product or subject is, pin it yourself before designing: name one concrete subject, its audience, and the page's single job, and state your choice. If there's any information in your memory about the human's preferences, context about what they're building, or designs you've made before — use that as a hint. The subject's own world, its materials, instruments, artifacts, and vernacular, is where distinctive choices come from. Build with the brief's real content and subject matter throughout.
+Pin the subject before designing whenever the brief leaves it open: name one concrete subject, its
+audience, and the page's single job, and state the choice. Use what you know of the user's
+preferences, of what they are building, and of designs you have made for them before as hints, never
+as templates. Draw the distinctive choices from the subject's own world — its materials,
+instruments, artifacts, and vernacular. Build with the brief's real content and subject matter
+throughout.
 
 ## Design principles
 
-For web designs, the hero is a thesis. Open with the most characteristic thing in the subject's world, in whatever form makes sense for it: a headline, an image, an animation, a live demo, an interactive moment. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the template answer — only use it if that's truly the best option.
+Open a web design's hero with the subject's thesis — the one claim the page makes — carried by the
+most characteristic thing in the subject's world, in whatever form suits it: a headline, an image,
+an animation, a live demo, an interactive moment. Choose that opening deliberately — a big number
+with a small label, supporting stats, and a gradient accent is the template answer, so take it only
+where it is genuinely the best option.
 
-Typography carries the personality of the page. Pair the display and body faces deliberately, not the same families you would reach for on any other project, and set a clear type scale with intentional weights, widths, and spacing. Make the type treatment itself a memorable part of the design, not a neutral delivery vehicle for the content.
+Set the typography as a decision rather than a default. Pair the display and body faces
+deliberately, and not the families you would reach for on any other project. Set a clear type scale
+with intentional weights, widths, and spacing. Make the type treatment one of the things the design
+is remembered by.
 
-Structure is information. Structural devices — numbering, eyebrows, dividers, labels — should encode something true about the content, not decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence, like a real process or a typed timeline where order carries information the reader needs. Question whether choices like numbered markers actually make sense before incorporating them.
+Make every structural device — numbering, eyebrows, dividers, labels — encode something true about
+the content rather than decorate it. Use numbered markers (01 / 02 / 03) only where the content is
+a sequence: a real process, or a typed timeline whose order carries information the reader needs.
+Before adding a device, check that it encodes something the reader needs.
 
-Leverage motion deliberately. Think about where and whether animation can serve the subject: a page-load sequence, a scroll-triggered reveal, hover micro-interactions, ambient atmosphere. An orchestrated moment usually lands harder than scattered effects; choose what the direction calls for. Sometimes less is more — extra animation is one of the fastest ways to make a design feel AI-generated.
+Decide where and whether animation serves the subject: a page-load sequence, a scroll-triggered
+reveal, hover micro-interactions, ambient atmosphere. Prefer one orchestrated moment to scattered
+effects, and follow the direction where it calls for something else. Cut animation the direction
+does not need — extra animation is one of the fastest ways to make a design read as AI-generated.
 
-Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.
+Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions
+need precision in spacing, type, and detail.
 
-Consider written content carefully. A design brief often contains no real content, and it's up to you to come up with copy. Copy can make a design feel as templated as the layout itself. See the writing section below.
+Write the copy yourself when the brief supplies none, and treat it as design material: templated
+copy makes a surface read as templated as a templated layout does. Follow the writing rules below.
 
 ## Where the signature lives in product UI
 
-The same craft applies to dense, authenticated tools — but the signature moves. In an admin screen or dashboard, the data is the content and must stay quiet, legible, and fast to scan; spending the aesthetic risk on the table itself taxes every user on every visit. Put the point of view in the chrome instead: the navigation and header treatment, the type pairing, the empty states, the way status and density are handled. A distinctive product UI is one whose _frame_ could not be mistaken for another product while its data surfaces stay disciplined and conventional enough to disappear into use.
+Apply the same craft to dense, authenticated tools, and move the signature. In an admin screen or
+dashboard the data is the content: keep it quiet, legible, and fast to scan, and never spend the
+aesthetic risk on the table itself, which adds scan time for every user on every visit. Put the
+point of view in the chrome — the navigation and header treatment, the type pairing, the empty
+states, the handling of status and density. Make the frame impossible to mistake for another
+product's, and keep the data surfaces disciplined and conventional enough to read without effort.
 
 ## Process: brainstorm, explore, plan, critique, build, critique again
 
-For calibration: AI-generated design right now clusters around three looks: (1) a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns. All three are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. Just like a hired human designer, there's a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.
-
-Work in two passes. First, brainstorm a short design plan based on the human's design brief: create a compact token system with color, type, layout, and signature. Color: describe the palette as 4–6 named hex values. Type: the typefaces for 2+ roles (a characterful display face used with restraint, a complementary body face, and a utility face for captions or data if needed). Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Signature: the single unique element this page will be remembered by, embodying the brief in an appropriate way.
-
-Then review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, and say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan exactly and deriving every color and type decision from it.
-
-When writing the code, be careful structuring your CSS selector specificities. It's easy to generate classes that cancel each other out (especially a type-based selector like `.section` against an element-based selector like `.cta`), and paddings/margins between sections are where it happens most.
-
-Do a lot of this planning and iteration in your thinking, and only show ideas to the user when you have higher confidence they'll delight.
+Calibrate against the three looks AI-generated design currently clusters around: (1) a warm cream
+background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a
+near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style
+layout with hairline rules, zero border-radius, and dense newspaper-like columns. All three are
+legitimate for some briefs; they are defaults rather than choices, and they appear regardless of
+subject. Follow the brief exactly where it pins a visual direction — the brief's own words always
+win, including when they ask for one of these looks. Where the brief leaves an axis free, spend that
+freedom somewhere other than these defaults. Balance the moves you have already proven against
+experimenting where the brief invites it.
+
+Work in two passes. First, brainstorm a short design plan from the brief: a compact token system
+with color, type, layout, and signature. Color: describe the palette as 4–6 named hex values. Type:
+name the typefaces for 2+ roles — a characterful display face used with restraint, a complementary
+body face, and a utility face for captions or data where one is needed. Layout: state a layout
+concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare.
+Signature: name the single element this page will be remembered by, embodying the brief.
+
+Then review that plan against the brief before building. Where a part of it reads like the generic
+default you would produce for any similar page — work through a similar prompt and see whether you
+arrive somewhere similar — revise that part, and say what you changed and why. Start writing code
+only once the plan is specific to this brief, then follow the revised plan exactly and derive every
+color and type decision from it.
+
+Structure your CSS selector specificities deliberately when writing the code. Classes cancel each
+other out easily, especially a type-based selector like `.section` against an element-based selector
+like `.cta`, and the padding and margin between sections is where it happens most.
+
+Do this planning and iteration in your thinking. Show the user a direction only once it satisfies
+the brief and the quality floor below.
 
 ## Restraint and self-critique
 
-Spend your boldness in one place. Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Not taking a risk can be a risk itself! Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected. Critique your own work as you build, taking screenshots if your environment supports it — a picture is worth 1000 tokens, and it is the only thing that can tell you whether the design you wrote is the design that rendered. Look at both themes and both the wide and the narrow viewport; a treatment that only exists in the markup is not a treatment yet. Consider Chanel's advice: before leaving the house, look in the mirror and remove one accessory. Human creators have memory and always try to do something new; if you have a place to jot down notes about what you've tried, it will help future passes.
-
-## More on writing in design
-
-Words appear in a design for one reason: to make it easier to understand, and therefore easier to use. They are design material, not decoration. Bring the same intentionality to copy that you bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.
-
-Write from the end user's side of the screen. Name things by what people control and recognize, never by how the system is built. A person manages notifications, not webhook config. Describe what something does in plain terms rather than selling it. Being specific is always better than being clever.
-
-Use active voice as default. A control should say exactly what happens when it's used: "Save changes," not "Submit." An action keeps the same name through the whole flow, so the button that says "Publish" produces a toast that says "Published." The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.
-
-Treat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.
-
-Keep the register conversational and tuned: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each element do exactly one job. A label labels, an example demonstrates, and nothing quietly does double duty.
-
-Brevity on a control is not the same as vagueness. Where the surrounding context already names the object, the visible label can be a single word and stay unambiguous — the specific phrase then lives in the control's accessible name, so nothing is lost for someone who arrives without the context. The same discipline governs the visual vocabulary: a glyph is a word, and a word means one thing. Once a mark stands for "finished" it cannot also stand for "selected" three panels over, or the reader has to relearn the language on every screen.
+Spend the boldness in one place. Let the signature element be the one memorable thing, keep
+everything around it quiet and disciplined, and cut any decoration that does not serve the brief —
+decorative emoji as UI, pill soup, glow effects, and gradient-on-everything are the usual instances
+of decoration with no reason in the subject. Treat a surface with no deliberate risk as failing the
+distinctiveness mandate. Meet the quality floor without announcing it: responsive down to mobile,
+visible keyboard focus, reduced motion respected. Critique your own work as you build, and take
+screenshots where the environment supports it. Read both themes and both the wide and the narrow
+viewport from those captures, not the markup. Before shipping, remove one accessory: cut the
+least-necessary decorative element, and restore it only where the surface demonstrably loses
+information without it. Where notes persist across passes, record what you tried so the next pass
+reads it.
+
+## Writing in design
+
+Keep a word only where it makes the design easier to understand, and therefore easier to use. Bring
+the same intentionality to copy as to spacing and color. Before writing anything, decide what the
+design needs to say, and how to say it so the person can navigate the experience.
+
+Write from the end user's side of the screen. Name things by what people control and recognize,
+never by how the system is built: a person manages notifications, not webhook config. Describe what
+something does in plain terms rather than selling it, and choose the specific word over the clever
+one.
+
+Use the active voice by default. Make a control say exactly what happens when it is used: "Save
+changes," not "Submit." Keep an action's name through the whole flow, so the button that says
+"Publish" produces a toast that says "Published." Hold one vocabulary across every screen.
+
+Give failure and emptiness direction rather than mood. State what went wrong and how to fix it, in
+the interface's voice rather than a person's, without apology and without vagueness about what
+happened. Name the action that fills an empty screen.
+
+Keep the register conversational and tuned: plain verbs, sentence case, no filler, tone matched to
+the brand and the audience. Give each element exactly one job: a label labels, an example
+demonstrates, and nothing does double duty.
+
+Keep a short control label unambiguous. Where the surrounding context already names the object, make
+the visible label a single word and carry the specific phrase in the control's accessible name, so
+nothing is lost for someone who arrives without that context.

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

@@ -301,7 +301,7 @@ Helpers are single-purpose classes that sit alongside utilities.
 
 - **Spacing scale:** prefer `gap-*` on flex/grid parents over scattering `m-*` on every child — the parent owns rhythm, children stay reorderable. Use `p-3` / `p-4` for panel padding; reserve `p-5` for sparse marketing-like empty states.
 - **Body surfaces:** `bg-body`, `bg-body-secondary`, `bg-body-tertiary` track `data-bs-theme` — raw `bg-white` / `bg-light` freeze the surface in light mode.
-- **Text hierarchy:** `text-body` for content, `text-body-secondary` for meta, `text-*-emphasis` when a status must stay readable on subtle backgrounds. `text-body-tertiary` is the decoration tier — it misses the 4.5:1 bar for information-bearing small text, so anything a user must read is `text-body-secondary` or better.
+- **Text hierarchy:** `text-body` for content, `text-body-secondary` for meta, `text-*-emphasis` for any status a reader acts on. The plain `text-success` / `text-danger` / `text-warning` colors and `text-body-tertiary` are the decoration tier ([SKILL.md](../SKILL.md) → Surfaces, color, contrast).
 - **Opacity traps:** `text-white-50` / `text-black-50` often fail contrast — prefer `text-opacity-75` on a known solid, or `text-body-secondary`. Every one of these pairings is measured against the shipped cascade in both themes; a skin retunes the same token names.
 - **Flex floors:** a flex column gives its items an automatic minimum size, and `text-truncate` removes it. Titles and marks that must keep their height carry `flex-shrink-0`; only the growing sibling absorbs the slack.
 - **Flex toolbars:** `d-flex align-items-center gap-2 flex-wrap` (or `flex-nowrap overflow-auto` for dense bars). Equal-height siblings: `align-items-stretch` + `h-100` on cards.

package/dist/host/agents/skills/orkestrel-human-journey/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: orkestrel-human-journey
+description: Prove a browser application the way a person uses it — real keystrokes, clicks, and Tab/Enter against only what is visible and reachable — and generate the capture portfolio from those same journeys. Use when accepting a UI build, proving an application end to end, deciding whether a surface is reachable by keyboard alone, proving what a screen refuses as well as what it does, auditing whether the interface speaks the user's vocabulary rather than the engine's, producing the screenshots a design review judges, or whenever the only evidence a screen works is a test that drove it through JavaScript instead of through the interface.
+---
+
+# Prove an application through human journeys
+
+## Load authority
+
+Read the current files in this order:
+
+1. `AGENTS.md`.
+2. `.claude/rules/tests.md` for test law, real implementations, and shared test infrastructure;
+   `.claude/rules/browser.md` for browser and Vue usage; `.claude/rules/application.md` for app
+   composition and entries; `.claude/rules/documentation.md` for parity. Those rules are the
+   contract; this skill is the workflow.
+3. [layer.md](references/layer.md) before building, extending, or debugging the journey layer.
+4. [captures.md](references/captures.md) before registering a state or placing a capture.
+5. `guides/README.md`, the governing guide for the surface, and `ROADMAP.md` when present.
+6. The `*/types.ts` of every environment the journeys drive, plus the application's root component,
+   route entry, and store contract.
+
+## Apply the journey laws
+
+1. **Drive only what a person can see and reach.** Target every control by its ARIA role and its
+   accessible name as rendered. Never reach into a component instance, a store, a transport, a
+   copied credential, or a test-only hook to make a step succeed. Report a step that cannot be
+   performed through the interface as a finding about the interface.
+2. **Assert what is seen.** Quote the rendered text a person reads, which is `innerText` — a label
+   under `text-uppercase` asserts as `TRACE` where the source says `Trace`. Never let a state read
+   replace a perception assertion; it may only corroborate one, and `.claude/rules/tests.md` fixes
+   which state a test may read at all.
+3. **Assert what the interface withholds.** Assert every refusal through the resolver's exact
+   failure voice, and distinguish an absent control from a present but humanly unreachable one.
+4. **Keep transport and persistence proofs in their own declared block,** never inside a journey.
+   Assert every live or asynchronous fact by convergence — poll until it contains or equals — never
+   by an identity read of one frame.
+5. **Generate the portfolio from the acceptance journeys.** Place each registered state inside the
+   journey that reaches it, and never register a state no journey reaches.
+6. **Commit a value through an act a person performs:** Enter, Tab away, or a named button. Report a
+   surface that commits on a timer, on an unpredictable event, or only after work the person cannot
+   observe as a surface finding, and never work around it in the layer.
+7. **Type only what a person would.** Journeys carry trusted input; adversarial payloads belong to
+   the transport family and the parser suites.
+
+## Build or verify the journey layer
+
+- Build the layer as shared browser test infrastructure under `.claude/rules/tests.md`: it lives in
+  the workspace's browser test setup module, exports every helper from there, and adds a journey
+  helper only where `@orkestrel/test` publishes none. Never declare a resolver inside a test file.
+- Give the layer every capability [layer.md](references/layer.md) fixes: the role-scoped resolver
+  and its distinct failure voices, region-scoped resolution, the input and traversal verbs, the
+  perception readers, and the capture hook.
+- Drive every step through the browser provider's user-event API, and never dispatch a constructed
+  event ([layer.md](references/layer.md) → What it drives).
+- Re-verify the layer against what the application renders now whenever markup changes
+  ([layer.md](references/layer.md) → Role vocabulary).
+
+## Derive journeys from intents
+
+Write one journey per user intent, named for what the person achieves rather than for the
+components it passes through. Place them in the browser environment's `integration.test.ts`, whose
+placement and scope `.claude/rules/tests.md` fixes.
+
+- Enter through the real entry: mount the shipped root component with a real store and the route a
+  person lands on, and let the application load itself.
+- Reach each surface's own controls through forward Tab traversal in at least one journey.
+- Type keystroke by keystroke where the keystrokes are the subject; fill in one operation where the
+  text is only a payload the person pastes.
+- Poll every fact the application produces asynchronously until it converges. Never assert one from
+  a single read after the action. A poll's predicate must be able to go false-to-true after the
+  action it observes; a predicate already true when the poll starts binds nothing.
+- Assert the state the flow must reach, never the transient path taken to it. A criterion that bans
+  a harmless transient over-refuses and breaks on the next honest implementation.
+- Assert the negative beside the positive whenever a value replaces another: the new sentence is
+  present **and** the old one is gone.
+- After a confirmed destructive action, assert through trusted input that focus landed on a visible,
+  announced location.
+- Assert the whole page's perception never matches the vocabulary the product does not speak —
+  engine, schema, and implementation words the interface is supposed to translate.
+- Report a bare accessible name that answers for two reachable elements on one screen as a surface
+  finding, and target through role or region until the surface is fixed.
+
+## Prove the refusals
+
+- Give every surface a refusal family: the controls a person must not reach in the state the
+  journey has put the surface in.
+- Assert the exact failure voice the case means. Never write an assertion that accepts either of
+  two voices.
+- Cover the restrictions the interface imposes on itself: a collapsed panel's field, a verb
+  belonging to another kind of object, a control disabled until its precondition lands.
+- When a refusal changes voice after a markup change, read it as a role or reachability change
+  before treating the element as missing
+  ([layer.md](references/layer.md) → Role vocabulary).
+
+## Declare the transport family
+
+- Name the block for what it proves — persistence, restart, storage failure.
+- Drive it through the application's real session and store contracts. Build a store that stalls a
+  read, fails a fixed number of reads, or fails a write as an inert configurable implementation of
+  the published interface, under the real-implementation law in `AGENTS.md`.
+- Prove the visible half in a journey: the failure sentence a person reads, and the retry control
+  that clears it.
+- Assert restart by starting a second session over the same store and polling the restored value.
+
+## Generate the portfolio
+
+Follow [captures.md](references/captures.md) for the state registry and its placement rules, the
+theme-and-viewport variant matrix, the always-on filename proof, the capture-run membership proof,
+and how a state that exists only during an activation is captured.
+
+When a capture and a green suite disagree, the capture is the evidence and the fixture is the
+defect.
+
+Route review of the portfolio to the `orkestrel-polish-surface` campaign. Do not judge it here.
+
+## Accept
+
+Completion requires all of:
+
+- every in-scope user intent reaching its outcome through the interface, with no step that reaches
+  past it;
+- keyboard-only reachability proven on every surface the journeys cover;
+- a refusal family per surface, each asserting one exact failure voice;
+- the transport family declared separately, driven through real implementations, and convergent;
+- the registry-times-variants filename proof and the state-placement proof green in an ordinary run;
+- one capture run per variant writing every registered file, each read back non-empty;
+- perception assertions quoting rendered text, and the vocabulary sweep green on the whole page;
+- the repository gates green, under the independent-verification law in `.agents/orchestration.md`.
+
+Report each journey by the intent it proves, the refusals it establishes, the states it placed, and
+every surface finding the layer's refusals exposed.

package/dist/host/agents/skills/orkestrel-human-journey/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Prove Human Journeys'
+  short_description: 'Prove an application through the interface a person uses'
+  default_prompt: 'Use $orkestrel-human-journey to prove this application through the interface a person uses, and generate the capture portfolio from those journeys.'

package/dist/host/agents/skills/orkestrel-human-journey/references/captures.md

@@ -0,0 +1,74 @@
+# The capture portfolio
+
+Take every screenshot from an acceptance journey, at the moment that journey is in the state the
+picture names. Never add a test whose only purpose is a screenshot, and never stage a state for the
+camera that a journey did not reach through the interface.
+
+## The capture hook
+
+```ts
+capture(state: string): Promise<string | undefined>
+```
+
+- Return `undefined` and do nothing when the capture flag is unset, so an ordinary run neither
+  resizes the viewport nor writes a file.
+- Read one variant value that names the theme and the viewport together, and refuse a value that
+  names no registered variant.
+- Apply that variant's theme and viewport inside the hook, so the run's single variant value is the
+  only source of both.
+- Write one file named `<state>--<variant>.png` under the workspace's git-ignored `tmp/` tree, and
+  return the path it wrote.
+
+## The registry
+
+Declare two frozen lists in the journey file: the state names, and the variants.
+
+- Name a state for its surface and its condition — `answer-partial`, `start-storage-failure`,
+  `case-delete-confirmation`.
+- Register the states the design work actually needs, and place every registered one. Never leave a
+  registered state unplaced.
+- Wrap the hook in a placement helper that refuses an unregistered state name, refuses a second
+  placement of the same state, records each written path, and refuses a filename written twice.
+- Place a state from inside the journey that reaches it, immediately after the assertion that
+  proves the surface is in that state.
+
+## Variants
+
+- Name a variant as one value carrying both the theme and the viewport, such as `dark-390`. Never
+  split them into two selectors: a split lets a run write a filename describing a combination it
+  did not render.
+- Render one variant per run, and produce the portfolio — the registry times the variants — by
+  repeating the run once per variant.
+
+## The two proofs
+
+| Proof                | Runs                        | Asserts                                                                                        |
+| -------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
+| Filename expansion   | Always                      | The registry's length and uniqueness, the variant count, and that the expansion is unique      |
+| Portfolio membership | Always; disk under the flag | Every registered state was placed; under the flag, the files on disk are exactly the expansion |
+
+- Keep the filename proof always-on, so a registry edit that introduces a duplicate or a collision
+  fails the ordinary run.
+- Assert placement equality as set equality against the registry, in every run. Never assert a
+  count: a count passes while one state is placed twice and another never.
+- Under the capture flag, assert the written filenames equal the registry expanded for the run's
+  variant, then read each file back and require non-empty contents. Never treat the path a
+  screenshot call returned as proof that a file exists.
+- Put the membership proof last in the file, after every journey that feeds its tally.
+
+## Transient states
+
+Capture a state that exists only while an activation is in flight from inside that activation,
+never after the click returns.
+
+- Attach a one-shot listener to the resolved control, place the capture from inside it, then click
+  through the normal verb and await the promise the listener recorded.
+- Fail the step when the listener never ran.
+
+## Hygiene
+
+- Keep the portfolio out of version control.
+- Regenerate the whole matrix from the journeys after any surface change. Never judge a round
+  against a portfolio that is part old and part new.
+- Route review of the portfolio to the `orkestrel-polish-surface` campaign, which owns preflight,
+  verdicts, and reconciliation. This reference owns only how the journeys generate it.

package/dist/host/agents/skills/orkestrel-human-journey/references/layer.md

@@ -0,0 +1,131 @@
+# The journey layer
+
+Build every capability here before writing the first journey, and route every journey step through
+it. Treat a journey that works around a missing capability as a layer defect.
+
+Implement the signatures below as a contract in the workspace's browser test setup module; never
+copy them as source. Name each helper for the human act it performs.
+
+## What it drives
+
+- Drive the real browser through the installed Vitest browser provider. Import its `page` locators
+  and `userEvent` from `vitest/browser`; the `@vitest/browser/context` specifier is deprecated and
+  is not the import a new layer uses.
+- Use the provider verbs for input: `click`, `keyboard`, `tab`, `type`, `clear`, `fill`, and
+  `selectOptions`. Use `page.viewport` and `page.screenshot` for captures, and the runner's file
+  command to read a written capture back.
+- Never dispatch a constructed event from the layer or from a journey. The centralized event
+  factories `.claude/rules/tests.md` prescribes serve unit tests whose subject is the handler; a
+  journey drives input through the provider verbs only.
+- Never let a helper take an element, a component instance, or a selector from the caller. Every
+  helper resolves its own target from role and accessible name.
+
+## The resolver
+
+```ts
+resolveAccessible(name: string): HTMLElement
+resolveAccessible(role: string, name: string): HTMLElement
+```
+
+- Match the accessible name exactly, never a substring.
+- Search a fixed set of interactive roles for the bare-name form, and exactly the named role for
+  the two-argument form.
+- Count a match as reachable only when every condition holds: it is connected; it passes a
+  visibility check that honours opacity and CSS; its box has non-zero width and height; its
+  `tabIndex` is at least zero; it matches neither `:disabled` nor `[aria-disabled="true"]`; and it
+  has no `[inert]` ancestor.
+- Scroll a wholly off-viewport target into view once, then measure reachability again. Count a
+  control a person can scroll to as reachable, and one that stays outside the viewport as
+  unreachable.
+- Give the layer a rendered-only resolver beneath the public one, and use it from the acting verbs
+  so a click does not fail on a target the act itself scrolls into view.
+
+### The failure voices
+
+Keep these distinct, and never merge two into one message.
+
+| Condition                                  | The voice it must throw                                          |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| No element carries the name                | `No interactive element has the accessible name "<name>"`        |
+| Every match fails a reachability condition | `Interactive target "<name>" is not visible and focus-reachable` |
+| Several matches are reachable              | `Interactive target "<name>" is ambiguous across <n> elements`   |
+| Still off-viewport after being scrolled to | `Interactive target "<name>" is unreachable after scrolling`     |
+
+- Report an absent control and a present-but-unreachable one as different findings: the first names
+  a missing control, the second names the interface gating one that exists.
+- Report ambiguity as a finding about the surface. Name the match count in the message, and
+  re-target the journey by role or region.
+
+## Role vocabulary
+
+Never infer a role from markup. Confirm the computed role in the browser whenever a target stops
+resolving.
+
+- A `list`-bearing input computes `combobox`, not `textbox`. Attaching native suggestion machinery
+  to a field is a role change: re-target every journey that names that field, and read a resolver
+  miss immediately after such a change as this before treating the element as missing.
+- Always target a tab by its role. A tab and its panel collide on a bare name by construction,
+  because the panel is labelled by its tab.
+- `<summary>` is exposed as a native disclosure rather than through a role the provider's role
+  locators accept. Give the layer a separate disclosure verb keyed to the summary's rendered text,
+  applying the same reachability conditions and its own failure voices.
+
+## Region-scoped resolution
+
+```ts
+clickAccessibleWithin(region: string, role: string, name: string): Promise<void>
+```
+
+- Provide this form for repeated short verbs such as `Add`, and for a control whose accessible name
+  is completed by a status the row renders.
+- Apply the same reachability conditions inside the region, and throw voices that name the region
+  as well as the target.
+
+## Input and traversal
+
+| Verb                         | Contract                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `typeAccessible(name, text)` | Focus the field, select all, delete, then send real keystrokes. Escape the provider's key syntax in the text. |
+| `fillAccessible(name, text)` | Replace the value in one operation for text too long to type. The real element still publishes real input.    |
+| `pressKeys(keys)`            | Send a provider keyboard sequence for Enter, arrows, modifiers, and combinations.                             |
+| `traverseAccessible(name)`   | Move focus by forward Tab from wherever focus is, and return the target once focus lands on it.               |
+
+- Count a traversal step only when focus actually lands on an element, and never charge the step
+  bound for a Tab that moved nothing.
+- End the traversal when focus revisits an element, which is one complete cycle of the tab order,
+  and throw the traversal's own voice, carrying the trail of what focus did reach. Keep a hard cap
+  above the cycle so a page with no tab order fails instead of hanging.
+- Re-resolve the target by role and name on every step, and never hold a node reference across
+  steps. A framework may replace the node between resolution and focus arrival.
+- Never call the browser's focus method to place focus.
+
+## Perception
+
+```ts
+readPerception(name: string): string
+```
+
+- Return the normalized `innerText` of exactly one visible named region, dialog, table, tab panel,
+  alert, or status. Collapse whitespace runs to single spaces and trim.
+- Read `innerText`, never `textContent`: `innerText` applies CSS transforms and leaves out content
+  the layout hides. Quote that text in assertions.
+- Include descendant visually-hidden text, which a screen reader perceives and which a clip-based
+  hiding technique leaves in `innerText`.
+- Throw when the named region is absent, hidden, or ambiguous.
+- Give the layer a whole-page perception reader for cross-region sentences and the vocabulary
+  sweep, a focus reader that returns the active element's rendered text, and a value reader that
+  returns a resolved control's value. A perception assertion may quote that value: it is a rendered
+  fact rather than internal state.
+
+## Mounting and cleanup
+
+- Mount the shipped root component with its real provisions and return an idempotent cleanup that
+  unmounts the app and removes its container.
+- Undo everything a journey changed after each test: unmount, destroy the session, reset the theme,
+  clear the keys the application persisted, and return the route to its entry. Never let a journey
+  inherit the previous journey's state.
+
+## The capture hook
+
+Give the layer exactly one capture helper. [captures.md](captures.md) owns the registry, the
+variant matrix, and the proofs that read what it wrote.