@cratis/pi 7.125.2 → 7.127.0

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/authproxy.md

@@ -49,6 +49,32 @@ is a crawler policy, not authorization. Invitation error-page tokens
 letters, digits and `._+-@`; do not assume these placeholders always contain text.
 Signed-in `/register` forwarding needs no host workaround.
 
+## Starting AuthProxy from a Screenplay application's contract
+
+Requires AuthProxy 2.40.0 or later for `Cratis:AuthProxy:Application`; an older image ignores it and starts with no providers.
+
+AuthProxy can start from two inputs: the **provider list** of a Screenplay model (kind and identity per provider) and the **values of a Cratis environment**. It translates them onto its ordinary `Cratis:AuthProxy` options, so an application behind it trusts the proxy exactly as described above. The model never carries provider configuration; see `cratis-screenplay-authentication-and-onboarding` for the keys and `cratis-environments-and-secrets` for the values.
+
+```json
+{
+  "Cratis": { "AuthProxy": { "Application": {
+    "EnvironmentName": "production",
+    "Providers": [
+      { "Kind": "EntraId", "Identity": "EntraId" },
+      { "Kind": "OpenId", "Identity": "Partner" }
+    ]
+  } } }
+}
+```
+
+- A provider's `Kind` is `EntraId`, `GitHub`, `Google`, `Apple` or `OpenId`; `Identity` is the model's alias, otherwise the provider name, unique ignoring case. The identity is also the scheme (lowercase, spaces to hyphens), so the callback is `/signin-<scheme>`.
+- Required keys per kind: `clientId` and `clientSecret` for all; plus `tenantId` for `EntraId` and `authority` for `OpenId`. Each is addressed as `authentication.providers.<Identity>.<key>`.
+- The contract cannot be combined with providers configured directly under `Authentication:OidcProviders` or `OAuthProviders`; AuthProxy refuses to start.
+- A missing required key stops AuthProxy before it listens (exit code 78), naming the key, provider and environment, never a value.
+- **Secrets are never read from arguments and never logged.** A key resolves from `Cratis:AuthProxy:Application:Environment:<key>`, then the same key with `_FILE` appended (a path to a file holding the value), then a file named exactly `<key>` in `SecretsDirectory`. Mount secrets as files and point `SecretsDirectory` at the folder; do not put a secret in an environment variable or an image.
+- `Application:Development=true` allows HTTP only on loopback addresses; every other URL must be HTTPS. Never set it outside local development.
+- With `Application:Onboarding=true`, supply the `onboarding.*` keys for the application's own Ante and every provider also gets invitation completion; see `cratis-onboarding-runtime`.
+
 ## Tenants and services
 
 AuthProxy resolves the tenant through ordered strategies under `Cratis:AuthProxy:TenantResolutions` (`Host`, `Claim`, `Route`, `Specified`, `Default`, `SubHost`, `Selection`). The result reaches the backend as `x-cratis-tenant-id`, which is Arc's default tenant header, so an Arc application behind AuthProxy needs no tenancy configuration and the `UseHeaderTenancy("Tenant-ID")` workaround seen in older applications can be removed.

package/package/corpus/skills/cratis-arc-command/SKILL.md

@@ -274,10 +274,13 @@ Components guidance, not to this skill.
 
 ## Verify
 
-Start pure `Handle()` and validator decisions with direct calls and supplied
-read-model state. Add scenarios only for pipeline/authorization wiring,
-constraints, never read-protection plumbing or simulated concurrency;
-follow the [scenario selection and cost rule](../../rules/specs.scenarios.csharp.md).
+Keep `Handle` a pure function of the command, its read-model parameters and
+provided values: that makes it specifiable by a plain call. Start `Handle()` and
+validator decisions with direct calls and supplied read-model state. Add the
+pipeline scenario plus a negative proof per authorization policy, validator
+rejection and `Provide()` short-circuit, and a constraint scenario; never
+read-protection plumbing or simulated concurrency. Follow the
+[decision table](../../rules/specs.scenarios.csharp.md).
 
 - The command is a `record`, carries `[Command]`, and declares a public instance
   `Handle`.

package/package/corpus/skills/cratis-chronicle-event-specifications/SKILL.md

@@ -10,6 +10,11 @@ license: MIT
 database, no network — an empty event log at sequence number zero, with the
 application's constraints discovered and active.
 
+Specify every constraint with an `EventScenario`: one class for the violation
+and one for the nearest non-violation. A constraint is enforced at append, so no
+plain call or substituted event store proves it. Pure decisions around it are
+plain calls; see the [decision table](../../rules/specs.scenarios.csharp.md).
+
 ## Verified product sources
 
 | Package | Purpose |

package/package/corpus/skills/cratis-chronicle-reactor/references/specifications.md

@@ -12,8 +12,29 @@
 
 Start with `Specification` plus a direct call for pure reactor decisions,
 passing the trigger and supplied values explicitly and asserting the returned
-command or event. Add `ReactorScenario<TReactor>` only where invocation,
-dependency wiring or side effects contribute proof. In those scenarios, drive
+command or event. Add one `ReactorScenario<TReactor>` per reactor for what only
+Chronicle proves: dispatch, filtering, read-model parameters and routing of
+produced events to the right event source (the
+[decision table](../../../rules/specs.scenarios.csharp.md)).
+Substitute the reactor's collaborators in either style; never substitute the
+event store as proof of routing.
+
+```csharp
+public class when_an_author_is_registered : Specification
+{
+    readonly INotifier _notifier = Substitute.For<INotifier>();
+    readonly AuthorId _id = AuthorId.New();
+
+    async Task Because() =>
+        await new AuthorNotifications(_notifier).Registered(
+            new AuthorRegistered("Jane Austen"),
+            EventContext.EmptyWithEventSourceId(_id));
+
+    [Fact] void should_notify_about_the_author() => _notifier.Received(1).Notify("Jane Austen");
+}
+```
+
+In reactor scenarios, drive
 events with a service provider of substitutes and assert on the substitutes for
 non-event side effects; for handlers that return events, assert the resulting
 appends through the scenario's event store. Cover the replay path separately

package/package/corpus/skills/cratis-chronicle-read-model-specifications/SKILL.md

@@ -16,9 +16,12 @@ default, with the event and current state supplied explicitly (for a self model,
 `ReadModelScenario<TReadModel>` only where declarative projection behavior,
 event dispatch, filtering, metadata or read-model wiring contribute proof.
 Follow the [scenario selection and cost rule](../../rules/specs.scenarios.csharp.md):
-use one scenario class per read model, many read-only assertions on one shared
-setup, and keep shared lifecycle enabled. Do not create a class per property,
-mapping attribute or lifecycle event. Measure scenario cost with TRX durations
+use one scenario class per read model and per distinct event sequence the
+projection declares (lifecycle, join, children with two keys, removal), with many
+read-only assertions on one shared setup, and keep shared lifecycle enabled. Cover
+each declared sequence; do not create a class per property or mapping attribute.
+Never replace the engine with a substitute store as projection proof. Reducer
+transitions are plain calls; the scenario proves dispatch and filters. Measure scenario cost with TRX durations
 using [running-specs.md](../cratis-specifications-csharp/references/running-specs.md).
 
 For a read-model scenario specification the **`Given` *is* the act**. There

package/package/corpus/skills/cratis-chronicle-reducer/SKILL.md

@@ -271,8 +271,8 @@ Read [references/filtering.md](references/filtering.md) when restricting which e
 
 Start with `Specification` plus a direct call for pure reducer decisions:
 pass the event and current state explicitly and assert the returned next state.
-Add `ReadModelScenario<TReadModel>` only where event dispatch, filtering,
-metadata or read-model wiring contribute proof; drive the event sequence and
+Add one `ReadModelScenario<TReadModel>` per reducer for event dispatch, filtering,
+metadata and read-model wiring (the [decision table](../../rules/specs.scenarios.csharp.md)); drive the event sequence and
 assert on the resulting instance there. For the self example:
 
 Read [references/specification-example.md](references/specification-example.md) when you need a worked direct-call and `ReadModelScenario` spec.

package/package/corpus/skills/cratis-code-review/SKILL.md

@@ -155,8 +155,10 @@ degradations a reviewer can see without measuring:
 ## Step 6 — Specification coverage
 
 - Pure command, validator, reducer and reactor decisions have plain-call specs
-  with supplied read-model state; scenarios add only pipeline/authorization
-  wiring, constraints, declarative mapping or application-owned race-policy proof.
+  with supplied read-model state; scenarios cover exactly the obligations in the
+  per-artifact decision table of `specs.scenarios.csharp.md` (pipeline and
+  authorization, constraints, projection and reducer dispatch, reactor dispatch
+  and routing) plus application-owned race-policy proof.
 - Every State Change command has a happy-path specification.
 - Every validation rule has a direct-call failure spec. Pipeline validation
   specs assert **both** `ShouldNotBeSuccessful()` and `ShouldHaveValidationErrors()`.

package/package/corpus/skills/cratis-environments-and-secrets/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-environments-and-secrets/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: cratis-environments-and-secrets
+description: Use when a Cratis project needs named environments, per-environment configuration values or secrets with `cratis env` and `cratis config`, or when a Screenplay model's environment keys must be filled. Not for Chronicle server contexts or for authoring the model.
+license: MIT
+---
+
+# Cratis environments and secrets
+
+A Screenplay model is the same in every environment. What it needs to run (a client id, an SMTP
+host, a signing key) is not. A project keeps that in **named environments**, one committed file
+per environment next to the model, in the way a Pulumi project has stacks. Which keys a model
+needs is derived from its declarations: see
+[cratis-screenplay-authentication-and-onboarding](../cratis-screenplay-authentication-and-onboarding/SKILL.md).
+
+**Requires** `cratis` 3.114.0 or later for `cratis env` and `cratis config` (`cratis --version`,
+and `which -a cratis` for a shadowing copy). The commands do not exist in older releases.
+
+This is not a Chronicle server context: `cratis context` and `-e/--event-store` on `chronicle`
+commands belong to `cratis-chronicle-cli-operations`.
+
+## The secrets contract
+
+This skill applies the always-on [secrets rule](../../rules/secrets.md); read it first. For this
+CLI it means:
+
+- **A secret enters only through stdin or the hidden prompt.** Never as an argument (it lands in shell history and the transcript).
+- **An agent never runs `cratis config get <key> --show-secret`** and never prints a secret by
+  any other route. Without the flag a secret prints as `[secret]`, which is the form to use.
+- **An agent does not receive the value to set.** When a secret is needed and the person has not
+  provided it through a channel the agent cannot read, ask them to run the `--secret` command in
+  their own terminal. Do not ask them to paste it into the chat.
+- **A passphrase is not a value to hold.** It comes from `CRATIS_PASSPHRASE`, the file named by
+  `CRATIS_PASSPHRASE_FILE`, or the hidden prompt. Never write one to a file in the repository,
+  and never export one inline in a command.
+
+## Files and selection
+
+Each environment is `.cratis/environments/<name>.yaml`; a name is a safe file name such as
+`development`, `staging` or `customer-x`. Entries are a plain `key: value`, a `secure: <base64>`
+secret encrypted by the passphrase provider (safe to commit), or a `ref:` to a vault. The file
+never holds a clear-text secret. Read [environment file](references/environment-file.md) for the
+exact shape.
+
+The environment in effect is, in order: `--environment <name>` (`-e` on `env` and `config`),
+`CRATIS_ENVIRONMENT`, the user's selection in `.cratis/local/selected-environment` (not committed), then
+`development`. On Chronicle commands `-e` means `--event-store`; use `--environment` there.
+
+## Commands
+
+```bash
+cratis env init                          # creates "development"
+cratis env init production --secrets-provider azurekeyvault://<vault>
+cratis env select production
+cratis env ls
+cratis config set auth:clientId <client-id>
+cratis config set smtp:password --secret # reads stdin or a hidden prompt
+cratis config get smtp:password          # [secret]
+cratis config                            # list; secrets show as [secret]
+cratis config --missing ./model          # keys the model needs and the environment lacks
+```
+
+| Command | Purpose |
+|---|---|
+| `cratis env init [name]` | Create an environment; `--secrets-provider` picks where secrets live. |
+| `cratis env select <name>` / `ls` / `rm <name>` | Select for this user, list (the one in effect is marked), remove (confirms; `--yes` skips). |
+| `cratis env change-secrets-provider <uri>` | Move every secret to another provider; the file never holds clear text in between. |
+| `cratis env change-passphrase` | Re-encrypt every secret under a new passphrase and salt. |
+| `cratis config set <key> <value>` | Set a plain value. |
+| `cratis config set <key> --secret` | Set a secret. |
+| `cratis config get <key>` / `rm <key>` | Read (secrets masked) / remove (also from the vault). |
+| `cratis config [--missing <path>]` | List keys, or the keys a model needs that are absent. |
+
+All accept `-o json`. Exit codes: `0` success, `1` not found, `4` authentication failed (wrong
+passphrase), `5` validation, including any key missing under `--missing`.
+
+## Choosing a secrets provider
+
+Default to **passphrase** for a project with one team and a committed environment file. Choose a
+vault when secrets must not travel with the repository or are shared with a cluster.
+
+| Provider | Use when | Credentials come from |
+|---|---|---|
+| `passphrase` (default) | Secrets are committed encrypted (AES-256-GCM, key derived per environment). | `CRATIS_PASSPHRASE`, `CRATIS_PASSPHRASE_FILE` or a prompt. |
+| `azurekeyvault://<vault>` | The team already runs Azure Key Vault. | `DefaultAzureCredential` (Azure CLI login, managed or workload identity). |
+| `hashivault://<address>/<mount>[/<path>]` | The team runs HashiCorp Vault KV v2. `hashivault+http://` is for a development server. | `VAULT_TOKEN`, or `VAULT_ROLE_ID` and `VAULT_SECRET_ID`, or `VAULT_K8S_ROLE`. |
+
+`cratis run` on a model with `authentication` resolves the selected environment (or `-e <name>`)
+before starting Docker, hands the provider and onboarding values to the AuthProxy and Ante
+containers, and stops with exit `5` listing the missing keys, never their values. A mail
+server is optional: without `onboarding.email.server.host`, emails are written as `.eml` files.
+Requires cratis CLI 3.116.0 (`cratis --version`); older CLIs run the Stage alone and play a persona.
+
+## Pitfalls
+
+- Setting a secret with `cratis config set smtp:password <value>` stores a plain value and leaks it. Always add `--secret` and pipe or prompt.
+- Committing a `.cratis/local/` folder: it holds the personal selection and is git-ignored by `cratis init` and `cratis env select`.
+- Wrong passphrase is exit `4` before anything is decrypted; do not retry it in a loop.
+- `cratis config --missing` on a model that does not compile exits `5` and names the first errors; fix the model first.
+- A key added to the model later is missing from existing environments; re-run `--missing` per environment.
+
+## Verify
+
+1. `cratis env ls` marks the environment you intend; `cratis config -e <name>` lists the expected keys.
+2. `cratis config --missing <model-folder> -e <name>` exits `0` (`echo $?`).
+3. `git diff` on `.cratis/environments/` shows only plain values, `secure:` or `ref:` entries, and no clear-text secret.
+4. No command in the session used `--show-secret`, and no secret appears in the transcript.
+
+## Route near misses
+
+- Chronicle server contexts and operations: `cratis-chronicle-cli-operations`.
+- The model's `authentication` and `onboarding` blocks and their keys: `cratis-screenplay-authentication-and-onboarding`.
+- Running the application with the resolved values: `cratis-onboarding-runtime` (cluster) and `cratis-stage-rendering-and-sandbox`.

package/package/corpus/skills/cratis-environments-and-secrets/references/environment-file.md

@@ -0,0 +1,48 @@
+# Environment file
+
+```yaml
+secretsProvider: passphrase
+encryptionSalt: <base64>
+encryption:
+  kdf: pbkdf2-sha256
+  iterations: 600000
+  check: <base64>
+config:
+  auth:clientId: <client-id>
+  smtp:host: mail.example.com
+  smtp:password:
+    secure: <base64>
+  signing:key:
+    ref: <vault reference>
+```
+
+| Entry | Meaning |
+|---|---|
+| `key: value` | A plain value. |
+| `key: { secure: <base64> }` | A secret encrypted by the passphrase provider; bound to its key, so moving the ciphertext to another key fails. Safe to commit. |
+| `key: { ref: <name> }` | A secret kept in Azure Key Vault or HashiCorp Vault. The file holds only the reference. |
+
+`secretsProvider`, `encryptionSalt` and `encryption` describe where secrets live. The salt is per
+environment, so two environments with one passphrase get different ciphertext. Do not edit these
+fields by hand; use `cratis env change-passphrase` or `change-secrets-provider`.
+
+## Vault storage
+
+- Azure Key Vault: secrets named `cratis-<environment>-<key>` with a short hash suffix; the file holds the name as `ref:`.
+- HashiCorp Vault: KV v2 at `<path>/<environment>/<key>` (the path defaults to `cratis`); the file holds that path as `ref:`.
+- `VAULT_AUTH_MOUNT` overrides the auth method mount and `VAULT_NAMESPACE` sets the Vault namespace.
+
+## Reading environments from code
+
+The `Cratis.Environments` package reads the same files, so other tools resolve values and
+secrets exactly as the CLI does.
+
+```csharp
+var environments = ProjectEnvironments.Discover(Directory.GetCurrentDirectory());
+var selected = environments.Resolve(explicitName: null);
+var environment = ProjectEnvironment.Open(environments, selected.Name, PassphraseSources.FromEnvironment());
+
+var clientId = await environment.GetValueAsync("auth:clientId");
+```
+
+Keep a resolved secret in memory only; never log it or write it to a file the repository tracks.

package/package/corpus/skills/cratis-onboarding-runtime/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-onboarding-runtime/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: cratis-onboarding-runtime
+description: Use when running or deploying the onboarding of a Screenplay application, meaning configuring the application's Ante from the onboarding contract or declaring a Showrunner Stage Manager `Performance` that runs the application with its AuthProxy and Ante. Not for authoring the model or for Ante used by a host product.
+license: MIT
+---
+
+# Onboarding runtime: Ante and Stage Manager
+
+A Screenplay model with `authentication` and `onboarding` is carried out by three runtime parts
+that read one contract, produced from the model and a Cratis environment:
+
+| Part | Does | Contract |
+|---|---|---|
+| **AuthProxy** | The only public entry point; signs people in with the model's providers. | `Cratis:AuthProxy:Application` (see the AuthProxy reference of `cratis-arc-authentication-authorization-and-identity`). |
+| **Ante** | **One per application.** Signs invitation tokens, serves the lobby, records acceptance and legal terms, publishes to its outbox. | `Ante:Onboarding:*`. |
+| **Herald** | Sends the invitation and welcome emails from the application (the declined template waits for an Ante outcome). | `cratis-showrunner-herald`. |
+
+Nobody writes the equivalent `Ante:*` or `Cratis:AuthProxy:*` keys by hand for a Screenplay
+application. The model supplies structure (providers, personas, invitation types, legal files);
+the **environment** supplies every value and secret (`cratis-environments-and-secrets`).
+
+**Requires** Ante 1.5.0 or later for `Ante:Onboarding:*`, AuthProxy 2.40.0 or later for
+`Cratis:AuthProxy:Application`, and Showrunner 1.11.0 or later for the `Performance` resource.
+
+## Who owns what
+
+Ante owns token signing, the lobby, local acceptance, legal terms presented from files, and the
+persona and invitation-type checks. The **application** owns the persona list (the model), who is
+invited, link delivery, membership and provisioning. Ante sends no email: the application sends
+the invitation link through Herald using the `InvitationTokenIssued` token. Every accepted fact
+(`InvitationToJoinTenantAccepted`, `InvitationToCreateTenantAccepted`,
+`OrganizationRegistrationCompleted`, `LegalTermsAccepted`) means **published to Ante's outbox, not
+provisioned**: make provisioning idempotent by event source id and event kind. Ante does not know
+what a persona may do; it validates grantable personas against the configured list only.
+
+## Ante's onboarding contract
+
+Set `Ante:Onboarding:Enabled=true` to apply it. While `false` or absent every `Ante:Onboarding:*`
+key is ignored. When enabled, each value it carries wins over the ordinary key it maps to,
+including values from `appsettings.json`. Read [Ante onboarding keys](references/ante-onboarding-keys.md)
+for the table before configuring anything.
+
+- `HostStore` is the application's own Chronicle store, the only host store Ante observes. The application appends `UserInvitedToJoinTenant` or `UserInvitedToCreateTenant` to that store's outbox.
+- `SignUp` is `CreateTenant` (default; self-service registration may create a tenant) or `JoinTenant` (`/register` closed; invitation only). This is the model's `signup` line.
+- `InvitationTypes` and `Personas` are runtime checks: an invitation of a disallowed type is rejected with `InvitationTypeNotAllowed`, one granting a persona outside the list with `PersonaNotGrantable`, and no token is issued either way. Validate against the model's persona list in the application first; Ante is the second line of defense. Observe generation 4 of `InvitationRejected`.
+- Legal terms are files in a mounted folder (`terms.md`, `privacy.md`). The version is a content hash, so editing either file requires everyone onboarding afterwards to accept again. Archive each version for consent audit; the bodies live in your files.
+- **Secrets** (the signing private key, pinned attestation public keys) arrive only as mounted files or standard configuration, never on the command line; Ante logs no value.
+
+## Development mode is for local runs only
+
+`Ante:Onboarding:Development:Enabled=true` generates a 2048-bit RSA signing key per data volume and
+needs no secret. Ante refuses to start when the environment name is production-like (`Production`,
+`Prod`, `Live`, `Staging`, `Stage`, `Preprod`), in a Kubernetes pod, or when a configured URL is not
+loopback. Never copy a development key to another environment, and leave `Secrets:SigningKeyFile` out of a development run.
+
+Locally, `cratis run` on a model with `onboarding` starts Ante this way: `ASPNETCORE_ENVIRONMENT`
+is `Development` and `Ante:Onboarding:Development:Enabled` is `true`, so Ante generates its signing
+key into a folder that lives only for the run. It shares AuthProxy's network stack, so AuthProxy
+reaches it on loopback, and the lobby is served through AuthProxy. Nothing from a local run is
+trusted by another run or cluster.
+
+## Stage Manager `Performance`
+
+A `Performance` (`showrunner.cratis.io/v1alpha1`) runs one application in one Cratis environment,
+with its AuthProxy when the application has `authentication` and its own Ante when it has
+`onboarding`. Read [Performance resource](references/performance.md) to write or review the spec.
+
+- The environment file is supplied as a ConfigMap key (the file `cratis` keeps in `.cratis/environments/<name>.yaml`); a passphrase environment names a Secret for the passphrase. Vault access belongs to the operator's identity, set in the chart, not the Performance.
+- **A resolved value reaches a container only as a file in a mounted Secret volume**: never an environment variable, a ConfigMap, the status or the operator log.
+- Nothing is created until everything is in hand. A missing environment key makes the phase `Blocked` and lists the keys in `status.missingEnvironmentKeys`; running Deployments are left alone.
+- AuthProxy is the only ingress target; the application and Ante are ClusterIP Services behind it.
+- The operator generates and rotates the invitation and attestation signing keys (`spec.signingKeys.rotation`) and derives the issuers, audiences and URLs, so none of them is written twice.
+
+## Pitfalls
+
+- Treating `Accepted` as provisioned: provisioning is the application's, and must be idempotent.
+- Setting a signing key or provider secret as an environment variable in a manifest: use the mounted files.
+- Two Ante instances for one application, or one Ante shared by several Performances: one Ante per Performance, with its own event store (`ante-<name>` by default).
+- Using development mode in a shared cluster: Ante refuses; do not work around the guard.
+
+## Verify
+
+1. The model compiles and `screenplay environment <folder>` lists the keys; `cratis config --missing <folder> -e <name>` exits `0`.
+2. `kubectl get performance <name> -o jsonpath='{.status.phase}'` is `Ready`; `-o jsonpath='{.status.missingEnvironmentKeys}'` is empty.
+3. An invitation for a persona outside the model is rejected with `PersonaNotGrantable` and issues no token.
+4. No secret value appears in a manifest, the status, a log or the transcript (`kubectl get -o json` on pods or secrets is forbidden by the secrets rule; project fields instead).
+
+## Route near misses
+
+- The model's `onboarding` block and environment keys: `cratis-screenplay-authentication-and-onboarding`.
+- Environment commands and secrets providers: `cratis-environments-and-secrets`.
+- Sending the emails: `cratis-showrunner-herald`.
+- Ante used by a host product, not a Screenplay application: Ante's own documentation; this corpus does not cover it.
+- Chronicle itself in a cluster: `cratis-chronicle-hosting`.

package/package/corpus/skills/cratis-onboarding-runtime/references/ante-onboarding-keys.md

@@ -0,0 +1,31 @@
+# Ante onboarding keys
+
+Configuration keys under `Ante:Onboarding:` when `Enabled` is `true`. Each value maps onto the
+ordinary key shown and wins over it. In environment-variable form use `__` for `:`.
+
+| Key | Type | Maps to | Notes |
+|---|---|---|---|
+| `Enabled` | bool | none | Applies the contract. Default `false`. |
+| `HostStore` | string | `Ante:HostStores` (one entry) | The application's own Chronicle store. Required unless development mode (then `Application`). |
+| `EventStore`, `Namespace` | string | `Ante:EventStore`, `Ante:Namespace` | Optional. Ante's own store and fixed namespace. |
+| `PublicBaseUrl` | absolute URL | `Ante:Invitations:Token:PublicBaseUrl` | Where users reach this Ante. HTTPS, or HTTP on loopback. |
+| `ApplicationUrl` | URL | `Ante:HostAppUrl` | Where people go when onboarding completes. |
+| `SignUp` | `CreateTenant` or `JoinTenant` | `Ante:Registration:Enabled` | `JoinTenant` closes `/register`. |
+| `RegistrationEnabled` | bool, default `true` | `Ante:Registration:Enabled` | Always off when `SignUp` is `JoinTenant`. |
+| `InvitationTypes` | list | none (runtime check) | `JoinTenant`, `CreateTenant`; unset allows both. |
+| `Personas` | list | none (runtime check) | Grantable personas; ordinal comparison; unset or empty accepts any role. |
+| `DefaultLocale`, `AllowedLocales` | string, list | `Ante:DefaultLocale`, `Ante:SupportedLocales` | |
+| `Legal:Folder`, `Legal:TermsAndConditions`, `Legal:PrivacyPolicy` | paths | `Ante:Legal:Source=Files`, `Ante:Legal:Files:*` | Omit `Legal` for no legal step. |
+| `Secrets:Path` | folder | any key | One file per setting, named like the key with `__` for `:`; trailing newline removed; names starting `.` skipped. |
+| `Secrets:SigningKeyFile` | file path | `Ante:Invitations:Token:PrivateKeyPem` | PEM RSA private key, at least 2048 bits. |
+| `Secrets:VerificationKeyFile` | file path | `Ante:Invitations:Token:PublicKeyPem` | Optional extra trusted public key. |
+| `Development:Enabled`, `Development:DataPath` | bool, folder | none | Local runs only; see `SKILL.md`. |
+
+The same instance still needs `Cratis:Chronicle:ConnectionString` and `Cratis:MongoDB`, normally
+supplied by the Cratis environment. Attested-exchange settings, `Issuer`, `Audience` and `Expiry`
+stay under `Ante:Invitations`.
+
+Legal terms from files: the version is `sha256-` plus the first 16 hex characters of a SHA-256
+over both bodies. The set is read on every request, so a changed mounted file applies without a
+restart. Acceptance is recorded and published as `LegalTermsAccepted` carrying that version; Ante
+does not publish `LegalDocumentSetActivated` for a file set.

package/package/corpus/skills/cratis-onboarding-runtime/references/performance.md

@@ -0,0 +1,86 @@
+# Performance resource
+
+```yaml
+apiVersion: showrunner.cratis.io/v1alpha1
+kind: Performance
+metadata:
+  name: crm
+  namespace: apps
+spec:
+  productionRef:
+    name: ledger
+  chronicle:
+    connectionSecretRef:
+      name: chronicle-connection
+  application:
+    image: registry.example.com/crm:1.0.0
+    eventStores: [Crm]
+  environment:
+    name: production
+    configMapRef:
+      name: crm-environment
+    passphraseSecretRef:
+      name: crm-passphrase
+  authProxy:
+    enabled: true
+    providers:
+      - kind: EntraId
+        identity: EntraId
+  onboarding:
+    enabled: true
+    signUp: CreateTenant
+    personas: [Administrator, Member]
+    legal:
+      configMapRef:
+        name: crm-legal
+  ingress:
+    enabled: true
+    className: nginx
+    hosts: [crm.example.com]
+    tlsIssuer:
+      name: letsencrypt
+```
+
+## Fields that decide behavior
+
+- Chronicle: `chronicle.connectionSecretRef` (an existing Secret) takes precedence over `productionRef`. The Secret is mounted as a file, never copied. `application.eventStores[0]` is the store Ante observes.
+- `environment.configMapRef` holds `<name>.yaml` unless `key` says otherwise. `passphraseSecretRef` is only for a passphrase environment. Azure Key Vault uses the operator's workload identity; HashiCorp Vault uses Kubernetes auth with the operator's service account and `VAULT_K8S_ROLE`; both are chart values.
+- `authProxy.providers` carry kind and identity only, matching the model. `onboarding` carries `signUp`, `personas` and legal files; every value comes from the environment.
+- `onboarding.attestedProviders` set: Ante runs attested invitation exchange against AuthProxy's attestations; unset keeps the legacy exchange.
+
+## Created resources (for a Performance named `crm`)
+
+| Resource | Name | Notes |
+|---|---|---|
+| Deployment and Service | `crm-app`, `crm-authproxy` (when enabled), `crm-ante` (when onboarding) | ClusterIP; Ante has one replica. |
+| Ingress | `crm` | Every host routes to AuthProxy only; certificate from cert-manager. |
+| Secrets | `crm-app-environment`, `crm-authproxy-environment`, `crm-ante-secrets`, `crm-signing-keys` | Mounted content and generated keys. |
+
+AuthProxy gets one file per environment key it needs in `/run/secrets/cratis`; Ante gets one file
+per setting (`__` for `:`) in `/run/secrets/ante`; the application gets the remaining keys in
+`/run/secrets/cratis`. Pods roll when mounted content changes, via a keyed hash annotation that
+reveals nothing about a value. Ante's own MongoDB server comes from the environment key `ante.mongodb.server`.
+
+## Status
+
+| Field | Meaning |
+|---|---|
+| `phase` | `Pending`, `Blocked`, `Progressing` or `Ready`. |
+| `publicUrl` | `https://` and the first ingress host. |
+| `missingEnvironmentKeys` | Keys the environment lacks while `Blocked`. |
+| `conditions` | `SpecValid`, `ChronicleConnection`, `EnvironmentResolved`, `EnvironmentComplete`, and per component `ApplicationReady`, `AuthProxyReady`, `AnteReady`. |
+| `signingKeys` | Key ids in use, rotation counter applied, previous public keys pinned. |
+
+Conditions and status never contain a secret value. An unresolved environment is reported in
+`EnvironmentResolved` with a message naming the key and the provider.
+
+## Signing keys
+
+The operator generates the key Ante signs invitations with and the key AuthProxy signs
+attestations with, in `crm-signing-keys`. Raise `spec.signingKeys.rotation` to rotate both. The
+public half of each replaced key stays pinned (`signingKeys.retainPrevious`, two by default), so
+Ante verifies invitations signed with a previous key.
+
+Routing `/_invite` and `/.well-known/ante` from AuthProxy to Ante is configured on AuthProxy's
+side; set `onboarding.lobbyBackendBaseUrl` in the environment when needed. Other Stage Manager
+resources (`Production`, `Understudy`, `Restore`, `Rehearsal`, `BackstagePass`, `ControlRoom`) are schema only; nothing acts on them.

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.