@cratis/pi 7.28.0 → 7.29.0

package/README.md

@@ -29,6 +29,24 @@ yields to the managed installation to avoid duplicate resources and hooks. The P
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
 
+## Screenplay MCP tools
+
+The packaged `cratis-mcp` extension starts the Screenplay MCP server
+(`cratis screenplay mcp`) when the resolved profiles include `cratis/screenplay`.
+The backend application profiles compose it, so an application repository gets
+the Screenplay skills and, when the Cratis CLI 3.46.1 or later is installed, the
+Screenplay tools; the server creates no model folder until the first write.
+Installing them does not opt the repository in to model-first work.
+
+When Screenplay comes in only through such a profile and no model root is
+configured, a missing CLI, a CLI older than 3.46.1 (which creates the model
+folder at server start) or a server that fails to start leaves the Screenplay
+tools inactive with one informational notice when Pi has a UI, and silently otherwise.
+Selecting any profile that also reaches Screenplay without going through an application
+profile (including `cratis/screenplay`, `cratis/modeling/screenplay-stage`,
+`cratis/full/*` or `cratis`), or configuring `mcpServers.screenplay.root` in
+`.cratis/ai.json`, keeps startup failures visible as errors.
+
 ## Path guidance and subagents
 
 The packaged `cratis-path-guidance` extension attaches a path-scoped rule to the

package/package/corpus/harnesses/pi/extensions/cratis-mcp/configuration.ts

@@ -69,14 +69,21 @@ export function selectedServer(project: string, corpus: string) {
     });
     const languages = new Set(strings(configuration.languages));
     const selected = new Set<string>();
-    const select = (id: string, explicit: boolean): void => {
-        if (selected.has(id)) return;
+    const visited = new Set<string>();
+    let nonApplicationSelection = false;
+    const select = (id: string, explicit: boolean, throughApplication = false): void => {
         const profile = profiles.find(candidate => candidate.id === id);
         if (!profile) throw new Error(`Unknown Cratis AI profile '${id}'.`);
         const supported = strings(profile.languages);
         if (!explicit && supported.length && !supported.some(language => language === 'language-agnostic' || languages.has(language))) return;
+        const applicationPath = throughApplication || id === 'cratis/application' || id.startsWith('cratis/application/');
+        // Visit both paths: application composition must not hide an existing, independently selected Screenplay path.
+        const key = JSON.stringify([id, applicationPath]);
+        if (visited.has(key)) return;
+        visited.add(key);
         selected.add(id);
-        strings(profile.composes).forEach(child => select(child, false));
+        if (id === 'cratis/screenplay' && !applicationPath) nonApplicationSelection = true;
+        strings(profile.composes).forEach(child => select(child, false, applicationPath));
     };
     requested.forEach(id => select(id, true));
     if (!selected.has('cratis/screenplay')) return undefined;
@@ -99,5 +106,9 @@ export function selectedServer(project: string, corpus: string) {
     const root = object(screenplay) ? screenplay.root : undefined;
     if (root !== undefined && typeof root !== 'string') throw new Error('Screenplay MCP root must be a project-relative string.');
     const physicalProject = realpathSync(project);
-    return { project: physicalProject, root: root === undefined ? undefined : physicalRoot(physicalProject, root) };
+    return {
+        project: physicalProject,
+        root: root === undefined ? undefined : physicalRoot(physicalProject, root),
+        composedOnly: !nonApplicationSelection && root === undefined,
+    };
 }

package/package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts

@@ -7,19 +7,22 @@ import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { ConnectionFailure } from './ConnectionFailure.ts';
 import { object, selectedServer } from './configuration.ts';
-import { startConnection } from './process.ts';
+import { startConnection, supportsNoModelStartup } from './process.ts';
 import { discover, failedResult, mapResult } from './protocol.ts';
+import type { DiscoveredTool } from './DiscoveredTool.ts';
 import type { StdioConnection } from './StdioConnection.ts';
 
 const extensionDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCorpus = resolve(extensionDirectory, '..', '..', '..', '..');
 
 /** Native tools go through Pi's tool_call restrictions and normal execution/result pipeline. */
-export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection): void {
+export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup): void {
     let connection: StdioConnection | undefined;
     let selectionKey: string | undefined;
     let attempted = false;
     let uncertain = false;
+    let startupSupported: Promise<boolean> | undefined;
+    let unavailableReported = false;
     const registered = new Set<string>();
     const paused = new Set<string>();
     const failures = new Map<string, ReturnType<typeof failedResult>>();
@@ -47,6 +50,7 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         if (!connection || connection.stopped) throw new Error('Screenplay connection is unavailable. No request was retried; explicitly reload after inspecting any uncertain mutation.');
     };
     const refresh = async (context: ExtensionContext, newSession = false): Promise<void> => {
+        if (newSession) { startupSupported = undefined; unavailableReported = false; }
         const previouslyActive = new Set([...pi.getActiveTools(), ...paused]);
         let selection: ReturnType<typeof selectedServer>;
         try { selection = currentSelection(context); }
@@ -60,11 +64,27 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         if (!selection) return;
         if (uncertain) throw new Error('Screenplay mutation outcome remains unknown. Explicitly reload, inspect workspace-state, and obtain authorization before any recovery.');
         const modelRoot = selection.root ?? "the project's Screenplay model";
-        const activeConnection = connect(selection.project);
-        connection = activeConnection;
+        let activeConnection: StdioConnection;
+        let tools: DiscoveredTool[];
         try {
-            const tools = await discover(activeConnection);
+            if (selection.composedOnly && !await (startupSupported ??= checkVersion(selection.project))) {
+                throw new Error('Screenplay optional startup requires Cratis CLI 3.46.1 or later.');
+            }
+            activeConnection = connect(selection.project);
+            connection = activeConnection;
+            tools = await discover(activeConnection);
             if (connection !== activeConnection || activeConnection.stopped) throw new Error('Screenplay session ended during discovery.');
+        } catch (error) {
+            dispose();
+            // Application-only composition makes MCP optional. Independent profile/root errors and uncertain mutations still surface.
+            if (!selection.composedOnly || uncertain) throw error;
+            if (!unavailableReported) {
+                unavailableReported = true;
+                if (context.hasUI) context.ui.notify('Screenplay MCP is unavailable; install/update the Cratis CLI to 3.46.1 or later to enable it.', 'info');
+            }
+            return;
+        }
+        try {
             const existing = new Set(pi.getAllTools().map(tool => tool.name));
             if (tools.some(tool => existing.has(tool.nativeName) && !registered.has(tool.nativeName))) throw new Error('Screenplay native tool name conflicts with another extension.');
             const oldNames = new Set(registered);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/process.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { StdioConnection } from './StdioConnection.ts';
 
 /** Preserve OS/runtime lookup only; never copy arbitrary credentials or descriptor environment values. */
@@ -13,6 +13,27 @@ export function childEnvironment(source: NodeJS.ProcessEnv = process.env): NodeJ
     return environment;
 }
 
+/** Older CLIs create a model root at server startup; optional composition must remain footprint-free. */
+export function supportsNoModelStartup(project: string, execute: typeof execFile = execFile): Promise<boolean> {
+    return new Promise(resolve => {
+        execute('cratis', ['--version'], {
+            cwd: project,
+            env: childEnvironment(),
+            shell: false,
+            windowsHide: true,
+            timeout: 3000,
+            killSignal: 'SIGKILL',
+            maxBuffer: 4096,
+            encoding: 'utf8',
+        }, (error, stdout) => {
+            const version = /^\s*(\d+)\.(\d+)\.(\d+)(?:\+[\w.-]+)?\s*$/.exec(stdout);
+            if (error || !version) { resolve(false); return; }
+            const [, major, minor, patch] = version.map(Number);
+            resolve(major > 3 || (major === 3 && (minor > 46 || (minor === 46 && patch >= 1))));
+        });
+    });
+}
+
 export function startConnection(project: string, launch: typeof spawn = spawn): StdioConnection {
     return new StdioConnection(launch('cratis', ['screenplay', 'mcp', '--project-root', project], {
         cwd: project,

package/package/corpus/rules/profiles.md

@@ -51,16 +51,21 @@ The complete list of available profiles is defined in [profile-catalog.json](../
 
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
-| `cratis/application` | Full application stack (C# + React + TypeScript) | `cratis/application/csharp`, `cratis/application/elixir`, `cratis/application/kotlin`, `cratis/application/typescript`, `cratis/arc/core`, `cratis/arc/react`, `cratis/chronicle/core`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
-| `cratis/application/csharp` | C# backend with Arc + Chronicle | `cratis/arc`, `cratis/arc/react`, `cratis/chronicle`, `cratis/components`, `cratis/fundamentals`, `cratis/language/csharp`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
+| `cratis/application` | Full application stack (C# + React + TypeScript) | `cratis/application/csharp`, `cratis/application/elixir`, `cratis/application/java`, `cratis/application/kotlin`, `cratis/application/typescript`, `cratis/arc/core`, `cratis/arc/react`, `cratis/chronicle/core`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
+| `cratis/application/csharp` | C# backend with Arc + Chronicle | `cratis/arc`, `cratis/arc/react`, `cratis/chronicle`, `cratis/components`, `cratis/fundamentals`, `cratis/language/csharp`, `cratis/screenplay`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
 | `cratis/application/react` | React frontend with Cratis Components | `cratis/arc/core`, `cratis/arc/react`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
-| `cratis/application/typescript` | TypeScript client for Chronicle | `cratis/chronicle/client-typescript`, `cratis/language/typescript`, `cratis/specifications/typescript` |
-| `cratis/application/arc-chronicle` | Arc + Chronicle integration | `cratis/arc/core`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
-| `cratis/application/arc-only` | Arc without Chronicle | `cratis/arc/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
-| `cratis/application/chronicle-dotnet` | Chronicle .NET client | `cratis/chronicle/client-dotnet`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
-| `cratis/application/elixir` | Elixir Chronicle client | `cratis/chronicle/client-elixir`, `cratis/language/elixir` |
-| `cratis/application/kotlin` | Kotlin Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin` |
-| `cratis/application/java` | Java Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-java`, `cratis/language/java` |
+| `cratis/application/typescript` | TypeScript client for Chronicle | `cratis/chronicle/client-typescript`, `cratis/language/typescript`, `cratis/screenplay`, `cratis/specifications/typescript` |
+| `cratis/application/arc-chronicle` | Arc + Chronicle integration | `cratis/arc/core`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/screenplay`, `cratis/specifications/dotnet` |
+| `cratis/application/arc-only` | Arc without Chronicle | `cratis/arc/core`, `cratis/fundamentals`, `cratis/screenplay`, `cratis/specifications/dotnet` |
+| `cratis/application/chronicle-dotnet` | Chronicle .NET client | `cratis/chronicle/client-dotnet`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/screenplay`, `cratis/specifications/dotnet` |
+| `cratis/application/elixir` | Elixir Chronicle client | `cratis/chronicle/client-elixir`, `cratis/language/elixir`, `cratis/screenplay` |
+| `cratis/application/kotlin` | Kotlin Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin`, `cratis/screenplay` |
+| `cratis/application/java` | Java Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-java`, `cratis/language/java`, `cratis/screenplay` |
+
+`cratis/application` inherits `cratis/screenplay` through its language-specific
+children. Backend-bearing application profiles include the method skills and MCP
+declaration, not `cratis/stage`; the frontend-only `cratis/application/react`
+profile includes neither Screenplay nor Stage.
 
 ### Framework Profiles
 
@@ -179,7 +184,8 @@ or gap-fill from its contract; never edit Stage-managed output or weaken protect
 Otherwise stay code-first; only the entry-point session may propose a model, at most once
 per session. Master definition: `cratis-screenplay-modeling-lifecycle`. Framework and non-opted-in brownfield work remain
 code-first; infrastructure, clients, adapters and code attachments stay in code.
-Application profiles do not automatically compose `cratis/screenplay`.
+Backend-bearing application profiles automatically compose `cratis/screenplay`;
+installing its skills or registering its MCP server is not model-first opt-in.
 
 `cratis/screenplay` carries the **method** and the **language**. Load the lifecycle
 and one phase skill, then the construct skill needed for syntax.
@@ -228,6 +234,15 @@ conflicts. The model is wherever the project keeps its `.play` files, else under
 `src/`, else in a `Screenplay/` folder at the repository root; never under `.cratis/`.
 Project-owned configuration can name a root explicitly.
 
+**No-model startup requires Cratis CLI 3.46.1 or later.** With
+`cratis screenplay mcp --project-root <project>`, that version resolves the root
+without creating it; discovery, startup and proposals leave no model folder, and
+the first `apply` write creates it. `cratis ai install` also creates no model
+folder unless the project configured a root. Older CLIs create the resolved model root at
+server startup (`Screenplay/` when no `.play` files, `Source/` or `src/` exist); upgrade before using the automatically selected MCP server in a
+repository without a model. In Pi, when every selected path to Screenplay goes through an application profile and no root is configured, a missing, older or unavailable CLI leaves its MCP tools inactive with one informational UI notice (none in headless mode); an independent non-application path to Screenplay or a configured root still surfaces startup errors. See the toolchain skill's
+[version reference](../skills/cratis-screenplay-toolchain/references/versions.md).
+
 ## How to Use Profiles
 
 ### 1. Select Your Profile
@@ -268,7 +283,7 @@ Profiles can compose other profiles. When you select a parent profile, all child
 {
   "schemaVersion": "1.0.0",
   "profiles": [
-    "cratis/application/csharp"  // Includes: arc, arc/react, chronicle, components, fundamentals, language/csharp, specifications/dotnet, specifications/typescript
+    "cratis/application/csharp"  // Includes: arc, arc/react, chronicle, components, fundamentals, language/csharp, screenplay, specifications/dotnet, specifications/typescript
   ]
 }
 ```

package/package/corpus/rules/reactors.md

@@ -278,4 +278,34 @@ async Task Because() => await _scenario.Given.ForEventSource(_id).Events(new Inv
 [Fact] async Task should_notify_about_the_issued_invoice() => await _notifications.Received(1).Notify(Arg.Is<string>(_ => _.Contains("INV-1001")));
 ```
 
+### Read-model dependencies in scenarios — Chronicle 19.46.0+
+
+`ReactorScenario<TReactor>` does **not** build read models from `Given` events,
+including `[Passive]` models. Seed the handler's read-model parameter explicitly
+before firing the trigger:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_order);
+async Task Because() => await _scenario.Given.ForEventSource(_id).Events(_orderPlaced);
+```
+
+In a separate absence specification, replace the seeding with
+`_scenario.Given.ForEventSourceId(_id).NoReadModel<Order>()` to deliberately pass
+`null` to an `Order?` parameter. Without either setup, resolution to `null` throws
+`ReadModelNotSeededForReactorScenario` (`Cratis.Chronicle.Testing.Reactors`), even
+for a nullable parameter. Its message names the type and missing key, suggests
+both setup methods, and lists other seeded keys for that type when any exist.
+Use the key from `ICanResolveReadModelKey.Resolve` for seeding or absence when
+implemented, not the triggering source id. `NoReadModel<T>()` does not remove a
+seeded instance. This guard applies to `EventStoreForTesting`, not an explicitly
+supplied store of another type; production read-model resolution is unchanged.
+
+Also in Chronicle 19.46.0+, `Events(...)` surfaces a synchronously throwing
+handler's own exception, preserving its stack, rather than the reflection
+`TargetInvocationException`. Capture it with `Catch.Exception` and assert the
+handler's exception type. `EventContext.From(...)` now defaults an omitted
+`occurred` to `DateTimeOffset.UtcNow`, not local `Now`; scenario contexts,
+`EventContext.Empty` and `EmptyWithEventSourceId(...)` use that helper. An
+explicit occurrence time is preserved, not normalized to UTC.
+
 For reactors that return side-effect events, assert the resulting appends through the scenario's event store; for non-event side effects, assert on the mocked services (as above). See [specs.scenarios.csharp.md](./specs.scenarios.csharp.md) for the full `*Scenario` family.

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

@@ -160,6 +160,47 @@ async Task Because() => await _scenario.Given.ForEventSource(_id).Events(new Aut
 [Fact] async Task should_notify() => await _service.Received(1).Notify("Jane Austen");
 ```
 
+#### Read-model setup — Chronicle 19.46.0+
+
+In a class-based `ReactorScenario<TReactor>`, `Given` events invoke the reactor;
+they **do not materialize read models**, even `[Passive]` ones. For each
+read-model handler parameter, choose one setup before `Because()`:
+
+```csharp
+// Present-state specification: supply the instance the handler must receive.
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_author);
+
+// Separate absence specification: deliberately let an Author? parameter receive null.
+void Establish() => _scenario.Given.ForEventSourceId(_id).NoReadModel<Author>();
+```
+
+These are alternatives in **separate specification classes**, not two
+`Establish()` methods in one class. Both builders return
+`ReactorSourceGivenBuilder<TReactor>` for chaining; neither setup is async.
+Use the triggering event-source id by default, or the key returned by the
+reactor's `ICanResolveReadModelKey.Resolve` when implemented. An absence
+declaration is for that exact type and key and does not delete a seeded model.
+
+If a recognized read-model parameter resolves to `null` without declared absence,
+`Events(...)` throws `ReadModelNotSeededForReactorScenario` from
+`Cratis.Chronicle.Testing.Reactors`, even if the parameter is nullable. The
+message names the full type and missing key, explains `ReadModel(...)` and
+`NoReadModel<T>()`, and lists seeded keys for that type when any exist. Fix the
+fixture or its key; do not add `NoReadModel<T>()` just to silence missing setup.
+The guard applies to `EventStoreForTesting`; it does not alter production
+resolution or an explicitly supplied event store of another type.
+
+**Handler failures:** in Chronicle 19.46.0+, a synchronous handler throw surfaces
+its own exception, not `TargetInvocationException`, with its handler stack
+preserved. Use `await Catch.Exception(() => _scenario.Given.ForEventSource(_id).Events(...))`
+and assert the handler's exception type.
+
+**Occurrence time:** in Chronicle 19.46.0+, `EventContext.From(...)` uses
+`DateTimeOffset.UtcNow` when `occurred` is omitted (previously local `Now`).
+`ReactorScenario` builds its contexts through this helper, as do
+`EventContext.Empty` and `EmptyWithEventSourceId(...)`. Explicit occurrence times
+keep their supplied offset; the positional constructor has no such default.
+
 ## 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).

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -30,6 +30,10 @@ This skill decides **when to add a scenario** and **what to cover**. The C# mech
 
 > Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
 
+Reactor read-model setup and the `EventContext.From` UTC default below are
+verified separately at **Chronicle 19.46.0**, the minimum version for that
+guidance; see `cratis-chronicle-reactor/references/specifications.md` for sources.
+
 `Cratis.Testing` is the meta-package that brings `Cratis.Arc.Testing` and
 `Cratis.Arc.Chronicle.Testing` together. Reverify against the owning product
 repository before claiming support for another version.
@@ -112,6 +116,15 @@ keep a scenario for that wiring and for appended-event behavior.
 | Automation or Translation — a reactor | `ReactorScenario<TReactor>` | `cratis-specifications-csharp` |
 | A host, transport, or real-infrastructure boundary | Out-of-process integration | `cratis-specifications-csharp` |
 
+For a class-based reactor scenario on **Chronicle 19.46.0+**, explicitly seed
+handler read-model parameters with `Given.ForEventSourceId(id).ReadModel(instance)`
+or declare intentional absence with `.NoReadModel<T>()`. An unseeded model throws
+`ReadModelNotSeededForReactorScenario` even if nullable; `Given` events do not
+build read models, including passive ones. Use the reactor's resolved key, not
+necessarily the trigger's source id. This is **not** the command-scenario event
+seeding described in Step 5. Read `cratis-chronicle-reactor` for the setup examples,
+exception diagnostics, synchronous handler throws and UTC context defaults.
+
 ## Step 3 — Cover every outcome of a State Change slice
 
 One specification class for **each** of:

package/package/corpus/skills/cratis-chronicle-reactor/SKILL.md

@@ -45,6 +45,11 @@ This skill is verified against these exact sources:
 | `Cratis.Chronicle` | `18.3.0` | `Cratis.Chronicle.Reactors`, `Cratis.Chronicle.Reactors.SideEffects`, `Cratis.Chronicle.EventSequences`, `Cratis.Chronicle.Events` |
 | `Cratis.Chronicle.CodeAnalysis` | `18.3.0` | `CHR0004`, `CHR0005`, `CHR0008`, `CHR0013`, `CHR0022`, `CHR0031`, `CHR0032` |
 
+Scenario read-model seeding/absence, synchronous handler exception propagation,
+and the `EventContext.From` UTC default are verified separately at **Chronicle
+19.46.0**; they require **19.46.0+**. See the source paths in
+[references/specifications.md](references/specifications.md).
+
 Reverify product sources before claiming support for another version.
 
 > **There is no `ReactorSideEffect` type.** It does not exist in Chronicle, in
@@ -363,7 +368,17 @@ when they serve that concern.
 
 Start with `Specification` plus a direct call for pure reactor decisions; add `ReactorScenario<TReactor>` only where invocation, dependency wiring or side effects contribute proof. Specify the contract, not only the happy path: field lineage, contract-authorized filtering, repeated delivery, and unrelated events.
 
-Read [references/specifications.md](references/specifications.md) when writing or reviewing reactor specifications.
+In Chronicle **19.46.0+**, a handler's unseeded read-model parameter throws
+`ReadModelNotSeededForReactorScenario`, even if nullable. Seed it through
+`Given.ForEventSourceId(id).ReadModel(instance)`, or declare intentional absence
+with `.NoReadModel<T>()`. Use the resolved read-model key; `Given` events do not
+build read models, including passive ones. A synchronous handler throw surfaces
+the handler's exception rather than a reflection wrapper, and the scenario's
+`EventContext.Occurred` defaults to UTC.
+
+Read [references/specifications.md](references/specifications.md) before writing
+or reviewing reactor specifications; it shows both setup alternatives and the
+scope of these scenario-only guards.
 
 ## Verify
 

package/package/corpus/skills/cratis-chronicle-reactor/references/specifications.md

@@ -1,3 +1,12 @@
+# Reactor specifications
+
+## Contents
+
+- Specifications
+- Read-model setup — Chronicle 19.46.0+
+- Exceptions and occurrence time — Chronicle 19.46.0+
+- Contract coverage
+
 ## Specifications
 
 Start with `Specification` plus a direct call for pure reactor decisions,
@@ -9,6 +18,82 @@ non-event side effects; for handlers that return events, assert the resulting
 appends through the scenario's event store. Cover the replay path separately
 when the reactor has `[OnceOnly]` or `[Replay]` handlers.
 
+## Read-model setup — Chronicle 19.46.0+
+
+Class-based `ReactorScenario<TReactor>` does not build read models from `Given`
+events, **including passive models**. Seed a pre-built instance in `Establish()`:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_order);
+async Task Because() => await _scenario.Given.ForEventSource(_id).Events(_orderPlaced);
+```
+
+For a **separate absence specification**, use this setup instead, so an `Order?`
+handler parameter deliberately receives `null`:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).NoReadModel<Order>();
+```
+
+The builders live in `Cratis.Chronicle.Testing.Reactors`. Exact signatures on
+`ReactorSourceGivenBuilder<TReactor>` (`where TReactor : class, IReactor`):
+
+```csharp
+public ReactorSourceGivenBuilder<TReactor> ReadModel<TReadModel>(TReadModel readModel)
+    where TReadModel : class;
+public ReactorSourceGivenBuilder<TReactor> NoReadModel<TReadModel>()
+    where TReadModel : class;
+public Task Events(params object[] events);
+```
+
+Both `Given.ForEventSource(EventSourceId)` and
+`Given.ForEventSourceId(EventSourceId)` return this builder. Seed or declare
+absence using the triggering source id by default, or the key returned by
+`ICanResolveReadModelKey.Resolve` when implemented. Declarations are shared
+across the scenario's builders, match the **exact type and key**, and do not
+remove a seeded instance. Do not declare absence to hide forgotten setup.
+
+If a recognized read-model parameter resolves to `null` without declared
+absence, `Events(...)` throws `ReadModelNotSeededForReactorScenario` from
+`Cratis.Chronicle.Testing.Reactors`, **even for nullable parameters**. Its message
+names the full read-model type and key, tells you to seed via `ReadModel(...)`
+or declare `NoReadModel<T>()`, and lists other seeded keys for that type when
+any exist. Check the key first if the fixture already seeds that type. This
+guard applies only when the scenario uses `EventStoreForTesting` (including an
+explicit instance); an explicitly supplied store of another type and production
+read-model resolution are unchanged.
+
+## Exceptions and occurrence time — Chronicle 19.46.0+
+
+`Events(...)` rethrows a synchronously throwing handler's **own exception**,
+unwrapping the `TargetInvocationException` previously surfaced by reflection,
+and preserves the handler stack. Capture with
+`await Catch.Exception(() => _scenario.Given.ForEventSource(_id).Events(_orderPlaced))`
+and assert the handler's exception type, not a reflection wrapper.
+
+`EventContext.From(...)` defaults omitted `occurred` to `DateTimeOffset.UtcNow`
+(previously `DateTimeOffset.Now`). `ReactorScenario` uses this helper, as do
+`EventContext.Empty` and `EmptyWithEventSourceId(...)`. Explicit timestamps keep
+their supplied offset; the positional constructor does not default `Occurred`.
+For deterministic time-dependent plain-call specs, supply a fixed occurrence
+time rather than asserting an exact current instant.
+
+Verified against **Chronicle tag `v19.46.0`**:
+
+- `Source/Clients/Testing/Reactors/ReactorSourceGivenBuilder.cs` and
+  `ReactorScenarioGivenBuilder.cs`: seeding, absence and builder signatures.
+- `Source/Clients/Testing/Reactors/ScenarioReactorMethodArgumentsResolver.cs` and
+  `ReadModelNotSeededForReactorScenario.cs`: guard scope, resolved key and message.
+- `Source/Clients/Testing/Reactors/ReactorScenario.cs`: synchronous exception
+  unwrapping and context creation.
+- `Source/Clients/DotNET/Events/EventContext.cs`: UTC default and explicit time.
+- `Source/Clients/Testing.Specs/Reactors/for_ReactorScenario/when_resolving_read_model_dependencies/`:
+  seeded, absent, nullable, passive, custom-key and explicit-store examples.
+- `Source/Clients/Testing.Specs/Reactors/for_ReactorScenario/when_a_reactor_handler_throws_synchronously.cs`
+  and `when_a_reactor_reads_the_occurrence_time.cs`: handler exception and UTC specs.
+
+## Contract coverage
+
 Specify the contract, not only the happy path:
 
 - **Field lineage.** For each returned command or event, a specification asserts

package/package/corpus/skills/cratis-screenplay-toolchain/references/versions.md

@@ -31,6 +31,17 @@ Check the actual executable before relying on this table: `screenplay --version`
 `cratis --version`, MCP `initialize` → `serverInfo.version`. An older executable
 on PATH can shadow a newer install; inspect `which -a cratis`.
 
+**Minimum for no-model MCP startup: Cratis CLI 3.46.1.** At `v3.46.1`,
+`cratis screenplay mcp --project-root <project>` resolves a root without creating
+it; startup, discovery and proposals leave no model folder, and the first
+`apply` write creates it. `cratis ai install` creates no model folder unless a
+root is configured. Older CLIs create the resolved root on server startup (`Screenplay/` when no `.play` files, `Source/` or `src/` exist). Released
+source evidence: CLI
+`Source/Cli.Specs/for_ScreenplayMcpInvocation/when_serving_a_project_without_a_model/and_the_client_writes_a_document.cs`
+and `Source/Cli.Specs/for_AiMcpRegistration/when_installing/with_a_composed_profile.cs`
+at tag `v3.46.1` (CLI#322 / CLI#311). This minimum does not re-label the compiler
+or renderer probes below as results from the newer bundle.
+
 ## Two compilers, one rule
 
 Standalone Screenplay 4.131.0 and the CLI's 4.130.0 bundle are different releases.

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -22,6 +22,11 @@ This skill is verified against these exact public releases:
 | `Cratis.Arc.Testing` | `22.16.0` | `CommandScenario<TCommand>` and `CommandResult` assertions |
 | `Cratis.Chronicle.Testing` | `18.3.0` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
 
+Reactor read-model seeding/absence, synchronous handler exceptions and the
+`EventContext.From` UTC default are verified separately at **Chronicle 19.46.0**
+and require **19.46.0+**; see the ReactorScenario section in
+[application-scenarios.md](references/application-scenarios.md).
+
 Generated-value scenario pinning is verified separately against
 `Cratis.Arc.Testing` **22.68.0** (introduced in **22.67.0**).
 
@@ -83,6 +88,14 @@ never produces a concurrency violation. `ShouldHaveConcurrencyViolations()`
 cannot pass for such an append and its negation passes vacuously — specify concurrency against the
 real kernel with an out-of-process integration specification instead.
 
+For a class-based `ReactorScenario<TReactor>` on **Chronicle 19.46.0+**, seed each
+handler read-model parameter with `Given.ForEventSourceId(id).ReadModel(instance)`
+or declare intentional absence with `.NoReadModel<T>()`; `Given` events do not
+build it, even if passive. Missing setup throws
+`ReadModelNotSeededForReactorScenario` even for a nullable parameter. Use the
+resolved read-model key. See the ReactorScenario reference for diagnostics,
+exception capture and UTC occurrence-time defaults.
+
 Specification projects are named `<Source>.Specs` and run on xUnit.
 
 ### Pin server-generated Handle values

package/package/corpus/skills/cratis-specifications-csharp/references/application-scenarios.md

@@ -262,6 +262,47 @@ async Task Because() =>
 Construct with an `IServiceProvider` of substituted collaborators and assert on
 those substitutes after `Given` fires the events.
 
+### Read-model parameters — Chronicle 19.46.0+
+
+`Given` events invoke the reactor; they **do not build read models**, including
+passive ones. In the present-state specification, seed a pre-built instance:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_author);
+```
+
+In a **separate absence specification**, deliberately let an `Author?` handler
+parameter receive `null`:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).NoReadModel<Author>();
+```
+
+Both return `ReactorSourceGivenBuilder<TReactor>` for chaining, not a `Task`.
+Use the triggering source id by default or `ICanResolveReadModelKey.Resolve`'s
+key when implemented. Absence matches the exact type and key and does not remove
+a seeded instance. Missing setup throws `ReadModelNotSeededForReactorScenario`
+(`Cratis.Chronicle.Testing.Reactors`), **even for nullable parameters**. Its
+message names the type/key, explains both setups, and lists other seeded keys
+for that type when any exist. Fix the fixture/key rather than hiding missing
+setup with `NoReadModel<T>()`. This guard applies to `EventStoreForTesting`, not
+production resolution or an explicitly supplied store of another type.
+
+Also in **Chronicle 19.46.0+**, a synchronous handler throw surfaces its own
+exception, not reflection's `TargetInvocationException`, preserving the handler
+stack. Capture with `await Catch.Exception(() => _scenario.Given.ForEventSource(_id).Events(...))`
+and assert the handler's exception type.
+
+`EventContext.From(...)` defaults omitted `occurred` to `DateTimeOffset.UtcNow`,
+previously local `Now`. Scenario contexts, `EventContext.Empty` and
+`EmptyWithEventSourceId(...)` use this helper; explicit times retain their offset,
+and the positional constructor has no such default.
+
+Sources at **Chronicle tag `v19.46.0`**:
+`Source/Clients/Testing/Reactors/{ReactorScenario,ReactorSourceGivenBuilder,ScenarioReactorMethodArgumentsResolver,ReadModelNotSeededForReactorScenario}.cs`
+and `Source/Clients/DotNET/Events/EventContext.cs`. For exact signatures and
+source-backed examples, read `cratis-chronicle-reactor/references/specifications.md`.
+
 ## Application conventions
 
 - **Use a per-specification fixture value for anything under a shared uniqueness

package/package/profile-catalog.json

@@ -114,6 +114,7 @@
         "cratis/arc/core",
         "cratis/chronicle/core",
         "cratis/fundamentals",
+        "cratis/screenplay",
         "cratis/specifications/dotnet"
       ],
       "languages": [
@@ -125,6 +126,7 @@
       "composes": [
         "cratis/arc/core",
         "cratis/fundamentals",
+        "cratis/screenplay",
         "cratis/specifications/dotnet"
       ],
       "languages": [
@@ -137,6 +139,7 @@
         "cratis/chronicle/client-dotnet",
         "cratis/chronicle/core",
         "cratis/fundamentals",
+        "cratis/screenplay",
         "cratis/specifications/dotnet"
       ],
       "languages": [
@@ -152,6 +155,7 @@
         "cratis/components",
         "cratis/fundamentals",
         "cratis/language/csharp",
+        "cratis/screenplay",
         "cratis/specifications/dotnet",
         "cratis/specifications/typescript"
       ],
@@ -165,7 +169,8 @@
       "id": "cratis/application/elixir",
       "composes": [
         "cratis/chronicle/client-elixir",
-        "cratis/language/elixir"
+        "cratis/language/elixir",
+        "cratis/screenplay"
       ],
       "languages": [
         "elixir"
@@ -176,7 +181,8 @@
       "composes": [
         "cratis/arc/client-kotlin",
         "cratis/chronicle/client-java",
-        "cratis/language/java"
+        "cratis/language/java",
+        "cratis/screenplay"
       ],
       "languages": [
         "java"
@@ -187,7 +193,8 @@
       "composes": [
         "cratis/arc/client-kotlin",
         "cratis/chronicle/client-kotlin",
-        "cratis/language/kotlin"
+        "cratis/language/kotlin",
+        "cratis/screenplay"
       ],
       "languages": [
         "kotlin"
@@ -214,6 +221,7 @@
       "composes": [
         "cratis/chronicle/client-typescript",
         "cratis/language/typescript",
+        "cratis/screenplay",
         "cratis/specifications/typescript"
       ],
       "languages": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.28.0",
+  "version": "7.29.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [