@orkestrel/scaffold 0.0.18 → 0.0.19

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

@@ -0,0 +1,59 @@
+# Frontend Design
+
+> Part of the `enterprise-bootstrap` package. Full aesthetic, typography,
+> 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.
+
+## 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.
+
+## 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## 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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,312 @@
+# Bootstrap 5 Utilities Reference
+
+> Part of the `enterprise-bootstrap` package. Bootstrap **5.3.x** class index +
+> composition notes. Component markup: [components.md](components.md).
+> Theming, patterns, a11y: [bootstrap-reference.md](bootstrap-reference.md).
+
+## Contents
+
+- [Utility classes](#utility-classes-quick-reference) — background, borders, text color, display, flexbox, float, interactions, links, object fit, opacity, overflow, position, shadows, sizing, spacing, text, vertical align, visibility, z-index
+- [Scales](#spacing-scale) — spacing scale, z-index component scale
+- [Print utilities](#print-utilities)
+- [Helpers](#helpers) — visually-hidden, stretched-link, ratio, stacks, vr, focus-ring, icon-link
+- [Enterprise notes](#enterprise-notes-utilities) — composition habits
+
+## Utility Classes Quick Reference
+
+### Background
+
+```css
+.bg-primary, .bg-secondary, .bg-success, .bg-danger, .bg-warning, .bg-info, .bg-light, .bg-dark, .bg-body, .bg-white, .bg-transparent, .bg-black
+.bg-body-secondary, .bg-body-tertiary
+.bg-primary-subtle, .bg-secondary-subtle, .bg-success-subtle, .bg-danger-subtle, .bg-warning-subtle, .bg-info-subtle, .bg-light-subtle, .bg-dark-subtle
+.bg-gradient
+.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75, .bg-opacity-100
+```
+
+Prefer `bg-body-*` and `*-subtle` over `bg-white`/`bg-light` — they track `data-bs-theme` so dark mode works without extra rules.
+
+### Borders
+
+```css
+.border, .border-top, .border-end, .border-bottom, .border-start
+.border-0, .border-top-0, .border-end-0, .border-bottom-0, .border-start-0
+.border-1, .border-2, .border-3, .border-4, .border-5          /* widths */
+.border-primary, .border-secondary, .border-success, .border-danger, .border-warning, .border-info, .border-light, .border-dark, .border-white, .border-black
+.border-primary-subtle, .border-secondary-subtle, .border-success-subtle, .border-danger-subtle, .border-warning-subtle, .border-info-subtle, .border-light-subtle, .border-dark-subtle
+.border-opacity-10, .border-opacity-25, .border-opacity-50, .border-opacity-75, .border-opacity-100
+.rounded, .rounded-top, .rounded-end, .rounded-bottom, .rounded-start, .rounded-circle, .rounded-pill
+.rounded-0, .rounded-1, .rounded-2, .rounded-3, .rounded-4, .rounded-5
+```
+
+For borders that must stay visible in both color modes, prefer `border-*-subtle` variants (theme-adaptive) over raw color borders.
+
+### Colors (Text)
+
+```css
+.text-primary, .text-secondary, .text-success, .text-danger, .text-warning, .text-info, .text-light, .text-dark
+.text-body, .text-body-secondary, .text-body-tertiary, .text-body-emphasis
+.text-primary-emphasis, .text-secondary-emphasis, .text-success-emphasis, .text-danger-emphasis, .text-warning-emphasis, .text-info-emphasis, .text-light-emphasis, .text-dark-emphasis
+.text-black, .text-white, .text-black-50, .text-white-50
+.text-muted        /* DEPRECATED in 5.3 — use .text-body-secondary; removed in v6 */
+.text-opacity-25, .text-opacity-50, .text-opacity-75, .text-opacity-100
+```
+
+### Display
+
+```css
+.d-none, .d-inline, .d-inline-block, .d-block, .d-grid, .d-inline-grid, .d-table, .d-table-cell, .d-table-row, .d-flex, .d-inline-flex
+.d-{breakpoint}-none, .d-{breakpoint}-inline, .d-{breakpoint}-inline-block, .d-{breakpoint}-block, .d-{breakpoint}-grid, .d-{breakpoint}-inline-grid, .d-{breakpoint}-table, .d-{breakpoint}-table-cell, .d-{breakpoint}-table-row, .d-{breakpoint}-flex, .d-{breakpoint}-inline-flex
+```
+
+### Flexbox
+
+```css
+/* Direction */
+.flex-row, .flex-column, .flex-row-reverse, .flex-column-reverse
+.flex-{breakpoint}-row, .flex-{breakpoint}-column, .flex-{breakpoint}-row-reverse, .flex-{breakpoint}-column-reverse
+
+/* Justify Content */
+.justify-content-start, .justify-content-end, .justify-content-center, .justify-content-between, .justify-content-around, .justify-content-evenly
+.justify-content-{breakpoint}-start, .justify-content-{breakpoint}-end, .justify-content-{breakpoint}-center, .justify-content-{breakpoint}-between, .justify-content-{breakpoint}-around, .justify-content-{breakpoint}-evenly
+
+/* Align Items */
+.align-items-start, .align-items-end, .align-items-center, .align-items-baseline, .align-items-stretch
+.align-items-{breakpoint}-start, .align-items-{breakpoint}-end, .align-items-{breakpoint}-center, .align-items-{breakpoint}-baseline, .align-items-{breakpoint}-stretch
+
+/* Align Self */
+.align-self-start, .align-self-end, .align-self-center, .align-self-baseline, .align-self-stretch
+
+/* Fill */
+.flex-fill, .flex-{breakpoint}-fill
+
+/* Grow/Shrink */
+.flex-grow-0, .flex-grow-1, .flex-shrink-0, .flex-shrink-1
+
+/* Wrap */
+.flex-wrap, .flex-nowrap, .flex-wrap-reverse
+
+/* Order */
+.order-first, .order-0, .order-1, .order-2, .order-3, .order-4, .order-5, .order-last
+
+/* Align Content */
+.align-content-start, .align-content-end, .align-content-center, .align-content-between, .align-content-around, .align-content-stretch
+```
+
+### Float
+
+```css
+.float-start, .float-end, .float-none
+.float-{breakpoint}-start, .float-{breakpoint}-end, .float-{breakpoint}-none
+```
+
+### Interactions
+
+```css
+.user-select-all, .user-select-auto, .user-select-none
+.pe-none, .pe-auto        /* pointer-events */
+```
+
+`.pe-none` blocks pointer input only — keyboard and assistive tech can still reach the element. Pair with `tabindex="-1"` and `aria-disabled="true"`, or better, use the real `disabled` attribute on form controls and drop `href` on links.
+
+### Link
+
+```css
+.link-primary, .link-secondary, .link-success, .link-danger, .link-warning, .link-info, .link-light, .link-dark
+.link-body-emphasis
+.link-opacity-10, .link-opacity-25, .link-opacity-50, .link-opacity-75, .link-opacity-100
+.link-underline, .link-underline-primary (…per theme color)
+.link-underline-opacity-0, .link-underline-opacity-10, .link-underline-opacity-25, .link-underline-opacity-50, .link-underline-opacity-75, .link-underline-opacity-100
+.link-offset-1, .link-offset-2, .link-offset-3
+```
+
+### Object Fit
+
+```css
+.object-fit-contain, .object-fit-cover, .object-fit-fill, .object-fit-scale, .object-fit-none
+.object-fit-{breakpoint}-contain, .object-fit-{breakpoint}-cover, .object-fit-{breakpoint}-fill, .object-fit-{breakpoint}-scale, .object-fit-{breakpoint}-none
+```
+
+### Opacity
+
+```css
+.opacity-0, .opacity-25, .opacity-50, .opacity-75, .opacity-100
+```
+
+### Overflow
+
+```css
+.overflow-auto, .overflow-hidden, .overflow-visible, .overflow-scroll
+.overflow-x-auto, .overflow-x-hidden, .overflow-x-visible, .overflow-x-scroll
+.overflow-y-auto, .overflow-y-hidden, .overflow-y-visible, .overflow-y-scroll
+```
+
+### Position
+
+```css
+.position-static, .position-relative, .position-absolute, .position-fixed, .position-sticky
+.fixed-top, .fixed-bottom
+.sticky-top, .sticky-bottom
+.top-0, .top-50, .top-100
+.bottom-0, .bottom-50, .bottom-100
+.start-0, .start-50, .start-100
+.end-0, .end-50, .end-100
+.translate-middle, .translate-middle-x, .translate-middle-y
+```
+
+### Shadows
+
+```css
+.shadow-none, .shadow-sm, .shadow, .shadow-lg
+```
+
+### Sizing
+
+Bootstrap ships exactly these — nothing else (no `.vw-25`, `.vh-50`, `.mw-auto`, `.min-vh-75`, etc.; add missing steps via the utilities API if a project truly needs them — see [bootstrap-reference.md](bootstrap-reference.md)):
+
+```css
+/* Width / height (percent of parent) */
+.w-25, .w-50, .w-75, .w-100, .w-auto
+.h-25, .h-50, .h-75, .h-100, .h-auto
+
+/* Max */
+.mw-100, .mh-100
+
+/* Viewport */
+.vw-100, .vh-100, .min-vw-100, .min-vh-100
+```
+
+### Spacing
+
+```css
+/* Format: {property}{sides}-{size} or {property}{sides}-{breakpoint}-{size} */
+/* Property: m (margin), p (padding) */
+/* Sides: t, b, s (start), e (end), x, y, (blank) */
+/* Size: 0, 1, 2, 3, 4, 5, auto (margins only) */
+
+.m-0 … .m-5, .m-auto      .mt-* .mb-* .ms-* .me-* .mx-* .my-*   (same sizes, + auto)
+.p-0 … .p-5               .pt-* .pb-* .ps-* .pe-* .px-* .py-*   (same sizes)
+
+/* Gap — flex and grid parents */
+.gap-0 … .gap-5
+.row-gap-0 … .row-gap-5
+.column-gap-0 … .column-gap-5
+```
+
+Notes: `s`/`e` are logical start/end — they flip automatically under RTL; never reach for physical left/right. `.g-*` / `.gx-*` / `.gy-*` are **row gutters** (used on `.row`), a separate system from `gap-*`. Negative margins exist in source but are disabled by default (`$enable-negative-margins`).
+
+### Text
+
+```css
+/* Alignment */
+.text-start, .text-center, .text-end
+.text-{breakpoint}-start, .text-{breakpoint}-center, .text-{breakpoint}-end
+
+/* Wrap / break */
+.text-wrap, .text-nowrap, .text-break
+
+/* Transform */
+.text-lowercase, .text-uppercase, .text-capitalize
+
+/* Weight / italics */
+.fw-lighter, .fw-light, .fw-normal, .fw-medium, .fw-semibold, .fw-bold, .fw-bolder
+.fst-normal, .fst-italic
+
+/* Line height */
+.lh-1, .lh-sm, .lh-base, .lh-lg
+
+/* Family / reset / decoration */
+.font-monospace, .text-reset
+.text-decoration-none, .text-decoration-underline, .text-decoration-line-through
+
+/* Size */
+.fs-1, .fs-2, .fs-3, .fs-4, .fs-5, .fs-6
+
+/* Truncate — needs display block/inline-block or a flex child with min-width 0 */
+.text-truncate
+```
+
+Two composition traps in this group:
+
+- **`fs-*` without `lh-1` grows the row.** A resized glyph or mark keeps the parent's line-height, so the line box stretches and the row sits taller than its neighbors. Pair `fs-*` with `lh-1` on anything that is a mark rather than a paragraph.
+- **`text-truncate` zeroes a flex item's automatic minimum size** (that's the `min-width: 0` it carries). Inside a flex _column_, that also removes the floor that kept a heading at its own height: a growing sibling then squeezes the title from the bottom until it clips. Floor the title with `flex-shrink-0` and let the growing sibling absorb the change.
+
+### Vertical Align
+
+```css
+.align-baseline, .align-top, .align-middle, .align-bottom, .align-text-top, .align-text-bottom
+```
+
+### Visibility
+
+```css
+.visible, .invisible
+```
+
+### Z-index
+
+```css
+.z-n1, .z-0, .z-1, .z-2, .z-3    /* NOT responsive — no breakpoint variants exist */
+```
+
+## Spacing Scale
+
+| Class  | Size                           |
+| ------ | ------------------------------ |
+| `0`    | 0                              |
+| `1`    | $spacer \* .25 (0.25rem = 4px) |
+| `2`    | $spacer \* .5 (0.5rem = 8px)   |
+| `3`    | $spacer (1rem = 16px)          |
+| `4`    | $spacer \* 1.5 (1.5rem = 24px) |
+| `5`    | $spacer \* 3 (3rem = 48px)     |
+| `auto` | auto                           |
+
+## Z-index Scale (components)
+
+| Component          | Z-index |
+| ------------------ | ------- |
+| Dropdown           | 1000    |
+| Sticky             | 1020    |
+| Fixed              | 1030    |
+| Offcanvas backdrop | 1040    |
+| Offcanvas          | 1045    |
+| Modal backdrop     | 1050    |
+| Modal              | 1055    |
+| Popover            | 1070    |
+| Tooltip            | 1080    |
+| Toast              | 1090    |
+
+## Print Utilities
+
+```css
+.d-print-none, .d-print-inline, .d-print-inline-block, .d-print-block, .d-print-grid, .d-print-table, .d-print-table-cell, .d-print-table-row, .d-print-flex, .d-print-inline-flex
+```
+
+## Helpers
+
+Helpers are single-purpose classes that sit alongside utilities.
+
+- **`.visually-hidden`** — hide visually, keep for screen readers (icon-button labels, table caption text, "Danger:" prefixes).
+- **`.visually-hidden-focusable`** — hidden until focused; the skip-link class. Never combine with `.visually-hidden`.
+- **`.stretched-link`** — makes a whole `position-relative` container (e.g. a card) the click target of one inner link, without wrapping everything in `<a>`.
+- **`.ratio .ratio-16x9`** (also `1x1`, `4x3`, `21x9`, or `--bs-aspect-ratio`) — responsive embeds/iframes.
+- **`.vstack` / `.hstack gap-*`** — shorthand vertical/horizontal flex stacks for quick toolbars and side rails.
+- **`.vr`** — vertical rule divider inside an `.hstack` or flex row.
+- **`.focus-ring`** (+ `.focus-ring-primary` … per theme color) — opt-in focus ring for custom interactive elements; tune via `--bs-focus-ring-width` (.25rem), `--bs-focus-ring-opacity` (.25), `--bs-focus-ring-color`, `--bs-focus-ring-x/y/blur`. Use it instead of `outline: none` hacks so keyboard focus stays visible.
+- **`.icon-link`** (+ `.icon-link-hover`) — pairs a Bootstrap Icon SVG with a text link; icon auto-sizes to 1em; give decorative icons `aria-hidden="true"`. Hover shift via `--bs-icon-link-transform`.
+
+## Enterprise notes (utilities)
+
+### Composition habits
+
+- **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.
+- **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.
+- **Responsive hide:** show the best layout per breakpoint (`d-none d-md-block` vs `d-md-none`) rather than cramming one layout everywhere. Below `sm`, hide button captions (`d-none d-sm-inline` on the label span, `aria-label` on the control so the accessible name stays) before you let the brand or page title truncate.
+- **RTL safety:** always `ms-*`/`me-*`/`ps-*`/`pe-*`, `text-start`/`text-end`, `float-start`/`float-end` — the logical model is what lets one build serve LTR and RTL.
+- **Density as a system:** when a screen offers compact/comfortable density, drive it from a token or wrapper class that swaps padding — not ad-hoc `-sm` sprinkling per element ([bootstrap-reference.md](bootstrap-reference.md) → Design tokens).
+- **Shadows:** `shadow-sm` for panels in product UI; `shadow-lg` rarely belongs in dense admin screens.
+- **Print:** mark chrome `d-print-none`; keep the data table/results printable.

package/dist/host/agents/skills/orkestrel-align-packages/references/integration.md

@@ -2,20 +2,9 @@
 
 ## Map ownership
 
-Use this dependency model unless a package-specific guide narrows it:
+Dependency direction across environments is the root project model in `AGENTS.md`, detailed for placement in `.claude/rules/workspace.md` and for app composition in `.claude/rules/application.md`. Read those; this reference does not restate them. Apply the same law to a dependency's `@orkestrel/<package>/browser` and `/server` exports, whose bare export is its core API.
 
-| Surface       | May depend on                                                       | Must not depend on                     |
-| ------------- | ------------------------------------------------------------------- | -------------------------------------- |
-| `src/core`    | host-independent Orkestrel core packages                            | Node, DOM, browser/server environments |
-| `src/server`  | its core and server-capable dependencies                            | browser/app environments               |
-| `src/browser` | its core and browser-capable dependencies                           | Node/server/app environments           |
-| `app/core`    | host-independent library/core and app/core logic                    | Node, DOM, app/server, app/browser     |
-| `app/server`  | app/core plus core/server libraries                                 | browser/app/browser                    |
-| `app/browser` | app/core plus core/browser libraries and shared transport contracts | Node/app/server implementation         |
-
-Browser application code reaches server behavior through shared contracts and transports, not server implementation imports.
-
-Framework packages own reusable mechanisms. Applications own workflows, policy, presentation, users, authorization decisions, and product-specific defaults.
+Ownership across packages is what those rules leave open: framework packages own reusable mechanisms, and applications own workflows, policy, presentation, users, authorization decisions, and product-specific defaults.
 
 ## Use consumers as evidence
 
@@ -53,4 +42,6 @@ Place each proof at the highest useful layer:
 
 Use the actual packages and transports. Use temporary resources or protocol-faithful fixture servers for deterministic network boundaries. Use the real external service when its behavior is the claim. Never simulate an owned package with a mock or fake.
 
+When the claim is that a foreign client can consume the stack — an editor, an agent CLI, a third-party protocol client — one representative real client of that class drives the surface end to end before the claim ships. Record the exact commands, the authentication and approval model that client needed, and every part of the surface it could not reach. Protocol-level tests prove the protocol; only the client proves the integration.
+
 Test both successful composition and contract disagreement: invalid options, unavailable capability, partial failure, abort/cleanup, version mismatch, and lifecycle ordering where applicable.

package/dist/host/agents/skills/orkestrel-build-application/SKILL.md

@@ -5,60 +5,88 @@ description: Design, scaffold, extend, or harden Orkestrel `app/core`, `app/brow
 
 # Build an Orkestrel application
 
-Read `AGENTS.md`, `.claude/rules/application.md`, `.claude/rules/workspace.md`,
-`.claude/rules/architecture.md`, `.claude/rules/documentation.md`, and every other rule
-selected by the files in scope. Then read
-[`references/application.md`](references/application.md) completely.
+## Load authority
 
-## Workflow
+Read the current files in this order:
 
-1. Inventory existing `src`, `app`, `configs`, tests, manifest scripts, aliases,
-   and guide rows. Treat current code as evidence, not policy.
-2. Select only required environments. `--src` selects published src environments and
-   `--app` selects private app environments; the two selections are independent,
-   at least one is required, and there is no `--surfaces` synonym. Each side offers
-   `core`, `browser`, and `server`. Browser and server may depend on their core, core
-   depends on neither host implementation, and browser/server remain disjoint.
-3. Define or refine public contracts in each environment's `types.ts` before
-   implementation. Inspect exact installed `@orkestrel/*` capabilities before
-   writing boundary code, and reuse a primitive whose semantics match.
-4. Add aliases in root TypeScript configuration and derive Vite aliases from
-   them. Keep `configs/app` wrappers thin.
-5. Implement complete entries, `export *`-only barrels, centralized `types.ts` /
-   `constants.ts` / `helpers.ts` and their sibling kind files, dedicated one-class
-   implementation files, environment parsing, lifecycle, builds, and scripts.
-   App-only manifests must be `private: true`; mixed manifests publish only
-   `dist/src` and never expose `dist/app`.
-6. Keep boundary enforcement inside the configured toolchain, each layer owning what
+1. `AGENTS.md`.
+2. `.claude/rules/application.md` for composition, entries, manifest safety, and
+   lifecycle; `.claude/rules/workspace.md` for environments, aliases, configuration, and
+   scripts; `.claude/rules/architecture.md` for placement and barrels;
+   `.claude/rules/tests.md` for test law; `.claude/rules/documentation.md` for parity;
+   plus every other rule the files in scope select.
+3. `guides/README.md`, the governing application guide, and `ROADMAP.md` when present.
+4. The authoritative `*/types.ts` of each selected environment, the root
+   `tsconfig.json` and `vite.config.ts`, the manifest, and `configs/app`.
+
+Those rules are the contract; this skill is only the workflow. Where a step names a law,
+read the law rather than this summary of it.
+
+## Select the environments
+
+`--src` selects published src environments and `--app` selects private app environments.
+The selections are independent, at least one is required, each offers `core`, `browser`,
+and `server`, and there is no `--surfaces` synonym.
+
+| Selection   | What it owns                                                             |
+| ----------- | ------------------------------------------------------------------------ |
+| app/core    | Host-independent contracts and composition; check and test only          |
+| app/browser | Vue runtime behind an `index.html` entry, `vue-tsc`, real Chromium tests |
+| app/server  | Node runtime, `dist/app/server/main.cjs` with only `node:*` external     |
+
+Core-only, browser-only, and server-only applications are valid. A browser+server pair
+includes app/core so the shared transport contracts have one host-independent owner.
+
+## Execute the workflow
+
+1. **Inventory** existing `src`, `app`, `configs`, tests, manifest scripts, aliases, and
+   guide rows. Treat current code as evidence, not policy.
+2. **Contract first.** Define or refine each environment's `types.ts` before
+   implementation, and inspect the exact installed `@orkestrel/*` capabilities before
+   writing any boundary code.
+3. **Wire configuration.** Root `tsconfig.json` owns the `@app/*` aliases and root
+   `vite.config.ts` derives from them and owns the Vitest projects; `configs/app` holds
+   thin target wrappers and scoped tsconfigs.
+4. **Implement completely** — entries, barrels, centralized declarations, one-class
+   implementation files, environment parsing, lifecycle, builds, and scripts — under the
+   placement and manifest laws. Parse the options container and its host and port leaves
+   before mutation, rejecting wrong-shaped containers, empty hosts, and non-integer,
+   negative, or out-of-range ports with a coded error and its guard.
+5. **Own the shutdown contract.** Lifecycle transitions serialize in call order, an
+   ephemeral restart re-requests port zero, stop closes hostile active connections
+   deterministically, and runner stop idempotently releases its signal listeners. Runner
+   generations isolate asynchronous failures so an older transition cannot release a
+   newer run's listeners, and convenience startup returns the runner rather than hiding
+   that cleanup.
+6. **Keep boundary enforcement inside the configured toolchain,** each layer owning what
    it can express: Oxlint `no-restricted-imports` for literal-string declared package,
    alias, and conventional relative import direction; Oxfmt for formatting;
    `tests/setupPolicy.ts` as the narrow TypeScript compiler-API pass over computed and
    template-literal specifiers, declaration placement, and the barrel law; scoped
-   TypeScript projects for host-global isolation; and Vite's real browser/server
-   builds and environment-boundary plugin for Vue, CSS, assets, workers, runtime
-   resolution, and physical workspace containment, using Vite's Oxc AST for
-   TypeScript/JavaScript, the official Vue SFC compiler for `.vue` blocks, Vite's
-   HTML parser callbacks, and Vite's bundled Lightning CSS dependency analyzer.
-   Exercise the combined configuration through
-   fresh generated-consumer lint, typecheck, build, and integration tests. Add no
-   standalone boundary script and no second general-purpose parser or source-language
-   analyzer duplicating those layers. Keep browser-only runtime tooling
-   development-only and require explicit authorization before adding a Sass compiler.
-7. Add real app/core Node tests, app/browser Playwright-backed Chromium tests,
-   app/server loopback and child-process tests, and cross-environment integration.
-   Exercise repeated lifecycle, malformed environment values, protocol failures,
-   concurrency, hostile connections, and cleanup. A signal-owning server runner must
-   expose idempotent explicit stop so normal shutdown releases every installed process
-   listener; stale asynchronous failures cannot mutate a newer generation, and
-   convenience starters return the runner rather than hiding that cleanup contract.
-   Keep the runner class alone in `ApplicationServerRunner.ts` and its convenience
-   starter in centralized `factories.ts`.
-8. Update the guide, examples, manifest index, and parity specifiers for every
-   app export and behavioral method.
-9. Run source cleanup, test cleanup, one independent design audit and one
-   independent objective audit, a mechanical conformance pass, and the
-   repository gates in their required order.
+   TypeScript projects for host-global isolation; and Vite's real builds and
+   environment-boundary plugin for Vue, CSS, assets, workers, runtime resolution, and
+   physical workspace containment. Add no standalone boundary script and no second
+   parser or source-language analyzer duplicating those layers. Disable the browser
+   application's public directory so an unmanaged file copy cannot bypass the module
+   graph. Keep browser-only runtime tooling development-only and require explicit
+   authorization before adding a Sass compiler.
+7. **Prove it on real hosts.** app/browser tests run on Playwright-backed Vitest Browser
+   Mode against real DOM, probing the installed executable directly with
+   `existsSync(chromium.executablePath())` rather than guessing a channel or reading an
+   environment flag; app/server tests bind port zero on loopback and use real fetch;
+   real child-process tests prove executable readiness, collision exit, signal
+   termination, and port release, remembering that Windows reports
+   `ChildProcess.kill('SIGTERM')` as OS termination by signal while POSIX delivery
+   exercises the graceful listener and exits zero. A capability-dependent test probes the
+   actual capability and scopes any skip narrowly.
+8. **Document and prove parity** for every app export and behavioral method: guide,
+   examples, manifest index, and the parity specifiers walking the existing `src` and
+   `app` roots and every selected alias.
+9. **Verify.** Run the rules' cleanup sweeps over source and tests, then one independent
+   design audit, one independent objective audit, a mechanical conformance pass, and the
+   repository gates in their required order. Generated CI runs those gates on the declared
+   minimum Node release and on the current major.
 
-Do not add showcase, authentication, persistence, proxy, styling-system, or
-product policy unless the request requires it. Do not leave placeholders,
-compatibility shims, empty setup files, or deferred app behavior.
+Do not add showcase, authentication, persistence, proxy, styling-system, or product
+policy unless the request requires it. Do not leave placeholders, compatibility shims,
+empty setup files, or deferred app behavior.

package/dist/host/agents/skills/orkestrel-debrief/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: orkestrel-debrief
+description: Convert a closed campaign's residue into portable truth through field evidence, a findings ledger, fix loops with live re-proof, canon refinement, and disciplined disposal. Use after a campaign or milestone closes to audit what was built and how it was built, when live field testing must precede judgment, when learnings must propagate into skills/rules/guides/scaffold, or when working ledgers must fold into canon and retire.
+---
+
+# Debrief a closed campaign
+
+## Load authority
+
+Read the current files in this order:
+
+1. `AGENTS.md`.
+2. Every applicable `.claude/rules/*.md`; the documentation and quality laws bind every
+   ledger entry and every canon refinement this skill produces.
+3. [field-testing.md](references/field-testing.md) before running or judging any live
+   field pass.
+4. `guides/README.md`, the governing guide for what the campaign built, and `ROADMAP.md`.
+
+The user's current instruction wins. The debrief judges both the artifact and the process
+that produced it; neither is exempt.
+
+## The debrief laws
+
+- **Use it before you judge it.** A debrief of a surface nobody drove is a review of
+  intentions. Field evidence — real clients, real harnesses, goal-only prompts — precedes
+  every finding about usability, and the field transcript is the evidence of record.
+- **Evidence is verbatim or it is not evidence.** The ledger quotes exact commands, exact
+  refusals, exact reasoning-trace lines. A paraphrase cannot be re-verified after the
+  session that produced it is gone.
+- **Every finding ends in exactly one bucket**: fix now; canon refinement (skill, rule,
+  guide); promotion (package/library boundary move); stays as-is with the reason; or
+  dropped on the record with the refuting evidence. A finding with no bucket is an
+  unfinished debrief.
+- **Fixes are re-proven by the class of evidence that found them.** A defect found by a
+  live field pass is closed by a live field pass, never by the fix's own tests alone.
+- **Portable versus resident.** Anything reusable beyond this repository — process
+  doctrine, teaching-surface laws, harness knowledge — lands in the portable skill/rule
+  set and propagates through the scaffold. Repository-specific truth lands in the guide.
+  Forward-looking work lands in `ROADMAP.md`. Nothing load-bearing stays only in the
+  ledger.
+- **The ledger is ephemeral.** The debrief folder is a working file: fold every surviving
+  truth into its destination, then delete the folder on the owner's explicit go-ahead —
+  never silently, and never leave it as residue after its campaign.
+
+## Run the round
+
+1. **Scope.** Name the campaign(s) under debrief, the artifact surfaces involved, and the
+   audiences that matter (human operators, frontier models, small models, external
+   clients). State what evidence already exists and what must be produced live.
+2. **Field passes.** Drive the artifact with representative real consumers per
+   [field-testing.md](references/field-testing.md): goal-only prompts, no coaching, the
+   tier ladder from frontier to the smallest model that matters, reasoning traces
+   captured wherever the runtime exposes them. Record every pass verbatim in the ledger.
+3. **Layer audits.** In parallel with the field passes, audit each layer the campaign
+   touched: implementation boundaries (what belongs a layer down or in a published
+   package), the process record (which dispatches failed, which laws were missing, where
+   executors deviated), and the instruction set itself (agents, rules, skills — what
+   confused an executor is a defect in the instruction, not the executor).
+4. **Reconcile into the ledger.** Number the findings, attach verbatim evidence to each,
+   and bucket every one. Confusion signatures from reasoning traces are findings about
+   the artifact's teaching surface, not anecdotes — see the signature catalog in
+   [field-testing.md](references/field-testing.md).
+5. **Fix loops.** Dispatch fix-now findings as bounded units under the repository's
+   engine contract, serialized, failing-first. After each round, re-run the field passes
+   that found the class and record the delta. Iterate until the field tier that matters
+   walks the surface unaided or the residual is proven to be consumer-floor, not
+   artifact darkness — state which, with evidence.
+6. **Canon refinement.** Write or revise the portable skills/rules the findings justify;
+   update the guide for resident truth; update `ROADMAP.md` for forward work. Every
+   retained finding names the artifact that now carries it.
+7. **Propagate.** Land the portable set in the scaffold repository so every future
+   project inherits it; run the scaffold's own gates before pushing.
+8. **Dispose.** Present the ledger's disposition map to the owner: what folded where,
+   what remains open. Delete the ledger only on their explicit go-ahead.
+
+## Verdict shape
+
+Each debrief round ends with one fixed report: the finding table (id, evidence pointer,
+bucket, carrier), the field-pass scoreboard before and after, the canon delta (files
+created or changed), and exactly one terminal line — `DEBRIEF: FOLDED` when every finding
+has a carrier and the propagation is pushed, or `DEBRIEF: OPEN` with the blocking items.