@cratis/pi 2.23.1 → 2.24.0

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

@@ -0,0 +1,215 @@
+---
+name: cratis-screenplay-projections
+description: Build a Cratis Screenplay read model with the Projection Declaration Language (PDL) — keys, `from`/`every`/`all`, property mapping and AutoMap, joins, children and nested objects, removal, arithmetic counters, and the reducer escape hatch. Use when declaring or changing how events become read-model state in a `.play` model, or when a projection does not populate what was expected. Use `cratis-chronicle-projection` instead for hand-written C# Chronicle projections.
+license: MIT
+---
+
+# Projections — the Screenplay PDL
+
+A `projection` folds events into a read model. Its body is the **Projection
+Declaration Language**, an embedded sub-grammar with its own parser — not free
+text. This is half of every event model, and the half most easily got wrong.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | PDL parser, validator, diagnostics |
+
+Read from the Screenplay repository at tag `v4.12.1` (commit `122eee8`), against
+`Documentation/screenplay/projections/` and
+`Source/DotNET/Screenplay/Parsing/ProjectionParser.cs`. Reverify before claiming
+another version behaves the same.
+
+## The shape
+
+```screenplay
+readmodel InvoiceDetailsReadModel
+  invoiceNumber InvoiceNumber
+  status        InvoiceStatus
+  lastUpdatedAt DateTime
+
+projection InvoiceDetails => InvoiceDetailsReadModel
+  key invoiceId
+  every
+    lastUpdatedAt = $eventContext.occurred
+    exclude children
+  from InvoiceRegistered key invoiceId
+    status = "draft"
+  from InvoiceSent
+    status = "sent"
+  remove with InvoiceCancelled
+```
+
+**The arrow always points the same way.** A read model never declares what builds
+it; the projection or reducer points at it with `=>`. **Exactly one thing may
+build a read model** — two builders is error `PLAY0191`: *a projection or a
+reducer builds it, and only one of them*. A slice may still declare several
+projections, each building a **different** read model.
+
+## Projection-level directives
+
+`key <expr>`, `no automap`, `sequence <name>`, `file <path>`. A second `key` is
+error `PLAY0059`.
+
+## Keys — eight ways, and the default
+
+| Form | Example |
+| --- | --- |
+| Projection-level | `key invoiceId` |
+| From-level inline | `from InvoiceRegistered key invoiceId` |
+| From-level block | indented `key invoiceId` inside the `from` |
+| Per event, several events | `from A key idA, B key idB, C` |
+| Composite | `key OrderKey` with indented `<property> = <expr>` parts |
+| Literal (constant) | `key literal "site-stats"` — every event updates the **same** instance |
+| Children identity | `children lines identified by lineNumber` |
+| **Default** | **the event source id** — `from X` ≡ `from X key $eventSourceId` |
+
+A second key on one `from` is error `PLAY0060`. A template expression in a
+composite key is error `PLAY0073`; an empty composite key is `PLAY0074`.
+
+## `from` vs `every` vs `all`
+
+| Block | Fires for | Use for |
+| --- | --- | --- |
+| `from <Event>` | that event type only | the actual mapping work |
+| `every` | **only** the types this projection subscribes to via `from` | common fields across your own events |
+| `all` | **every event type in the system** | system-wide audit logs, global counters |
+
+⚠️ `all` and `every` are not synonyms, and confusing them is the classic PDL
+mistake. `every` is scoped to your `from` blocks; `all` is not scoped at all.
+
+`every` accepts `exclude children`, so child events do not bump the parent's
+`lastUpdatedAt`. The `every` block **inside** a `children` block does not accept
+it — it is already in a children context.
+
+## 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 … with`, `children` or `nested` level — it
+**cannot** be toggled inside an individual `from` block.
+
+Mapping sources: a property path (`name`, `contactInfo.email`), a literal
+(`true`, `"Pending"`, `42`, `null`), a template (`` `${first} ${last}` ``),
+`$eventSourceId`, `$eventContext.<occurred|sequenceNumber|correlationId|eventSourceId>`,
+and `$causedBy.<subject|name|userName>` (an unknown one is an error naming all
+three).
+
+`clear <property>` removes a value and is equivalent to `= null`; prefer `clear`.
+It takes a dotted path (`clear Owner.Note`) and escapes reserved names
+(`clear @with`).
+
+## Arithmetic
+
+| Line | Effect |
+| --- | --- |
+| `count <prop>` | +1, expressing *counting occurrences* |
+| `increment <prop>` | +1, expressing *modifying state* |
+| `decrement <prop>` | −1 |
+| `add <prop> by <expr>` | += expression |
+| `subtract <prop> by <expr>` | −= expression |
+
+`count` and `increment` behave identically; the difference is intent. The target
+must be numeric.
+
+## Joins
+
+```screenplay
+join Customer on CustomerId
+  with CustomerCreated
+    no automap
+    CustomerName = name
+  with CustomerUpdated
+    CustomerName = name
+```
+
+`join <property> on <key>` (error `PLAY0063` otherwise), then one or more
+`with <EventType>` blocks (error `PLAY0064` otherwise), each able to toggle
+`automap` / `no automap` for itself. Joins work at projection level and inside
+`children`. A join cannot declare its own key or trigger removal — that is
+`remove via join on`.
+
+## Children and nested
+
+```screenplay
+children lineItems identified by lineNumber
+  from InvoiceLineItemAdded key lineNumber
+    parent invoiceId
+    quantity = quantity
+  remove with InvoiceLineItemRemoved key lineNumber
+    parent invoiceId
+
+nested billingContact
+  from BillingContactSet
+    email = email
+  clear with BillingContactCleared
+```
+
+- **`children <collection> identified by <expr>`** — a collection with its own
+  lifecycle. `parent <expr>` ties a child to its parent instance; it accepts an
+  event property, `$eventContext.eventSourceId`, or a nested path. Children nest
+  arbitrarily deep and may contain `join`, `remove`, `nested` and `every`.
+- **`nested <property>`** — a single nullable object. It **must** contain at least
+  one `from` (error `PLAY0067`), and `clear with <Event>` drops the whole object
+  back to null. To clear one property instead, use a `clear <property>` mapping.
+
+## Removal
+
+```screenplay
+remove with InvoiceCancelled key invoiceId
+remove via join on CustomerAccountClosed
+```
+
+`remove with <Event> [key <expr>]` removes the instance the event identifies.
+`remove via join on <Event> [key <expr>]` removes instances reached through a
+join. Inside `children`, both take an indented `parent <expr>` — and **only**
+`parent`; anything else is error `PLAY0069`. Several removal conditions may
+coexist.
+
+## When PDL is not enough — the reducer
+
+```screenplay
+reducer Balance => AccountBalance
+  on AmountDeposited
+    csharp
+      ```
+      return context.State is null
+          ? new(context.Event.amount, 1)
+          : context.State with { balance = context.State.balance + context.Event.amount };
+      ```
+  on AmountWithdrawn
+    file Reducers/Withdrawn.cs
+```
+
+Reach for a reducer only when the next state depends on the current one — a
+running balance, a state machine. `context.State` is **null for the first event**
+and is the only nullable member; `Event`, `Key`, `Tenant`, `Occurred`,
+`SequenceNumber` and `IsFirst` are always there.
+
+**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. A reducer binds to
+`UnsupportedSemanticSyntax` in ESM v1, so it never reaches the reference runtime.
+
+Read [pdl-grammar.md](references/pdl-grammar.md) for the complete EBNF, every
+diagnostic code, and the full worked examples.
+
+## Verify
+
+- [ ] `screenplay <model> --warnaserror` reports zero errors and zero warnings.
+- [ ] Each read model has **exactly one** builder.
+- [ ] Every read-model property traces back to an event that carries it.
+- [ ] `every` was intended where `every` is written — not `all`.
+- [ ] AutoMap's default-on behavior is intended, or `no automap` is declared at the
+      right level.
+- [ ] Every `children` block's `from` declares `parent`.
+- [ ] Every `nested` block contains at least one `from`.
+- [ ] A reducer is present only because a projection genuinely could not express it.
+
+## Route near misses
+
+- Deciding which read models exist at all: `cratis-screenplay-event-modeling`.
+- Read-model shape, queries and screens: `cratis-screenplay-read-surface`.
+- Specifying projection behavior: `cratis-screenplay-specifications`.
+- Hand-written C# Chronicle projections: `cratis-chronicle-projection`.
+- Hand-written C# Chronicle reducers: `cratis-chronicle-reducer`.

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

@@ -0,0 +1,239 @@
+# PDL — complete grammar and diagnostics
+
+Verified against `Documentation/screenplay/projections/grammar.md` and
+`Source/DotNET/Screenplay/Parsing/ProjectionParser.cs` at commit `122eee8`.
+
+Two places below are deliberately **looser than the published EBNF**, because the
+parser accepts more than that EBNF describes and both forms were confirmed by
+compiling them:
+
+- `EveryBlock` accepts a bare `automap` as well as `no automap`. The published
+  grammar lists only `no automap`, but `from-every.md` shows `automap` in an
+  example and `ParseMappingBlock` handles both.
+- The braces on a composite key are **optional**. The published grammar writes
+  them as required; a composite key with and without them both compile clean.
+
+## Grammar
+
+```ebnf
+Projection      = "projection", Ident, [ "=>", TypeRef ], NL,
+                  [ INDENT, { ProjDirective | Block }, DEDENT ] ;
+
+ProjDirective   = "no", "automap", NL
+                | "sequence", Ident, NL
+                | "file", FilePath, NL
+                | KeyDecl
+                | CompositeKeyDecl ;
+
+Block           = EveryBlock | FromAllBlock | FromEventBlock | JoinBlock
+                | ChildrenBlock | NestedBlock | RemoveWithBlock | RemoveWithJoinBlock ;
+
+EveryBlock      = "every", NL, INDENT,
+                    [ "automap" | "no", "automap", NL ], { MappingLine },
+                    [ "exclude", "children", NL ], DEDENT ;
+
+FromAllBlock    = "all", NL,
+                  [ INDENT, [ "automap" | "no", "automap", NL ], { MappingLine }, DEDENT ] ;
+
+FromEventBlock  = "from", EventSpec, { ",", EventSpec }, NL,
+                  [ INDENT, [ ParentDecl ], { MappingLine | KeyDecl | CompositeKeyDecl }, DEDENT ] ;
+EventSpec       = TypeRef, [ "key", Expr ] ;
+
+JoinBlock       = "join", Ident, "on", Ident, NL, INDENT, { WithEventBlock }, DEDENT ;
+WithEventBlock  = "with", TypeRef, NL,
+                  [ INDENT, [ "automap" | "no", "automap", NL ], { MappingLine }, DEDENT ] ;
+
+ChildrenBlock   = "children", Ident, "identified", "by", Expr, NL,
+                  INDENT, [ "no", "automap", NL ], { ChildBlock }, DEDENT ;
+ChildBlock      = ChildEveryBlock | FromEventBlock | JoinBlock | RemoveWithBlock
+                | RemoveWithJoinBlock | ChildrenBlock | NestedBlock | ClearWithBlock ;
+ChildEveryBlock = "every", NL, INDENT, [ "no", "automap", NL ], { MappingLine }, DEDENT ;
+
+NestedBlock     = "nested", Ident, NL,
+                  INDENT, [ "automap" | "no", "automap", NL ],
+                  { ProjDirective | Block | NestedBlock | ClearWithBlock }, DEDENT ;
+ClearWithBlock  = "clear", "with", TypeRef, NL ;
+
+RemoveWithBlock = "remove", "with", TypeRef, [ "key", Expr ], NL,
+                  [ INDENT, [ ParentDecl ], DEDENT ] ;
+RemoveWithJoinBlock = "remove", "via", "join", "on", TypeRef, [ "key", Expr ], NL ;
+
+KeyDecl         = "key", Expr, NL ;
+CompositeKeyDecl= "key", TypeRef, [ "{" ], NL,
+                  INDENT, KeyPart, { NL, KeyPart }, DEDENT, [ "}", NL ] ;
+KeyPart         = Ident, "=", Expr ;
+
+MappingLine     = Assignment | ClearLine | IncLine | DecLine | CountLine | AddLine | SubLine ;
+Assignment      = Ident, "=", Expr, NL ;
+ClearLine       = "clear",     Path, NL ;
+IncLine         = "increment", Ident, NL ;
+DecLine         = "decrement", Ident, NL ;
+CountLine       = "count",     Ident, NL ;
+AddLine         = "add",       Ident, "by", Expr, NL ;
+SubLine         = "subtract",  Ident, "by", Expr, NL ;
+
+Expr            = Template | Literal | DollarExpr | Path ;
+DollarExpr      = "$eventSourceId" | "$eventContext", ".", Ident | "$causedBy", ".", Ident ;
+Template        = "`", { TemplateChar | "${", Expr, "}" }, "`" ;
+Literal         = BoolLiteral | StringLiteral | NumberLiteral | NullLiteral ;
+LiteralKeyword  = "literal", " ", Literal ;   (* parsed at the Expr level *)
+```
+
+## Parser regexes
+
+| Construct | Regex |
+| --- | --- |
+| Projection header | `^projection\s+(@?[\w.]+)\s*(?:=>\s*([\w.]+))?$` |
+| Event spec | `^(@?[\w.]+)(?:\s+key\s+(.+))?$` |
+| Join | `^join\s+(@?[\w.]+)\s+on\s+(@?[\w.]+)$` |
+| With | `^with\s+(@?[\w.]+)$` |
+| Children | `^children\s+(@?[\w.]+)\s+identified\s+by\s+(.+)$` |
+| Nested | `^nested\s+(@?[\w.]+)$` |
+| Remove with | `^remove\s+with\s+(@?[\w.]+)(?:\s+key\s+(.+))?$` |
+| Remove via join | `^remove\s+via\s+join\s+on\s+(@?[\w.]+)(?:\s+key\s+(.+))?$` |
+| Counters | `^(increment\|decrement\|count\|clear)\s+(@?[$\w.]+)$` |
+| Arithmetic | `^(add\|subtract)\s+(@?[$\w.]+)\s+by\s+(.+)$` |
+| Assignment | `^(@?[$\w.@]+)\s*=(?!=\|>)\s*(.+)$` |
+
+## Diagnostics
+
+| Code | Meaning |
+| --- | --- |
+| `PLAY0054` | A projection document's top-level line does not open a `projection` |
+| `PLAY0055` | A projection document declares no projection |
+| `PLAY0056` | A `projection` line is not `projection <Name> [=> <ReadModel>]` |
+| `PLAY0057` | A projection declares no directives, so it builds nothing |
+| `PLAY0058` | A projection body line opens with an unknown word |
+| `PLAY0059` | A projection declares more than one key |
+| `PLAY0060` | A `from` block declares more than one key |
+| `PLAY0061` | A `from` line names no event |
+| `PLAY0062` | An event reference is not a readable name |
+| `PLAY0063` | A `join` line is not `join <property> on <key>` |
+| `PLAY0064` | A join block holds a line that is not `with <EventType>` |
+| `PLAY0065` | A `children` line is malformed |
+| `PLAY0066` | A `nested` line is not `nested <property>` |
+| `PLAY0067` | A nested block reads from no event, so nothing ever fills it |
+| `PLAY0068` | A `remove` line is neither `remove with` nor `remove via join on` |
+| `PLAY0069` | A remove block holds a line other than `parent` |
+| `PLAY0070` | A `clear` line is not `clear with <EventType>` |
+| `PLAY0071` | `clear with` is written where there is nothing to clear |
+| `PLAY0072` | A composite key part is not `<property> = <expression>` |
+| `PLAY0073` | A composite key part is a template expression, which a key cannot be |
+| `PLAY0074` | A composite key declares no parts |
+| `PLAY0075` | A projection mapping line is unreadable |
+| `PLAY0186` | A `readmodel` line is not `readmodel <Name>` |
+| `PLAY0187` | A `reducer` line is not `reducer <Name> => <ReadModel>` |
+| `PLAY0188` | A reducer body line is not `on <EventType>` |
+| `PLAY0189` | A reducer declares no rules |
+| `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 |
+
+## Worked examples
+
+### Composite key with event context
+
+```screenplay
+projection LineItems => LineItemReadModel
+  from LineItemAdded
+    key LineItemKey
+      OrderId        = orderId
+      LineNumber     = lineNumber
+      SequenceNumber = $eventContext.sequenceNumber
+      CreatedBy      = $causedBy.subject
+    Product = productName
+```
+
+### Global counter with a literal key
+
+```screenplay
+projection SiteStats => SiteStatsReadModel
+  from UserLoggedIn key literal "site-stats"
+    count TotalLogins
+    lastLogin = $eventContext.occurred
+```
+
+Every `UserLoggedIn` updates the same instance, whatever its event source.
+
+### System-wide audit with `all` alongside `from`
+
+```screenplay
+projection ActivityFeed => ActivityFeedModel
+  all
+    count totalSystemEvents
+    lastActivity = $eventContext.occurred
+  from UserRegistered
+    recentUsers = name
+```
+
+`totalSystemEvents` counts **every** event in the system; `recentUsers` only fills
+on `UserRegistered`.
+
+### Children with a join and scoped removal
+
+```screenplay
+projection Group => GroupReadModel
+  from GroupCreated
+    Name = name
+  children members identified by userId
+    from UserAddedToGroup key userId
+      parent groupId
+      Role = role
+    join User on UserId
+      with UserCreated
+        no automap
+        UserName = name
+    remove with UserRemovedFromGroup key userId
+      parent groupId
+```
+
+### `every` that ignores child activity
+
+```screenplay
+projection Group => GroupReadModel
+  every
+    LastActivity = $eventContext.occurred
+    exclude children
+  from GroupCreated
+    Name = name
+  children members identified by userId
+    from UserAdded
+      Name = userName
+```
+
+Group-level events bump `LastActivity`; member events do not.
+
+### Nested nullable object
+
+```screenplay
+projection Slice => SliceReadModel
+  from SliceCreated
+    Name = name
+  nested command
+    from CommandSetForSlice
+      Name   = commandName
+      Schema = schema
+    from CommandRenamed
+      Name = newName
+    clear with CommandClearedForSlice
+```
+
+`command` is null until `CommandSetForSlice`, updated in place by
+`CommandRenamed`, and set back to null by `CommandClearedForSlice`.
+
+### Several projections in one slice
+
+```screenplay
+slice StateView CustomerPortalReport
+  query GetPortalReport => PortalReportReadModel
+    by customerId CustomerId
+  projection PortalReport => PortalReportReadModel
+    from PortalInvitationSent
+      invitedAt = $eventContext.occurred
+  projection RevokedPortalToken => RevokedPortalTokenReadModel
+    from PortalTokenRevoked
+      revokedAt = $eventContext.occurred
+```
+
+Two read models, one behavior. Splitting them across two slices would say the
+system has two behaviors where it has one.

package/package/corpus/skills/cratis-screenplay-projections/verification.json

@@ -0,0 +1,11 @@
+{
+  "skill": "cratis-screenplay-projections",
+  "input": "Build a read model from events with the Projection Declaration Language.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "AutoMap is on by default" },
+    { "kind": "skill-contains", "value": "PLAY0191" },
+    { "kind": "skill-contains", "value": "every event type in the system" },
+    { "kind": "skill-contains", "value": "references/pdl-grammar.md" }
+  ]
+}

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

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

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

@@ -0,0 +1,188 @@
+---
+name: cratis-screenplay-read-surface
+description: Declare the read side of a Cratis Screenplay `.play` model — the `readmodel` shape, `query` with `by`/`filter`/`scoped to`/`observable`/`performer`, and `screen` at its three levels of detail, plus how a bare name resolves across slices. Use when adding or changing a query, a read-model shape, or a screen in a `.play` model, or when deciding what a caller may narrow a result by. Do not use for how events fill the read model, and do not use for layouts, templates or forms.
+license: MIT
+---
+
+# The Screenplay read surface
+
+What the system can be asked, and what a user sees. The `readmodel` declares the
+shape, the `query` is the entry point, and the `screen` renders it.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | Parser, validator, diagnostics |
+
+Read from the Screenplay repository at tag `v4.12.1` (commit `122eee8`), against
+`Documentation/screenplay/{queries,readmodels,screens}.md` and
+`Source/DotNET/Screenplay/Parsing/`. Reverify before claiming another version
+behaves the same.
+
+## `readmodel` — shape only
+
+```screenplay
+readmodel AccountBalance
+  description "What the account is worth right now"
+  balance   Decimal
+  movements Int
+  note      String?
+```
+
+A read model declares what it **is** — nothing about what builds it. Whatever
+builds it points at it with `=>`, and **exactly one thing may**: two builders is
+error `PLAY0191`. See `cratis-screenplay-projections` for the builder side.
+
+## `query`
+
+```screenplay
+query ListInvoices => InvoiceListReadModel[]
+  description "Every invoice the caller may see, narrowed by status and customer"
+  filter status     InvoiceStatus?
+  filter customerId CustomerId?
+  filter tenantId   TenantId from $context.tenant
+  authorize IsAuthenticated
+```
+
+Return-type forms after `=>`: `ReadModel`, `ReadModel?`, `ReadModel[]`, each
+optionally prefixed `observable`.
+
+### `by` vs `filter` — and why it is a security decision
+
+| Clause | Meaning |
+| --- | --- |
+| `by` | the **identifying** parameter — the query returns the instance it identifies |
+| `filter` | an optional parameter narrowing the result set; usually typed `?` |
+| `from <source>` | fills the parameter **from the context** instead of from the caller |
+
+⚠️ **Anything the caller must not be able to choose — the tenant, the caller's own
+subject — belongs on a `from` parameter, never on a `filter` the UI supplies.**
+Any mapping source works as a `from` source, so `$context.`, `$env.` and constants
+are all available.
+
+### `scoped to`
+
+```screenplay
+query Mine => Timesheet[]
+  scoped to identity
+query Everyones => Timesheet[]
+  scoped to global
+```
+
+⚠️ **The tenant is the default and stays unstated.** A query is scoped to the
+tenant it runs for unless it says otherwise, so `scoped to global` is how a query
+*opts out* and reaches past the tenant. As the documentation puts it: *"Making the
+narrow case the default means the dangerous case is the one you have to write
+down, rather than the one you get by forgetting."*
+
+**The scope is a name, not a closed set.** `identity` and `global` are the two the
+language documents, but the grammar accepts any name — what scopes exist follows
+the identity model of whatever runs the document. A query declares at most one.
+
+Treat every `scoped to global` in a review as a question to answer, not a detail.
+
+### `observable`
+
+`=> observable OverdueInvoicesReadModel[]` is a live read that keeps 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 `[]`,
+`?`, `by`, `filter`, `authorize` and a `performer`. A screen binds to a live query
+exactly as it binds to a one-shot one and gets updates for free.
+
+### `performer`
+
+A query is **complete without a performer** — it is realization metadata, not a
+precondition. It takes a `file` reference or an inline code block, and is the
+query's counterpart to a command's `handler`. `csharp` and `sql` are the two that
+make sense here; the parser accepts any registered inline language
+(`csharp`, `typescript`, `react`, `html`, `sql` are built in) and does not
+reject a nonsensical one, so the choice is yours to get right.
+
+## `screen` — three levels
+
+**Level 1 — intent.** Data and actions; the tool generates the component.
+
+```screenplay
+screen InvoiceList
+  data InvoiceListReadModel[] via query ListInvoices
+  action RegisterInvoice
+    navigate to RegisterInvoiceScreen
+  action CancelInvoice
+```
+
+**Level 2 — structure.** Named sections, tables and summaries filling a template's
+slots.
+
+```screenplay
+screen InvoiceDetails
+  template MasterDetail
+    sidebar
+      data InvoiceDetailsReadModel via query GetInvoice by invoiceId
+      summary InvoiceDetailsReadModel
+        field invoiceNumber label "Invoice #"
+      section actions
+        action CancelInvoice
+    main
+      section lineItems
+        table lineItems
+          column lineNumber label "#"
+          column quantity   label "Qty"
+          on row-click navigate to InvoiceLineDetail by lineNumber
+```
+
+**Level 3 — inline code.** The surrounding Screenplay context supplies the typed
+data contract; the inline block receives it as `Props`. Languages: `react`,
+`typescript`, `html`, `csharp`.
+
+Constructs: `title`, `data … via query … [by <param>]`, `action <Command>` with
+`label` and `navigate to <Screen> [by <param>]`, `section <name>`,
+`table <target>` with `column <property> [label]` and
+`on row-click navigate to <Screen> [by <param>]`, `summary <ReadModel>` with
+`field <property> label`, and `template <Name>` with slot bodies.
+
+## How a bare name resolves
+
+**Inside out:** the slice, then the enclosing feature, then the module, then the
+document. The innermost match wins.
+
+That rule exists because a generated document cannot make every name unique — one
+real application declares 76 queries under 37 distinct names, with `All` appearing
+21 times. Two sibling slices can each declare `All`, and each screen gets its own.
+
+Reach across slices by qualifying with **any trailing part** of the scope:
+
+```screenplay
+screen OverviewScreen
+  data QueueReadModel[]     via query Queue.All
+  data DeviationReadModel[] via query Preparation.Deviations.All
+```
+
+Use the shortest unambiguous form. If a bare name matches two declarations equally
+well, the compiler **warns and names the candidates** rather than picking one:
+
+```text
+Ambiguous query 'All' - it matches 2 declarations equally well
+(Invoicing.Preparation.Queue, Invoicing.Preparation.Deviations); qualify it to say which
+```
+
+⚠️ Unresolved and ambiguous references are **warnings, not errors**, because a
+name may resolve to something outside the document. Run with `--warnaserror` or a
+screen can navigate to a screen that does not exist and the build stays green.
+
+## Verify
+
+- [ ] `screenplay <model> --warnaserror` reports zero errors and zero warnings.
+- [ ] Every value the caller must not choose is a `from` parameter, not a `filter`.
+- [ ] Every `scoped to global` is deliberate and defensible.
+- [ ] `observable` is present exactly where the caller should see changes without
+      asking again.
+- [ ] Each read model has exactly one builder and every field traces to an event.
+- [ ] No screen reference is left ambiguous or unresolved.
+
+## Route near misses
+
+- How events fill the read model: `cratis-screenplay-projections`.
+- Layouts, templates, forms, contributions, themes: `cratis-screenplay-ui-composition`.
+- Asserting query results: `cratis-screenplay-specifications`.
+- Deciding which read models exist: `cratis-screenplay-event-modeling`.

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

@@ -0,0 +1,10 @@
+{
+  "skill": "cratis-screenplay-read-surface",
+  "input": "Declare a Screenplay query and the screen that binds to it.",
+  "fixtures": [],
+  "assertions": [
+    { "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" }
+  ]
+}

package/package/corpus/skills/cratis-screenplay-specifications/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.