@cratis/pi 7.75.0 → 7.77.0

package/package/corpus/skills/cratis-chronicle-multi-tenancy/references/remove-namespace.md

@@ -0,0 +1,38 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Remove a namespace
+
+Requires Chronicle 19.73.0 for `IEventStore.RemoveNamespace`.
+Requires Chronicle 19.75.1 for reminder cleanup.
+Requires Chronicle 19.76.1 for concurrent re-subscription recovery.
+Requires client 19.77.1 for forgetting a removed namespace on reconnect. Check
+with `dotnet list package` and the kernel image tag; older pairs can recreate
+an apparently removed namespace.
+
+This is destructive tenant removal, not a way to hide a tenant in the UI.
+Before calling it, confirm the named event store and namespace, the authorized
+scope, backups and application-owned storage disposition. Never target the
+default namespace: its removal is refused. Removing an unknown namespace is a
+no-op, and an interrupted removal can be repeated.
+
+Removal first stops listing the namespace, unsubscribes and removes its
+observers and their persistent reminders, then drops provider-owned namespace
+storage and forgets the namespace. Forwarding and pattern observers with no
+saved state are included through their reminders. Re-subscriptions already in
+flight are handled by bounded unsubscribe/remove retries.
+
+MongoDB drops its namespace database. SQL and in-memory providers retain their
+namespace data; do not claim removal is erasure in those providers. Application
+read-model databases are not dropped: the application owns that data and its
+separately authorized cleanup.
+
+On reconnect a non-default store asks whether its namespace still exists. If
+absent, it releases that store instead of re-registering it; if the kernel
+cannot answer, registration follows the older behavior. Explicitly using the
+namespace again can create it anew. Stop or reroute writers when removal must
+remain final.
+
+Verify removal with a matching kernel and provider, including restart and
+reconnect, and separately inspect the disposition of application-owned data.
+Do not create or delete a live tenant merely to test this workflow.

package/package/corpus/skills/cratis-chronicle-projection/references/definition-changes.md

@@ -23,5 +23,31 @@ history. Sources: `Documentation/projections/registration-lifecycle.md`,
 `Documentation/concepts/observers.mdx`, `Observation/Jobs/{CatchUpObserver,ReplayObserver}.cs`
 and `Observation/States/Routing.cs` (under `Source/Kernel/Core/`).
 
+## Rolling deployment versions
+
+Requires Chronicle 19.79.0 on client and kernel for projection registration's
+`ChronicleOptions.SoftwareVersion`. It defaults to the entry assembly's informational version;
+`Cratis:Chronicle:SoftwareVersion` overrides it, and startup warns on `1.0.0`.
+Check `dotnet list package` and the kernel image tag; older kernels ignore it.
+
+The kernel compares semantic-version precedence, including prerelease labels.
+An older definition cannot overwrite a newer stored version, and an older
+full-set registration cannot retire newer projections. Equal, missing or
+unparseable versions retain ordinary registration behavior. An intentional
+rollback must give the older code a software version higher than the stored
+one. Changing only software version does not request a replay; definition
+evolution policy still determines that.
+
+## Namespace reconciliation
+
+Requires Chronicle 19.81.1 for projections and captures to reconcile subscriptions
+in every namespace, including runtime-created namespaces. Explicit ensure waits
+for healthy subscriptions; implicit first-append creation is reconciled within
+a watchdog interval. A broken definition does not block healthy ones or creation.
+A lost subscription is repaired, but reconciliation never lifts quarantine,
+revives a retired observer, or restarts a stopped/deleted capture. A kernel
+restart or a newly added namespace still ends projection quarantine through a
+fresh subscription; do not interpret ordinary watchdog repair as operator clear.
+
 Closing a stream does not erase its events or prevent a projection replay.
 Keep the closing fact as history; see **cratis-chronicle-event-constraints**.

package/package/corpus/skills/cratis-chronicle-projection/references/model-bound-attributes.md

@@ -59,6 +59,14 @@ pair it with `[NotRewindable]`. `[NotProjected]` excludes a query-assembled memb
 from AutoMap and CHR0024. Sources: `Projections/ModelBound/NotProjectedAttribute.cs`,
 `Projections/FromEveryBuilder.cs`, and `Documentation/projections/model-bound/`.
 
+Requires Chronicle 19.78.1 for `[FromAll]`/`[FromEvery]` properties under
+`[ChildrenFrom<T>]` or `[Nested]` to be declared on the child itself, including
+the event creating it. Parent all-event mappings are not copied into children.
+Older client definitions with root-declared child mappings work only when the
+root has no property with the same name; otherwise the mapping stays on the
+root until the client is upgraded. Check client/kernel versions and replay
+affected projections to rebuild already materialized child values.
+
 ## Setting values
 
 | Attribute | Arity | Parameters | Targets |

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

@@ -133,32 +133,15 @@ re-delivers the event as an ordinary observation, and a `[OnceOnly]` handler run
 again. Catch-up and crash redelivery are not replay either; every ordinary
 matching event can run, even on the same source. Keep effects idempotent.
 
-**A reactor new to a store catches up the whole history on first registration, and
-`[OnceOnly]` does not cover that.** For a side-effect reactor (jobs, AI or external
-calls), start the observer at the tail or have the handler ignore facts that
-predate its registration, and specify that history causes nothing. A
-reconciliation sweep that decides from a read model must not run while that model's
-observer is replaying or behind: a rebuilding model looks like "never processed".
-Decide from the events or a `[Passive]` model, and specify the replaying case.
+**A new reactor catches up history; `[OnceOnly]` does not stop that.**
+Requires Chronicle 19.70.0 for `[StartAtTail]` to start only its first registration
+at the tail; existing positions remain. Upgrade the server first: older kernels
+ignore it. Read references/starting-and-replaying.md when avoiding pre-registration
+side effects or choosing alternate replay behavior.
 
 Analyzer **CHR0022** (warning) requires `[OnceOnly]` on a handler that returns
 event side effects, because a replay would otherwise append duplicates.
 
-`Cratis.Chronicle.Reactors.ReplayAttribute` (`[Replay]`) is the other half, and
-targets a method only. Mark a **second** handler for the same event type with it
-when replay needs to do something *different* rather than nothing:
-
-```csharp
-public Task <MethodName>(<EventName> @event) => <serviceName>.<Operation>(@event.<Property>);
-
-[Replay]
-public Task <MethodName>DuringReplay(<EventName> @event) => Task.CompletedTask;
-```
-
-With a `[Replay]` handler present, only it runs during replay. Without one, the
-ordinary handler runs during replay as before. An event type handled *only* by a
-`[Replay]` handler is still subscribed to.
-
 ## Identity and event sequence
 
 `Cratis.Chronicle.Reactors.ReactorAttribute` takes two optional arguments:

package/package/corpus/skills/cratis-chronicle-reactor/references/starting-and-replaying.md

@@ -0,0 +1,33 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Start at the tail and distinguish replay
+
+Requires Chronicle 19.70.0 for `[StartAtTail]` in
+`Cratis.Chronicle.Reactors`. Upgrade the server before the client: an older
+server ignores the field and catches up from the beginning. Check with
+`dotnet list package` and the kernel image tag.
+
+Put `[StartAtTail]` on a side-effect reactor that should observe only future
+events. It changes the **first registration**: an observer already holding a
+position keeps it. Leaving the attribute in place is safe, but adding it is not
+a command to fast-forward an existing observer. Specify that historical facts
+cause no effect on first registration.
+
+`[OnceOnly]` excludes replay, not initial catch-up, failed-partition recovery
+or crash redelivery. Keep side effects idempotent. A reconciliation sweep must
+not decide from a model that is replaying or behind: rebuilding state can look
+like "never processed". Decide from events or a passive model and cover that case.
+
+## Alternate replay behavior
+
+`Cratis.Chronicle.Reactors.ReplayAttribute` targets a method. Mark a second
+handler for the same event type when replay must do different work. With that
+handler present only it runs during replay; without one, the ordinary handler
+runs unless excluded by `[OnceOnly]`. An event type handled only by a `[Replay]`
+handler is still subscribed to.
+
+Verify first registration, restart with an existing position, replay and
+failed-partition redelivery separately. Assert the external effect count, not
+only that the handler was invoked. Run `dotnet test` on the owning spec project;
+server-first compatibility and durable positions also need kernel integration.

package/package/corpus/skills/cratis-chronicle-read-model/SKILL.md

@@ -215,8 +215,8 @@ current rather than eventually consistent.
 **Passive is fresher, not safer.** A materialized read may lag the log; a passive
 read is current when read. Neither captures a position or enrolls a guard, so
 neither makes a rule hold when two requests race. To guard a decision use a decision
-read over a flat, event-source-keyed projection with an `Id` property (reducers and
-self-reducing models are refused), a constraint for uniqueness, or an aggregate;
+read over an admitted projection or unfiltered dependency-free reducer, a
+constraint for uniqueness, or an aggregate;
 see [choosing how a rule holds](../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md).
 
 **`IMongoCollection<T>` reads only the sink.** It cannot compute passive state:
@@ -227,6 +227,13 @@ read-model parameter injection) when you need its computed state. Do not remove
 Keep secret-bearing state on the protected access path; project only safe
 metadata into a separate list/search model.
 
+Requires Chronicle 19.77.3 for strongly consistent per-key projections to fold
+from the start on every read: passive, stream-scoped, wildcard-key and session
+reads immediately reflect revisions, redactions and joined-subject erasure.
+Earlier warm reads can retain old content. Each read costs O(key history), not
+an incremental suffix; prefer materialization for frequent long-history reads.
+Check the deployed kernel tag before relying on this freshness.
+
 The number of passive types is not itself a performance smell. Review event
 history length, invocation frequency, and the consistency/security requirement;
 repeated reconstruction of large histories on a hot path is the concern.

package/package/corpus/skills/cratis-chronicle-read-model/references/queries.md

@@ -32,10 +32,15 @@ Chronicle extensions — Chronicle declares no `Observe` on `IMongoCollection<T>
 
 ## Discovery rules
 
-Arc discovers **public static** methods; private and compiler-generated methods
-are never queries. Use `[ReadModel(RequireQueryAttribute = true)]` and `[Query]`
-on intended endpoints when the type also has folds (`Create`/`Reduce`) or public
-helpers. `[Query]` alone does not hide siblings. ARC0026 checks invalid/ambiguous
+Arc discovers eligible **public and internal static** methods on `[ReadModel]`
+types. Internal visibility is not an endpoint privacy boundary. Keep helpers
+outside the read model, regardless of their visibility. Use
+`[ReadModel(RequireQueryAttribute = true)]` and `[Query]` on intended endpoints
+when the type also has folds (`Create`/`Reduce`); `[Query]` alone does not hide
+siblings. Requires Arc 22.27.1 for exclusion of private, protected, special-name
+and compiler-generated methods; older versions can expose private statics too.
+Check with `dotnet list package`; on older versions move helpers out rather
+than relying on visibility. ARC0026 checks invalid/ambiguous
 query declarations; ARCCHR0019 warns about fold-like statics exposed by convention.
 Requires Arc 22.90.0 for automatic exclusion of methods taking the model itself,
 including `Reduce(event, current)`; `[Query]` cannot force such a method into an

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

@@ -234,6 +234,10 @@ event means no observer subscription; assembly membership alone is not event
 membership. Types implementing `IReducer` stay classic even with a self-shaped
 static helper.
 
+Requires Chronicle 19.72.0 for CHR0065 to warn on fold-like methods that are
+misnamed (`Reducer`/`reduce`) or not static and therefore never discovered.
+Check `dotnet list package`; older analyzers can leave those methods silent.
+
 Use the existing generic or Type `RegisterReducer` API for explicit self-model
 nomination too; there is no special self API. A self model cannot share ownership
 with a separate reducer, fluent projection or genuine model-bound mappings in the

package/package/corpus/skills/cratis-multi-service-architecture/SKILL.md

@@ -154,9 +154,15 @@ of tags, and export only the fields consumers need. Read
 ## Versioning contracts
 
 A public event type follows the same generation and migration rules as a private
-one (`cratis-chronicle-event-type-migration`). Kernel subscriptions name event
-types by id and register them as generation 1, and the CLI's `subscriptions add`
-takes ids only. Prefer additive, optional changes to a contract; publish a new
+one (`cratis-chronicle-event-type-migration`). Requires Chronicle 19.66.0 for
+subscription-builder `WithGenerationDelivery(EventGenerationDelivery.Pinned)`
+with typed `WithEventType<TEvent>()` or `WithEventType(id, generation)` to pin
+forwarding into the target inbox. Both stores must register that generation;
+Compatibility remains the default. Read
+../cratis-chronicle-client-dotnet/references/pinned-generation-delivery.md when
+configuring subscription pins and failure behavior. The CLI's `subscriptions add`
+takes ids only; do not invent a generation flag. Prefer additive, optional changes
+to a contract; publish a new
 event type for a breaking change and keep publishing the old one until every
 consumer has moved, rather than adding a generation consumers may not handle.
 Version the contracts package with the contract, and never move a type between

package/package/corpus/skills/cratis-performance-review/SKILL.md

@@ -80,7 +80,10 @@ behavior this file does not already state.
 - Preserve reducer admission and ordering guards when proposing a projection
   conversion; an unconditional setter may resurrect or prematurely create state.
 - Count passive models as inventory, not a smell. Assess history length and read
-  frequency against consistency/security needs. `IMongoCollection<T>` cannot
+  frequency against consistency/security needs. Requires Chronicle 19.77.3 for
+  per-key strongly consistent projection reads to fold from the start each time;
+  repeated reads are O(key history), not incremental cache hits. Prefer a
+  materialized projection for frequent long-history reads when freshness permits. `IMongoCollection<T>` cannot
   read passive computed state; never materialize secrets to make that query work.
 - Distinguish retained `Observe` state and in-memory emissions from explicit
   recompute queries. Narrow source filters and inspect page-refill/membership

package/package/corpus/skills/cratis-screenplay-automations-and-translations/SKILL.md

@@ -42,8 +42,8 @@ Start new models with application-root `reaction batches atomic` (ESM v22 or lat
 Each trigger occurrence's direct productions and each selected refusal branch are
 separate all-or-none batches; invoked commands remain independent. Absence retains
 legacy per-fact behavior even at later versions. Assert no failed-batch facts and
-unchanged views, not only `then error`. Stage refuses v22 (STAGE-ESM-016) and
-atomic mode in admitted v23/v24 models (STAGE-ESM-043); keep the semantics as gap-fill.
+unchanged views, not only `then error`. Requires Stage 4.139.0 for v22 admission
+(older: -016); atomic mode stays STAGE-ESM-043. Keep as gap-fill.
 Read [atomic batches and source mappings](../cratis-screenplay-captures-and-reactions/references/atomic-batches-and-source-mappings.md)
 when choosing these boundaries or mapping an invoked identifier from `$eventSourceId`
 (or `$eventContext.eventSourceId`) instead of copying it into event payload.

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/realization-and-gap-fill.md

@@ -22,11 +22,19 @@ recovery behavior rather than assuming this handler supplies all-or-nothing sett
 rejected model renderable, and never claim a whole-application V5 from a subset. Choose the route
 with `cratis-screenplay-render-and-gap-fill`.
 
-Application-root `reaction batches atomic` also blocks Stage delivery: v22
-refuses STAGE-ESM-016; mode in admitted v23–v27 refuses STAGE-ESM-043. Preserve the
+Application-root `reaction batches atomic` also blocks Stage delivery with
+STAGE-ESM-043. Requires Stage 4.139.0 for v22 admission; older Stage reports -016. Preserve the
 per-occurrence/selected-branch batch boundary and independent invoked commands.
 Atomic appends do not prove redelivery deduplication or external exactly-once effects.
 
+Requires Stage 4.141.1 for independent event-reaction specifications with `given clock`;
+older executors refuse clocks beside reactions. This supplies `$context.occurred`
+through cascades, invocation arguments and refusal branches, not a scheduler.
+Clock/non-event triggers still refuse `STAGE-ESM-024`. Generated append/redelivery
+clock fixtures retain -024 and context-dependent generated reaction specs retain -011.
+Read [sandbox occurrence boundaries](../../cratis-stage-rendering-and-sandbox/references/sandbox-and-specrunner.md)
+when verifying reaction time in Stage rather than reference execution.
+
 ## Where the pieces go (hand-written)
 | Model element | Realization | Skill |
 |---|---|---|

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/SKILL.md

@@ -29,11 +29,11 @@ Language claims follow Screenplay `reactions.md`, `triggers.md`, `captures.md` a
 The compiler's ESM admission decides, not the slice type. Reactions, triggers and
 captures bind/reference-execute from v6; older compilers refuse them. Read toolchain
 `references/diagnostics.md` when diagnosing skew or false PLAY0285 cascades.
-- **The CLI and Stage** render supported event-triggered Automation, not
-  Translate/captures, non-event triggers or opaque bodies (`-024`). Role/authenticated `runs as`
-  and semantic `from` render; claim/opaque gates, mixed effects and unsupported mappings remain refused;
-  cascade specs remain `-011`. Keep refused scope as gap-fill. Full boundary and source
-  citations: `cratis-stage-rendering-and-sandbox` `references/admission.md`.
+- **Stage realization:** read `cratis-stage-rendering-and-sandbox` `references/admission.md`
+  before claiming rendering. Supported event-triggered Automation renders; captures,
+  Translate, clocks and opaque bodies remain gap-fill (`-024`).
+  Read [sandbox boundaries](../cratis-stage-rendering-and-sandbox/references/sandbox-and-specrunner.md)
+  when checking authored occurrence versus generated-spec limits; a clock fixture is not scheduling.
 
 Name the binding tool. For the automation test, loops and translation boundaries,
 read `cratis-screenplay-automations-and-translations`.
@@ -74,7 +74,7 @@ Start new models with application-root `reaction batches atomic`. One trigger's
 productions, or one selected refusal branch, append all-or-none; invoked commands stay
 separate. Legacy models without opt-in retain per-fact appends even at newer versions.
 Read [atomic batches and source mappings](references/atomic-batches-and-source-mappings.md)
-for batch failure assertions, PLAY0693, Stage STAGE-ESM-016/043 refusals and
+for batch failure assertions, PLAY0693, Stage atomic-mode refusals and
 `invokes` mappings from `$eventSourceId` / `$eventContext.eventSourceId`.
 
 ## Caller-less invokes and unprotected reads
@@ -104,9 +104,9 @@ binding, because its decision dependency cannot be protected. A reaction that on
 command's own reads. Eligible command reads protect under application-root
 `command reads protected` (ESM v25); legacy reads retain PLAY0271. Read command-surface
 [protected reads](../cratis-screenplay-command-surface/references/protected-reads.md)
-for admission and absence/conflict behavior. Stage admits v25 and, from 4.138.0, renders protected reads as Arc read protection (CLI 3.75.0 refuses them with STAGE-ESM-044).
-Semantic Host/executor support is separate; non-Error protected requirements refuse -045,
-including reaction-invoked commands.
+for admission and absence/conflict behavior. Requires Stage 4.138.0 to render
+protected reads; older bundles refuse -044. Semantic Host/executor non-Error
+protected requirements refuse -045.
 `where` over read paths out of scope, and `where` needs
 every operand to resolve from the trigger's declared scalar occurrence shape (listed in
 the input selection or not; nested paths and read aliases fail binding): keep the logic that uses the state in

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/atomic-batches-and-source-mappings.md

@@ -36,8 +36,8 @@ batch and unchanged read models with evaluator world/read-model assertions; earl
 accepted work can remain. `then no events` means accepted zero outcomes and cannot
 accompany `then error`. Do not invent a mixed success/error specification form.
 
-Stage refuses ESM v22 with STAGE-ESM-016. Even an admitted v23–v27 model carrying
-atomic mode is refused with STAGE-ESM-043 by renderer, Host and specification executor.
+Requires Stage 4.139.0 for ESM v22 admission; older Stage refuses STAGE-ESM-016.
+Atomic mode is still refused with STAGE-ESM-043 by renderer, Host and specification executor.
 Keep the declaration and report authorized gap-fill; do not promise a render date or
 strip atomicity to lower the version.
 

package/package/corpus/skills/cratis-screenplay-model-authoring/SKILL.md

@@ -26,6 +26,9 @@ Record open modeling questions as `question` notes in committed
 personal data in notes. Read [model notes](references/model-notes.md) when
 listing, recording or resolving questions: `list-model-notes`,
 `propose-model-notes`, `read-proposal view=notes`, refs and orphan review.
+Prefer dotted split-model targets; inspect `substitutions`, also for reanchor,
+and disclose broader owners. The reference covers typed `parts` targets from
+`open-workspace.applicationIdentity`.
 
 ## Choosing a strategy
 
@@ -45,8 +48,7 @@ Use the declared `screenplay` MCP server (for example `open-workspace`).
 Never ask the user which folder to use before trying `open-workspace` without
 arguments; do not invent a root. Read [MCP loop](references/mcp-loop.md) when connecting or switching roots;
 it owns fallback discovery, fixed-root limits and the initialization protocol.
-Discover `tools/list` schemas rather than relying on a remembered count.
-
+Discover `tools/list` schemas.
 
 Look first for the project's existing `.play` files: their folder is the model.
 New models go in `Source/` or `src/`, else root `Screenplay/`, never `.cratis/`
@@ -104,9 +106,8 @@ for handler views: `executableReady` means binding, not an implemented body.
 
 ## Compare models
 
-For a `main` comparison, pass a worktree `path` to `semantic-diff`, not two
-exports. Read [comparison sources](references/mcp-tools.md#semantic-revision-comparison)
-for paging and proposal review.
+Compare with `main` through `semantic-diff` worktree `path`, not two exports.
+Read [comparison sources](references/mcp-tools.md#semantic-revision-comparison) for paging.
 
 ## Make one coherent proposal
 
@@ -191,11 +192,10 @@ Commit `.screenplay/identities.json` with the model; only `apply` writes it. Nev
 
 ## Code attachments
 
-Code bodies and `file` constraints are opaque attachments. Screenplay never compiles or runs them.
-A screen's `file` realizes UI, not an attachment. Read
-[MCP code attachments](references/mcp-tools.md#code-attachments) when resolving
-paths or diagnosing `PLAY0430`-`PLAY0434`; `read-workspace`/`read-proposal`
-`view: "implementation-requirements"` hashes/maps are not behavioral evidence.
+Screenplay never compiles/runs opaque code attachments or `file` constraints;
+a screen's `file` realizes UI instead. Read [MCP code attachments](references/mcp-tools.md#code-attachments)
+for paths, PLAY0430–PLAY0434 and implementation-requirements views; hashes/maps
+are not behavioral evidence.
 
 ## Verify and report honestly
 
@@ -225,7 +225,7 @@ Record screen MCP transcripts in `.ai-work/`; render/runtime checks must use the
 same source, never an app that silently drops authored UI. Use the Screenplay-owned canonical
 corpus fixture path instead of copying available `.play` fixtures here.
 
-Never invent commands, parameters, syntax nodes or downstream capabilities.
+Never invent syntax or capabilities.
 
 ## Route near misses
 

package/package/corpus/skills/cratis-screenplay-model-authoring/references/mcp-tools.md

@@ -555,6 +555,15 @@ row is authored presence, not full coverage, causation or a passing specificatio
 Bare rejections cannot distinguish message-specific rules; syntax-only owners
 retain information-level readiness reasons. Never invent rules from opaque code.
 
+A query's SPEC004 denial matches either `when query <Query>` with `then denied`,
+or a read-only specification with no `when`, exactly one `then query <Query>`
+with `arguments` and no `result`, followed by `then denied`. That read-only denial
+does not meet the returned read model's SPEC006 assertion obligation; add a
+separate state, absence or query-result specification.
+Requires Screenplay 4.212.2 (`screenplay --version`) for this obligation matching;
+older servers miss the read-only denial for SPEC004 and count it for SPEC006.
+Upgrade before treating those rows as a coverage gate.
+
 `find-modeling-smells` asks information-level questions, never changes compilation
 or `--warnaserror`: SMELL001 generic event endings, SMELL002 generic command verbs,
 SMELL003 duplicate nonempty event shapes from different commands, SMELL004 event

package/package/corpus/skills/cratis-screenplay-model-authoring/references/model-notes.md

@@ -5,7 +5,6 @@
 
 ## Contents
 
-- Verified product sources
 - Choose the artifact
 - Anchors and independent state
 - List with bounded, pinned reads
@@ -14,25 +13,8 @@
 - Source proposals can orphan notes
 - Question gate is independent of compilation
 
-## Verified product sources
-
 Requires Screenplay 4.144.0 or later (`screenplay --version`) for model notes; the CLI-bundled MCP can be older.
 
-Sources in `Cratis/Screenplay`:
-
-| Contract | Path |
-| --- | --- |
-| Purpose, anchors, decisions and privacy | `Documentation/screenplay/model-notes.md` |
-| Filters, operations, review and orphan disclosure | `Documentation/screenplay/mcp/reference.md`; `Source/DotNET/Screenplay.Mcp/McpNotesSchemas.cs` |
-| Retained proposals, revision guards and notes review | `Source/DotNET/Screenplay.Mcp/McpWorkspaces.Notes.cs` |
-| Operation fields and resolution evidence | `Source/DotNET/Screenplay.Mcp/McpNotesOperations.cs` |
-| Sidecar bytes, absence and canonical revision | `Source/DotNET/Screenplay/Workspaces/ModelNotesStore.cs` |
-| Standalone question gate | `Source/DotNET/Tool/ModelOpenQuestions.cs`; `Documentation/screenplay/model-notes.md` |
-
-The source-edit and authoring guides remain useful for the ordinary proposal loop:
-`Documentation/screenplay/mcp/edit.md` and `authoring-tools.md`.
-The notes-specific arguments are in the reference and sources above.
-
 ## Choose the artifact
 
 Record an unresolved modeling choice as a `question` note on the affected element,
@@ -60,10 +42,45 @@ Notes live beside the model in committed `.screenplay/notes.json`. An anchor is
 do not derive them from names. Renames and moves keep notes without rewriting the
 sidecar. `lastAddress` is a display hint, never an anchor.
 
-For a syntax-only construct, select its current source handle or address and kind.
-The server substitutes its nearest identified slice, feature, module or application;
-inspect `substitutions` and name the particular construct in the note text.
-Document and authoring-key anchors are unsupported.
+Prefer dotted `{ address, kind }` targets for Module, Feature and Slice notes,
+including split models. Repeated Module/Feature headers at the same logical
+address merge across import placements and explicit headers; genuinely ambiguous
+leaf declarations still refuse. A folder is one application, not a separate note
+namespace per file.
+
+For a typed `{ kind, parts }` target, copy an address from `read-ast` or
+`read-workspace view=semantics`, or build it from names and the exact
+`applicationIdentity` returned by `open-workspace`. This argument template targets
+a Module (replace the Application key with that response's value):
+
+```json
+{
+  "kind": "Module",
+  "parts": [
+    { "kind": "Application", "key": "<applicationIdentity from open-workspace>" },
+    { "kind": "Module", "key": "Library" }
+  ]
+}
+```
+
+A typed address needs an existing catalog identity; it refuses when none exists.
+Use the construct's current source handle instead. A target without an identity
+lands on the nearest identified slice, feature, module or application. On an
+unbound model, even a Slice can lack an identity and fall back to Application;
+opening the workspace does not guarantee container identities.
+
+Always inspect `substitutions` for both `add` and `reanchor`, even when reanchor
+leaves the note unchanged. Each entry has the requested `target`, resolved
+`anchor`, resolved `address` and `reason`. If the note lands on a broader owner,
+say so to the user and name the intended construct in its text; reanchor once
+the intended owner has an identity. Never report the requested anchor as applied
+without checking the actual owner. Document and authoring-key anchors refuse.
+
+Requires Screenplay 4.212.0 (`screenplay --version`) for split dotted-target
+resolution, `open-workspace.applicationIdentity` and complete substitution
+reporting. Older servers can refuse split targets, omit that field or silently
+broaden the anchor; use a catalog address/current handle and inspect the notes
+review's actual anchor, or upgrade before relying on these responses.
 
 Notes do not change source, workspace/catalog/semantic revisions, executable
 model bytes or compiler verdicts. Their own `notesRevision` is `nrev1:` plus the
@@ -141,7 +158,8 @@ revisions just read and an actual declaration address before calling it.
 ```
 
 1. Retain `proposalId`, `afterNotesRevision`, server `addedNotes` IDs and inspect
-   `substitutions`. `changeCount: 0` means no source changes, not no notes change.
+   every `substitutions` entry for the actual owner, also for reanchor.
+   `changeCount: 0` means no source changes, not no notes change.
 2. Read `read-proposal` with `view: "notes"`: before/after notes revisions and
    paged `{ id, before, after }` pairs. On continuation pin **afterNotesRevision**
    as `expectedNotesRevision`, not the disk revision. Review the entire batch.

package/package/corpus/skills/cratis-screenplay-model-authoring/verification.json

@@ -37,6 +37,11 @@
     { "kind": "skill-contains", "value": "never hand-edit `generate` text", "file": "references/mcp-loop.md" },
     { "kind": "skill-contains", "value": "Record open modeling questions as `question` notes" },
     { "kind": "skill-contains", "value": "list-model-notes", "file": "references/model-notes.md" },
+    { "kind": "skill-contains", "value": "`applicationIdentity` returned by `open-workspace`", "file": "references/model-notes.md" },
+    { "kind": "skill-contains", "value": "Repeated Module/Feature headers", "file": "references/model-notes.md" },
+    { "kind": "skill-contains", "value": "Always inspect `substitutions` for both `add` and `reanchor`", "file": "references/model-notes.md" },
+    { "kind": "skill-contains", "value": "even a Slice can lack an identity", "file": "references/model-notes.md" },
+    { "kind": "skill-contains", "value": "older servers miss the read-only denial for SPEC004 and count it for SPEC006", "file": "references/mcp-tools.md" },
     { "kind": "skill-contains", "value": "`anchor`", "file": "references/model-notes.md" },
     { "kind": "skill-contains", "value": "`scope`", "file": "references/model-notes.md" },
     { "kind": "skill-contains", "value": "`state`", "file": "references/model-notes.md" },
@@ -163,11 +168,11 @@
     },
     {
       "kind": "skill-contains",
-      "value": "`view: \"implementation-requirements\"`"
+      "value": "implementation-requirements views"
     },
     {
       "kind": "skill-contains",
-      "value": "Screenplay never compiles or runs them"
+      "value": "Screenplay never compiles/runs opaque code attachments"
     },
     {
       "kind": "skill-contains",
@@ -180,7 +185,7 @@
     },
     {
       "kind": "skill-contains",
-      "value": "schemas rather than relying on a remembered count"
+      "value": "Discover `tools/list` schemas"
     },
     {
       "kind": "skill-contains",

package/package/corpus/skills/cratis-screenplay-projections/SKILL.md

@@ -28,11 +28,9 @@ source is the single flow model.
 
 ## Product sources
 
-Screenplay `Documentation/screenplay/projections/` (including `semantic-model.md`, `keys.md`
-and `variants.md`), `readmodels.md`, `diagnostics.md`, `commands.md`, `events.md` and
-`mcp/authoring-tools.md` describe the PDL parser, validator, diagnostics, semantic binder and
-reducer-body binding (`Semantics/`). Every example below compiles with the standalone compiler.
-Reverify before claiming another version behaves the same.
+Consult Screenplay `Documentation/screenplay/projections/` for grammar and semantics,
+`readmodels.md` for targets and `diagnostics.md` for errors. Verify examples with
+the standalone compiler before claiming another version behaves the same.
 
 **Chronicle decides what a projection means.**
 Screenplay owns the grammar; which instance an event affects, what a join may
@@ -81,11 +79,8 @@ Read [observer filters](../cratis-screenplay-toolchain/references/production-rou
 
 ## Projection-level directives
 
-`description "..."` (or a fenced text block) on the projection header (report-only `PLAY0270`; variants
-and nested blocks take none), `no automap`, `sequence <name>`, `file <path>`. `sequence` is a realization
-concern and does not bind to the executable model. A mapping target may end in a dynamic dictionary
-key, `count eventCountByType.$eventContext.eventType.id` (one entry per distinct value); only
-`$eventContext` resolves there, any other `$` text is a literal key with warning `PLAY0299`.
+Read [projection-level directives](references/pdl-grammar.md#projection-level-directives)
+when using descriptions, `sequence`, `file` or dynamic dictionary-key targets.
 
 ⚠️ **Do not write `key` on the projection.** It parses, but neither Chronicle nor
 the executable model routes any event by it, and it is not a default for the
@@ -148,14 +143,26 @@ subscribe to every event type: `all` inside `children` or `nested` behaves as
 `lastUpdatedAt`. The `every` block **inside** a `children` block does not accept
 it — it is already in a children context.
 
+## One event per level
+
+One event type is used once per projection level (`PLAY0801`): two `from` blocks
+cannot update two rows at that level, even with different keys. Combine mappings
+for one row; model a genuine second domain fact as its own event. Never invent
+events only to satisfy the read side. Joins use a separate set; each children,
+nested and variant block starts fresh sets. Read [event scope](references/pdl-grammar.md#event-scope)
+for grouped events, removals and compiler compatibility.
+
 ## Property mapping and AutoMap
 
 ⚠️ **AutoMap is on by default.** Matching property names are copied before your
 explicit mappings run, and explicit mappings win. Turn it off with `no automap` at
 **projection**, `every`/`all`, `join`, `children` or `nested` level — it
 **cannot** be toggled inside an individual `from` block. An `automap`/`no automap`
-under a joined event (`with …`) parses but Chronicle replaces it with the auto-map
-of the level the join sits in (`PLAY0380`).
+under a joined event (`with …`) decides auto-mapping for that event alone;
+without one, the joined event follows its level's auto-map.
+
+Requires Screenplay 4.212.4 (`screenplay --version`) for joined-event auto-map
+overrides in executable binding; older binders replace the setting with the level's.
 
 Mapping sources: a property path (`name`, `contactInfo.email`), a literal
 (`true`, `"Pending"`, `42`, `null`), `$eventSourceId`, and