@cratis/pi 0.0.1 → 2.0.1

package/package/corpus/rules/specs.md

@@ -0,0 +1,132 @@
+---
+applyTo: "**/for_*/**/*.*, **/when_*/**/*.*"
+paths:
+  - "**/for_*/**/*.*"
+  - "**/when_*/**/*.*"
+---
+
+# How to Write Specs
+
+We call automated tests **specs** (specifications), not tests. This is deliberate — specs are executable documentation that describe what the system *does*, written in the language of the domain. A new developer should be able to read the spec folder structure like a table of contents and understand the system's behavior without opening a single source file.
+
+This philosophy comes from Specification by Example and BDD (Behavior Driven Development). The goal is human-readable, navigable specifications that double as a living contract.
+
+## Core Philosophy
+
+- **Specify behaviors, not implementations.** A spec should verify what a method *promises from its signature* — its contract with callers. If the implementation changes but the contract holds, specs should still pass. When they don't, the spec was testing the wrong thing.
+- **One behavior, one spec.** Every public method that performs an action gets its own `when_` folder or file. Never bundle multiple behaviors into one spec — it obscures what broke and why.
+- **Specs are documentation first.** The folder tree, class names, and `should_` assertions form a specification anyone can read. Optimize for readability over DRY. A little repetition in setup is fine if it makes the spec self-contained and clear.
+- **Do not test logging** — it is too fragile and provides no value. Don't test simple delegation or trivial getters either. The cost of maintaining these specs exceeds the value they provide.
+
+## Folder & File Structure
+
+Specs mirror the source structure and read like a sentence when you trace the path: `for_Changeset / when_adding_changes / and_there_are_differences`. This is not accidental — the folder hierarchy *is* the specification. Every level adds context:
+
+```
+for_<TypeUnderTest>/
+├── given/
+│   ├── all_dependencies              ← common DI/mock setup
+│   └── a_<descriptive_name>          ← reusable context
+├── when_<behavior>/                  ← folder for behaviors with multiple outcomes
+│   ├── given/                        ← behavior-specific context (optional)
+│   │   └── a_<specific_setup>
+│   ├── and_<condition>.cs            ← spec file for one outcome
+│   ├── and_<condition>/              ← OR a sub-folder when that condition itself has multiple outcomes
+│   │   ├── with_<data_state>.cs
+│   │   └── without_<requirement>.cs
+│   ├── with_<data_state>.cs
+│   └── without_<requirement>.cs
+└── when_<simple_behavior>.cs         ← single file for single-outcome behaviors
+```
+
+The `and_`, `with_`, `without_`, `having_`, `given_` prepositions work **both** as file names and as folder names. Use a folder when there are multiple outcomes under that condition; use a file when there is only one.
+
+**Naming conventions — read them as English sentences:**
+| Element | Pattern | Reads as... |
+|---|---|---|
+| Unit folder | `for_<ClassName>` | "For the Changeset..." |
+| Behavior folder | `when_<action>` | "...when adding changes..." |
+| Condition folder or spec file | Descriptive preposition | "...and there are differences" |
+| Assertion | `should <expected result>` | "...it should return true" |
+
+**Allowed prepositions for spec file/class names (and sub-folder names):**
+- `and_*` — additional conditions or compound scenarios
+- `with_*` / `without_*` — specific data or state present/absent
+- `having_*` — possession or state-based conditions
+- `given_*` — precondition scenarios
+
+**Critical naming rule — never embed `when` in a spec file or folder name:**
+`when` belongs **only** in `when_<behavior>` folder names. A spec file, spec class, or non-`when_` folder must **never** contain the word `when` anywhere in it. If the name starts with a preposition (`with_`, `and_`, etc.) but also contains `_when_` somewhere in the middle (e.g. `with_a_registered_migration_when_appending_a_generation_1_event`), you have two "whens" in the sentence — which is always wrong.
+
+The fix is to fold the context into the `when_` folder name itself, then use preposition files/folders for the outcomes:
+
+```
+# ❌ Wrong — double when in the sentence path
+when_appending_event_with_migrations/
+└── with_a_registered_migration_when_appending_a_generation_1_event.cs
+
+# ❌ Still wrong — unnecessary extra level when a single flat file suffices
+when_appending_event_with_migrations/
+└── and_event_is_generation_1/
+    └── with_a_registered_migration.cs
+
+# ✅ Correct — context baked into the when_ folder; outcomes are flat files
+when_appending_event_with_registered_migration/
+├── and_event_is_generation_1.cs
+├── and_event_is_generation_2.cs
+└── and_event_has_default_value.cs
+```
+
+A sub-folder under `when_` is only needed when that condition has its **own** multiple outcomes that warrant further breakdown. If there is only one outcome per condition, use a flat file. This applies to **all languages** (C#, TypeScript, etc.).
+
+## What to Specify
+
+The goal is to cover *decisions and transformations* — code where bugs hide. Simple plumbing that the compiler already validates is noise.
+
+**Write specs for:**
+- Public methods that perform actions (behaviors)
+- Methods with branching logic or business rules
+- Methods that coordinate between dependencies
+
+**Do NOT write specs for:**
+- Simple auto-properties (`public string Name { get; set; }`)
+- Properties returning constructor parameters (`public Key Key => key;`)
+- Simple delegation (`public IEnumerable<Property> Properties => mapper.Properties;`)
+- Trivial null checks or basic validation without complex logic
+- Getters returning injected dependencies
+
+**Avoid file names starting with:** `when_getting_*`, `when_returning_*` — if a spec name starts with "getting" or "returning", it's probably testing a simple getter, which is not worth specifying.
+
+## Multiple Outcomes
+
+Each distinct outcome deserves its own spec file. This keeps specs small, focused, and independently verifiable. When a spec fails, you immediately know *which* outcome broke — no debugging through a multi-assertion file.
+
+- When a behavior has multiple outcomes, create a `when_<behavior>/` folder with separate files for each outcome.
+- For simple behaviors with a single outcome, use a single file: `when_<behavior>`.
+- Never write a single file that tests an entire class.
+
+## Reusable Context
+
+Contexts capture the "given" part of a specification — the world as it exists before the action under test. They prevent duplicating setup across specs while keeping each spec readable.
+
+- Place in `given/` folder within the unit folder.
+- Name with `a_` or `an_` prefix (e.g. `an_observer`, `a_command_pipeline`). This reads naturally: "given an observer, when handling..."
+- More specific contexts can use descriptive names (e.g. `two_queries`, `existing_query`).
+- Context properties must be accessible to the specs that use them — see language-specific instructions for the exact access modifiers and naming conventions.
+- Use the setup phase for context initialization — **never** put the action under test in a reusable context. The action under test belongs only in the concrete spec.
+- Contexts can build on each other in layers: `all_dependencies → a_reactor_handler → when_handling`.
+- Consider creating `all_dependencies` as a root context that mocks all common dependencies. This avoids duplicating mock creation across unrelated specs.
+
+## Formatting
+
+- Keep assertions concise — prefer single-line assertions where the logic is readable.
+- Don't add blank lines between related assertions for the same behavior.
+
+## Language-specific guides
+
+This file is the shared base. For the concrete patterns:
+
+- [specs.csharp.md](./specs.csharp.md) — C#: the universal `Cratis.Specifications` base + NSubstitute (both profiles; this is what framework/library specs use).
+- [specs.scenarios.csharp.md](./specs.scenarios.csharp.md) — C# **application** profile: the in-process scenario family (`CommandScenario`, `EventScenario`, `ReadModelScenario`, `ReactorScenario`) + out-of-process Chronicle integration.
+- [specs.typescript.md](./specs.typescript.md) — TypeScript framework-package specs (`given()` helper).
+- [frontend-testing.md](./frontend-testing.md) — application frontend specs (view models, React components).

package/package/corpus/rules/specs.scenarios.csharp.md

@@ -0,0 +1,172 @@
+---
+applyTo: "**/for_*/**/*.cs, **/when_*/**/*.cs"
+paths:
+  - "**/for_*/**/*.cs"
+  - "**/when_*/**/*.cs"
+profile: application
+---
+
+# Application Specs — the in-process scenario family
+
+> **Application profile.** This file covers spec-writing for **event-sourced Cratis applications** — exercising commands, projections, reducers, reactors, and constraints with the in-process scenario family. It builds on the universal [specs.csharp.md](./specs.csharp.md) (the `Specification` base + NSubstitute). **Framework / library** specs predominantly use that plain base instead; a framework repo reaches for a scenario helper here only when testing the very engine it provides — Arc tests its command pipeline with `CommandScenario`, Chronicle tests its event/projection/reactor engine with `EventScenario`/`ReadModelScenario`/`ReactorScenario`. That is the minority case, not the general framework testing mode.
+
+Specs are **mandatory for every slice type**, including reactors.
+
+## Lead with the in-process scenario family
+
+For Cratis application behavior, prefer the four in-process scenario helpers over full out-of-process Chronicle host specs. They target different concerns and are additive.
+
+| Tool | Tests | Use when |
+|---|---|---|
+| `Specification` (unit) | an isolated class with mocked collaborators | pure function / injected services to mock |
+| `CommandScenario<TCommand>` | the real Arc command pipeline — authorization + validators + `Provide()` + `Handle()` + appended events | **default for State Change slices** |
+| `EventScenario` | Chronicle-level append semantics, no command pipeline | constraint violations, raw stream sequencing/concurrency |
+| `ReadModelScenario<TReadModel>` | projection/reducer state from a sequence of events (auto-detects model-bound / fluent / reducer) | **default for State View slices** |
+| `ReactorScenario<TReactor>` | reactor handler invocation + side effects via mocked services | Automation / Translation slices |
+
+> **Out-of-process Chronicle integration specs are an advanced case** — reserve them for host wiring, real infrastructure, serialization/transport, or end-to-end boundaries the scenario helpers can't exercise. They are not the default vertical-slice test shape.
+
+**Every spec file is wrapped in `#if DEBUG … #endif`** so spec code ships only in Debug (the Debug build gate validates it and also regenerates proxies).
+
+### `CommandScenario<TCommand>` — State Change default
+
+Runs authorization, validators, `Provide()` (when present), and `Handle()` in-process, and exposes the appended events.
+
+```csharp
+#if DEBUG
+namespace MyApp.Authors.Registration.when_registering_an_author;
+
+public class and_all_information_is_valid : Specification
+{
+    readonly CommandScenario<RegisterAuthor> _scenario = new();
+    readonly AuthorId _id = AuthorId.New();
+    CommandResult _result;
+
+    async Task Because() => _result = await _scenario.Execute(new RegisterAuthor(_id, "Jane Austen"));
+
+    [Fact] void should_succeed() => _result.ShouldBeSuccessful();
+    [Fact] async Task should_have_appended_registered_event() =>
+        await _scenario.ShouldHaveAppendedEvent<RegisterAuthor, AuthorRegistered>(_id, e => e.Name == "Jane Austen");
+}
+#endif
+```
+
+- `CommandScenario<TCommand>` exposes `Services` (an `IServiceCollection`), `Context`, `Execute(command)`, and `Validate(command)` — and nothing else; everything else is configured through `Services` and asserted with extension methods.
+- **Event assertions are extension methods on the scenario** (from the Chronicle testing package), keyed by **command + event** type: `await _scenario.ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId)` or the `(eventSourceId, Func<TEvent,bool> predicate)` overload; plus `await _scenario.ShouldHaveTailSequenceNumber<TCommand>(...)`. They return `Task`, so the fact is `async Task`.
+- **`CommandResult` assertions** (Arc extensions): `ShouldBeSuccessful()`, `ShouldNotBeSuccessful()`, `ShouldBeValid()`, `ShouldHaveValidationErrors()`, `ShouldHaveValidationErrorFor(message)`, `ShouldBeAuthorized()`, `ShouldNotBeAuthorized()`, `ShouldHaveExceptions()`/`ShouldNotHaveExceptions()`.
+- **Seed prior state through `_scenario.Services`** — there is no `Given`/`Events` on `CommandScenario`. To populate the DCB read models the validator/`Provide()`/`Handle()` inject, substitute `IReadModels` and register it (`_scenario.Services.Replace(new ServiceDescriptor(typeof(IReadModels), mock))`, mocking `GetInstanceById(...)`) or register projections with `_scenario.Services.AddReadModels(...)`.
+- **Validator/`Provide()` dependencies:** register them in `_scenario.Services`; Arc testing discovers the concrete validator automatically. When several specs need different injected validator states, test rejected variants by instantiating the validator directly (per-scenario state can be order-sensitive under parallel xUnit).
+- **`Provide()`:** drive it through `CommandScenario` end-to-end; when the handler's decision is pure given provided data, also test `Handle(providedValue)` directly.
+
+#### Validation-failure assertions — non-negotiable
+
+Every unhappy-path spec asserts **both**:
+
+```csharp
+[Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
+[Fact] void should_have_validation_errors() => _result.ShouldHaveValidationErrors();
+```
+
+`ShouldNotBeSuccessful()` alone can't tell a validation rejection from an unhandled exception. **Never assert on message strings** — they're presentation text. Authorization failures use `ShouldNotBeAuthorized()` (an unauthorized result has *no* validation errors, so `ShouldHaveValidationErrors()` would silently flip). To exercise a command that carries authorization attributes, register the identity the authorization evaluator reads into `_scenario.Services` (substitute the identity provider your app uses). **Adding `[Roles]` to an existing command breaks its happy-path AND validation-failure `.Execute()` specs** — an unauthorized result is not successful and carries no validation errors; switch those assertions to `ShouldNotBeAuthorized()`.
+
+`CommandResult` assertions (from `Cratis.Arc.Testing.Commands`; failures throw `CommandResultAssertionException`): `ShouldBeSuccessful()` (`isAuthorized && isValid && !hasExceptions`), `ShouldNotBeSuccessful()`, `ShouldBeValid()` (no validation errors — does *not* check authz/exceptions), `ShouldHaveValidationErrors()`, `ShouldHaveValidationErrorFor(message)`, `ShouldBeAuthorized()`, `ShouldNotBeAuthorized()`, `ShouldHaveExceptions()`.
+
+> **Validator-state order-sensitivity:** the command-scenario pipeline can cache enough state to make injected-validator branches order-sensitive when xUnit runs classes in parallel. Use `CommandScenario` for the valid path, test rejected state-variants by **instantiating the validator directly**, and — only for that validator-state case — put the command's specs in a **small xUnit `[Collection]`**. (This is distinct from the unique-value-collision rule below, where `[Collection]` is the *wrong* fix.)
+
+### `EventScenario` — constraints & append semantics
+
+```csharp
+readonly EventScenario _scenario = new();
+IAppendResult _result;
+
+async Task Establish() =>
+    await _scenario.Given.ForEventSource(AuthorId.New()).Events(new AuthorRegistered("Jane Austen"));
+
+async Task Because() =>
+    _result = await _scenario.EventLog.Append(AuthorId.New(), new AuthorRegistered("Jane Austen"));
+
+[Fact] void should_be_failed() => _result.ShouldBeFailed();
+[Fact] void should_violate_unique_constraint() => _result.ShouldHaveConstraintViolationFor(AuthorConstraintNames.UniqueName);
+```
+
+`IAppendResult` assertions (failures throw `AppendResultAssertionException`): `ShouldBeSuccessful()`, `ShouldBeFailed()`, `ShouldHaveConstraintViolations()`/`ShouldNotHave…`, `ShouldHaveConstraintViolationFor(name)`, `ShouldHaveConcurrencyViolations()`/`ShouldNotHave…`, `ShouldHaveErrors()`/`ShouldNotHave…`. Assert the constraint **name**, never the message.
+
+### `ReadModelScenario<TReadModel>` — State View default
+
+Drives events into the projection/reducer and asserts the resulting state. Use xUnit `Assert.*` on `_scenario.Instance`.
+
+```csharp
+ReadModelScenario<Author> _scenario = null!;
+void Establish() => _scenario = new();
+
+async Task Because() =>
+    await _scenario.Given.ForEventSource(_id).Events(new AuthorRegistered("Jane Austen"), new AuthorArchived());
+
+[Fact] void should_be_archived() => Assert.True(_scenario.Instance!.IsArchived);
+```
+
+Use the named-parameter constructor when services/initial state are needed: `new ReadModelScenario<Author>(initialState: null, serviceProvider: services)`. Pre-seed a keyed read model with `Given.ForEventSourceId(id).ReadModel(instance)` for code that calls `IReadModels.GetInstanceById`. Cross-stream projections (`UsingKey`/`UsingParentKey`) are supported — seed each contributing stream with its own `Given.ForEventSource(...)`.
+
+**Bridging `IReadModels` into a `CommandScenario`** (current harness limitation): when a command handler injects `IReadModels` directly, build a focused `ReadModelScenario<T>`, seed it via `Given.ForEventSourceId(id).ReadModel(...)`, then register its read models into the command scenario — `_scenario.Services.AddSingleton(readModelScenario.ReadModels)`. Pass `scenario.ReadModels` into code under test for keyed `GetInstanceById` reads; for non-key searches/filters, register a fake lookup or an `IMongoCollection<T>` mock in the scenario services instead.
+
+**Skip discipline:** don't pre-emptively `[Fact(Skip=...)]` a read-model assertion — assume scalar `ConceptAs<string>`, enum, and identifier properties populate correctly; if one fails, investigate the projection. Only skip on a *reproduced* harness gap, and put the specific reason in the skip message.
+
+### `ReactorScenario<TReactor>` — Automation / Translation
+
+Construct with an `IServiceProvider` of NSubstitute mocks; assert on the mocks after `Given` fires events. Import `Cratis.Chronicle.Testing.Reactors;`.
+
+```csharp
+void Establish()
+{
+    _service = Substitute.For<IMyService>();
+    _scenario = new(new ServiceCollection().AddSingleton(_service).BuildServiceProvider());
+}
+async Task Because() => await _scenario.Given.ForEventSource(_id).Events(new AuthorRegistered("Jane Austen"));
+[Fact] async Task should_notify() => await _service.Received(1).Notify("Jane Austen");
+```
+
+## Out-of-process Chronicle integration specs (advanced)
+
+Reserve these for the host/transport boundary the scenario helpers can't reach. They test a complete slice — HTTP request → command → append → constraint → projection — against a real Chronicle store, and live under `when_<behavior>/` directly inside the slice folder (no `for_` folder; the "unit" is the whole slice).
+
+```csharp
+using context = MyApp.Authors.Registration.when_registering.and_name_already_exists.context;
+
+namespace MyApp.Authors.Registration.when_registering;
+
+[Collection(ChronicleCollection.Name)]
+public class and_name_already_exists(context context) : Given<context>(context)
+{
+    public class context(ChronicleOutOfProcessFixture fixture) : given.an_http_client(fixture)
+    {
+        public const string AuthorName = "John Doe";
+        public CommandResult<object>? Result;
+
+        async Task Establish() => await EventStore.EventLog.Append(AuthorId.New(), new AuthorRegistered(AuthorName));
+        async Task Because() => Result = await Client.ExecuteCommand<RegisterAuthor>("/api/authors/register", new RegisterAuthor(AuthorName));
+    }
+
+    [Fact] void should_not_be_successful() => Context.Result!.IsSuccess.ShouldBeFalse();
+    [Fact] void should_have_appended_only_one_event() => Context.ShouldHaveTailSequenceNumber(EventSequenceNumber.First);
+}
+```
+
+- `ExecuteCommand<TCommand>(url, cmd)` returns `CommandResult<object>?`; `ExecuteCommand<TCommand, TResult>(url, cmd)` returns `CommandResult<TResult>?`.
+- Helpers: `Context.ShouldHaveTailSequenceNumber(n)` (First = 0), `Context.ShouldHaveAppendedEvent<TEvent>(seq, eventSourceId, validator)`.
+
+**Async reactor follow-ups** — when a reactor fires after the command and appends further events, collect them: start the collector **before** the triggering act with `_collector = StartCollectingAppends()`, then `await _collector.WaitForCount(2, TimeSpan.FromSeconds(10))`, assert via `_collector.ShouldHaveEvent<TEvent>(e => ...)`, and `_collector.Dispose()` in `Destroy()`. (`IEventAppendCollection` from the Chronicle testing API.)
+
+## Application spec conventions
+
+These supplement the universal conventions in [specs.csharp.md](./specs.csharp.md#conventions):
+
+- **Per-test values for anything in a uniqueness check** — `$"{Guid.NewGuid():N}@example.com"`, a fresh `Guid`, or a truncated id `Guid.NewGuid().ToString("N")[..9]`. Hardcoded values cause order-dependent flakes. Do not add `[Collection(...)]` to work around *collisions* (it's the wrong fix here).
+- **Sequence numbers are zero-based** — first event = `0`, tail of two events = `1`, tail of three = `2`. Never write "tail of 1" for a single appended event; the tail of `[A]` is `0`. (A common first-pass defect.)
+- A slice covering **multiple subjects** (several read models/constraints/aspects) groups its specs under `<Slice>/for_<Subject>/when_<behavior>/`.
+
+## See also
+
+- [specs.csharp.md](./specs.csharp.md) — the universal `Specification` + NSubstitute base this builds on (and what framework specs use).
+- [vertical-slices.md](./vertical-slices.md) — what each artifact promises (the contract under spec).
+- [efcore.specs.md](./efcore.specs.md) — `DbContext` specs with SQLite in-memory.
+- skills: **write-specs**, **write-specs-events**, **write-specs-readmodels**.

package/package/corpus/rules/specs.typescript.md

@@ -0,0 +1,139 @@
+---
+applyTo: "**/for_*/**/*.ts, **/when_*/**/*.ts"
+paths:
+  - "**/for_*/**/*.ts"
+  - "**/when_*/**/*.ts"
+---
+
+# How to Write TypeScript Specs
+
+Extends the base [specs.md](./specs.md) with TypeScript-specific conventions.
+
+> **Which TS spec guide?** For **application frontend** specs — view models, React components, helpers in a Cratis application — use [frontend-testing.md](./frontend-testing.md) (plain `describe`/`beforeEach`, view models constructible without React). This file covers the **`given()`-helper** style used inside Cratis framework TypeScript packages (`@cratis/*`). Use it when contributing to the framework packages themselves.
+
+TypeScript specs follow the same BDD philosophy as C# specs — they describe behaviors, not implementations. The `given()` helper and context classes mirror the Cratis.Specifications pattern on the C# side: setup is separated from the action, and each `it()` assertion verifies a single outcome.
+
+## Frameworks
+
+- [Vitest](https://vitest.dev/) for running tests.
+- [Mocha](https://mochajs.org) for test structure (`describe`, `it`, `beforeEach`).
+- [SinonJS](https://sinonjs.org) for mocking/stubbing.
+- [Chai](https://www.chaijs.com) for assertions — **always use the `.should` fluent interface**, never `expect()`. The fluent style reads as a natural sentence: `result.should.equal(expected)`.
+- Run tests with `yarn test` from each package.
+
+## File Structure
+
+Tests live alongside source code in `for_`, `when_`, or `given_` folders:
+
+```
+for_EventsCommandResponseValueHandler/
+├── given/
+│   └── an_events_command_response_value_handler.ts
+├── when_checking_can_handle/
+│   ├── with_valid_events_collection.ts
+│   ├── with_null_value.ts
+│   └── without_event_source_id.ts
+└── when_handling/
+    ├── empty_events_collection.ts
+    └── multiple_events_collection.ts
+```
+
+## BDD Pattern with `given()` Helper
+
+The `given()` function is the TypeScript equivalent of the C# `Specification` base class. It instantiates a context class (the "given"), passes it to the test suite, and ensures setup runs before assertions. This keeps the Establish/Because/should pattern consistent across both stacks.
+
+```typescript
+import { an_events_command_response_value_handler } from '../given/an_events_command_response_value_handler';
+import { given } from '../../../given';
+
+describe('when checking can handle with valid events collection', given(an_events_command_response_value_handler, context => {
+    let result: boolean;
+
+    beforeEach(() => {
+        result = context.handler.canHandle(context.commandContext, [new TestEvent('Test')]);
+    });
+
+    it('should return true', () => {
+        result.should.be.true;
+    });
+}));
+```
+
+For behaviors with multiple outcomes, include "when \<behavior\>" as a prefix in the `describe` text.
+
+## Reusable Context Classes
+
+Context classes play the same role as `given/` classes in C# — they capture preconditions that multiple specs share. Unlike C# (where fields are `protected`), TypeScript context properties are public because tests access them directly through the `context` parameter.
+
+```typescript
+export class an_events_command_response_value_handler {
+    handler: EventsCommandResponseValueHandler;
+    commandContext: CommandContext;
+
+    constructor() {
+        this.commandContext = /* setup */;
+        this.handler = new EventsCommandResponseValueHandler(/* deps */);
+    }
+}
+```
+
+- Properties are public (not protected) — tests access them via `context.propertyName`.
+- Import `given` from the package root: `import { given } from '../../given';`.
+- Simple tests without shared setup don't need a reusable context.
+
+## Simple Test Pattern (without context)
+
+```typescript
+describe('when replacing route parameters', () => {
+    let result: { route: string; unusedParameters: object };
+
+    beforeEach(() => {
+        result = UrlHelpers.replaceRouteParameters('/api/items/{id}', { id: '123' });
+    });
+
+    it('should replace the route parameter', () => {
+        result.route.should.equal('/api/items/123');
+    });
+});
+```
+
+## Naming Conventions
+
+TypeScript specs use spaces in `it()` descriptions (unlike C# which uses underscores) because they appear in test runner output as human-readable sentences.
+
+- Use **spaces** (not underscores) in `it()` descriptions:
+  - ✅ `it('should return invalid result', ...)`
+  - ❌ `it('should_return_invalid_result', ...)`
+- Start `it()` descriptions with "should".
+- `describe()` text describes the scenario in natural language.
+
+## Assertions — Chai Fluent Interface
+
+**Always use the `.should` fluent interface. Never use `expect()`.** The `.should` style reads as a natural English sentence — `value.should.equal(expected)` vs `expect(value).to.equal(expected)` — and matches the project's preference for code that reads like prose.
+
+```typescript
+value.should.equal(expected);
+value.should.be.true;
+value.should.be.false;
+value.should.be.null;
+value.should.not.be.null;
+value.should.deep.equal(expected);
+value.should.be.instanceOf(Type);
+array.should.contain(item);
+array.should.have.lengthOf(3);
+(() => throwingFn()).should.throw(ErrorType);
+```
+
+## Mocking with Sinon
+
+```typescript
+import sinon from 'sinon';
+
+const stub = sinon.createStubInstance(ConcreteClass);
+const fetchStub = sinon.stub(globalThis, 'fetch');
+fetchStub.resolves({ ok: true, json: async () => ({ /* data */ }) });
+```
+
+## Async
+
+`beforeEach`, `afterEach`, and `it` callbacks can all be `async` when needed.

package/package/corpus/rules/storybook.md

@@ -0,0 +1,84 @@
+---
+applyTo: "**/*.stories.tsx"
+profile: application
+paths:
+  - "**/*.stories.tsx"
+---
+
+# Storybook Story Conventions
+
+Stories are visual coverage and documentation for reusable React components built on Cratis Components — **not** the behavior test suite. Non-trivial view-model/helper behavior still needs BDD Vitest specs (see [frontend-testing.md](./frontend-testing.md)). Every story file is colocated with the component it covers.
+
+## When to write a story
+
+Write stories for **reusable components**: shared component-library primitives and slice-internal components reused across slices. Do **not** story live slice pages wired directly to Arc query/command hooks or a backend — exercise those in the running app. For a presentational view that needs visual coverage, extract it or render its presentational subcomponents with deterministic fixture props.
+
+Good candidates: a presentational card/list-item/form-field with multiple visual states; a component with hover/selected/disabled/error variants; anything reusable across slices.
+
+## Preview infrastructure (what you get for free)
+
+A configured `.storybook/preview` should wrap every story in `CratisComponentsProvider` (from `@cratis/components/Common`) and import `@cratis/components/styles` so PrimeReact-based components render correctly. With that in place:
+
+- **Auto prop tables** via `react-docgen-typescript` — a component's `interface` + per-prop JSDoc renders as a Docs prop table, and union props become `select` controls automatically. Keep a JSDoc comment on every prop. **`argTypes` is an override layer** (change control type, group under `table.category`, disable a control) — don't re-list every prop.
+- **Accessibility panel** (`@storybook/addon-a11y`) scans each story with axe-core. Treat new violations as defects.
+
+## Meta block
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { MyComponent } from './MyComponent';
+
+const meta = {
+    title: 'Components/MyComponent',          // sidebar path
+    component: MyComponent,
+    parameters: { layout: 'centered' },       // 'centered' | 'padded' | 'fullscreen'
+    tags: ['autodocs'],                       // always include
+} satisfies Meta<typeof MyComponent>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+```
+
+Use `satisfies Meta<typeof Component>` — never `: Meta<T>` (better inference). `layout`: `centered` for atoms, `padded` for compound/container components, `fullscreen` for layout shells.
+
+## Required stories
+
+Adapt depth to the component — rich for complex/stateful, trimmed for atoms:
+
+1. **`Playground`** — controllable: `args` for the happy path, all props tweakable. Use `fn()` from `storybook/test` for callbacks (not `() => {}`).
+2. **Showcase** — one or more `render:` stories covering the meaningful axes (`Variants`/`Tones`, `Sizes`, `States`, `WithIcons`). Use the Arc story-kit (`StoryContainer`, `StorySection`, `StoryGrid`, `StoryDivider`, `StoryBadge` from `@cratis/arc.react/stories`) for layout. Note: `StorySection` has no `label` prop (use an `<h3>` inside); `StoryGrid` has no `columns` prop (it auto-wraps).
+3. **`InContext`** — the component in a small realistic composition.
+4. **`Interactive`** — for **stateful** components: a local `const Demo: React.FC` owning `useState`, plus a `play:` test. **Omit for presentational atoms.**
+
+Add a one-line `/** … */` doc above each story; set `parameters.docs.description.component` on the meta.
+
+## Interaction tests (`play:`) — stateful components only
+
+```tsx
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+export const Interactive: Story = {
+    render: () => <Demo />,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getAllByRole('tab')[1]);
+        await expect(canvas.getAllByRole('tab')[1]).toHaveAttribute('aria-selected', 'true');
+    },
+};
+```
+
+- **Stateful only** — presentational atoms get no `play:`. Thin PrimeReact wrappers (overlay-portal components) are excluded — their behavior is the framework's.
+- Prefer role/structure queries over localized text. `play:` runs in the Interactions panel (documentation/QA); the enforced behavioral gate is the Vitest spec.
+
+## Router-dependent components
+
+Wrap with `MemoryRouter` via a story decorator when a component uses `Link`/`useNavigate`.
+
+## Gate
+
+`build-storybook` should be green in CI — it compiles every story and `play:` function (catching broken imports/decorators) but does not execute play assertions.
+
+## See also
+
+- [react.md](./react.md) — component patterns; [components.md](./components.md) — component structure/styling.
+- [frontend-testing.md](./frontend-testing.md) — BDD Vitest specs (the behavioral gate).

package/package/corpus/rules/terminal-commands.md

@@ -0,0 +1,19 @@
+---
+applyTo: "**/*"
+description: "Use when running any terminal command. Prefix every command with rtk -- including each command in an && chain -- so token-heavy output is filtered."
+---
+
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+## Golden Rule
+
+**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.
+
+**Important**: Even in command chains with `&&`, use `rtk`:
+```bash
+# ❌ Wrong
+git add . && git commit -m "msg" && git push
+
+# ✅ Correct
+rtk git add . && rtk git commit -m "msg" && rtk git push
+```