@orkestrel/scaffold 0.0.2 → 0.0.3

package/dist/host/claude/rules/names.md

@@ -0,0 +1,209 @@
+---
+paths:
+  - '**/*.{ts,tsx,mts,cts,vue}'
+---
+
+# Naming and API-shape rules
+
+Names are public API. A consumer should be able to predict them without documentation.
+
+## Entity-scoped names: one word
+
+Properties/getters, methods, option keys, and event names belong to an entity whose type already supplies context. Use one descriptive word:
+
+```ts
+interface AgentInterface {
+	readonly id: string
+	readonly context: AgentContextInterface
+	readonly status: AgentStatus
+	generate(): Promise<string>
+	stream(options?: AgentStreamOptions): AsyncGenerator<string, string>
+	abort(): void
+}
+```
+
+Hard targets:
+
+- Public properties: one word.
+- Public methods: one word; use two only when no single verb is accurate.
+- Ungrouped option keys: one word.
+- Grouped option key: the configured entity noun; every leaf remains one word.
+- Events: one present-tense verb or noun.
+- Private methods: two or three words are acceptable.
+
+The rule does not apply to standalone helpers, type names with role suffixes, or qualified constants.
+
+## Split instead of compounding
+
+A compound entity member usually means the API contains multiple entities or behaviors. Do not create `addTool`, `removeDocument`, `databasePath`, or `serverTimeout`.
+
+### Group options by entity
+
+```ts
+interface ServerOptions {
+	readonly server?: { readonly port?: number; readonly timeout?: number }
+	readonly database?: { readonly path?: string; readonly timeout?: number }
+}
+```
+
+Never flatten these into prefixed keys.
+
+### Extract sub-entities
+
+Move prefixed method families to a manager and expose it as a noun:
+
+```ts
+interface AgentContextInterface {
+	readonly instructions: InstructionManagerInterface
+	readonly documents: DocumentManagerInterface
+	readonly tools: ToolManagerInterface
+}
+```
+
+Call `context.instructions.add(input)`, not `context.addInstruction(input)`.
+
+### Split behavioral variants
+
+Do not hide multiple algorithms behind a discriminator parameter:
+
+```ts
+parseJSON(input)
+parseYAML(input)
+parseTOML(input)
+```
+
+Do not write `parse(input, format)`. A literal that selects a different action is a magic mode and requires separate functions/methods.
+
+Distinguish behavior from data:
+
+- Different value selects a different action/algorithm/shape of work → split.
+- Different value selects a datum for the same operation → keep it as data.
+- Discriminants, reasoning/error codes, uniformly applied value enums, and field/key selectors are data.
+
+## Standalone helpers
+
+Module helpers have no owning entity at the call site, so default to `{verb}{Noun}`:
+
+`generateId`, `computeHash`, `extractColumns`, `derivePhaseStatus`, `inferLanguage`, `normalizePath`, `sanitizeFilename`, `matchesGlobPattern`, `belongsTo`, `hasMany`.
+
+- A one-word helper is valid only when its meaning and arguments are unmistakable: `delay`, `clamp`, `tokenize`, `similarity`.
+- Reject vague helpers such as `process` or `handle`.
+- A helper prefix has one project-wide meaning: `extract*` extracts structure, `infer*` derives, `compute*` calculates deterministically, and `matches*` is a predicate.
+- When a helper family grows around one shape, promote it to a class with entity-scoped one-word methods.
+
+## General vocabulary
+
+- Describe what a thing is, not its implementation.
+- Prefer short common English; avoid jargon, abbreviations, and non-universal acronyms.
+- One concept has one word project-wide. Do not alternate `count`/`length`/`size`/`total` or `abort`/`cancel`.
+- Properties are nouns; methods are verbs.
+- Booleans read as assertions: `aborted`, `exhausted`, `expired`.
+- A binary behavior switch is a boolean, such as `bail`; never model it as `'continue' | 'halt'`.
+- Genuine discriminants, multi-state lifecycles, conventional value pairs (`ascending`/`descending`, `and`/`or`), and external-spec literals remain unions.
+- Absence is `undefined`, never `'none'`, `'unset'`, `'unknown'`, `''`, `-1`, or another sentinel. Use `null` only when an external protocol distinguishes it from omission.
+- Derive facts from existing state through a getter or at the use site. Do not store a duplicate boolean/string label that can drift.
+- Use a union only for irreducible modes, phases, discriminants, or external values.
+- Accessors use bare nouns, never `get*`/`set*`.
+- A discriminant names its axis (`relationship`, `command`, `category`, `operation`, `via`), never `kind` or `type`.
+
+## Acronyms
+
+Keep canonical case:
+
+- Initialisms: `JSON`, `HTTP`, `NDJSON`, `SSE`, `URL`, `URI`, `SQL`, `API`, `DB`, `TTL`, `UUID`, `RFC`, `JWT`.
+- Brands/proper names: `SQLite`, `IndexedDB`, `GitHub`, `OAuth`.
+- PascalCase identifiers preserve the acronym: `JSONSchema`, `HTTPServer`, `NDJSONParser`, `SSEStream`, `URLPattern`, `SQLiteDriver`, `IndexedDBDriver`.
+- camelCase lowers an acronym only when it leads: `jsonValue`, `urlPath`, `sqlText`; otherwise preserve it: `parseJSON`, `toJSON`, `fromNDJSON`, `signJWT`, `compileSQL`.
+- Ecosystem-conventional `id` and leading `url`/`uri` remain lowercase.
+- Domain folders remain lowercase: `http/`, `sqlite/`, `indexeddb/`, `websocket/`.
+- Never title-fold canonical acronyms into `Json`, `Ndjson`, `Http`, `Sse`, or `Sqlite`.
+
+## Type-level identifiers
+
+| Kind                      | Required form                           |
+| ------------------------- | --------------------------------------- |
+| Behavioral interface      | `{Entity}Interface`                     |
+| Options/config            | `{Entity}Options`                       |
+| Creation input            | `{Entity}Input`                         |
+| Outcome/output            | `{Entity}Result`                        |
+| Execution context         | `{Entity}Context`                       |
+| Event map                 | `{Entity}EventMap`                      |
+| Union/enum-like           | `{Entity}{Noun}`                        |
+| Plain non-behavioral data | `{Entity}`                              |
+| Function type             | `{Entity}Handler` or `{Entity}Function` |
+| Manager interface         | `{Entity}ManagerInterface`              |
+
+- Never prefix interfaces with `I`.
+- Never pluralize type names.
+- `Handler` is for function types, never classes.
+
+## Value-level identifiers
+
+| Kind           | Required form                         |
+| -------------- | ------------------------------------- |
+| Class          | PascalCase `{Entity}`                 |
+| Manager class  | PascalCase `{Entity}Manager`          |
+| Factory        | camelCase `create{Entity}`            |
+| Guard          | camelCase `is{Condition}`             |
+| Helper         | camelCase `{verb}{Noun}`              |
+| Constant       | UPPER_SNAKE_CASE `{QUALIFIER}_{NOUN}` |
+| Property/field | camelCase bare noun                   |
+| Method         | camelCase bare verb                   |
+| Boolean        | camelCase adjective/past participle   |
+
+## Fixed derivation/construction forms
+
+- `is*`: total `Guard<T>`; never throws; returns false off-shape.
+- `parse*`: coercion producing `T | undefined`; cross-type conversion never belongs in a guard.
+- `create*`: factory constructing an entity/value.
+- `*Of`: builder combining constituent parts into a container/guard/value, such as `arrayOf(guard)` or `boundsOf(min, max)`.
+- `{noun}To{Noun}`: projection from a whole to a derived view, such as `definitionToSnapshot`.
+- `*Shape`: `ContractShape` value/JSON-Schema blueprint, not a function or type.
+- Leading `_`: intentionally unused binding only; never privacy.
+
+For `_` bindings:
+
+- Use only for genuine callback/signature conformance, rest omission, swallowed catches, or intentionally unused loop variables.
+- Verify each use is intentional; remove `_` and wire the value if it should be consumed.
+- Remove the parameter when signature compatibility does not require it.
+- Prefer a short justification for each rare `_` in `src/`.
+
+## Tallies
+
+- A lone unambiguous tally is `count`.
+- When several distinct tallies coexist, name each fact: a pool may expose `size`, `idle`, and `active`; a queue may expose `count` and `active`.
+- Do not expose several ambiguous `count` properties.
+
+## Files and folders
+
+| Kind           | Pattern                                      |
+| -------------- | -------------------------------------------- |
+| Domain folder  | lowercase plural entity: `agents/`, `tools/` |
+| Implementation | PascalCase entity: `Agent.ts`                |
+| Test           | PascalCase entity + `.test`: `Agent.test.ts` |
+| Guide          | lowercase domain: `agents.md`                |
+
+## Fixed lifecycle vocabulary
+
+| Verb      | Exact meaning                             |
+| --------- | ----------------------------------------- |
+| `start`   | Begin or restart                          |
+| `stop`    | End permanently                           |
+| `pause`   | Suspend resumably                         |
+| `resume`  | Continue after pause                      |
+| `skip`    | Mark intentionally unexecuted             |
+| `abort`   | Cancel with signal propagation            |
+| `clear`   | Reset state without destroying the entity |
+| `destroy` | Tear down and release resources           |
+| `execute` | Run primary work to completion            |
+
+Never introduce synonyms such as `cancel`, `reset`, or `run` for these meanings.
+
+## Rejected naming
+
+- Generic words: `data`, `info`, `item`, `thing`, `obj`.
+- Type-encoded names: `nameString`, `countNumber`.
+- Abbreviations: `cfg`, `doc`, `msg`; write `config`, `document`, `message`.
+- `@internal` methods; use `#` privacy.
+- Compound entity members where grouping/extraction/splitting provides the context.
+- Behavior-selecting magic strings.

package/dist/host/claude/rules/patterns.md

@@ -0,0 +1,130 @@
+---
+paths:
+  - 'src/**/*.ts'
+  - 'app/**/*.{ts,vue}'
+  - 'tests/**/*.ts'
+---
+
+# API pattern rules
+
+## Declared ecosystem capabilities
+
+Before writing a guard, parser, combinator, outcome, safe exception boundary, contract shape/compiler, schema utility, error narrower, emitter helper, or other general primitive:
+
+1. Inspect `package.json`, the lockfile, vendored dependency guides, and exact installed declarations/exports.
+2. Build a semantic overlap map between the proposed/local behavior and declared `@orkestrel/*` capabilities.
+3. Reuse the originating package directly when semantics match.
+4. Keep local behavior only when it adds a real domain invariant, composition, projection, translation, or intentionally different contract.
+5. Test the difference. Similar names are not proof of equivalent semantics.
+
+Never reimplement or rename-wrap a declared package primitive. Do not add an ecosystem dependency unless the user explicitly authorizes it.
+
+## Options
+
+- Top-level keys are single words.
+- Group related settings beneath the configured entity noun; every leaf is one word.
+- Never encode grouping through prefixes such as `serverPort` or `databasePath`.
+- Reserve `on` exclusively for initial `EmitterHooks`.
+- Explain short option keys in TSDoc `@remarks`, not through longer names.
+
+```ts
+interface ServerOptions {
+	readonly on?: EmitterHooks<ServerEventMap>
+	readonly error?: EmitterErrorHandler
+	readonly server?: { readonly port?: number; readonly timeout?: number }
+	readonly database?: { readonly path?: string }
+}
+```
+
+## Managers
+
+### Accessors
+
+Managers expose one item and all items through singular/plural domain nouns:
+
+```ts
+entity(key): EntityInterface | undefined
+entities(): readonly EntityInterface[]
+```
+
+Examples: `timeout(id)`/`timeouts()`, `agent(id)`/`agents()`.
+
+### Batch operations
+
+One single-word verb carries three overloads:
+
+```ts
+method(): void
+method(id: string): boolean
+method(ids: readonly string[]): boolean
+```
+
+- No argument applies to all.
+- One id applies to one.
+- An id list applies to those items and returns true only when all succeed.
+- Never split into `methodAll`, `methodOne`, or `methodMany`.
+- When a single item type can itself be a list/open record, declare the array overload first and document how callers express one list-valued item.
+
+## Stateful emitters
+
+An entity with lifecycle transitions, constraints, or observable operations owns an emitter by composition:
+
+1. Define `{Entity}EventMap` in `types.ts`.
+2. Add `readonly on?: EmitterHooks<{Entity}EventMap>` and `readonly error?: EmitterErrorHandler` to options.
+3. Add `readonly emitter: EmitterInterface<{Entity}EventMap>` to the interface.
+4. Store `readonly #emitter: Emitter<{Entity}EventMap>` and expose it through `get emitter()`.
+5. Initialize with both hooks and error handling: `new Emitter({ on: options?.on, error: options?.error })`. Positional constructors thread both values equivalently.
+6. Emit directly with `this.#emitter.emit(...)`; do not add a guarded `#notify`.
+7. Call `this.#emitter.destroy()` last in the entity's `destroy()`.
+
+Never inherit from `Emitter`, write delegation boilerplate, or use `Omit` to reshape it.
+
+### Listener isolation
+
+- The emitter isolates each listener; one throw never prevents sibling listeners.
+- It reports every listener throw to its own `(error, event)` error handler.
+- It never rethrows a listener error.
+- A throwing error handler is swallowed to prevent recursion.
+- Never add `observerError` or another listener-failure event to a domain `EventMap`.
+- A genuine domain I/O/transport `error` event is distinct and remains valid.
+
+### Browser/DOM variant
+
+In a pure browser-DOM environment where each entity already owns a host `Element`, the element may be the event host:
+
+- emit a typed bubbling `CustomEvent` through shared dispatch helpers;
+- subscribe with shared listener helpers;
+- bind `options.on` through one `bindEventMap` helper.
+
+Choose one event model per environment. `Emitter<TMap>` remains the default outside exclusively DOM-bound environments.
+
+### Event maps
+
+- Event names are single present-tense verbs or nouns: `start`, `connect`, `expire`, `exhaust`, `drain`, `chunk`.
+- Never publish a generic `status` event carrying a transition value; publish each transition as its own event.
+- Type errors as `unknown`.
+- Use empty tuples for signals and labeled tuple elements for IDE clarity.
+- Keep an entity's event map focused, normally four to eight events.
+
+## Validation and contracts
+
+Use four orthogonal contract mechanisms:
+
+| Surface          | Contract                                                                      |
+| ---------------- | ----------------------------------------------------------------------------- |
+| `validators.ts`  | Total `is*` guards: `(unknown) => value is T`; no coercion/side effects       |
+| `combinators.ts` | Build guards from guards: `arrayOf`, `recordOf`, `unionOf`                    |
+| `parsers.ts`     | Flat coercers returning `T \| undefined`                                      |
+| Shape DSL        | One `ContractShape` compiled into schema, guard, parser, and seeded generator |
+
+- Use plain guards/parsers for small contracts.
+- Use the shape DSL only when four-way validation/serialization/generation parity earns its complexity.
+- When `@orkestrel/contract` is declared, use its exact installed guards, parsers, combinators, outcomes, `attempt` boundary, and shape DSL wherever their semantics match. Do not maintain a local copy of those primitives.
+- A guard never throws for adversarial input, cycles, deep nesting, or hostile prototypes; return false.
+- Recursive guards track ancestors and cap depth.
+- Recursion enters only through an explicit lazy gate.
+- Non-lazy structural cycles fail at build time, not runtime.
+- Parse/guard soundness is mandatory:
+  - guard-valid input is never rejected by its parser;
+  - every parsed result satisfies its guard.
+- Derive parser and guard from one source or test the round trip.

package/dist/host/claude/rules/quality.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - 'src/**/*'
+  - 'app/**/*'
+  - 'tests/**/*'
+  - 'guides/**/*'
+  - 'package.json'
+  - 'vite.config.ts'
+  - 'tsconfig.json'
+  - '.agents/skills/**/*'
+  - '.claude/skills/**/*'
+---
+
+# Research, hardening, and completion rules
+
+## Evidence before change
+
+- Research is mandatory when the user requests it, when comparing an upstream/protocol/legacy implementation, or when current external behavior materially affects design.
+- Use current primary sources for external capabilities and exact installed declarations/guides for dependencies. Separate verified fact from inference.
+- Read authoritative types and named decision-bearing implementation files first-hand. Delegate bulk supporting context, not the owning design decision.
+- Treat existing code, tests, `old/`, branches, and copied projects as evidence rather than authority.
+- Build a capability/defect matrix before a broad API or production-readiness change. Every row ends as implement, repair, retain, or intentionally exclude with evidence.
+
+## Ecosystem reuse
+
+- Inspect declared `@orkestrel/*` packages before implementing overlapping infrastructure.
+- Prefer an exact originating primitive when semantics match; test semantic differences when they do not.
+- Downstream friction is valid evidence of a reusable upstream defect, not automatic proof. Fix the lowest package that owns the general mechanism and keep product policy downstream.
+- Update affected consumers atomically. Never add compatibility shims or dependency re-exports.
+
+## Production hardening
+
+- Translate “enterprise-grade” or “production-ready” into an explicit risk/seam matrix covering applicable inputs, states, failures, cleanup, cancellation, concurrency, resource ownership, hostile boundaries, environment isolation, serialization/restore, and package consumption.
+- Test observable invariants at each applicable seam with real implementations.
+- Use dedicated real-service projects for external model/service behavior. Require readiness and tune each request to the smallest robust proof.
+- Audit test discovery, counts, skipped/todo tests, cleanup, and assertion adequacy; passing discovered tests alone is insufficient.
+- Inspect public exports, declarations, supported runtime targets, and generated outputs.
+- Add an independent adversarial review for security, destructive paths, concurrency, protocols, or untrusted external input.
+
+## Completion
+
+- Run the applicable repository skill for comprehensive hardening, structural cleanup, contract adoption, or multi-package alignment.
+- Finish every in-scope capability and required finding now. Do not leave TODOs, deferred rows, empty branches, skipped proof, or hidden follow-up work.
+- Perform a final centralization/wrapper/test-helper/text-integrity sweep after implementation and before gates.
+- Local quality gates and relevant output inspection are required evidence.

package/dist/host/claude/rules/styles.md

@@ -0,0 +1,64 @@
+---
+paths:
+  - '**/*.{scss,css}'
+  - 'src/styles/**/*'
+  - 'tests/setupStyles.ts'
+  - 'tests/setupBrowser.ts'
+---
+
+# SCSS and CSS rules
+
+SCSS mirrors TypeScript centralization. Concrete token prefixes are project-specific; these structural rules are universal.
+
+## Centralized files
+
+| File           | Sole responsibility                                           |
+| -------------- | ------------------------------------------------------------- |
+| `_mixins.scss` | `@function` values and `@mixin` declaration emitters          |
+| `_tokens.scss` | `:root` public custom-property tokens and cascade-layer order |
+| `_theme.scss`  | Token overrides under theme selectors                         |
+| `index.scss`   | Sole compilation barrel                                       |
+
+- `_mixins.scss` emits no top-level CSS.
+- Consumers load it with `@use '../mixins' as *`.
+- Never load `mixins` from `index.scss`.
+- `index.scss` is the sole compilation barrel; it loads `tokens`, `theme`, and output partials with `@use`.
+- `_tokens.scss` is the token source of truth. Adding a token is allowed; rename/removal is breaking.
+- `_theme.scss` only retunes tokens under selectors such as `[data-theme='…']`.
+- Component partials never override global tokens.
+
+## Sass mechanisms
+
+- `@function`: pure calculation returning one CSS value.
+- `@mixin`: emits declarations and may take `@content`; owns repeated boilerplate.
+- `%placeholder`: sharing inside one partial only. It is not reachable across `@use`; cross-file reuse uses mixins.
+
+## Prohibitions
+
+- Check `_tokens.scss` before inventing a token.
+- Put global tokens in `_tokens.scss`; put truly component-scoped custom properties on the component selector.
+- Never bury tokens in unrelated partials.
+- Never use literal colors. Use `var(--token)` or `color-mix()` over tokens.
+- Never repeat per-color/per-variant blocks; drive shared structure with one `@each` over a shared list.
+- If a pattern appears in at least two partials, move it to `_mixins.scss`.
+- A one-partial pattern stays inline; do not create a mixin for one caller.
+- Never `@extend` across partials; share through tokens/mixins.
+- Never declare a `transition:` without `prefers-reduced-motion: reduce`. Use the project transition mixin, which emits both.
+- Animations include `@include reduced-motion { animation: none }`.
+- Never wrap rules in a foreign cascade layer. Each partial uses its folder's own layer.
+- Declare cascade-layer order once in the consumer entry before `@import 'tailwindcss'`, so utilities win predictably.
+
+## Naming
+
+| Kind            | Form                                                                |
+| --------------- | ------------------------------------------------------------------- |
+| Function        | lowercase kebab-case verb/noun: `tint`, `clamp`                     |
+| Mixin           | lowercase kebab-case verb/verb-noun: `transition`, `reduced-motion` |
+| Sass variable   | lowercase kebab-case; `!default` when overridable                   |
+| Custom property | project token scheme: `--{scope}-{property}[-modifier]`             |
+| Modifier class  | bare adjective/noun: `.surface`, `.muted`, `.accent`                |
+| State class     | bare adjective using the shared lifecycle vocabulary                |
+
+State classes are bare adjectives such as `.active` and `.disabled`, chosen consistently with the shared lifecycle vocabulary.
+
+The composable owns interaction state, class application, `aria-*`, and timing. The partial owns visual presentation. Their contracts are stable class names and transition tokens.

package/dist/host/claude/rules/tests.md

@@ -0,0 +1,123 @@
+---
+paths:
+  - 'tests/**/*'
+  - 'vite.config.ts'
+  - 'configs/**/*.ts'
+  - 'package.json'
+---
+
+# Testing rules
+
+## Test contract
+
+- Mirror source/application structure:
+  `tests/{src,app}/[environment]/[domain]/[Entity].test.ts`.
+- Prefer test filenames matching entrypoints: `index.test.ts` for `index.ts`, `main.test.ts` for `main.ts`.
+- Tests are deterministic: identical inputs produce identical results.
+- Keep default suites fast: timers normally use 10–50 ms and tests make no network calls.
+- Use real implementations and small scenarios. Never use mocks, behavioral fakes, module replacement, or framework spies for project-owned or integrated behavior.
+- Use recorders for calls/events, temporary resources for stateful boundaries, protocol-faithful fixture servers for deterministic network peers, and the real external service when its behavior is the claim.
+- Prefer inert customizable data/input stubs. A scripted boundary stub is allowed only when it implements the real interface/protocol minimally to drive the system under test; it never reimplements project-owned behavior or stands in for the integration being claimed.
+- Cover happy paths, error paths, empty input, boundary values, `NaN`, positive/negative zero, cycles, and Map/Set order where relevant.
+- Test observable behavior, not implementation details.
+- Use `it.todo()` only for explicitly out-of-scope roadmap work, never to complete the current request. Every `.skip` or conditional skip has a narrow verifiable applicability reason.
+- Do not create test files solely for `constants.ts`, barrels, error definitions, or `types.ts`.
+- Run the narrowest relevant Vitest project during development; do not run the entire suite casually.
+
+## Live-service tests
+
+Live external services/models are the deliberate exception to fast hermetic defaults:
+
+- Put them in a dedicated isolated Vitest project with its own setup and longer timeout.
+- Keep them out of the default run.
+- Warm and verify service readiness in setup.
+- Hard-require readiness: throw loudly; never silently skip.
+- Verify service-dependent logic through that service's project, not unrelated module tests or scattered conditional skips.
+- Tune each request to the smallest input/context/output that proves one behavior without becoming brittle or expensive.
+- Prefer semantic bounded assertions over exact generated prose. Increase context/workload only when the scenario requires it.
+
+## Shared test infrastructure
+
+Test helpers are shared infrastructure, not local test-file clutter.
+
+- Extract a fixture, recorder, event factory, async wait, renderer, scenario/data builder, protocol fixture, or DOM builder as soon as it could serve another test.
+- Any duplicate or near-duplicate helper is a defect; consolidate it into one general form.
+- Export every reusable helper, fixture type, factory, constant, and guard from setup files.
+- Test files import shared infrastructure rather than declaring local fixture factories.
+- Never reimplement a framework helper in tests or fixtures; import the real parser, signer, flattener, or other helper.
+- Prefer small customizable factories/stubs that seed inert data for a real scenario over repeated inline setup.
+- Helper names follow module-helper naming: `createRecorder`, `buildElement`, `appendItems`, `renderRows`, `waitForDelay`, `extractDetail`.
+
+Place helpers by environment:
+
+- `tests/setup.ts`: host-independent; no `node:*`, DOM, `window`, or Vue.
+- `tests/setupServer.ts`: Node-only helpers and `node:fs` loaders anchored to `WORKSPACE_ROOT`.
+- `tests/setupBrowser.ts`: DOM/Vue/browser helpers and setup CSS.
+- `tests/setupStyles.ts`: CSS/style helpers and compiled cascade.
+
+### Recorder
+
+Use a real recorder callback instead of a framework spy when only calls/arguments matter:
+
+```ts
+interface TestRecorderInterface<TArgs extends readonly unknown[]> {
+	readonly calls: readonly TArgs[]
+	readonly count: number
+	readonly handler: (...args: TArgs) => void
+	clear(): void
+}
+```
+
+### Delay
+
+Use the shared delay helper; never repeat inline timeout promises:
+
+```ts
+export function waitForDelay(ms = 0): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}
+```
+
+### Style primitives
+
+Browser/style setup exposes shared assertions/builders:
+
+`mount`, `render`, `build`, `style`, `token`, `rootToken`, `pixels`, `rgba`, `colorEqual`, `findRule`.
+
+`findRule` proves a declaration exists in the cascade; `style()` reads the resolved result.
+
+## Browser tests
+
+Use the real browser as the system under test:
+
+- Do not replace DOM events, storage, observers, viewports, layout methods, pointer, or drag APIs unless the browser genuinely lacks one.
+- Prefer real nodes, events, styles/layout, and observers.
+- Centralize event factories: `createPointerEvent`, `createDragEvent`, `typeInput`, `fireTransitionEnd`.
+- Centralize DOM builders: `createButtonElement`, `createDropdownElements`, `createModalElement`.
+- Assert DOM state, emitted events, callback records, focus, classes, attributes, and public API state.
+- Do not assert private state, internal timers, or framework scheduler internals.
+- Prefer real short timers and observable wakeups. Never replace the host clock.
+
+## Runner configuration
+
+Keep Vitest/provider configuration minimal:
+
+- Prefer defaults until a measured problem proves them insufficient.
+- Centralize provider setup in one helper/shared block.
+- Add browser/provider/teardown/timeout/parallelism/cache/launch settings only for a current verified need.
+- Avoid long browser flag lists and persistent contexts unless a test requires them.
+- For slow teardown, inspect test cleanup, open handles, file parallelism, and context churn before adding launch flags.
+- Remove exploratory settings after fixing the cause.
+- Config comments explain the current reason, not the history of failed experiments.
+
+## Discovery and adequacy audit
+
+Before acceptance:
+
+- prove every intended test file is discovered by the correct project;
+- inspect actual test counts and environments;
+- audit `.todo`, `.skip`, conditional skips, retries, and inflated timeouts;
+- confirm each assertion would fail for the defect it claims to catch;
+- confirm helpers do not reimplement production behavior;
+- confirm cleanup runs after setup or assertion failure;
+- confirm current-scope requirements have real tests rather than placeholders.

package/dist/host/claude/rules/typescript.md

@@ -0,0 +1,78 @@
+---
+paths:
+  - '**/*.{ts,tsx,mts,cts,vue}'
+---
+
+# TypeScript rules
+
+The non-negotiables in `AGENTS.md` apply without exception.
+
+## Syntax and imports
+
+- Tabs for indentation.
+- No semicolons unless ASI requires one.
+- Single quotes.
+- Named exports only, except framework-required defaults.
+- ESM imports use explicit `.js` extensions for local TypeScript modules.
+- Place `import type` declarations before value imports.
+- Do not place blank lines between consecutive imports of the same kind.
+- Use runtime `#` fields, never TypeScript `private`.
+- Accept untrusted values as `unknown`; narrow with total guards.
+- Never assert with `as` or `!`, and never suppress TypeScript/lint diagnostics.
+
+## Types
+
+- Put every reusable or public interface/type alias in the nearest authoritative `*/types.ts`.
+- Define the public contract before implementation.
+- Interface properties are readonly.
+- Public collection properties and return types use `readonly T[]`, `ReadonlyMap<K, V>`, or `ReadonlySet<T>`.
+- Parameters are never `readonly`.
+- Optional state is `T | undefined`; optional lookup failure returns `undefined`.
+- Use `null` only when an external protocol/data format gives it semantics distinct from omission.
+- A binary behavior switch is boolean; a literal union must represent real domain modes, phases, discriminants, or external values.
+
+## Immutability
+
+- Never mutate caller-owned inputs.
+- Use copy-on-write for internal state.
+- Return copies or readonly views; never leak a mutable internal reference.
+- Compute derived facts instead of persisting duplicate state.
+
+## Errors and outcomes
+
+| Condition                            | Required strategy                           |
+| ------------------------------------ | ------------------------------------------- |
+| Programmer error or invalid argument | Throw an `AppError`                         |
+| I/O/network/external operation       | Return `Result<T, E>` or throw consistently |
+| Optional missing lookup              | Return `undefined`                          |
+| Invalid input inside a guard         | Return `false`; never throw                 |
+
+Use the existing outcome contract from a declared dependency or the owning environment; do not redeclare it at each call site. When no such contract exists and adding a dependency is not authorized, define this once in the owning `types.ts`:
+
+```ts
+interface Success<T> {
+	readonly success: true
+	readonly value: T
+}
+
+interface Failure<E> {
+	readonly success: false
+	readonly error: E
+}
+
+type Result<T, E = Error> = Success<T> | Failure<E>
+```
+
+- When `@orkestrel/contract` is declared, inspect and use its exact installed `Result`, construction/narrowing helpers, and `attempt` behavior instead of duplicating them.
+- Otherwise construct and narrow through the owning environment's centralized helpers.
+- Error classes expose a machine-readable `code` and optional `context`.
+- Every public error class ships with a guard such as `isAppError` for safe `catch` narrowing.
+
+## Comments and API documentation
+
+- Comments explain why, never restate what self-explanatory code does.
+- Every public export has complete TSDoc: description, `@param`, `@returns`, and `@example` where applicable.
+- Document an options object as one `@param`; describe its short fields under `@remarks`.
+- Private methods and overload-specific notes use single-line `//` comments, not public TSDoc.
+- Do not document speculative future product behavior unless requested.
+- Never use `@internal` to hide a method; make it `#` private.