@cratis/pi 7.23.0 → 7.25.0

package/package/corpus/skills/cratis-application-slice-conformance/SKILL.md

@@ -73,7 +73,7 @@ are, is `cratis-screenplay-modeling-lifecycle` ("Decide the level first").
 4. Existing code has no authority over the contract.
 
 Precedence inside the contract. Executable parts of the contract beat prose: specifications,
-mappings, constraints and authorization first; then the `description` and realization notes;
+mappings, constraints and authorization first; then the `description`, `documentation` and realization notes;
 then issue text. If prose contradicts an executable part, that is a model defect: stop that
 scope, return an **edit request** (address, change, reason) and do not pick a side silently.
 Reading a question is not resolving it. Details: `references/contract-and-precedence.md`.

package/package/corpus/skills/cratis-application-slice-conformance/references/contract-and-precedence.md

@@ -23,11 +23,11 @@ or the unmanaged extension code.
 
 ## Precedence (highest first)
 1. Executable parts: specifications, mappings, constraints, authorization, rules.
-2. The slice `description` and realization notes: they explain intent and never license a
-   contradiction or an undocumented default. Realization notes are the explicit realization
-   requirements stated in a description: they bind adapters and fallback code, cannot contradict
-   executable parts, and are never supplemented with inferred rules; other description prose is
-   only a hint.
+2. The slice `description`, its fenced `documentation`, and realization notes: they explain intent
+   and never license a contradiction or an undocumented default. Realization notes are the explicit
+   realization requirements stated in the `description` or `documentation`: they bind adapters and
+   fallback code, cannot contradict executable parts, and are never supplemented with inferred
+   rules; other prose is only a hint.
 3. Issue or ticket text.
 4. Existing code: no authority.
 

package/package/corpus/skills/cratis-application-slice-conformance/verification.json

@@ -3,6 +3,9 @@
   "input": "The marina berth model changed: RegisterBerth now rejects lengths over 25 metres and a new BerthRetired event removes a berth from the list. Re-deliver the slice code against the updated .play slice and tell me whether it is done.",
   "fixtures": [],
   "assertions": [
+    {
+      "kind": "play-compiles"
+    },
     {
       "kind": "skill-contains",
       "value": "Executable parts of the contract beat prose"

package/package/corpus/skills/cratis-arc-react-page/verification.json

@@ -0,0 +1,14 @@
+{
+  "skill": "cratis-arc-react-page",
+  "input": "Build a list page with an Add command dialog for a .play screen.",
+  "fixtures": [],
+  "assertions": [
+    {
+      "kind": "play-compiles"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "DataPage"
+    }
+  ]
+}

package/package/corpus/skills/cratis-screenplay-automations-and-translations/assets/pending-certificates.play

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Minimal parent for the queue query excerpt; the complete behavior remains in todo-list-example.md.
+module Certificates
+  feature Sending
+    slice StateView CertificatesToSend
+      readmodel PendingCertificate
+        enrolmentId Uuid
+      // @excerpt

package/package/corpus/skills/cratis-screenplay-automations-and-translations/assets/retry-sweep.play

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Minimal parent for the retry sweep excerpt; it checks source, not opaque code execution.
+module Certificates
+  feature Sending
+    slice StateView CertificatesToSend
+      readmodel PendingCertificate
+        enrolmentId Uuid
+    slice Automation SendCertificates
+      // @excerpt

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/automation-patterns.md

@@ -56,7 +56,7 @@ Outcomes:
 
 When a todo list is not needed: the effect is immediate, internal and cannot fail (a direct
 `produces` or co-production), and nobody needs to see pending work. Say why in the slice
-`description`; do not add a list just to follow a pattern.
+`documentation`; do not add a list just to follow a pattern.
 
 ## 3. Effects: `produces` vs `invokes`
 | | `produces <Fact>` | `invokes <Command>` |
@@ -80,8 +80,8 @@ not identity inferred from prose or an imperative pipeline call.
 Decide and record one of:
 1. **Internal ungated command** - only if the security design supports it: not reachable by
    outside callers in the target (verify; the model cannot show exposure), safe to repeat
-   (guarded by `unique event`), and touching one stream. State the reasons in the module
-   `description` (as `todo-list-example.md` does) and list "not externally exposed" as a target
+   (guarded by `unique event`), and touching one stream. State the reasons in module
+   `documentation` (the historical `todo-list-example.md` used a description) and list "not externally exposed" as a target
    requirement in `STATE.md`.
 2. **Direct `produces`** - when no decision is left (the fact is already decided) and nothing
    should refuse it.

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/cases-to-specify.md

@@ -38,7 +38,7 @@ One spec in the slice does not cover the others.
 | invalid | unknown code, wrong type | `translate` has no entry -> decide and specify |
 | changed / corrected | outside value changes after our fact | correction fact or open decision (`translation-patterns.md` §6) |
 | mis-correlated | reference points at the wrong stream | property constraint on the external reference, or an expert review case |
-| personal data | field we must not keep | excluded from the append mappings; note in `description`; the source record may still carry it |
+| personal data | field we must not keep | excluded from the append mappings; record the reason in `documentation`; the source record may still carry it |
 | authenticity / ownership | wrong source, tenant or entity reference | specify the rejection and name where it is enforced; capture metadata does not verify it |
 | each mapping branch | every recognized code has its intended local meaning | concrete payload and exact translated values; unknown code is a separate case |
 | same object, different occurrence | two legitimate events share a provider object id | both stay representable; dedup hits only the repeated occurrence |

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/effects-and-idempotency.md

@@ -70,7 +70,7 @@ See "Effect guarantees and recovery traps" in SKILL.md.
   the target's replay behaviour before relying on it, and record the answer.
 See "Effect guarantees and recovery traps" in SKILL.md.
 
-## What to write down (slice `description` + `STATE.md`)
+## What to write down (slice `documentation` + `STATE.md`)
 - Effect placement (1-4) and why. Placement 4 is syntax-only: say the model then has no
   executable form.
 - The idempotency key, and whether the outside system honours it.

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/integration-contracts.md

@@ -1,7 +1,7 @@
 # Integration contracts
 
 Use before completing a new or changed translation. Keep accepted decisions in the relevant
-`.play` descriptions and specs; open questions and target requirements go to `STATE.md`. Do
+`.play` `documentation` and specs; open questions and target requirements go to `STATE.md`. Do
 not create a second canonical model.
 
 ## Resolve only the unknowns

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

@@ -17,14 +17,16 @@ with `cratis-screenplay-render-and-gap-fill`.
 | Model element | Realization | Skill |
 |---|---|---|
 | reaction `when <Event>` with `invokes` or `produces` | Chronicle reactor returning commands or events | `cratis-chronicle-reactor` |
-| trusted actor for `invokes` | `[ExecuteCommandsAsSystem("<role>")]` on the reactor plus a policy requiring the role (Arc, since v20.56.0; available in a rendered app's Arc 22.25.0) | `cratis-chronicle-reactor` |
+| trusted actor for `invokes` | `[ExecuteCommandsAsSystem("<role>")]` on the reactor plus a policy requiring the role (Arc, since v20.56.0; available in Stage 4.51.3's rendered Arc 22.50.5) | `cratis-chronicle-reactor` |
 | clock trigger, application trigger | scheduler or host signal that raises the occurrence | `cratis-engineering-effect-boundaries` |
 | call to an outside system | adapter behind an effect boundary, keyed by the idempotency key in the model | `cratis-engineering-effect-boundaries` |
 | capture source (webhook, poll, topic) | adapter that authenticates, parses and appends | `cratis-engineering-effect-boundaries` |
 | replay versus recovery redelivery | `[OnceOnly]` for replay; a receipt keyed by `ReactorDelivery.Id` for recovery | `cratis-chronicle-reactor` |
 
-`[ProtectedDecision]` (Arc v22.39.0 and later) is not available in a Stage-rendered app (Arc
-22.25.0), and `Directory.Packages.props` there is Stage-managed: do not edit it to get a newer Arc.
+Stage 4.51.3 rendered apps pin Arc 22.50.5/Chronicle 19.32.0, so
+`[ProtectedDecision]` and `DecisionRead<T>` are available to gap-fill, not
+Stage-emitted enforcement. Admit the projection/key and enroll the read in the
+active unit of work; never edit managed `Directory.Packages.props`.
 
 ## Faithful realization
 A realization may choose the reactor, scheduler or queue mechanism. It may not: drop pending

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/todo-list-example.md

@@ -28,7 +28,7 @@ What the model proves and what it does not:
   `runs as system role` on 4.125.0 (ESM v10), with separate CLI/Stage refusal.
 - Report reference outcomes only after executing the selected scenarios.
 
-```screenplay
+```screenplay expect PLAY0469,PLAY0516
 // Todo-list automation. Shape: CoursePassed opens an item -> CertificateSender invokes
 // SendCertificate -> CertificateSent closes the item. The once-only FACT is
 // `unique event CertificateSent`; the external send is NOT proven once-only by this model.
@@ -196,12 +196,12 @@ above: a list query (the visible queue) and a retry sweep that reads the whole v
 (Screenplay#286). Keep them in the model only when the document is the deliverable and say so
 in the verdict.
 
-```screenplay excerpt
+```screenplay excerpt parent=assets/pending-certificates.play
 // Parent: the complete document above, slice StateView CertificatesToSend.
 query PendingCertificates => PendingCertificate[]
 ```
 
-```screenplay excerpt
+```screenplay excerpt parent=assets/retry-sweep.play
 // Parent: the complete document above, slice Automation SendCertificates, after CertificateSender.
 // The sweep reads the whole view (a clock trigger takes no `by`); iterating items needs code.
 reaction CertificateRetrySweep

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/translation-patterns.md

@@ -33,7 +33,7 @@ thing by it. Keep it as a property when it is needed to correlate or deduplicate
   `<X>WebhookReceived` are smells; a business fact such as `PaymentReceived` is fine).
 
 ## 4. Per-field disposition
-For every field of the outside record, decide and write in the slice `description`:
+For every field of the outside record, decide and write in slice `documentation`:
 | Disposition | Meaning | Screenplay |
 |---|---|---|
 | **map** | carried into our fact as is or translated | `map` + mapping `x = $.x`; `translate` for codes |

package/package/corpus/skills/cratis-screenplay-automations-and-translations/verification.json

@@ -3,6 +3,7 @@
   "input": "Our payment provider sends webhooks when invoices are paid or refunded, and we must email a receipt afterwards. Model the integration and the follow-up in the Screenplay model.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     { "kind": "skill-contains", "value": "`[ExecuteCommandsAsSystem(\"<role>\")]`" },
     { "kind": "skill-contains", "value": "ESM v10" },
     { "kind": "skill-contains", "value": "STAGE-ESM-024" },

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/complete-examples.md

@@ -197,7 +197,7 @@ event, on a trigger (with `where` and `invokes`), on a view read and on the cloc
 a capture with its specifications. The excerpts later in this skill have their own
 complete parent documents in `references/complete-examples.md`.
 
-```screenplay
+```screenplay expect PLAY0469
 concept InvoiceId : Uuid
 trigger PaymentFileArrived
   description "The bank's payment file listed a payment for an invoice"

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/refusals-and-redelivery.md

@@ -61,7 +61,7 @@ The complete authoring model below compiles without warnings on 4.125.0;
 `screenplay test` intentionally returns 3/unbound with PLAY0268 for redelivery
 and no-event assertion, not a recovery pass:
 
-```screenplay
+```screenplay test=unbound
 module Billing
   feature Claims
     slice Automation Recovery

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/verification.json

@@ -3,6 +3,7 @@
   "input": "Translate external data into events and declare a reaction.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     {
       "kind": "skill-contains",
       "value": "main `fd18129`"

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

@@ -87,7 +87,7 @@ commands reference; use `concept` for a single wrapped primitive.
 Excerpt: the concepts, the `InvoiceLine` type, the policy and the event are
 declared elsewhere in the model.
 
-```screenplay
+```screenplay excerpt
 command RegisterInvoice
   description "Registers a new invoice with its lines and payment terms"
   invoiceId      InvoiceId identifier
@@ -138,7 +138,7 @@ something whose identity the caller does not supply).
 Excerpt: the `Account` read model, its projection and its keyed query are
 declared elsewhere.
 
-```screenplay
+```screenplay excerpt
 command TransferFunds
   sourceId      AccountId
   destinationId AccountId
@@ -200,7 +200,7 @@ a rule that travels is worth more than one that is repeated.
 
 Excerpt: the policies are declared at the top of the model.
 
-```screenplay
+```screenplay excerpt
 authorize IsAccountant
           or IsCustomerSelf
 
@@ -252,7 +252,7 @@ choosing or omitting `for` on a production, or fixing `PLAY0469`-`PLAY0478`.
   must bind on an older version.
   Excerpt:
 
-```screenplay
+```screenplay excerpt
 produces when isProForma == true
   ProFormaInvoiceIssued
     for invoiceId
@@ -309,7 +309,7 @@ Read `cratis-screenplay-toolchain/references/sources-and-streams.md` when author
 Chronicle's constraints enforce **uniqueness only**. Excerpt: the events are
 declared in the same model.
 
-```screenplay
+```screenplay excerpt
 constraint UniqueInvoiceNumber
   unique invoiceNumber on InvoiceRegistered
   released by InvoiceCancelled

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

@@ -172,7 +172,7 @@ A template is backticked with `${}` substitutions. It parses in mappings but doe
 not bind to the executable model in `produces` or projections. Excerpt, one
 mapping line inside a `produces` block:
 
-```screenplay
+```screenplay excerpt
 fullName = `${firstName} ${lastName}`
 ```
 
@@ -181,7 +181,7 @@ Literals are `true` / `false`, `"quoted text"`, numbers (`42`, `-3.14`), and
 rather than a property path — that is how a constant key is written. Excerpt,
 inside a `projection`:
 
-```screenplay
+```screenplay excerpt
 from UserLoggedIn key literal "site-stats"
   count totalLogins
 ```

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

@@ -47,7 +47,7 @@ This complete authoring-only model compiles with `--warnaserror` at 4.125.0.
 `screenplay test` intentionally returns exit 3/unbound with PLAY0268; it proves
 no failure/compensation behavior today:
 
-```screenplay
+```screenplay test=unbound
 system Accounting
 concept ProjectId : Uuid
 module Projects

package/package/corpus/skills/cratis-screenplay-command-surface/references/policy-persona-seed.md

@@ -55,7 +55,7 @@ Source: `v4.125.0:Documentation/screenplay/policies.md`.
 
 Excerpt: `CustomerRegistered` is declared in a slice.
 
-```screenplay
+```screenplay excerpt
 seed
   for "3fa85f64-5717-4562-b3fc-2c963f66afa6"
     CustomerRegistered

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

@@ -21,7 +21,7 @@ has no portable meaning (`PLAY0268`). Give it a body when the logic can live in
 model — a `file` or a tagged ` ```csharp ` fence indented under the rule, or a
 fenced `validate` block for cross-field rules. Excerpt, inside a command:
 
-```screenplay
+```screenplay excerpt
 validate
   orgNumber rule BeAValidOrganizationNumber message "Must be a valid organization number"
     file Validations/BeAValidOrganizationNumber.cs

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

@@ -3,6 +3,7 @@
   "input": "Declare a Screenplay command with validation, authorization, a uniqueness constraint and a state-dependent rule.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     { "kind": "skill-contains", "value": "PLAY0653" },
     { "kind": "skill-contains", "value": "personal` is an alias of `pii", "file": "references/compliance.md" },
     { "kind": "skill-contains", "value": "report-only (PLAY0270)", "file": "references/compliance.md" },

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

@@ -88,7 +88,8 @@ to reach the intended result." With a brief, restate domain and goal in two sent
 
 **Unattended: assume visibly.** Never stop to ask. Take the most reasonable assumption,
 record it with its reason in the session STATE.md (`.ai-work/screenplay/<model-slug>/STATE.md`,
-untracked) and, when it shapes the model, in the feature `description`. Keep what the user
+untracked) and, when it shapes the model, in the feature's fenced `documentation` (a short
+**ASSUMED** marker may stay in its `description`). Keep what the user
 decided apart from what you assumed. Never guess silently.
 
 ## Procedure
@@ -111,7 +112,7 @@ decided apart from what you assumed. Never guess silently.
    a set-aside, an open question, or "does not apply, because ...". Unattended: model a lens
    fact only when the input implies it; otherwise record an open question.
 5. **Plot: order and branch** (`references/plotting-and-handoff.md`). Walk from the first
-   trigger to every end. In each event's slice `description` record what it comes **after**,
+   trigger to every end. In each event's slice `documentation` record what it comes **after**,
    what **causes** it (persona, schedule, outside party, other fact) and what it is **only
    allowed under** (intent). At every event ask what can happen next *instead*, including
    nothing, and which next steps may happen in any order. Classify forks: *outcome branch* (one
@@ -151,7 +152,7 @@ decided apart from what you assumed. Never guess silently.
   matches alphabetically. Unimported folder files remain visible after ranked siblings.
   MCP `expand-layout` preserves this order with import barrels; an import-less
   `PlayFileWriter.Expand` layout falls back to path order. Order is presentation, not
-  execution or identity. Keep causes and branches in the feature `description` and STATE.md.
+  execution or identity. Keep causes and branches in the feature `documentation` and STATE.md.
 - A misspelt keyword inside a slice is only warning PLAY0029 and the block disappears: always
   validate with warnings as errors.
 
@@ -159,7 +160,7 @@ decided apart from what you assumed. Never guess silently.
 - An event is a fact the business wants to remember: past tense, business verb, two to four
   words, specific (`BerthAssigned`, not `BerthUpdated`). No generic edit events.
 - One business decision usually yields one event; several facts recognised separately may
-  yield several, with the reason in the slice `description`.
+  yield several, with the reason in slice `documentation`.
 - Calculated values are views, not events, unless the calculation is itself a decision the
   business must be able to show later (a quoted price, a fee set for the season).
 - Personas are roles with a purpose. A read-only persona is legitimate; a role that neither
@@ -169,7 +170,7 @@ decided apart from what you assumed. Never guess silently.
 - A hand-over from an outside party is named as the fact we learn from it
   (`MooringPermitGranted`). If most of a story is the outside party's steps, model only what
   crosses to us.
-- A rule that depends on stored state goes into the `description` of the slice it constrains
+- A rule that depends on stored state is recorded in `documentation` on the slice it constrains
   (`only if ...`), marked as stated intent not enforced in the model today, with its target
   enforcement named for `cratis-screenplay-streams-and-consistency` and
   `cratis-screenplay-slice-design`. Never state copies, attestation booleans or rules living

package/package/corpus/skills/cratis-screenplay-discovery/references/event-naming.md

@@ -56,7 +56,7 @@
 - Optional event properties: the default is none. Chronicle warns on nullable event
   properties (CHR0012) and a specification cannot state `null` for an event value (PLAY0350).
   Make the value required, or record the second situation as its own event. Keep `optional`
-  only for a detail the business genuinely may not have, with the reason in the `description`.
+  only for a detail the business genuinely may not have, with the reason in event `documentation`.
 - Does the event restate the creation event's fields (a generic edit in disguise)? Ask which
   business change it records; if none, name the specific correction or drop it.
 - Never put personal data in the event-source id; one data subject per event.

package/package/corpus/skills/cratis-screenplay-discovery/references/facilitation.md

@@ -38,7 +38,7 @@ that decision. If not, note the need as a view and move on.
 ## Unattended runs
 
 - Never block on a question. Take the most reasonable assumption, record it in STATE.md with
-  why, and mark it in the feature `description` when it shapes the model.
+  why, and record it in feature `documentation` when it shapes the model.
 - Prefer assumptions that keep the model honest (fewer, clearly named facts) over ones that
   invent detail.
 
@@ -52,6 +52,7 @@ See "Evidence and privacy" in SKILL.md.
 4. List assumptions taken.
 5. Per workflow give the happy path, the decision points and the terminal facts in a few lines.
 6. Propose the next step: the next workflow, or `cratis-screenplay-slice-design` for this one.
-7. Update STATE.md (phase, status, carry-forward); keep durable rationale in model
-   `description` text, which is rendered and queryable; `//` comments survive printing at
-   Screenplay v4.66.0, but check the dropped-comments report after any edit that cannot retain them.
+7. Update STATE.md (phase, status, carry-forward); keep durable rationale in fenced Markdown
+   `documentation`, summaries in `description`. At 4.127.0 canonical printing retains
+   documentation on its owner; MCP exposes it, but it changes no `modelRevision` and
+   reaches no rendered code. Inspect dropped comments after canonicalizing edits.

package/package/corpus/skills/cratis-screenplay-discovery/references/human-workshop.md

@@ -142,7 +142,7 @@ lists non-human causes (schedules, outside parties) separately.
 - Ask everywhere: "What happens next instead, including nothing?"
 
 Do not get stuck on exact timing; the point is the logical flow. The agent keeps the feature
-`description` story line and after / caused by / only if in the slices current
+`documentation` story line and after / caused by / only if in the slices current
 (`plotting-and-handoff.md`).
 
 ### 6. Sweep and close (15 to 20 minutes)

package/package/corpus/skills/cratis-screenplay-discovery/references/interview-questions.md

@@ -28,7 +28,7 @@ assumption you take instead of asking.
 | Hotspots | Where does this go wrong, get disputed or need workarounds today? | Focuses depth | per hotspot: what happened the last time? |
 | Competition | Can two parties want the same thing at the same moment? | Uniqueness rules, competing claims | yes: who wins, and what does the other see? |
 | On behalf | Does anyone do this for someone else, or override it? | Authority and denial | yes: may they, and must we record who acted? |
-| In any order | After this, which next steps must wait for each other and which need not? | Ordering, later automations | they need not: say so in the feature description |
+| In any order | After this, which next steps must wait for each other and which need not? | Ordering, later automations | they need not: say so in the feature `documentation` |
 | Instead | At this point, what else could happen instead, including nothing? | Branches and endings | "nothing": does it expire or wait forever? |
 
 ## Interview flow

package/package/corpus/skills/cratis-screenplay-discovery/references/personas-and-causes.md

@@ -61,8 +61,8 @@ into exactly one of these:
 
 1. **Executable.** An `authorize` gate with a role, claim or authenticated policy the persona
    does not satisfy, or an ownership policy (`claim "x" matches subject|<command property>`),
-   plus a `then denied` specification whose `given caller` carries the roles and claims that
-   stand for that persona (`cratis-screenplay-scenario-coverage`). Every command and query
+   plus a `then denied` specification using `given caller as <Persona>` for a
+   synthesized witness, or an explicit effective-gate caller (`cratis-screenplay-scenario-coverage`). Every command and query
    under an inherited module or feature `authorize` gets its own denial spec. Ownership
    against a Uuid-backed identifier is not renderable today (STAGE-ESM-015): note it.
 2. **Gap or target requirement.** The check depends on stored state ("only the requester may
@@ -74,8 +74,11 @@ into exactly one of these:
 Anything not yet resolved is an open question. Do not write Cannot lines for rules that bind
 everyone (business rules, not authority).
 
-A spec that passes is not a persona check by itself: it proves the gate refuses a caller with
-those roles and claims. Say which fixture stands for which persona.
+A passing spec proves the gate refuses that caller, not every caller fitting a
+persona. `given caller as <Persona>` chooses one authenticated policy witness;
+inspect its `or` choice. Use explicit fixtures for anonymous callers, ownership
+claims, missing gate conjuncts or refused synthesis. Name which witness stands
+for which persona.
 
 ## Cannot resolved to an executable gate
 

package/package/corpus/skills/cratis-screenplay-discovery/references/plotting-and-handoff.md

@@ -13,8 +13,9 @@
 
 Plotting arranges the discovered events as a narrative: what happens first, what depends on
 what, what can happen instead, where it ends. In Screenplay the plot is written into the
-model (slice and feature `description` text) and into STATE.md; files sort by name, so story
-order is never carried by structure.
+model (fenced `documentation` on slices and features) and into STATE.md. Board order is the
+authored declaration and import order; it is presentation, not causation, so write causes and
+dependencies down.
 
 ## 1. Sequence
 
@@ -23,7 +24,7 @@ what came before it, what made it happen, what is it only allowed under?
 
 ## 2. Record after / caused by / only if
 
-Write these three into the `description` of the `StateChange` slice that produces the event:
+Write these three into the `documentation` of the `StateChange` slice that produces the event:
 
 ```text
 After:     BerthRequested
@@ -48,7 +49,7 @@ At every event, not only at forks someone mentions:
 
 - What can happen next *instead*, including nothing? Does "nothing" expire, or wait forever?
 - Which next steps may happen in any order, and which must wait for each other? Unordered
-  successors become automations or ordering specs later; say so in the feature description.
+  successors become automations or ordering specs later; say so in the feature `documentation`.
 - On failure or refusal, what compensates, and is the refusal itself a fact the business must
   remember (a decision) or just a rejection (a scenario later)?
 
@@ -62,7 +63,7 @@ thing from the views that listed it).
 
 ## 4. Plot output format
 
-Put a compact story line in the feature `description` and report the plot per workflow:
+Put a compact story line in the feature `documentation` and report the plot per workflow:
 
 ```text
 The plot: SeasonalBerths
@@ -92,7 +93,7 @@ Switch only at a genuine handoff (a boat owner requests a berth, then the Harbou
 act on it) or as a deliberate cutaway to show what another persona sees. A change to another
 persona's read model is not automatically a new beat; it earns one only when that persona
 would look at it as the next step. Do not alternate personas for symmetry. Carry each real
-handoff into the feature `description` and the slice-design handoff packet; a cutaway is
+handoff into the feature `documentation` and the slice-design handoff packet; a cutaway is
 marked as such there.
 
 ```text
@@ -105,7 +106,7 @@ Alternating: Harbourmaster, BoatOwner, Harbourmaster, BoatOwner with no handoff
 When the story is about a *view* rather than a stream (a waiting list, a work queue, a berth
 board), a set of isolated before/after pairs hides what the user cares about: the same read
 model changing over time. Note it as one narrated walkthrough in STATE.md and the feature
-`description`: empty, then an item added, then the item done or failed, then removed, naming
+`documentation`: empty, then an item added, then the item done or failed, then removed, naming
 the event that causes each step. It is a seed only; discovery writes no specification.
 `cratis-screenplay-scenario-coverage` turns it into cumulative lifecycle specifications on
 the read model, and `cratis-screenplay-automations-and-translations` owns the work-queue

package/package/corpus/skills/cratis-screenplay-discovery/references/storming-loop.md

@@ -29,7 +29,7 @@ then reports what changed and asks one question. The user should always be able
    | rename | better business name for an existing fact | identity-affecting once persisted: see SKILL.md |
    | split | one name was covering two facts | keep the original if it is persisted; add the second |
    | merge | two names for one fact | only when they truly mean the same thing |
-   | reorder | the story order changed | change declaration/import order for the board; update the feature `description`/STATE.md for causes and branches |
+   | reorder | the story order changed | change declaration/import order for the board; update the feature `documentation`/STATE.md for causes and branches |
    | drop | not a fact after all | record why in STATE.md |
    | none | already modeled | say so briefly |
 
@@ -68,7 +68,7 @@ What a model looks like after the first workflow has been stormed: no commands,
 or screens yet. Slices are named after the command expected to produce each event. At
 Screenplay 4.125.0, boards use authored declaration/import order, and MCP `expand-layout`
 preserves it with imports. An import-less `PlayFileWriter.Expand` layout still falls back to
-path order. Order is presentation only; the feature `description` records causes and branches.
+path order. Order is presentation only; the feature `documentation` records causes and branches.
 Persona `description` text holds Does / Reads / Cannot on one quoted line here; the multi-line fenced
 form is in `personas-and-causes.md`.
 

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

@@ -3,6 +3,7 @@
   "input": "We are starting a new model for a marina that hands out seasonal berths. Here are rough notes from the harbourmaster. Find the events, the roles and the story, and put them straight into the .play model.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     { "kind": "skill-contains", "value": "## Interview phase" },
     { "kind": "skill-contains", "value": "Unattended: assume visibly" },
     { "kind": "skill-contains", "value": "Does / Reads / Cannot" },

package/package/corpus/skills/cratis-screenplay-event-modeling/SKILL.md

@@ -191,6 +191,16 @@ do not assume; it lands as `module`, `persona` and `import`; protocol in
 `cratis-screenplay-discovery`). Phase 2 designs one workflow at a time through all nine steps
 ([nine-steps.md](references/nine-steps.md): activities, Screenplay output, questions).
 
+## Keep modeling reasoning with its declaration
+
+Use `description` for summaries and fenced Markdown `documentation` on modules,
+features, slices, commands, read models and reactions (also events) for assumptions,
+boundaries and rejected alternatives. Do not leave that reasoning only in comments
+or disconnected notes. Both are report-only (PLAY0270), never executable rules.
+Specifications use `description` to name the witnessed behavior; longer reasoning
+belongs to their slice. Syntax, merge rules and diagnostics:
+[model reasoning](../cratis-screenplay-slice-design/references/model-reasoning.md).
+
 ## The prime directive: do not lose information
 
 Store what happened (events), not just current state. Events are immutable

package/package/corpus/skills/cratis-screenplay-event-modeling/references/nine-steps.md

@@ -113,7 +113,7 @@ identity), `authorize`, and `produces`. Excerpt: the complete document is
 fact, and fenced Markdown `documentation` when its meaning needs elaboration.
 Alternatively, declare it in the command with `produces event` and typed mappings.
 
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-example.md#1
 // Parent: references/invoicing-example.md (complete document), slice RegisterInvoice
 slice StateChange RegisterInvoice
   command RegisterInvoice
@@ -164,7 +164,7 @@ A `from` without a key never inherits another `from`'s key, and a projection-lev
 `key` routes nothing (`PLAY0381`). Excerpt: the complete document is
 [invoicing-example.md](invoicing-example.md); both events target the invoice's event source.
 
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-example.md#1
 // Parent: references/invoicing-example.md (complete document), slice InvoiceList
 slice StateView InvoiceList
   readmodel InvoiceListReadModel
@@ -215,8 +215,7 @@ reaction's `reads UnpaidInvoice` is report-only metadata at 4.66.0 (information
 it does not make the model consult the view. Binding therefore admits only a scheduled
 invocation that records a timestamp. Choosing which invoices are overdue (due date before the
 clock instant) is a target-side decision: record it as gap-fill with the model as the
-contract (`cratis-screenplay-render-and-gap-fill`), and say so in the slice description as
-the example does. Do not claim the specification proves the overdue decision.
+contract (`cratis-screenplay-render-and-gap-fill`), and say so in the slice `documentation`. Do not claim the specification proves the overdue decision.
 
 ```screenplay
 domain Acme.Invoicing

package/package/corpus/skills/cratis-screenplay-event-modeling/verification.json

@@ -3,6 +3,7 @@
   "input": "Facilitate an event modeling session and land the model as .play source.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     {
       "kind": "skill-contains",
       "value": "main `fd18129`"

package/package/corpus/skills/cratis-screenplay-legacy-extraction/SKILL.md

@@ -148,7 +148,7 @@ chain per slice before handoff (evidence template); never manufacture references
      `<Noun>Updated`): split by intent;
    - refusals: input or constraint rejection is `validate` / `require` / constraint plus
      `then error` with the exact message from code; authorization refusal is `authorize` plus
-     `then denied`. Legacy HTTP codes and check order go in the description;
+     `then denied`. Legacy HTTP codes and check order go in the slice `documentation`;
    - a state-dependent rule is `reads <View>` + `require ... message "..."`, marked **NOT enforced
      in the model today**, target named; a unique index with business meaning becomes
      `unique ... on <every event that sets it>` with `released by`

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/intent-example.md

@@ -20,7 +20,7 @@ What to notice:
 - The nightly hook reset (E4) is unexplained, so it is not modeled; it stays an open question
   (Q5) in the loss report.
 
-```screenplay
+```screenplay test=unbound
 // An intentional candidate re-sliced from as-is evidence. DESIGN MODE.
 // Evidence ids refer to rows like those in evidence-table-template.md: the legacy
 // POST /api/checkins inserted Checkins and updated Hooks (E1); here that becomes one