@cratis/pi 2.21.3 → 2.23.0

package/package/corpus/prompts/verify-ai-setup.prompt.md

@@ -1,19 +1,29 @@
 ---
 agent: agent
-description: Validate AI framework setup integrity, canonical source conventions, and symlink health.
+description: Check the installed Cratis AI corpus for drift, conflicts, and healthy harness adapters.
 ---
 
 # Verify AI Setup
 
-Validate the repository AI setup by running:
+Check the repository's installed Cratis AI setup by running:
 
 ```bash
-bash .cratis/ai/hooks/scripts/validate-ai-setup.sh
+cratis ai status
 ```
 
-If anything fails:
+It reports the configured harnesses, profiles and languages, the installed corpus revision against the
+available one (`updateAvailable`), and every managed file that was modified locally — exiting non-zero
+when there is any. (A user-owned path that collides with a managed one is reported and refused by
+`cratis ai install` / `cratis ai update`, not by `status`.) Then confirm
+the harness adapters this repository uses (`.claude/`, `.agents/`, `.github/`, `.pi/`, `.cursor/`,
+`.opencode/` as applicable) still resolve into `.cratis/ai/` — a broken or dangling symlink is a setup
+fault, not corpus drift.
 
-1. List every failure with the exact file path.
-2. Explain whether the issue is canonical-source drift, missing metadata, or broken links.
-3. Propose the smallest safe fix.
+If anything is reported:
+
+1. List every finding with the exact file path.
+2. Explain whether it is a hand-edited managed file, a pending update, or a broken adapter.
+3. Propose the smallest safe fix. A managed file is never patched by hand — `cratis ai update`
+   replaces it (with `--force` only for content already recorded as Cratis-managed); a user-owned
+   file is the repository's and stays.
 4. Apply fixes if requested.

package/package/corpus/rules/ai-distribution.md

@@ -0,0 +1,58 @@
+---
+applyTo: "**/*"
+---
+
+# Shared AI Distribution
+
+How the shared Cratis AI corpus reaches a repository, and what a consuming
+repository must and must not do with it. The always-loaded instructions keep only
+the two invariants; this rule carries the mechanics.
+
+Do not copy or synchronize shared `.cratis/ai`, `.agents`, `.claude`, `.github`, or
+`.pi` trees from one Cratis repository to another. A consuming repository must
+never become an accidental source that republishes its local AI corpus.
+
+Shared Cratis capabilities are authored and reviewed in `Cratis/AI` and reach a
+repository through one of three channels, each with its own version semantics:
+
+- **`cratis ai install` / `cratis ai update`** copy the corpus into `.cratis/ai/`
+  from the current `main` of `Cratis/AI` (or an explicit `--source` path), record
+  the source commit and every installed file's hash in `.cratis/ai.manifest.json`,
+  and create native harness adapters as symlinks into that managed copy. There is
+  no version pin on this channel: an update takes whatever `main` holds. Agents,
+  prompts, and hooks are always installed; rules are filtered by profile and
+  language; skills by the profile catalog; `harnesses/<harness>/` only for the
+  harnesses selected.
+- **`@cratis/pi`** is the one versioned channel: an npm package cut per release,
+  pinned and rolled back by package version. It yields to a managed install when
+  `.cratis/ai.manifest.json` exists.
+- **Native plugin marketplaces** (Claude Code, Codex, Copilot, Cursor) expose the
+  skills only, from the unpinned GitHub source.
+
+Keep existing repository-local AI files in place while a replacement corpus is
+under canary; do not restart legacy all-to-all propagation and do not delete
+legacy adapters before reviewed retirement evidence exists.
+
+Shared public product and `engineering-*` packages contain only public-safe
+Cratis behavior. The `engineering-` prefix identifies the maintainer audience;
+it does not imply confidential package contents or a private registry.
+
+The consuming repository owns its project facts, confidential behavior, local
+skills, and minimal host bootstraps. Use repository-owned documentation as canonical
+project context when that migration is active, `.agents/skills/` for private or
+repository-specific local workflows, and repository-owned documentation only as the
+documented legacy context fallback. Never merge, overwrite, or remove these
+local files as a side effect of installing, updating, rolling back, or
+uninstalling shared AI capabilities.
+
+Keep confidential and repository-specific behavior local. Generalize and remove
+private facts before proposing a reusable improvement to `Cratis/AI`; never
+reverse-sync a private repository's AI tree or generated adapters.
+
+Update shared AI through the channel's own mechanism (`cratis ai update`, or the
+`@cratis/pi` package version). Canary the change, observe its behavior and gates,
+and roll back the same way — by package version where one exists, otherwise by
+reinstalling from a known-good source commit with `--source`. Never patch managed
+files under `.cratis/ai/`, generated adapters, or marketplace wrappers by hand;
+`cratis ai status` reports such drift and `update` refuses it without `--force`.
+

package/package/corpus/rules/components.md

@@ -7,54 +7,66 @@ profile: application
 
 # Building React Components
 
-## Cratis Components — pick the wrapper, import from subpaths
+The frontend is composed from **Cratis Components** (`@cratis/components` **4.x**). Components owns its markup, styling contract and public types; React Aria supplies focus, overlay, collection and date behavior *internally* — you never import or style it. Components declares **no** PrimeReact, PrimeIcons or PrimeUI dependency or peer, and it ships no vendor CSS. PrimeReact (11 and 10) and MUI exist only as optional *presentation adapters* (`@cratis/components.primereact`, `.primereact10`, `.mui`) that adapt nine primitive slots — button, icon-button, text input, text area, checkbox, radio, switch, progress bar, surface — and nothing else. Dialogs, dropdowns, tables, date pickers, toasts and steppers are always Components-owned.
 
-Reach PrimeReact almost exclusively through Cratis Components wrappers. Import from **subpaths**, not the root barrel (the barrel pulls optional-peer-heavy exports):
+## Import from subpaths — the root is setup-only
+
+The package root exports **only** setup (`CratisComponentsProvider`, configuration and message types). Every component ships from its own subpath; the Components 3 root namespaces are gone, and `@cratis/eslint-plugin-components`' `no-root-barrel-import` keeps them gone.
 
 | Need | Use | Subpath |
 |---|---|---|
-| Page chrome | `Page` | `@cratis/components/Common` |
-| Query list page | `DataPage` | `@cratis/components/DataPage` |
-| Standalone query table | `DataTableForQuery` / `DataTableForObservableQuery` | `@cratis/components/DataTables` |
-| Form section | `FormElement` | `@cratis/components/Common` |
-| Icon | `Icon` / `IconDisplay` | `@cratis/components/Common` |
+| App root | `CratisComponentsProvider` | `@cratis/components` |
+| Page chrome, buttons, basic controls | `Page`, `Button`, `IconButton`, `TextInput`, `TextArea`, `NumberInput`, `Checkbox`, `Radio`, `Switch`, `Tooltip`, `ErrorBoundary`, `FormElement`, `ComboBox` (≥ 4.6.0 — single-selection, text-searching entity picker) | `@cratis/components/Common` |
+| Icon | `Icon` (type) / `IconDisplay` | `@cratis/components/Common` |
+| Query list page | `DataPage`, `MenuItem`, `Column` | `@cratis/components/DataPage` |
+| Standalone query table | `DataTableForQuery` / `DataTableForObservableQuery`, `Column` | `@cratis/components/DataTables` |
 | Dropdown | `Dropdown` | `@cratis/components/Dropdown` |
-| Command dialog | `CommandDialog` / `StepperCommandDialog` | `@cratis/components/CommandDialog` |
-| Data/confirmation dialog | `Dialog` / `ConfirmationDialog` / `BusyIndicatorDialog` | `@cratis/components/Dialogs` |
-| Command form fields | `InputTextField`, `PasswordField`, `ToggleSwitchField`, `RatingField`, … | `@cratis/components/CommandForm` |
-| Notifications (toasts) | `Toaster` / `toast` / `toastCommandResult` | `@cratis/components/Notifications` |
-| Status & display | `Tag` / `Badge` / `Chip` / `Skeleton` / `Avatar` / `ProgressBar` | `@cratis/components/Display` |
-| Canvas tool palette | `Toolbar` | `@cratis/components/Toolbar` |
+| Command dialog | `CommandDialog`, `StepperCommandDialog`, `StepperPanel` | `@cratis/components/CommandDialog` |
+| Standalone stepper | `CommandStepper` | `@cratis/components/CommandStepper` |
+| Data / confirmation / busy dialog | `Dialog`, `ConfirmationDialog`, `BusyIndicatorDialog` | `@cratis/components/Dialogs` |
+| Command form fields | `InputTextField`, `NumberField`, `DropdownField`, `CheckboxField`, `CalendarField`, …, `AutoCommandForm` | `@cratis/components/CommandForm` |
+| Notifications | `Toaster`, `toast`, `toastCommandResult` | `@cratis/components/Notifications` |
+| Status & display | `Tag`, `Badge`, `Chip`, `Skeleton`, `Avatar`, `ProgressBar`, `ProgressSpinner`, `Message` | `@cratis/components/Display` |
+| Canvas tool palette | `Toolbar`, `ToolbarButton`, … | `@cratis/components/Toolbar` |
+| Shared types | `JsonSchema`, `Json`, … | `@cratis/components/types` |
 
-Use `Dropdown` from `@cratis/components/Dropdown` (not raw `primereact/dropdown`) — it appends to the document body and stacks correctly above overlays, avoiding the z-index issues raw PrimeReact dropdowns have inside dialogs.
+Use `Dropdown` from `@cratis/components/Dropdown`, never a vendor select: it renders through the Components overlay environment, so it stacks correctly above dialogs, and it follows the WAI-ARIA button/listbox (or combobox, when `filter` is on) pattern. Its `onChange` receives the **value**, not an event — as do every CommandForm field's.
 
 ### Notifications — feedback for commands run outside a dialog
 
 `CommandDialog` handles success/error feedback itself. For a command executed
-**programmatically** (`command.execute()` outside a dialog), mount one
-`<Toaster />` near the app root and surface the result with `toastCommandResult`
-(both from `@cratis/components/Notifications`) — it maps the granular
-`ICommandResult` flags to the right toast (success, not-authorized, validation
-with per-field messages, exceptions — never stack traces):
+**programmatically** (`command.execute()` outside a dialog), mount the toast region once —
+`toaster` on `CratisComponentsProvider`, or one `<Toaster />` near the root — and surface the result
+with `toastCommandResult` (`@cratis/components/Notifications`). It maps the granular
+`ICommandResult` flags to the right toast (success, not-authorized, validation with per-field
+messages, exceptions — never stack traces):
 
 ```tsx
 const result = await command.execute();
 if (toastCommandResult(result, { successTitle: 'Author registered' })) refresh();
 ```
 
-For ad-hoc notifications, call the imperative `toast.success/info/warn/error(...)`
-— each takes an **options object**, not a bare string: `toast.info({ title: 'Saved', description: '…' })`.
+For ad-hoc notifications, call the imperative `toast.success/info/warn/error(...)` — each takes an
+**options object**, not a bare string: `toast.info({ title: 'Saved', description: '…' })`.
 
 ### Column filtering & display components
 
-`<Column>` supports `filter` (a per-column filter menu with match modes) and
-`DataPage` / the data tables show a global search box when `globalFilterFields`
-is set. Use the `Display` components (`Tag`, `Badge`, `Skeleton`, …) for status
-indicators and loading states in tables and detail views.
+`<Column>` supports `sortable` and `filter` (a per-column filter popup with match modes), and
+`DataPage` / the data tables show a search box when `globalFilterFields` is set. **Sorting and
+filtering apply to the currently loaded page**; complete-result filtering belongs in the query's
+arguments and the server-side query, before paging (`clientFiltering` is a deprecated no-op). Use the
+`Display` components (`Tag`, `Badge`, `Skeleton`, …) for status indicators and loading states.
 
 ### `DataPage` — query list pages
 
-`DataPage` (from `@cratis/components/DataPage`) owns the data table's subscription, paging, selection, action menubar, and details split — **do not pre-fetch rows and pass an `items` array**. Required props: `title`, `query` (`Constructor<TQuery>`; snapshot and observable queries are auto-detected), `emptyMessage`, and `children`. Other props: `queryArguments`, `dataKey` (pass whenever the read model has an identity), `selection` / `onSelectionChange`, `globalFilterFields` / `defaultFilters` / `clientFiltering`, `detailsComponent` (`React.FC<IDetailsComponentProps<T>>` = `{ item, onRefresh? }`), `onRefresh`, and PrimeReact pass-through `tablePt`/`tableClassName`/`menubarPt`/`menubarClassName`.
+`DataPage` (from `@cratis/components/DataPage`) owns the data table's subscription, paging,
+selection, action menubar, and details split — **do not pre-fetch rows and pass an `items` array**.
+Required props: `title`, `query` (`Constructor<TQuery>`; snapshot and observable queries are
+auto-detected), `emptyMessage`, and `children`. Other props: `queryArguments`, `dataKey` (pass
+whenever the read model has an identity), `selection` / `onSelectionChange`, `globalFilterFields` /
+`defaultFilters`, `detailsComponent` (`React.FC<IDetailsComponentProps<T>>` = `{ item, onRefresh? }`),
+`onRefresh`, and the Cratis part props `tablePt: DataTableParts` / `paginatorPt: TablePaginatorParts`
+/ `menubarPt: ButtonParts` (plus `tableClassName` / `menubarClassName`).
 
 Columns and toolbar actions are compositional children:
 
@@ -71,7 +83,10 @@ import { DataPage, MenuItem, Column } from '@cratis/components/DataPage';
 </DataPage>
 ```
 
-`MenuItem` is a PrimeReact menu item (use `command`, not `onClick`); `disableOnUnselected` greys it out until a row is selected. See the **cratis-react-page** skill for the full page workflow.
+`MenuItem` is a declarative Components element read by `DataPage.MenuItems` (use `command`, not
+`onClick`); `disableOnUnselected` greys it out until a row is selected; its `icon` is a **React
+component type** (e.g. a `react-icons` icon), not an `Icon`. See the **cratis-arc-react-page** skill
+for the full page workflow.
 
 ## Composition over Monoliths
 
@@ -100,33 +115,48 @@ Add an `index.ts` that re-exports the public surface so import paths stay stable
 
 ## Styling
 
-Consistent styling comes from discipline: static styles in CSS files, dynamic values inline, and colors always from PrimeReact's design tokens. This ensures theming works automatically and no component breaks the visual language.
+Consistent styling comes from discipline: static styles in CSS files, dynamic values inline, and colors always from the `--cratis-*` design tokens. This ensures theming works automatically and no component breaks the visual language.
 
 ### App setup — the imports Cratis Components needs
 
-From `@cratis/components` **3.0.0** (PrimeReact 11), an app must do two things or the components render unstyled and PrimeReact may end up with two React contexts:
+An app does three things, once, at its root — or the components render unstyled:
 
-1. **Install PrimeReact yourself** — it is a **peer dependency**, not bundled: `primereact@^11`, `@primereact/core@^11`, `@primereact/headless@^11`, `primeicons@^8`. Two copies of PrimeReact means two `PrimeReactProvider` contexts, which breaks overlays and `pt` silently. Delete any `resolutions`/`overrides` pin that used to work around this.
-2. **Import the stylesheets explicitly**, in this order — components no longer import their own CSS:
+1. **Import the stylesheets, in this order** — components do not import their own CSS:
 
    ```ts
-   import '@cratis/components/tokens';   // the --cratis-* layer every component reads
-   import '@cratis/components/styles';   // every component stylesheet, in one file
-   import '@cratis/components/theme';    // optional: the license-free baseline look
+   import '@cratis/components/tokens';   // the semantic --cratis-* variables every component reads
+   import '@cratis/components/styles';   // structural rules for every component, in low-priority Cratis layers
+   import '@cratis/components/theme';    // optional: the baseline light/dark look (auto, or `cratis-dark`/`cratis-light`)
    ```
 
-PrimeReact 11 ships **zero CSS** — there is no `primereact/resources/themes/*.css`. A styled look comes from a `@primeuix/themes` preset passed through the provider (`value={{ theme: { preset: Aura } }}`, license-gated), from `@cratis/components/theme` (no license), or from your own `pt`/CSS.
+   A product with its own design system omits `theme`, defines the `--cratis-*` variables itself, and imports those values *after* the two Components entries so they win the cascade.
+
+2. **Mount `CratisComponentsProvider`** (from the package root) around the app. Its `value` carries `locale` (BCP 47 — drives dates, numbers, keyboard behavior and announcements) and `messages` (the Components-owned labels for `paginator`, `datePicker`, `dropdown`, `dialog`, `stepper`, `notifications`, `dataTable`, `columnFilter`, `toolbar`); `toaster` mounts the toast region. Renderer keys from Components 3 — `license`, `theme`, `pt`, `ripple`, `unstyled`, z-index — are a **type error**, on purpose. Keep the `value` object stable when it carries a large message catalog.
 
-### Writing styles inside the library
+   ```tsx
+   import { CratisComponentsProvider } from '@cratis/components';
+
+   export const App = () => (
+       <CratisComponentsProvider value={{ locale: 'en-US' }} toaster>
+           <Application />
+       </CratisComponentsProvider>
+   );
+   ```
 
-- Use **CSS classes in co-located `.css` files** for static styles, and add an `@import` for each new stylesheet to `Source/styles.css` — the build fails if a component stylesheet is not reachable from that manifest. **Never** add `import './Foo.css'` to a `.tsx`: a CSS file in the JavaScript module graph is what made the published package unloadable in Node (Cratis/Components#118).
-- Each component must have its own CSS file — never add sub-component styles to the parent's CSS. This keeps styles co-located with the component they belong to.
+3. **Install nothing else.** No PrimeReact, no PrimeIcons, no theme preset, no vendor provider. Only if the product wants a vendor's *look* on the nine primitive slots does it install one adapter package and pass its manifest to the provider's `library` prop — and the vendor's own provider, theme and license then stay the application's, outside Components.
+
+### Writing styles
+
+- Use **CSS classes in co-located `.css` files** for static styles; each component has its own CSS file — never add sub-component styles to the parent's CSS.
 - The composition root's CSS only contains layout/grid rules for positioning children — it should not style the children themselves.
 - Use inline `style` props **only** for runtime-dynamic values (pixel positions, computed sizes).
-- Use **PrimeReact CSS variables** for all colors, backgrounds, borders. This ensures the application respects theming and dark/light mode switches:
-  - `var(--surface-0)` through `var(--surface-900)`, `var(--surface-card)`, `var(--surface-border)`, `var(--surface-ground)`
-  - `var(--text-color)`, `var(--text-color-secondary)`, `var(--primary-color)`, `var(--primary-color-text)`, `var(--highlight-bg)`
-  - Never hard-code hex or `rgb()` for UI chrome — it will break when themes change. Only hard-code colors that are intentionally theme-independent (e.g. brand-specific accent dots, traffic-light indicators).
+- Use the **`--cratis-*` tokens** for every color, background, border, shadow and radius, so theming and dark mode work automatically:
+  - surfaces — `var(--cratis-surface-0)`, `var(--cratis-surface-100)`, `var(--cratis-surface-card)`, `var(--cratis-surface-ground)`, `var(--cratis-surface-section)`, `var(--cratis-surface-overlay)`, `var(--cratis-surface-hover)`, `var(--cratis-surface-border)`
+  - text & accent — `var(--cratis-text-color)`, `var(--cratis-text-color-secondary)`, `var(--cratis-primary-color)`, `var(--cratis-primary-color-text)`, `var(--cratis-highlight-bg)`, `var(--cratis-highlight-text-color)`, `var(--cratis-focus-ring)`
+  - status — `var(--cratis-success-background)`/`-text`, `var(--cratis-warning-*)`, `var(--cratis-danger-*)`, `var(--cratis-info-*)`
+  - shape — `var(--cratis-border-radius)`, `var(--cratis-control-height)`, `var(--cratis-shadow-subtle)`/`-overlay`/`-dialog`
+  - Never hard-code hex or `rgb()` for UI chrome. Only hard-code colors that are intentionally theme-independent (brand accent dots, traffic-light indicators).
+- **Reach inside a component through its parts, not its DOM.** Every meaningful element carries `data-cratis-part="<name>"` and state attributes (`data-selected`, `data-invalid`, `data-disabled`, `data-active`, `data-position`). Style them with those selectors, or pass per-part attributes through the component's `pt` prop typed by its `*Parts` type (`DialogParts`, `StepperParts`, `DataTableParts`, `TablePaginatorParts`, `ButtonParts`, the `Toolbar*Parts` family). Never target React Aria class names or the internal element structure — they are not a contract.
 - Name CSS classes with a BEM-like prefix matching the component name.
 
 ## Props
@@ -136,16 +166,19 @@ Props are a component's public API. They should be clear, minimal, and well-docu
 - Each sub-component declares its own `*Props` interface with JSDoc on every prop.
 - Pass only needed props — avoid threading large prop bags through component trees.
 - Event handlers follow `on*` naming: `onPointerDown`, `onSelect`.
+- Model visual variation the way `Button` does — one typed `variant` (`solid | outline | ghost | link`), one `tone` (`neutral | accent | positive | caution | critical`), one `shape` — not a pile of boolean flags.
 
 ## Dialogs
 
 See [dialogs.md](./dialogs.md) for the full dialog guide.
 
-**Summary:** Never import `Dialog` from `primereact/dialog`. Use `CommandDialog` from `@cratis/components/CommandDialog` for command-executing dialogs and `Dialog` from `@cratis/components/Dialogs` for data-collection dialogs. Do not render manual `<Button>` components for dialog actions — the dialog components handle footers.
+**Summary:** Use `CommandDialog` from `@cratis/components/CommandDialog` for command-executing dialogs and `Dialog` from `@cratis/components/Dialogs` for data-collection dialogs; confirmations and busy indicators are raised through hooks, never built. Never import a vendor dialog. Do not render manual `<Button>` components for dialog actions — the dialog components handle footers.
 
 ## Icons
 
-Follow these rules when working with SVG icons:
+Components accepts an **`Icon`** (`@cratis/components/Common`) wherever a control takes an icon: either a React node — preferred — or a complete, consumer-owned icon-font class string. Components installs **no icon font**: a string is rendered on an `<i>` unchanged, so the product must load that stylesheet itself. `react-icons` is a Components dependency and the natural source of React icon nodes (`<FaHouse aria-hidden="true" />`). Not every `icon` prop has that shape — `DataPage.MenuItem.icon` is a React component *type* because the page instantiates it; follow the exported prop type.
+
+For the application's own SVG icons:
 
 - **Distinguish icons from status/interactive components.** A pure SVG icon is a simple presentational element. A component that wraps an icon with interactive behavior (e.g. a dropdown, tooltip, or complex state) is a _component_, not an icon — name it accordingly (e.g. `SliceStatus`, not `SliceStatusIcon`).
 - **Store each SVG as a separate `.svg` file** inside the icon's folder. Do not embed SVG markup directly in `.tsx` files.

package/package/corpus/rules/dialogs.md

@@ -7,14 +7,14 @@ paths:
 
 # 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.
+The Cratis dialogs handle command execution, validation timing, busy state, focus, dismissal and footer buttons consistently. A vendor dialog, or a hand-rolled modal, bypasses all of this and leads to inconsistent UX — and a second focus trap around a Components dialog breaks keyboard and screen-reader behavior.
 
 ## 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.
+- **Never** use a vendor or hand-rolled modal. Dialogs are Components-owned; the optional renderer adapters do not replace them.
 
 ## Confirmations and busy indicators are host-rendered — register once, raise by hook
 
@@ -109,24 +109,24 @@ if (result === DialogResult.Ok) {
 
 ### `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).
+It receives the current command values and **must return them** (mutated or not). **Returning `void` does not execute with `undefined`** — the current values are kept and a `console.warn` is logged; still, always return the 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`.
+Use built-in `CommandForm` fields (from `@cratis/components/CommandForm`) for every user-input value — a raw control (a `Common` `TextInput`, a native `<input>`) inside a command dialog is not bound to the command, so validation never re-runs and the submit button stays **permanently disabled**. Catalog: `InputTextField`, `PasswordField`, `NumberField`, `NumberInputField`, `DropdownField`, `CheckboxField`, `ToggleSwitchField`, `TextAreaField`, `CalendarField`, `RadioButtonField`, `RadioGroupField`, `ChipsField`, `MultiSelectField`, `ColorPickerField`, `SliderField`, `RatingField`. `AutoCommandForm` generates the field list from the command's properties (`string` → `InputTextField`, `number` → `NumberField`, `boolean` → `CheckboxField`, `Date` → `CalendarField`; other types need a registered field-type provider) — use it for plain forms, hand-write fields when the layout or a concept type needs it. Several `RadioButtonField`s bound to one property need the same explicit `name`.
 
-- 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.
+- 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. The binding is inferred from the accessor's *source text*, so a computed accessor (`c => c[descriptor.name]`) cannot be inferred — name it explicitly with `fieldName="…"` (Arc ≥ 22.16.0).
 - **`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).
+- **`useCommandInstance<TCommand>()`** (`@cratis/arc.react/commands`, no argument — reads the enclosing form's context) 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?)`.
+`useDialog<TResponse, TInput>(Component)` returns `[Wrapper, showFn, context]` (the third element is rarely needed): 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<TRequest, TResponse>()`** (request type first) — 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`.
+For a command split across named steps use `StepperCommandDialog` (`@cratis/components/CommandDialog`) — see the **cratis-components-stepper-command-dialog** skill. Conditional steps written as `{condition && <StepperPanel/>}` are supported: only the steps that actually render are counted, so Next and Submit appear where the user expects them, and the active step is clamped if a late-resolving condition removes a step the user had passed. ⚠️ A `<>…</>` fragment wrapping several panels counts as **one** step — give each step its own `StepperPanel` child. Stepper parts are Cratis-owned (`root`, `list`, `step`, `header`, `number`, `title`, `separator`, `panels`, `panel`; `StepperParts` from `@cratis/components/CommandDialog`). When the wizard belongs inline in a page region rather than in a modal, use the sibling `CommandStepper` (`@cratis/components/CommandStepper`) — same steps, same command execution, no dialog chrome.
 
 ## When Using `Dialog`
 
@@ -136,7 +136,7 @@ Use this for dialogs that collect data and return it without executing a command
 import { useState } from 'react';
 import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
 import { Dialog } from '@cratis/components/Dialogs';
-import { InputText } from 'primereact/inputtext';
+import { TextInput } from '@cratis/components/Common';
 
 export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
     const [name, setName] = useState('');
@@ -150,10 +150,10 @@ export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
             onConfirm={() => closeDialog(DialogResult.Ok, { name })}
             onCancel={() => closeDialog(DialogResult.Cancelled)}
         >
-            <InputText
+            <TextInput
                 value={name}
-                onChange={event => setName(event.target.value)}
-                autoFocus
+                onChange={value => setName(value)}
+                aria-label="Project name"
             />
         </Dialog>
     );
@@ -249,16 +249,20 @@ Use `buttons={null}` for dialogs that contain their own internal actions (e.g. a
 
 | Prop | Type | Notes |
 |---|---|---|
-| `title` | `string` | Header text (replaces PrimeReact `header`) |
-| `visible` | `boolean` | Controls visibility |
+| `title` | `string` | Header text |
+| `visible` | `boolean` | Controlled open state; defaults to `true` |
 | `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 |
+| `isBusy` | `boolean` | Disables every action **and every dismissal path** while work is in flight |
+| `initialFocus` | `DialogInitialFocus` | Where focus lands on open; defaults to the confirmation action — the **cratis-components-accessibility** skill covers the armed-Enter hazard |
+| `okLabel` / `cancelLabel` / `yesLabel` / `noLabel` | `string` | Per-dialog label; falls back to the provider's `messages.dialog`, then English |
+| `closeAriaLabel` | `string` | Accessible name of the header close button; same fallback chain |
 | `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 |
+| `onCancel` | `() => boolean \| void \| Promise<boolean> \| 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` |
+| `width` | `string` | Dialog width (e.g. `'50vw'`); defaults to `450px` |
+| `dismissable` | `boolean` | Header close, Escape and backdrop dismissal (when not busy) |
+| `style` / `contentStyle` / `className` | | Modal-root and content-region styling |
+| `pt` | `DialogParts` | Per-part attributes: `backdrop`, `positioner`, `root`, `header`, `title`, `close`, `content`, `footer`, `confirm`, `cancel` |
 
-`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.)
+`resizable`, `ptOptions` and `unstyled` are accepted for source compatibility and do nothing. There is no `modal`, `draggable`, `footer` or `onHide` — the dialog is always modal, the footer comes from `buttons`, and closing is reported through `onCancel`/`onClose`. Style the dialog through its parts (`pt`, or `[data-cratis-part='root']` selectors), never through React Aria class names.