@cratis/pi 2.28.0 → 2.29.0

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/SKILL.md

@@ -10,6 +10,17 @@ The two slice types that run without anyone pressing a button. A `capture` in a
 `Translate` slice turns outside data into events; a `reaction` in an `Automation`
 slice runs when something happens.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |

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

@@ -3,6 +3,8 @@
   "input": "Translate external data into events and declare a reaction.",
   "fixtures": [],
   "assertions": [
+    { "kind": "skill-contains", "value": ".cratis/screenplay/" },
+    { "kind": "skill-contains", "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`" },
     { "kind": "skill-contains", "value": "cannot be mixed in one clause" },
     { "kind": "skill-contains", "value": "`where` belongs to the reaction, not to one trigger" },
     { "kind": "skill-contains", "value": "Startup` and `Shutdown" }

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

@@ -10,6 +10,17 @@ Everything that changes the system: the `command` that expresses intent, the
 `event` it appends, the rules that can refuse it, and the strongly-typed values
 they are all built from.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |

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

@@ -3,6 +3,14 @@
   "input": "Declare a Screenplay command with validation, authorization and concurrency.",
   "fixtures": [],
   "assertions": [
+    {
+      "kind": "skill-contains",
+      "value": ".cratis/screenplay/"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`"
+    },
     {
       "kind": "skill-contains",
       "value": "A second `identifier` on the same command is an error"

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

@@ -17,6 +17,17 @@ assumptions. Keep asking *"and then what happens?"* after every event, every
 command, every answer. Use business language. Do not discuss databases, APIs, or
 frameworks during modeling.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |
@@ -131,14 +142,24 @@ When one is found, ask the user to clarify, create the missing element, re-valid
    instances — ask *"can there be more than one of these at once?"* for each field.
 8. No cross-cutting infrastructure is modeled as a `Translate` slice.
 
-## One file, or a folder
+## Choose a file layout
+
+Treat `.cratis/screenplay/` as one application and choose the coarsest layout
+that keeps both the source and its diffs readable:
+
+- Keep one `application.play` while it stays readable top to bottom.
+- Use one file per module when modules are simple.
+- Use one file per feature when features have sub-features.
+- Use one file per slice when the model is large enough that a change must be
+  reviewable in isolation.
 
-Start with one file, read top to bottom. Reach for a folder when it stops being
-navigable — the invoicing sample is 981 lines with **one** module.
+Reviewability, not an arbitrary line count, triggers the next split. In a large
+model, one slice per file makes a scripted edit's blast radius visible in the
+diff instead of hiding cross-reference defects in a single enormous file.
 
-The folder layout mirrors the language, one folder per level: `application.play`
-at the root (`domain`, `import`, `concept`, `type`, `policy`, `persona`,
-`authentication`, `seed`), then `<Module>/<Module>.play`,
+At the most granular layout, folders mirror the language, one folder per level:
+`application.play` at the root (`domain`, `import`, `concept`, `type`, `policy`,
+`persona`, `authentication`, `seed`), then `<Module>/<Module>.play`,
 `<Module>/…/<Feature>/<Feature>.play`, and `<Module>/…/<Slice>/<Slice>.play` for
 one slice, whole. A slice file restates its `module` and `feature`; nothing is
 written twice.
@@ -155,7 +176,7 @@ and slices come back sorted by name. Never encode meaning in order.
 ## Verify
 
 ```shell
-screenplay path/to/model --warnaserror
+screenplay .cratis/screenplay/ --warnaserror
 ```
 
 - [ ] Zero errors **and zero warnings**. An unrecognized construct inside a slice

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

@@ -3,6 +3,18 @@
   "input": "Facilitate an event modeling session and land the model as .play source.",
   "fixtures": [],
   "assertions": [
+    {
+      "kind": "skill-contains",
+      "value": ".cratis/screenplay/"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "Use one file per slice"
+    },
     {
       "kind": "skill-contains",
       "value": "expected StateChange, StateView, Automation or Translate"

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

@@ -18,6 +18,17 @@ application.** Nothing in it emits C#, TypeScript or any target artifact — tha
 is Stage's job, and Stage admits less than Screenplay parses. Author against that
 reality, not against the ecosystem diagram.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |
@@ -29,11 +40,32 @@ reality, not against the ecosystem diagram.
 Behavior below is read from the repository at tag `v4.12.1`. Reverify before
 claiming another version behaves the same.
 
+## Choose a file layout
+
+Treat `.cratis/screenplay/` as one application and choose the coarsest layout
+that keeps both the source and its diffs readable:
+
+- Keep one `application.play` while it stays readable top to bottom.
+- Use one file per module when modules are simple.
+- Use one file per feature when features have sub-features.
+- Use one file per slice when the model is large enough that a change must be
+  reviewable in isolation.
+
+Reviewability, not an arbitrary line count, triggers the next split. In a large
+model, one slice per file makes a scripted edit's blast radius visible in the
+diff instead of hiding cross-reference defects in a single enormous file.
+When files are split, restate their parent `module` and `feature`; the folder
+compiler merges declarations by name before resolving references.
+
+Always verify `.cratis/screenplay/` as a folder after a change. Verifying one
+split file alone produces false unknown-name diagnostics for declarations held
+in its siblings.
+
 ## Verify a model
 
 ```shell
 dotnet tool install -g Cratis.Screenplay.Tool
-screenplay                      # or: screenplay path/to/model
+screenplay .cratis/screenplay/ --warnaserror
 ```
 
 The tool takes **one positional argument** — a directory or a single `.play`

package/package/corpus/skills/cratis-screenplay-model-authoring/verification.json

@@ -0,0 +1,27 @@
+{
+  "skill": "cratis-screenplay-model-authoring",
+  "input": "Author and organize a Screenplay model in a repository.",
+  "fixtures": [],
+  "assertions": [
+    {
+      "kind": "skill-contains",
+      "value": ".cratis/screenplay/"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "source is the single flow model"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "Use one file per module"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "Use one file per slice"
+    }
+  ]
+}

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

@@ -10,6 +10,17 @@ A `projection` folds events into a read model. Its body is the **Projection
 Declaration Language**, an embedded sub-grammar with its own parser — not free
 text. This is half of every event model, and the half most easily got wrong.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |

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

@@ -3,6 +3,8 @@
   "input": "Build a read model from events with the Projection Declaration Language.",
   "fixtures": [],
   "assertions": [
+    { "kind": "skill-contains", "value": ".cratis/screenplay/" },
+    { "kind": "skill-contains", "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`" },
     { "kind": "skill-contains", "value": "AutoMap is on by default" },
     { "kind": "skill-contains", "value": "PLAY0191" },
     { "kind": "skill-contains", "value": "every event type in the system" },

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

@@ -9,6 +9,17 @@ license: MIT
 What the system can be asked, and what a user sees. The `readmodel` declares the
 shape, the `query` is the entry point, and the `screen` renders it.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |

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

@@ -3,6 +3,8 @@
   "input": "Declare a Screenplay query and the screen that binds to it.",
   "fixtures": [],
   "assertions": [
+    { "kind": "skill-contains", "value": ".cratis/screenplay/" },
+    { "kind": "skill-contains", "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`" },
     { "kind": "skill-contains", "value": "The tenant is the default and stays unstated" },
     { "kind": "skill-contains", "value": "belongs on a `from` parameter, never on a `filter`" },
     { "kind": "skill-contains", "value": "warnings, not errors" }

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

@@ -10,6 +10,17 @@ A `specification` is the acceptance criterion for a slice, written in the same
 document as the behavior it pins. Given/when/then, in business language, with
 concrete data.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |

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

@@ -3,6 +3,14 @@
   "input": "Write given/when/then specifications for a Screenplay slice.",
   "fixtures": [],
   "assertions": [
+    {
+      "kind": "skill-contains",
+      "value": ".cratis/screenplay/"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`"
+    },
     {
       "kind": "skill-contains",
       "value": "**`then` contains either events or an error \u2014 never both.**"

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

@@ -10,6 +10,17 @@ Event Modeling's wireframe step is a first-class part of the language. The shell
 the reusable shapes inside it, the forms bound to commands, and the navigation
 entries other modules contribute are all declared in the `.play` model.
 
+## Locate the model
+
+Look first in `.cratis/screenplay/` at the repository root. This is the
+conventional home for consumer-owned `.play` source; do not invent another
+location or search the whole repository before checking it.
+
+`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`. Never
+hand-copy Screenplay source between repositories. Keep Markdown that explains,
+questions or navigates the model in the repository's documentation; the `.play`
+source is the single flow model.
+
 ## Verified product sources
 
 | Package | Version | Purpose |

package/package/corpus/skills/cratis-screenplay-ui-composition/verification.json

@@ -3,6 +3,8 @@
   "input": "Declare the application shell, a screen template and a command form.",
   "fixtures": [],
   "assertions": [
+    { "kind": "skill-contains", "value": ".cratis/screenplay/" },
+    { "kind": "skill-contains", "value": "`cratis ai install` manages `.cratis/ai/`, not `.cratis/screenplay/`" },
     { "kind": "skill-contains", "value": "A form is discovered, not referenced" },
     { "kind": "skill-contains", "value": "declares no\n`fits slot`" },
     { "kind": "skill-contains", "value": "override-priority order" }

package/package.json

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