@cratis/pi 7.126.0 → 7.128.0

package/package/corpus/skills/cratis-onboarding-runtime/references/sign-up-review.md

@@ -0,0 +1,52 @@
+# Sign-up review
+
+Requires Ante 1.6.0 or later (`Ante:Registration:Review`, `RegistrationReview` in the onboarding
+contract). Older releases complete every sign-up without a decision and publish neither event
+below.
+
+Review is off by default and changes nothing while off. Turn it on when a person must be approved
+before an organization is created.
+
+## Flow
+
+1. A person finishes the sign-up. With review on, Ante accepts it but holds it: no
+   `OrganizationRegistrationCompleted` is published and the registration is not complete.
+2. Ante publishes `OrganizationRegistrationAwaitingReview` to its outbox, once per registration, on
+   the registration id. It carries the same details `OrganizationRegistrationCompleted` would carry:
+   the organization name asked for, the contact address (can be empty, never verified), the names,
+   the sign-in subject and provider, and the untrusted sign-up context.
+3. The host shows the sign-up to its reviewers. Ante has no administrator screen and takes no
+   decision itself.
+4. The host appends one of these to **its own store's outbox**, with the registration id as the
+   event source id:
+   - `OrganizationRegistrationApproved`: Ante completes the registration as it would have without
+     review and publishes `OrganizationRegistrationCompleted`.
+   - `OrganizationRegistrationDeclineRequested(Message)`: Ante publishes
+     `OrganizationRegistrationDeclined` with the contact address, the name the person gave and the
+     reviewer's message. `Message` is required; a blank one is refused and nothing is published.
+
+## Rules
+
+- A registration is decided once. A decision for a registration that was completed, was already
+  declined or was never held is ignored, so redelivery is safe and a completed registration is
+  never declined afterwards.
+- Deduplicate `OrganizationRegistrationAwaitingReview` by registration id, like every Ante outcome:
+  delivery is at least once.
+- If an approved registration's organization name was claimed by someone else while it waited, it
+  stays held and Ante logs a warning. Decline it with a message instead.
+- While a sign-up is held the lobby tells the person it is waiting for review; after a decline it
+  says the sign-up was not approved, stops polling and offers no second submission.
+- Ante emails no one. The host sends the person the declined message from
+  `OrganizationRegistrationDeclined` (Herald, `signupDeclined` template with `decline.message`).
+- `OrganizationRegistrationDeclined` is the only outcome that says a person was turned down.
+  `InvitationRejected` says an invitation did not match what the host allows; treat it as a
+  configuration problem for whoever issued the invitation.
+
+## Verify
+
+1. With review on, a sign-up produces `OrganizationRegistrationAwaitingReview` and no
+   `OrganizationRegistrationCompleted`.
+2. Appending `OrganizationRegistrationApproved` on the registration id produces
+   `OrganizationRegistrationCompleted`; appending it again produces nothing.
+3. A decline request with a blank message publishes nothing; with a message it publishes
+   `OrganizationRegistrationDeclined` once.

package/package/corpus/skills/cratis-screenplay-authentication-and-onboarding/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.
+
+Third-party notices
+
+This skill adapts material from agentic-engineer by Martin Dilger and Nebulit GmbH
+(https://github.com/Nebulit-GmbH/agentic-engineer, commit 07b0f30648d663cb588d7e2c7aa031af9dfc21f2;
+https://nebulit.de), used with the explicit consent of Martin Dilger and Nebulit GmbH. The adapted
+material remains credited to Martin Dilger and Nebulit GmbH.

package/package/corpus/skills/cratis-screenplay-authentication-and-onboarding/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: cratis-screenplay-authentication-and-onboarding
+description: Use when a `.play` model declares how users sign in or get into an application, meaning `authentication` providers, the `onboarding` block (signup, invitations, legal terms, emails) or the environment keys a provider or mail server needs. Not for personas and policies, or for running the application.
+license: MIT
+---
+
+# Screenplay authentication and onboarding
+
+Two top-level blocks say how people reach an application. `authentication` names the identity
+providers. `onboarding` says how people get in: self-signup, who invites whom, which terms they
+accept and which emails they receive. Both are authoring metadata, not executable behavior: the
+reference evaluator does not run them, and whatever runs the application provisions them.
+
+**Requires** Screenplay 4.259.0 or later for `onboarding`, the environment key listing and its
+diagnostics (`screenplay --version`; the compiler bundled in `cratis` may be older). Older
+releases reject the block as an unknown top-level construct.
+
+## The line the model never crosses
+
+The model is the same document in every environment. A client id, a client secret, an authority,
+a sender address, a mail server and its password differ per environment, so none of them appears
+in the model. A configuration line under a provider is a compile error (`PLAY0183`), not an
+ignored line. The model refers to a value by a **key derived from its declarations**, and the
+environment supplies the value. Never add the value to the model to "make it render". Creating
+and filling the environment is [cratis-environments-and-secrets](../cratis-environments-and-secrets/SKILL.md).
+
+## `authentication`
+
+```text
+authentication
+  provider EntraId
+  provider GitHub
+  provider OpenId name Partner
+  provider OpenId name Supplier
+```
+
+- At most one block for the application (`PLAY0125`); the line carries only the keyword (`PLAY0124`).
+- Providers are `EntraId`, `GitHub`, `Google`, `Apple` and `OpenId`.
+- A provider's **identity** is its `name` alias when it has one, otherwise the provider name.
+  Two entries with one identity are `PLAY0169`, so two `OpenId` providers each need a `name`.
+- Typed information about the caller is the separate `identity` block, not part of `authentication`.
+
+## `onboarding`
+
+```text
+onboarding
+  signup open creates tenant
+  invite tenant as Owner
+  invite member
+    by Owner, Administrator
+    grant Accountant, InvoiceManager
+  legal terms
+    file Legal/terms-of-service.md
+    file Legal/privacy-policy.md
+  offering Starter
+  emails
+    invitation file Emails/invitation.html
+    welcome file Emails/welcome.html
+    signupDeclined file Emails/signup-declined.html
+    images Emails/Images
+```
+
+Read [onboarding directives](references/onboarding-directives.md) before writing or reviewing a
+block. The diagnostics for each rule are in that reference. The rules that decide most mistakes:
+
+- It needs `authentication` in the same application, and there is at most one block.
+- Every line is optional and appears once. Anything that is not a directive is a compile error.
+- **No `signup` line means self-signup is off**; every newcomer arrives by invitation.
+  `signup open creates tenant` makes a signup create a tenant, `signup open joins tenant` asks to join an existing one.
+- Every persona in `as`, `by` and `grant` must be declared with `persona`; there are no free-text roles.
+- `emails` names only `invitation`, `welcome` and `signupDeclined`. The sender and mail server are not in the model.
+- `file` paths are repository-relative, like handler files. `offering` is the name of an offer the operator publishes in Box Office; a rendered application starts each new tenant on it. `signupDeclined` is sent when the host declines a held sign-up (review is not modeled; see `cratis-onboarding-runtime`).
+
+## Environment keys
+
+Every key is derived from a declaration, so nothing is configured twice. Keys are dotted,
+case-sensitive paths.
+
+| Declaration | Keys | Secret |
+|---|---|---|
+| each provider | `authentication.providers.<Identity>.clientId` | no |
+| each provider | `authentication.providers.<Identity>.clientSecret` | **yes** |
+| `EntraId` | `authentication.providers.<Identity>.tenantId` | no |
+| `OpenId` | `authentication.providers.<Identity>.authority` | no |
+| `onboarding` | `onboarding.email.sender`, `onboarding.email.server.host`, `.port`, `.username` | no |
+| `onboarding` | `onboarding.email.server.password` | **yes** |
+
+List the keys for the model instead of working them out by hand:
+
+```bash
+screenplay environment ./model                 # one key per line, secrets marked "(secret)"
+screenplay environment ./model --format json   # key, secret, source, owner, description
+```
+
+Pass the folder, not one file. It exits `0` when it listed keys, `1` when the model does not
+compile (it lists nothing) and `2` when it could not run. Compare an environment with the model's
+keys using `cratis config --missing <path>`, which exits `5` when any key is absent.
+
+## Verify
+
+1. `screenplay <folder> --warnaserror` exits `0` with none of the diagnostics in the directives reference.
+2. The key listing for the folder contains exactly the keys the table above predicts for the providers and the `onboarding` block.
+3. `grep -rn -i -E "clientSecret|password|authority" <folder>` finds no value in any `.play` file.
+
+## Route near misses
+
+- Personas, policies and `require`: `cratis-screenplay-command-surface`.
+- Choosing a compiler and reading verdicts: `cratis-screenplay-toolchain`.
+- Creating an environment, setting a secret: `cratis-environments-and-secrets`.
+- How AuthProxy, Ante and Herald consume the contract at runtime: `cratis-onboarding-runtime`.
+- How an Arc application trusts the proxy: `cratis-arc-authentication-authorization-and-identity`.

package/package/corpus/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md

@@ -0,0 +1,89 @@
+# Onboarding directives
+
+A complete model: personas are declared before the blocks name them.
+
+```text
+policy IsOwner
+  require role "Owner"
+
+policy IsAdministrator
+  require role "Administrator"
+
+policy IsAccountant
+  require role "Accountant"
+
+policy IsInvoiceManager
+  require role "InvoiceManager"
+
+persona Owner
+  description "Owns the tenant"
+  goal "Run the tenant"
+  policy IsOwner
+
+persona Administrator
+  description "Administers the tenant"
+  goal "Keep people onboarded"
+  policy IsAdministrator
+
+persona Accountant
+  description "Keeps the books"
+  goal "Keep the books correct"
+  policy IsAccountant
+
+persona InvoiceManager
+  description "Manages invoices"
+  goal "Keep invoices moving"
+  policy IsInvoiceManager
+
+authentication
+  provider EntraId
+  provider GitHub
+  provider OpenId name Partner
+  provider OpenId name Supplier
+
+onboarding
+  signup open creates tenant
+  invite tenant as Owner
+  invite member
+    by Owner, Administrator
+    grant Accountant, InvoiceManager
+  legal terms
+    file Legal/terms-of-service.md
+    file Legal/privacy-policy.md
+  offering Starter
+  emails
+    invitation file Emails/invitation.html
+    welcome file Emails/welcome.html
+    signupDeclined file Emails/signup-declined.html
+    images Emails/Images
+```
+
+Syntax and meaning of each line of the `onboarding` block. All lines are optional and each may appear once.
+
+| Directive | Form | Meaning |
+|---|---|---|
+| `signup` | `signup open creates tenant` or `signup open joins tenant` | Anyone may sign up; signing up creates a tenant or asks to join one. Absent: signup is off. |
+| `invite tenant` | `invite tenant as <Persona>` | An invitation that creates a tenant; the invitee becomes the persona in it. One line, no body. |
+| `invite member` | body with `by <Persona>, ...` and `grant <Persona>, ...` | An invitation into an existing tenant. `by` lists who may send it, `grant` what the invitee is given. Both are required. |
+| `legal terms` | body of `file <path>` lines | Documents a newcomer must accept. Present means acceptance is required. |
+| `offering` | `offering <Id>` | The Box Office offer a new tenant starts on. Absent means no licensing. |
+| `emails` | body of `<email> file <path>` lines and `images <folder>` | Templates for `invitation`, `welcome` and `signupDeclined`, and the folder they take images from. |
+
+## What the block deliberately lacks
+
+No sender address, mail server, credentials or price. Those are environment values (see the key
+table in `SKILL.md`). Languages for the emails follow the cultures of the model's `.strings` files.
+
+## Diagnostics
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `PLAY0826` | The `onboarding` line carries more than the keyword. | Move content into the body. |
+| `PLAY0827` | More than one `onboarding` block. | Merge them. |
+| `PLAY0828` | `onboarding` without `authentication`. | Declare the providers. Draft authoring reports a warning until the folder is assembled. |
+| `PLAY0829` | A line is not a directive, or one is malformed or incomplete. | Use the forms above. |
+| `PLAY0830` | A directive stated twice. | Keep one. |
+| `PLAY0831` | An invitation names a persona nothing declares. | Declare it with `persona`. |
+| `PLAY0832` | `emails` names an email onboarding does not send. | Use `invitation`, `welcome` or `signupDeclined`. |
+
+A missing `file` target is reported like a missing handler file: an attachment warning when files are loaded.

package/package/corpus/skills/cratis-screenplay-authentication-and-onboarding/verification.json

@@ -0,0 +1,32 @@
+{
+  "skill": "cratis-screenplay-authentication-and-onboarding",
+  "input": "Declare how people sign in and get into a Screenplay application, and say which environment keys it needs.",
+  "fixtures": [],
+  "assertions": [
+    {
+      "kind": "skill-contains",
+      "value": "PLAY0183"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "authentication.providers.<Identity>.clientSecret"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "onboarding.email.server.password"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "screenplay environment ./model --format json"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "No `signup` line means self-signup is off"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "| `PLAY0832` |",
+      "file": "references/onboarding-directives.md"
+    }
+  ]
+}

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

@@ -35,6 +35,7 @@ a second (`PLAY0441`) — **or** one implementation (a tagged ` ```csharp ` bloc
 runner; a code policy binds as opaque ESM v3 and needs a target to evaluate it.
 A `persona` is authoring metadata: the binder reports it as information `PLAY0270`
 (report-only) and it does not block binding; an unknown policy it lists is an error.
+Personas an `onboarding` block invites or grants must be declared here; see `cratis-screenplay-authentication-and-onboarding`.
 
 ## Anonymous policy
 

package/package/corpus/skills/cratis-screenplay-model-authoring/references/language-reference.md

@@ -261,7 +261,7 @@ See read-surface `references/named-keys.md` for the collection-key exclusion alg
 | Binds as ESM v6 (`PLAY0268` on a compiler that stops before v6) | `Automation` and `Translate` slices, reactions that produce or invoke, captures, top-level `trigger`, clock, trigger and capture specifications. The standalone `screenplay test`/MCP reference route evaluates admitted v6 actions; Stage renders supported event-triggered Automation, with remaining refusals in the Stage skill's `references/admission.md` |
 | Reaction with trigger `reads` | Direct-producing (or code-bodied) reaction with `reads`: `PLAY0268` ("ESM v6 cannot protect that decision dependency"), non-executable. Invokes-only reaction with `reads`: information only; the invoked command must declare and protect its own decision reads. Keep the `reads`; never remove them to obtain binding |
 | Binds as opaque code (v3); reference runner reports unsupported | Bodied reducers, bodied named rules, fenced `validate` blocks, code or file policies. A pure reducer body is the only attachment Stage admits |
-| Information only, never blocks | `persona` (report-only: `PLAY0270`, the policies it lists must exist), `authentication`, `domain`, `seed`, descriptions and `file` provenance. A persona does not block binding and does not change behavior, so state persona scope in a description or a policy the model uses |
+| Information only, never blocks | `persona` (report-only: `PLAY0270`, the policies it lists must exist), `authentication`, `onboarding` (see `cratis-screenplay-authentication-and-onboarding`), `domain`, `seed`, descriptions and `file` provenance. A persona does not block binding and does not change behavior, so state persona scope in a description or a policy the model uses |
 | Binds as ESM v7 (`PLAY0268` on a compiler that stops before v7) | `generated` properties and `returns` responses, generated fixtures and `then returns`: bound and executed by the reference runner; a policy, rule or requirement that references a generated value is `PLAY0273`, and generated-concept rules select v20 with PLAY0688/0689 proof diagnostics. Stage renders supported UUID/String strategies, scalar/named responses and fixtures; unsupported types/result combinations remain `-028`/`-038` |
 | Authorable, not executable (PLAY0268) | Systems/operations, the `numbers exact` source mode (PLAY0268; exact lowering of qualifying Double literals is the admitted v11) remain unadmitted |
 | Concept generation strategies (ESM v15) | Required scalar generatable Uuid/String concepts; concept-owned uuid/uuidv7/ulid/typeid/nanoid/bytes strategies and admitted modifiers. Strict fixture encoding; Guarded whole-source freshness rejects Concurrency with no append/retry. Generated secrets and sequence remain refused; generated-concept rules select v20, pattern/random/rule and checksum validation select v21. Stage renders supported strategies: command-surface `references/generated-values-and-responses.md` |

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

@@ -97,6 +97,8 @@ model's behalf.
     mode in a design model is a recorded gap, not a defect to delete. Removing protection
     (`pii`, authorization, rules) to pass a tool is always a critical finding.
     Protection and reaction-privilege checks: [mode compliance](references/mode-compliance.md).
+    A client id, secret, authority, sender or mail server in a model is a critical finding: those
+    belong in the environment (`cratis-screenplay-authentication-and-onboarding`).
 12. **Root causes, classify, report** (`references/report-template.md`). Group findings that share
     a declaration; report the root cause with its symptoms under it; severity critical, major or
     minor; kind defect, question or note; verdict with confidence. Never apply changes.

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/renderability-gate.md

@@ -60,6 +60,14 @@ Requires Stage 4.138.0 for the Cratis renderer to render protected reads.
 - Admission can pass and a Debug test still fail. Admission is never a passing test; see
   `cratis-stage-rendering-and-sandbox` `references/render-example.md`.
 
+## Authentication and onboarding are realized
+A model's `authentication` and `onboarding` blocks are rendered by Stage (AuthProxy and Ante
+configuration, personas, provisioning, emails); do not gap-fill them by hand
+(`cratis-stage-rendering-and-sandbox` `references/rendered-application.md`). A provider kind
+AuthProxy does not support is left out of the render with the warning `STAGE-AUTH-001`; the
+render still publishes, so report it as a model decision, not as a hand-written provider.
+Requires cratis CLI 3.116.0 with Stage 4.211.0 (`cratis --version`); older releases report `authentication` and `onboarding` as unrendered warnings.
+
 ## Stage issues to cite in fallback record entries
 Historical issue pointers (not a fresh issue-state check): portable query semantics Stage#58;
 Translate and unsupported automation forms Stage#79; mapping expressions and projection blocks Stage#117; modeled authentication

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

@@ -7,6 +7,8 @@ Which skill owns each task next to the toolchain.
 - Construct depth: `cratis-screenplay-command-surface`, `cratis-screenplay-projections`,
   `cratis-screenplay-read-surface`, `cratis-screenplay-captures-and-reactions`,
   `cratis-screenplay-specifications`, `cratis-screenplay-ui-composition`.
+- Sign-in providers, onboarding and the environment keys a model needs: `cratis-screenplay-authentication-and-onboarding`;
+  creating the environment and setting secrets: `cratis-environments-and-secrets`.
 - Rendering and gap-fill: `cratis-screenplay-render-and-gap-fill`,
   `cratis-stage-rendering-and-sandbox`.
 - Running systems (Chronicle server operations through the `cratis` CLI, with its authorization boundaries): `cratis-chronicle-cli-operations`.

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

@@ -26,5 +26,75 @@
     "kind": "diagnostic",
     "value": "PLAY0686",
     "reason": "Explicit retirement notice, not an active diagnostic or repair recommendation. The published contract marks PLAY0686 retired. Remove when this notice is removed or replaced."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/SKILL.md",
+    "text": "screenplay environment ./model                 # one key per line, secrets marked \"(secret)\"",
+    "kind": "cliCommand",
+    "value": "environment",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/SKILL.md",
+    "text": "screenplay environment ./model --format json   # key, secret, source, owner, description",
+    "kind": "cliCommand",
+    "value": "environment",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/SKILL.md",
+    "text": "screenplay environment ./model --format json   # key, secret, source, owner, description",
+    "kind": "cliOption",
+    "value": "--format",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0826` | The `onboarding` line carries more than the keyword. | Move content into the body. |",
+    "kind": "diagnostic",
+    "value": "PLAY0826",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0827` | More than one `onboarding` block. | Merge them. |",
+    "kind": "diagnostic",
+    "value": "PLAY0827",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0828` | `onboarding` without `authentication`. | Declare the providers. Draft authoring reports a warning until the folder is assembled. |",
+    "kind": "diagnostic",
+    "value": "PLAY0828",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0829` | A line is not a directive, or one is malformed or incomplete. | Use the forms above. |",
+    "kind": "diagnostic",
+    "value": "PLAY0829",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0830` | A directive stated twice. | Keep one. |",
+    "kind": "diagnostic",
+    "value": "PLAY0830",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0831` | An invitation names a persona nothing declares. | Declare it with `persona`. |",
+    "kind": "diagnostic",
+    "value": "PLAY0831",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
+  },
+  {
+    "file": ".cratis/ai/skills/cratis-screenplay-authentication-and-onboarding/references/onboarding-directives.md",
+    "text": "| `PLAY0832` | `emails` names an email onboarding does not send. | Use `invitation`, `welcome` or `signupDeclined`. |",
+    "kind": "diagnostic",
+    "value": "PLAY0832",
+    "reason": "Documents the onboarding and environment-key surface of Screenplay 4.259.0, which the pinned 4.245.0 contract predates. Remove when the pinned contract moves to 4.259.0 or later (the check then reports it unnecessary)."
   }
 ]

package/package/corpus/skills/cratis-showrunner-herald/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.
+
+Third-party notices
+
+This skill adapts material from agentic-engineer by Martin Dilger and Nebulit GmbH
+(https://github.com/Nebulit-GmbH/agentic-engineer, commit 07b0f30648d663cb588d7e2c7aa031af9dfc21f2;
+https://nebulit.de), used with the explicit consent of Martin Dilger and Nebulit GmbH. The adapted
+material remains credited to Martin Dilger and Nebulit GmbH.

package/package/corpus/skills/cratis-showrunner-herald/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: cratis-showrunner-herald
+description: Use when a Cratis .NET application sends email such as invitations or welcome messages with Herald (`Cratis.Showrunner.Herald`), including `AddHerald`, `IEmails`, email templates and images, SMTP or the development folder transport. Not for a custom SMTP client or for Ante's token issuance.
+license: MIT
+---
+
+# Herald email
+
+Herald sends the email an application needs from template and image files, and records every
+email as a fact. It is a **library** that runs in the application's process and keeps its state
+as events in the application's own Chronicle event store. It is not a service.
+
+**Requires** `Cratis.Showrunner.Herald` 1.10.0 or later and an application that is a Chronicle
+client (`AddCratis` or `AddCratisChronicle`); check the package reference in the `.csproj`.
+Herald records in the host application's own event store, without naming it again; set
+`HeraldOptions.EventStore` only to use another store. Showrunner 1.13.0 or later takes the host's
+store; an older release takes the name from the Chronicle client options, which an ASP.NET Core
+host leaves empty, so set `EventStore` explicitly there.
+
+## Add it
+
+```csharp
+builder.AddCratis();
+builder.AddHerald(herald =>
+{
+    herald.TemplatesFolder = Path.Combine(builder.Environment.ContentRootPath, "Emails");
+    herald.ImagesFolder = Path.Combine(builder.Environment.ContentRootPath, "Emails", "images");
+    herald.Sender = new() { Address = builder.Configuration["Herald:Sender"]!, Name = "Ledger" };
+    herald.Smtp = new()
+    {
+        Host = builder.Configuration["Herald:SmtpHost"]!,
+        Port = 587,
+        Security = SmtpSecurity.StartTls,
+        UserName = builder.Configuration["Herald:SmtpUserName"]!,
+        Password = builder.Configuration["Herald:SmtpPassword"]!
+    };
+});
+```
+
+- **Take the sender, host, user name and password from configuration, never literals.** For a
+  Screenplay application these are the `onboarding.email.*` environment values (see
+  [cratis-environments-and-secrets](../cratis-environments-and-secrets/SKILL.md)), and the
+  password is a secret that never enters source, a log, an event or the transcript.
+- `TemplatesFolder` is required and must exist; `Sender.Address` is required. Options are
+  validated at startup and the error names the option.
+- Defaults worth knowing: `DefaultLanguage` `en`, `Transport` `Smtp`, `Smtp.Security` `StartTls`,
+  `Retry.MaxAttempts` 6, `PollingInterval` 5 seconds. Read [options](references/options.md) for the full table.
+- A `signupDeclined` email is sent from `OrganizationRegistrationDeclined` with the reviewer's message as a value; see `cratis-onboarding-runtime`.
+- Chronicle finds Herald's events through type discovery of referenced `Cratis*` packages.
+- Run the worker in **one** application instance: delivery is at least once.
+
+## Send
+
+```csharp
+await emails.Send(new EmailRequest(
+    Kind: "invitation",
+    About: context.EventSourceId,
+    To: @event.Email,
+    Values: new Dictionary<string, string> { ["invitation.link"] = @event.Link })
+{
+    ToName = @event.Name,
+    Language = @event.Language
+});
+```
+
+Send from where the decision is made: a reactor on the fact that an invitation was issued, or an
+Arc command. `Send` renders first and throws `EmailCannotBeRendered` without queuing anything when
+a template, value or image is wrong; otherwise it appends `EmailQueued` against `About`, returns
+the `EmailId` and does not wait for the server. Pass the compliance `Subject` so erasing the
+person erases the recipient and any link that works as a credential. Report a bounce with
+`emails.Bounced(about, emailId, kind, reason)` and leave the address out of the reason.
+
+## Templates and images
+
+A kind is lowercase letters, digits and dashes. The folder holds `{kind}.json` (the manifest of
+accepted values) and `{kind}.{language}.html` per language. Read
+[templates and images](references/templates-and-images.md) before writing either.
+
+- Templates are strict Handlebars with only `{{value}}`, `{{#if value}}…{{else}}…{{/if}}` and `{{date value "format"}}`. Triple braces, partials and other helpers are refused.
+- A value the manifest does not declare is an error, never an empty space. Every value is HTML-encoded.
+- Images are PNG, JPEG or GIF referenced as `cid:name.png`. **SVG is refused**; export a PNG.
+
+## Facts and delivery
+
+`EmailSent`, `EmailFailed` and `EmailBounced` are in `Cratis.Showrunner.Herald.Contracts`, carry
+the `EmailId`, and never the recipient or a value; project and react to them. They are not
+`[Public]`: they live in the event log so the application's own projections can follow them.
+`EmailQueued` and `EmailAttemptFailed` are Herald's own. A change to a released event is a new generation, not an edit.
+
+For development set `Transport = EmailTransportKind.Folder` and `PickupFolder`; each email is
+written as an `.eml` file and nothing leaves the machine. To send through a provider API, register
+a custom `IEmailTransport` before `AddHerald`.
+
+## Pitfalls
+
+- Hard-coding the SMTP password in `AddHerald` or committing it: read it from configuration or the environment.
+- Sending a new kind without its manifest, or with a value the manifest lacks: `EmailCannotBeRendered`.
+- Putting a remote `https://` image in a template: use `cid:`.
+- Running two worker instances: duplicate deliveries.
+
+## Verify
+
+1. `dotnet build` is clean and the host starts: option errors surface at startup naming the option.
+2. With the `Folder` transport, send one email in a spec or locally and open the `.eml`: the subject, plain-text alternative and embedded image are present.
+3. The event log has `EmailQueued` then `EmailSent` against the `About` id.
+
+## Route near misses
+
+- Events, reactors and projections that call Herald: `cratis-chronicle-reactor`, `cratis-chronicle-projection`.
+- Invitation tokens, the lobby and acceptance: `cratis-onboarding-runtime`.
+- Erasing personal data: `cratis-chronicle-compliance`.

package/package/corpus/skills/cratis-showrunner-herald/references/options.md

@@ -0,0 +1,35 @@
+# Herald options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `TemplatesFolder` | required | Folder with the templates; must exist. |
+| `ImagesFolder` | none | Folder with the images; optional when no template has an image. |
+| `DefaultLanguage` | `en` | Language used when no template exists in the language asked for. |
+| `Sender.Address` | required | The address the emails come from. |
+| `Sender.Name`, `Sender.ReplyTo` | empty | Display name; where replies go. |
+| `Look.BrandColor` | `#2563eb` | Button and link color as `#rrggbb`; templates use `{{look.brandColor}}`. |
+| `Look.Footer` | empty | Shared footer; templates use `{{look.footer}}`. |
+| `Transport` | `Smtp` | `Smtp`, or `Folder` to write `.eml` files. |
+| `Smtp.Host`, `Smtp.Port` | none, `587` | The mail server. |
+| `Smtp.Security` | `StartTls` | `StartTls` (587), `Tls` (465) or `None` (a relay on the same machine or network). |
+| `Smtp.UserName`, `Smtp.Password` | empty | Sign-in; leave both empty for an open relay. The password is a secret. |
+| `PickupFolder` | none | Where the `Folder` transport writes. |
+| `Retry.MaxAttempts` | `6` | Deliveries tried before the email fails for good. |
+| `Retry.InitialDelay`, `Retry.MaxDelay` | 30 s, 1 h | Wait after the first failure, doubling up to the maximum. |
+| `PollingInterval` | 5 s | How often queued emails that are due are looked for. |
+| `Namespace` | default namespace | Event store namespace for the facts. |
+
+The server certificate is always validated; there is no switch to turn it off.
+
+## Failure handling
+
+| What happened | Result |
+|---|---|
+| Server unreachable, sign-in refused, timeout | `EmailAttemptFailed`, retried with growing delay. A bad sign-in is retried because it can be fixed while the email waits. |
+| Server refuses message or recipient for good (550 to 554) | `EmailFailed` at once. |
+| Last allowed attempt fails | `EmailFailed` with the attempt count. |
+| Template or image gone when due | `EmailFailed` with zero attempts. |
+
+Failure reasons are sentences Herald wrote, with the password and recipient address removed. An
+unexpected failure is recorded by its kind only. Which emails are waiting comes from the event
+log; the `QueuedEmail` read model lists emails with no outcome yet, for a count.