@cratis/pi 0.0.1 → 2.0.1

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

@@ -0,0 +1,70 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Writing Cratis documentation — tour voice and Starlight authoring
+
+The Cratis docs must **take the reader on a tour, like a teacher** — the way [Marten](https://martendb.io), [Wolverine](https://wolverinefx.net), and [aspire.dev](https://aspire.dev) docs do — **not** state facts like a reference dump. The differentiator is pedagogical structure, not decoration. Match it.
+
+## The bar
+
+- **Pain → relief.** Open by naming the friction the reader feels, then reveal the feature as the relief.
+- **Why before how.** A reader who understands the reasoning handles edge cases the docs do not cover.
+- **Active voice, present tense, second person.** “You append the event,” not “the event is appended.”
+- **Be honest about limits.** A “when this is the wrong fit” section builds more trust than omitting the limits.
+
+## One page equals one Diátaxis type
+
+| Type | Reader is… | Reads like |
+|---|---|---|
+| **Tutorial** | learning by doing | a guided lesson — each step produces a visible result |
+| **How-to** | solving a specific problem | a recipe — assume competence, no teaching |
+| **Explanation** | trying to understand | a discussion — concepts, trade-offs, *why*, a diagram |
+| **Reference** | looking something up | a dictionary — exhaustive, terse, tables/signatures |
+
+Never mix types. A tutorial padded with reference detail overwhelms; a how-to interrupted by concept digressions stops being a recipe. Diátaxis type does not imply a universal navigation bucket; bucket names are product-specific.
+
+## The tour-voice checklist
+
+Apply this checklist to tutorials, getting-started pages, and explanations:
+
+1. **Open with a concrete scenario**, not a definition of the tool.
+2. **Name the friction first**, then the feature as its relief.
+3. **Use chronological verbs** such as define → append → project → query.
+4. **After every code block, explain the invisible** — what happens under the hood and why it matters.
+5. **Recap before pivoting** to the next concept.
+6. **Anticipate the reader's doubt** with a meaningful aside.
+7. **Show the result** — output, a resulting model, or another visible success signal.
+8. **Organize by workflow**, not alphabetically.
+9. **End each substantial section with the natural next step** when one exists.
+
+Read a current, well-reviewed tutorial in the product or a closely related product before writing; do not assume one product's domain vocabulary fits every other product.
+
+## Use presentation to support the tour
+
+Choose the simplest authoring surface that preserves the reading flow. Use steps for real procedures, tabs for genuine alternatives, asides for meaningful context or risk, and diagrams for non-trivial flows. Do not turn sequential cause-and-effect examples into tabs merely because they use different languages; hiding one side can make the explanation harder to follow.
+
+Full-stack type safety is a differentiator, so show both the backend contract and generated frontend shape when both matter. Use `FullStackTabs` only when each pane remains understandable independently.
+
+The raw Markdown mirror behind page actions such as “Copy Markdown” comes from synchronized Markdown/MDX rather than rendered HTML. Converter rewrites and normalized frontmatter are present, but component imports and JSX remain visible. Prefer plain Markdown unless a component adds real teaching value.
+
+The exact Markdown/MDX boundary, aside semantics, component contracts, import paths, and rendering checks live in [Documentation Structure and Formatting](./documentation-structure-and-formatting.md). Do not duplicate or infer that rendering API here.
+
+## Two voices, connected products
+
+- **Two voices per area:** the toured/educational layer and the terse, exhaustive reference. Narrative pages link *down* into the reference; the reference stays a dictionary.
+- **Connect at the seams** rather than re-explaining. Show how neighboring products meet in the user's workflow and link to the glossary for shared terms.
+- **Coming-from-X bridges** map new concepts to what the reader already knows without organizing the whole product around a competitor.
+
+## Before you call a page done
+
+- Verify every framework API in a code example against real source — see [Writing Correct Code Examples](./writing-correct-examples.md). Readers paste snippets verbatim.
+- The owning repository's local documentation gate passes when one exists; when available, the sibling Documentation site's full check has zero hard lint errors and zero broken rendered links attributable to the change.
+- For a visual page, screenshot it in light **and** dark — see the `qa-cratis-docs` skill.
+
+Study the **aspire.dev** docs for strong Starlight information architecture and tour writing.
+
+The edit/sync/verify loop and source ownership live in [Editing Cratis Documentation](./editing-cratis-docs.md).

package/package/corpus/skills/cratis-engineering-csharp-conventions/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-engineering-csharp-conventions/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: cratis-engineering-csharp-conventions
+description: Apply the Cratis C# house conventions when writing or reviewing C# in a Cratis repository - formatting, naming, records and primary constructors, nullable handling, XML documentation, custom exceptions, structured logging, dependency injection, and service lifetimes. Use for any "how should this be written" C# style question; defer product API decisions and specification authoring to their focused workflows.
+license: LICENSE
+---
+
+# Cratis C# engineering conventions
+
+These are the house conventions Cratis maintainers apply across every
+repository. They are **conventions**, not framework contracts: nothing here is
+enforced by an analyzer unless this skill says so. Follow them for consistency;
+do not claim the framework requires them.
+
+## Route near misses
+
+- The question is what a Cratis product API *does*: resolve it against the
+  owning product repository, not against this style guide.
+- The subject is a specification file: the specification conventions own the
+  `Establish`/`Because`/`should_` pattern and the `for_`/`when_` hierarchy.
+- The subject is TypeScript or React: this skill covers C# only.
+- The subject is repository structure or documentation: those are separate
+  workflows.
+
+## Quick reference
+
+- Use current C# language features — records, primary constructors, pattern
+  matching, collection expressions.
+- `var` over an explicit type; the right-hand side already names the type.
+- File-scoped namespace declarations.
+- `using` directives alphabetically sorted, single-line, unused ones removed.
+- No regions. A file that needs them needs refactoring instead.
+- No technical postfixes on type names: no `Impl`, `Service`, `Manager`,
+  `Handler`, `Base`, `Async`.
+- No `Exception` suffix on exception types — `AuthorNotFound`, not
+  `AuthorNotFoundException`.
+- Never throw a built-in exception type. Always define a domain exception.
+- `record` for events, commands, read models, concepts, and DTOs.
+- `is null` and `is not null` — never `== null` or `!= null`.
+- Blank line before the opening `{` of every block.
+- A final `return` sits on its own line.
+- Private fields are `_camelCase`; interfaces take the `I` prefix.
+- American English everywhere — initialize, behavior, color, serialize.
+- Every file starts with the repository license header.
+
+## Formatting
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace <RootNamespace>.<Feature>;
+
+using <Namespace>.<First>;
+using <Namespace>.<Second>;
+
+// Blank line before the opening brace of every block
+if (<condition>)
+{
+    <statement>;
+}
+
+// Expression-bodied form for simple members
+public string <PropertyName> => $"{<First>} {<Second>}";
+
+// The final return stands alone
+public <ReturnType> <MethodName>()
+{
+    var result = <expression>;
+
+    return result;
+}
+```
+
+## Naming
+
+| Artifact | Convention | Example |
+| --- | --- | --- |
+| Type, method, public member | PascalCase | `RegisterAuthor`, `AuthorId` |
+| Private field | `_camelCase` | `_eventLog` |
+| Local variable | camelCase | `authorId` |
+| Interface | `I` prefix | `IEventLog` |
+| Exception type | No `Exception` suffix | `AuthorNotFound` |
+| Feature folder | Pluralized domain noun | `Authors/` |
+| Concept file | The concept name | `AuthorId.cs` |
+
+Avoid abbreviations unless they are universally known (`Id`, `Xml`, `Json`,
+`Url`). Never add a prefix or postfix that names a technical role —
+`Controller`, `ViewModel`, `Handler`, `Manager`, `Factory`, `Base`. Name after
+the domain, not the pattern.
+
+## Where the detail lives
+
+| Topic | Reference |
+| --- | --- |
+| Records, primary constructors, `var`, collections, nullable, async, pattern matching, XML documentation | [code-style.md](references/code-style.md) |
+| Custom exceptions, structured logging, dependency injection, service lifetimes, implementation discovery | [exceptions-logging-and-di.md](references/exceptions-logging-and-di.md) |
+| CUPID, cohesion over layers, ubiquitous language, immutability | [domain-philosophy.md](references/domain-philosophy.md) |
+
+Read the reference that covers the decision at hand rather than all three.
+
+## The two rules most often got wrong
+
+**`[Singleton]` is a narrow choice, not the default.** A singleton may not
+depend on anything that belongs to a tenant, a user, or a request. Capturing a
+scoped collaborator does not throw — it silently binds to the root scope's
+default namespace forever and returns empty results. See
+[exceptions-logging-and-di.md](references/exceptions-logging-and-di.md).
+
+**Use `IInstancesOf<T>`, never `IEnumerable<T>`, to enumerate implementations of
+an abstraction.** `IEnumerable<T>` only works when every implementation is
+hand-registered, which defeats convention-based discovery.
+
+## Verify
+
+- Every file carries the repository license header and a file-scoped namespace.
+- `using` directives are sorted, single-line, and free of unused entries.
+- No regions, no technical postfixes, no `Exception` suffix.
+- Every thrown exception is a domain type deriving from `Exception` with a
+  meaningful message and an XML `<exception>` or `<summary>` doc starting with
+  "The exception that is thrown when".
+- No `catch` block is empty or silently swallowing.
+- Null checks use `is null` / `is not null`, and no defensive check contradicts a
+  non-nullable annotation.
+- Every public type, method, property, and operator carries multiline XML
+  documentation with `<param>` and `<returns>` where applicable.
+- No `[Singleton]` holds tenant-, user-, or request-bound state.
+- No `services.Add*<TInterface, TImplementation>()` registers a type that exists
+  to be discovered by convention.
+- Text is American English.
+- The solution builds with zero warnings and zero errors, and the affected
+  specifications pass.

package/package/corpus/skills/cratis-engineering-csharp-conventions/references/code-style.md

@@ -0,0 +1,187 @@
+# C# code style
+
+## Records
+
+Use `record` for every immutable data structure — events, commands, read
+models, concepts, DTOs. Records supply value equality, immutability, and concise
+syntax. A `record class` with `init`-only properties is equivalent when the type
+also needs methods.
+
+```csharp
+public record <EventName>(<ConceptType> <PropertyName>);
+
+public record <ModelName>(<IdentityType> Id, <ConceptType> <PropertyName>);
+```
+
+## Primary constructors
+
+Use primary constructors for all types. They remove the field-plus-constructor
+ceremony.
+
+```csharp
+// Preferred
+public class <ClassName>(<CollaboratorType> <collaborator>)
+{
+    public async Task <MethodName>(<ArgumentType> <argument>) =>
+        await <collaborator>.<Method>(<argument>);
+}
+```
+
+When a type genuinely needs field initialization logic and cannot use a primary
+constructor, declare private fields with the `_camelCase` prefix.
+
+## `var`
+
+Always use `var` for a local variable. The right-hand side already names the
+type.
+
+```csharp
+var <identifier> = <Factory>.New();
+var <items> = <source>.Where(<predicate>).ToList();
+```
+
+## Expression-bodied members
+
+Use expression-bodied form for simple members.
+
+```csharp
+public string <PropertyName> => $"{<First>} {<Second>}";
+public void <MethodName>(string <argument>) => <collaborator>.<Method>(<argument>);
+```
+
+## Collections
+
+Return read-only sequence types from public APIs. Never expose a mutable
+collection type — a caller could mutate state its owner is responsible for.
+
+```csharp
+// Preferred
+public IEnumerable<<ItemType>> <MethodName>() => <source>.ToList();
+public IReadOnlyDictionary<<KeyType>, <ItemType>> <MethodName>() => <source>;
+
+// Avoid on a public API
+public List<<ItemType>> <MethodName>() => <source>;
+public Dictionary<<KeyType>, <ItemType>> <MethodName>() => <source>;
+```
+
+## Nullable reference types
+
+Embrace the type system — it is the first defense against null bugs. When an
+annotation says a value cannot be null, trust it.
+
+```csharp
+// Use is null / is not null
+if (<value> is null) throw new <DomainException>();
+if (<value> is not null) <statement>;
+
+// Do not add a defensive check the annotation already guarantees
+public void <MethodName>(<NonNullableType> <argument>)
+{
+    <statement>;
+}
+
+// Add ! only where the compiler cannot see what you can prove
+var <identifier> = <source>.FirstOrDefault(<predicate>)!;
+```
+
+Never write `== null` or `!= null`.
+
+## Async
+
+- Use `async`/`await`; return `Task` or `Task<T>`.
+- Do not suffix a method with `Async` unless the suffix disambiguates an
+  overload.
+- Never use `.Result` or `.Wait()`.
+
+```csharp
+public async Task <MethodName>(<ArgumentType> <argument>) =>
+    await <collaborator>.<Method>(<argument>);
+
+public async Task<<ResultType>?> <FindMethod>(<IdentityType> id) => <expression>;
+```
+
+## Immutability
+
+Prefer immutable designs. Produce a modified copy with a `with` expression
+rather than mutating in place.
+
+```csharp
+var updated = <existing> with { <PropertyName> = <newValue> };
+```
+
+The owner of state is responsible for its mutations. Do not return a mutable
+object a caller could change behind the owner's back.
+
+## Pattern matching
+
+Use pattern matching and switch expressions wherever they read better than a
+branch chain.
+
+```csharp
+if (<result> is <ResultType>.Success success)
+    return success.Value;
+
+var <identifier> = <value> switch
+{
+    <EnumType>.<Member> => <expression>,
+    <EnumType>.<OtherMember> => <expression>,
+    _ => <fallback>
+};
+```
+
+## String interpolation
+
+```csharp
+// Preferred
+var message = $"<text> '{<value>}' <text>";
+
+// Avoid
+var message = string.Format("<text> '{0}' <text>", <value>);
+var message = "<text> '" + <value> + "' <text>";
+```
+
+## Interface bodies
+
+Omit the body of a member-less interface.
+
+```csharp
+// Preferred
+public interface <IMarkerName>;
+
+// Avoid
+public interface <IMarkerName> { }
+```
+
+## XML documentation
+
+XML documentation is a public API's first impression. Every public type, method,
+property, and operator carries it.
+
+- `<summary>` is **always multiline** — opening and closing tags on their own
+  lines. Never cram it onto one line.
+- Every method or operator with parameters includes a `<param name="…">` for
+  each one.
+- Every non-void method or operator includes `<returns>`.
+- Every method that throws documents it with `<exception cref="…">`.
+- Cross-reference with `<see cref="…"/>` and `<paramref name="…"/>`.
+- Keep summaries concise. Document only where it adds understanding beyond the
+  name.
+
+```csharp
+/// <summary>
+/// Represents <description>.
+/// </summary>
+/// <param name="<parameterName>">The <see cref="<ParameterType>"/> to <purpose>.</param>
+public class <ClassName>(<ParameterType> <parameterName>) : <IInterfaceName>
+{
+    /// <summary>
+    /// <Verb> the <subject>.
+    /// </summary>
+    /// <param name="<argumentName>">The <see cref="<ArgumentType>"/> to <purpose>.</param>
+    /// <returns>A <see cref="<ReturnType>"/> representing <description>.</returns>
+    public async Task<<ReturnType>> <MethodName>(<ArgumentType> <argumentName>)
+    {
+        <statement>;
+    }
+}
+```

package/package/corpus/skills/cratis-engineering-csharp-conventions/references/domain-philosophy.md

@@ -0,0 +1,91 @@
+# Domain philosophy
+
+## CUPID characteristics
+
+Cratis favors the CUPID characteristics over a strict SOLID reading:
+
+| Letter | Characteristic | What it means |
+| --- | --- | --- |
+| **C** | Composable | Parts play nicely together with minimal coupling and can be assembled freely |
+| **U** | Unix philosophy | Do one thing well — focused, single-purpose components |
+| **P** | Predictable | Deterministic behavior, consistent output, no surprises |
+| **I** | Idiomatic | Code feels natural for the language and its ecosystem |
+| **D** | Domain-based | Domain vocabulary and structure, not technical vocabulary |
+
+## Cohesion over layers
+
+Do not split code by technical role.
+
+```
+# Avoid — layered by technical role
+Models/
+  <Model>.cs
+Controllers/
+  <Name>Controller.cs
+Services/
+  <Name>Service.cs
+Events/
+  <Name>Event.cs
+```
+
+Group by feature instead, so everything that changes together lives together.
+Feature folders sit directly under the source root; there is no `Features/`
+wrapper.
+
+```
+# Preferred — cohesive by feature
+<Feature>/
+  <Behavior>/
+    <Behavior>.cs      ← the backend artifacts for this behavior
+    <Behavior>.tsx     ← its component
+  <OtherBehavior>/
+    <OtherBehavior>.cs
+    <OtherBehavior>.tsx
+```
+
+Frontend and backend concerns naturally separate into different projects, but
+each project keeps the cohesive feature structure inside it.
+
+## Ubiquitous language
+
+Name after the domain concept, not the technical pattern.
+
+| Domain-named | Tech-named |
+| --- | --- |
+| `Authors` | `AuthorController`, `AuthorManager` |
+| `Registration` | `RegisterAuthorHandler`, `RegisterAuthorCommand` |
+| `AuthorNotFound` | `AuthorNotFoundException`, `NotFoundException` |
+| `AuthorId` | a raw `Guid authorId` |
+| `Listing` | `GetAllAuthorsQuery` |
+
+## Pluralization
+
+Features are groupings, so pluralize them consistently across folder, route, and
+schema: `Authors/`, `/api/Authors/{authorId}`, an `Authors` schema.
+
+## Twelve-factor operability
+
+Systems follow the twelve-factor guidance for scalability, maintainability, and
+operability:
+
+- Configuration comes from the environment, never hardcoded.
+- Processes are stateless.
+- Logs are treated as event streams.
+- Setup is declarative so an environment can be replicated.
+
+## Frictionless dependencies
+
+Healthy dependencies mean fast, independent releases. If two components must
+have their releases coordinated, that is unhealthy coupling — address it through
+events, an interface, or package versioning rather than accepting the lockstep.
+
+## Immutability and side effects
+
+Favor immutable designs to reduce side effects:
+
+- Records with `init`-only properties.
+- Return a new instance rather than mutating an existing one.
+- Expose `IEnumerable<T>` and `IReadOnlyDictionary<TKey, TValue>` from public
+  APIs, never a mutable collection.
+- The owner of state is responsible for its mutations. Do not let a consumer
+  mutate internal state.