@cratis/pi 2.22.0 → 2.23.1

package/package/corpus/rules/frontend-testing.md

@@ -69,7 +69,7 @@ Behavior that can regress without TypeScript catching it:
 - Command orchestration outside `CommandDialog`: handling of unauthorized / invalid / exception / success outcomes.
 - React component rendering only when markup, wrapper behavior, disabled state, or integration with a wrapped component is the point.
 
-**Do not test:** generated Cratis proxies; framework/PrimeReact internals; CSS pixel-perfection; trivial presentational pass-throughs with no branch/derived behavior.
+**Do not test:** generated Cratis proxies; framework/Cratis Components internals; CSS pixel-perfection; trivial presentational pass-throughs with no branch/derived behavior.
 
 ## View models
 
@@ -90,9 +90,9 @@ import React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { vi } from 'vitest';
 
-vi.mock('primereact/dialog', () => ({
-    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
-        React.createElement('div', null, props.footer, props.children),
+vi.mock('@cratis/components/Dialogs', () => ({
+    Dialog: (props: { buttons?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', null, props.children, props.buttons),
 }));
 
 describe('when rendered while busy', () => {

package/package/corpus/rules/general.md

@@ -2,7 +2,7 @@
 
 Cratis repositories come in **two profiles**, and the rules are scoped to them. **Identify your profile first** — it decides which rules apply.
 
-- **Application profile (default)** — you are *building an application on Cratis*: event-sourced CQRS with **Cratis Chronicle** + **Cratis Arc**, vertical slices, read models persisted to MongoDB/EF Core, and a React + Cratis Components (PrimeReact) frontend in MVVM. Most of this corpus targets this profile.
+- **Application profile (default)** — you are *building an application on Cratis*: event-sourced CQRS with **Cratis Chronicle** + **Cratis Arc**, vertical slices, read models persisted to MongoDB/EF Core, and a React + Cratis Components (4.x) frontend in MVVM. Most of this corpus targets this profile.
 - **Framework profile** — you are *contributing to a Cratis framework repository itself* (Arc, Chronicle, Fundamentals, Components, …). These are **libraries** — source generators, the Chronicle kernel (Orleans grains + storage), client SDKs, a React component library — **not** vertical-slice event-sourced apps. The application-architecture rules here **do not apply**; follow **[framework.md](./framework.md)**.
 
 **How to tell:** if the repo's own package is `Cratis.*` / `@cratis/*` and it *builds* the framework, you are in the framework profile. If it *consumes* Cratis to build a product, you are in the application profile.
@@ -76,66 +76,17 @@ immediately before acting and stop only when drift invalidates the authorized sc
 or recovery plan. Git history rewrites remain prohibited unless the user explicitly
 requests one.
 
-## New Repository Strategy Intake
-
-When a repository is created in the Cratis organization, prepare one transient,
-no-effect Strategy intake proposal. Do not create, comment on, assign, mention,
-link, or otherwise mutate a GitHub issue unless a current repository profile and
-the exact operation are separately accepted. Tool access and a request to create
-the repository do not supply that issue-effect authority.
-
-The proposal should include only the bounded facts needed for Strategy triage:
-
-- repository name, URL, visibility, and creation state;
-- purpose, intended users, lifecycle, and whether it is canonical, generated,
-  experimental, operational, or scheduled for retirement;
-- accountable owner or explicit vacancy and cross-repository boundaries;
-- upstream/downstream dependencies and current owning records;
-- release, distribution, credential, security, privacy, compliance, and data
-  expectations; and
-- requested Strategy identity, portfolio, metadata, ownership, and local AI
-  context review.
-
-First decide whether no record, an existing Strategy record, a bounded update
-proposal, a new proposal, or a sensitive human route is appropriate. Treat the
-result as Strategy intake, not strategic approval. Do not invent Strategy
-metadata or copy private Strategy content into a public repository. Repository
-creation does not require an issue URL; unresolved Strategy reconciliation is an
-explicit next action for the authorized human/owning process.
-
 ## Shared AI Distribution
 
-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 approved in `Cratis/AI`, generated
-into `Cratis/AI.Distribution`, and installed only from an immutable reviewed
-version after its release gates pass. Keep existing repository-local AI files in
-place while the replacement distribution remains 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 by changing a version pin through the approved organization or
-host mechanism. Canary the new version, observe its behavior and gates, and roll
-back by version when needed. Never patch generated distribution bytes or
-marketplace wrappers by hand.
+Two invariants; the mechanics of every channel (`cratis ai install`, `@cratis/pi`,
+the plugin marketplaces) are in [ai-distribution.md](./ai-distribution.md):
+
+- Never copy or synchronize `.cratis/ai`, `.agents`, `.claude`, `.github`, or `.pi`
+  trees between repositories, and never patch managed files under `.cratis/ai/`
+  by hand — update through the channel that installed them.
+- The consuming repository owns its project facts, confidential behavior, and
+  local skills; installing, updating, or uninstalling shared AI never merges,
+  overwrites, or removes them.
 
 ## Verification Discipline
 
@@ -144,98 +95,13 @@ A claim is only as good as the signal behind it — a build result, a test run,
 - **Confirm "done"/"fixed"/"correct" against a fresh signal — never self-assessment.** Run the relevant gate and observe it pass *this time*.
 - **After a fix, re-run the gate that failed.** Don't argue yourself to green.
 - **A green build is not behavioral correctness.** Compilation proves it builds, not that the slice does the right thing — that's what specs and exercising the UI are for.
-- **Report with inspectable evidence, and name what you didn't verify.**
+- **Report the conclusion and what you didn't verify, in a line or two.** Show the output when asked, when a claim is contested, or when the check failed — see [verification-discipline.md](./verification-discipline.md).
 
 ---
 
 # Application profile
 
-> The following — **Project Layout, Slice Types, Slice Naming, the Rules, and the Implementation Workflow** — applies when **building an application on Cratis**. If you are contributing to a Cratis framework repo, skip to **Framework profile** below and follow [framework.md](./framework.md).
-
-## Project Layout (Cratis Application convention)
-
-The framework discovers commands and read models by attributes and static methods — **the folder shape is a convention, not a requirement.** The house default keeps everything for one behavior together, with **no top-level `Features/` wrapper**: the domain hierarchy lives directly under the app source root.
-
-```
-<AppSourceRoot>/                 e.g. Source, Source/Core (app-defined)
-├── Common/                      shared ConceptAs<T> / EventSourceId<T> types
-├── Identity/ Components/ ...    cross-cutting / shared concerns, at the top level
-└── <Module>/                    top-level domain area — natural for most apps, NOT required
-    └── <Feature>/               grouping within the domain area
-        ├── <Feature>.tsx        pass-through layout (renders <Outlet/>)
-        ├── <Concept>.cs         feature-level concept types
-        └── <Slice>/             one folder per behavior — the invariant unit
-            ├── <Slice>.cs       backend artifacts for the slice in one file
-            ├── *.tsx            React component(s) for the slice
-            └── when_*/          spec folders
-```
-
-**The slice is the invariant unit** — one behavior (command + events + projection + component + specs), created/renamed/deleted together. Features group related slices. A `<Module>` is the natural top-level domain grouping for larger areas (e.g. `Accounts`, `Admin`, `Requests`) but is **not required** — a feature may sit directly under the source root when no module grouping is natural; depth follows what fits the application. Cross-cutting concerns (shared concepts in `Common/`, shared components, identity) live at the top level. Namespace mirrors the path under `<AppSourceRoot>` (`<RootNamespace>.<Module>.<Feature>.<Slice>`, dropping any level that isn't present). Splitting the backend file is allowed when a slice grows large or shared concepts move upward; the single-file shape is the default, not a mandate.
-
-> **No top-level `Features/` wrapper** — modules/features live directly under the app source root. The framework enforces no layout; this nested domain hierarchy is the chosen Cratis Application convention.
-
-## Slice Types
-
-Pick exactly one type per slice folder — determined by what the slice *does*.
-
-| Type | What it does | Contents |
-| --- | --- | --- |
-| **State Change** | Accepts a command, appends events | Command + validator + event(s); optional `[Passive]` read model for command-side decisions |
-| **State View** | Projects events into a queryable read model | `[ReadModel]` + model-bound projection + static query method(s) |
-| **Automation** | Reacts to events, calls external systems / `ICommandPipeline` | Reactor only |
-| **Translation** | Reacts to events and appends follow-up events to another stream | Reactor only |
-
-## Slice Naming (convention)
-
-Commands are imperative intents (`Register`, `Create`); the slice folder is the action only, never repeating a noun the Feature already establishes. **`[EventType]` records are past-tense facts** and must be self-describing (`AuthorRegistered`, never `Created`) — this past-tense, one-purpose naming is a Chronicle framework recommendation. Static query methods are descriptive reads (`AllAuthors`, `AuthorById`, `AuthorsByName`).
-
-## Rules
-
-Tagged **[contract]** (framework-enforced) or **[convention]** (house default). Mechanics and examples live in `vertical-slices.md`.
-
-1. **[contract] Model-bound — no controllers.** Commands are `[Command]` records with a public instance `Handle()` (Arc analyzers enforce this); queries are `static` methods on `[ReadModel]` records; projections/constraints/authorization use attributes. Arc generates the HTTP surface. Drop to fluent (`IProjectionFor<T>`, `IConstraint`) only when model-bound can't express the rule.
-2. **[contract] Command validation & data flow.** Put command rejection in `CommandValidator<T>`, global value invariants in `ConceptValidator<T>`, and fetched/computed handler data in **`Provide()`** (runs after validation/authorization; may short-circuit with `ValidationResult.Error` / `Result<TProvided, ValidationResult>`). Keep `Handle()` focused on event construction. For a state-dependent rule that must hold **under concurrency**, inject the read model into `Handle()` and return a typed error via `Result<TEvent, ValidationResult>`. **Throwing from `Provide()`/`Handle()` is an exception (HTTP 500), not a validation rejection** — throw only for genuinely exceptional conditions, never for normal business rejection.
-3. **[contract] Event-source id resolution order:** `ICanProvideEventSourceId` → an `EventSourceId`/`EventSourceId<T>`-derived value → `[Key]` → else Arc/Chronicle generates one. A value actually used as a Chronicle stream identity derives from `EventSourceId<T>` with the underlying `IComparable` primitive — never `ConceptAs<Guid>` for that stream identity. `NotSet`, `New()`, and primitive→derived-id operators are optional domain/API conveniences, not Chronicle requirements; typed empty/zero values are real specified stream IDs, not `EventSourceId.Unspecified`.
-4. **[contract] Events never carry the event-source id** — it is implicit in the event context.
-5. **[contract] `[Key]` / `[Subject]` are distinct.** `[Key]` is for event-source/read-model/projection key resolution; `[Subject]` is compliance identity only. Don't put either on an `EventSourceId<T>` value (it already is both); use them only for non-`EventSourceId<T>` values.
-6. **[contract] Avoid nullable event properties** — Chronicle's analyzer warns on them. Model optional facts as a separate event; resolve nullable command inputs to a non-null sentinel before constructing the event.
-7. **[contract] `[EventType]` takes no arguments for new events** — the type name is the identifier. Use `generation:`/id only when evolving an existing contract; schema changes get a new generation + an `EventTypeMigration<TUpgrade,TPrevious>` (never edit stored-event semantics silently). An enum that only gains a member, or has one renamed, is the exception — Chronicle accepts that in place; a *removed* or *renumbered* member still needs a generation, plus a value map saying what the old values became.
-8. **[convention] Every `[EventType]` has an XML `<summary>`** — a Cratis C# documentation convention (not a Chronicle rule); events live in the log forever, so record why they exist.
-9. **[convention] `[ReadModel]` properties carry no default values** except semantically meaningful enum initial states and `[SetValue<T>]`-driven `bool` flags. False defaults hide missing projection wiring.
-10. **[contract] AutoMap is on by default — never call `.AutoMap()`.** Match property names so AutoMap wires them; diverge with `[SetFrom<T>]` / fluent `.Set().To()` only for genuine name differences. Re-enable `.AutoMap()` only inside a scope where it was disabled with `.NoAutoMap()`.
-11. **[contract] Projections consume events and event context — never other read models.** Default to model-bound attributes; use fluent `IProjectionFor<T>` for joins/nested/context/transforms; use a reducer when the model is "current state + event → next state" (a valid style, not a failure mode).
-12. **[contract] Model-bound query custom paths use `[Path("...")]`** (`PathAttribute`), not ASP.NET `[Route]`. Reserve `[Route]` for controller-based endpoints (which this convention avoids).
-13. **[convention] Cross-slice access is read-only through Chronicle** — inject another slice's read model or reference its events; never instantiate or DI another slice's command/handler/service.
-14. **[contract] Never inject `IEventLog` into `Handle()`** — express appends through return types (`IEnumerable<object>` with `EventForEventSourceId` wrappers for cross-stream). In application reactors, return side-effect events or use `ICommandPipeline`; don't reach for `IEventLog` directly.
-15. **[contract] Never edit a generated file** — proxies carry a `// @generated by Cratis` header. Fix the C# source and rebuild.
-16. **[convention] Use the Cratis dialog wrappers** — never import `Dialog` from `primereact/dialog`; use `CommandDialog` / `Dialog` from `@cratis/components`. The default frontend stack is Cratis Components on PrimeReact theming/tokens/`pt` — **not** Tailwind (Tailwind is one supported unstyled path, not the generic default).
-17. **[convention] One slice is one unit** — creating/renaming/moving/deleting a slice means doing the same to every artifact (the `.cs`, every `when_*/`, every `.tsx`, the composition import/JSX, the route).
-
-## Implementation Workflow
-
-- **Phase 0 — Model the request.** Confirm Module/Feature, Slice name, slice type, domain rules. For new behavior or unclear event vocabulary, run the **event-modeling** skill before writing code.
-- **Phase 1 — Backend.** Implement a coherent slice change. **Gate:** incrementally build the affected Debug project to regenerate proxies and compile spec code; add Release verification when required for cross-cutting or merge/release gates (see the proxy-generation note below).
-- **Phase 2 — Specs.** Mandatory for every slice type, in-process scenario family first: `CommandScenario<T>` (commands), `EventScenario` (constraints/append), `ReadModelScenario<T>` (projections/reducers), `ReactorScenario<T>` (reactors). Reserve out-of-process integration specs for host/infra/transport boundaries. **Gate:** tests pass.
-- **Phase 3 — Frontend.** Proxies now exist. Build React components from generated proxies, register in the composition page, wire routing. **Gate:** lint, conditional test, and build all clean.
-
-**Backend before frontend, always** — the frontend depends on proxies that only exist after a successful Debug build. After a coherent set of changes, incrementally build/compile the affected project and run targeted regression checks before proceeding; do not build after every file.
-
-**Proxy generation runs on Debug, not Release.** `dotnet build -c Debug` is the canonical trigger for regenerating TypeScript proxies — it carries the fullest, most reliably-emitted PDB debug information the proxy generator relies on to place generated files. Generate proxies with a Debug build first; when you (or an agent) subsequently build Release purely to verify the app compiles in that configuration, skip proxy regeneration so the second build can't re-run the generator against a different compilation and touch already-correct generated files: `dotnet build -c Release -p:CratisProxiesOutputPath=`. The empty override clears the output path property the generator's MSBuild target is conditioned on, so the target no-ops for that invocation — no generated file is read or written.
-
-## Quality Gates
-
-| Phase | Command (app-pinned) | Pass criteria |
-| --- | --- | --- |
-| Backend | build (Debug) | zero errors, zero warnings — validates `#if DEBUG` spec code and regenerates proxies |
-| Backend | build (Release) | zero errors, zero warnings — build-only check; pass `-p:CratisProxiesOutputPath=` to skip re-running proxy generation |
-| Specs | test | zero failures |
-| Frontend | lint | zero errors |
-| Frontend | test | zero failures when frontend specs/behavior changed |
-| Frontend | build | zero errors |
-
-Run affected-project incremental checks after a coherent change, then targeted regression tests for the changed behavior. Re-run a failed gate after a relevant fix. Reserve wider matrices and clean/Release builds for cross-cutting changes, demonstrated stale outputs, or required merge/release gates. Documentation/rule-only edits need relevant Markdown, frontmatter, link, and corpus checks, not an application build. Diagnose unrelated or environmental failures within a bounded attempt; report the evidence and blocker instead of broadening scope or retrying indefinitely. Required gates remain blocking until satisfied; never silently waive red CI.
-
-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. See [pull-requests.md](./pull-requests.md).
+> **Building an application on Cratis?** Project layout, slice types, slice naming, the seventeen slice rules, the implementation workflow and the application quality gates are in [application-profile.md](./application-profile.md), which loads only for repositories that select an application profile. If you are contributing to a Cratis framework repo, see **Framework profile** below.
 
 ---
 
@@ -258,7 +124,7 @@ Documentation-only changes use repository-supported non-release intent, ordinari
 | For | Location |
 | --- | --- |
 | **AI Corpus Profiles** — what profiles exist and how to configure them | `profiles.md` |
-| **Contributing to a Cratis framework repo** (framework profile) | `framework.md` |
+| **Contributing to a Cratis framework repo** (framework profile) | `framework.md`; creating a repository in the Cratis organization: `new-repository-intake.md` |
 | Slice anatomy (commands, `Provide()`, validators, events, projections, read models, reactors, constraints, compliance, cross-slice) | `vertical-slices.md` |
 | C# / TypeScript style | `csharp.md`, `typescript.md` |
 | Service lifetimes — why anything taking a scoped dependency is scoped or transient, never a singleton | `csharp.md` |
@@ -268,18 +134,18 @@ Documentation-only changes use repository-supported non-release intent, ordinari
 | Spec patterns — the four `*Scenario` helpers (application only) | `specs.scenarios.csharp.md` |
 | Strongly-typed values (`ConceptAs<T>`, `EventSourceId<T>`) | `concepts.md` |
 | Shared term definitions (event, projection, reducer, reactor, observer, DCB, …) | `glossary.md` |
-| Diagnosing a misbehaving slice (read model stale, proxy missing, quarantine, …) | the **diagnose-slice** skill |
-| Inspecting or operating a **running** Chronicle store (failed partitions, replays, browsing events) with the `cratis` CLI | the **inspect-running-chronicle** skill |
+| Diagnosing a misbehaving slice | read model stale or startup crash: **cratis-chronicle-projection** (*Startup-crash traps*); reactor paused or quarantined: **cratis-chronicle-reactor** (*Failure behavior*); proxy missing: **cratis-arc-command** (*Generate the TypeScript proxy*) |
+| Inspecting or operating a **running** Chronicle store (failed partitions, replays, browsing events) with the `cratis` CLI | the **cratis-chronicle-cli-operations** and **cratis-cli-terminal-workbench** skills |
 | EF Core read models / migrations | `efcore.md`, `efcore.specs.md` |
 | PRs / commits | `pull-requests.md`, `git-commits.md` |
-| Reading, citing and superseding a decision record | `decision-records.md` |
+| Reading, citing and superseding a decision record | the **cratis-engineering-decision-record** skill |
 | Whether you are allowed to do the thing you are able to do | `capability-is-not-authority.md` |
-| What must stop and ask a human | `human-verdicts.md` |
+| What must stop and ask a human | `capability-is-not-authority.md` (absent authority for a consequential effect: stop and ask) |
 | What counts as evidence that something works | `verification-discipline.md` |
-| `next:` / `blocker:` values and when a comment is warranted | `work-records-and-comments.md` |
+| Where session notes, plans and handovers may live | `local-work-artifacts.md` |
 | Exit-code meaning and wrappers that lose a verdict | `exit-codes-and-wrappers.md` |
 | Writing a scan, allowlist or destructive pass that cannot pass vacuously | `guards-and-fuses.md` |
-| The section skeleton every engineering recipe follows | `engineering-recipe-skeleton.md` |
+| How the shared corpus is installed, updated and rolled back | `ai-distribution.md` |
 | Event modeling / schema migration / calling commands from code / paging / cross-cutting metadata / multi-tenancy | the matching skills |
 | Step-by-step recipes | `.cratis/ai/skills/` |
 
@@ -289,7 +155,7 @@ Documentation-only changes use repository-supported non-release intent, ordinari
 - **Skills and rules are the authoritative answer.** If not answered there, ask. Don't infer Cratis behavior from package internals.
 - Only make high-confidence suggestions.
 - Don't change dependency manifests / lockfiles / `global.json` / NuGet config unless explicitly asked.
-- When asked to commit, push, create a PR, ship, or land changes, use the **ship-changes** skill.
+- When asked to **ship** or **land** changes, use the **ship-changes** prompt (`.cratis/ai/prompts/ship-changes.prompt.md`); invoking it is what authorizes the branch → commits → push → PR → merge → cleanup chain it describes. A request to only commit, only push, or only open a PR authorizes exactly that step, under [Git commits](./git-commits.md) and [Pull requests](./pull-requests.md) — do not route it through ship-changes and do not add the later steps.
 
 ## General
 
@@ -305,11 +171,4 @@ Documentation-only changes use repository-supported non-release intent, ordinari
 
 ## Local AI work artifacts — `.ai-work/` only
 
-AI-assisted sessions produce working artifacts: plans, handover documents, session notes, continuation prompts, status boards, scratch analyses, research dumps. These are **work records, not documentation**:
-
-- Create every such artifact inside **`.ai-work/`** at the repository root — never at the repository root itself, never under documentation folders, never anywhere else.
-- `.ai-work/` is gitignored and must stay untracked. Never commit anything inside it, never `git add -f` anything inside it, and never remove the ignore entry.
-- These artifacts must never enter git history or reach GitHub — not on any branch. If you find an unrelated tracked work record, report its path and obtain explicit authorization before moving it into `.ai-work/`, removing it from tracking, or making a dedicated cleanup commit. Discovery alone does not authorize unrelated changes or a commit.
-- A genuine follow-up that must survive the session is **not** a work record — suggest opening a GitHub issue for it (or open one when asked) so future work is tracked where everyone can see it, instead of leaving a planning file behind.
-- Knowledge that must outlive the session belongs in the repository's documentation structure through normal review, not in a work record.
-- **A decision log is not a work record.** A decision — a durable choice with a decider and a date — is documentation: it lives in **`decisions/`** (or the repository's documented decisions folder) and is reviewed like any other documentation. A handover may summarize decisions; it never holds the only copy.
+Plans, handovers, session notes, scratch analyses and research dumps are **work records, not documentation**: they live only in the gitignored `.ai-work/` at the repository root, never enter git history, and are never the only copy of a durable decision (those go in `decisions/`). A follow-up that must outlive the session is an issue, not a file. Full rule: [local-work-artifacts.md](./local-work-artifacts.md).

package/package/corpus/rules/guards-and-fuses.md

@@ -8,6 +8,11 @@ A guard that cannot fail is worse than no guard: it converts "nobody looked" int
 check. Every line is tagged **[contract]** (binding) or **[convention]** (the house
 default) per the Three Levels of Authority in [`general.md`](./general.md).
 
+**Scope.** This rule governs two situations: *authoring* a scanner, guard, allowlist or
+checker, and *running a pass* that mutates a computed set of subjects rather than the
+targets the request named. An ordinary edit, review, fix, or a change to the one file the
+user pointed at is outside it and carries none of the machinery below.
+
 ## Non-vacuity
 
 - **[contract] A scan over a possibly-empty population carries a non-vacuity check.**
@@ -28,19 +33,28 @@ default) per the Three Levels of Authority in [`general.md`](./general.md).
 - **[convention] Prefer an expiry to a permanent exemption.** An entry nobody revisits is
   a rule quietly deleted.
 
-## Destructive passes
+## Bulk and irreversible passes
+
+These contracts are keyed to the *risk class* of the effect — bulk deletion, history
+rewriting, cross-repository migration, anything irreversible or high-fanout — not to
+whether a person is watching. An autonomous session runs them exactly as an interactive
+one does.
 
 - **[contract] Distinguish "subject set empty" from "qualifying set empty".** Finding no
   candidates at all is a different situation from finding candidates that none qualified;
-  an unattended pass must refuse to proceed on the first.
-- **[contract] Every unattended destructive pass carries a per-pass fuse** — a maximum
-  number of subjects it may act on in one run, which stops the run rather than trimming
-  the work silently.
-- **[contract] Prepare the inverse before the forward action.** If an exact inverse or a
-  safe compensation cannot be prepared, stop.
+  a pass must refuse to proceed on the first.
+- **[contract] Every pass carries a per-pass fuse** — a maximum number of subjects it may
+  act on in one run, which stops the run rather than trimming the work silently.
+- **[contract] Know the recovery before the forward action.** For a reversible effect,
+  know how it is undone. For an irreversible one, preserve what the recovery needs first —
+  a backup ref, a copy under `.ai-work/keep/`, the list of targets — and stop if nothing
+  can be preserved and the request did not name the targets. Do not demand an exact
+  inverse where none can exist.
 - **[contract] Re-read preconditions immediately before each mutation and stop when drift
   invalidates the authorized scope, safety assumptions, or recovery plan.** Benign drift
   within an already authorized bounded pass does not require another confirmation.
-- **[convention] Dry-run output is the review artifact for a destructive pass whose exact
-  targets were not already established in the conversation.** A user who has reviewed
-  and authorized those targets is not asked to approve the same pass again.
+- **[convention] When the targets were not already established in the conversation, show
+  the dry-run list and act on it once the user has answered.** A user who has reviewed
+  and authorized those targets is not asked to approve the same pass again. The list is a
+  message in the conversation, not a retained artifact: do not write receipts, ledgers,
+  snapshots or escrow copies of it.

package/package/corpus/rules/local-work-artifacts.md

@@ -21,6 +21,12 @@ dumps, and similar coordination files. These are **work records, not documentati
 - Knowledge that must outlive the session (real documentation, ADRs, operator
   guides) is written deliberately into the repository's documentation structure
   through normal review — not left behind as a work record.
+- **A worktree is a work record too.** Remove the worktree you created for a task
+  once its branch is merged to the default branch — pushed is not merged. Do it from
+  the parent checkout, after `git status --ignored` in the worktree, because a nested
+  `.ai-work/`, `.env` files and local databases are ignored and are deleted with it.
+  If the branch must outlive the task unmerged, leave the worktree and say so in the
+  handoff. Never `--force` a removal; a refusal means look, not push harder.
 - **A decision log is not a work record.** A decision — a durable choice with a
   decider and a date — is documentation: it lives in **`decisions/`** (or the
   repository's documented decisions folder) and is reviewed like any other

package/package/corpus/rules/new-repository-intake.md

@@ -0,0 +1,34 @@
+---
+applyTo: "**/*"
+profile: framework
+---
+
+# New Repository Strategy Intake
+
+This is Cratis organization process for maintainers creating repositories under the
+Cratis organization. It does not apply to applications built on Cratis.
+
+When a repository is created in the Cratis organization, prepare one transient,
+no-effect Strategy intake proposal. Do not create, comment on, assign, mention,
+link, or otherwise mutate a GitHub issue unless a current repository profile and
+the exact operation are separately accepted. Tool access and a request to create
+the repository do not supply that issue-effect authority.
+
+The proposal should include only the bounded facts needed for Strategy triage:
+
+- repository name, URL, visibility, and creation state;
+- purpose, intended users, lifecycle, and whether it is canonical, generated,
+  experimental, operational, or scheduled for retirement;
+- accountable owner or explicit vacancy and cross-repository boundaries;
+- upstream/downstream dependencies and current owning records;
+- release, distribution, credential, security, privacy, compliance, and data
+  expectations; and
+- requested Strategy identity, portfolio, metadata, ownership, and local AI
+  context review.
+
+First decide whether no record, an existing Strategy record, a bounded update
+proposal, a new proposal, or a sensitive human route is appropriate. Treat the
+result as Strategy intake, not strategic approval. Do not invent Strategy
+metadata or copy private Strategy content into a public repository. Repository
+creation does not require an issue URL; unresolved Strategy reconciliation is an
+explicit next action for the authorized human/owning process.

package/package/corpus/rules/orleans.md

@@ -10,41 +10,27 @@ paths:
 > **⚠️ APPLIES ONLY TO PROJECTS USING MICROSOFT ORLEANS**
 > If your project does not reference `Microsoft.Orleans` or any Orleans packages, **ignore this entire file**. These rules are irrelevant outside of Orleans contexts.
 
-These conventions apply to projects that use Microsoft Orleans for distributed grain-based actors.
+In the Cratis organization, Orleans is the Chronicle kernel's actor runtime (`Source/Kernel/`). These conventions describe how that kernel is shaped, verified against `Cratis/Chronicle` **v18.3.0**; follow them in any Cratis repository that hosts Orleans grains.
 
 ## General
 
-- Do **not** split Orleans grain interfaces into a separate project. Keep all grain types in the same project as their implementations.
-- Use localhost clustering for local development (`UseLocalhostClustering()`).
-- Do **not** add `[Alias]` attributes to grain interfaces or methods — rely on the default alias generated by Orleans.
+- Do **not** split grain interfaces into a separate project. Grain interfaces and their implementations live together in `Kernel/Core`; the `Contracts` project holds the gRPC contracts, not grain interfaces.
+- Clustering is chosen by the host, not the grain code: the server uses `UseLocalhostClustering(siloPort, gatewayPort, serviceId, clusterId)` for local development and the MongoDB storage integration switches on `UseMongoDBClustering` (`MongoDBMembershipStrategy.Multiple`) when clustering is enabled. A silo pointed at non-local shared storage while still on localhost clustering is logged as a **warning** at startup (each such node forms its own single-node cluster over the same data); `Cratis__Chronicle__Clustering__Type=MongoDB` on every node is what joins them.
+- Do **not** add `[Alias]` to grain interfaces or grain methods — rely on the default alias Orleans generates. `[Alias(nameof(Type))]` is used only on `[GenerateSerializer]` **state and definition records** in `Kernel/Concepts` (`ReadModelDefinition`, `IndexDefinition`, `ReadModelChangeContext`, `ProjectionFuture`), where a stable serialization alias must survive a rename.
 
-## Storage Providers
+## Grain storage providers
 
-- Centralize all storage provider names in a single `WellKnownStorageProviders` static class at the root of the project.
-- Reference provider names via the constants in `WellKnownStorageProviders` — never use magic strings.
-- Use `WellKnownStorageProviders.Default` as the name for the primary MongoDB-backed storage provider.
+- Storage provider names are constants in `WellKnownGrainStorageProviders` (`Kernel/Core`), **one name per concern** — 25 of them at v18.3.0 (`Namespaces`, `EventSequences`, `ObserverDefinitions`, `ObserverState`, `FailedPartitions`, `Jobs`, `JobSteps`, `Recommendations`, `Projections`, `ProjectionsManager`, `ProjectionFutures`, `Reactors`, `Reducers`, `ReducersManager`, `ReadModels`, `ReadModelsManager`, `ReadModelReplayManager`, `Constraints`, `EventStoreSubscriptionsManager`, `EventSeeding`, `Webhooks`, `WebhooksManager`, `DataProtectionKeys`, `PatchManager`, `System`). Reference a provider only through its constant — never a magic string, and there is no "default" provider.
+- Each concern has its own `IGrainStorage` implementation (`JobGrainStorageProvider`, `EventSequencesStorageProvider`, `NamespacesStateStorageProvider`, …) taking the kernel's `IStorage` abstraction — **not** a MongoDB collection. The storage backend (MongoDB, SQL, in-memory) is selected behind `IStorage`, so a grain storage provider never references a database driver.
+- Every provider is registered once, in `StorageProviderExtensions.AddStorageProviders(this ISiloBuilder)`, as a keyed singleton wrapped in `ResilientGrainStorage` (a Polly resilience pipeline configured from `Chronicle:ResilientStorage`). A new concern adds a constant, an `IGrainStorage` over `IStorage`, and one `AddKeyedSingleton(WellKnownGrainStorageProviders.<Name>, CreateResilientStorageFor<…>)` line there — nothing else.
+- Grains declare their state with `[PersistentState(nameof(<StateType>), WellKnownGrainStorageProviders.<Name>)]`.
 
 ```csharp
-public static class WellKnownStorageProviders
+public class JobGrainStorageProvider(IStorage storage) : IGrainStorage
 {
-    public const string Default = "MongoDbGrainStorage";
+    // ReadStateAsync / WriteStateAsync / ClearStateAsync over
+    // storage.GetEventStore(key.EventStore).GetNamespace(key.Namespace).Jobs
 }
-```
-
-- Annotate grains with `[StorageProvider(ProviderName = WellKnownStorageProviders.Default)]` when they need persistent state.
-
-## MongoDB Grain Storage
 
-- The `MongoDbGrainStorage<TState>` implementation accepts `IMongoCollection<TState>` as its only dependency — no additional plumbing is required.
-- Register it as a keyed singleton in the Orleans silo builder:
-
-```csharp
-builder.Host.UseOrleans(siloBuilder =>
-{
-    siloBuilder.UseLocalhostClustering();
-    siloBuilder.Services.AddKeyedSingleton<IGrainStorage>(
-        WellKnownStorageProviders.Default,
-        (sp, _) => new MongoDbGrainStorage<MyState>(
-            sp.GetRequiredService<IMongoCollection<MyState>>()));
-});
+services.AddKeyedSingleton(WellKnownGrainStorageProviders.Jobs, CreateResilientStorageFor<JobGrainStorageProvider>);
 ```

package/package/corpus/rules/profiles.md

@@ -1,3 +1,9 @@
+---
+applyTo: "**/.cratis/**"
+paths:
+  - "**/.cratis/**"
+---
+
 # AI Corpus Profiles
 
 Profiles determine which rules and skills apply to your work. They define the scope of the AI corpus and which documentation, conventions, and skills are available.

package/package/corpus/rules/react.md

@@ -8,7 +8,7 @@ paths:
 
 # React + Arc + Cratis Components
 
-The frontend is React + TypeScript in MVVM style, composed from **Cratis Components** on top of **Arc-generated proxies**. Cratis Components is PrimeReact-based; you reach PrimeReact almost exclusively through the Cratis wrappers. For component structure, styling, and icons see [components.md](./components.md); for dialogs see [dialogs.md](./dialogs.md). This rule covers MVVM, queries, and commands.
+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.md); for dialogs see [dialogs.md](./dialogs.md). This rule covers MVVM, queries, and commands.
 
 ## The proxy boundary
 
@@ -81,7 +81,7 @@ Extract as soon as a component has **any** of: 3+ `useState`, any `useCallback`
 
 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: `publish()` trickles **down** into nested scopes; bubbling **up** is opt-in with `{ bubble: true }`. Use the default `IMessenger` unless you genuinely need scoping.
+- **`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(); }`).
@@ -94,7 +94,7 @@ A typed proxy class is generated per query. Pick the hook:
 
 | Hook | When |
 |---|---|
-| `<Query>.use(args?, sorting?)` | standard — returns `[result]`, re-renders on change |
+| `<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>`) |
@@ -106,12 +106,12 @@ A typed proxy class is generated per query. Pick the hook:
 
 | Hook | Returns |
 |---|---|
-| `<Query>.use(args?, sorting?)` | `[result, perform]` |
+| `<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]` — **no `perform`** |
-| `<ObservableQuery>.useChangeStream(args?, getKey?, sorting?, isEnabled?)` | `ChangeSet<T> { added, replaced, removed }` |
+| `<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.
 
@@ -141,7 +141,7 @@ Inside dialogs, use `CommandDialog` + CommandForm fields rather than driving the
 | `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 `{ property, message }` — render per-field UI from it, but **never branch on raw `.message` text**. `exceptionMessages`/`exceptionStackTrace` are for logging, never for users.
+`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:
 
@@ -157,11 +157,11 @@ if (result.hasExceptions) { toast.error('Something went wrong'); console.error(r
 
 ### Command helpers
 
-- **`useCommandInstance(Command)`** — read the live reactive command instance for dependent fields (read it; never mutate — mutations go through field bindings).
+- **`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; members tracked automatically (no `addCommand`); 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`.
+- **`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`.
 
 ### `<Arc>` global configuration
 
@@ -175,7 +175,7 @@ Top-level provider for microservice name and API base path. Config props (with d
 | `queryConnectionCount` | `1` | hub connection slots |
 | `queryDirectMode` | `false` | direct per-query connection — dev use only |
 
-`QueryTransportMethod`/`ObservableQueryTransferMode` import 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.
+`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
 
@@ -185,11 +185,11 @@ Top-level provider for microservice name and API base path. Config props (with d
 
 ## Styling default
 
-Default to **Cratis Components on PrimeReact theming/tokens** (`var(--surface-*)`, `var(--primary-color)`, `var(--text-color)`, `pt`/unstyled where needed) — see [components.md](./components.md). Tailwind is **not** the Cratis default (it's one supported unstyled path). Never hard-code hex/`rgb()` for chrome.
+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.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.md) — component structure, CSS, PrimeReact tokens, icons, Storybook.
+- [components.md](./components.md) — component structure, CSS, `--cratis-*` tokens and parts, icons, Storybook.
 - [dialogs.md](./dialogs.md) — `CommandDialog` / `Dialog` / `StepperCommandDialog` rules.
 - [frontend-quality.md](./frontend-quality.md) — engineering bar; [frontend-testing.md](./frontend-testing.md) — BDD specs.
 - [typescript.md](./typescript.md) — TS style.