@cratis/pi 7.65.0 → 7.66.0

package/package/corpus/product-sync.json

@@ -171,9 +171,9 @@
         }
       ],
       "synced": {
-        "version": "4.199.0",
+        "version": "4.201.0",
         "date": "2026-10-16",
-        "by": "Cratis/AI#735"
+        "by": "Cratis/AI#733"
       },
       "covers": {
         "skills": [
@@ -201,7 +201,7 @@
         ],
         "rules": []
       },
-      "notes": "Standalone 4.199.0 and byte-identical compiler contract pinned. Cratis/AI#735: chronological Date/DateTime ordering in command conditions and command/property literal validation (ESM v26), UTC tick precision and pre-rule offset validation; then matching remains ordinal. Source-checked Screenplay v4.199.0 commands, diagnostics, interoperability and specifications documentation plus decision 0087. Stage v4.127.1 still refuses v26 with STAGE-ESM-016 (stage-rendering.md and SemanticVersionFeatures.Supports); no render/runtime probe. Cratis/AI#576: prior mechanical compiler catch-up. Language batch #717/#722/#723/#724/#720/#728/#734 teaches atomic reaction batches (v22), described payload handlers (v23), portable linear matching, ordinal text rules (v24), protected command reads (v25), diagnostic arguments and event-source invokes mappings. Facts read at Screenplay v4.198.0 and introducing tags; Stage v4.127.0 admits exact v1-v21 and v23-v25 pairs but refuses v22/v26 and mixed pairs (STAGE-ESM-016), protected reads (044), atomic mode (043) and described handlers (STAGE-IMPL-002), even Stub mode. Stage text rules execute/render; no new renderer/runtime probe or Stage pin uplift. Cratis/AI#706: application navigation regions (module inherit, extend or override), toolbar slice buttons, blueprint template references and sample data packs in cratis-screenplay-ui-composition (references/application-shell.md), with the canonical shell vector and the rejection codes PLAY0710-PLAY0722 and PLAY0740-PLAY0765. Examples moved to the executable-state rules since 4.164: translator reactions in an Automation slice beside the Translate slice (PLAY0694) and the first record of a capture key appended with `when added`. Earlier: Standalone 4.164.0 and byte-identical compiler contract pinned. Cratis/AI#663: one origin per capture (PLAY0687). #668: executable no-event/redelivery v17. #684: concept query-argument validation in every version and query-error assertions v18. #681: executable refusal branches and refusal values v19. #666: proposal summary/severity counts and exact structural source proposals. Generated-concept rules select v20 with PLAY0688/0689 proofs and derived-matches repair; generated secrets and preview strategies remain refused. Release-baseline from-esm admission reads storedName. Standalone binding is not renderer admission: Stage 4.103.0 admits v1-v17 and v19; CLI 3.62.0 bundles Screenplay 4.159.0 / Stage 4.99.0 and renders through v16. Prior evidence remains unless superseded; no new renderer, Docker or browser probe."
+      "notes": "Standalone 4.201.0 and byte-identical compiler contract pinned. Cratis/AI#733: the ui profile root template, shell options, appearance and new screens default (PLAY0788-PLAY0799, quick fix for the legacy layout line, ui-profiles MCP tool, 44 tools). Cratis/AI#735: chronological Date/DateTime ordering in command conditions and command/property literal validation (ESM v26), UTC tick precision and pre-rule offset validation; then matching remains ordinal. Source-checked Screenplay v4.199.0 commands, diagnostics, interoperability and specifications documentation plus decision 0087. Stage v4.127.1 still refuses v26 with STAGE-ESM-016 (stage-rendering.md and SemanticVersionFeatures.Supports); no render/runtime probe. Cratis/AI#576: prior mechanical compiler catch-up. Language batch #717/#722/#723/#724/#720/#728/#734 teaches atomic reaction batches (v22), described payload handlers (v23), portable linear matching, ordinal text rules (v24), protected command reads (v25), diagnostic arguments and event-source invokes mappings. Facts read at Screenplay v4.198.0 and introducing tags; Stage v4.127.0 admits exact v1-v21 and v23-v25 pairs but refuses v22/v26 and mixed pairs (STAGE-ESM-016), protected reads (044), atomic mode (043) and described handlers (STAGE-IMPL-002), even Stub mode. Stage text rules execute/render; no new renderer/runtime probe or Stage pin uplift. Cratis/AI#706: application navigation regions (module inherit, extend or override), toolbar slice buttons, blueprint template references and sample data packs in cratis-screenplay-ui-composition (references/application-shell.md), with the canonical shell vector and the rejection codes PLAY0710-PLAY0722 and PLAY0740-PLAY0765. Examples moved to the executable-state rules since 4.164: translator reactions in an Automation slice beside the Translate slice (PLAY0694) and the first record of a capture key appended with `when added`. Earlier: Standalone 4.164.0 and byte-identical compiler contract pinned. Cratis/AI#663: one origin per capture (PLAY0687). #668: executable no-event/redelivery v17. #684: concept query-argument validation in every version and query-error assertions v18. #681: executable refusal branches and refusal values v19. #666: proposal summary/severity counts and exact structural source proposals. Generated-concept rules select v20 with PLAY0688/0689 proofs and derived-matches repair; generated secrets and preview strategies remain refused. Release-baseline from-esm admission reads storedName. Standalone binding is not renderer admission: Stage 4.103.0 admits v1-v17 and v19; CLI 3.62.0 bundles Screenplay 4.159.0 / Stage 4.99.0 and renders through v16. Prior evidence remains unless superseded; no new renderer, Docker or browser probe."
     },
     {
       "id": "scene",

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

@@ -25,7 +25,7 @@
 - Formatting and recovery limits
 - Code attachments
 
-The standalone MCP server lists 43 tools (including the MCP-Apps visualization tool); `tools/list` is the authority for the installed server.
+The standalone MCP server lists 44 tools (including the MCP-Apps visualization tool); `tools/list` is the authority for the installed server.
 
 The supported CLI launch is `cratis screenplay mcp <model-root>`, or `cratis screenplay mcp`
 alone inside a project, where the CLI locates the model (the project's `.play` files, else
@@ -51,7 +51,7 @@ the [MCP loop](mcp-loop.md).
 | --- | --- | --- |
 | Understanding | `describe-application`, `search-declarations`, `find-declaration`, `declaration-details` | Navigate logical hierarchy and inspect bounded details |
 | References and examples | `find-references`, `dependencies`, `dependency-graph`, `find-fixtures`, `find-assertion-gaps`, `find-specification-obligations`, `find-modeling-smells`, `semantic-diff` | Inspect declared relationships and authored examples, not executed coverage |
-| Source and validation | `diagnostics`, `read-document`, `merged-document`, `syntax-schema` | Read exact source or typed structure and diagnose problems |
+| Source and validation | `diagnostics`, `ui-profiles`, `read-document`, `merged-document`, `syntax-schema` | Read exact source or typed structure and diagnose problems |
 | Workspace inspection | `open-workspace`, `read-workspace`, `read-ast`, `workspace-state`, `export-workspace`, `repair-capabilities` | Obtain current identities, handles, readiness, code attachment requirements, source-map locations, durable-state status and the repair catalog |
 | Visual (MCP-Apps hosts only) | `visualize-model` | Draw the board for the model or a `proposalId`; its `sketch` argument previews a what-if of whole documents. Reads only |
 | Planning | `propose-source`, `propose-ast`, `propose-rename`, `propose-move`, `propose-repair`, `propose-property`, `propose-number-enum-members`, `propose-extract-inline-event`, `propose`, `recommend-layout`, `expand-layout` | Produce validated, reviewable candidates without writing them |

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

@@ -170,6 +170,19 @@ open, read, propose, review, apply, reopen loop; the syntax and rules are in
 5. Switching a module from inherit to override copies the application's items; retarget each copy to the module's own
    features first or the proposal is refused.
 
+### The profile's shell
+
+`ui-profiles` (Screenplay 4.201.0 or later) reads each `ui profile`'s root template, shell options, appearance, new screens default and
+shell diagnostics, and lists the own templates that could be the root template (`applicableRootTemplates`) or the new screens
+default (`applicableNewScreenTemplates`); pick from those instead of guessing. Edit `RootTemplateSyntax` (`name`, `blueprint`,
+`version`), `ShellOptionSyntax` (`add` to the root's `options`; `syntaxKind` is `Word`, `Text`, `Number` or `Flag`),
+`ProfileAppearanceSyntax` (`colorScheme`, `accent`) and `NewScreenTemplateSyntax` with `propose-ast`. A refusal is the answer:
+`PLAY0790` (a template nothing declares), `PLAY0792` (a blueprint the profile does not list), `PLAY0794` (a template that cannot
+be the shell), `PLAY0795` (no `content` slot), `PLAY0797` (a bad color scheme or accent), `PLAY0799` (a new screens default that
+cannot start a screen). `PLAY0796` (an option the shell does not expose) and `PLAY0791` (the legacy `layout` line) are warnings:
+the proposal is accepted and `ui-profiles` shows them. Replay against the `ui-profile-root-positive` vector and its rejection
+vectors (`ui-profile-root-unknown`, `ui-profile-root-not-a-shell`, `ui-profile-root-invalid`) in `Cratis.Screenplay.CanonicalCorpus`.
+
 Requires Screenplay 4.188.0 or later (`screenplay --version`) to `add` the first region, button or sub-item to a member
 the node JSON omits while empty; an older MCP server answers "Unknown typed syntax member".
 

package/package/corpus/skills/cratis-screenplay-toolchain/references/diagnostic-arguments.md

@@ -49,6 +49,13 @@ a separate `case` names an expansion. Argument order is immaterial.
 | PLAY0524 | `specification` (declaration), `step` (keyword), `stepIndex` (index), `property`, `type`, `example?`, `case?`, `parameter?` |
 | PLAY0525, PLAY0526 | `example` |
 | PLAY0583 | `case?`, `parameter?`, `type?`, `text?` |
+| PLAY0790, PLAY0794, PLAY0799 | `profile`, `template`, `blueprint?` |
+| PLAY0791 | `profile`, `template` (the layout name) |
+| PLAY0792 | `profile`, `template`, `blueprint` |
+| PLAY0793 | `profile`, `template`, `blueprint`, `version` |
+| PLAY0795 | `profile`, `template`, `blueprint?`, `outlet` |
+| PLAY0796 | `profile`, `template`, `blueprint?`, `option` |
+| PLAY0797 | `profile`, `value` |
 
 For PLAY0524, `step` is given, given readmodel, when, when append or then.
 `stepIndex` counts every authored given/when/then clause once across all forms,

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

@@ -11,6 +11,7 @@
 - Caller identity, compliance and routes
 - Specification metadata, callers, cases and locators
 - Guarded interaction diagnostics
+- UI profile shell: root template, options, appearance
 - Structural completeness and timeline checks
 - Editor versus C# verdicts
 - Consistency errors (V1: the model contradicts itself)
@@ -248,6 +249,26 @@ comment loss and do not support pinned evidence. TypeScript diagnoses but does
 not offer these repairs. Preview through MCP `propose-repair`, never text-patch
 around a refusal. Condition/subject errors also use guarded-action PLAY0341–0348.
 
+## UI profile shell: root template, options, appearance
+
+Requires Screenplay 4.200.0 or later (`screenplay --version`); 4.197.0 reads the syntax without the checks. The fix for each is in
+`../../cratis-screenplay-ui-composition/references/ui-profile-and-theme.md`.
+
+| Code | Severity | Meaning / fix |
+| --- | --- | --- |
+| PLAY0788 | E | A `root template` / `new screens use template` line is malformed, or pins a version on an own template. |
+| PLAY0789 | E | A malformed or repeated `appearance` line, or a second `appearance` block. |
+| PLAY0790 | E | The template is not declared (or the blueprint does not ship it). Declare it or take it from a blueprint. |
+| PLAY0791 | W | The profile selects its shell with the legacy `layout <Name>`. Write `root template <Name>`; the quick fix rewrites it (or removes the ignored line beside a `root template`). |
+| PLAY0792 | E | The blueprint is not in the profile's `packages` (or not installed). |
+| PLAY0793 | W | The pinned `version` range is not satisfied by the installed blueprint (catalog hosts only). |
+| PLAY0794 | E | The root template cannot be the shell (not a layout or application-scope template, fits a slot, `scopes` without `application`). |
+| PLAY0795 | E | The root template has no `content` slot. |
+| PLAY0796 | W | An `option` the shell does not expose. |
+| PLAY0797 | E | Color scheme is not `light`, `dark` or `system`, or the accent is not a hex colour. |
+| PLAY0798 | E | More than one `root template` in a profile. |
+| PLAY0799 | E | `new screens use template` cannot start a screen in a feature. |
+
 ## Structural completeness and timeline checks
 
 Opt in with `--check <names>` or MCP diagnostics `checks`, then treat warnings

package/package/corpus/skills/cratis-screenplay-toolchain/references/preferred-syntax.md

@@ -5,7 +5,7 @@
 
 Use these forms when writing or reviewing `.play`. Acceptance of an older
 spelling is not a recommendation to teach it. Information diagnostics do not
-fail `--warnaserror`; the corpus verification gate rejects the eleven style codes
+fail `--warnaserror`; the corpus verification gate rejects the twelve style codes
 below even when a fence declares `expect`, unless an exact, reasoned migration
 exception exists in the verifier's preferred-syntax allowlist. That allowlist also
 covers deliberate legacy explanations in prose; stale entries fail.
@@ -24,6 +24,7 @@ covers deliberate legacy explanations in prose; stale entries fail.
 | Interaction guard | Block-form `when` alternatives | Opaque interaction `where` on click, double click or select | PLAY0564 (warning or information) |
 | Projection transition cardinality | Source binding emits `One` | Constructed/deserialized ESM v1–v3 `ZeroOrOne` / `Many` | PLAY0445 (warning; ESM-only, not a source spelling) |
 | Command decision reads | `command reads protected` after reviewing every read's admission, absence and conflict semantics | Eligible legacy command reads without the application-root preamble | PLAY0786 (information; individual typed repair review, never fix-all) |
+| Profile shell | `root template <Name>` in a `ui profile` | `layout <Name>` in a `ui profile` | PLAY0791 (warning; quick fix) |
 | Literal text rules | `starts with`, `ends with`, `contains`, `not contains` or equality, preserving message and severity | Exact deprecated Studio `matches` shapes | PLAY0787 (warning; not arbitrary regex rewriting) |
 
 `query Q => observable?` is not a legacy optional type suffix and has no keyword

package/package/corpus/skills/cratis-screenplay-toolchain/references/screenplay-contract.json

@@ -79,6 +79,7 @@
     "count",
     "criminal",
     "csharp",
+    "dark",
     "data",
     "day",
     "days",
@@ -184,6 +185,7 @@
     "legalObligation",
     "legitimateInterests",
     "length",
+    "light",
     "literal",
     "load",
     "locale",
@@ -26070,6 +26072,10 @@
           "minimumSemanticVersion": "1.0",
           "diagnostic": "PLAY0269",
           "diagnostics": [
+            {
+              "code": "PLAY0791",
+              "severity": "warning"
+            },
             {
               "code": "PLAY0720",
               "severity": "warning"
@@ -34238,6 +34244,260 @@
       "reserved": false,
       "retired": false
     },
+    {
+      "code": "PLAY0790",
+      "name": "UnknownRootTemplate",
+      "severity": "error",
+      "severities": [
+        "error"
+      ],
+      "title": "A ui profile\u0027s root template, or its new screens use template default, names an own template the document does not declare.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that names the template."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The template name that nothing declares, or the blueprint does not ship."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": true,
+          "meaning": "The blueprint a template was expected from."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0791",
+      "name": "LegacyProfileLayout",
+      "severity": "warning",
+      "severities": [
+        "warning"
+      ],
+      "title": "A ui profile selects its shell with the legacy layout line instead of root template.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that uses the legacy \u0060layout\u0060 line."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The layout name the line selects."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0792",
+      "name": "UnknownRootBlueprint",
+      "severity": "error",
+      "severities": [
+        "error"
+      ],
+      "title": "A ui profile\u0027s root template, or its new screens use template default, comes from a blueprint the profile does not list in its packages, or one the host\u0027s installed catalog does not contain.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that names the blueprint."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The template that was taken from the blueprint."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The blueprint the profile does not list or the host has not installed."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0793",
+      "name": "RootTemplateVersionNotSatisfied",
+      "severity": "warning",
+      "severities": [
+        "warning"
+      ],
+      "title": "A ui profile\u0027s root template pins a blueprint version range the installed blueprint does not satisfy.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that names the root template."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The root template."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The blueprint whose installed version does not satisfy the pin."
+        },
+        {
+          "name": "version",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The version range that is pinned, or the default \u0060^\u0060 pin of the installed version."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0794",
+      "name": "RootTemplateNotApplicable",
+      "severity": "error",
+      "severities": [
+        "error"
+      ],
+      "title": "A ui profile\u0027s root template cannot be the application\u0027s shell: it is not a layout or an application-scope root screen template.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that names the root template."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The template that cannot be the application\u0027s shell."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": true,
+          "meaning": "The blueprint the template comes from."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0795",
+      "name": "RootTemplateWithoutContentOutlet",
+      "severity": "error",
+      "severities": [
+        "error"
+      ],
+      "title": "A ui profile\u0027s root template has no outlet for the screens\u0027 content.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that names the root template."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The root template that has no content outlet."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": true,
+          "meaning": "The blueprint the template comes from."
+        },
+        {
+          "name": "outlet",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The outlet the screens\u0027 content is placed in."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0796",
+      "name": "UnknownShellOption",
+      "severity": "warning",
+      "severities": [
+        "warning"
+      ],
+      "title": "A ui profile sets a shell option the root template does not expose.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that sets the option."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The root template that does not expose the option."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": true,
+          "meaning": "The blueprint the template comes from."
+        },
+        {
+          "name": "option",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The option name."
+        }
+      ]
+    },
+    {
+      "code": "PLAY0797",
+      "name": "InvalidAppearanceValue",
+      "severity": "error",
+      "severities": [
+        "error"
+      ],
+      "title": "A ui profile appearance block has a color scheme that is not light, dark or system, or an accent that is not a hex colour.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile whose appearance is invalid."
+        },
+        {
+          "name": "value",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The color scheme or accent as authored."
+        }
+      ]
+    },
     {
       "code": "PLAY0798",
       "name": "DuplicateProfileRootTemplate",
@@ -34248,6 +34508,37 @@
       "title": "A ui profile declares more than one root template.",
       "reserved": false,
       "retired": false
+    },
+    {
+      "code": "PLAY0799",
+      "name": "NewScreenTemplateNotApplicable",
+      "severity": "error",
+      "severities": [
+        "error"
+      ],
+      "title": "A ui profile\u0027s new screens use template default names a template that cannot start a screen in a feature.",
+      "reserved": false,
+      "retired": false,
+      "arguments": [
+        {
+          "name": "profile",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The ui profile that names the template."
+        },
+        {
+          "name": "template",
+          "kind": "text",
+          "optional": false,
+          "meaning": "The template that cannot start a screen in a feature."
+        },
+        {
+          "name": "blueprint",
+          "kind": "text",
+          "optional": true,
+          "meaning": "The blueprint the template comes from."
+        }
+      ]
     }
   ],
   "mcpTools": [
@@ -40019,6 +40310,23 @@
         "additionalProperties": false
       }
     },
+    {
+      "name": "ui-profiles",
+      "requiredParameters": [],
+      "optionalParameters": [
+        "name"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "visualize-model",
       "requiredParameters": [],

package/package/corpus/skills/cratis-screenplay-toolchain/references/screenplay-contract.version

@@ -1 +1 @@
-4.199.0
+4.201.0

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

@@ -1,6 +1,6 @@
 ---
 name: cratis-screenplay-ui-composition
-description: Compose the user interface of a Cratis Screenplay `.play` model — `layout` and responsive `arrangement`, screen/dialog templates, component data-context bindings, exposed template configuration, command forms and columns, navigation contributions, application navigation regions (topbar/sidebar, module inherit/extend/override), toolbar slice buttons, blueprint template references, sample data packs, hierarchical outlets/routes, toolbar dialogs, package/icon selection, interaction `behavior`/`on`/`uses` wiring, `ui profile`, `theme`, localized `$strings`, and `file` references. Use when declaring the application shell, reusable screen shapes, component/package configuration, command forms, navigation/toolbars, click or submit behavior, or theming. Do not use for a screen's own data and actions.
+description: Compose the user interface of a Cratis Screenplay `.play` model — `layout` and responsive `arrangement`, screen/dialog templates, component data-context bindings, exposed template configuration, command forms and columns, navigation contributions, application navigation regions (topbar/sidebar, module inherit/extend/override), toolbar slice buttons, blueprint template references, sample data packs, hierarchical outlets/routes, toolbar dialogs, package/icon selection, interaction `behavior`/`on`/`uses` wiring, `ui profile` (root template, shell options, appearance, new screens default), `theme`, localized `$strings`, and `file` references. Use when declaring the application shell, reusable screen shapes, component/package configuration, command forms, navigation/toolbars, click or submit behavior, or theming. Do not use for a screen's own data and actions.
 license: MIT
 ---
 
@@ -81,7 +81,7 @@ Read `references/worked-flow.md` when a complete example is needed before compos
 
 ## `layout` — the application shell
 
-One per application, declared at the top level and selected by a `ui profile`.
+One or more per application, declared at the top level; a `ui profile` selects the shell with `root template <Name>`.
 A complete example:
 
 ```screenplay
@@ -267,7 +267,7 @@ precedence, PLAY0485 and examples.
 
 ## `ui profile` and `theme`
 
-A `ui profile` selects the layout, theme and `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. Read [references/ui-profile-and-theme.md](references/ui-profile-and-theme.md) when writing a profile or theme.
+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.
 
 ## Localized strings
 
@@ -288,6 +288,7 @@ Localized text lives in companion `.strings` files and is referenced unquoted as
 - [ ] Every slot a `contribute` targets is declared `contributes <Point>` somewhere
       that encloses it.
 - [ ] No `dialog template` declares `fits slot`.
+- [ ] Each `ui profile` names its shell with `root template`, not the legacy `layout` line (`PLAY0791`); a blueprint shell is listed under `packages` and its `version` pin is deliberate.
 - [ ] `packages` are ordered deliberately — later shadows earlier.
 - [ ] Every theme a profile selects is `compatible with` one of its packages.
 - [ ] `target platform` and `target size` values are spelled correctly; nothing

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

@@ -41,7 +41,7 @@ layout AppShell
 
 ui profile Desktop
   target platform web
-  layout AppShell
+  root template AppShell
 
   packages
     core

package/package/corpus/skills/cratis-screenplay-ui-composition/references/screen-composition-contract.md

@@ -200,7 +200,7 @@ field.
 ```screenplay excerpt
 ui profile Desktop
   target platform web
-  layout AppShell
+  root template AppShell
   packages
     Product.DesignSystem
     Cratis.Components

package/package/corpus/skills/cratis-screenplay-ui-composition/references/ui-profile-and-theme.md

@@ -1,6 +1,124 @@
 # UI profile and theme
 
-This reference holds the `ui profile` and `theme` excerpt and its rules for platforms, sizes, package order and theme compatibility.
+## Contents
+
+- The shell: `root template`
+- `ui profile` and `theme`
+- Reading and editing the shell
+
+This reference holds the `ui profile` and `theme` excerpts and their rules: the root template that names the application shell, shell options, appearance, the new screens default, platforms, sizes, package order and theme compatibility. Requires Screenplay 4.200.0 or later (`screenplay --version`) for the diagnostics `PLAY0790` to `PLAY0799`; 4.197.0 reads the syntax.
+
+## The shell: `root template`
+
+A `ui profile` names the template the whole application is drawn in with `root template`. Every screen's template chain is placed in the
+shell's primary outlet (`content`). The reference is the one a `template` assignment uses: an own `layout` or application-scope
+screen template by name, or a template a blueprint ships, `blueprint <Blueprint> <Name>`, with an optional `version "<range>"` pin.
+`ui profile` is the only place that selects the shell; a screen never names it.
+
+```screenplay
+layout AppShell
+  category application
+  topbar
+  side
+  content
+
+exposure for AppShell
+  property topbar.showFooter label "Footer"
+
+module Workspaces
+  screen template Sheet
+    category Page
+    scopes feature
+    content
+
+ui profile Desktop
+  target platform web
+  target size regular
+  theme Nordic
+
+  root template AppShell
+    option showFooter true
+
+  appearance
+    color scheme dark
+    accent "#4F46E5"
+
+  new screens use template Sheet
+
+  packages
+    Cratis.Components
+
+theme Nordic
+  compatible with Cratis.Components
+```
+
+A shell from a blueprint lists the blueprint under `packages` (the blueprint's name is a package) and may pin a version:
+
+```screenplay
+ui profile Web
+  packages
+    Cratis.Blueprint.Default
+
+  root template blueprint Cratis.Blueprint.Default AppShell version "^4.5"
+  new screens use template blueprint Cratis.Blueprint.Default Detail
+```
+
+- `root template`: at most one per profile. The shell is a `layout`, or a screen template that declares `scopes application` and fits no slot. It
+  needs a `content` slot, or no screen has a place in it.
+- `option <name> <value>`: a configurable item the shell exposes (an own shell exposes the properties of its `exposure for <Shell>`).
+  The value is a bare word, a quoted string, a number, `true` or `false`. Set each name once.
+- `appearance`: `color scheme` is `light`, `dark` or `system`; `accent` is a quoted `#RGB`, `#RRGGBB` or `#RRGGBBAA`. One block per profile.
+- `new screens use template`: the template a new screen starts from in a designer. It is an authoring default, it changes no existing
+  screen, and it has to be able to start a screen in a feature (not a layout or an application-scope root; a `scopes` list that leaves
+  out `feature` is refused).
+- A version range only applies to a blueprint template; `*`, an exact version or a `^`, `~`, `>=`, `>`, `<=` or `<` range.
+
+### Errors and fixes
+
+| Code | Severity | Cause | Fix |
+| --- | --- | --- | --- |
+| `PLAY0788` | Error | A `root template` or `new screens use template` line is malformed, or it pins a version on an own template | Write `[blueprint <B>] <Name> [version "<range>"]`; drop the version on an own template |
+| `PLAY0789` | Error | A malformed `appearance` line, a repeated line, or two `appearance` blocks | `color scheme <word>` / `accent "<colour>"`, each once, one block |
+| `PLAY0790` | Error | The template is not declared in the document (or the blueprint does not ship it) | Declare `layout <Name>` or `screen template <Name>`, or take it from a blueprint |
+| `PLAY0791` | Warning | The profile still selects its shell with the legacy `layout <Name>` line | Write `root template <Name>`; remove the `layout` line when a `root template` is present (the quick fix does either) |
+| `PLAY0792` | Error | The blueprint is not listed in the profile's `packages` (or not installed) | Add it under `packages` |
+| `PLAY0793` | Warning | The pinned `version` range is not satisfied by the installed blueprint | Move the pin or update the blueprint |
+| `PLAY0794` | Error | The root template cannot be the shell: a dialog or ordinary screen template, a slot-fitting template, `scopes` without `application` | Choose a layout or an application-scope template |
+| `PLAY0795` | Error | The root template has no `content` slot | Add the line `content` to it |
+| `PLAY0796` | Warning | An `option` the shell does not expose | Use a name the shell exposes, or add the property to its `exposure` |
+| `PLAY0797` | Error | An invalid color scheme or accent | `light`, `dark` or `system`; a quoted hex colour |
+| `PLAY0798` | Error | More than one `root template` in one profile | Keep one |
+| `PLAY0799` | Error | The `new screens use template` default cannot start a screen in a feature | Name a feature-scope screen template |
+
+What a blueprint ships is only known where the blueprint is installed, so its checks (`PLAY0790` for a template it lacks, `PLAY0793`,
+the options and outlets of its templates) come from the host that has the catalog (Stage, the `cratis` CLI, the MCP server); the compiler
+decides everything the document alone decides.
+
+### Negative example: the legacy `layout` line
+
+`layout <Name>` inside a profile still reads, but it is the old way to name the shell. Do not write it in a new model:
+
+```screenplay excerpt
+layout AppShell
+  category application
+  topbar
+  content
+
+ui profile Desktop
+  layout AppShell
+```
+
+The canonical form is `root template AppShell`:
+
+```screenplay
+layout AppShell
+  category application
+  topbar
+  content
+
+ui profile Desktop
+  root template AppShell
+```
 
 ## `ui profile` and `theme`
 
@@ -10,7 +128,7 @@ Excerpt: `AppShell` is the layout above.
 ui profile Desktop
   target platform web
   target size regular
-  layout AppShell
+  root template AppShell
   theme Nordic
   packages
     Cratis.Components
@@ -32,3 +150,7 @@ theme Nordic
 - `compatible with` lists the packages a theme actually supports, each at most
   once. A profile selecting a theme not declared compatible with one of its own
   packages gets a compile-time **warning**.
+
+## Reading and editing the shell
+
+`ui-profiles` (MCP, Screenplay 4.201.0 or later) returns every profile's root template, options, appearance and new screens default with the shell diagnostics, and the own templates that could be the root template or the new screens default. Edit with `propose-ast` on `RootTemplateSyntax`, `ShellOptionSyntax` (`syntaxKind` is the value's kind), `ProfileAppearanceSyntax` and `NewScreenTemplateSyntax`; an invalid reference is refused with its code.

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

@@ -146,6 +146,31 @@
       "kind": "skill-contains",
       "value": "references/application-shell.md"
     },
+    {
+      "kind": "skill-contains",
+      "value": "`ui profile` is the only place that selects the shell",
+      "file": "references/ui-profile-and-theme.md"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "| `PLAY0791` | Warning |",
+      "file": "references/ui-profile-and-theme.md"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "| `PLAY0799` | Error |",
+      "file": "references/ui-profile-and-theme.md"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "`layout <Name>` inside a profile still reads",
+      "file": "references/ui-profile-and-theme.md"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "`root template` (an own layout or application-scope screen template",
+      "file": "SKILL.md"
+    },
     {
       "kind": "skill-contains",
       "value": "A module's own items may only target that module",

package/package.json

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