@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/rules/concepts.md

@@ -0,0 +1,115 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+---
+
+# Concepts — Strongly Typed Domain Values
+
+## Why
+
+A primitive such as `Guid` or `string` does not tell the compiler whether a
+value is an `AuthorId`, `UserId`, or `InvoiceNumber`. A Cratis concept gives a
+meaningful value its own type and keeps that meaning in method signatures,
+serialization, validation, events, and read models.
+
+Use a concept for a real domain value, not mechanically for every primitive in a
+DTO or framework API. An enum already represents a closed domain concept and
+does not need a `ConceptAs<T>` wrapper.
+
+## Product contracts
+
+- A value concept derives from `ConceptAs<T>` in `Cratis.Fundamentals`.
+- A value actually used as a Chronicle event-source/stream identity derives from
+  `EventSourceId<T>` in `Cratis.Chronicle`.
+- An arbitrary entity ID that does not identify a Chronicle stream remains a
+  value concept; do not derive it from `EventSourceId<T>` merely because its name
+  ends in `Id`.
+- Both generic bases require an underlying type implementing `IComparable`.
+
+## Value concept rules
+
+- Use a positional record containing exactly one wrapped value. Fundamentals
+  serialization assumes a single-value concept; do not add extra properties.
+- `ConceptAs<T>` supplies concept → `T` conversion.
+- Add `T` → derived concept conversion only when it improves the domain API. It
+  is optional, not a framework requirement.
+- `ConceptAs<T>` rejects a null wrapped value. Use a nullable concept reference
+  such as `AuthorName?` when absence is valid.
+- `NotSet` or `Empty` is optional domain policy. Add one only when the backing
+  value is impossible or explicitly reserved in that domain. Do not assume
+  empty string, zero, or `Guid.Empty` is universally invalid.
+- Mark a concept that holds **personal data** `[PII]` and one that holds a
+  **secret** `[NotAudited]`. Both markings travel with the type, so marking it
+  once covers every command and event that uses it - which is the point of
+  having the concept. A command's property values are written to the causation
+  chain of every event it appends, so an unmarked `ApiKey` or `AccessToken`
+  concept reaches the event log in the clear and stays there. The two are not
+  interchangeable: `[PII]` also encrypts and enrolls the value in erasure, which
+  is wrong for a password, and `[NotAudited]` does nothing for an erasure
+  request, which is wrong for a name.
+
+```csharp
+public record AuthorName(string Value) : ConceptAs<string>(Value)
+{
+    public static implicit operator AuthorName(string value) => new(value);
+}
+```
+
+## Chronicle stream identity rules
+
+```csharp
+public record AuthorId(Guid Value) : EventSourceId<Guid>(Value)
+{
+    public static AuthorId New() => new(Guid.NewGuid());
+    public static implicit operator AuthorId(Guid value) => new(value);
+}
+```
+
+- `New()`, primitive → derived ID conversion, and sentinels are optional domain
+  conveniences; `EventSourceId<T>` does not create an arbitrary derived type.
+- The exact `EventSourceId<T>` base supports conversions among its underlying
+  `T`, string, typed ID, and untyped `EventSourceId`, but those operators do not
+  construct your derived domain record from every source form.
+- String and Guid are the safest round-trip primitives. Other comparable values
+  rely on Chronicle conversion behavior and require focused verification.
+- Pass the identity explicitly to Chronicle append/read operations. Declaring an
+  `EventSourceId<T>` property does not select the stream.
+- Do not put `[Key]` or `[Subject]` on an `EventSourceId<T>`-derived member;
+  Chronicle analyzer `CHR0026` reports it.
+- Do not put `[PII]` on an event-source ID; analyzer `CHR0034` rejects it.
+  Sensitive natural identifiers use a random surrogate stream ID and a separate
+  compliance-managed value.
+- `EventSourceId.Unspecified` is the untyped string-backed sentinel. Typed empty
+  or zero values convert to real specified stream IDs and are not equivalent to
+  `Unspecified`.
+
+## Application placement convention
+
+In a Cratis application, place a concept with the feature/module that owns its
+meaning rather than in a generic `Concepts/` folder. Put genuinely cross-feature
+concepts in `Common/`. Do not introduce a top-level `Features/` wrapper.
+
+This is a Cratis application convention, not a Fundamentals or Chronicle API
+contract. Framework and client repositories follow their own structure.
+
+## Promote a value deliberately
+
+Promote a value when its meaning or cross-cutting characteristics must travel
+with it—for example validation, compliance classification, or a domain-specific
+format. Reuse an existing shared concept when it already owns that meaning.
+
+## Call-site guidance
+
+Use the constructors, conversions, factories, or sentinels the domain type
+actually provides. Do not require `NotSet`, `New()`, or a reverse conversion on
+every concept. If a sentinel exists, reference the named sentinel rather than
+reconstructing its backing primitive.
+
+## Geospatial values
+
+Use GeoJSON types from `Cratis.Geospatial`: `Point` for a location,
+`LineString` for a route, and `Polygon` for an area. Do not use the removed
+experimental `Coordinate` type. Model geospatial absence according to the
+owning domain contract; do not invent a nullable event payload that conflicts
+with Chronicle event rules.

package/package/corpus/rules/csharp.md

@@ -0,0 +1,269 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+---
+
+
+# C# Conventions
+
+The goal is minimal ceremony, maximum clarity. Modern C# (13+) gives us records, primary constructors, pattern matching, and file-scoped namespaces — use them everywhere. The less boilerplate in a file, the faster a reader can understand what it *does*.
+
+## Building
+
+- Use `dotnet build` from the command line.
+- Use `dotnet format` to format code.
+- Use `dotnet test` to run tests.
+
+## Formatting
+
+These rules exist so that every file in the codebase reads the same way. When formatting is consistent, code review focuses on logic, not style.
+
+- Apply code-formatting style defined in `.editorconfig`.
+- Use file-scoped namespace declarations — one less level of indentation for the entire file.
+- Use single-line `using` directives, sorted alphabetically.
+- Never qualify a type that is already unambiguously in scope via a `using` directive. When two `using` directives introduce conflicting type names, qualify only the conflicting occurrences using the shortest unambiguous path (e.g. `Concepts.Events.Foo` or `Contracts.Events.Foo`) — do not add `using` aliases for every conflicting type.
+- Insert a blank line before the opening `{` of every code block (`if`, `for`, `foreach`, `try`, `using`, etc.).
+- Ensure the final `return` statement of a method is on its own line.
+- Use pattern matching and switch expressions wherever possible — they are more readable and the compiler verifies exhaustiveness.
+- Use `nameof` instead of string literals — it survives refactoring.
+- Place private class declarations at the bottom of the file — public API first, implementation details last.
+
+## Language — American English Only
+
+All identifiers, comments, XML docs, and string literals must use **American English** spelling (initialize, serialize, behavior, color, organization, center, modeling, dialog, license, judgment, gray). See [general.md](./general.md) for the full guidance.
+
+## Naming
+
+- PascalCase for type names, method names, and public members.
+- camelCase for private fields and local variables.
+- Prefix private fields with `_` (e.g. `_myField`).
+- Prefix interface names with `I` (e.g. `IMyService`).
+
+## Code Style
+
+Every rule here reduces noise. `var` avoids redundant type repetition. Expression bodies eliminate braces for trivial members. Primary constructors remove the constructor-plus-field ceremony.
+
+- Prefer `var` over explicit types — the right side of the assignment already tells you the type.
+- Use expression-bodied members for simple methods and properties.
+- Favor primary constructors for all types — they eliminate field declarations for injected dependencies.
+- Use string interpolation instead of `string.Format()` or concatenation.
+- Favor collection initializers and object initializers.
+- Use `IEnumerable<T>` for collections that are not modified; never return mutable collections from public APIs.
+- Prefer LINQ (`.Where`, `.Any`, `.Select`, `.FirstOrDefault`) over a `foreach` that filters inside its body with an `if`/`continue` or an early `return` — put the filter in the query so the intent is explicit (`items.Where(predicate)`, `return items.Any(predicate);`). Reserve `foreach` for genuine iteration with side effects. (Filtering inside a loop is what the analyzers flag as a "missed opportunity to use Where".)
+- Don't use regions — they hide code instead of organizing it. If a file needs regions, it needs refactoring.
+- Never add postfixes like `Async`, `Impl`, `Service` to class names — they add noise without information.
+- For types with no implementation body, omit the braces (e.g. `public interface IMyInterface;`).
+- Prefer `record` types for immutable data structures (events, commands, read models, concepts) — they give you value equality, immutability, and concise syntax for free.
+
+## Nullable Reference Types
+
+Embrace the type system — it is the first line of defense against null-related bugs. When it says something cannot be null, trust it.
+
+- Use `is null` / `is not null` — never `== null` / `!= null`.
+- Trust the C# null annotations; don't add defensive null checks when the type system guarantees a value.
+- Add `!` operator where nullability warnings occur and you are certain the value is non-null.
+- Use `is not null` checks before dereferencing potentially null values.
+
+## XML Documentation
+
+XML doc comments are the public API's first impression. They must be multiline — never cram `<summary>` onto a single line. Every public type, method, property, and operator must have XML docs.
+
+- Always use **multiline** `<summary>` tags — opening and closing tags on their own lines:
+
+  ```csharp
+  /// <summary>
+  /// Represents the unique identifier of a project.
+  /// </summary>
+  ```
+
+- **Never** use single-line summaries:
+
+  ```csharp
+  // ❌ Wrong
+  /// <summary>Represents the unique identifier of a project.</summary>
+  ```
+
+- Every method or operator with parameters **must** include `<param name="...">` for each parameter.
+- Every method or operator that returns a value (non-void) **must** include `<returns>`.
+- Every method that throws must document the exception with `<exception cref="...">` tags.
+- Use `<see cref="..."/>` and `<paramref name="..."/>` to cross-reference types and parameters.
+- Keep summaries concise and purposeful — only document when it adds understanding beyond the name itself.
+
+Example:
+
+```csharp
+/// <summary>
+/// Represents an instance of <see cref="ICommandFilters"/>.
+/// </summary>
+/// <param name="filters">The collection of <see cref="ICommandFilter"/> to use for filtering commands.</param>
+[Singleton]
+public class CommandFilters(IInstancesOf<ICommandFilter> filters) : ICommandFilters
+{
+    /// <summary>
+    /// Filters the command execution through all registered command filters.
+    /// </summary>
+    /// <param name="context">The <see cref="CommandContext"/> to filter.</param>
+    /// <returns>A <see cref="CommandResult"/> representing the aggregated filter outcome.</returns>
+    public async Task<CommandResult> OnExecution(CommandContext context)
+    {
+        // ...
+    }
+}
+```
+
+## Exceptions
+
+Every exception type in the codebase should communicate *what went wrong* in domain terms. Built-in types like `InvalidOperationException` tell you nothing about the problem — a custom `AuthorAlreadyRegistered` tells you everything.
+
+- Use exceptions for exceptional situations only — never for control flow.
+- Always create a custom exception type that derives from `Exception`.
+- Never use built-in exception types (`InvalidOperationException`, `ArgumentException`, etc.).
+- Never suffix exception class names with `Exception` — `AuthorNotFound` reads better than `AuthorNotFoundException`.
+- Always provide a meaningful message when throwing.
+- Add XML doc on the exception type starting with "The exception that is thrown when ...".
+- Never write an empty or silently-swallowing `catch` block. Handle the exception, log it, or let it propagate. When ignoring is genuinely correct, use an exception filter (`catch (SomeException) when (…)`) with a body that states the decision (a comment and/or a fallback) — never a bare `catch { }`.
+
+## Dependency Injection
+
+The framework discovers and wires dependencies by convention. Explicit registration is the exception, not the rule.
+
+- Prefer constructor injection; avoid `IServiceProvider` directly (service locator anti-pattern).
+- For singletons, use the `[Singleton]` attribute — no explicit registration needed.
+- Systems with a convention of `IFoo → Foo` do not need to be registered explicitly.
+- Command/query `Handle()` method parameters are automatically resolved from DI by type.
+
+### Service lifetimes — `[Singleton]` is a narrow choice, not the default
+
+**Assume every application you build is multi-tenant.** Not "design for it later" — assume it now, even when the deployment ships with a single tenant and no tenant resolution configured. A single-tenant application is a multi-tenant one with one tenant in it, and the code shape that serves both is the same shape. The code shape that serves only one has to be found and rewritten later, from the far side of a data migration, under production. The same reasoning applies to the signed-in user: an application always has one, and a service that remembers *which* one will eventually answer for the wrong person.
+
+That gives one rule with two faces:
+
+> **A singleton may not depend on anything that belongs to a tenant, a user, or a request.**
+
+These resolve **per scope**, and the scope is what carries the tenant — so none of them may be injected into a `[Singleton]`:
+
+| Off limits in a singleton | Why |
+| --- | --- |
+| `IEventStore` — and everything off it: `IEventLog`, `IReadModels`, `IConstraints`, `IEventTypes`, `IProjections`, `IReducers`, `IPII` | resolved for the scope's namespace |
+| `IMongoCollection<T>`, `IMongoDatabase`, `IMongoClient` | the database name is resolved per scope from the current tenant |
+| An EF Core `DbContext` | scoped for the same reason, plus it is not thread-safe |
+| A read model injected directly by key | same scope, same binding |
+| Any held tenant, principal, claims, correlation id, or `HttpContext` **value** | belongs to one request and outlives it in a singleton |
+
+A `[Singleton]` taking one of these is a **captive dependency**: the container hands it the *root* scope's instance and keeps it for process lifetime. The root scope has no request, so it resolves no tenant — every read and write goes to the default namespace forever, regardless of who is asking.
+
+**It does not throw. It returns nothing.** A query against the wrong namespace hits a database that exists and is empty, so the caller gets an empty collection, a `null` read model, or a default-valued options object, and carries on. The application starts, the pages render, the build is green, and the configuration a tenant spent an afternoon entering is simply not there. It is also invisible while there is only one tenant — every symptom appears on the day a second one arrives.
+
+**What to use instead.** Default to the convention (transient), which inherits the resolving scope's tenant for free, or `[Scoped]` when a service must be shared within one request. Reserve `[Singleton]` for things that are genuinely process-wide and hold no tenant-, user-, or request-bound state: `IInstancesOf<T>` aggregators, HTTP client wrappers, `IOptions<T>` readers, pure computation, framework plumbing.
+
+When something must be a singleton and still needs data — a hosted service, a dispatcher, a poller — inject `IServiceScopeFactory` and open a scope per unit of work:
+
+```csharp
+// ❌ Wrong — IEventStore is scoped; this captures the root scope's default namespace forever.
+[Singleton]
+public class DigestSources(IEventStore eventStore) : IDigestSources
+{
+    public Task<DigestConfiguration?> GetCurrent() =>
+        eventStore.ReadModels.GetInstanceById<DigestConfiguration>(DigestId.Default);
+}
+
+// ✅ Right — a scope per call, so the collaborators bind to the caller's tenant.
+[Singleton]
+public class DigestSources(IServiceScopeFactory scopeFactory) : IDigestSources
+{
+    public async Task<DigestConfiguration?> GetCurrent()
+    {
+        using var scope = scopeFactory.CreateScope();
+        var eventStore = scope.ServiceProvider.GetRequiredService<IEventStore>();
+        return await eventStore.ReadModels.GetInstanceById<DigestConfiguration>(DigestId.Default);
+    }
+}
+```
+
+`IChronicleClient` **is** singleton-safe, and is the right collaborator when a flow knows which namespace it means and has no scope to resolve one from — it names the event store and namespace explicitly: `await chronicleClient.GetEventStore("MyStore", tenantId.Value)`. Naming the namespace is a deliberate, readable statement that this code crosses a tenant boundary; capturing a scoped service is the same crossing made by accident.
+
+**The current user is not process-wide either.** Never keep the signed-in user, their principal, claims, roles, or anything derived from them in a singleton. The distinction that matters: *the accessor is fine, the value is not.* `IHttpContextAccessor` is itself a singleton and safe to inject; reading a value out of it once and keeping it is not. A current-user service may be a singleton only when every method reads through the accessor on each call and stores nothing. Anything that derives something per user and wants to keep it holds a cache **keyed by the user**, never a single field.
+
+**Off-request work carries its tenant.** Reactors, hosted services, background dispatch and scheduled jobs run with no HTTP request, so there is nothing for a tenant resolver to read. Chronicle observers are themselves instantiated per namespace, but the collaborators they call are not — a reactor that reaches a tenant-blind singleton has left its namespace behind without saying so. Such a flow states its tenant explicitly rather than inheriting whatever the root scope happens to be.
+
+**Caching.** A process-wide cache of tenant data is the same bug wearing a performance justification. If a singleton caches, the tenant (and where relevant the user) is part of the key. The same holds for `static` fields: a `static` cache of anything tenant-scoped is shared by every tenant in the process.
+
+**Enforce it, do not remember it.** This failure is silent, so review will not reliably catch it. Add an architecture spec that reflects over the assembly, finds every `[Singleton]` whose constructor takes a scope-bound service, and asserts the set is empty. It is a few dozen lines, it runs on every build, and it is the only thing that keeps the rule true a year from now.
+
+> .NET's own captive-dependency detection (`ServiceProviderOptions.ValidateScopes`, which Arc deliberately leaves on in Development) exists to catch exactly this. If a singleton in your codebase holds a scoped service and Development startup is not complaining, that path is not being exercised in Development — worth knowing on its own.
+
+### Discovering multiple implementations — use `IInstancesOf<T>`, never `IEnumerable<T>`
+
+When a type needs every implementation of an abstraction (handlers, strategies, filters, validators, formatters), inject `IInstancesOf<TInterface>` from `Cratis.Types`. The framework discovers and instantiates every implementation by convention — no `services.AddSingleton<TInterface, Impl1>()` calls anywhere.
+
+```csharp
+// ❌ Wrong — requires hand-maintained registrations for every implementation.
+// Adding a new IReactorSideEffectHandler somewhere else in the codebase silently
+// does nothing until someone remembers to register it here, and dead registrations
+// linger after types are removed.
+services.AddSingleton<IReactorSideEffectHandler, EventResultHandler>();
+services.AddSingleton<IReactorSideEffectHandler, EventsResultHandler>();
+services.AddSingleton<IReactorSideEffectHandlers, ReactorSideEffectHandlers>();
+
+public class ReactorSideEffectHandlers(IEnumerable<IReactorSideEffectHandler> handlers) : IReactorSideEffectHandlers { ... }
+
+// ✅ Right — implementations discovered automatically. Mark singletons with [Singleton].
+[Singleton]
+public class EventResultHandler(IEventTypes eventTypes) : IReactorSideEffectHandler { ... }
+
+[Singleton]
+public class EventsResultHandler(IEventTypes eventTypes) : IReactorSideEffectHandler { ... }
+
+[Singleton]
+public class ReactorSideEffectHandlers(IInstancesOf<IReactorSideEffectHandler> handlers) : IReactorSideEffectHandlers { ... }
+```
+
+**Rules:**
+
+- Never inject `IEnumerable<TInterface>` to enumerate implementations of an abstraction. That signature only works if every implementation is hand-registered, which defeats convention-based discovery. Use `IInstancesOf<TInterface>` instead.
+- Never write `services.AddSingleton<TInterface, Impl>()` or `services.AddTransient<TInterface, Impl>()` for a type that exists to be discovered. Mark the implementation with `[Singleton]` (for singletons) or rely on the `IFoo → Foo` convention (for transients) and remove the registration line.
+- `IInstancesOf<T>` resolves at the point of access — implementations added later in the assembly become available without touching the consumer or any composition root.
+- `IEnumerable<T>` is still the right type to **return** from a method that yields a sequence of values. The rule applies only when the goal is to enumerate **implementations** of an abstraction.
+
+## Logging
+
+- Use structured logging with named parameters.
+- Use `ILogger<T>` where `T` is the class name.
+- Keep log messages in a separate `<ClassName>Logging.cs` partial static internal class.
+- Use `[LoggerMessage]` attribute (without `eventId`).
+
+## Async
+
+- Use `async`/`await` for asynchronous programming.
+- Use `Task` and `Task<T>` for asynchronous methods.
+
+## Chronicle & Arc — Key API Types
+
+These are the building blocks. Each type has a specific role in the vertical slice architecture — using the right type in the right place means the framework handles discovery, wiring, and proxy generation automatically.
+
+| Type | Purpose |
+| --- | --- |
+| `ConceptAs<T>` | Strongly-typed domain *value* wrapper (see [concepts.md](./concepts.md)) |
+| `EventSourceId<T>` | Strongly-typed *identity* base — derive event-source ids from this, not `ConceptAs<T>` |
+| `[EventType]` | Marks a record as a Chronicle event — **never** pass arguments for a new event |
+| `[Command]` | Marks a record as a model-bound command — define `Handle()` directly on the record |
+| `[ReadModel]` | Marks a record as a model-bound query — define static query methods on the record |
+| `CommandValidator<T>` | FluentValidation validator for commands |
+| `IProjectionFor<T>` | Fluent projection definition — AutoMap is on by default, never call `.AutoMap()` |
+| `IReducerFor<T>` | Imperative reducer — receives current state, returns new state |
+| `IReactor` | Marker interface for side-effect observers — method dispatch by event type parameter |
+| `IConstraint` | Constraint definition — enforced server-side by Chronicle at append time |
+| `AggregateRoot` | Chronicle aggregate root with `Apply()` and `Commit()` |
+| `ICommandPipeline` | Programmatic command execution from reactors or other code |
+| `EventContext` | Event metadata: `Occurred`, `SequenceNumber`, `CorrelationId`, `EventSourceId`, etc. |
+| `ISubject<T>` | Observable query return type — enables real-time push |
+| `IMongoCollection<T>` | MongoDB collection — use `.Observe()` for reactive queries |
+
+**Key conventions:**
+
+- Prefer `ConceptAs<T>` over raw primitives in all domain models, commands, events, and queries; derive identity concepts from `EventSourceId<T>`. See [concepts.md](./concepts.md) for details.
+- Projections join **events**, never read models — projections rebuild state from the event stream, not from other projections.
+- For fluent projections, AutoMap is on by default — call `.From<EventType>()` without `.AutoMap()` and without manually mapping every matching property.
+- Use model-bound projection attributes (`[FromEvent<T>]`, `[SetFrom<T>]`, etc.) when possible; fall back to `IProjectionFor<T>` for complex cases.
+- Full slice anatomy lives in [vertical-slices.md](./vertical-slices.md).

package/package/corpus/rules/dialogs.md

@@ -0,0 +1,264 @@
+---
+applyTo: "**/*.tsx"
+profile: application
+paths:
+  - "**/*.tsx"
+---
+
+# Using Dialogs
+
+The Cratis dialog wrappers handle command execution, validation timing, loading states, and footer buttons consistently. Using PrimeReact's raw `Dialog` bypasses all of this and leads to inconsistent UX.
+
+## Choose the Correct Dialog Type
+
+- If confirm executes a command, use `CommandDialog` from `@cratis/components/CommandDialog`.
+- If no command is executed on confirm, use `Dialog` from `@cratis/components/Dialogs`.
+- If you are **asking the user to confirm** or **showing that something is in progress**, do not build a dialog at all — raise the host-rendered one through its hook (below).
+- **Never** import `Dialog` from `primereact/dialog` directly.
+
+## Confirmations and busy indicators are host-rendered — register once, raise by hook
+
+`ConfirmationDialog` and `BusyIndicatorDialog` are **not** instantiated in a slice's JSX. They are
+registered once at the app root and raised from anywhere through a hook, so every confirmation and
+every busy indicator in the application looks and behaves identically:
+
+```tsx
+import { DialogComponents } from '@cratis/arc.react/dialogs';
+import { BusyIndicatorDialog, ConfirmationDialog } from '@cratis/components/Dialogs';
+
+export const App = () => (
+    <DialogComponents confirmation={ConfirmationDialog} busyIndicator={BusyIndicatorDialog}>
+        <YourApp />
+    </DialogComponents>
+);
+```
+
+```tsx
+import { DialogButtons, DialogResult, useConfirmationDialog, useBusyIndicator } from '@cratis/arc.react/dialogs';
+
+const [confirm] = useConfirmationDialog();
+const answer = await confirm('Delete this alert?', `"${alert.title}" disappears permanently.`, DialogButtons.YesNo);
+if (answer !== DialogResult.Yes) return;
+
+const [showBusy, closeBusy] = useBusyIndicator('Importing', 'This takes a moment.');
+showBusy();
+try { await doTheSlowThing(); } finally { closeBusy(); }
+```
+
+**Rules:**
+- Register both in **exactly one** place — the app root. A second registration, or a slice building its own confirm/busy dialog, is how two of them end up looking different.
+- Reach them only via `useConfirmationDialog` / `useBusyIndicator`. Never hand-roll a Yes/No `Dialog`, and never use `window.confirm`.
+- `showConfirm()` resolves to a `DialogResult` — branch on the enum member, never on button text.
+- Always pair `showBusy()` with `closeBusy()` in a `finally`; the busy dialog is deliberately non-dismissible, so a missed close leaves the user stuck.
+- **A busy indicator is a modal for work that blocks the user.** For a quick command behind a button, an in-flight/disabled button (eventual-consistency rule 9) is the better control — a modal that flashes for 200 ms is worse than no modal. Use the busy dialog when the user genuinely cannot proceed.
+- From a view model, use the injectable `IDialogs` abstraction (`@cratis/arc.react.mvvm/dialogs`) rather than the hooks — see [react.md](./react.md).
+
+## When Using `CommandDialog`
+
+- Pass the command constructor to `command={}`. `CommandDialog` handles instantiation, execution, and confirm/cancel buttons.
+- Use command form fields (`InputTextField`, `TextAreaField`, etc. from `@cratis/components/CommandForm`) for user-input values.
+- `CommandDialog` automatically disables confirm while the command executes.
+- Any value that must be present for the form to be considered valid (i.e. passes `validateRequiredProperties`) must be supplied via `initialValues`, **not** via `onBeforeExecute`.
+  - `onBeforeExecute` fires only at execution time — the command is already validated before it runs, so values set there never influence `isValid` and the OK/Submit button will remain permanently disabled.
+  - Use `initialValues` for injected context values (e.g. a parent entity id passed as a prop).
+  - Use `onBeforeExecute` only for transformations that should not affect form validity (e.g. generated IDs).
+
+```tsx
+import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
+import { CommandDialog } from '@cratis/components/CommandDialog';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { RegisterProject } from './Registration';
+import { Guid } from '@cratis/fundamentals';
+
+export const AddProject = ({ closeDialog }: DialogProps) => {
+    return (
+        <CommandDialog<RegisterProject>
+            command={RegisterProject}
+            title="Add Project"
+            okLabel="Add"
+            cancelLabel="Cancel"
+            onBeforeExecute={(values) => {
+                values.projectId = Guid.create();  // generated, not user input
+                return values;
+            }}>
+            <InputTextField<RegisterProject>
+                value={instance => instance.name}
+                title="Project name"
+                placeholder="My Project"
+            />
+        </CommandDialog>
+    );
+};
+```
+
+To await the result from the parent:
+
+```tsx
+const [AddProjectDialog, showAddProjectDialog] = useDialog(AddProject);
+
+const [result] = await showAddProjectDialog();
+if (result === DialogResult.Ok) {
+    // Dialog confirmed and command executed successfully
+}
+```
+
+### `onSuccess` vs `onConfirm`
+
+- **`onSuccess(response)`** fires only after the command succeeds and receives the typed command response — use it for `closeDialog(DialogResult.Ok, response)`, refreshing a query, or a toast.
+- **`onConfirm()`** receives **no** command result. It is a close gate after successful execution: return `true` to let the wrapper close, `false`/`undefined` to keep it open. **Do not use `onConfirm` as a command-result handler.**
+
+### `onBeforeExecute` is a transformer
+
+It receives the current command values and **must return them** (mutated or not). **Returning `void` executes the command with `undefined` values.** It runs only on submit — never use it to seed *required* values (validation runs against pre-transform state, so a value seeded here never makes the form valid and the submit button stays permanently disabled). Seed required values via `initialValues`; reserve `onBeforeExecute` for transforms that don't affect validity (e.g. a generated id).
+
+### CommandForm fields
+
+Use built-in `CommandForm` fields (from `@cratis/components/CommandForm`) for every user-input value — a raw PrimeReact control inside a command dialog bypasses `CommandFormFieldWrapper`, so validation never re-runs and the submit button stays **permanently disabled**. Catalog: `InputTextField`, `PasswordField`, `NumberField`, `DropdownField`, `CheckboxField`, `ToggleSwitchField`, `TextAreaField`, `CalendarField`, `RadioButtonField`, `RadioGroupField`, `ChipsField`, `MultiSelectField`, `ColorPickerField`, `SliderField`, `RatingField`.
+
+- The `value={c => c.name}` **accessor lambda doubles as the binding and type-checked field selection** — renaming a command property surfaces a compile error at every binding.
+- **`RadioGroupField<T>`** renders a whole group from data (`options`/`optionLabel`/`optionValue`, `layout='horizontal'|'vertical'`); **`RadioButtonField<T>`** is one component per option (each takes a `buttonValue`). Both infer the value type from the accessor — no `as string` casts.
+- **`asCommandFormField(Component, opts)`** (`asCommandFormField`, `WrappedFieldProps` from `@cratis/arc.react/commands`) wraps a custom input so it participates in `CommandForm` like a built-in. `WrappedFieldProps<T>` gives `{ value, onChange, invalid, required, errors }` (`errors` is `string[]` → `errors.join(', ')`); options are `{ defaultValue, extractValue: e => ... }`.
+- **`useCommandInstance(Command)`** (`@cratis/arc.react/commands`) returns the live reactive instance the form is bound to — **read** it to drive dependent fields (e.g. read `command.country` to choose a `DropdownField`'s options); never mutate (mutations go through field bindings).
+
+### Opening dialogs — `useDialog` / `useDialogContext`
+
+`useDialog<TResponse, TInput>(Component)` returns `[Wrapper, showFn]`: render `<Wrapper />` in JSX and call `showFn(input)` to open it; it resolves to `[DialogResult, TResponse?]` when the dialog closes. For a new dialog, prefer reading input as **plain typed props** (`<Name>Input`) and obtaining `closeDialog` from **`useDialogContext<TResponse>()`** — rather than declaring a props interface that extends `DialogProps` to thread both input and `closeDialog`. (Existing dialogs that destructure `closeDialog` from `DialogProps` remain valid.) Signal the outcome with `closeDialog(DialogResult.Ok | Cancelled, response?)`.
+
+### Multi-step wizards — `StepperCommandDialog`
+
+For a command split across named steps use `StepperCommandDialog` (`@cratis/components/CommandDialog`) — see the **stepper-command-dialog** skill. Conditional steps written as `{condition && <StepperPanel/>}` are supported **from 2.7.1**: only the steps that actually render are counted, so Next and Submit appear where the user expects them. ⚠️ On earlier versions a hidden step is still counted — Submit never appears on the real last step and a dead Next takes its place, so check what you are pinned to before relying on this. ⚠️ A `<>…</>` fragment wrapping several panels still counts as **one** step — give each step its own `StepperPanel` child. When a step needs non-CommandForm inputs, or cross-step state is complex, fall back to a manual `Dialog` + PrimeReact `Stepper`.
+
+## When Using `Dialog`
+
+Use this for dialogs that collect data and return it without executing a command (e.g. confirmation prompts, pure data-entry dialogs). `Dialog` defaults to OK + Cancel buttons. Use `isValid` to control confirm button state, `okLabel`/`cancelLabel` to customize button text.
+
+```tsx
+import { useState } from 'react';
+import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
+import { Dialog } from '@cratis/components/Dialogs';
+import { InputText } from 'primereact/inputtext';
+
+export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
+    const [name, setName] = useState('');
+    const isValid = name.trim().length > 0;
+
+    return (
+        <Dialog
+            title="Add Project"
+            width='32rem'
+            isValid={isValid}
+            onConfirm={() => closeDialog(DialogResult.Ok, { name })}
+            onCancel={() => closeDialog(DialogResult.Cancelled)}
+        >
+            <InputText
+                value={name}
+                onChange={event => setName(event.target.value)}
+                autoFocus
+            />
+        </Dialog>
+    );
+};
+```
+
+## Prefer `DialogButtons` over Custom Button JSX
+
+Use the built-in `DialogButtons` enum instead of rendering manual `<Button>` elements in the `buttons` prop:
+
+```tsx
+import { DialogButtons, DialogResult, useDialogContext } from '@cratis/arc.react/dialogs';
+```
+
+### Available Button Sets
+
+| `buttons` value | Shows |
+|---|---|
+| `DialogButtons.OkCancel` | Ok + Cancel |
+| `DialogButtons.YesNo` | Yes + No |
+| `DialogButtons.YesNoCancel` | Yes + No + Cancel |
+| `DialogButtons.Ok` | Ok only |
+| `null` | No buttons (content-only dialog) |
+
+## Customizing Built-in Buttons
+
+Use `okLabel`/`cancelLabel` to rename the buttons, and `isValid` to disable the confirm button:
+
+```tsx
+<Dialog
+    title="Import Orders"
+    visible={true}
+    buttons={DialogButtons.OkCancel}
+    okLabel="Upload"
+    isValid={!!file && !isUploading}
+    onConfirm={handleUpload}
+    onCancel={() => closeDialog(DialogResult.Cancelled)}
+>
+```
+
+## Validation Guard — Keep Dialog Open on Failure
+
+When `onConfirm` needs to keep the dialog open (e.g. a command fails), annotate the handler as `Promise<boolean>` and return `false` to block the close. Return `true` to let the Dialog close itself:
+
+```tsx
+const handleConfirm = async (): Promise<boolean> => {
+    const result = await myCommand.execute();
+    if (!result.isSuccess) return false; // dialog stays open
+    return true; // dialog closes
+};
+```
+
+> **TypeScript note:** Always annotate the function as `Promise<boolean>`. Without it TypeScript infers `Promise<false | void>` which does not satisfy the `ConfirmCallback` type.
+
+## Passing Result Data on Confirm
+
+When the dialog must return data to its caller (e.g. a postal code lookup result), use `onClose` and call `closeDialog` manually, returning `false` to prevent the Dialog from calling it a second time:
+
+```tsx
+<Dialog
+    title="Confirm Location"
+    visible={true}
+    buttons={DialogButtons.OkCancel}
+    isValid={isValid}
+    onClose={(result) => {
+        if (result === DialogResult.Ok) {
+            closeDialog(DialogResult.Ok, { postalCode, city, latitude, longitude } as MyResult);
+            return false; // prevent Dialog from calling closeDialog(Ok) again
+        }
+        // Cancelled: return undefined so the Dialog calls closeDialog(Cancelled)
+    }}
+>
+```
+
+## Content-only Dialogs (No Action Buttons)
+
+Use `buttons={null}` for dialogs that contain their own internal actions (e.g. a menu + data table) and don't need a confirm/cancel footer:
+
+```tsx
+<Dialog
+    title="Hubs"
+    visible={true}
+    width="50vw"
+    buttons={null}
+    onCancel={() => closeDialog(DialogResult.Cancelled)}
+>
+    <Menubar model={menuItems} />
+    <Listing configurationId={configurationId} />
+</Dialog>
+```
+
+## Props Reference
+
+| Prop | Type | Notes |
+|---|---|---|
+| `title` | `string` | Header text (replaces PrimeReact `header`) |
+| `visible` | `boolean` | Controls visibility |
+| `buttons` | `DialogButtons \| ReactNode \| null` | Prefer `DialogButtons` enum; `null` for no footer |
+| `isValid` | `boolean` | Disables the confirm button when `false` |
+| `okLabel` | `string` | Override the Ok/Confirm button label |
+| `cancelLabel` | `string` | Override the Cancel button label |
+| `onConfirm` | `() => boolean \| void \| Promise<boolean> \| Promise<void>` | Called when Ok is clicked; return `false` to keep dialog open, `true` to close |
+| `onCancel` | `() => void \| Promise<void>` | Called when Cancel is clicked |
+| `onClose` | `(result: DialogResult) => boolean \| void \| Promise<...>` | Combined handler for both Ok and Cancel |
+| `width` | `string` | Dialog width (e.g. `'50vw'`) — replaces PrimeReact `style={{ width }}` |
+| `resizable` | `boolean` | Default `false` |
+
+`style`, `contentStyle`, and `dismissable` **are** supported. The other v10 PrimeReact Dialog props (`modal`, `dismissableMask`, `draggable`, `footer`, `onHide`) are **not** available — do not use them. (`resizable` is accepted for compatibility but is a no-op in PrimeReact 11.)