@cratis/pi 7.33.0 → 7.34.1

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/core-rules-digest.md

@@ -0,0 +1,131 @@
+# Core rules digest
+
+## Contents
+
+- Two postures, never mixed in one pass
+- Elements and names
+- Causality
+- Roles
+- Field lineage
+- Open question versus decided failure
+- Offline-first lens
+- Anti-patterns to reject early
+- Structural shapes (candidates)
+- Quick self-check
+
+A one-page card of the element, naming and causality rules that every modeling phase
+relies on. It restates what the construct and phase skills own, in one place, so a session
+does not reopen five skills to check a name. When this card and a construct skill differ, the
+construct skill and the compiler win. Adapted from Martin Dilger and Nebulit GmbH's
+eventmodeling-core-rules (see `provenance.md`), translated to `.play` constructs.
+
+## Two postures, never mixed in one pass
+- **Modeling.** Discovery, slice design, authoring. Build the process as completely as you can.
+  Flag a naming slip or an incomplete precondition and move on; do not stall the step on it.
+- **Critic.** Review (`cratis-screenplay-model-review`). Apply every rule strictly and report every
+  violation; do not soften a finding because the model mostly works, and do not quietly add
+  missing structure on the model's behalf. Findings go in the report, not into the model.
+
+A modeling pass is not the place for a full audit, and a critic pass never edits.
+
+## Elements and names
+| Construct | Means | Name it | Reject |
+|---|---|---|---|
+| `event` | A business fact that already happened; immutable; a correction is a new event | Past tense, business language: `BerthReserved`, `PaymentAuthorized` | UI or machinery: `SidebarOpened`, `ApiCalled`, `ResponseReceived` |
+| `command` | Business intent from a caller; can be refused; on success produces one or more events | Imperative: `ReserveBerth`, `CancelSubscription` | Queries and UI actions: `LoadOrders`, `FetchData`, `OpenDialog` |
+| `readmodel` (+ `query`) | A projection of events shaped for one question; optional for any given command | A noun phrase for the data: `BerthAvailability`, `InvoiceList` | Implementation words: `...Projector`, `...Repository` |
+| `screen` | What a user sees and can act on | What a user would call it: `Dashboard`, `ReservationsPage` | `...Component`, `...View` internals |
+| `reaction` / `trigger` | An automated actor reacting to an event, a clock or an application signal | What it does: `BillingScheduler`, `BerthReleaser` | Handler or service names |
+| `persona` | A named role with Does / Reads / Cannot | A role in domain language | A generic "User" |
+
+An event holds captured or decided facts. A running total, an average or a status that is only
+recomputed from other events is a `readmodel`, not an event. A calculation that was actually
+decided at a point in time (a quoted price, an approved amount) is a fact and belongs in the
+event; say which it is.
+
+## Causality
+- Every locally produced event has a modeled producer that is reachable and motivated: whatever
+  the language lets produce it, for example a command or reaction `produces`, a capture, or an
+  event-target projection or reducer publishing an outbound public event. A foreign event
+  declared with `from` is produced by its owning system, not locally. The examples are not a
+  closed list; the construct skills and checklist F13 in `cratis-screenplay-model-review` decide.
+- Every command has a reachable, authorized origin, for example a screen or form action, or a
+  reaction to an event, a clock or an application trigger (not a closed list; F13 decides). A
+  command may have several origins and a screen several actions; judge each origin on its own.
+- A process starts at a screen or form action (a blank creation form counts), at a reaction to a
+  modeled event, a clock or application trigger, or at a capture appending outside facts; never at
+  an unmotivated command.
+- Two state changes in a row need something that triggers the second (a screen, or a reaction).
+- Connections read forward: what a later step needs from an earlier one is an event or a read
+  model that already exists. When a later event must change what an earlier view shows, the
+  projection of that view consumes the later event; do not draw a backward dependency.
+- Slices connect through events and views. Common transitions: StateView to StateChange,
+  StateChange to StateView, StateChange to Automation, Automation to StateChange, Automation to
+  StateView, Translate to StateView, Translate to Automation. Judge a connection by checklist
+  F13 in `cratis-screenplay-model-review`, not by this list.
+
+## Roles
+Every persona has a name in domain language, what it does, what it reads, and what it cannot do,
+and each "Cannot" is backed by an `authorize` gate and a `then denied` specification, or recorded
+as a gap. No command is attributed to a generic "User". A persona that never acts and never reads
+anything is decorative, not modeled. See `cratis-screenplay-discovery` `references/personas-and-causes.md`.
+
+## Field lineage
+Every command input, event property and read-model field has an origin (user input, caller
+context, a prior event property, a decided derivation, or an external payload) and, where it
+matters, a destination. A field with no origin is a gap to resolve, not a detail to fill in later.
+See `cratis-screenplay-slice-design` `references/field-lineage.md`.
+
+## Open question versus decided failure
+- **Open question.** Genuinely undecided. It goes in session state (`STATE.md`) or the review
+  report and stays open until someone answers it. Resolving means answering.
+- **Decided failure.** A rejection or error whose behavior is already decided ("payment fails,
+  refuse, no event"). Model it as a `specification` with `then error` or `then denied`. It is
+  permanent specified behavior, not a note waiting on an answer.
+
+A decided failure left as an open note looks unresolved when it is not. When counting
+completeness, only a genuinely unanswered question is a gap; a decided failure needs its
+specification.
+
+## Offline-first lens
+Model the business process as it would run without software first: who acts, what triggers each
+action, what information they need before acting. Question any step that exists only because of
+the system (a loading state, a cache refresh, a session check); it is not a business step and
+does not belong on the timeline. The anti-patterns below are what skipping this looks like.
+
+## Anti-patterns to reject early
+- **Data-loading commands.** `LoadOrders` is a query; model a `readmodel` and a `query`.
+- **UI-interaction events.** `ButtonClicked` is UI state; model it only if the business cares.
+- **Technical events.** `ApiCalled` describes machinery; find the business outcome underneath.
+- **Recomputed events.** A value that changes whenever its source data changes is a read-model field.
+
+## Structural shapes (candidates)
+Check these only when the model's wiring is visible; a count over the threshold is a prompt to
+think, not a finding.
+- **Screen with several commands** (the bed). Check each action is a distinct decision the user
+  already made on that screen. Screenplay allows several actions on a screen; the signal is a
+  single submit that quietly settles several things.
+- **Command with more than two events** (left chair). One business outcome that fans out, or a
+  command doing two jobs? Ask whether the events always happen together.
+- **Read model fed by more than three events** (right chair). One coherent picture, or a view
+  answering several questions? Ask whether the fields describe one thing.
+- **Slice with many more specifications than its neighbors** (shelf). Genuinely complex, or
+  quietly covering a neighbor's ground? Read what the extra specifications cover.
+
+Use plain descriptions in anything a business stakeholder reads; the shape names are shorthand
+for modelers. The full signal, consequence and fix per shape is in
+`cratis-screenplay-model-review` `references/anti-patterns.md`.
+
+## Quick self-check
+- [ ] Every event is past tense and a business fact.
+- [ ] Every command is imperative intent, not a data load.
+- [ ] Every read model is named for its data.
+- [ ] No event carries a value that is only recomputed from other events.
+- [ ] Every command has a reachable, authorized origin.
+- [ ] Every process starts at a screen or form action, a reaction, a clock or application trigger, or a capture.
+- [ ] No two state changes are chained without a trigger between them.
+- [ ] Every persona has a Cannot line backed by a gate and a denial specification, or a recorded gap.
+- [ ] Every decided failure is a specification; every open question is in session state.
+
+This is the fast pass; the full audit is `cratis-screenplay-model-review`
+`references/checklist.md`, and the closing quality checklist is in `references/phases.md`.

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/phases.md

@@ -127,7 +127,7 @@ phase, a decision important enough that a later reader could misread the model (
 - **Input**: the accepted identity.
 - **Carry-forward**: the admission result; render output and named gaps in `Customizations/`;
   non-renderable scope handed to a code agent with the model as contract, plus a fallback record
-  naming the blocking codes. Automations and translations are not rendered at the pinned Stage version, so the whole behavior is gap-fill. Three cases stay distinct: admission failure (nothing rendered); an
+  naming the blocking codes. Automations and translations are not rendered at the pinned Stage version (4.73.1), so the whole behavior is gap-fill (a reaction that produces and invokes keeps its one modeled form; `STAGE-ESM-037` is Stage's refusal, not a reason to split it). Three cases stay distinct: admission failure (nothing rendered); an
   existing generated base plus separately authorized gap-fill; fully hand-written delivery.
 - **Gate**: V5 sub-results, or a fallback entry per non-renderable scope. A customization never
   makes a rejected model renderable; no whole-application V5 from a subset.

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/provenance.md

@@ -11,7 +11,7 @@ sections, in this order:
    not empty, the skill `LICENSE` carries the "Third-party notices" section with the **complete**
    MIT text (copyright line, permission notice and disclaimer). Closely adapted material is
    attributed to the source it came from, not to a neighboring one.
-2. **Adapted closely (Martin Dilger and Nebulit GmbH, with agreement).** One row per item taken from Martin Dilger and Nebulit GmbH's
+2. **Adapted closely (Martin Dilger and Nebulit GmbH).** One row per item taken from Martin Dilger and Nebulit GmbH's
    agentic-engineer: source file, where it is used, how. Mark "idea; our wording kept" where only
    the idea was taken. The skill `LICENSE` carries the Nebulit notice.
 3. **Method lineage.** Public method sources (books, talks, standards), cited as sources of ideas.
@@ -34,11 +34,10 @@ full notice is in this skill's `LICENSE` ("Third-party notices").
 | same file, "Mid-Workflow Entry" | `SKILL.md`, `phases.md` "Resume mid-workflow" | Entry points table and identity recomputation added |
 | same file, "Final Output" and "Quality Checklist" | `phases.md` "Final output" and "Quality checklist (closing)" | Items rewritten around Screenplay verdicts, specifications and review |
 
-## 2. Adapted closely (Martin Dilger and Nebulit GmbH, with agreement)
+## 2. Adapted closely (Martin Dilger and Nebulit GmbH)
 
 Source: https://github.com/Nebulit-GmbH/agentic-engineer at commit `07b0f30648d663cb588d7e2c7aa031af9dfc21f2`,
-by Martin Dilger and Nebulit GmbH (https://nebulit.de). The repository carries no licence file; this material
-is adapted with the agreement of Martin Dilger and Nebulit GmbH.
+by Martin Dilger and Nebulit GmbH (https://nebulit.de), used with the explicit consent of Martin Dilger and Nebulit GmbH.
 
 | Source file | Used in | How |
 |---|---|---|
@@ -55,6 +54,28 @@ is adapted with the agreement of Martin Dilger and Nebulit GmbH.
 | `.claude/skills/update-prompt-status/SKILL.md` and kit "exactly two status updates per prompt" | `references/per-turn-protocol.md` step 7 | Idea; one start marker and one closing outcome per turn, our wording |
 | `.claude/skills/eventmodeling-core-rules/SKILL.md`: modeling and critic postures never mixed; a known refusal is a documented rule | `SKILL.md` "Modes", "Do not cut corners to save tokens or effort" | Idea; our wording kept |
 | `.claude/skills/connect/SKILL.md`: discover capabilities once per session | `SKILL.md` "Run protocol", `references/identity-and-edits.md` | Idea; our wording kept |
+| `.claude/skills/eventmodeling-core-rules/SKILL.md`: modes (modeling versus critic), element definitions and naming, causality, role catalog, field lineage, open question versus decided failure, offline-first, anti-patterns, structural shapes, quick self-check | `references/core-rules-digest.md` | Adapted closely as a one-page card translated to `.play` constructs. Not adopted: lanes, the single-issuer command rule, linked copies, the translation chain with a never-closing todo list, "read model never drives command validation" (Screenplay `reads` + `require`), the update-feeding-read-model procedure; "bed" is a candidate signal here, not an always-flag |
+
+## Not adopted from agentic-engineer (rejected, with reasons)
+
+Recorded once here for the whole method family, checked against the same commit
+(`07b0f30648d663cb588d7e2c7aa031af9dfc21f2`). A rejection stays rejected unless a released Screenplay or
+Chronicle capability removes its reason.
+
+| Source file or topic | Reason |
+|---|---|
+| `connect`, `learn-eventmodelers-api`, `load-slice`, `update-prompt-status`, and the 24 `references/api-fallback.md` files | Transport and credentials for the eventmodelers board. The Screenplay MCP server (`cratis screenplay mcp`) is the only transport; its tool catalog is `cratis-screenplay-model-authoring` `references/mcp-tools.md` and the root is `mcpServers.screenplay.root` in `.cratis/ai.json` |
+| `place-element`, `html-screen`, `storyboard-screen`, `discover-storyboard` HTML reconstruction | Board lanes, columns, cells and HTML or wireframe rendering. Screenplay screens are declarative and Stage renders them; a recreated page is never evidence |
+| `.agent-modeling-kit/README.md`, `lib/config.js`, `package.json`, `package-lock.json`, root `CLAUDE.md` and `README.md` | Board runtime, config walk, package stubs and an Emmett/Postgres/Express/Flyway template; Chronicle and Arc are the runtime here |
+| `.agent-modeling-kit/CLAUDE.md` and `AGENTS.md`: `<promise>`, progress file, board prompt queue, post-question-and-continue autonomy | Board-specific loop control. Our per-turn protocol and stop-or-assume keep the useful parts, and Cratis stops for consequential unknowns |
+| `eventmodeling-designing-event-models/references/examples.md` | The order example embeds a calculated `total` event field and a generic domain; Cratis examples are compiled |
+| Single issuer per command; a screen wired to more than one command always fails; "the bed" as an always-flag | Screenplay commands may have several origins and a screen several actions; the shape stays a candidate signal |
+| "A read model never drives command validation" | Screenplay commands declare `reads` and `require`; a decision uses stored state only through declared `reads` |
+| Compulsory todo list per automation; never-closing translation queue; every trigger is an event | Direct reactions, clock and application triggers and `capture` are supported; a translation holding pending work gets a terminal disposition |
+| "Default gracefully" and log-and-drop for missing external data | Defaults are never fabricated and failures are recorded facts |
+| Linked copies, backward-arrow handling, `session:` field mappings, `validate_model` batch calls | Board mechanics; caller identity is `context` and the model has no columns |
+| "No natural end" red flag, event-granularity tip, archival splits, `no computed fields` as an absolute | Long-lived identities are normal here, generic update events are defects, and decided calculations are facts |
+| Emmett decide/evolve structure, `processor.ts`, processor ids and locks, DLQ store, SQL operations, Flyway, Testcontainers, `routes.ts` | A different runtime; Chronicle and Arc own delivery, projection and transport |
 
 ## 3. Method lineage
 

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/reasoning-notes.md

@@ -14,8 +14,8 @@ PLAY0477 retained for events. Specifications accept `description`, not documenta
 put their longer reasoning on the owning slice. Projections/screens do not accept it.
 Canonical printing retains documentation on its owner. It is report-only (PLAY0270),
 absent from executable bytes and `modelRevision`; edits change source identity
-(`verdicts-and-modes.md`). Neither description nor documentation is rendered as code
-(Stage#178): model the rule first, never treat prose as enforcement.
+(`verdicts-and-modes.md`). Neither description nor documentation reaches rendered code except as XML doc
+comments (Stage#178 closed): model the rule first, never treat prose as enforcement.
 
 Cover, briefly and only where real:
 1. Scope: the business process and the identities its streams are keyed by.

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/verdicts-and-modes.md

@@ -18,7 +18,7 @@ defines what each result means and how to report it. Do not copy version facts h
 
 | Result | Evidence | Does NOT prove |
 |---|---|---|
-| V1 authorable | folder-mode validate with warnings as errors. The standalone compiler includes imports in folder and file mode; the pinned `cratis` CLI (v3.28.2) file validation still ignores imports (cli#244, probed), so folder mode is the cross-tool check | semantics, binding, specs |
+| V1 authorable | folder-mode validate with warnings as errors. The standalone compiler includes imports in folder and file mode; `cratis` CLI 3.28.2 file validation ignored imports (cli#244, probed); since 3.28.4 (PR #258) it compiles the file with its imports, but folder mode stays the recommended cross-tool check | semantics, binding, specs |
 | V2 executable diagnostics | the executable model reports no diagnostics for the scope | that any spec runs or passes |
 | V3 binding-ready | the model binds to the executable semantic model | that any spec runs or passes |
 | V4 reference specs run | the reference execution route only: engine, and per `.play` specification passed / failed / unsupported / cancelled | rendering, generated code, build or target tests |

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/vocabulary-map.md

@@ -18,10 +18,10 @@ speaks in them; never model board mechanics (lanes, node ids, positions).
 | Chapter / workflow | `feature` | feature folder | vertical slices |
 | Slice | `slice` (one behaviour, not one artifact of each kind) | vertical slice folder | vertical slices |
 | Scenario (Given/When/Then) | `specification` | generated spec class `when_<spec_name>` (Debug) or hand-written C# specs | `cratis-screenplay-specifications`; C# spec skills |
-| Storyline (ordered beats) | a **family** of specifications sharing example data, each one transition (no storyline syntax at the verified Screenplay v4.66.0) | several spec classes | specifications |
+| Storyline (ordered beats) | a **family** of specifications sharing example data, each one transition (no storyline syntax at Screenplay 4.139.0) | several spec classes | specifications |
 | Field validation | concept `validate` (every use) / command `validate`, `require` | `ConceptValidator<T>` / `CommandValidator<T>` | command validation |
 | Role permission ("Cannot") | `policy` + `authorize` + `then denied` spec; ownership via `claim ... matches subject` | `[Authorize(Policy)]`, generated policies | authorization |
-| Precondition on stream state | `reads` + `require` as stated intent, not enforced at the verified Screenplay v4.66.0 (target: Arc `[ProtectedDecision]` + `DecisionRead<T>`, or Chronicle DCB; APIs available to gap-fill in Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0, not emitted protection) | decision over a guarded read | command validation |
+| Precondition on stream state | `reads` + `require` as stated intent, not enforced at Screenplay 4.139.0 (target: Arc `[ProtectedDecision]` + `DecisionRead<T>`, or Chronicle DCB; APIs available to gap-fill in the Arc and Chronicle the Stage 4.73.1 scaffold pins, not emitted protection) | decision over a guarded read | command validation |
 | Generated id (`derived:uuid4()`) | `generated` (authorable, not executable) | id supplied before `Handle()` | commands |
 | External system / outbound call | `Translate` slice (inbound); `system`/`operation` (authorable, not executable) or Automation (outbound) | `ICommandOperation` / reactor | operations, reactors |
 | HTML mockup | `screen` Level 1 + board (`visualize-model`) | default Scene composition | ui composition |
@@ -42,8 +42,9 @@ Screenplay meaning, and when you meet the older usage, translate it and say so.
 - Screenplay **`reaction`**: the construct that models it (`when` trigger, optional `where`,
   `invokes` a command or `produces` events).
 - Chronicle **reactor**: C# observer, usually for side effects; it does not by itself define
-  business decisions. A Screenplay reaction is authorable and bindable, but Stage `v4.24.2` renders no Automation or
-  Translate slice: the reactor and command are gap-fill code.
+  business decisions. A Screenplay reaction is authorable and bindable, but Stage 4.73.1 renders no Automation or
+  Translate slice: the reactor and command are gap-fill code. A reaction that both produces events and invokes commands is
+  refused by Stage (`STAGE-ESM-037`); Arc 22.72.0 and later run one reactor returning events and commands (the Arc the Stage scaffold pins needs a proven override), so keep the reaction whole.
 
 ## Scenario vs specification
 "Scenario" is the Event Modeling example and the scenario *types* `cratis-screenplay-scenario-coverage` uses for

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

@@ -35,7 +35,8 @@ source is the single flow model.
 The update follows `commands.md`, `events.md` and `mcp/authoring-tools.md` at
 that main commit (after v4.52.0); no PDL example changes in this update.
 
-Checked against the Screenplay repository at tag `v4.31.0` (commit `355dffb`):
+Originally checked against the Screenplay repository at tag `v4.31.0` (commit `355dffb`; the
+projection grammar was re-read at v4.139.0 for headers and dynamic keys):
 `Documentation/screenplay/projections/` (including `semantic-model.md`, `keys.md`
 and `variants.md`), `readmodels.md`, `diagnostics.md` and decisions 0001 and 0002.
 Every example below compiles with that version's compiler. Reverify before
@@ -88,8 +89,11 @@ Read [observer filters](../cratis-screenplay-toolchain/references/production-rou
 
 ## Projection-level directives
 
-`no automap`, `sequence <name>`, `file <path>`. `sequence` is a realization
-concern and does not bind to the executable model.
+`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`.
 
 ⚠️ **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
@@ -328,8 +332,8 @@ What the executable model does with it (ESM v3):
 - The body is an opaque attachment identified by a content hash, never compiled
   or run by Screenplay. The reference runner cannot compute reducer state, so a
   specification that reads a reducer-built read model reports unsupported and
-  never passes. A target must supply the transition. Stage 4.24.0 admits only pure reducer bodies
-(Roslyn allowlist); an impure body is gap-fill code, and the model stays the contract.
+  never passes. A target must supply the transition. Stage (4.73.1) admits only pure reducer bodies
+(Roslyn allowlist, `STAGE-ESM-019`/`-022`); an impure body is gap-fill code, and the model stays the contract.
 
 **Prefer a projection where one will do.** A reducer is code, and code is the part
 of a document a reader cannot check at a glance.

package/package/corpus/skills/cratis-screenplay-projections/references/pdl-grammar.md

@@ -10,7 +10,9 @@
 
 Checked against `Documentation/screenplay/projections/{grammar,semantic-model,keys,variants}.md`
 and `Source/DotNET/Screenplay/Parsing/ProjectionParser.cs` at Screenplay tag
-`v4.31.0` (commit `355dffb`).
+`v4.31.0` (commit `355dffb`); the header `description` and the dynamic dictionary-key target
+(`Target = ["@"] Path [DynamicKey]`, `DynamicKey = "." "$eventContext" "." EventContextPath`) were added in
+later releases and re-read at v4.139.0.
 
 The grammar says what **parses**. It does not say what an event does at runtime:
 Chronicle's lowering decides that (Screenplay decision 0001), and the
@@ -143,7 +145,7 @@ LiteralKeyword  = "literal", " ", Literal ;   (* parsed at the Expr level *)
 | `PLAY0190` | A reducer rule body opens with an unknown word |
 | `PLAY0191` | A read model is built by more than one projection or reducer |
 | `PLAY0192` | A read model is declared more than once |
-| `PLAY0295`–`PLAY0299` | An `$eventContext` path the event-context catalog does not have |
+| `PLAY0295`–`PLAY0299` | An `$eventContext` path the event-context catalog does not have; `PLAY0299` also warns when a dynamic dictionary key uses a `$` source other than `$eventContext` |
 | `PLAY0380` | Chronicle drops part of a construct: `all` below the top level, or `automap` on a joined event |
 | `PLAY0381` | A projection-level `key` routes no event |
 | `PLAY0382`–`PLAY0385` | Variant errors: no `enters on`, shared mapping missing on a variant, duplicate variant name, entering event claimed twice |

package/package/corpus/skills/cratis-screenplay-read-surface/LICENSE

@@ -1,2 +1,9 @@
 Copyright (c) Cratis. All rights reserved.
 Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+Third-party notices
+
+This skill adapts material from agentic-engineer by Martin Dilger and Nebulit GmbH
+(https://github.com/Nebulit-GmbH/agentic-engineer, commit 07b0f30648d663cb588d7e2c7aa031af9dfc21f2;
+https://nebulit.de), used with the explicit consent of Martin Dilger and Nebulit GmbH. The adapted
+material remains credited to Martin Dilger and Nebulit GmbH. See references/provenance.md.

package/package/corpus/skills/cratis-screenplay-read-surface/SKILL.md

@@ -150,7 +150,8 @@ pushing; without the marker a query is one-shot, which is the default and what
 most reads are. The marker qualifies only *how* the result arrives, so it composes
 with `[]`, `optional`, `by`, `filter`, `authorize` and a `performer`, and a screen binds
 to a live query exactly as it binds to a one-shot one. The delivery itself is the
-target runtime's: the executable model does not bind observable queries.
+target runtime's: the executable model binds `observable` queries (delivery `live`) that
+have no `filter`, `scoped to` or `performer`.
 
 Paging, sorting and change-set delivery for queries are accepted as Screenplay
 decision 0010 but **not in the language yet**. Do not invent syntax for them.
@@ -173,13 +174,14 @@ on the header line is a declaration error, not a shorthand.
 
 ### What runs
 
-In the Screenplay 4.66.0 executable model, only the keyed snapshot shape binds:
-`=> <ReadModel> optional` with one caller-supplied `by` argument and no `observable`,
-`filter`, `scoped to` or `performer`. Anything else, including `=> <ReadModel>`
-and `=> <ReadModel>[]`, reports `PLAY0268`. Its `authorize` gate runs before
+In the Screenplay 4.139.0 executable model (admitted since 4.105.0) these bind: a keyed
+`=> <ReadModel> optional` with one caller-supplied `by` argument, an unfiltered list
+`=> <ReadModel>[]`, a list narrowed by one caller-supplied `by` key, and the `observable`
+form of each. `filter`, `scoped to`, `performer`, `by ... from` and composite `by` report
+`PLAY0268`, as does a single non-optional `=> <ReadModel>`. Its `authorize` gate runs before
 the lookup, ANDed with module and feature gates; a denied caller gets
 `Unauthorized`. Pin that with a `given caller` fixture and `then denied` (see
-`cratis-screenplay-specifications`). Model the richer query shapes when the
+`cratis-screenplay-specifications`). Model `filter`, `scoped to` and `performer` shapes when the
 application needs them; just do not claim the reference runner exercised them.
 
 ## `screen` — three levels
@@ -192,8 +194,10 @@ commands and screens it names are declared elsewhere.
 ```screenplay excerpt
 screen InvoiceList
   data InvoiceListReadModel[] via query ListInvoices
-  action RegisterInvoice
-    navigate to RegisterInvoiceScreen
+  section registerInvoiceInput
+    title "Register invoice"
+    on click
+      navigate to RegisterInvoiceScreen
   action CancelInvoice
 ```
 
@@ -307,8 +311,12 @@ binding failures are errors.
 Read `references/versions.md` in `cratis-screenplay-toolchain` when choosing a tool, checking versions, or assessing executable and renderable subsets. Where a construct sits in the
 method: `cratis-screenplay-modeling-lifecycle` and `cratis-screenplay-slice-design`.
 
+Read [screen patterns](references/screen-patterns.md) when deciding whether a screen is an input, status or error-state screen and which `data` and `action` lines it needs.
+
 ## Route near misses
 
+Attribution and licences: `references/provenance.md`.
+
 - How events fill the read model: `cratis-screenplay-projections`.
 - Layouts, templates, forms, component bindings, toolbars, outlets, contributions, packages and themes: `cratis-screenplay-ui-composition`.
 - Asserting query results: `cratis-screenplay-specifications`.

package/package/corpus/skills/cratis-screenplay-read-surface/references/provenance.md

@@ -0,0 +1,21 @@
+# Provenance
+
+## Adapted closely (Martin Dilger and Nebulit GmbH)
+
+Source: https://github.com/Nebulit-GmbH/agentic-engineer at commit `07b0f30648d663cb588d7e2c7aa031af9dfc21f2`,
+by Martin Dilger and Nebulit GmbH (https://nebulit.de), used with the explicit consent of Martin Dilger
+and Nebulit GmbH. The notice is in this skill's `LICENSE`.
+
+| Source file | Used in | How |
+|---|---|---|
+| `.claude/skills/eventmodeling-storyboarding-events/SKILL.md`, "Common Patterns": input screen, status screen, error state | `references/screen-patterns.md` | Adapted closely and mapped to `screen`, `data`, `action` and `specification` (`then error`); one screen per column, lanes, actor perspective rows and mandatory rendering not adopted; the example is compiled with Screenplay 4.139.0 |
+
+Not adopted: HTML screen reconstruction and wireframe sketching (`html-screen`, `storyboard-screen`), which are board
+mechanics; Screenplay screens are declarative and Stage renders them.
+
+## Other lineage
+
+- Screenplay language documentation and the released tool, pinned in `cratis-screenplay-toolchain`
+  `references/versions.md`: the `readmodel`, `query` and `screen` constructs.
+- Event Modeling (Adam Dymitruk) and Martin Dilger, *Understanding Eventsourcing*: the screen as the point where
+  a person reads a view and decides.

package/package/corpus/skills/cratis-screenplay-read-surface/references/screen-patterns.md

@@ -0,0 +1,130 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Screen patterns
+
+## Contents
+
+- Input screen
+- Status screen
+- Error state
+- A complete example
+- What a screen pattern is not
+
+Three screen shapes recur in almost every model. Decide which one a screen is before declaring
+its `data` and `action` lines; the shape tells you which read model and which command it needs.
+Adapted from Martin Dilger and Nebulit GmbH's storyboarding patterns (see `provenance.md`),
+translated to `screen`, `data`, `action` and `specification`.
+
+## Input screen
+
+The person fills in a form, submits, and a fact is recorded.
+
+- The form fields are the command's inputs; a field the person should not supply (their own
+  identity, the tenant) comes from context, not the form (`cratis-screenplay-command-surface`
+  `references/context.md`).
+- The submit is `action <Command>` on the screen. The screen needs no read model when it is a
+  blank creation form; when it shows current state before the person acts (the berth's
+  availability, the amount still owed), it also needs `data <ReadModel> via query <Query>`.
+- After success the person lands somewhere meaningful: `navigate to <Screen>` on the action, or the
+  list that now contains the new item. Where the person goes next is part of the story, so name it.
+
+## Status screen
+
+The person looks at where something stands and decides what to do next.
+
+- `data <ReadModel> via query <Query> [by <param>]` supplies the current state, built from the
+  events so far. Every field shown has a source in that read model.
+- The available actions depend on state. A static `action` line is always offered; an action that
+  must differ by state is a guarded action (`references/guarded-actions.md`), never prose.
+- A status screen with no incoming view is a gap; only a blank creation form is exempt.
+
+## Error state
+
+The person acts and the command is refused: no event is recorded, a message is shown, and the
+person can retry or choose another action.
+
+- The refusal is not drawn on the screen. It is behavior, pinned by a `specification` with
+  `then error` (a rule) or `then denied` (a gate), and by the command's `validate` and `require`
+  messages, which are the text the person sees.
+- Name the way out. After a refusal the person can correct the input and submit again, or take a
+  different action on the same screen. If neither is possible, the slice has a dead end; record
+  it as an open question.
+- Do not add a screen per error. One screen with its refusal specifications covers the states.
+
+## A complete example
+
+A berth booking form that shows availability (input screen over a view), a booking list that
+shows state (status screen), and the refusal pinned by a specification (error state).
+
+```screenplay
+domain Harbourlight.Berths
+
+concept BookingId : Uuid
+concept BerthName : String
+  validate
+    not empty  message "A berth needs a name"
+
+policy IsAuthenticated
+  require authenticated
+
+module Berths
+  description "Berth bookings for one marina"
+  authorize IsAuthenticated
+  feature Bookings
+    slice StateChange BookBerth
+      description "A skipper books a berth"
+      command BookBerth
+        bookingId BookingId identifier
+        berth BerthName
+        produces BerthBooked
+          for bookingId
+          berth = berth
+      event BerthBooked
+        berth BerthName
+      screen BookBerthScreen
+        title "Book a berth"
+        action BookBerth
+          navigate to OpenBookingsScreen
+      specification BookingABerth
+        given caller
+          authenticated
+        when BookBerth
+          bookingId = "3b0c7a14-5d2e-4f61-8a9b-0c1d2e3f4a01"
+          berth = "Pier 2, berth 14"
+        then BerthBooked
+          for "3b0c7a14-5d2e-4f61-8a9b-0c1d2e3f4a01"
+          berth = "Pier 2, berth 14"
+      specification BookingWithoutABerthNameIsRefused
+        given caller
+          authenticated
+        when BookBerth
+          bookingId = "3b0c7a14-5d2e-4f61-8a9b-0c1d2e3f4a02"
+          berth = ""
+        then error "A berth needs a name"
+
+    slice StateView OpenBookings
+      description "The harbour office lists the bookings that hold a berth"
+      readmodel OpenBooking
+        bookingId BookingId
+        berth BerthName
+      query ListOpenBookings => OpenBooking[]
+      projection OpenBookings => OpenBooking
+        from BerthBooked
+          bookingId = $eventSourceId
+          berth = berth
+      screen OpenBookingsScreen
+        title "Open bookings"
+        data OpenBooking[] via query ListOpenBookings
+        action BookBerth
+```
+
+## What a screen pattern is not
+
+- Not a column or a lane: a screen is a declaration in a slice, not a position on a timeline.
+  One screen per step is not a rule; a screen hosts every action the person can reasonably take
+  there, and an action may be reachable from several screens.
+- Not a mockup: a drawn page is never evidence for the model, and a Level 1 screen is a data and
+  action contract that a renderer or a person fills in (`cratis-screenplay-ui-composition`).
+- Not mandatory to render: a screen that stays design-only is still a contract for lineage and
+  review.

package/package/corpus/skills/cratis-screenplay-read-surface/verification.json

@@ -16,7 +16,7 @@
     { "kind": "skill-contains", "value": "The tenant is the default and stays unstated" },
     { "kind": "skill-contains", "value": "belongs on a `from` parameter, never on a `filter`" },
     { "kind": "skill-contains", "value": "warnings, not errors" },
-    { "kind": "skill-contains", "value": "the executable model does not bind observable queries" },
+    { "kind": "skill-contains", "value": "the executable model binds `observable` queries" },
     { "kind": "skill-contains", "value": "A compiling query is not evidence that access control works" },
     { "kind": "skill-contains", "value": "decision 0010 but **not in the language yet**" }
   ]

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/LICENSE

@@ -5,5 +5,5 @@ Third-party notices
 
 This skill adapts material from agentic-engineer by Martin Dilger and Nebulit GmbH
 (https://github.com/Nebulit-GmbH/agentic-engineer, commit 07b0f30648d663cb588d7e2c7aa031af9dfc21f2;
-https://nebulit.de), used with the agreement of Martin Dilger and Nebulit GmbH. That repository
-carries no licence file; the adapted material remains credited to Martin Dilger and Nebulit GmbH.
+https://nebulit.de), used with the explicit consent of Martin Dilger and Nebulit GmbH. The adapted
+material remains credited to Martin Dilger and Nebulit GmbH.