@cratis/pi 7.103.0 → 7.103.2

package/package/corpus/harnesses/copilot/instructions/scripting.instructions.md

@@ -0,0 +1,22 @@
+---
+applyTo: "**/*.sh,**/*.py,**/*.mjs,**/*.cjs,**/*.ps1,**/scripts/**,**/tools/**,**/.github/workflows/**,**/.cratis/ai/hooks/**"
+paths:
+  - "**/*.sh"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.ps1"
+  - "**/scripts/**"
+  - "**/tools/**"
+  - "**/.github/workflows/**"
+  - "**/.cratis/ai/hooks/**"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Scripts and tooling
+
+- Write repository scripts, CI helpers and tooling in Node (`.mjs`, or `.ts` limited to erasable syntax: no enums, no parameter properties), using only `node:` built-ins (`fs.glob`, `util.parseArgs`, `fetch`, `node:test`). Node and the .NET SDK are the only runtimes every Cratis build machine and runner is guaranteed to have.
+- Use a C# file-based app (`dotnet run --file tool.cs`, `#:package` pinned) when the script needs .NET or Cratis libraries or shares types with the product. Do not use one in hooks or on per-call hot paths.
+- Hooks under `.cratis/ai/hooks` are POSIX sh compatible with bash 3.2, or Node. Read stdin with `IFS= read -r -d '' x || true`, never `$(</dev/stdin)`.
+- Do not add Python scripts or `python3` workflow steps to Cratis repositories unless the project itself is Python (for example the Chronicle Python client). Existing Python scripts are ported to Node opportunistically: when you substantially change one, port it in the same PR. There is no bulk port.
+- Agents: edit files with the edit/write tools, query JSON with `gh --jq`/`jq`, and use `node -e` or `node --input-type=module - <<'EOF'` for ad-hoc logic. Never `python3 -c`, and never rewrite files by script.

package/package/corpus/rules/general.md

@@ -149,11 +149,11 @@ A claim is only as good as the signal behind it — a build result, a test run,
 | Before any browser call: production permit, handoff, artifact paths, evidence | `browser.md` |
 | Whether you are allowed to do the thing you are able to do | `capability-is-not-authority.md` |
 | Before running a command that could print a credential, or when a secret value appears in output | `secrets.md` |
-| What must stop and ask a human | `capability-is-not-authority.md` (absent authority for a consequential effect: stop and ask) |
+| What must stop and ask a human | `capability-is-not-authority.md` |
 | What counts as evidence that something works | `verification-discipline.md` |
 | Before writing a session note, plan or handover: where they may live (`.ai-work/` only) | `local-work-artifacts.md` |
 | What may be written into the `.cratis/` folder (configuration and the corpus only, never deliverables) | `cratis-folder-is-configuration.md` |
-| Exit-code meaning, scripts and wrappers that lose a verdict | `exit-codes-and-wrappers.md` |
+| Exit-code meaning, scripts and wrappers that lose a verdict; which language a script uses | `exit-codes-and-wrappers.md`, `scripting.md` |
 | Writing a scan, allowlist, script or CI check, or a destructive pass, that cannot pass vacuously | `guards-and-fuses.md` |
 | How the shared corpus is installed, updated and rolled back | `ai-distribution.md` |
 | Code-level event modeling / schema migration / calling commands from code / paging / cross-cutting metadata / multi-tenancy | the matching skills |

package/package/corpus/rules/scripting.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**/*.sh,**/*.py,**/*.mjs,**/*.cjs,**/*.ps1,**/scripts/**,**/tools/**,**/.github/workflows/**,**/.cratis/ai/hooks/**"
+paths:
+  - "**/*.sh"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.ps1"
+  - "**/scripts/**"
+  - "**/tools/**"
+  - "**/.github/workflows/**"
+  - "**/.cratis/ai/hooks/**"
+---
+
+# Scripts and tooling
+
+- Write repository scripts, CI helpers and tooling in Node (`.mjs`, or `.ts` limited to erasable syntax: no enums, no parameter properties), using only `node:` built-ins (`fs.glob`, `util.parseArgs`, `fetch`, `node:test`). Node and the .NET SDK are the only runtimes every Cratis build machine and runner is guaranteed to have.
+- Use a C# file-based app (`dotnet run --file tool.cs`, `#:package` pinned) when the script needs .NET or Cratis libraries or shares types with the product. Do not use one in hooks or on per-call hot paths.
+- Hooks under `.cratis/ai/hooks` are POSIX sh compatible with bash 3.2, or Node. Read stdin with `IFS= read -r -d '' x || true`, never `$(</dev/stdin)`.
+- Do not add Python scripts or `python3` workflow steps to Cratis repositories unless the project itself is Python (for example the Chronicle Python client). Existing Python scripts are ported to Node opportunistically: when you substantially change one, port it in the same PR. There is no bulk port.
+- Agents: edit files with the edit/write tools, query JSON with `gh --jq`/`jq`, and use `node -e` or `node --input-type=module - <<'EOF'` for ad-hoc logic. Never `python3 -c`, and never rewrite files by script.

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

@@ -121,7 +121,32 @@ At most one command property may carry `identifier`. It names the value the
 runtime uses as the event source id, so **choosing it is choosing the stream
 boundary** — the highest-consequence decision in the slice. Leave it out only
 when the runtime should allocate a fresh `Uuid` (a command that creates
-something whose identity the caller does not supply).
+something whose identity the caller does not supply); for a create command prefer
+`generated identifier` below, which also keeps the id out of the rendered form.
+
+**A command that creates something has no caller-supplied id.** Declare
+`<id> <IdConcept> generated identifier` (ESM v7, Screenplay 4.68.0 or later) and `returns <id>` when the
+caller needs it back. Symptom of getting it wrong: `organizationId OrganizationId identifier` on a create
+command makes the rendered form ask the user to type an Organization Id. Keep plain `identifier` for
+commands that act on an existing stream (the id comes from the selected row). Specifications pin the
+allocated value with `for "<value>"` in `when` and `then` (see the generated-values reference). Read
+[generated values](references/generated-values-and-responses.md) before writing one.
+
+```screenplay excerpt
+command RegisterOrganization
+  organizationId OrganizationId generated identifier
+  name           OrganizationName
+  produces event OrganizationRegistered
+    name OrganizationName = name
+  returns organizationId
+specification RegistersAnOrganization
+  when RegisterOrganization
+    for "11111111-1111-1111-1111-111111111111"
+    name = "Acme"
+  then OrganizationRegistered
+    for "11111111-1111-1111-1111-111111111111"
+    name = "Acme"
+```
 
 - A second `identifier` on the same command is an error: *only one property can be
   the identifier*.

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

@@ -282,6 +282,23 @@ of a document a reader cannot check at a glance.
 
 Read [pdl-grammar.md](references/pdl-grammar.md) when checking exact syntax, interpreting a projection diagnostic code, or needing a worked example.
 
+## `STAGE-ESM-017` on a projection passes `validate` and fails at `render`
+
+Symptom: `cratis screenplay validate --executable` exits 0, then `cratis render` (or `render --check`)
+refuses with `STAGE-ESM-017` and a generic message whose location is a `sem1:<hash>`, not a source line
+(seen on Stage 4.192.0 and CLI 3.94.0). Cause: `validate --executable` binds only Screenplay's model;
+Stage's admission runs only in `render`. Check every `from` block in turn:
+
+1. **Key.** An event property or the event source. A root `from` also accepts a constant text key (nonempty, only letters, digits, `_`, space and `. / : * + -`); any other literal key, and a literal key outside a root, is refused.
+2. **Do not overwrite the key.** A mapping onto the key property must restate the key itself (`from E` keyed by the event source with `berthId = $eventSourceId`, or the key's own event property); mapping a different value onto it is refused (`MatchesKey`). Simplest is to leave the key property unmapped.
+3. **`$eventSourceId` into a non-key target** is admitted in a `from` block keyed by an event property, when every command and reaction producing the event addresses it with a non-collection value of exactly the target's type (optionality ignored). It is refused in `join`s, for a mismatched type, and for an event nothing produces.
+4. **No `$context.*`.** Map an event property instead and have the command set it. The compiler may refuse it first (`PLAY0152`); Stage refuses a context value in a projection with `STAGE-ESM-017`.
+5. **Targets.** A target path through an optional or non-composite intermediate is refused; an optional leaf and a path through required composites are fine. The event property mapped from must exist on the event.
+
+Bisect: run `cratis render <root> --target cratis --name <App> --destination <dir> --check` (plans,
+writes nothing), comment out `from` blocks one at a time until the error clears, then apply the list to
+the block that cleared it. Reference: `cratis-stage-rendering-and-sandbox` `references/admission.md`.
+
 ## Verify
 
 - [ ] Standalone `screenplay <model> --warnaserror` reports zero errors and zero

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/SKILL.md

@@ -178,6 +178,23 @@ Adapters and non-renderable scope follow the contract rules of `cratis-applicati
   Never `.cratis-render/` (the journal directory) and never `.ai-work/`.
 - Limits stated in this text are prompt policy unless a guard enforces them; say so.
 
+## Hand-written query logic and re-render
+
+Symptom: a today-relative query (overdue, due today) was written by editing the body of a generated query
+file; the next `render` refused with `Managed artifact '<file>' was modified by the user; pass --force to
+replace it.` Query filters are equality only and there is no `today` in a filter or projection, so this
+logic is gap-fill. Cause: a managed file's hash is in `.cratis-render.json`, and an edited one blocks the
+whole re-render. What to do:
+
+- Never edit a managed file. Put the logic in a new unmanaged file, for example `Customizations/<Name>.cs`
+  (compiled with the project, never replaced by `render`), with its own endpoint or query class, and record it
+  as gap-fill (`references/gap-fill-handoff.md`).
+- `--force` replaces the edited managed file with the generated one and discards the edit; use it only with
+  approval that names the file.
+- Screens reported as `PLAY0269` are information that the backend profile defers them. They are not
+  proof of a rendered screen: check the running app (`cratis-screenplay-toolchain` `references/fast-path.md`)
+  and list any authored screen that is missing as not rendered.
+
 ## Gate
 
 Before reporting done:

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

@@ -277,11 +277,19 @@ For view specifications:
 - [ ] Queries cover out-of-rule concept arguments with `then error`; a valid
       absent key uses `then no result`. Projections still cannot reject events.
 
+## Run the specs before calling the work done
+
+Symptom: a model delivered with specifications that were never run. `screenplay test <root>` runs the
+reference evaluator; after a render, run `dotnet test` (Debug) in the destination for the generated
+specification classes. Report both results separately (`cratis-screenplay-toolchain` V4 and V5.tests); a
+build that succeeds is not a test run, and `unbound`/`unsupported` is not a pass.
+
 ## Verify
 
 - [ ] Validate the complete root with warnings as errors, naming tool/version.
       Standalone tool version: `cratis-screenplay-toolchain/SKILL.md`. Run specification examples through
       `screenplay test`; expected unadmitted syntax reports unbound, not passed.
+- [ ] `screenplay test` and, after a render, `dotnet test` were run and their counts reported.
 - [ ] Executable diagnostics are clean too: `PLAY0350`, `PLAY0352`, `PLAY0388`,
       `PLAY0389` and `PLAY0273` are only reported at binding.
 - [ ] Every slice has at least one boundary specification.

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

@@ -218,7 +218,7 @@ 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).
+Read [fast path](references/fast-path.md) for the ordered requirements-to-running-app checklist (validate, `render --check`, render, build, run, check in a browser, run the specs).
 
 ## Route near misses
 

package/package/corpus/skills/cratis-screenplay-toolchain/references/cheat-sheet-example.md

@@ -171,6 +171,7 @@ module Billing
         table InvoiceRow
           column number label "Number"
         action RegisterInvoice
+          label "Register invoice"
       specification ListingAnInvoice
         given caller                                  // module + feature gates apply to the query too
           authenticated

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

@@ -20,5 +20,12 @@ Run these in order and stop at the first failure; each step catches what the one
 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.
 
+9. **Verify in a browser:** open the Vite URL, load every screen the model authored (sidebar and each screen title),
+   run one create command and one query, and read the console for errors. The check is the app, not the build:
+   a screen reported as `PLAY0269` (deferred from the backend profile, information only) is not evidence that
+   it was rendered. List any authored screen that is absent as not rendered; do not call it delivered.
+10. **Specs:** `dotnet test` in `<dir>` (the generated specifications) and `screenplay test <root>`; see
+    `cratis-screenplay-specifications`.
+
 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

@@ -72,3 +72,4 @@ Traps 39 to 44 are tool traps.
 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.
+48. `STAGE-ESM-017` on a projection also passes `validate --executable` and shows only a `sem1:` location, not the `from` block. Run `render --check` after validate, then follow the checklist and bisect in projections `SKILL.md` ("`STAGE-ESM-017` on a projection").

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

@@ -270,6 +270,44 @@ precedence, PLAY0485 and examples.
 
 A `ui profile` selects the application shell with `root template` (an own layout or application-scope screen template, or `blueprint <B> <Name>` with an optional `version` pin), its shell `option` lines, an `appearance` block (`color scheme`, `accent`), the template new screens start from (`new screens use template`), the theme and the `packages`, listed in override-priority order (a later package shadows an earlier one); `target platform` and `target size` accept any identifier, so a typo is silent. The legacy `layout <Name>` line inside a profile still reads but warns `PLAY0791`: write `root template`. `PLAY0790` to `PLAY0799` check the shell. Read [references/ui-profile-and-theme.md](references/ui-profile-and-theme.md) when writing a profile or theme, or fixing a shell diagnostic.
 
+## A deliverable app declares its identity, titles and labels
+
+Symptom: a rendered app titled "Cratis Stage" whose buttons and dialogs show raw command names. The renderer
+defaults to those when the model is silent, so declare, in every deliverable app:
+
+- the layout's `logo image "<path>" title "<text>"` inside `navigation topbar` or `navigation sidebar` (the
+  application title the shell shows; `logo initials` is only valid in a profile's `identity`);
+- a `ui profile` with `root template`, shell `option` lines such as `option showFooter false`, and an `identity`
+  block (`name`, `logo initials`);
+- a `title "<text>"` in each screen and a navigation `item <id> title "<text>" target <Module.Feature>` per screen;
+- `label "<text>"` on **every** `action`.
+
+```screenplay excerpt
+layout AppShell
+  category application
+  content
+
+  navigation sidebar
+    logo image "/assets/solocrm.svg" title "SoloCRM"
+    item organizations title "Organizations" target Crm.Organizations
+
+ui profile Desktop
+  target platform web
+  root template AppShell
+    option showFooter false
+  identity
+    name "SoloCRM"
+    logo initials "SC"
+```
+
+```screenplay excerpt
+screen Organizations
+  data OrganizationOverview[] via query AllOrganizations
+  title "Organizations"
+  action RegisterOrganization
+    label "New organization"
+```
+
 ## Localized strings
 
 Localized text lives in companion `.strings` files and is referenced unquoted as `$strings.<dotted.key>`. Read [references/localized-strings.md](references/localized-strings.md) when localizing messages, labels or titles.
@@ -294,6 +332,8 @@ Localized text lives in companion `.strings` files and is referenced unquoted as
 - [ ] Every theme a profile selects is `compatible with` one of its packages.
 - [ ] `target platform` and `target size` values are spelled correctly; nothing
       checks them.
+- [ ] A deliverable app declares layout `logo ... title`, a `ui profile` with `option` lines and `identity`,
+      a `title` per screen and a `label` on every `action`.
 - [ ] User-visible text is `$strings.` where the application is localized.
 - [ ] No `file` reference is doing work the declaration should be doing.
 - [ ] Every click, submit and screen entry that does something has an `on` or

package/package/corpus/skills/cratis-screenplay-ui-composition/references/response-continuations.md

@@ -73,6 +73,7 @@ module Billing
         returns invoiceId
       screen CreateInvoiceScreen
         action CreateInvoice
+          label "Create invoice"
     slice StateView Details
       readmodel Invoice
         invoiceId InvoiceId

package/package/corpus/skills/cratis-screenplay-ui-composition/references/worked-flow.md

@@ -23,6 +23,7 @@ module Marina
         data BerthListView[] via query ListBerths
         action BookBerth
           navigate to BerthListScreen
+          label "Book berth"
     slice StateView BerthList
       readmodel BerthListView
         berthId BerthId

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

@@ -251,8 +251,9 @@ Stage renders two projection forms; the restrictions differ.
   inside a child are admitted), `nested`
   over an optional composite property, and `every`/`all` with set-from-event-source mappings. Keys
   are an event property or the event source. The key establishes the identifier, so it must
-  end up unmapped: a mapping onto it is refused unless it copies the key's own event
-  property, so an event-source key admits no mapping at all (`STAGE-ESM-017`). Auto-map
+  end up unmapped: a mapping onto it is refused unless it restates the key (the key's own
+  event property, `$eventSourceId` for an event-source key, or the same literal)
+  (`STAGE-ESM-017`). Auto-map
   counts as a mapping: if the event carries a property with the identifier's name and type,
   declare `no automap` and map the other properties explicitly. `from E` and
   `from E key $eventSourceId` render when the identifier ends up unmapped, whether or not

package/package.json

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