@cratis/pi 7.36.1 → 7.38.0

package/package/corpus/harnesses/copilot/instructions/pull-requests.instructions.md

@@ -0,0 +1,176 @@
+---
+applyTo: "**/*"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# How to Do Pull Requests
+
+## The description is the release note
+
+**The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up. The same contract applies to release notes typed into a manual workflow run or written straight into a release. Where it is installed, the `verify-release-notes` check enforces it on release-bound PRs into the default branch carrying `major`/`minor`/`patch` (it re-runs when the label is added); it warns on `no-release` and unlabelled PRs, which must still be written this way because any of them may become releasable. `release-action` does not run for a `no-release` PR, so `(#n)` closes nothing there. Editing the description re-runs the check. HTML comments are not shown on the release page and the check ignores them for headings, keywords and placeholders, and `release-action` removes them before publishing, so a `(#n)` only inside a comment closes nothing; the check fails it, so never put an issue reference in a comment. The template's own comment can stay: its `(#123)` examples are inline code, and the comment is not published.
+
+### Allowed shape
+
+- Follow the repository's pull request template (`.github/pull_request_template.md`) within this contract.
+- An optional summary, first, only when one cohesive theme spans the bullets: **either** a `## Summary` section (short, user-facing prose) **or** one unheaded lead paragraph (1–3 sentences), never both. `Summary` is a level-2 heading; `# Summary` is the wrong level. No bullets before the first section.
+- Then only these `##` sections, each at most once, in this order after any `## Summary`: `## Added`, `## Changed`, `## Fixed`, `## Removed`, `## Security`, `## Deprecated`. Keep only the sections that have bullets: a section holding only prose, a code example or `None.` fails the check, so delete it. `###` sub-headings inside a section are fine unless they use a forbidden name; inside a section even `### Added` is only a sub-heading, and a section itself is always level 2.
+- A `major`/`minor`/`patch` PR needs at least one bullet under an allowed section.
+- Bullets are short, self-contained and user-facing: what a consumer compiles against, runs or observes. A user-visible fix may add one sentence of root cause or regression guard, stated as observable behavior. Credit an external contributor by name or handle, unless they asked not to be named.
+- Breaking changes and upgrade actions are bullets in `## Changed` or `## Removed` that state the action. A longer migration story goes in the docs, linked by absolute URL.
+- Do not list internal plumbing (storage, converters, gRPC internals, specs, file lists, refactor narration).
+
+### Issue references
+
+| Write | Meaning |
+| --- | --- |
+| `(#351)` at the **end of the bullet that delivers it** | Delivered: in a repository released by `cratis/release-action`, it closes it at release |
+| `(part of #351)` or prose `see #351` | Related, partial or follow-up: never closes |
+| `Cratis/Repo#351` | Other repository: never closed |
+| one `(#351)` per issue, never `(#351, #352)` | `(#351, #352)` closes nothing: write `(#351) (#352)` |
+
+- Nothing but more issue references (also `(part of #n)`, `(see #n)` and `(Cratis/Repo#n)`), closing emphasis, `<br>` and sentence punctuation (a `:` may introduce nested bullets) may follow the delivering `(#n)`. Write one `(#n)` per issue: release-action only matches `(#n)`, so `(#56, #57)` closes nothing; write `(#56) (#57)`.
+- Never use a linking or closing keyword before a number, anywhere: `Close`, `Closes`, `Closed`, `Fix`, `Fixes`, `Fixed`, `Resolve`, `Resolves`, `Resolved`, `Refs`, `Ref`, `References`, also as `Keyword: #n`, with `owner/repo#n`, followed by an issue URL, and wrapped in bold, italics or a link (`**Closes** #n`, `Closes [#n](url)`, `[Closes #n](url)`, and `[Closes](url)` where the link starts a clause). A `Refs #93` line closes nothing and is not a delivery marker: write `(#93)` at the end of the delivering bullet, or `(part of #93)` if it must stay open.
+- Comment on or close an issue when the user's request includes that effect; otherwise prepare a bounded post-merge disposition without performing it. In repositories released by `cratis/release-action`, a delivered `(#n)` is closed by release-action at release, so do not close it by hand; for a `no-release` PR release-action does not run, so any disposition follows this same rule. Elsewhere, follow the repository's own release and issue-closing process.
+- Use a bare `(#n)` only for an issue this PR fully delivers. No issue means no reference. Never use a placeholder such as `(#issue)` or the template's `(#123)`, and verify every number exists in the right repository; never guess.
+
+### Forbidden anywhere outside code
+
+- **Headings** (any level, also written as HTML `<h2>`, `<b>`, `<i>` or a possibly multi-line `<summary>`, or as an `*italic*` line; a heading line is checked like any other, so a keyword, relative link or `(#n)` in one fails too) other than a first `## Summary`, such as Overview, Description, What, Why, How, Context, Changes, What changed, Test plan, Testing, Tests, Verification, Verified, Validation, Quality, Review, Notes, Notes for reviewers, Limitations, Known follow-up, Acceptance, Details, and any `#`/`##` heading not in the allowed list.
+- **Review, verification, testing and provenance notes**: `Review:`, `Reviewed:`, a stand-alone `Reviewed by` line, `Verification:`, `Tested:`, `Testing:`, `Validation:` lines that stand alone or report a result (`Tests: 400 passed`, `Review: approved`); same-provider, cross-provider, Opus-only or Anthropic-only review remarks; the review workflow having passed, returned or run; CI or gate results (`CI green`, `all tests passed`); and a line stating which agent or model wrote the description (`Generated with Claude Code`, `Co-Authored-By:`). A bullet that describes a product change and only mentions review, validation, tests or an AI model (`- Validation: rules now apply to commands (#3)`, `- Reviewed by status is now shown on the dashboard (#4)`) is fine: inside a bullet, a summary or the lead paragraph the check reads a note only when it ends the clause (`- Cross-provider review pending`).
+- **Verification and scope notes**: how or where something was checked (`verified by building …`, `verified in Storybook`, `tested locally`, `Storybook only`), what was not checked (`not yet verified`, `Not verified against a real kernel`), and results (`492/492`, `9 of 9 runs`, `Tier 1 PASS`, `0 warnings, 0 errors`, a `Local:`, `CI:`, `Checks:` or `Checked locally:` line).
+- **Reviewer, merge and deploy instructions**: `Stacked on #207`, `retarget to main once #207 merges`, `This PR should be deployed separately`, `Draft:`, `do not merge`, merge or deploy order. If a consumer must upgrade in a set order, write that as an upgrade bullet ("Upgrade the Chronicle kernel to 19.25 before this client").
+- **Provenance**: which branch, commit or build something was checked against (`verified against Arc.TypeScript main (v0.34.0)`). If compatibility matters to the reader, state it as a fact about the release: "Requires `@cratis/arc` 0.34 or later."
+- **Internal state** that is not a consumer change (for example "npm publication remains disabled").
+- **Relative links** (`](Documentation/x.md)`, `](./x)`, `](Source/...)`): they 404 on the release page. Use `https://github.com/Cratis/<Repo>/blob/main/<path>`, a `#anchor` or `mailto:`.
+- **Placeholders and transcripts**: template text, empty sections, Copilot "Original prompt" blocks, agent transcripts.
+
+Reviewer-facing information (test plan, verification, what was not verified, review provenance, stacking, merge or deploy order) goes in a **PR comment** posted right after creating the PR: `gh pr comment <n> --body-file .ai-work/pr-notes.md`. Never put it in the description, even when the PR is labelled `no-release`.
+
+### Keep the note true to the diff
+
+After merging or rebasing the base branch, and before every body edit, run `git diff --stat origin/main...HEAD`. Delete each bullet whose change is now on main through another PR, or was dropped in conflict resolution. Check every version, package name and registry against the diff and the current `.github/workflows/publish*.yml`; never name a registry the publish workflow does not push to.
+
+### Bad to good
+
+Bad (Cratis/Arc.TypeScript v0.48.0 as first published, bullets abridged):
+
+```markdown
+Arc can now construct Chronicle reactors and reducers through its own dependency injection, one scope per delivered batch, as an opt-in preview. npm publication remains disabled.
+
+## Added
+
+- Preview option `withChronicle({ ..., activateArtifactsInScopes: true })` ... (#93)
+
+See [Activate reactors and reducers in Arc scopes](Documentation/chronicle/reactors/scoped-activation.md).
+
+Review: Opus-only (same-provider) review.
+
+Refs #93
+```
+
+Good (as corrected):
+
+```markdown
+Arc can now construct Chronicle reactors and reducers through its own dependency injection, one scope per delivered batch, as an opt-in preview.
+
+## Added
+
+- Preview option `withChronicle({ ..., activateArtifactsInScopes: true })` ... See [Activate reactors and reducers in Arc scopes](https://github.com/Cratis/Arc.TypeScript/blob/main/Documentation/chronicle/reactors/scoped-activation.md). (part of #93)
+```
+
+"npm publication remains disabled" is internal status, the link was relative (it 404s on the release page), the review line is provenance for reviewers, and `Refs #93` is a keyword line. #93 was only partly delivered by this release, so its bullets say `(part of #93)`; `(#93)` would have closed it.
+
+### Before you create or edit a PR
+
+1. Run `node .cratis/ai/hooks/scripts/cratis-check-pr.mjs --body-file <file> --label <intent>`. It runs the exact `verify-release-notes` rules plus the label and diff checks, and the Bash hook runs it on `gh pr create` and `gh pr edit`.
+2. Read the body against the forbidden list and the issue table above; delete every hit and verify every issue number.
+3. Sections in order, none empty, at most one summary form; every bullet user-facing.
+4. Test plan, verification and review notes are in a PR comment.
+
+If `verify-release-notes` fails, fix it by editing the description, not by pushing code.
+
+## Commits
+
+See the full [Git Commits guide](./git-commits.instructions.md) for rules on logical grouping, message format, and staging discipline.
+
+Quick reminders:
+
+- Imperative mood: "Add author registration" not "Added author registration".
+- Each commit = one logical unit of work. No WIP commits in the final PR.
+- Never mix unrelated changes in a single commit.
+
+## Labels
+
+Confirm the current repository workflow contract before selecting release intent because release-intent labels can trigger publication. A direct request to ship with a named label authorizes applying that label and completing the repository's standard pull-request workflow, including the release it normally triggers. Do not ask for separate authorization at each step. If the user did not request shipping or publication, a proposed semantic label describes impact but does not grant authority.
+
+- Exactly one of `major`/`minor`/`patch`/`no-release`, set in the creating command (`gh pr create --label patch`), in every repository, including samples, docs and tooling repositories (`no-release` when nothing is shipped). To change intent, swap labels in one command: `gh pr edit <n> --remove-label minor --add-label patch`. Never add a second: with more than one of them, release-action releases nothing and reports `reason=error`. Re-running a `pull_request` workflow replays the original label payload, so fix a label mistake by editing the PR or pushing; a `workflow_dispatch` run needs an explicit `version` and the PR description as `release-notes`, and without notes it closes no issues.
+- Dependabot PRs carry only `no-release`. release-action never releases them, and the `major`/`minor`/`patch` Dependabot adds describe the dependency's version, not this product's.
+- Label the PR according to semantic versioning impact:
+  - **major** — breaking changes to public APIs
+  - **minor** — new features, new slices, non-breaking additions
+  - **patch** — bug fixes, refactoring with identical behavior
+
+### A major release needs a human's explicit go-ahead
+
+A `major` label is the one release-intent label a ship request does not, by
+itself, authorize through to merge. Breaking a public API is the most
+consequential and hardest-to-reverse thing a release does — every downstream
+consumer eventually has to act on it — so it gets a checkpoint the other two
+intents do not.
+
+- Prepare the branch, commits, push, and PR carrying the `major` label exactly
+  as any other ship request would.
+- Before merging, stop and ask a human to confirm the major bump specifically:
+  name the exact breaking change(s), who is affected and how, and the
+  resulting version number. A generic "ready to ship?" is not this checkpoint —
+  say plainly that this release breaks compatibility and needs a yes.
+- Proceed to merge only on an explicit, affirmative answer to that question.
+  A prior general instruction to "ship" or "land this" does not answer it,
+  even when it named `major` as the intended label.
+- This checkpoint is per release, not per conversation — a human confirming
+  one major release does not pre-authorize the next one.
+
+This narrows the general ship-changes authorization in
+[`ship-changes.prompt.md`](../../../prompts/ship-changes.prompt.md) for exactly this
+label; every other step of that workflow proceeds under its existing
+authority.
+
+### A pull request that changes nothing outward-facing carries `no-release`
+
+**If nothing in the PR can change what a consumer compiles against, runs, or observes, propose repository-supported non-release intent, ordinarily `no-release`** — not `patch`. Confirm that the current workflow supports the label, requires exactly one release-intent label, and suppresses publication as intended before applying it with authorization.
+
+Where the repository requires release intent, `no-release` is a decision, not an omission. Missing required labels are blockers, not a reason to bypass the check.
+
+This covers, whenever the PR touches *only* these:
+
+- **Documentation** — anything under `Documentation/**`, READMEs, the `.cratis/ai/` corpus.
+- **CI and repository automation** — `.github/workflows/**`, `.github/scripts/**`, `.github/CODEOWNERS`, issue/PR templates.
+- **Tests and specs** — `*.Specs/**`, `when_*/**`, `for_*/**`, `Integration/**`, and test-only fixtures.
+- **Build and tooling configuration** that produces no shipped artifact difference — lint config, editor config, local scripts.
+
+The test is **outward-facing effect, not file location**. A change under `Source/**` that only touches specs is not shippable; a one-line change to a published package's behavior is, however small. If a consumer could not tell the difference by upgrading, there is nothing to version. When genuinely unsure, ask rather than defaulting to `patch` — an unnecessary release is not free: it burns a version number, ships release notes describing nothing, and buries the releases that matter.
+
+A non-release pull request must satisfy the relevant required checks like any other. Confirm label acceptance and publication suppression against the current workflow contract; do not assume external CI or API state.
+
+### Group small related changes into one pull request
+
+Do not open a pull request per task when the tasks belong to the same body of work. Several small merged PRs become several releases, and a stream of near-empty patch releases makes the release history useless for the people it is written for. Collect related work — a set of CI gates, a group of fixes in one area, the steps of one refactor — onto **one branch, as separate commits**, and open **one** pull request. Commits stay one-logical-unit-each; the pull request is the release boundary, and the release boundary should be a coherent, describable change.
+
+**Before consolidating open PRs, review each PR’s release intent and workflow effects.** Integration may trigger completion/publication behavior on an absorbed PR. Use supported non-release intent where appropriate. A direct request to consolidate the named pull requests authorizes the necessary relabeling and merge; it does not authorize unrelated notifications.
+
+Split into separate pull requests when the changes are genuinely unrelated, when one is urgent and the others are not, or when one is risky enough to want its own revert.
+
+## Quality Gates
+
+Documentation-only changes use repository-supported non-release intent, ordinarily `no-release`; confirm the workflow contract rather than assuming a label or API state. Run relevant content, link, frontmatter, and corpus checks instead of unrelated application builds, and satisfy every repository-required check, including release-intent checks where supported. Documentation is never a blanket exemption from red CI.
+
+**`no-release` does not otherwise excuse a PR from this section.** A CI, tooling, or spec-only pull request ships nothing, but it is exactly the kind of change that can break the build or the pipeline for everyone else — a broken workflow or a deleted spec does its damage without ever being released. Hold it to every gate below.
+
+Before marking code/automation work ready, select the affected-project gates that apply from the following list; run wider checks for cross-cutting changes and repository-required merge/release gates:
+
+- `dotnet build` — zero errors, zero warnings
+- `dotnet test` — all specs pass
+- `yarn lint` — zero errors
+- `npx tsc -b` — zero TypeScript errors
+- Code follows all project coding standards and conventions
+- **Required CI checks pass.** After an authorized push, inspect checks and failure logs. Diagnose within a bounded attempt, fix in-scope causes, and re-run relevant gates after each fix. Report unrelated/environmental failures and missing authority as blockers rather than retrying indefinitely or silently waiving required checks. If a release job fails after a concurrent merge (the release for the tag exists for another commit), re-run it: it releases under the next version (release-action v1.4.2 fails the job rather than reporting success).

package/package/corpus/harnesses/copilot/instructions/react.instructions.md

@@ -0,0 +1,203 @@
+---
+applyTo: "**/*.tsx, **/Components/**/*.ts"
+profile: application
+paths:
+  - "**/*.tsx"
+  - "**/Components/**/*.ts"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# React + Arc + Cratis Components
+
+The frontend is React + TypeScript in MVVM style, composed from **Cratis Components** on top of **Arc-generated proxies**. Cratis Components (4.x) owns its markup, styling contract and behavior — there is no vendor component library underneath to reach for; React Aria is an internal detail you never import. For component structure, styling, and icons see [components.md](./components.instructions.md); for dialogs see [dialogs.md](./dialogs.instructions.md). This rule covers MVVM, queries, and commands.
+
+## The proxy boundary
+
+`dotnet build` (Debug) generates a typed TypeScript proxy per command and query, emitted next to the slice's `.cs`. React imports those proxies and calls their static hooks. **Backend before frontend, always** — the proxies don't exist until the backend compiles. **Never edit a generated proxy** (`// @generated by Cratis` header) — fix the C# source and rebuild.
+
+## MVVM
+
+Move behavior out of the render function. Two accepted idioms:
+
+- **`withViewModel`** from `@cratis/arc.react.mvvm` — for command/query orchestration, long-lived UI state, and workflow components that benefit from observable class state.
+- **A tested pure state module/helper** — for deterministic page/form state that doesn't need MobX. The component stays rendering + event wiring; the module owns derived state, filtering/sorting, wizard steps, command-value derivation, and has BDD specs (see [frontend-testing.md](./frontend-testing.instructions.md)).
+
+Don't leave complex behavior inline. Trivial presentational leaf components need no view model.
+
+```ts
+import { injectable } from 'tsyringe';
+
+@injectable()
+export class <Entity>ListingViewModel {
+    selectedId: string | null = null;
+    select(id: string) { this.selectedId = id; }
+}
+```
+
+```tsx
+import { withViewModel } from '@cratis/arc.react.mvvm';
+
+export const Listing = withViewModel(<Entity>ListingViewModel, ({ viewModel }) => (
+    /* read viewModel state inside JSX; call viewModel methods */
+));
+```
+
+**View-model rules:**
+- Pure TypeScript classes — no JSX, never store React state, never call React hooks (`useIdentity`, `useNavigate`) inside one — inject the Cratis abstraction instead.
+- Fields are auto-observable (`makeAutoObservable` is applied by `withViewModel`); no `@observable` on plain assignments.
+- Inject services via the primary constructor (`@injectable` / tsyringe).
+- A non-trivial view model must be constructible directly in a spec and covered with BDD specs.
+
+### When to extract a view model
+
+Extract as soon as a component has **any** of: 3+ `useState`, any `useCallback` beyond a trivial inline handler, any `useEffect` that synchronizes state, derived values computed from other state (use a getter), or state shared via prop drilling.
+
+### MobX reactivity
+
+- **Dereference late** — read `viewModel.property` *inside* JSX; never destructure observables at the top of the component body (the captured value won't track changes).
+- **Computed getters** for derived state (auto-`computed`) — not `useMemo` in the component.
+- **`useCallback`/`useMemo` are unnecessary in `withViewModel` components** — the render is wrapped in `Observer`. Their presence signals state that belongs in the view model. (This does *not* apply to plain functional components using proxy hooks directly. A plain component reaching for `useCallback` to stabilize a handler is a signal that handler belongs in a view model or tested state module.)
+- **Observable arrays into raw children** — passing `viewModel.items` (an observable array) to a *raw non-observer* child needs `viewModel.items.slice()` to materialize a plain array. Uncommon in practice — prefer `DataTableForObservableQuery`, which handles reactivity internally.
+
+### Props / route / query params in view models
+
+| Need | Mechanism |
+|---|---|
+| Props that change after mount | implement `IHandleProps<TProps>` → `handleProps(props)` (called on initial mount **and** every props change) |
+| Props set once at mount | `@props readonly componentProps: TProps` |
+| Route params | `@params readonly routeParams: RouteParams` — put `@field` on each property |
+| Query-string params | `@queryParams` |
+
+`@field` on each route/query-param property is what makes Arc's JSON serializer convert the URL **strings** to the property's real type — **without `@field`, the values stay strings**.
+
+### Injectable abstractions (never touch browser/React globals in a view model)
+
+| Interface | Package | Replaces |
+|---|---|---|
+| `IMessenger` | `@cratis/arc.react.mvvm/messaging` | cross-component selection (list↔detail) — not React Context |
+| `IDialogs` | `@cratis/arc.react.mvvm/dialogs` | imperative confirmation/busy dialogs from a view model |
+| `IIdentityProvider` | `@cratis/arc/identity` | identity in a view model (not the `useIdentity` hook) |
+| `ILocalStorage`, `INavigation` | `@cratis/arc.react.mvvm/browser` | `localStorage`, URL navigation |
+| `IViewModelDetached` | `@cratis/arc.react.mvvm` | teardown (`detached()`) for subscriptions/timers |
+
+These are registered automatically by `withViewModel` and injected via the primary constructor. Concrete usage:
+
+- **`IMessenger`** — messages are plain classes; `_messenger.publish(new <Entity>Selected(id))` and `messenger.subscribe(<Entity>Selected, ({ id }) => ...)`. For scoped delivery, the messenger from `@cratis/arc/messaging` (distinct from `…mvvm/messaging`) resolves the nearest scope and falls back to root: a `<MessengerScope>` trickles `publish()` **down** into nested scopes by default (`trickleDownToChildren`, default `true`) and bubbles **up** only when `bubbleToParent` is set (default `false`) — both are props on `MessengerScope` / properties on the messenger, not options on `publish()`. Use the default `IMessenger` unless you genuinely need scoping.
+- **`IDialogs`** — `await _dialogs.showConfirmation(title, message, DialogButtons.YesNo)` returns a `DialogResult`. For user-triggered dialogs that open React command dialogs, use `useDialog` in the component, not `IDialogs`.
+- **`IIdentityProvider`** — `await _identityProvider.getCurrent<TDetails>()`. Use the `useIdentity()` hook only in functional components without a view model.
+- **`ILocalStorage`** — `setItem(key, value)` / `getItem(key)`; **`IViewModelDetached.detached()`** runs on unmount (`detached() { this._subscription?.unsubscribe(); }`).
+
+**Decorator prerequisite:** `experimentalDecorators` + `emitDecoratorMetadata` + `reflect-metadata` must be wired (tsconfig + the build) for `@injectable`/`@props`/`@params`/`@field` to work — don't change them.
+
+## Queries
+
+A typed proxy class is generated per query. Pick the hook:
+
+| Hook | When |
+|---|---|
+| `<Query>.use(args?, sorting?)` | standard — returns `[result, perform, setSorting]`, re-renders on change |
+| `<Query>.useSuspense(...)` | suspense-aware — throws while loading; wrap in `<QueryBoundary>` |
+| `<Query>.when(condition).use(args)` | conditional — only fires when `condition` is true (don't wrap a hook in `if`) |
+| `<Query>.useWithPaging(pageSize, args?, sorting?)` | server-side paging (backend returns `IQueryable<T>`) |
+| `<Query>.useSuspenseWithPaging(pageSize, ...)` | suspense + paging |
+| `<ObservableQuery>.use(...)` | live observable (`ISubject<T>` backend) pushed over SSE/WebSocket |
+| `<ObservableQuery>.useChangeStream(args?, getKey?, ...)` | item-level add/replace/remove deltas |
+
+**Return-tuple shapes** (load-bearing — the observable variants have no `perform`):
+
+| Hook | Returns |
+|---|---|
+| `<Query>.use(args?, sorting?)` | `[result, perform, setSorting]` |
+| `<Query>.useSuspense(...)` | `[result, perform, setSorting]` |
+| `<Query>.useWithPaging(pageSize, args?, sorting?)` | `[result, perform, setSorting, setPage, setPageSize]` |
+| `<Query>.useSuspenseWithPaging(pageSize, ...)` | `[result, perform, setSorting, setPage, setPageSize]` |
+| `<ObservableQuery>.use(...)` | `[result, setSorting]` for an enumerable query; `[result]` for a single-instance one — **no `perform`** |
+| `<ObservableQuery>.useChangeStream(args?, getKey?, sorting?)` | `ChangeSet<T> { added, replaced, removed }` |
+
+`result.paging` = `{ page, size, totalItems, totalPages }` (zero-based `page`). Read models returning `IQueryable<TReadModel>` get automatic server-side paging/sorting — use it whenever a list can grow.
+
+- **`useChangeStream` `getKey`:** without `getKey`, removed items can't be identified — everything shows up as `added`. `getKey` enables `replaced` detection. Change streams exist only on observable queries returning `IEnumerable<T>`.
+- **Conditional:** `<Query>.when(!!id).use({ id: id ?? '' })` — when `condition` is false no request/subscription is made and the hook returns `QueryResultWithState.empty()` (`hasData: false`, empty `data`); guard with `result.hasData`. `.when()` works with paging, suspense, and observable variants too.
+- **Suspense:** `useSuspense()` throws a promise while loading and a typed error on failure — it **must** render inside a `<QueryBoundary>` (combines `<Suspense>` + `QueryErrorBoundary`) or React surfaces the thrown promise as an unhandled rejection. `useSuspense()` **re-suspends** on `refresh()`/`setSorting()`/`setPage()` (the cache entry is cleared). `<QueryBoundary onError={({ isQueryFailed, isQueryUnauthorized, error, reset }) => ...}>` exposes the failure; `(error as QueryFailed).exceptionMessages` carries diagnostics. In test teardown clear the caches with `clearSuspenseQueryCache()` / `clearSuspenseObservableQueryCache()` (`@cratis/arc.react/queries`).
+- **`QueryScope`** + `useQueryScope()` (`@cratis/arc.react/queries`): `<QueryScope setIsPerforming={...}>` aggregates one `isPerforming` flag across the queries inside it — they register automatically (no manual add); scopes nest (inner registers with the nearest outer).
+
+## Commands
+
+A typed proxy class is generated per command. For programmatic execution:
+
+```tsx
+const [command, setCommandValues, clearCommandValues] = Command.use();   // 3-tuple
+command.someField = value;                  // or setCommandValues({ ... })
+const result = await command.execute();
+```
+
+Inside dialogs, use `CommandDialog` + CommandForm fields rather than driving the command by hand — see [dialogs.md](./dialogs.instructions.md).
+
+### Read `CommandResult` by the granular flag — not just `isSuccess`
+
+| Flag | Meaning | UX response |
+|---|---|---|
+| `isSuccess` | `isAuthorized && isValid && !hasExceptions` | happy path |
+| `isAuthorized` | `[Roles]`/policy rejected | redirect to login / "not allowed" |
+| `isValid` | validation failed — `validationResults` has per-field messages | render inline field errors |
+| `hasExceptions` | `Provide()`/`Handle()` threw — `exceptionMessages` carry diagnostics | generic error toast + log; never show stack traces |
+
+`CommandDialog` handles all of this automatically; the flags matter most when executing a command **outside** a dialog. `validate()` returns the same shape with `response == null` (handler did not run). `result.validationResults` is a `ValidationResult[]` of `{ severity, message, members: string[], state, reason, reasonDetail? }` — `members` names the affected properties — render per-field UI from it, but **never branch on raw `.message` text**. `exceptionMessages`/`exceptionStackTrace` are for logging, never for users.
+
+Out-of-dialog execution branches in this order:
+
+```tsx
+const result = await command.execute();
+if (!result.isAuthorized) { redirectToLogin(); return; }
+if (!result.isValid)      { /* validationResults → inline field errors */ return; }
+if (result.hasExceptions) { toast.error({ title: 'Something went wrong' }); console.error(result.exceptionMessages); return; }
+// happy path — refresh queries, close, etc.
+```
+
+`toastCommandResult(result, opts)` from `@cratis/components/Notifications` collapses this whole branch into one call (with a `<Toaster />` mounted) — success/not-authorized/validation/exception → the right toast, no stack traces shown.
+
+### Command helpers
+
+- **`useCommandInstance<TCommand>()`** — inside a `CommandForm`/`CommandDialog`, read the live reactive command instance from context for dependent fields (no argument; the type parameter is the command type) (read it; never mutate — mutations go through field bindings).
+- **`onBeforeExecute`** is a **transformer**: it receives the current values and **must return them** (mutated or not). It runs only on submit — never use it to seed required values (use `initialValues`).
+- **`initialValues`** = synchronous baseline (also drives change tracking); **`currentValues`** = reactive overlay for async/late-loading values (e.g. from a query).
+- **`asCommandFormField<P>(Component, opts)`** — wrap a custom input (rich text, address picker) so it participates in `CommandForm` with validation/error wiring.
+- **`CommandScope`** + `useCommandScope()` (`@cratis/arc.react/commands`) — aggregate state across multiple commands (and queries) on one screen; commands and queries rendered inside the scope register themselves (the `ICommandScope` API also exposes `addCommand`/`addQuery`/`addChildScope` for manual registration); scopes nest (a child reports up to its parent); injectable as `ICommandScope` (nearest enclosing scope). Props: `setHasChanges`, `setIsPerforming`, `onBeforeExecute`, `onSuccess(cmd, result)`, `onFailed`, `onException`, `onUnauthorized`. `ICommandScope` members: `hasChanges`, `isPerforming`, `hasValidationFailures`, `hasExceptions`, `validationFailures`/`exceptions` (this scope), `aggregatedValidationFailures`/`aggregatedExceptions` (scope + children), `execute()` (runs only commands with changes), `revertChanges()`, `parent`.
+
+At Arc v22.75.0 `CommandForm` defaults to safe exception text rather than raw
+server messages; customize with `exceptionMessage` or `exceptionDisplayComponent`
+(`ExceptionDisplayProps`). `showErrors={false}` hides built-in display. Dynamic
+accessors need explicit `fieldName`; custom field validation failures block submit.
+
+### `<Arc>` global configuration
+
+Top-level provider for microservice name and API base path. Config props (with defaults):
+
+| Prop | Default | Notes |
+|---|---|---|
+| `apiBasePath` | — | Backend API prefix; `<Arc basePath>` is deprecated, not router configuration |
+| `detailsType` | — | Constructor for typed identity details |
+| `httpHeadersCallback` | — | returns `HeadersInit` merged into every request (bearer/tenant headers) |
+| `queryTransportMethod` | `ServerSentEvents` | SSE is capped at 4 connections on HTTP/1.1 |
+| `observableQueryTransferMode` | `Delta` | `Delta` = server ChangeSet/client diff; `Full` = all items as `added` |
+| `queryConnectionCount` | `1` | hub connection slots |
+| `queryDirectMode` | `false` | direct per-query connection — dev use only |
+
+`QueryTransportMethod` imports from `@cratis/arc/queries` and `ObservableQueryTransferMode` from `@cratis/arc`; `Arc` from `@cratis/arc.react`. Reach `arc.reconnectQueries()` via `useContext(ArcContext)` and call it after login/logout to re-establish observable connections.
+
+## Composition
+
+- Single responsibility — if you write a `// Section` comment inside a component, that section is its own component. Parent owns state; children receive props.
+- Single-file component → in the slice folder; multi-file → a folder named after the component with an `index.ts` re-export.
+- A `.tsx` belongs in the slice folder it implements — never one level up. A feature's pass-through layout renders only `<Outlet />`.
+
+## Styling default
+
+Default to **Cratis Components with the `--cratis-*` tokens** (`var(--cratis-surface-*)`, `var(--cratis-primary-color)`, `var(--cratis-text-color)`; `pt`/`data-cratis-part` when you must reach a part) — see [components.md](./components.instructions.md). Tailwind is **not** the Cratis default: it is one supported way to *write* the CSS that maps a product's design onto those tokens. Never hard-code hex/`rgb()` for chrome.
+
+## See also
+
+- [components.md](./components.instructions.md) — component structure, CSS, `--cratis-*` tokens and parts, icons, Storybook.
+- [dialogs.md](./dialogs.instructions.md) — `CommandDialog` / `Dialog` / `StepperCommandDialog` rules.
+- [frontend-quality.md](./frontend-quality.instructions.md) — engineering bar; [frontend-testing.md](./frontend-testing.instructions.md) — BDD specs.
+- [typescript.md](./typescript.instructions.md) — TS style.