@cratis/pi 7.23.0 → 7.24.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-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/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-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-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

@@ -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-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/loss-report-template.md

@@ -31,7 +31,7 @@ and the question raised.
 One line per rule, named individually (never one generic platform caveat): the rule, its
 evidence row, the invariant and consistency risk, and the target enforcement. State-dependent
 checks are written as `reads` + `require` and marked NOT enforced in the slice description;
-date rules and opaque policies that no declaration can state stay in `description` and here.
+date rules and opaque policies that no declaration can state stay in the slice `documentation` and here.
 
 ## Unknowns and undecided target decisions
 | Row/question | What is unknown | Who can answer | Candidate assumption |

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/rule-modeling.md

@@ -4,19 +4,19 @@
 - Input or constraint rejection: declarative `validate`, `require` or constraint, plus a
   `then error "<exact legacy message>"` specification.
 - Authorization refusal: `authorize` with a policy (role, claim, authenticated, or an
-  ownership policy) plus `then denied`, with caller fixtures carrying the roles or claims.
+  ownership policy) plus `then denied`, with a synthesized persona caller or an explicit effective-gate fixture.
   Every command and query under an inherited module or feature `authorize` gets its own
   `then denied` spec. A role gate with no executable form is a recorded gap.
 - Legacy HTTP status and check order (for example 409 before 403) are facts about the old
-  system: record them in the slice description and the evidence row, not in the model logic.
+  system: record them in slice `documentation` and the evidence row, not in the model logic.
 
 ## State-dependent rules
 A rule that depends on stored state (current status, existing records, balances) is written
 as `reads <View>` + `require <expr> message "…"` and the slice description says it is **NOT
 enforced in the model today** (PLAY0268/0271 at binding are expected in design mode;
 Screenplay#129/#209). Name the invariant, the race it leaves open, and the target:
-`[ProtectedDecision]` + `DecisionRead<T>` (Arc 22.39.0 and later; hand-written code only,
-not available in Stage-rendered applications, which pin Arc 22.25.0), or a Chronicle
+`[ProtectedDecision]` + `DecisionRead<T>` (Arc 22.39.0 and later; available to gap-fill
+in Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0 package set, not automatically emitted), or a Chronicle
 `concurrency` scope on the event source or stream, or a constraint where one fits. Forbidden: caller-supplied copies of state
 in `require`, boolean inputs standing in for a rule (`confirmsX == true`), and rules hidden in
 `handler`/`implementation hint` prose. Descriptions are not rendered (Stage#178), so a rule

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

@@ -14,7 +14,7 @@ who decided it?* If nobody can answer, classify the row `unknown` and ask.
 |---|---|---|---|
 | One request writes several tables | one decision; one table carries the fact, the others are consequences | one event per table (`CheckinCreated`, `HookUpdated`) | one event named for the decision (`CoatTakenIn`); consequences become projections |
 | Generic update route (`PUT /members/{id}`) | several intents hidden behind one form | one `MemberUpdated` event | split by which columns change together and why (address change, suspension, renewal); ask experts. No `Update/Edit/Save<Noun>` command and no `<Noun>Updated/Changed` event; a full-payload `*Updated` event is the default generator output and a review signal |
-| Request with no table write and a 4xx status | a rejected attempt; evidence of a rule | Prologue models it like a success (status codes are ignored) and the merge can strip properties | `validate`/`require`/constraint plus a `then error` spec with the exact message from code (authorization refusals are `then denied`); legacy HTTP code and check order go in the slice description |
+| Request with no table write and a 4xx status | a rejected attempt; evidence of a rule | Prologue models it like a success (status codes are ignored) and the merge can strip properties | `validate`/`require`/constraint plus a `then error` spec with the exact message from code (authorization refusals are `then denied`); legacy HTTP code and check order go in slice `documentation` |
 | 2xx with no table write | read, idempotent no-op, or external side effect | treated as a command | check code; classify |
 | Single-column unique index | a business uniqueness rule, or a technical key | every unique index becomes a constraint, or a clear business rule is dropped to a bare `rule` | when the meaning is clear, `unique <prop> on <every event that sets it>` plus `released by <removal event>`; list collation, case and reuse questions. Fall back to a bare `rule` only when no constraint form fits, and record that as a loss. A purely technical key stays out |
 | Foreign key | an identity relation between streams or read models | copying the parent id into every event | keep ids only where a consumer needs the value |

package/package/corpus/skills/cratis-screenplay-model-authoring/SKILL.md

@@ -130,9 +130,9 @@ and applies; others send an edit request ([MCP loop](references/mcp-loop.md)).
 3. Prefer `propose-rename` for supported logical renames: it coordinates fragments,
    repairs proven references and preserves assigned identities. Never substitute
    global string replacement for an explicit refusal.
-4. Use `propose-ast` for typed additions, replacements, removals and moves. Group
-   related cross-file changes in one batch so no broken intermediate state lands.
-   Parser-invalid source can be repaired by typed whole-document replacement.
+4. Use `propose-source` for whole text or `propose-ast` for typed edits
+   (Authoring defaults); `propose` is executable-only. Batch changes;
+   details: `references/mcp-tools.md`.
 5. Keep reference policy `Safe`. Use `Draft` only for deliberately requested
    unresolved model debt and report that debt; it does not waive structural,
    identity or binding-protection checks.
@@ -261,7 +261,8 @@ target or consequence expands.
 Readiness has two verdicts: `readiness.authoringAccepted` says the source is valid
 Screenplay; `executableReady` describes only the current executable subset. Do not
 call a model broken because it is not executable, and prefer `propose-ast` for
-full-language authoring. A rejected proposal lists its diagnostics: fix those, do not
+focused full-language edits, or `propose-source` for whole documents. A rejected
+proposal lists its diagnostics: fix those, do not
 retry the same input.
 
 ## Code attachments

package/package/corpus/skills/cratis-screenplay-model-authoring/references/mcp-loop.md

@@ -102,14 +102,18 @@ the server sends `roots/list` and serves `tools/list` after the reply).
    `search-declarations`, `declaration-details`, `dependencies`/`dependency-graph`.
    Diagnostics `scope` includes descendants and direct dependents; `checks` opts
    into completeness warnings (skipped on whole-source errors). Paging with
-   `offset > 0` requires `expectedSourceRevision`.
+   `offset > 0` requires `expectedSourceRevision`. Seed coverage with
+   `find-specification-obligations` (presence, not execution), use
+   `find-modeling-smells` as questions needing a domain consequence, and compare
+   generated/curated exported snapshots with `semantic-diff`.
 3. `open-workspace` and keep `revision` and `catalogRevision`. Opening writes
    nothing. With `identityPersistence: "root-local-on-apply"` the identities file
    is written only by `apply`.
 4. Choose the edit route (next section). For typed edits: `syntax-schema` for the
    node kind, then `read-ast` with `includeContent` for revision-bound handles.
    Never invent a handle.
-5. Propose one coherent change (a slice works best): `propose-ast` with
+5. Propose one coherent change (a slice works best): `propose-source` for whole
+   `.play` text, `propose-ast` for focused typed edits, with
    `validation: "Authoring"`, `referencePolicy: "Safe"` (`Draft` only for
    deliberate, reported gaps), `formatting: "PreserveTrivia"` for value and mapping
    patches, otherwise `CanonicalizeTouchedDocuments` (reprints the touched files).
@@ -140,7 +144,11 @@ the server sends `roots/list` and serves `tools/list` after the reply).
 2. **Prefer typed, identity-preserving operations**: `propose-rename` for renames
    (keeps `id` pins and assigned identities, refuses on ambiguity),
    `propose-repair`, `propose-extract-inline-event`, `propose-ast` for additions,
-   replacements, removals and moves.
+   replacements, removals and moves. Use `propose-source` when authoring whole
+   documents as UTF-8 text, not base64 or typed node JSON; `propose` remains the
+   executable-only exact-byte interface. Both authoring routes require revisions,
+   formatting consent and identity continuity. `SourceParseFailed` returns located
+   `authoringDiagnostics` without a proposal. Details: `mcp-tools.md`.
 3. **Bounded text edits** are fine only where no catalog address changes (table below). With
    `.screenplay/identities.json`, adding, removing or renaming a declaration, a property of a
    command, event, read model, composite type or trigger, a query, a query argument or a
@@ -162,10 +170,10 @@ the server sends `roots/list` and serves `tools/list` after the reply).
 | --- | --- | --- |
 | Address-preserving | descriptions; bodies of rules and expressions; mappings between members that already exist; any edit that adds, removes or renames no addressed element. Also every edit in a model with no `.screenplay/identities.json` except persisted names | bounded text edit of the `.play` file, then compile the folder; or `propose-ast` |
 | Catalog-changing (identity file present) | add, remove or rename a declaration (slice, command, event, read model, projection, ...), a property of a command, event, read model, composite type or trigger, a query, a query argument or a specification; create, delete, rename or move a mapped `.play` document (McpState refuses reopening with `IdentityMappingConflict`; use document operations in `propose-ast`); rename, remove or move an event, command, read model, constraint, module, feature or slice; move declarations between files; contract evolution of a persisted event (new generation, property added, removed or retyped) | `propose-rename` or a reviewed `propose-ast`; never a blind text rename. Renaming a constraint resets its uniqueness index: ask first unless the request names it, then report the reset. A persisted event rename needs `id "OldName"` (added by default) |
-| Repair | `PLAY0166`, `0478`, `0469`, `0471`, `0479`, `0516`, `0565`, `0653` (and recipe-only `0397`) | `propose-repair` with `formatting`; PLAY0166/0478 may pin attachment evidence (`pinRepairEvidence` and `expectedRepairEvidenceRevision`), never fix-all PLAY0478 |
+| Repair | `PLAY0166`, `0478`, `0469`, `0471`, `0479`, `0516`, `0563`, `0564`, `0565`, `0614`, `0653` (and recipe-only `0397`) | `propose-repair` with `formatting`; PLAY0166/0478 may pin attachment evidence (`pinRepairEvidence` and `expectedRepairEvidenceRevision`), never fix-all PLAY0478 |
 | Inline event extraction | `produces event ...` to a declared event | `propose-extract-inline-event` |
-| Parser-invalid document | no editable handles | `propose-ast` `replace-document` with a whole typed document, or fix the text |
-| Unadmitted constructs | systems/operations, exact numbers, refusal/redelivery | reviewed Authoring `propose-ast`; preserve intent and report PLAY0268 |
+| Parser-invalid document | no editable handles | `propose-source` `replace-document` with corrected source, or typed `propose-ast` document replacement |
+| Unadmitted constructs | systems/operations, exact numbers, refusal/redelivery | reviewed Authoring `propose-source` (whole documents) or `propose-ast` (typed edits); preserve intent and report PLAY0268 |
 | Admitted source/stream routing | ESM v8 at 4.125.0 | typed `propose-ast`; `propose-rename` repairs proven route references; target admission separate |
 
 ## Self-describing identity migration refusals