@cratis/pi 2.21.3 → 2.23.0

package/package/corpus/rules/efcore.md

@@ -10,226 +10,74 @@ profile: application
 > **⚠️ APPLIES ONLY TO PROJECTS USING ENTITY FRAMEWORK CORE**
 > If your project does not reference `Microsoft.EntityFrameworkCore` or any EF Core packages, **ignore this entire file**. These rules are irrelevant outside of EF Core contexts.
 
-## Project Structure
+`Cratis.Arc.EntityFrameworkCore` gives an Arc application EF Core-backed read models: two `DbContext` base types, convention-based registration, provider selection from the connection string, cross-database column helpers for migrations, concept-aware value conversion, and live observation of a `DbSet`. **That is the whole of what Arc ships** — it has no migration runner, no table-name constant convention, no design-time factory and no prescribed project split. Where an application adds one of those, it is that application's local convention, not Cratis; keep such conventions in the repository's own instructions, never present them as framework. The step-by-step workflow, the exact signatures and the traps live in the **cratis-arc-ef-core-migration** skill; this rule states the invariants.
 
-Responsibilities are split across three projects:
+## DbContext base types **[contract]**
 
-| Project | Responsibility |
-|---------|----------------|
-| `Database` | Migrations only – no entities, no DbContexts |
-| `Core` | Entities and feature DbContexts (co-located with features) |
-| `Infrastructure` | DbContext registration, migration runner, cross-cutting EF setup |
+Always derive from one of Arc's base types — never directly from `DbContext`:
 
-**Critical dependency rule**: `Database` must NEVER import from `Core`. Migrations reference only `WellKnownTables` constants (strings) and EF migration types. The dependency chain is:
-
-```
-Core → Infrastructure → Database
-```
-
-## DbContext Base Types
-
-Always use the Cratis Arc base types — never inherit directly from `DbContext`:
-
-- **`ReadOnlyDbContext`** — for all read model / projection contexts (the vast majority)
-- **`BaseDbContext`** — only for writable contexts that own state (e.g. device state, infrastructure state)
+- **`ReadOnlyDbContext`** — for every read model / projection context (the vast majority). Its save-changes interceptor **throws** on any `SaveChanges`, so a projection cannot be bypassed by accident.
+- **`BaseDbContext`** — only for a writable context that genuinely owns state (device state, infrastructure state).
 
 ```csharp
-// ✅ Read model context
 public class StartupPhaseDbContext(DbContextOptions<StartupPhaseDbContext> options)
     : ReadOnlyDbContext(options)
 {
     public DbSet<StartupPhase> StartupPhases => Set<StartupPhase>();
-    public DbSet<PersonnelAssignment> PersonnelAssignments => Set<PersonnelAssignment>();
-}
-
-// ✅ Writable (state-owning) context
-public class DeviceStateDbContext(DbContextOptions<DeviceStateDbContext> options)
-    : BaseDbContext(options)
-{
-    public DbSet<DeviceState> DeviceStates => Set<DeviceState>();
 }
 ```
 
-Use the primary constructor pattern. Expose `DbSet<T>` as expression-bodied properties using `Set<T>()`.
+Use the primary constructor; expose each `DbSet<T>` as an expression-bodied property over `Set<T>()`. Co-locate the context with the feature whose read models it holds.
 
-## Feature Contexts — Not God Contexts
+## Feature contexts — not god contexts **[convention]**
 
-Create one focused DbContext per feature or tightly-related feature group. Never aggregate unrelated entities into a single context.
+One focused `DbContext` per feature or tightly related feature group. Never aggregate unrelated entities into a single context: a context's shape is a cohesion boundary, and a god context couples every feature's schema change to every other's.
 
-```csharp
-// ❌ God context
-public class AppDbContext : DbContext
-{
-    public DbSet<Mission> Missions { get; set; }
-    public DbSet<User> Users { get; set; }
-    public DbSet<Station> Stations { get; set; }
-    // ... many more
-}
-
-// ✅ Focused feature context
-public class StartupPhaseDbContext(DbContextOptions<StartupPhaseDbContext> options)
-    : ReadOnlyDbContext(options)
-{
-    public DbSet<StartupPhase> StartupPhases => Set<StartupPhase>();
-    public DbSet<PersonnelAssignment> PersonnelAssignments => Set<PersonnelAssignment>();
-}
-```
-
-Co-locate the DbContext file with its feature:
-
-```
-Missions/Ongoing/StartupPhase/
-├── StartupPhase.cs
-├── StartupPhaseDbContext.cs
-└── ...
-```
-
-## State Mutation — The Golden Rule
+## State mutation — the golden rule **[convention]**
 
 > **Never mutate state directly through a DbContext.**
 
-All state changes must flow through events and Chronicle projections. Direct writes bypass the audit trail and event log.
-
-```csharp
-// ❌ Direct mutation — forbidden
-dbContext.StartupPhases.Add(new StartupPhase(...));
-await dbContext.SaveChangesAsync();
-
-// ✅ Correct: emit an event, let the projection handle writes
-[Command]
-public record UpdateStartupPhase(MissionId MissionId, ...) { ... }
-```
-
-Only infrastructure projection code, the Chronicle event engine, and reference data sync may write through DbContexts.
+All state changes flow through events and Chronicle projections; a direct write bypasses the event log and the audit trail. Only projection infrastructure, the Chronicle engine, and deliberate reference-data synchronization write through a context — and those are `BaseDbContext`s, never `ReadOnlyDbContext`s.
 
-## Registration
-
-Use the Cratis Arc `Cratis.Arc.EntityFrameworkCore` extension methods:
-
-```csharp
-// Register a single writable DbContext
-services.AddDbContextWithConnectionString<DeviceStateDbContext>(connectionString, optionalConfigure);
-
-// Auto-discover and register ALL ReadOnlyDbContext subtypes from given assemblies
-services.AddReadModelDbContextsWithConnectionStringFromAssemblies(
-    connectionString,
-    configureOptions,
-    [Assembly.GetExecutingAssembly()]);
-```
+## Registration **[contract]**
 
-Configure the database provider using `UseDatabaseFromConnectionString`, which auto-detects PostgreSQL vs SQLite from the connection string:
+Wire EF Core through the Arc builder and give it the connection string:
 
 ```csharp
-options.UseDatabaseFromConnectionString(connectionString);
+builder.AddCratisArc(arc => arc.WithEntityFrameworkCore(
+    options => options.ConnectionString = connectionString));
 ```
 
-Centralize all DbContext setup in a single `AddApplicationDbContexts` extension method per layer.
+With a non-empty connection string and `AutoDiscoverDbContexts` (the default), Arc discovers every public `BaseDbContext` subtype not marked `[IgnoreAutoRegistration]`, registering `ReadOnlyDbContext` subtypes read-only and the rest read-write. ⚠️ `WithEntityFrameworkCore()` with **no** connection string discovers nothing. Explicit registration remains available (`AddDbContextWithConnectionString<T>`, `AddReadOnlyDbContextWithConnectionString<T>`, `AddReadModelDbContextsFromAssemblies`, `AddReadModelDbContextsWithConnectionStringFromAssemblies`).
 
-## Multiple Database Support
+Select the provider with **`UseDatabaseFromConnectionString(connectionString)`** — never hard-code `UseSqlite` / `UseNpgsql` / `UseSqlServer`. It infers `DatabaseType` (`Sqlite`, `SqlServer`, `PostgreSql`) from the connection string, ensures a SQLite file's directory exists, and installs Arc's migrations SQL generator for that provider (which is what adds the JSON validation constraint for `[Json]` columns). An unsupported connection string throws `UnsupportedDatabaseType`.
 
-The application supports both PostgreSQL (ASP.NET mode) and SQLite (MAUI mode) from the same code. The provider is selected at runtime via the connection string — `UseDatabaseFromConnectionString` handles the detection.
+## Migrations **[contract]/[convention]**
 
-Never hardcode a provider (e.g. `UseSqlite` or `UseNpgsql`) in application code. Always use `UseDatabaseFromConnectionString`.
-
-## Migrations
-
-Migrations live exclusively in the **`Database`** project, never in `Core` or `Infrastructure`.
-
-### Organization
-
-Each entity category has its own folder with versioned migration files:
-
-```
-Database/
-├── Missions/
-│   ├── v1_0_0.cs
-│   └── v1_1_0.cs
-├── Users/
-│   └── v1_0_0.cs
-└── WellKnownTables.cs
-```
-
-### Naming
-
-Version files using the pattern `v{major}_{minor}_{patch}.cs` and place them inside a namespace matching their folder:
-
-```csharp
-namespace Database.Missions;
-
-public class v1_0_0 : Migration
-{
-    protected override void Up(MigrationBuilder migrationBuilder) { ... }
-    protected override void Down(MigrationBuilder migrationBuilder) { ... }
-}
-```
-
-The migration ID is composed as `{folder}_{ClassName}` (e.g. `Missions_v1_0_0`).
-
-### Cross-Database Column Helpers
-
-Always use the Cratis Arc `MigrationBuilder` extension helpers to define columns. These abstract over PostgreSQL and SQLite type differences:
+Migrations are created and applied with the **standard EF Core tooling** (`dotnet ef migrations add`, `dotnet ef database update`, or `Database.Migrate()` at startup). Arc adds only the column helpers that keep one migration valid across all three providers — use them instead of raw `table.Column<T>()`:
 
 | Helper | Use for |
-|--------|---------|
-| `table.StringColumn(migrationBuilder)` | Text / varchar columns |
-| `table.GuidColumn(migrationBuilder)` | UUID / GUID columns |
-| `table.NumberColumn<T>(migrationBuilder)` | Integer, long, or numeric columns |
-| `table.DateTimeOffsetColumn(migrationBuilder)` | Timestamps with timezone |
-
-Never use raw EF `table.Column<string>()` etc. — the helpers ensure cross-database compatibility.
-
-```csharp
-// ✅ Cross-database migration
-migrationBuilder.CreateTable(
-    name: WellKnownTables.Missions,
-    columns: table => new
-    {
-        Id = table.StringColumn(migrationBuilder, nullable: false),
-        Title = table.StringColumn(migrationBuilder, maxLength: 200, nullable: false),
-        ResourceId = table.NumberColumn<int>(migrationBuilder, nullable: true),
-        DispatchTime = table.DateTimeOffsetColumn(migrationBuilder),
-        UrgencyId = table.GuidColumn(migrationBuilder)
-    },
-    constraints: table =>
-    {
-        table.PrimaryKey("PK_Missions", x => x.Id);
-        table.ForeignKey("FK_Missions_Urgency", x => x.UrgencyId,
-            WellKnownTables.MissionUrgencies, "Id", onDelete: ReferentialAction.SetNull);
-    });
-```
-
-### Table Names — WellKnownTables
-
-Always reference table names from `WellKnownTables` constants. Never use magic strings directly in migrations.
+| --- | --- |
+| `table.StringColumn(migrationBuilder, …)` | text |
+| `table.GuidColumn(migrationBuilder, …)` | GUID / UUID |
+| `table.NumberColumn<T>(migrationBuilder, …)` | integers, longs, decimals |
+| `table.BoolColumn(migrationBuilder, …)` | booleans |
+| `table.DateTimeOffsetColumn(migrationBuilder, …)` | timestamps with offset |
+| `table.AutoIncrementColumn(migrationBuilder, …)` | identity columns |
+| `table.JsonColumn<TProperty>(migrationBuilder, …)` | a `[Json]`-mapped property |
+| `migrationBuilder.Add{String,Guid,Number,Bool,DateTimeOffset,AutoIncrement,Json,Point,LineString,Polygon}Column(…)` | adding a column to an existing table |
 
-```csharp
-// ❌ Magic string
-migrationBuilder.CreateTable(name: "Missions", ...);
-
-// ✅ Constant
-migrationBuilder.CreateTable(name: WellKnownTables.Missions, ...);
-```
-
-Add new table names to `Database/WellKnownTables.cs` before writing the migration.
+Where a repository organizes its migrations (a dedicated project, a versioned file naming scheme, a table-name constants class) is its own convention: follow what the repository already does, and do not introduce one as if Arc required it.
 
-### Applying Migrations
+## Concepts and JSON **[contract]**
 
-Migrations are applied via a custom runner from the `Database` project (not `dotnet ef database update`):
-
-```csharp
-// ASP.NET mode
-await app.ApplyAllMigrations(connectionString);
-
-// MAUI / IServiceProvider mode
-await services.ApplyAllMigrations(connectionString);
-```
+`ConceptAs<T>` properties map to their underlying primitive without per-property value converters: `BaseDbContext.OnModelCreating` applies the concept conversions, and every Arc registration path calls `AddConceptAsSupport()` so concepts also work inside LINQ predicates. (A context you register with plain EF `AddDbContext` must call `options.AddConceptAsSupport()` itself.) Mark a property `[Json]` to store it as a JSON column with the provider's validation constraint.
 
-The runner discovers all `Migration` subclasses from the `Database` assembly, checks the EF history table, and applies pending migrations in version order within a transaction. Both PostgreSQL and SQLite are supported through the same runner.
+## Observation **[contract]**
 
-## Auto-Discovery
+An EF Core read model can back an observable query: `dbSet.Observe(...)`, `ObserveById(...)` and `ObserveSingle(...)` (extension methods declared in the `Microsoft.EntityFrameworkCore` namespace, so they are in scope wherever the `DbSet` is) push changes through the provider's change notifier — see the skill for what each provider supports.
 
-The Cratis Arc `IImplementationsOf<T>` mechanism discovers DbContext types at runtime:
+## See also
 
-- `IImplementationsOf<BaseDbContext>` — all `DbContext` subtypes across all loaded assemblies.
-- `DiscoverAndFilterDbContextTypes<ReadOnlyDbContext>(assemblies)` — discovers the read-model contexts; the registration helpers (`AddReadModelDbContextsWithConnectionStringFromAssemblies` / `AddReadModelDbContextsFromAssemblies`) build on it.
-- To isolate **writable** contexts, filter the discovered set on assignability — `types.Where(t => !typeof(ReadOnlyDbContext).IsAssignableFrom(t))` — rather than a dedicated extension.
+- the **cratis-arc-ef-core-migration** skill — wiring, making an EF read model injectable into a command, writing a migration, observing, and specs.
+- [efcore.specs.md](./efcore.specs.md) — `DbContext` specs with SQLite in-memory.

package/package/corpus/rules/framework.md

@@ -24,7 +24,7 @@ Each framework repo is organized by what it builds, not by feature slices:
 - **Fundamentals** — the base library. `ConceptAs<T>`, type discovery (`IInstancesOf<T>` / `IImplementationsOf<T>`), serialization, common primitives. `Source/DotNET` (C#) + `Source/JavaScript` (`@cratis/fundamentals`) + the shared ESLint config.
 - **Arc** — the CQRS + model-binding + proxy-generation engine. `Source/DotNET` (the command/query pipeline, validation, authorization, identity, the Roslyn **proxy generator**) + `Source/JavaScript` (`@cratis/arc`, `@cratis/arc.react`, `@cratis/arc.react.mvvm`). Arc.Core does **not** depend on Chronicle.
 - **Chronicle** — the event-sourcing engine. `Source/Kernel` (the engine: **Orleans grains**, event sequences, observers/projections/reducers, storage providers — MongoDB and others), `Source/Clients` (the client SDKs incl. `DotNET` and `Testing`), `Infrastructure`, `Tools`, `Workbench`. The kernel is the deep, performance- and consistency-critical core.
-- **Components** — the React component library on PrimeReact. `Source/<Component>/` folder per component (`CommandDialog`, `DataPage`, `DataTables`, …) with Storybook stories; published as `@cratis/components`. (Application rules *consume* these components; here you *build* them.)
+- **Components** — the React component library (Components-owned markup and styling contract; React Aria internally; optional PrimeReact/MUI presentation adapters under `Adapters/`). `Source/<Component>/` folder per component (`CommandDialog`, `DataPage`, `DataTables`, …) with Storybook stories; published as `@cratis/components`. (Application rules *consume* these components; here you *build* them.)
 
 Repo conventions follow from this: `Source/DotNET` + `Source/JavaScript` for dual-stack libraries; `Kernel` vs `Clients` for Chronicle; a folder-per-component library layout for Components. Match the structure of the area you are editing — do not introduce app-style layouts.
 

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

@@ -29,7 +29,7 @@ Stop-and-fix signals during implementation and review:
 |---|---|---|
 | New component added without checking the shared component surface and `@cratis/components` | Duplicates fragment the design system | Reuse an existing primitive/wrapper, or document the missing one |
 | Slice-local helper promoted to the shared component folder after one use | Freezes a one-off as a shared API | Keep it beside the slice until a second real consumer appears |
-| Raw `primereact/*` import where a Cratis wrapper exists | Bypasses Arc behavior, overlay fixes, validation | Use the `@cratis/components` subpath wrapper |
+| A vendor UI control (any `primereact/*`, `@mui/*`, … import) where a Cratis component exists | Bypasses Arc binding, the overlay environment and validation; adds a second focus owner | Use the `@cratis/components` subpath component |
 | Import from the `@cratis/components` root barrel in new code | Pulls optional-peer-heavy exports, hides intent | Import from subpaths (`CommandDialog`, `DataPage`, `DataTables`, `Dialogs`, `Dropdown`, `Toolbar`, `Common`) |
 | Component API has many boolean visual flags (`primary`, `selected`, `muted`, …) | State combinations become undefined | One typed `variant`/`tone` union, or split components |
 | A reusable component reaches into domain strings, generated proxies, identity, query, command, or navigation | It is no longer a primitive | Move it to the slice, or make it explicitly Cratis-aware and test/story it as such |

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
 
@@ -154,25 +105,7 @@ A claim is only as good as the signal behind it — a build result, a test run,
 
 ## 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.
+The framework discovers commands and read models by attributes and static methods — **the folder shape is a convention, not a requirement.** The house default: the domain hierarchy lives directly under the app source root (**no top-level `Features/` wrapper**), cross-cutting concerns (`Common/` concepts, `Identity/`, shared components) at the top level, and one folder per behavior — `<Module>/<Feature>/<Slice>/` holding `<Slice>.cs`, the slice's `.tsx`, and its `when_*/` specs. **The slice is the invariant unit** — created, renamed, and deleted as one. Namespace mirrors the path under the source root, dropping any level that isn't present. The full tree and the split rules are in [vertical-slices.md](./vertical-slices.md).
 
 ## Slice Types
 
@@ -195,7 +128,7 @@ Tagged **[contract]** (framework-enforced) or **[convention]** (house default).
 
 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`.
+3. **[contract] Event-source id resolution:** `ICanProvideEventSourceId` first; else the first qualifying property in declaration order — an `EventSourceId`/`EventSourceId<T>`-derived value *or* a `[Key]` property (no priority between them; two candidates is `ARCCHR0002`); else Arc 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.
@@ -206,21 +139,19 @@ Tagged **[contract]** (framework-enforced) or **[convention]** (house default).
 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.
+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 commands (or use `ICommandPipeline` and inspect the result); 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).
+16. **[convention] Use the Cratis dialogs** — `CommandDialog` from `@cratis/components/CommandDialog`, `Dialog` from `@cratis/components/Dialogs`; never a vendor or hand-rolled modal. The default frontend stack is Cratis Components **4.x** (Components-owned markup, `--cratis-*` tokens, `pt`/`data-cratis-part` parts; no PrimeReact dependency) — **not** Tailwind (Tailwind is one supported way to write the token-mapping CSS, 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.
+- **Phase 0 — Model.** Confirm Module/Feature, slice name, slice type, domain rules; for new behavior or unclear event vocabulary run the **event-modeling** skill first.
+- **Phase 1 — Backend.** Implement a coherent slice change. **Gate:** incremental Debug build of the affected project (regenerates proxies, compiles `#if DEBUG` spec code).
+- **Phase 2 — Specs.** Mandatory for every slice type, in-process scenario family first (`CommandScenario<T>`, `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>`). **Gate:** tests pass.
+- **Phase 3 — Frontend.** Build from the generated proxies, register in the composition page, wire routing. **Gate:** lint, conditional test, build.
 
-**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.
+**Backend before frontend, always** — the frontend depends on proxies that exist only after a successful build. Generate proxies from the **Debug** build (house convention); verify Release without re-running the generator: `dotnet build -c Release -p:CratisProxiesOutputPath=`. Why that property, and what to do when nothing is generated: the **cratis-arc-command** skill's proxy-generation reference.
 
 ## Quality Gates
 
@@ -235,7 +166,7 @@ Tagged **[contract]** (framework-enforced) or **[convention]** (house default).
 
 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).
+Documentation-only changes carry non-release intent and run the documentation checks, never a blanket exemption from red CI — see [pull-requests.md](./pull-requests.md).
 
 ---
 
@@ -258,7 +189,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 +199,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 +220,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 commit, push, create a PR, ship, or land changes, use the **ship-changes** prompt (`.cratis/ai/prompts/ship-changes.prompt.md`).
 
 ## General
 
@@ -305,11 +236,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/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.