@cratis/pi 7.125.2 → 7.127.0

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 an opaque name resolved where the application is provisioned.
+
+## 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 offering a new tenant starts on. Opaque; 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,106 @@
+---
+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`.
+
+## 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.
+- 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.

package/package/corpus/skills/cratis-showrunner-herald/references/templates-and-images.md

@@ -0,0 +1,70 @@
+# Templates and images
+
+## Layout
+
+```
+Emails/
+  invitation.json          the values the invitation email accepts
+  invitation.en.html       English
+  invitation.nb.html       Norwegian
+  images/
+    logo.png
+```
+
+## Manifest
+
+```json
+{
+  "values": [
+    { "name": "invitation.link", "required": true },
+    "invitation.expiresAt",
+    "inviter.name"
+  ]
+}
+```
+
+A plain string is an optional value. A required value that is missing or blank stops the email
+before it is queued. A name cannot be both a value and a group (`inviter` and `inviter.name`),
+and `look` is reserved for `look.brandColor` and `look.footer`.
+
+## Template
+
+A header between two `---` lines carries `subject` and optionally `preview`; both may use values.
+Then email-ready HTML.
+
+```html
+---
+subject: {{inviter.name}} invited you to Ledger
+preview: Accept the invitation before {{date invitation.expiresAt "d MMMM"}}
+---
+<html>
+<head><style>.button { background-color: {{look.brandColor}}; color: #ffffff; }</style></head>
+<body>
+  <table role="presentation" width="600" align="center"><tr><td>
+    <img src="cid:logo.png" alt="Ledger" width="120">
+    {{#if inviter.name}}<p>{{inviter.name}} invited you.</p>{{/if}}
+    <a class="button" href="{{invitation.link}}">Accept the invitation</a>
+    <p>{{look.footer}}</p>
+  </td></tr></table>
+</body>
+</html>
+```
+
+Author for email clients: table layout, about 600 px wide, `role="presentation"` on layout tables,
+an `alt` on every image. Write styles in a `<style>` element; Herald moves the rules into `style`
+attributes at render. Media queries stay in the element.
+
+## Rendering rules
+
+- Every value is HTML-encoded in the body, quotes in attributes included. Subject and preview are plain text and not encoded.
+- The subject is collapsed to one line. The plain-text alternative is generated from the HTML.
+- Dates are ISO 8601 and formatted in the culture of the email's language.
+- Language falls back from `nb-NO` to `nb` to `DefaultLanguage`; the language used is recorded.
+
+## Images
+
+Referenced as `cid:logo.png` and embedded inline, so nothing is hosted and no remote content has
+to be allowed. PNG, JPEG and GIF are embedded. SVG and anything else fail the rendering with an
+error naming the file, because mail clients do not render SVG; export a PNG at twice the display
+size. A referenced image that is missing also fails rendering. File names use letters, digits,
+dots, dashes and underscores and are looked up only inside the images folder.

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

@@ -89,8 +89,8 @@ before changing runner or package family.
 
 The plain `Specification` base is the universal foundation and the dominant mode
 in library and framework code. In applications, start pure decisions with a
-plain call, including direct validator calls, and add scenarios only for
-pipeline/authorization wiring, constraints, or declarative mapping. Keep shared lifecycle on; measure scenario cost using
+plain call, including direct validator calls, and add the scenarios the
+per-artifact decision table in `specs.scenarios.csharp.md` obligates. Keep shared lifecycle on; measure scenario cost using
 [running-specs.md](references/running-specs.md). Read
 [application-scenarios.md](references/application-scenarios.md) before using
 one. Out-of-process integration specifications are an advanced case reserved for

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/SKILL.md

@@ -206,6 +206,11 @@ generated application: API on `9090`, Workbench on `https://localhost:35000`.
 Requires Cratis CLI 3.73.0 for the semantic engine by default, 3.75.0 for v27 keys;
 older CLIs use the legacy EventModel engine, which does not enforce authorization.
 Unsigned caller headers make sandbox authorization no security boundary.
+A model with `authentication` makes `cratis run` start a stack instead: AuthProxy (the
+address to open), the Stage with `Stage__Sandbox__ForwardedIdentity=true` so it trusts the
+forwarded identity instead of playing a persona, and with `onboarding` Ante and MongoDB.
+`cratis render` realizes authentication and onboarding (`references/rendered-application.md`).
+Requires cratis CLI 3.116.0 (`cratis --version`); older CLIs run the Stage alone and play a persona.
 Read [references/sandbox-and-specrunner.md](references/sandbox-and-specrunner.md)
 before running either image: engine selection, protected reads, outside-append
 conflicts/retries, reached bodies, authored occurrence and generated-spec limits live there.