@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/rules/documentation-structure-and-formatting.md

@@ -0,0 +1,148 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Documentation structure and formatting
+
+This is the authoritative rendering contract for product documentation consumed by the Astro Starlight site. For content and teaching voice, see [Writing Cratis Documentation](./writing-cratis-docs.md). For source ownership and the edit loop, see [Editing Cratis Documentation](./editing-cratis-docs.md).
+
+Product `.md` and `.mdx` files are copied through the Documentation repository's `web/scripts/sync-content.mjs`; the converter preserves the extension and rewrites the content before Starlight renders it.
+
+## Frontmatter
+
+```yaml
+---
+title: Append an event
+description: Append a domain event to one event source and inspect the result.
+tableOfContents: false             # optional per-page override
+sidebar:
+  badge: { text: New, variant: tip }
+---
+```
+
+- Product pages should declare `title` and `description`. The title becomes the page H1; the description feeds metadata and AI-facing exports.
+- Preserve existing frontmatter when editing unless the task deliberately changes it. The converter preserves only `title`, `description`, `sidebar`, and `tableOfContents`; it drops DocFX keys and other Starlight keys. Features such as `template`, `hero`, `banner`, `head`, `prev`, `next`, `slug`, and `draft` work only on site-level pages authored directly in the Documentation repository.
+- Product navigation comes from `toc.yml`, not Starlight autogeneration. `sidebar.badge` works, but `sidebar.order`, `sidebar.label`, and `sidebar.hidden` do not control product navigation.
+- A frontmatter-less page falls back to its first H1, but that loses the description and relies on converter inference. Do not add new pages that way.
+
+## Headings
+
+- Do not put an H1 in the body; frontmatter supplies it.
+- The global “On this page” list shows H2 headings only. Organize the page around a short, flat set of `##` sections; use H3/H4 only inside them.
+- Use sentence case and no trailing punctuation.
+- Keep a real H2 when a section needs a stable URL anchor. A card or aside title is presentation, not document structure.
+
+## Files, folders, and navigation
+
+- A navigable product folder normally has `toc.yml` plus one landing page: `<folder>/index.md[x]` or a sibling `<folder>.md[x]`.
+- Never keep both `<folder>.md[x]` and `<folder>/index.md[x]`. A legacy `<folder>.md` sibling makes the sync move the directory index to `/overview/`; other duplicate landing shapes can fail the build. Either outcome can orphan the intended landing page or make compatibility links point back to themselves.
+- A folder with neither an index nor a sibling landing has no page at its bare URL.
+- Product bucket names are product-specific. Read that product's `PRODUCTS[].buckets` entry in `web/scripts/sync-content.mjs`; do not assume generic “Get started / Guides / Understand / Reference” labels.
+- A missing built slug is dropped from the sidebar and counted as a broken toc entry. Keep that count at zero.
+- `toc.yml` entries with external URLs, `../`, or `/api/` are intentionally dropped. A group with one child collapses to the child link. Check the generated sidebar rather than inferring it from YAML alone.
+- Sync slugification lowercases path segments and removes characters outside `[a-z0-9_-]`; for example, `react.mvvm` becomes `reactmvvm`. Verify hand-authored site-absolute URLs against the built route.
+
+## Choose Markdown or MDX
+
+Use the least powerful format that communicates the idea:
+
+- Keep `.md` for headings, prose, links, GFM tables, fenced code, Mermaid/EventModeling diagrams, images, and Starlight aside directives.
+- Use `.mdx` only when the page needs imported Astro components, expressions, props, or named slots.
+- Imports and JSX in `.md` fail silently: the import can render as visible prose and the component as an inert element. Permissive Markdown HTML allowlists can hide this mistake. A page using a component must be `.mdx`.
+- Do not rename a page to `.mdx` merely for a callout or diagram. Renames require checking `toc.yml`, inbound links, generated routes, and AI-facing Markdown output.
+- Do not add raw HTML, inline styling, scripts, or one-off visual components to decorate a product page. Reuse an established component or make an explicit reusable site change in the Documentation repository.
+
+## Callouts and asides
+
+The complete Starlight directive set is `note`, `tip`, `caution`, and `danger`. These work in both `.md` and `.mdx` and support a custom title:
+
+```markdown
+:::caution[Do not use a raw Guid as the event source id]
+Chronicle treats a raw `Guid` as an ordinary response value.
+:::
+```
+
+| Variant | Meaning |
+|---|---|
+| `note` | Neutral context or an important clarification |
+| `tip` | A recommendation or easier path |
+| `caution` | A likely mistake, compatibility trap, or behavior that produces the wrong result |
+| `danger` | Destructive, security-sensitive, or data-loss consequences |
+
+The set is closed. Do not use `warning`, `important`, `info`, or `success`: an unknown container directive silently renders as an unstyled `<div>` rather than failing the build.
+
+Legacy DocFX alerts are converted as follows; prefer titled native directives when editing the surrounding content:
+
+| DocFX | Starlight |
+|---|---|
+| `> [!NOTE]` / `> [!IMPORTANT]` | `:::note` |
+| `> [!TIP]` | `:::tip` |
+| `> [!WARNING]` | `:::caution` |
+| `> [!CAUTION]` | `:::danger` |
+
+In MDX, `<Aside type="tip" title="A specific title">…</Aside>` is available when component composition requires it. Directive asides can also take a Starlight icon attribute, but verify the icon name first; a bad aside icon fails the build.
+
+## Code blocks
+
+- Always tag the language: `csharp`, `tsx`, `typescript`, `bash`, `yaml`, and so on.
+- Expressive Code supports useful metadata such as ``title="Program.cs"`` and line/text markers. Use them to orient the reader or focus a diff, not to decorate every snippet.
+- DocFX-era aliases include `env`, `pdl`, `ebnf`, `pql`, `gitignore`, `flow`, and `screenplay`; use a real language where one exists.
+- Dedent snippets to column zero while preserving their internal indentation.
+- Show both sides of a full-stack contract, but do not automatically hide sequential C#→generated-TypeScript explanations behind tabs. Use `FullStackTabs` only when the snippets are alternatives that remain understandable independently.
+- The converter's DocFX-alert and link rewriting is not fully code-fence-aware. Literal `> [!NOTE]`, Markdown-link targets, or `href="…"` examples can be rewritten; inspect the synced output when documenting those syntaxes.
+
+## Tables, images, links, and diagrams
+
+- Use GFM tables with a separator row and a blank line before the table. `remarkGfm` in the Documentation site's Astro config is load-bearing for `.mdx`; raw pipe text in a rendered page indicates that integration is missing or degraded.
+- Keep images beside the source page, use meaningful alt text, and rely on the site's click-to-zoom behavior.
+- In product source, relative links to files keep their real `.md` or `.mdx` extension. The converter strips either extension for the public route. Directory URLs end in `/`.
+- Site-level MDX uses clean root-relative routes such as `/arc/backend/commands/`. Cross-product links are also root-relative.
+- Link text describes the destination; `here`, `click here`, and `see documentation` are hard lint errors.
+- Use `mermaid` for architecture, sequence, flow, and state diagrams. Use `eventmodeling` for EventModeling diagrams. Both are pre-rendered to responsive SVG at build time.
+
+## MDX component surface
+
+Place imports immediately after frontmatter, with a blank line before the first body content. Import only what the page uses. Starlight exports exactly `Aside`, `Badge`, `Card`, `CardGrid`, `Code`, `FileTree`, `Icon`, `LinkButton`, `LinkCard`, `Steps`, `TabItem`, and `Tabs`:
+
+```mdx
+import { Aside, Steps, TabItem, Tabs } from '@astrojs/starlight/components';
+```
+
+Shared Cratis components are default imports through exact `@components/<Name>.astro` paths; there is no bare `@components` barrel:
+
+```mdx
+import FullStackTabs from '@components/FullStackTabs.astro';
+import Recap from '@components/Recap.astro';
+```
+
+Common shared components include `FullStackTabs`, `OsAwareTabs`, `TopicHero`, `SimpleCard`, `StackDiagram`, `YouWillLearn`, and `Recap`. Inspect the current component and an existing page before using its props or slots; do not infer an API from the component name.
+
+Icon names must come from the installed Starlight set. Use `seti:windows`, not `windows`. Invalid icons in `Icon`, `TabItem`, `SimpleCard`, and `TopicHero` can produce an empty SVG without a build failure, so visual verification is mandatory.
+
+## AI-facing Markdown
+
+The published `.md` mirror behind page actions such as “Copy Markdown” is copied from synchronized Markdown/MDX rather than reconstructed from rendered HTML. Synced frontmatter and converter rewrites are present, but MDX imports and JSX remain visible in that raw Markdown surface. Prefer plain Markdown unless a component creates a real teaching advantage, and inspect the emitted `.md` artifact when changing a page's authoring format. Generated AI indexes can process content separately; do not infer their exact representation from the page action.
+
+## Verification
+
+Run the owning repository's local documentation gate first when it has one. Many product repositories expose:
+
+```bash
+./Documentation/verify-markdown.sh
+```
+
+For full-fidelity rendering, use the sibling Documentation checkout:
+
+```bash
+cd ../Documentation/web
+npm run check
+```
+
+The local gate validates the authored repository in isolation. The full site check builds and syncs every available sibling product, runs site linting and rendered-link checks, and can expose unrelated sibling failures; diagnose those separately rather than silently waiving them. Some optional local tools skip when not installed, so name what actually ran.
+
+A successful build proves syntax, not presentation. For any aside, diagram, tabs, cards, or custom component change, use the `qa-cratis-docs` skill to inspect light and dark screenshots.
+
+End every file with a single trailing newline.

package/package/corpus/rules/documentation.md

@@ -0,0 +1,90 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.{md,mdx}"
+---
+
+# How to write documentation
+
+Documentation exists for one audience: **developers who need to use the framework** — not the team that built it. Write from the reader's perspective. They want to know *what this does*, *why they should care*, and *how to use it* — in that order.
+
+Every page should answer: “If I were a developer encountering this concept for the first time, what would I need to understand to use it correctly?”
+
+The site is built with [Astro Starlight](https://starlight.astro.build/). Documentation lives in the `Documentation/` folder of each product repository as [GitHub Flavored Markdown](https://github.github.com/gfm/); a converter synchronizes product `.md`/`.mdx` into the Starlight site, and all repositories are aggregated into one published site. Readers experience it as a single place — write for that whole, not for one repository in isolation. For the authoritative rendering contract, see [Documentation Structure and Formatting](./documentation-structure-and-formatting.md).
+
+## Every page is exactly one Diátaxis type
+
+We organize documentation with the [Diátaxis framework](https://diataxis.fr/). Before writing, decide which of the four types a page is — and write *only* that type. Mixing types is the most common way docs fail: a tutorial padded with reference detail overwhelms the learner; a how-to interrupted by concept digressions stops being a quick recipe.
+
+| Type | The reader is… | Reads like | Rule |
+|---|---|---|---|
+| **Tutorial** | learning by doing | a guided lesson | Steps that each produce a visible result. Do not explain *why* — just *do this, then this*. The reader must succeed even before they fully understand. |
+| **How-to guide** | solving a specific problem | a recipe | Assume competence. Goal → prerequisites → steps → done. No teaching. |
+| **Reference** | looking something up | a dictionary | Exhaustive and terse. Tables, signatures, attributes, configuration. No narrative. |
+| **Explanation** | trying to understand | a discussion | Concepts, trade-offs, architecture, *why*. No steps. Lean on diagrams. |
+
+Diátaxis governs a page's purpose and voice, not a universal set of sidebar labels. Each product has navigation buckets suited to its domain; read `PRODUCTS[].buckets` in the Documentation site's sync script before placing a new section.
+
+For authoring a single page step by step, use the `write-documentation` skill.
+
+## Onboarding is the most important documentation you write
+
+Most readers decide whether to adopt Cratis in the first ten minutes. Protect that path.
+
+- **One canonical getting-started per product**, not a menu of competing quickstarts. Host variants are how-to guides linked *from* the canonical path — never rival front doors.
+- Drive to a **visible payoff fast** — something running the reader can see. State it up front: “By the end you'll have X running.”
+- **One threaded tutorial per product** builds a single realistic domain across chapters, each adding one concept. Open every chapter with what the reader will build or learn and close with a recap. The reader finishes with a working application, not a pile of snippets.
+- **One cross-product capstone tutorial** builds a real full-stack feature using the relevant Cratis products together. This is the connective tissue between products — keep it current and runnable.
+
+## Connect the products
+
+Readers do not care about repository boundaries — they are building one application.
+
+- The site has **one front door** stating what Cratis is, with a one-sentence definition and a “start here” link for each product.
+- Every product index opens with a **one-sentence definition** and a **“without vs. with” framing** of the problem it removes — lead with the pain, then the relief.
+- **Cross-link at the seams** rather than re-explaining: show how the products meet in the reader's workflow.
+- Maintain a **glossary** of shared terms and link to it instead of redefining terms per page. One term, one concept, everywhere.
+
+## Writing style
+
+The project's voice is **direct, practical, and opinionated**. Write like an experienced colleague explaining something to a capable developer — confident but never condescending.
+
+- **Active voice, present tense, second person.** “You append the event,” not “The event is appended.”
+- **Lead with *why* before *how*.** A reader who understands the reasoning handles edge cases the docs do not cover.
+- **Do not document the obvious.** If the API is self-explanatory, a complete code example is enough.
+- Use headings, lists, tables, and code blocks — dense paragraphs lose readers.
+- **Be honest about trade-offs.** A “when this is the wrong fit” section builds more trust than omitting the limits.
+- Focus on public APIs and behavior — never internal implementation or third-party libraries.
+
+## Diagrams
+
+- Use [Mermaid](https://mermaid-js.github.io/mermaid/#/) for every non-trivial concept — architecture, event and command flow, state transitions, projection and reactor pipelines. A concept page without a diagram is usually incomplete.
+
+## Code examples
+
+- Prefer `record` types for events, commands, and read models — match the codebase.
+- Use argument-free `[EventType]` for new events. A new generation or an explicit legacy identifier is valid only when documenting evolution of an existing stored-event contract.
+- Every example must be **complete and correct** — no pseudo-code, no `// ...` elisions that leave the reader guessing.
+- **Short illustrative snippets** may be purpose-built. **Longer or real samples must be embedded from compiled, tested source** when snippet tooling is available, so they cannot drift as APIs change. Never paste untested code, and never substitute a bare “see the repository” link for showing the code.
+- Where a feature spans products or languages, show both sides when both matter. Keep causal explanations sequential; use tabs only for alternatives.
+
+## Links
+
+- **Link text must describe the destination.** Write `[Event types](...)`, never `[see documentation](...)`, `[here](...)`, or `[click here](...)`. Non-descriptive link text is a defect.
+- Use relative links for internal product-source references. Verify every link resolves — broken links and links to non-existent folders fail review.
+
+## What every product's docs must have
+
+- A front-door **index** with a one-sentence definition and a “start here” link.
+- A **“Why <product>”** explanation page covering the problem it solves and when *not* to use it.
+- A canonical **getting started** with a visible payoff.
+- A **threaded tutorial**.
+- A **concepts/glossary** page and an **architecture diagram**.
+- A **troubleshooting/FAQ** page.
+- An **`llms.txt`** and **`llms-full.txt`** output so AI assistants can ground answers in the docs.
+
+## File rules
+
+- Follow [Documentation Structure and Formatting](./documentation-structure-and-formatting.md) for frontmatter, landing pages, `toc.yml`, Markdown/MDX, links, and rendering.
+- End every Markdown file with a single trailing newline.
+- Run the owning repository's local documentation gate when present; use `cd ../Documentation/web && npm run check` for full-fidelity site verification when the sibling checkout is available.

package/package/corpus/rules/editing-cratis-docs.md

@@ -0,0 +1,69 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Editing Cratis documentation
+
+Cratis documentation is split across product repositories and aggregated by the sibling `Documentation` repository. Find the authored source before editing; synchronized product copies under `Documentation/web/src/content/docs/` are disposable build output.
+
+## Find the source of truth
+
+Common routes map as follows:
+
+| Public route | Authored source |
+|---|---|
+| `/chronicle/**` | `Chronicle/Documentation/**` |
+| `/arc/**` | `Arc/Documentation/**` |
+| `/components/**` | `Components/Documentation/**` |
+| `/chronicle-mcp/**`, `/authproxy/**`, `/cli/**`, `/fundamentals/**`, `/screenplay/**`, `/prologue/**`, `/prompter/**`, and other product routes | The product or family-source repository selected by `PRODUCTS` |
+| `/contributing/**` | The organization `.github` repository (legacy fallback: `GitHubLanding`) |
+| Site-level routes such as `/`, `/why-cratis`, `/cratis-stack`, `/glossary`, `/ai/**`, and `/compare-event-sourcing-*` | `Documentation/web/src/content/docs/**` |
+
+The definitive source map is `PRODUCTS` and its optional `familySources` in `Documentation/web/scripts/sync-content.mjs`. The site prefers sibling checkouts and falls back to configured submodules. Do not hard-code a shorter product list when the script can answer ownership.
+
+Never edit a synchronized subtree under `Documentation/web/src/content/docs/`. Each `PRODUCTS[].key` is regenerated there even when Git state or `.gitignore` makes a particular directory look hand-authored. Site-level files that are not populated from `PRODUCTS` are authored directly in the Documentation repository. Check `PRODUCTS`, source paths, and the site configuration when ownership is unclear.
+
+## Edit and verify
+
+From the owning repository:
+
+1. Edit the authored `.md` or `.mdx` file and preserve its existing frontmatter unless the task deliberately changes it.
+2. Run that repository's local documentation gate when present, commonly `./Documentation/verify-markdown.sh`.
+3. For full rendering, run the site from the sibling checkout:
+
+   ```bash
+   cd ../Documentation/web
+   npm run check
+   ```
+
+4. Preview with `npm run dev` from that same `../Documentation/web` directory and inspect visual changes in light and dark.
+
+The local gate validates authored content without requiring every sibling product. The full site check synchronizes every available product and can expose unrelated sibling or optional-tool failures; diagnose and report those separately. Report which checks actually ran when local prose, Markdown, or external-link tools skip because their executables are absent.
+
+Restart `npm run dev` after a build/check. The build re-sync can degrade a running dev server, producing 500s or missing table rendering. If a change still appears stale, clear `web/.astro` and `web/node_modules/.astro`, restart, and recheck before blaming the source.
+
+## Add, move, rename, or delete a page
+
+- Product navigation comes from its `toc.yml`; site-level navigation comes from `astro.config.mjs`.
+- Product navigation buckets are defined per product in `PRODUCTS[].buckets`. Read the actual names and section lists before changing them.
+- Keep exactly one landing for a route. A sibling `<folder>.md[x]` collides with `<folder>/index.md[x]`; a legacy `.md` collision can move the directory index to `/overview/`, while other duplicate landing shapes can fail the build.
+- Update inbound links and `toc.yml` together. For a published route change, inspect the Documentation site's redirect mechanism rather than assuming a source-file move preserves old URLs.
+- Watch sync output for dropped toc entries and verify the built sidebar. External, `../`, and `/api/` toc targets are intentionally omitted; single-child groups collapse.
+
+## Links
+
+- Product source links to files keep the real `.md` or `.mdx` extension. The converter removes either extension for the public route.
+- Directory links end in `/`.
+- Site-level MDX and cross-product links use clean root-relative public routes such as `/arc/backend/commands/`.
+- Slugification removes punctuation from path segments (`react.mvvm` becomes `reactmvvm`), so verify hand-authored site-absolute paths against the build.
+
+## Content and rendering
+
+- Match the page's Diátaxis type and the tour voice in [Writing Cratis Documentation](./writing-cratis-docs.md).
+- Verify framework APIs against source using [Writing Correct Code Examples](./writing-correct-examples.md).
+- Follow [Documentation Structure and Formatting](./documentation-structure-and-formatting.md) as the single authority for frontmatter, Markdown/MDX boundaries, asides, components, navigation behavior, and gates.
+
+Commit in the repository that owns the authored source. Touch the Documentation repository only when the task deliberately changes site-level content, navigation composition, components, styling, redirects, or build behavior.

package/package/corpus/rules/efcore.md

@@ -0,0 +1,235 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+profile: application
+---
+
+# Entity Framework Core Instructions
+
+> **⚠️ 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
+
+Responsibilities are split across three projects:
+
+| 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 |
+
+**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)
+
+```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>()`.
+
+## Feature Contexts — Not God Contexts
+
+Create one focused DbContext per feature or tightly-related feature group. Never aggregate unrelated entities into a single context.
+
+```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
+
+> **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.
+
+## 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()]);
+```
+
+Configure the database provider using `UseDatabaseFromConnectionString`, which auto-detects PostgreSQL vs SQLite from the connection string:
+
+```csharp
+options.UseDatabaseFromConnectionString(connectionString);
+```
+
+Centralize all DbContext setup in a single `AddApplicationDbContexts` extension method per layer.
+
+## Multiple Database Support
+
+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.
+
+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:
+
+| 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.
+
+```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.
+
+### Applying Migrations
+
+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);
+```
+
+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.
+
+## Auto-Discovery
+
+The Cratis Arc `IImplementationsOf<T>` mechanism discovers DbContext types at runtime:
+
+- `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.

package/package/corpus/rules/efcore.specs.md

@@ -0,0 +1,44 @@
+---
+applyTo: "**/for_*/**/*.cs, **/when_*/**/*.cs"
+paths:
+  - "**/for_*/**/*.cs"
+  - "**/when_*/**/*.cs"
+profile: application
+---
+
+# Entity Framework Core Specs
+
+> **⚠️ 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.
+
+EF Core specs verify database interaction logic — migrations, queries, and error handling. They use SQLite in-memory databases, which are fast, isolated, and disposable. This keeps specs independent of any real database server.
+
+These specs are for code that interacts directly with `DbContext`. For event-sourcing integration specs (testing commands against Chronicle), use the Chronicle integration spec pattern in [specs.scenarios.csharp.md](./specs.scenarios.csharp.md) instead.
+
+## Database Setup
+
+- Use SQLite in-memory database for all `DbContext` specs — it's fast and each spec gets a clean database.
+- Configure and dispose the in-memory database properly to avoid state leakage between tests. Each spec run should start with a fresh schema.
+
+## Mocking DbContext
+
+- `SaveChanges()` and `SaveChangesAsync()` are virtual — mock with NSubstitute.
+- `DbSet<T>` methods are virtual — mock as needed.
+- Pass options when substituting: `Substitute.For<YourDbContext>(options)`.
+
+```csharp
+var options = new DbContextOptionsBuilder<YourDbContext>()
+    .UseSqlite("DataSource=:memory:")
+    .Options;
+
+var context = Substitute.For<YourDbContext>(options);
+```
+
+## Simulating Failures
+
+Mock `SaveChanges` / `SaveChangesAsync` to throw exceptions for testing error handling and recovery:
+
+```csharp
+context.SaveChangesAsync(Arg.Any<CancellationToken>())
+    .Throws(new DbUpdateException("Simulated failure"));
+```

package/package/corpus/rules/exit-codes-and-wrappers.md

@@ -0,0 +1,33 @@
+---
+applyTo: "**/*"
+---
+
+# Exit codes and wrappers
+
+An exit code is a verdict, and a wrapper that loses it turns a red run green. Every line
+is tagged **[contract]** (binding) or **[convention]** (the house default) per the Three
+Levels of Authority in [`general.md`](./general.md).
+
+- **[contract] Three codes, three meanings.** `0` ran clean, `1` found defects, `2` could
+  not run. A tool that cannot distinguish "found nothing" from "never looked" has no
+  usable verdict.
+- **[contract] `2` is never reported as a pass.** Could-not-run is an unknown, and
+  unknown is not pass; see [`verification-discipline.md`](./verification-discipline.md).
+- **[contract] A wrapper's own success is not the child's verdict.** A script that runs a
+  checker and then exits `0` because *the script* finished has thrown the result away.
+  Propagate the child's status.
+- **[contract] Pipelines and loops lose exit codes by default.** Use `set -euo pipefail`,
+  check `PIPESTATUS` where a pipeline's left side matters, and accumulate a failure flag
+  inside a loop rather than relying on the last iteration.
+- **[contract] Green prints counts.** A clean run says how many subjects it examined. A
+  bare "OK" cannot be distinguished from a run over an empty set; see
+  [`guards-and-fuses.md`](./guards-and-fuses.md).
+- **[contract] `--self-test` plants defects.** A checker ships a self-test that seeds
+  known violations and fails if it does not find every one of them. That is the only way
+  to know the checker still detects anything.
+- **[contract] Never swallow output to make a gate quiet.** Redirecting stderr, adding
+  `|| true`, or catching and ignoring is a decision to stop checking. Say so out loud or
+  do not do it.
+- **[convention] Name the subject in the failure line.** The path, the id, the rule — a
+  failure a reader cannot locate costs more than it saves.
+- **[convention] Keep the wrapper thin.** Logic in a wrapper is logic no test covers.