@cratis/pi 7.98.0 → 7.100.0

package/package/corpus/skills/cratis-components-toolbar/SKILL.md

@@ -204,6 +204,10 @@ consumer, ordered ascending by `order` (default `0`). `useToolbarSlot(slotName)`
 returns the current content for a custom consumer. `ToolbarContext` also accepts
 a `slotName`.
 
+In a Screenplay model the same idea is authored, not coded: a `feature` or `module` adds buttons to the `toolbar` slot of every
+screen beneath it and links each to a command of the feature (see `cratis-screenplay-ui-composition`, "Feature and module
+toolbars"). Use the slot components above only when writing the React application by hand.
+
 ## Props
 
 ### `Toolbar`

package/package/corpus/skills/cratis-screenplay-command-surface/references/constraints-produces-concurrency.md

@@ -1,5 +1,12 @@
 # Constraints, produces mappings and concurrency
 
+## Contents
+
+- `constraint` — uniqueness at append time
+- Refuse a command on an unknown id
+- `concurrency`
+- `produces`
+
 This reference holds the detailed forms for append-time `constraint` uniqueness, `produces` mapping sources and conditions, and the `concurrency` block.
 
 ## `constraint` — uniqueness at append time
@@ -39,6 +46,48 @@ belongs in `validate`/`require`. Use a constraint when two concurrent appends mu
 not both win — a `validate` rule cannot do that. Stage renders only single-text-property and
 `unique event` constraints (`STAGE-ESM-014`; `cratis-stage-rendering-and-sandbox` `references/admission.md`).
 
+## Refuse a command on an unknown id
+
+Without a guard, a command naming an id that has no state is accepted and appends its event. Guard
+existence with a protected read: after authorization and property rules, and before any `require`
+or mapping runs, it rejects with `<ReadModel> '<key>' does not exist.` The preamble goes in the root document, the read model's key property is
+named `id` (`STAGE-ESM-044` otherwise, found by `cratis render --check`), and the view needs a
+`remove with` event. Complete model; it validates with `--executable`, renders with `--check`,
+and the specification passes in `screenplay test`:
+
+```screenplay
+domain Tasks
+command reads protected
+module Work
+  feature Closing
+    slice StateView TaskStatus
+      event TaskOpened
+        title String
+      event TaskDeleted
+      readmodel Task
+        id String key
+        title String
+      projection TaskProjection => Task
+        from TaskOpened
+        remove with TaskDeleted
+    slice StateChange CloseTask
+      event TaskClosed
+        reason String
+      command CloseTask
+        taskId String identifier
+        reads Task by taskId
+        produces TaskClosed
+          for taskId
+          reason = "done"
+      specification ClosingAnUnknownTask
+        when CloseTask
+          taskId = "missing"
+        then error "Task 'missing' does not exist."
+```
+
+Admission, races and refused read shapes: [protected reads](protected-reads.md). A `validate` rule or a
+screen guard cannot check existence, and a `unique` constraint only guards duplicates.
+
 ## `concurrency`
 
 Five dimensions, each at most once, and at most one `concurrency` block per

package/package/corpus/skills/cratis-screenplay-command-surface/references/enum-numbers.md

@@ -34,6 +34,8 @@ module Invoicing
 
 ## Source rules
 
+- Member names are lowercase identifiers: `hourly`, not `Hourly`. A capitalised member is
+  PLAY0009 ("expected an identifier"); rename it, and use the same name in specifications.
 - Number **all members or none**; there is no implicit continuation after a pin.
 - Numbers are unique whole int32 values, from -2147483648 through 2147483647.
   Gaps and negative numbers are allowed; aliases and flags semantics are not.

package/package/corpus/skills/cratis-screenplay-command-surface/references/validate-rules.md

@@ -1,5 +1,13 @@
 # Validation rule forms
 
+## Contents
+
+- Rule vocabulary
+- `require` message
+- Date and DateTime comparisons
+- `not empty` means non-blank text
+- Rules whose logic is code
+
 ## Rule vocabulary
 
 | Rule | Example |
@@ -24,6 +32,16 @@ modifier generates check digits but does not add validation. Check digits catch
 typos, not forgery. For generated-concept proof statuses, deterministic regex
 limits and PLAY0688 repairs, read [generated rules](generated-values-and-responses.md#generated-concept-rules-esm-v20).
 
+## `require` message
+
+The `message` of a whole-command `require` goes on the next, indented line, not on the `require` line:
+
+```screenplay excerpt
+validate
+  require to >= from
+    message "The end must not be before the start"
+```
+
 ## Date and DateTime comparisons
 
 Requires Screenplay 4.199.0 (ESM v26; `screenplay --version`); older binders refuse

package/package/corpus/skills/cratis-screenplay-event-modeling/references/slice-type-rules.md

@@ -10,3 +10,7 @@ automation: model it as one `StateChange` slice with several `produces` blocks.
 
 **Translation is workflow-specific anti-corruption.** Generic infrastructure every
 workflow needs (event persistence, message transport) is not a `Translate` slice.
+
+**Events have no optional properties for the `cratis` target.** An event property
+marked `optional` validates, but `cratis render --check` refuses it (`STAGE-ESM-005`).
+Make it required, or leave it out of the event; whether the detail is a separate fact is a modeling decision.

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

@@ -170,6 +170,15 @@ open, read, propose, review, apply, reopen loop; the syntax and rules are in
 5. Switching a module from inherit to override copies the application's items; retarget each copy to the module's own
    features first or the proposal is refused.
 
+### Feature and module toolbars
+
+A feature (or module) toolbar is a `ScreenToolbarSyntax` in the `toolbars` member of its `FeatureSyntax` (or `ModuleSyntax`);
+`syntax-schema` for `FeatureSyntax` lists `toolbars`. `add` a `ScreenToolbarSyntax` with `name`, `items` and `buttons` to the
+feature, and `replace` a `ToolbarButtonSyntax` or `ToolbarItemSyntax` to set its `confirm` text; `remove` takes a button away.
+Read the proposal's diagnostics: a warning says an `item ... action` names a command no slice of that feature (or module)
+declares. The syntax, the `confirm` rule and when to prefer the feature toolbar are in `cratis-screenplay-ui-composition`
+(`references/application-shell.md`, "Feature and module toolbars"; Screenplay 4.238.0 or later).
+
 ### The profile's shell
 
 `ui-profiles` (Screenplay 4.201.0 or later) reads each `ui profile`'s root template, shell options, appearance, new screens default and

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

@@ -64,6 +64,9 @@ of executing the newly selected command.
 
 ## Guard boundaries
 
+A guard hides an offer; it does not make a command on an unknown id fail. Existence is refused in the
+command: [refuse a command on an unknown id](../../cratis-screenplay-command-surface/references/constraints-produces-concurrency.md#refuse-a-command-on-an-unknown-id).
+
 Conditions compare item paths to literals, not other paths, route/screen state,
 `$context` or `$env`. Equality/inequality, numeric ordering, string contains/starts
 with and grouped and/or are supported; and binds tighter than or. Collections

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

@@ -27,6 +27,17 @@ selection is:
    candidates and requires exactly one. An admitted list query here is a collection
    query without context-derived `by`, filters or scope.
 
+Two `*Id` properties (`orderId`, `customerId`) with only a list query are ambiguous
+(PLAY0268). Add one keyed query, whose `by` names the identity:
+
+```screenplay excerpt
+readmodel Order
+  orderId String
+  customerId String
+query OrderById => Order optional
+  by orderId String
+```
+
 A projection-only/queryless read model needs an explicit `key`: a lone `*Id`
 property alone does not infer identity. Never use the command's `identifier`
 modifier on a read model.

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

@@ -37,6 +37,8 @@ The person looks at where something stands and decides what to do next.
   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 list the screen renders is `query <Name> => observable <ReadModel>[]`. A snapshot list renders too, but
+  it is read once and does not follow later events; `observable` keeps the table current after a command.
 - A status screen with no incoming view is a gap; only a blank creation form is exempt.
 
 ## Error state

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

@@ -34,6 +34,24 @@ Requires Screenplay 4.145.0 or later (`screenplay --version`) for `run-specifica
 
 Read [source notes](references/source-notes.md) for the retained inline-fact and action-syntax evidence; run the changed examples at the standalone pin.
 
+## State every property
+
+A `when` command and each `then` event list **every** property, including `optional`
+ones, with a concrete value; omitting one is PLAY0524. Only a read-model property may be `null` (PLAY0350).
+This model fails with PLAY0524 on both `when` and `then` until `note = "none"` is added:
+
+```screenplay excerpt
+event TaskOpened
+  note String optional
+specification Opening
+  when OpenTask
+    taskId = "t1"
+    title = "Write"
+  then TaskOpened
+    for "t1"
+    title = "Write"
+```
+
 ## Reference execution — what actually runs
 
 Screenplay's reference runner executes specifications against an immutable

package/package/corpus/skills/cratis-screenplay-specifications/references/generated-fixtures.md

@@ -25,6 +25,8 @@ a seed is not a portable fixture.
 
 ## When not to
 
+A fixture still states every command and event property with a concrete value, optional ones included (PLAY0524); a generated value does not excuse an omitted field.
+
 Pins do not prove randomness, authorization, idempotency, storage freshness or
 secret safety. Client-minted IDs stay inputs; gapless invoice numbering needs an
 allocator, not a random fixture or pattern. Check digits catch typos, not forgery;

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

@@ -218,6 +218,8 @@ unresolved questions: the standalone tool has `--open-questions fail`; `cratis s
 does through `--open-questions report|fail`. It is separate from compilation and `--warnaserror`.
 Requires Cratis CLI 3.60.0 or later (`cratis --version`) for that option; older CLIs lack it.
 
+Read [fast path](references/fast-path.md) for the ordered requirements-to-running-app checklist (validate, `render --check`, render, build, run).
+
 ## Route near misses
 
 Read [references/neighbouring-skills.md](references/neighbouring-skills.md) when the work is modeling phases, MCP editing, construct depth, rendering or running systems.

package/package/corpus/skills/cratis-screenplay-toolchain/references/fast-path.md

@@ -0,0 +1,24 @@
+# Fast path: requirements to a running Cratis app
+
+Run these in order and stop at the first failure; each step catches what the one before cannot.
+`<root>` is the model folder, `<dir>` the render destination.
+
+1. **Model** the requirements (`cratis-screenplay-modeling-lifecycle`). Enum members lowercase,
+   specifications state every property, no optional event property, list queries `observable`
+   (`references/traps.md` 46-47).
+2. **Validate:** `cratis screenplay validate --executable --warnings-as-errors <root>`. Pass: exit 0 and no error.
+   It binds the model but does not run the renderer's admission.
+3. **Admit:** `cratis render <root> --target cratis --name <App> --destination <dir> --check`.
+   It plans without writing; a refusal (for example `STAGE-ESM-005`, an optional event
+   property) lists every blocker at once. Fix and repeat until it reports no error diagnostic. Exit 6 on a
+   clean plan means only that changes are pending; nothing is published.
+4. **Render:** the same command without `--check`. Publication succeeded when it exits 0 and the receipt shows
+   `refused: 0` and `recoveryPending: false`.
+5. **Build:** `dotnet build <dir>/<App>.csproj` (Debug).
+6. **Services:** `docker compose up -d` in `<dir>` (Chronicle and MongoDB).
+7. **Backend:** `dotnet run --project <App>.csproj` in `<dir>`.
+8. **Frontend:** in `<dir>`, `yarn` then `yarn dev` (npm: `npm install`, `npm run dev`); open the URL Vite
+   prints. It proxies API calls to the backend.
+
+The rendered `README.md` repeats steps 6-8 for the pinned scaffold. Re-render and gap-fill rules:
+`cratis-screenplay-render-and-gap-fill`.

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

@@ -18,7 +18,7 @@ Compiler syntax: `cheat-sheet.md`. Negative capability claims depend on the tool
 14. AutoMap is on by default: same-named event properties fill read-model properties silently (scoped: case-insensitive, same type only; flat-bound: exact name, no type check, so a type mismatch invalidates the model). Use `no automap` for control.
 15. `given readmodel` bypasses the projection; prove a projection with `given` events + `when append`/command + `then readmodel`/`then query`.
 16. PLAY0285/0286/0287 are static spec checks: do not edit expectations blindly. An older bundled compiler can report PLAY0285 falsely on reaction cascades; confirm with the standalone tool before changing a `then`.
-17. `null` in specs only for optional read-model properties (PLAY0350); omit the property or record a gap; whether an optional detail is really a separate fact is a review question, not the fix for this code.
+17. `null` in specs only for optional read-model properties (PLAY0350). A `when` command or `then` event states every property with a concrete value, optional ones too (PLAY0524); whether an optional detail is really a separate fact is a review question, not the fix for this code.
 18. `then` events are exhaustive and ordered (use `then events in any order` for order only). From ESM v6 they include reaction cascades; after `when append` they list only what followed the append.
 19. Under `command reads protected`, omitted `by` uses the command identifier; absent identifier is PLAY0782. Eligible reads bind v25; legacy reads and `concurrency` retain PLAY0271. Combining reads/concurrency under opt-in is PLAY0783.
 20. Declare each event once, in its producing slice; renaming a persisted event needs `id "OldName"`; renaming a constraint discards its index.
@@ -70,3 +70,5 @@ Traps 39 to 44 are tool traps.
 43. `modelRevision` is canonical semantic (line positions and descriptions do not change it; a file move only if it changes logical placement or application identity) and, without `identities.json`, changes with the root folder name; it is not comparable with a render's `semanticRevision`. Source identity for verdicts is the commit plus the digest from the source-identity helper (`cratis-screenplay-modeling-lifecycle` `references/verdicts-and-modes.md` "Source identity").
 44. `cratis render` neither builds nor tests; `--name` is required for plain source; `.cratis-render/` is control state and is never staged; rendered apps pin their own Arc and Chronicle versions (`[ProtectedDecision]` is available to gap-fill, not automatically emitted). `cratis` file mode versus folder mode (trap 6) and a stale `cratis` on `PATH` (`which -a cratis`) both silently change what a verdict means.
 45. A reducer cannot be re-keyed: its instances follow the event-source id, so a query `by` another identity type warns PLAY0690 (`--warnaserror` fails it; editors only show it when the host supplies native findings). Aggregate by a payload value with a projection keyed on each `from`, or a join: projections [reducer identity](../../cratis-screenplay-projections/references/reducer-identity.md).
+46. Enum members are lowercase identifiers (`hourly`, not `Hourly`; PLAY0009). A specification states every property of the command and events, optional ones too (PLAY0524). A read model with two `*Id` properties needs one keyed query, `query OrderById => Order optional` with `by orderId String` (PLAY0268 otherwise). A `require` message goes on the next indented line (trap 38). Screen list queries are `observable`.
+47. Cratis events have no optional properties (STAGE-ESM-005), and `validate --executable` does not catch it: run `cratis render <folder> --target cratis --name <App> --destination <dir> --check` right after validate, since it runs the renderer's admission and writes nothing.

package/package/corpus/skills/cratis-screenplay-ui-composition/SKILL.md

@@ -225,7 +225,8 @@ module Sales
 ```
 
 Read [references/application-shell.md](references/application-shell.md) before writing any of it: the inherit/extend/override
-choice, item target and slot, the module-only target rule (`PLAY0750`), buttons, blueprint ranges, sample data, MCP editing
+choice, item target and slot, the module-only target rule (`PLAY0750`), buttons, feature and module toolbars (`toolbar` in a
+`feature` or `module`, `confirm`), blueprint ranges, sample data, MCP editing
 and the review checklist. `contribute to Navigation` stays the flat contribution; a new application uses regions.
 
 ## Interactions — what a click does
@@ -297,7 +298,7 @@ Localized text lives in companion `.strings` files and is referenced unquoted as
 - [ ] No `file` reference is doing work the declaration should be doing.
 - [ ] Every click, submit and screen entry that does something has an `on` or
       `uses`; continuations sit only on actions that can fail.
-- [ ] Navigation regions, slice buttons, blueprint references and sample data follow `references/application-shell.md`: each module's mode is deliberate, no module item targets another module, every button names a State Change slice, every template has a `category`, and the active sample data pack is chosen once in the `ui profile`.
+- [ ] Navigation regions, slice buttons, blueprint references and sample data follow `references/application-shell.md`: each module's mode is deliberate, no module item targets another module, every button names a State Change slice, buttons shared by a feature's screens sit in a feature `toolbar` linked to its commands (`confirm` on destructive ones), every template has a `category`, and the active sample data pack is chosen once in the `ui profile`.
 - [ ] Component bindings, exposed template values, manual form columns, toolbar items, outlets and routes all trace to typed data; no runtime fallback counts as delivery. Report authoring acceptance, executable admission and runtime
       implementation separately.
 

package/package/corpus/skills/cratis-screenplay-ui-composition/references/application-shell.md

@@ -2,9 +2,11 @@
 
 ## Contents
 
+- Default shell
 - One complete shell
 - Navigation regions: inherit, extend or override
 - Toolbar buttons that invoke a State Change slice
+- Feature and module toolbars
 - Template references, categories and blueprints
 - Sample data packs
 - Shapes the compiler refuses
@@ -20,6 +22,12 @@ Every construct here is authoring syntax. The executable model defers it (`PLAY0
 tree, and none of it changes a backend. The Scene designer, the Stage runtime and Studio read the same lines, so the
 Screenplay is the one place to write them.
 
+## Default shell
+
+Requires Stage 4.189.3 or later (the CLI that bundles it) for a rendered frontend to get a default application shell without a
+`layout` or `ui profile`. Declare a `layout` and a `ui profile` only to customize that shell
+(navigation, logo, templates, sample data), as below.
+
 ## One complete shell
 
 ```screenplay
@@ -188,6 +196,41 @@ layout AppShell
 ⚠️ When a screen uses a `template`, put the `toolbar` inside a slot body (`body` above). Stage refuses a screen that
 mixes a top-level `template` directive with other top-level directives.
 
+## Feature and module toolbars
+
+Requires Screenplay 4.238.0 or later (`screenplay --version`); an older compiler refuses `toolbar` in a `feature` or `module`.
+
+A template declares a `toolbar` slot. When the same actions belong to every screen of a feature, write the toolbar once on the
+`feature` (or on the `module` for every feature below it) instead of repeating it on each screen: the entries are contributed to
+the `toolbar` slot of every screen beneath it, sub features included, after the screen's own entries (the nearer toolbar comes
+later), and each entry runs one command of the feature. A screen that needs its own buttons keeps its own `toolbar`.
+
+```text
+module Merchandising
+  feature Publication
+    toolbar actions
+      button approve title "Approve product" slice Merchandising.Publication.ApproveProductForSale emphasis primary icon check
+      button withdraw title "Withdraw product" slice Merchandising.Publication.WithdrawProduct emphasis quiet icon ban
+        confirm "Take this product off sale?"
+      item archive action ArchiveProduct
+        label "Archive"
+        icon archive
+```
+
+- The lines are the ones of a screen toolbar: `item <id> action <Command>` and `button <id> title "<text>" slice <Slice>`, with
+  the `PLAY0761`-`PLAY0765` rules above.
+- `confirm "<text>"` (or a `$strings.<key>` token) is an optional child line of an `item` and of a `button`: the user confirms
+  before the command runs or before the button's dialog opens. Use it for destructive or hard-to-undo commands, not for every entry.
+- An `item ... action <Command>` must name a command that a slice of the feature (or module) declares; otherwise the compiler
+  warns that the command is not the feature's. Fix the name or move the toolbar to the feature that owns the command; never silence the warning.
+- Choose the feature toolbar when the buttons act on the feature as a whole (approve, withdraw, new). A button that needs the row
+  the user picked (a row action) stays an `item ... action` on the screen's table or list, because the toolbar has no row.
+- Preview and Play open the command's form dialog for an entry (or run it after the confirmation); Studio's feature editor has a
+  Toolbar section that adds a button and links it to a command of the feature. All of it is authoring syntax like every screen
+  construct: the printer writes it back where it was written.
+- Verify: `screenplay <model> --warnaserror` is clean (no warning about a command the feature does not declare), then Preview or Play a screen of the feature and see the
+  buttons in the template's toolbar; a destructive one asks first.
+
 ## Template references, categories and blueprints
 
 - Every `layout`, `screen template` and `dialog template` declares a `category`; a template picker groups by it, and a
@@ -316,5 +359,6 @@ pass. Propose, show the difference, apply, reopen. Details: `cratis-screenplay-m
 - [ ] Hierarchy is in the sidebar; sub-items target features of the parent's module.
 - [ ] Every button names a State Change slice; none is left without a slice.
 - [ ] A screen with a `template` keeps its toolbar inside a slot body.
+- [ ] Buttons shared by every screen of a feature sit in a feature `toolbar`, each linked to a command of that feature, with `confirm` on the destructive ones.
 - [ ] Every template has a `category`; every blueprint reference has a valid range and is listed in a profile's `packages`.
 - [ ] The active sample data pack is selected once, in the `ui profile`, and no sample value sits in a component.

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/admission.md

@@ -2,6 +2,7 @@
 
 ## Contents
 
+- Probe before the first real render
 - How a refusal arrives
 - Event-reaction boundary
 - Recovery, stored identity and baseline boundaries
@@ -57,6 +58,13 @@ Binding with the CLI's bundled compiler is a separate
 prerequisite. The exhaustive construct table is `references/renderable-subset.md` in
 `cratis-screenplay-toolchain`; run the real render before claiming anything is admitted.
 
+## Probe before the first real render
+
+`cratis screenplay validate --executable` binds the model but does not run Stage admission, so a
+renderer refusal such as `STAGE-ESM-005` (Cratis events have no optional properties) passes it.
+Run `cratis render <root> --target cratis --name <App> --destination <dir> --check` right after validate:
+it runs the same admission, collects every refusal and writes nothing.
+
 ## How a refusal arrives
 
 One blocking diagnostic fails the **whole** plan and nothing is published (exit 5).

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/rendered-application.md

@@ -3,6 +3,7 @@
 ## Contents
 
 - Scaffold
+- Lists on screen
 - Reducer layout for new applications
 - What is managed
 - `Customizations/` (unmanaged)
@@ -50,6 +51,13 @@ is off), but any override must be proven with a restore and build. The compose f
 `35000`, keeps data in the named volumes `chronicle-data` and `chronicle-config`, and
 `docker compose down --volumes` is the only thing that deletes them.
 
+## Lists on screen
+
+A `data <ReadModel>[] via query <Query>` list renders from either list-query mode, but
+`observable` renders `Observe<T>()` and a first-result wait, while a snapshot renders a one-shot
+`GetInstances<T>()`. Declare `query <Name> => observable <ReadModel>[]` for any list a person watches change.
+Run `cratis render --check` first (`references/admission.md`) to catch refusals before a real render.
+
 ## Reducer layout for new applications
 
 Requires Stage 4.128.0 for the Cratis C# self-reducing profile; older renderers emit

package/package.json

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