@cratis/pi 0.0.1

package/skills/cratis-lens-browser-extension/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: cratis-lens-browser-extension
+description: Use the Cratis Lens browser extension against a running Cratis Arc application — building and side-loading it, what the Arc app must already serve for Lens to work, switching the active user and tenant, and executing a command or query from the popup. Use when setting Lens up, when Lens does not detect an Arc app, or when a switched identity or tenant does not take effect. Do not use for production authentication or authorization design, and do not use for Chronicle inspection.
+license: MIT
+---
+
+# Use Lens against a running Arc application
+
+Lens is a Manifest V3 browser extension that impersonates a user and a tenant
+against an Arc application you are developing, and executes that application's
+commands and queries from a popup. It changes nothing in the application: it
+rewrites request headers at the network boundary and reads Arc's own
+introspection endpoints.
+
+⚠️ Lens is a **development** tool that can present any identity to any origin
+the developer points it at. Nothing in it is production tooling.
+
+## Verified product sources
+
+| Source | Version | Purpose |
+| --- | --- | --- |
+| `Cratis/Lens` `Source/` | manifest `1.0.0`, repository revision `3d0df87` | The extension itself |
+| `Cratis.Arc.Core` | `22.10.4` | The `/.cratis/*` endpoints, the forwarded-identity contract, and the tenancy header Lens depends on |
+
+⚠️ **There is no published store listing.** Nothing in the Lens repository links
+a Chrome Web Store, Edge Add-ons, AMO, or App Store entry — the only store URLs
+present are developer-console links inside its own publishing guide. Building
+from source and loading unpacked is the only install path that exists.
+
+## Install
+
+```bash
+cd Source
+yarn install
+yarn build          # writes the unpacked extension to Source/dist/
+```
+
+Then open `chrome://extensions`, enable **Developer mode**, choose **Load
+unpacked**, and select `Source/dist`. Chrome lists it as **Cratis Lens** — the
+name in `manifest.json`; the repository's own tutorial calls it "Lens - Cratis
+Developer Tools", which is stale.
+
+`yarn dev` is `vite build --watch`; the extension still has to be reloaded in
+Chrome after each rebuild. `yarn ci` runs `typecheck`, `test` and `build` — the
+same three the pull-request workflow runs. There is no lint script.
+
+The code uses the `chrome.*` namespace throughout with no polyfill. The release
+workflow also packages for Edge, Firefox and Safari, but no cross-browser
+behavior is tested; treat Chromium as the supported target.
+
+## What the Arc application must already provide
+
+Lens is not self-contained. It reads endpoints Arc maps for itself, and it sends
+headers Arc's shipped identity handler already reads. **No NuGet package,
+middleware, `Program.cs` change, or configuration key exists for "Lens support"
+— nothing in either repository names one.**
+
+| Route | Mapped by | Lens uses it for |
+| --- | --- | --- |
+| `GET /.cratis/commands` | `MapIntrospectionEndpoints`, `AllowAnonymous` | The Commands tree |
+| `GET /.cratis/queries` | `MapIntrospectionEndpoints`, `AllowAnonymous` | The Queries tree |
+| `GET /.cratis/users` | every `ICanProvideUsers`, `AllowAnonymous` | The importable user roster |
+| `GET /.cratis/tenants` | every `ICanProvideTenants`, `AllowAnonymous` | The importable tenant list |
+| `GET /.cratis/identity-details/schema` | the identity endpoint mapper | The schema-driven editor for a user's `identityDetails` |
+
+`MapIntrospectionEndpoints` is called from Arc's own application startup, so the
+two introspection routes exist without being asked for. The user and tenant
+routes return whatever the application implements — with **no implementation
+registered they return an empty list**, and Lens treats a `404` on either as
+"empty", not "broken". Users and tenants can also be created by hand in Lens's
+Settings, so an application that provides neither still works.
+
+⚠️ `/.cratis/users` and `/.cratis/tenants` are mapped `AllowAnonymous` and
+**unconditionally**. Register `ICanProvideUsers`/`ICanProvideTenants` only for a
+development environment and return fixtures — see
+`cratis-arc-authentication-authorization-and-identity`.
+
+### Identity
+
+Lens sends exactly the three forwarded client-principal headers Arc's shipped
+handler reads:
+
+```text
+X-MS-CLIENT-PRINCIPAL-ID
+X-MS-CLIENT-PRINCIPAL-NAME
+X-MS-CLIENT-PRINCIPAL      # base64 of the principal JSON
+```
+
+The principal document it base64-encodes is
+`{ identityProvider, userId, userDetails, userRoles, claims: [{ typ, val }], … }`
+with the user's `identityDetails` and `applicationProperties` spread over it.
+`identityProvider` defaults to `aad` and `userRoles` falls back to
+`["authenticated", "anonymous"]` when the user has no roles.
+
+⚠️ That is Lens's **only** identity mode. There is no bearer token, no OIDC, no
+sign-in. The application has to be running on the Microsoft-Identity-Platform
+forwarded-header path, and the reverse proxy in front of it in production must
+be the only thing that can set those headers.
+
+### Tenancy
+
+Lens sets one header, named by its `tenantHeaderName` setting, whose default is
+`x-cratis-tenant-id`. That matches `TenancyOptions.HttpHeader`'s default, and
+`TenantResolverType.Header` is Arc's default resolver — so a default Arc
+application needs no change.
+
+⚠️ **`tenantHeaderName` has no user interface.** It is a stored setting with a
+default and nothing binds it to an input. An application that resolves tenancy
+by query parameter, claim, subdomain, or a renamed header **cannot be driven by
+Lens today** without editing `chrome.storage.local` by hand. Guidance describing
+a "Tenant Header Name" field on an options page is describing something that
+does not exist — there is no `options_page` in the manifest at all.
+
+### The frontend
+
+Detection is not header-level and is not invisible. Lens injects a function into
+the page's main world and looks for:
+
+1. an element with `id="root"`;
+2. a React fiber or container key on it (`__reactFiber…` / `__reactContainer…`);
+3. a context value on the fiber tree carrying either a `reconnectQueries`
+   property, or a `configuration` object with one of `baseUrl`, `apiBaseUrl`,
+   `apiSurface`, `apiSurfaceBaseUrl`, `baseUri` or `baseAddress`.
+
+If that fails it falls back to matching the path
+`/projects/{guid}/application/{guid}`, and otherwise to the host being
+`localhost` or `127.0.0.1`.
+
+⚠️ A non-React frontend, a root element with another id, or a React version that
+renames its internal fiber keys leaves Lens undetected — the Commands, Queries
+and Query Diagnostics tabs are then **disabled**, and only Context and Settings
+work. The detected base URL is also what the Commands and Queries tabs call, so
+without detection there is nothing to call.
+
+## Switch the active user or tenant
+
+Pick both on the **Context** tab. Two things then happen, in this order:
+
+1. The service worker rebuilds its `declarativeNetRequest` **dynamic** rules —
+   at most two, one for the identity headers and one for the tenant header.
+2. It deletes the Arc identity cookie `.cratis-identity` on the detected base URL
+   and page origins, then reloads every open tab on those origins.
+
+Step 2 is the one that matters. Headers alone do not change who you are once Arc
+has issued its identity cookie; the application keeps presenting the identity it
+was first given. Dropping the cookie and reloading is what makes the switch take
+effect.
+
+The rules are scoped, deliberately. When a page origin is known the condition is
+`{ urlFilter: '*', initiatorDomains: [<page host>] }`; otherwise it is
+`||<base URL host>`. **With neither resolvable, no rules are installed at all** —
+`host_permissions` is `<all_urls>`, so a wildcard filter would attach
+impersonation headers to every XHR on every site the developer browses.
+
+⚠️ The rules match `XMLHTTPREQUEST` **only**. Document navigations, WebSocket
+connections and EventSource/SSE streams carry no injected headers. Arc's
+observable-query transports (`/.cratis/queries/ws`, `/.cratis/queries/sse`) are
+therefore **not** covered by header injection.
+
+## Execute a command or query
+
+The Commands and Queries tabs read the introspection lists and group them into a
+tree by splitting the namespace on `.`.
+
+A command is always `POST <base URL><route>` with `Content-Type: application/json`
+and the active context headers, and a body built by the schema-driven editor. A
+query is always `GET`, with `{name}` segments in the route substituted from the
+path-parameter inputs and the same context headers.
+
+⚠️ **The schema-driven payload form does not currently receive a schema from
+Arc.** Lens reads an optional property named `schema` off each introspection
+item, and falls back to trying `/.cratis/types/{type}`, `/.cratis/schema/{type}`,
+`/.cratis/schemas/{type}` and `/.cratis/types?type={type}` in turn. Arc names the
+property **`payloadSchema`** on a command and **`argumentsSchema`** on a query,
+and maps none of those four fallback routes. Every branch therefore misses, and
+the panel shows *"No payload schema available. Lens will execute this command
+with an empty payload object."*
+
+There is **no raw-JSON editor** behind that empty state, so a command reached
+this way can only be fired with `{}`. Expect that for every command until the two
+sides agree on a property name; do not read it as a broken application. Queries
+are unaffected — their inputs come from the `{name}` segments of the route, not
+from a schema.
+
+Both result panels parse defensively rather than against a contract: success is
+`isSuccess` when present and HTTP 2xx otherwise, messages are harvested from
+`exceptionMessages`/`errors`/`message`/`title`/`detail`, and a query payload is
+unwrapped from the first of `data`, `result`, `items`, `results`, `value`,
+`payload` or `content` that is present.
+
+⚠️ **The two introspection fetches send no headers and no credentials**, while
+the Settings user/tenant refresh does send both. So an application that puts
+authorization in front of `/.cratis/commands` breaks the Commands and Queries
+tabs while Settings keeps working — which reads as a mysterious partial failure.
+Leave those two routes anonymous.
+
+Queries are path-parameter GETs only: no query-string arguments, no paging or
+sorting inputs, and no observable subscription from the popup.
+
+## Query diagnostics
+
+The Query Diagnostics tab is read-only and polls every 2 seconds. It requires the
+detected Arc context to expose `observableQueryDiagnostics.getSnapshot()`; when
+it does not, the panel reports no data. Nothing else in Lens depends on it.
+
+## Safety
+
+The manifest asks for `storage`, `scripting`, `cookies`, `declarativeNetRequest`,
+`declarativeNetRequestWithHostAccess` and `<all_urls>`. That combination lets the
+extension present a chosen identity to any origin, read and delete cookies, and
+inject into any page.
+
+- Keep it out of a browser profile used for anything but development.
+- The user roster, including claims, is stored unencrypted in
+  `chrome.storage.local`.
+- An application reachable outside a developer's machine while trusting the
+  forwarded headers is impersonatable by anyone who can set them. Lens does not
+  create that exposure — it demonstrates it.
+
+## Verify
+
+- `yarn ci` is clean, and Chrome loaded `Source/dist` without errors.
+- The application answers `/.cratis/commands` and `/.cratis/queries`
+  anonymously.
+- Tenancy resolves from the header and the header is named
+  `x-cratis-tenant-id`.
+- Opening the popup on the app's tab enables the Commands tab — that is the
+  detection signal.
+- After switching a user, the tab reloaded and the application reports the new
+  identity, not the previous one.
+- Development user and tenant providers, if registered at all, return fixtures.
+
+## Route near misses
+
+- Designing authentication, authorization, identity details or tenancy in the
+  application: `cratis-arc-authentication-authorization-and-identity`.
+- Calling a command over HTTP without the extension: `cratis-arc-command-execution`.
+- Observable query transports and their HTTP shapes: `cratis-arc-observable-query-http`.
+- Inspecting a Chronicle event store: the Chronicle CLI or Workbench guidance.

package/skills/cratis-performance-review/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-performance-review/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: cratis-performance-review
+description: Perform a focused scalability review of changed code in a Cratis application — Chronicle observers and replay, read-model query shape, command and query payloads, .NET enumeration, and React render cost — and report findings by risk. Use when asked to check for performance or scalability problems. Do not use for ordinary implementation and do not override the authoritative paging guidance.
+license: MIT
+---
+
+# Cratis performance review
+
+Most performance findings in a Cratis application are shape problems, not
+hot-loop problems: a projection that has to re-read, a query that materializes
+before it filters, a payload nobody uses. They are cheap to fix while the change
+is open and expensive once data has grown behind them.
+
+Two things make this stack different. **A projection must be able to replay the
+entire history** — a cost that is invisible at development volumes and fatal at
+production ones. And **an event is permanent**, so an oversized event is a
+storage and replay cost that never goes away.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Chronicle` | `16.45.2` | Observers, projections, reducers, reactors, replay |
+| `Cratis.Arc.Core` | `22.10.4` | Query return shapes and server-side paging |
+| `@cratis/components` | current | `DataTable` paging surface |
+
+Reverify against the owning product repository before asserting a framework
+behavior this file does not already state.
+
+## Route near misses
+
+- General correctness and maintainability: use `cratis-code-review`. Its
+  performance section is the pass-by list; this skill is the focused one. When
+  both have run, do not restate the same finding twice.
+- Adding paging to a query rather than judging one: use
+  `cratis-arc-query-paging`. That skill is authoritative on the mechanism; this
+  one does not override it.
+- Security or data exposure: use `cratis-security-review`. An over-fetching
+  payload is a finding for both — say which lens produced it.
+
+## Step 1 — Chronicle and event sourcing
+
+- **A projection joins on events, never on a read model.** A read-model join
+  forces a re-read the projection engine cannot optimize, and it makes the
+  projection depend on another observer's position.
+- **A reactor does not re-query the event log inside its handler.** The event it
+  received already carries what it needs. (Reactor dispatch is by the handler's
+  first parameter type — the method name is free, so look for the event-typed
+  parameter, not for a method called `On`.)
+- **A new projection can replay all historical events without failing.** Ask it
+  explicitly: at production volume, does this projection complete a full replay?
+- **Events are small.** No large blob and no base64 payload embedded in an
+  event; put the content elsewhere and carry a reference.
+- No eager load of a whole event sequence without paging or filtering.
+- AutoMap is on by default. Hand-mapping every property is both a maintenance
+  and a cost problem — and, since AutoMap runs anyway, it does not save the work
+  it appears to.
+
+## Step 2 — Read models and their store
+
+- Queries filter on indexed fields. An unintentional full-collection scan is the
+  most common finding here.
+- **A list that can grow returns `IQueryable<T>`**, so Arc applies server-side
+  paging and sorting. Materializing and then slicing in memory reads the whole
+  collection every request.
+- No N+1: one query returns what the caller needs.
+- A count is a count. Hydrating the collection to measure its length is the
+  same finding as an unpaged list, wearing different clothes.
+- A read model does not embed a large nested collection nothing fully iterates.
+
+## Step 3 — Commands and queries
+
+- A response payload carries only fields the client uses.
+- Command validators are synchronous and in-memory. Validation is on the hot
+  path of every attempt, including the ones that will be rejected — an I/O call
+  there is paid on every request.
+- No `await Task.Run(() => syncWork)` wrapping for work that is naturally
+  asynchronous.
+
+## Step 4 — .NET
+
+- No `.ToList()` before `.Where()`. Filter before materializing.
+- An `IEnumerable<T>` is not enumerated more than once — materialize once when
+  it must be reused.
+- Large-object logging uses the destructuring form only at `Debug` level, so a
+  production log level does not pay to serialize it.
+
+## Step 5 — React
+
+- A `DataTable` over a growable collection uses lazy loading and a paginator
+  rather than rendering every row.
+- No inline object or array literal passed as a prop: it is a new identity every
+  render and defeats memoization downstream.
+- `useEffect` dependencies are correct — neither missing nor over-broad. An
+  over-broad dependency array is a re-run per render, which reads as a
+  correctness bug and behaves as a performance one.
+- Components over large collections hold stable references or are memoized.
+- No `JSON.parse(JSON.stringify(x))` deep cloning.
+
+## Step 6 — Report
+
+Open with one line:
+
+> **Performance review: No issues / Minor findings / Blocking issues found**
+
+Group findings by the section that produced them, and classify each:
+
+| Risk | Meaning |
+| --- | --- |
+| **High** | Measurable degradation at moderate load — fix before merge |
+| **Medium** | Degrades under load or as data grows |
+| **Low** | Minor inefficiency |
+
+Close with a per-section summary table.
+
+**Say what the finding costs and at what scale.** "This is slow" is not
+actionable; "this scans the whole collection on every page load, so it is fine
+at hundreds of rows and not at tens of thousands" is. And **name what you did
+not measure** — a review of code shape is not a benchmark, and reporting it as
+one overstates the evidence.
+
+## What breaks
+
+- **A shape finding is reported as a measurement.** Reading code tells you the
+  shape; only running it tells you the cost. Say which one you have.
+- **The paging advice contradicts the paging skill.** `cratis-arc-query-paging`
+  is authoritative on the mechanism. Report the missing paging; do not invent an
+  alternative to it.
+- **A replay cost is judged at development volume.** A projection over a hundred
+  seeded events proves nothing about a replay over a production history.
+- **Every finding is High.** The classification is the value; when all findings
+  are urgent, none are.
+
+## How it is proven
+
+The build and specifications are green before the report is written; each
+finding cites the file and line and states the scale at which it bites; and the
+report says plainly that it reviewed code shape rather than measured behavior,
+naming anything that would need a benchmark to settle.

package/skills/cratis-screenplay-model-authoring/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

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

@@ -0,0 +1,231 @@
+---
+name: cratis-screenplay-model-authoring
+description: Author and verify a Cratis Screenplay `.play` event model — the file shape, the constructs the compiler actually accepts, the `screenplay` dotnet tool, and the gap between what parses and what any downstream runtime admits. Use when writing, reviewing, or compiling a `.play` file, or when deciding whether a construct is safe to model. Do not use for rendering a model into an application, and do not use for hand-written Arc or Chronicle C#.
+license: MIT
+---
+
+# Author a Screenplay `.play` model
+
+Screenplay is a declarative, indentation-based language that describes a whole
+event-sourced CQRS system in one document set: concepts, events, commands,
+queries, projections, screens and specifications. This repository owns the
+language and its compiler front end.
+
+⚠️ **Screenplay is experimental, and it is a front end.** It parses, validates
+and prints `.play` source, and binds a deliberately narrow subset to a versioned
+executable semantic model. **It does not generate, render or run an
+application.** Nothing in it emits C#, TypeScript or any target artifact — that
+is Stage's job, and Stage admits less than Screenplay parses. Author against that
+reality, not against the ecosystem diagram.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | The compiler: parser, syntax tree, validator, diagnostics, printer, semantic model |
+| `Cratis.Screenplay.Tool` | `4.12.1` | The `screenplay` dotnet tool |
+| `Cratis.Screenplay.CanonicalCorpus` | `4.12.1` | The frozen `RegisterProject` conformance vector downstream tools verify against |
+
+Behavior below is read from the repository at revision `7e2d91d`. Reverify before
+claiming another version behaves the same.
+
+## Verify a model
+
+```shell
+dotnet tool install -g Cratis.Screenplay.Tool
+screenplay                      # or: screenplay path/to/model
+```
+
+The tool takes **one positional argument** — a directory or a single `.play`
+file, defaulting to the current directory — plus `--no-color` and
+`--warnaserror`. That is the entire surface: no verbs, no `--help`, no
+`--version`, and no output or emit flag.
+
+⚠️ **It only verifies. It never writes anything.** A tool invocation that appears
+to have "generated" something did not.
+
+A directory is compiled as **one application**, recursively over `**/*.play`, so
+a name declared in one file resolves from another. A single file is compiled
+alone. Exit code is `1` when there is any error, or any warning under
+`--warnaserror`; otherwise `0`. Diagnostics print compiler-style with the
+offending line and a caret:
+
+```text
+<file>(<line>,<column>): error PLAY0042: <message>
+   42 | <the offending line>
+      |        ^
+```
+
+Codes run `PLAY0001` through `PLAY0276`. Embed the same compiler with
+`dotnet add package Cratis.Screenplay`.
+
+## The file shape
+
+Plain text, UTF-8, `.play`. Nesting is by **indentation** — no braces, no
+terminators. A construct owns everything indented beneath it. `//` starts a
+comment. Reserved words inside a block are escaped with a leading `@`.
+
+## What the compiler accepts
+
+These are the constructs the parser dispatches on, not a documentation summary.
+
+**Top level:** `domain`, `import`, `concept`, `type`, `policy`, `persona`,
+`authentication`, `module`, `seed`, `trigger`, `ui profile`, `theme`, `layout`.
+Anything else is `Unexpected '<word>' at the top level`.
+
+**Inside `module`:** `description`, `screen` (a screen template), `dialog` (a
+dialog template), `form`, `contribute`, `feature`.
+
+**Inside `feature`:** `description`, `feature` (nested to any depth), `slice`,
+`contribute`.
+
+**`slice <Type> <Name>`** takes one of four types — an unknown one is
+`Unknown slice type '<x>' - expected StateChange, StateView, Automation or
+Translate`:
+
+| Slice type | What it models | Constructs it carries |
+| --- | --- | --- |
+| `StateChange` | something changes the system | `command` → `event` via `produces`, with `validate`, `authorize`, `constraint` |
+| `StateView` | something reads the system | `readmodel`, `projection`, `query`, `screen` |
+| `Automation` | something runs when something happens | `reaction` |
+| `Translate` | outside data becomes events | `capture` |
+
+**Inside any slice:** `description`, `event`, `command`, `query`, `projection`,
+`capture`, `reaction`, `screen`, `constraint`, `specification`, `readmodel`,
+`reducer`. An unrecognised word here is a **warning**, not an error, and its
+block is skipped — a typo can silently drop a whole construct, so treat slice
+warnings as failures.
+
+A `concept` is based on one of `Uuid`, `String`, `Int`, `Decimal`, `Bool`,
+`Date`, `DateTime`, or `Enum` with its values indented beneath. Concepts carry
+`@pii` and `@sensitive` attributes and their own `validate` block, and every use
+of the concept inherits them.
+
+Projections are written in the Projection Declaration Language and captures in
+the Change Data Capture Language; both are sub-grammars of the same file, parsed
+by dedicated parsers rather than passed through as text.
+
+## A complete model
+
+This is the canonical conformance vector — the smallest complete program the
+whole toolchain is verified against, quoted from
+`Screenplay.CanonicalCorpus`'s `RegisterProject` source:
+
+```screenplay
+concept ProjectId : Uuid
+concept ProjectName : String
+module Projects
+  feature Registration
+    slice StateChange RegisterProject
+      command RegisterProject
+        projectId ProjectId identifier
+        name ProjectName
+        validate
+          name not empty message "Project name is required"
+        produces ProjectRegistered
+          for projectId
+          projectId = projectId
+          name = name
+      event ProjectRegistered
+        projectId ProjectId
+        name ProjectName
+      specification RegisteringAProject
+        when RegisterProject
+          projectId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+          name = "Screenplay"
+        then ProjectRegistered
+          projectId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+          name = "Screenplay"
+      specification RejectingAnEmptyProjectName
+        when RegisterProject
+          projectId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+          name = ""
+        then error "Project name is required"
+    slice StateView ProjectLookup
+      readmodel ProjectSummary
+        projectId ProjectId
+        name ProjectName
+      query ProjectById => ProjectSummary?
+        by projectId ProjectId
+      projection ProjectSummaryProjection => ProjectSummary
+        from ProjectRegistered key projectId
+          name = name
+```
+
+The same corpus ships as a NuGet package precisely so downstream tools verify
+against these exact bytes. When in doubt about a construct's shape, start from
+this file rather than from prose.
+
+The repository's own showcase, `invoicing.play`, is a 981-line file that parses
+with zero diagnostics and is pinned by 120 assertions. It is the
+best available reference for the wider language — policies, personas,
+authentication providers, composite `type` declarations, PDL joins, CDL captures,
+screens and triggers.
+
+## The boundary that matters: parsed is not admitted
+
+The parser accepts far more than anything can execute or render. Between the
+syntax tree and any runtime sits the **executable semantic model (ESM v1)**, and
+it fails closed.
+
+⚠️ `SemanticSliceKind` has exactly two members, `StateChange` and `StateView`.
+An `Automation` or `Translate` slice is rejected outright with
+`Slice '<name>' of type '<type>' is not admitted by ESM v1.` It parses, it
+validates, and it binds to nothing.
+
+Around forty further constructs bind to an `UnsupportedSemanticSyntax` error
+rather than a weaker model — imports, policies, personas, triggers, `authorize`,
+imperative `handler` bodies, code-backed `validate` rules, conditional
+`produces … when`, query filters and performers, non-`by` queries, non-scalar
+query results, `@pii`/`@sensitive` concepts, non-direct projection mappings,
+parent keys and `sequence` among them.
+
+The repository states the admitted set plainly: *"The minimum evaluator currently
+admits the RegisterProject-style vertical: `not empty` validation, unconditional
+event production, one affected read-model instance, optional snapshot lookup, and
+exact ordered specification results. Unsupported reachable capabilities block
+plan creation rather than producing a partial or stubbed execution."*
+
+So: model the wider language when the `.play` file is the artifact you want —
+documentation, review, a shared description of a system. Stay inside the
+RegisterProject vertical when the model has to reach a runtime. Never assume a
+construct works downstream because `screenplay` reported no diagnostics.
+
+## Editor support
+
+The language service ships two ways: the Monaco package
+`@cratis/screenplay-language`, and the VS Code extension `cratis.screenplay`
+(marketplace id `cratis.screenplay`), which is the same service plus a `.play`
+file icon.
+
+⚠️ Its keyword list has drifted from the parser. `theme`, `ui`, `form`,
+`contribute`, `dialog` and `reducer` appear nowhere in the Monaco package,
+although all six are real constructs the compiler accepts. They get no
+highlighting and no completion. Absent highlighting is not evidence that a
+construct is wrong — check `screenplay` instead.
+
+The repository's TypeScript workspaces are **not** built, linted or tested by any
+pull-request workflow; they run only inside the release job. Do not read a green
+pull request as evidence the language service still compiles.
+
+## Verify
+
+- `screenplay <model>` reports zero errors **and** zero warnings — an unknown
+  slice construct is only a warning and silently drops its block.
+- Every name referenced across files resolves when the whole folder is compiled,
+  not just the file being edited.
+- Concepts carrying personal data declare `@pii` with a reason, so the
+  classification travels with every use.
+- If the model is meant to reach a runtime, every slice is `StateChange` or
+  `StateView` and stays inside the admitted vertical.
+- Specifications express the intended behavior, including the rejection cases.
+
+## Route near misses
+
+- Turning a model into an application, or the runtime sandbox:
+  `cratis-stage-rendering-and-sandbox`.
+- Designing an event model as a diagram rather than as a `.play` file:
+  `cratis-event-model-diagram`.
+- Writing the Chronicle projections, reactors or read models by hand: the
+  Chronicle guidance.
+- Writing the Arc commands and queries by hand: `cratis-arc-command`.

package/skills/cratis-security-review/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.