@cratis/pi 0.0.1 → 2.0.1

package/package/corpus/rules/framework.md

@@ -0,0 +1,52 @@
+---
+applyTo: "**/*"
+profile: framework
+---
+
+# Framework Profile — Contributing to Cratis Itself
+
+> **Framework profile only.** This applies when you are working **inside a Cratis framework repository** (Arc, Chronicle, Fundamentals, Components, Specifications, and the like) — building the framework. If you are building an *application on* Cratis, ignore this file and follow the Application profile (`general.md` + `vertical-slices.md`).
+
+The framework repos are **libraries**, not event-sourced applications. The application-profile architecture — vertical slices, model-bound `[Command]`/`[ReadModel]` artifacts, projections/read-models, reactors, MVVM app components — **does not exist here and must not be imposed**. A Cratis framework repo has its own architecture per its purpose.
+
+## What still applies (universal rules)
+
+Everything tagged `profile: universal` holds in framework repos exactly as in apps: **C# conventions** (`csharp.md`), **TypeScript conventions** (`typescript.md`), **code quality** (`code-quality*.md`), **specs** (`specs.md` / `specs.csharp.md` / `specs.typescript.md` — `Cratis.Specifications` is how the framework tests itself, using the plain `Specification` base + NSubstitute against the classes under test — this is the dominant mode in framework repos. The in-process `*Scenario` family lives in `specs.scenarios.csharp.md` (`profile: application`); it is the *application* default, and a framework repo reaches for it only to test the very engine it provides — Arc → `CommandScenario`, Chronicle → `EventScenario`/`ReadModelScenario`/`ReactorScenario` — not as a general testing mode. The **write-specs** skill is application-oriented), **documentation**, **git-commits**, **pull-requests**, **concepts** (`ConceptAs<T>` / `EventSourceId<T>` are Fundamentals/Chronicle primitives the framework defines and uses), and **American English**.
+
+## What does NOT apply
+
+Skip these `profile: application` rules entirely when in a framework repo: `vertical-slices.md`, `reactors.md`, `react.md`, `components.md`, `dialogs.md`, `frontend-quality.md`, `frontend-testing.md`, `storybook.md`, `efcore.md`, `efcore.specs.md`. Do not create vertical-slice folders, `[Command]`/`Handle()` records, read models, or MVVM app components in framework source.
+
+## The repos and their shape
+
+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.)
+
+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.
+
+## Framework-contributor principles
+
+- **Public API design is the product.** These libraries are consumed by every Cratis app, so the **Lovable APIs** value (`general.md`) is paramount: sane defaults, convention over configuration, extensible/overridable, minimal boilerplate. Design the API the app developer will love before the implementation.
+- **Backward compatibility is a contract.** A change to a public type, attribute, interface, or generated-proxy shape is a breaking change for every downstream app — label PRs by semver impact (`major`/`minor`/`patch`) and treat removals/renames of public surface as `major`.
+- **Convention discovery is built here.** `IInstancesOf<T>` / `IImplementationsOf<T>`, attribute-based discovery, and source generation are the mechanisms the framework *provides*; use them internally too rather than hand-registration where a convention fits.
+- **Source generators / analyzers** (Arc's proxy generator, Fundamentals) follow Roslyn conventions; their output is consumed verbatim by apps, so treat generated shape as public API.
+- **Orleans grains** in the Chronicle kernel follow `orleans.md`.
+- **An alternate implementation of an interface must match the primary one's *semantics*, not just its signature.** Chronicle ships several implementations of the same storage interfaces (MongoDB, SQL, in-memory) and the in-memory ones exist precisely so the real kernel code paths can run without infrastructure. When you touch one, **diff it against the persistent implementations** — the signature tells you nothing about the contract. The specific trap: query criteria carry **sentinels meaning "do not narrow"** (`EventSourceId.Unspecified`, `EventSourceType.Unspecified`/`Default`, `EventStreamType.All`, `EventStreamId.Default`, an empty event-type set). Callers asking for "everything" pass those sentinels, never `null`, so a plain `is not null` check narrows every row away and the read silently returns nothing. A divergence here does not fail — it makes specs pass vacuously, which is worse.
+- **A stub that silently succeeds is a bug, not a placeholder.** An unimplemented method returning `Task.CompletedTask`/an empty result lets a spec assert on work that never happened. Implement it, or make it fail loudly — never leave it quietly lying.
+- **Specs** use `Cratis.Specifications` (the `Establish`/`Because`/`should_` BDD style) with NSubstitute — the same philosophy as apps, without the Arc/Chronicle `*Scenario` app-testing helpers.
+- **Treat "no spec touches this public API" as a defect in itself.** Public surface with zero coverage is where silent breakage lives — an entire read surface, including two shipped assertion helpers, was once dead in `Cratis.Chronicle.Testing` because nothing ever called it. When adding public API, add at least one spec that exercises it end to end.
+
+## Quality gates (framework)
+
+- Build clean (Debug and Release) with **zero warnings, zero errors**.
+- Specs pass for affected projects (C# via `dotnet test`; TS packages via their test command; Components also `build-storybook`).
+- For public-facing changes (APIs, attributes, generated output, component props): update the product documentation and verify it.
+- Match the repo's existing patterns; when a deep architectural question isn't answered by the universal rules or this file, consult the **repo's own docs/CONTRIBUTING** or ask — do not infer framework internals from a single call site.
+
+## Depth lives in the repo
+
+This file is the cross-cutting framework-contributor baseline. Repo-specific internals — the Chronicle kernel's grain/observer/storage design, Arc's proxy-generator internals, the Components build pipeline — are owned by each repo's own documentation, not duplicated here. Follow those for area-specific detail.

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

@@ -0,0 +1,59 @@
+---
+applyTo: "**/*.{ts,tsx}"
+profile: application
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# Frontend Code Quality
+
+The frontend is software engineering, held to the same bar as the backend — and it is the part most prone to silent degradation under iterative AI editing: orphaned code, duplicated components, sprawling files, shipped placeholders, untested state machines hidden in JSX. This rule is the maintainability contract that prevents that. It complements [react.md](./react.md) (architecture), [typescript.md](./typescript.md) (style), and [frontend-testing.md](./frontend-testing.md) (specs).
+
+Aim for CUPID code: **Composable**, **Unix-like** (small focused pieces), **Predictable**, **Idiomatic**, **Domain-based**.
+
+## Non-negotiables
+
+1. **Never ship placeholder or dead UI as if it were real.** "Coming soon", lorem-ipsum, fake counts, and stubbed fixtures must not reach a screen backing a feature the code actually implements. An empty state is the *designed* empty state for that surface, not a build-time apology. When you implement the real behavior, delete the placeholder and its strings in the same change.
+2. **Components stay small and single-responsibility.** A `// Section` comment inside a component means that section is its own component. A presentational `.tsx` over ~150 lines, or with more than one clear responsibility, is decomposed. Parent owns state; children receive props.
+3. **State logic lives in a view model, not the component.** Per [react.md](./react.md): extract a `withViewModel` view model (or a tested state module) as soon as a component has 3+ `useState`, any `useCallback`/state-syncing `useEffect`, or derived values. `useCallback`/`useMemo` inside a `withViewModel` component is a smell. Never store React state in a view model; never call hooks inside one — inject the Cratis abstraction. A view model must be constructible in a spec without React.
+4. **Reuse before rewrite.** Check the shared component surface and existing style constants before adding a component or a long class string. Never duplicate a primitive that already exists; prefer a Cratis Components wrapper or an existing shared component over a new one.
+5. **Test behavior, not implementation trivia.** Non-trivial view-model/helper logic gets BDD specs (see [frontend-testing.md](./frontend-testing.md)). Storybook is visual coverage, not a replacement for behavioral specs.
+6. **No `any`, descriptive names, no orphaned code.** `unknown` or a real type, never `any`. After editing a `.tsx`, read past its last closing `};` to confirm no stale `return (...)` block, duplicate body, or unreachable code remains. Comment only a non-obvious *why* — no "what"/provenance comments.
+
+## Smell guards
+
+Stop-and-fix signals during implementation and review:
+
+| Smell | Why it matters | Preferred move |
+|---|---|---|
+| 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 |
+| 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 |
+| Class/style string copied 3× or grown hard to scan | Styling changes become search-and-replace bugs | Extract to a shared style constant or a focused child component |
+| `style={{ ... }}` with static token names | Bypasses theming and review | Move to `className`; keep `style` only for runtime values |
+
+## Definition of done for a frontend change
+
+- [ ] No placeholder/stub copy ships for behavior that is actually implemented.
+- [ ] Each component is single-responsibility; oversized components were split.
+- [ ] State/logic crossing the [react.md](./react.md) thresholds lives in a view model.
+- [ ] Reused existing primitives/wrappers instead of duplicating.
+- [ ] No smell guard above is triggered without a short, intentional reason.
+- [ ] File read past its final `};` — no orphaned code.
+- [ ] New/changed reusable or stateful components have Storybook stories.
+- [ ] New/changed view-model/helper behavior has BDD specs (see [frontend-testing.md](./frontend-testing.md)).
+- [ ] Lint, conditional test, and build pass (the project's frontend gates).
+
+## Review discipline
+
+Treat the frontend gates as seriously as the backend build/test gates — a green lint is the floor, not the goal. For any non-trivial frontend change, run a correctness review (and a reuse/dead-code pass) before completing it. Degradation accrues one "it lints, ship it" at a time.
+
+## See also
+
+- [react.md](./react.md) — MVVM, Cratis Components, queries/commands.
+- [typescript.md](./typescript.md) — style, type discipline.
+- [frontend-testing.md](./frontend-testing.md) — BDD Vitest specs and layout.

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

@@ -0,0 +1,126 @@
+---
+applyTo: "**/for_*/**/*.{ts,tsx}"
+profile: application
+paths:
+  - "**/for_*/**/*.ts"
+  - "**/for_*/**/*.tsx"
+---
+
+# Frontend Testing
+
+Frontend tests are specifications. The `for_/when_/and_` shape is intentionally the same BDD language as the backend Cratis Specifications: one subject, one context, clear setup, small assertions, no framework noise. When in doubt, mirror the structure in the Cratis Components source before inventing a new style.
+
+The quality goal is CUPID code: frontend logic that cannot be tested in isolation is usually doing too much or depending on the wrong abstraction.
+
+## Frameworks
+
+- [Vitest](https://vitest.dev/) for running tests; Mocha-style `describe`/`it`/`beforeEach` structure.
+- [SinonJS](https://sinonjs.org) for mocking/stubbing.
+- [Chai](https://www.chaijs.com) — **always the `.should` fluent interface**, never `expect()`. `result.should.equal(expected)` reads as a sentence and matches the project's prose preference.
+
+## Location and naming
+
+Tests live next to the unit they specify:
+
+```
+<Slice>/
+    <Subject>.ts
+    for_<Subject>/
+        when_<context>/
+            and_<extra_context>.ts
+```
+
+| Shape | Use for |
+|---|---|
+| `for_<Subject>/when_<context>/and_<extra>.ts` | default — view models, helpers with branches, component specs |
+| `for_<Subject>/when_<context>.ts` | tiny pure-helper spec with no useful extra context |
+
+snake_case file/folder names so the path reads as a scenario sentence. Use `should` in `it()` descriptions (spaces, not underscores — TS specs read as human sentences). Don't add `.test.ts`/`.spec.ts` files unless the config changes intentionally.
+
+## BDD structure
+
+```ts
+import { describe, beforeEach, it } from 'vitest';
+import { MyViewModel } from '../../MyViewModel';
+
+describe('when filtering active candidates', () => {
+    let viewModel: MyViewModel;
+
+    beforeEach(() => {
+        viewModel = new MyViewModel();
+        viewModel.setSearch('senior');
+    });
+
+    it('should keep candidates matching the search text', () => {
+        viewModel.filteredItems.should.have.lengthOf(1);
+    });
+});
+```
+
+- `describe('when ...')` names the scenario, not the class.
+- `beforeEach` does the arrange/act once for the context; each `it('should ...')` asserts one observable outcome.
+
+## What to test
+
+Behavior that can regress without TypeScript catching it:
+
+- View-model state transitions, computed getters, filtering/sorting/selection, wizard steps, validation state, command-value derivation.
+- Pure helpers: parsing, formatting, path lookup, grouping, boundary cases.
+- 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.
+
+## View models
+
+Plain TypeScript classes constructible directly in a spec:
+
+- No React hooks; no direct `window`/`localStorage`/`location`/timers/network — inject the Cratis/browser abstraction (see [react.md](./react.md)).
+- Derived values are getters, not `useMemo`.
+- Commands are methods with explicit inputs, not inline closures hidden in JSX.
+
+Pass small typed fakes or `sinon.stub()` instances for dependencies; avoid broad harnesses until a second spec reuses them.
+
+## Component specs
+
+The environment is `node`. For behavior that doesn't need browser events, use server-rendered markup:
+
+```ts
+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),
+}));
+
+describe('when rendered while busy', () => {
+    let html: string;
+    beforeEach(() => { html = renderToStaticMarkup(React.createElement(MyDialog, { isBusy: true })); });
+    it('should disable the confirm button', () => { html.should.include('disabled'); });
+});
+```
+
+- Mock only the external component boundary needed; prefer typed mock props over `any`.
+- Add jsdom / Testing Library only when behavior truly requires DOM events; don't make it the default.
+- Avoid snapshots — they hide behavior and make refactors noisy.
+
+## Stories vs tests
+
+Storybook covers visual states, documentation, and manual verification; Vitest covers behavior. A component with non-trivial logic usually needs both — Storybook for variants/interactive state, Vitest for view-model/helper behavior and narrow rendered-component behavior.
+
+## Async and time
+
+Use `vi.useFakeTimers()` for time-dependent behavior; restore with `vi.useRealTimers()` in `afterEach`. Never depend on the real current date, random values, network, or browser storage. For suspense-query tests, clear the Arc query caches in teardown.
+
+## Gate
+
+Run the project's frontend test gate (e.g. `yarn test`) for frontend changes; it complements lint and build, it does not replace them.
+
+## See also
+
+- [react.md](./react.md) — MVVM, view-model testability, Arc hooks.
+- [frontend-quality.md](./frontend-quality.md) — the engineering bar these specs serve.
+- [specs.md](./specs.md) — the backend BDD language this mirrors.
+- skill: **write-specs-frontend** — the step-by-step workflow that applies these conventions.

package/package/corpus/rules/general.md

@@ -0,0 +1,305 @@
+# Cratis — Project Instructions
+
+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.
+- **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.
+
+Profile-specific rules declare a **`profile:`** in their frontmatter (`application` or `framework`); a rule **without** one is **universal** and applies everywhere — C#/TypeScript style, code quality, specs (`Cratis.Specifications`), documentation, commits/PRs, American English. In this file, everything from **Project Layout** through the **Implementation Workflow** is *application profile* (skip to the Framework profile section if you're contributing to the framework); Philosophy, Authority, Verification, Quality Gates, and the closing sections are universal.
+
+> **Arc is a standalone CQRS framework — not bound to event sourcing.** Even within the application profile, Arc provides model-bound commands/queries, validation, authorization, and full-stack proxy generation, and works **without** Chronicle (Arc.Core does not depend on Chronicle). A `[Command]` `Handle()` does not *have* to append events — it can return a response, return `void`, or work through injected services. The event-sourcing behavior (a returned event gets appended; `EventForEventSourceId`; "never inject `IEventLog`") comes from the **Arc + Chronicle** integration. This application is event-sourced, so the slice guidance assumes event-sourced commands — read the event-centric rules as the *house default for this app*, not universal Arc laws.
+
+The framework is convention-over-configuration. **Idiomatic Cratis is the goal — not custom abstractions over it.** When something is unclear, prefer the Cratis convention; do not invent. The rules and skills under `.cratis/ai/` are the authoritative answer — if your question is not answered there, ask rather than inferring framework behavior from package internals.
+
+## Project Philosophy
+
+Every rule here serves **ease of use**, **productivity**, and **maintainability**:
+
+- **Lovable APIs** — APIs should be pleasant to use: sane defaults, flexible, extensible, overridable. If an API feels awkward, it is wrong.
+- **Easy to do things right, hard to do things wrong** — convention over configuration; artifact discovery by naming/attributes; minimal boilerplate. The framework guides you into the pit of success.
+- **Events are facts** — immutable records of what happened. Past tense, one purpose, never ambiguous. If you reach for a nullable property on an event, you need a second event.
+- **Strongly-typed primitives are the foundation — get them right first.** The most important, load-bearing decisions in every slice are the domain primitives: `ConceptAs<T>` value types and `EventSourceId<T>` identities (never raw `Guid`/`string`/`int` for a domain value); `ConceptValidator<T>` for invariants that travel with a value everywhere it appears; `CommandValidator<T>` for command-level rules; and past-tense, self-describing `[EventType]` names. These are not boilerplate or an afterthought — they are what makes the model type-safe end to end, the rules enforceable in one place, the events trustworthy forever, and the generated proxies meaningful. Treat naming and typing them precisely as the highest-value craftsmanship in the codebase; a slice built on sloppy primitives is wrong no matter how good the rest is.
+- **High cohesion through vertical slices** — everything for a behavior lives together: backend, frontend, specs. Navigate by feature, not by technical layer.
+- **Full-stack type safety** — shared models flow from C# through proxy generation to TypeScript. End-to-end typing without manual synchronization.
+- **Specialization over reuse** — focused, purpose-built read models over one model reused across conflicting scenarios.
+- **Consistency is king** — when in doubt, follow the established pattern.
+
+When these instructions don't cover a situation, apply these values to make the call.
+
+## Three Levels of Authority
+
+Every rule below is one of three kinds — know which, because they carry different weight:
+
+- **Framework contract** — enforced by Arc/Chronicle source, analyzers, or runtime. Violating it breaks the build or behaves wrongly. (e.g. `[Command]` needs a public instance `Handle()`; model-bound queries are static methods on `[ReadModel]`; nullable event properties raise a Chronicle analyzer warning.)
+- **Cratis Application convention** — the house default for maintainability and consistent generated code. The framework does **not** enforce it, but follow it for consistency. (e.g. the slice folder shape, one backend file per small slice, declaration order.)
+- **Product policy** — belongs in a downstream app's own `.cratis/ai/`, not this generic corpus. (e.g. specific roles, locales, design systems.)
+
+Where a rule is convention rather than contract, this file says so. Do not claim "the framework requires this" for a convention.
+
+## Project-Specific Instructions
+
+This corpus is the shared, generic instruction set common to every Cratis
+repository. Individual projects need extra context that does not belong here,
+such as product composition, approved environment names, directions for
+obtaining credentials, and other local conventions ("Product policy" above).
+
+- Read repository-owned documentation as the canonical project-specific context when it
+  exists.
+- Read repository-owned documentation only as the documented legacy fallback when
+  repository-owned documentation does not exist; never merge both contexts.
+- Project context may explain which approved secret mechanism or local setup to
+  use, but it must never contain credential values, tokens, keys, passwords, or
+  other secrets.
+- Project-specific guidance wins when it deliberately narrows shared behavior,
+  but it may not weaken organization security, authorization, or required
+  quality gates.
+
+## Collaboration Default
+
+Default to agentic behavior: inspect local rules, skills, code, tests, and generated patterns; make conservative assumptions supported by that context; implement and verify end to end when feasible. Don't interrupt with questions the repository can answer. Ask when the answer can't be found locally, when reasonable product/domain choices differ meaningfully, when a change is risky, or when the user asked for checkpoints.
+
+## Destructive operations
+
+Before a destructive or bulk external mutation, show the exact targets and
+actions, explain how to recover, and obtain explicit user authorization. Re-read
+the target state immediately before acting and stop if it changed. 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.
+
+## Verification Discipline
+
+A claim is only as good as the signal behind it — a build result, a test run, a lint pass, observed app behavior — not the model's own confidence. Internal reasoning *plans* the work; external signals *confirm* it.
+
+- **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.**
+
+---
+
+# 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).
+
+---
+
+# Framework profile
+
+> You are contributing to a Cratis framework repository (Arc, Chronicle, Fundamentals, Components, …). **The Application-profile sections above do not apply** — there are no vertical slices, model-bound `[Command]`/`[ReadModel]` artifacts, projections/read-models, or MVVM app components here; these are libraries. Follow **[framework.md](./framework.md)** for repo structure, library/API design, source generators, the Chronicle kernel, and the framework quality gates. The universal sections (below, and every `profile: universal` rule) still apply.
+
+---
+
+# Both profiles (universal)
+
+## Definition of Done
+
+- The affected solution/project builds with zero warnings and zero errors.
+- Relevant specs for every affected project pass.
+- For public-facing changes (clients, SDKs, public APIs, developer-facing behavior), documentation is added or updated and its verification passes.
+
+## Where to Look
+
+| For | Location |
+| --- | --- |
+| **Contributing to a Cratis framework repo** (framework profile) | `framework.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 — what a singleton may never hold (tenant, user, request state) | `csharp.md` |
+| React + Arc + Cratis Components + MVVM + dialogs | `react.md`, `components.md`, `dialogs.md` |
+| Frontend engineering quality & testing | `frontend-quality.md`, `frontend-testing.md`, `storybook.md` |
+| Spec patterns — universal `Specification` base (both profiles) | `specs.md`, `specs.csharp.md`, `specs.typescript.md` |
+| 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 |
+| 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` |
+| 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 counts as evidence that something works | `verification-discipline.md` |
+| `next:` / `blocker:` values and when a comment is warranted | `work-records-and-comments.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` |
+| Event modeling / schema migration / calling commands from code / paging / cross-cutting metadata / multi-tenancy | the matching skills |
+| Step-by-step recipes | `.cratis/ai/skills/` |
+
+## Source-of-Truth Discipline
+
+- **Rules define invariants; skills define workflows.** A skill may refine how to apply a rule but must not contradict it. On conflict, follow the stricter invariant and fix the stale artifact.
+- **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.
+
+## General
+
+- **American English** in all code, comments, and docs (initialize, behavior, color, serialize…).
+- Treat warnings as errors; never suppress warning output.
+- Reuse the active terminal for commands; create a new one only when the current one is busy or fails.
+- All files start with the standard license header:
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+```
+
+## 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.