@cratis/pi 7.126.0 → 7.128.0

package/package/corpus/harnesses/copilot/instructions/profiles.instructions.md

@@ -215,12 +215,12 @@ language policy always follows the consuming repository's `go.mod` minimum.
 | `cratis/codescene` | Opt-in CodeScene Code Health change gates, refactoring, debt prioritization and risk-based testing; requires an account and available MCP tools; each user registers the MCP server (see below) |
 | `cratis/playwright` | Opt-in Playwright browser automation MCP server declaration for exploratory checks; carries no skills or rules and each user registers the server (see below) |
 | `cratis/studio` | Studio MCP safety guidance |
-| `cratis/cli` | CLI operations |
+| `cratis/cli` | CLI operations, project environments and secrets |
 | `cratis/cli/terminal-workbench` | Human-operated terminal Workbench |
 | `cratis/chronicle/mcp` | Chronicle MCP inspection and exact tool-effect guidance |
 | `cratis/lens` | Lens browser extension |
 | `cratis/screenplay` | Model-first event modeling: lifecycle, phase skills, toolchain, review, render and gap-fill, plus the whole `.play` language |
-| `cratis/stage` | Stage rendering and sandbox |
+| `cratis/stage` | Stage rendering and sandbox, onboarding runtime (Ante, Stage Manager) |
 | `cratis/modeling/screenplay-stage` | Screenplay + Stage together |
 
 ### Code Health with CodeScene
@@ -302,6 +302,7 @@ and one phase skill, then the construct skill needed for syntax.
 | `cratis-screenplay-read-surface` | `readmodel`, `query`, `screen`, name resolution |
 | `cratis-screenplay-ui-composition` | `layout`, templates, `form`, `contribute`, `ui profile`, `theme`, `$strings`, `file` |
 | `cratis-screenplay-captures-and-reactions` | The Change Data Capture Language, `reaction`, `trigger` |
+| `cratis-screenplay-authentication-and-onboarding` | `authentication`, `onboarding`, and the environment keys derived from them |
 | `cratis-screenplay-specifications` | Given/when/then and the reference execution |
 | `cratis-screenplay-model-authoring` | Typed MCP authoring, model navigation/refactoring, compiler diagnostics, and source-versus-executable readiness |
 

package/package/corpus/harnesses/copilot/instructions/secrets.instructions.md

@@ -17,7 +17,7 @@ Every line is tagged **[contract]** (binding) per the Three Levels of Authority
   secrets; `kubectl get secret`; `kubectl config view --raw`; `env`, `printenv`, `export -p`
   (including `env | …`); `docker inspect`; `gh secret`, `gh api …/secrets`, `gh auth token`;
   `vault read`, `vault kv get`; cloud secret-manager reads; `pulumi … --show-secrets`;
-  reading kubeconfigs, `.env*` files, private keys or token files.
+  `cratis config get … --show-secret`; reading kubeconfigs, `.env*` files, private keys or token files.
 - **[contract] Project the field you need and say which one:** `-o jsonpath='{.spec.containers[*].image}'`,
   `-o custom-columns=…`, `kubectl get … -o name`, status fields, `kubectl logs`, `docker inspect --format`.
   Read a `.env.example`, never the `.env`.

package/package/corpus/hooks/README.md

@@ -11,7 +11,7 @@ Three layers:
 | Pattern pass | `PostToolUse` on a write | `scripts/cratis-pattern-scan.sh` | zero tokens until a match | appends a one-line reminder to context, never blocks |
 | Hard block | `PreToolUse` on a write | `scripts/cratis-guard-writes.sh` | zero | exits **2** — the write does not happen |
 | Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-store-mutations.sh` | zero; parses only commands that mention `cratis` | exits **2** — the store-changing `cratis chronicle` command does not run |
-| Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-secrets.sh` | zero; parses only commands that mention a credential-bearing tool or file | exits **2** — a command that prints credentials (full `kubectl` specs and secrets, `env`/`printenv`, `docker inspect`, secret-manager reads, `.env`/kubeconfig/key files; also behind `/usr/bin/env`, `command`, attached options such as `-ePATTERN`, a bare `{.}` projection) does not run unless it projects a field; piped shells and recursive searches with no named file stay uncovered; see [`secrets.md`](../rules/secrets.md) |
+| Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-secrets.sh` | zero; parses only commands that mention a credential-bearing tool or file | exits **2** — a command that prints credentials (full `kubectl` specs and secrets, `env`/`printenv`, `docker inspect`, secret-manager reads, `cratis config get --show-secret`, `.env`/kubeconfig/key files; also behind `/usr/bin/env`, `command`, attached options such as `-ePATTERN`, a bare `{.}` projection) does not run unless it projects a field; piped shells and recursive searches with no named file stay uncovered; see [`secrets.md`](../rules/secrets.md) |
 | Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-pr-body.sh` | fetches shared rules only for `gh pr create/edit` | exits **2** for inline bodies, invalid notes or conflicting release labels; warns and allows when offline with no cache |
 | Cleanup of delivered work | `PostToolUse` on `Bash` (`gh pr merge`, `git pull/merge/worktree`) and `SessionStart` (Pi: `tool_result` and `session_start`) | `scripts/cratis-cleanup-worktrees.sh --hook` | zero when the command is unrelated | never blocks; removes delivered worktrees and branches, reports what it kept |
 | Quality gate (Claude) | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |

package/package/corpus/hooks/scripts/cratis-guard-secrets.sh

@@ -35,7 +35,7 @@ command_text="$(hook_json "$input" '.tool_input.command')"
 
 # Cheap exit for the overwhelming majority of shell commands, which mention none of these words.
 case "$(printf '%s' "$command_text" | tr '[:upper:]' '[:lower:]')" in
-    *kubectl*|*printenv*|*env*|*docker*|*podman*|*"gh "*|*vault*|*pulumi*|*aws*|*"az "*|*gcloud*|*kubeconfig*|*.kube*|\
+    *kubectl*|*printenv*|*env*|*docker*|*podman*|*"gh "*|*vault*|*pulumi*|*show-secret*|*aws*|*"az "*|*gcloud*|*kubeconfig*|*.kube*|\
     *export*|*declare*|*typeset*|*id_rsa*|*id_ed25519*|*id_ecdsa*|*id_dsa*|*.pem*|*.p12*|*.pfx*|*token*|*.netrc*|*.npmrc*|\
     *credentials*|*.pgpass*|*secrets*) ;;
     *) exit 0 ;;
@@ -397,7 +397,7 @@ function drop_redirects(A, s, n,    k, m, w) {
     }
     return m
 }
-function analyze(A, s, n,    w, b, k, names, p) {
+function analyze(A, s, n,    w, b, k, names, p, config, get, show) {
     while (s <= n) {
         w = A[s]; b = base(w)
         if (is_assign(w)) { s++; continue }
@@ -446,6 +446,17 @@ function analyze(A, s, n,    w, b, k, names, p) {
         for (k = s + 1; k <= n; k++) if (A[k] ~ /^--show-secrets/) report("pulumi --show-secrets prints decrypted secrets", "pulumi config / pulumi stack output without --show-secrets (secrets stay masked)")
         return
     }
+    # `cratis config get` prints a secret as [secret]; --show-secret resolves it through the secrets provider.
+    if (b == "cratis") {
+        config = 0
+        for (k = s + 1; k <= n; k++) {
+            if (A[k] == "config") config = 1
+            else if (config && A[k] == "get") get = 1
+            if (A[k] ~ /^--show-secret/) show = 1
+        }
+        if (config && get && show) report("cratis config get --show-secret prints a decrypted secret", "cratis config get without --show-secret (a secret prints as [secret]); name the key in your report")
+        return
+    }
     # A redirect is not a variable name: `printenv > f` and `export > f` still dump the whole environment.
     if (b == "printenv" || b == "export" || b == "declare" || b == "typeset") n = drop_redirects(A, s, n)
     if (b == "printenv") {

package/package/corpus/rules/profiles.md

@@ -214,12 +214,12 @@ language policy always follows the consuming repository's `go.mod` minimum.
 | `cratis/codescene` | Opt-in CodeScene Code Health change gates, refactoring, debt prioritization and risk-based testing; requires an account and available MCP tools; each user registers the MCP server (see below) |
 | `cratis/playwright` | Opt-in Playwright browser automation MCP server declaration for exploratory checks; carries no skills or rules and each user registers the server (see below) |
 | `cratis/studio` | Studio MCP safety guidance |
-| `cratis/cli` | CLI operations |
+| `cratis/cli` | CLI operations, project environments and secrets |
 | `cratis/cli/terminal-workbench` | Human-operated terminal Workbench |
 | `cratis/chronicle/mcp` | Chronicle MCP inspection and exact tool-effect guidance |
 | `cratis/lens` | Lens browser extension |
 | `cratis/screenplay` | Model-first event modeling: lifecycle, phase skills, toolchain, review, render and gap-fill, plus the whole `.play` language |
-| `cratis/stage` | Stage rendering and sandbox |
+| `cratis/stage` | Stage rendering and sandbox, onboarding runtime (Ante, Stage Manager) |
 | `cratis/modeling/screenplay-stage` | Screenplay + Stage together |
 
 ### Code Health with CodeScene
@@ -301,6 +301,7 @@ and one phase skill, then the construct skill needed for syntax.
 | `cratis-screenplay-read-surface` | `readmodel`, `query`, `screen`, name resolution |
 | `cratis-screenplay-ui-composition` | `layout`, templates, `form`, `contribute`, `ui profile`, `theme`, `$strings`, `file` |
 | `cratis-screenplay-captures-and-reactions` | The Change Data Capture Language, `reaction`, `trigger` |
+| `cratis-screenplay-authentication-and-onboarding` | `authentication`, `onboarding`, and the environment keys derived from them |
 | `cratis-screenplay-specifications` | Given/when/then and the reference execution |
 | `cratis-screenplay-model-authoring` | Typed MCP authoring, model navigation/refactoring, compiler diagnostics, and source-versus-executable readiness |
 

package/package/corpus/rules/secrets.md

@@ -16,7 +16,7 @@ Every line is tagged **[contract]** (binding) per the Three Levels of Authority
   secrets; `kubectl get secret`; `kubectl config view --raw`; `env`, `printenv`, `export -p`
   (including `env | …`); `docker inspect`; `gh secret`, `gh api …/secrets`, `gh auth token`;
   `vault read`, `vault kv get`; cloud secret-manager reads; `pulumi … --show-secrets`;
-  reading kubeconfigs, `.env*` files, private keys or token files.
+  `cratis config get … --show-secret`; reading kubeconfigs, `.env*` files, private keys or token files.
 - **[contract] Project the field you need and say which one:** `-o jsonpath='{.spec.containers[*].image}'`,
   `-o custom-columns=…`, `kubectl get … -o name`, status fields, `kubectl logs`, `docker inspect --format`.
   Read a `.env.example`, never the `.env`.

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

@@ -48,7 +48,7 @@ ingress above, otherwise configure a credential-validating scheme. The old
 same host-wide flag. See [authentication](references/authentication.md).
 Source: [secure defaults](https://github.com/Cratis/Arc/blob/main/Documentation/upgrading/secure-defaults.mdx).
 
-Cratis AuthProxy is the ingress that meets these obligations for Cratis applications. Read [AuthProxy](references/authproxy.md) when the application is deployed behind it (header contract, `/.cratis/me` fail-closed verification, tenant headers).
+Cratis AuthProxy is the ingress that meets these obligations for Cratis applications. Read [AuthProxy](references/authproxy.md) when the application is deployed behind it (header contract, `/.cratis/me` fail-closed verification, tenant headers, and starting it from a Screenplay model's provider list and a Cratis environment).
 
 ## Identity details — what the frontend is told
 

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-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,102 @@
+---
+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 (including the declined sign-up email). | `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`, `OrganizationRegistrationDeclined`, `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.
+
+## Sign-up review and the default offering
+
+- **Sign-up review** is opt-in (`Ante:Registration:Review`, off by default): Ante holds each sign-up until the host decides. Read [sign-up review](references/sign-up-review.md) before turning it on or handling `OrganizationRegistrationAwaitingReview`.
+- **The default offering** starts each new tenant on the offer the product declared, through Box Office. Read [default offering](references/default-offering.md) before wiring `IDefaultOffering` or diagnosing a tenant without seats or modules.
+- `InvitationRejected` is a host configuration problem, never a message to the invitee; only `OrganizationRegistrationDeclined` says a person was turned down.
+
+## 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).
+- Answering `InvitationRejected` with a message to the invitee: fix the invitation or host configuration instead.
+- 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`.
+- Box Office offers, seats and entitlements beyond the default offering: Showrunner's Box Office documentation; this corpus covers only starting a tenant on the default offering.
+- 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/default-offering.md

@@ -0,0 +1,61 @@
+# Default offering
+
+Requires Showrunner 1.13.0 or later (`Cratis.Showrunner.BoxOffice`) for `DefaultOffering`,
+`IDefaultOffering` and an event store taken from the host. Older releases have neither.
+
+A product that sells itself starts a new tenant on its default offering without waiting for the
+operator. The product decides, the operator is told, and a later operator decision replaces it.
+
+## Declare it
+
+```csharp
+builder.Services.AddBoxOfficeOffering(offering => offering
+    .Product(productId)
+    .Seats(SeatLicensing.PerUser)
+    .DefaultOffering("Starter"));
+```
+
+The name is the offer in the operator's catalog. The declaration is reported once per change as
+`DefaultOfferingDeclared`, so the operator knows which offer new tenants start on. A declaration
+that cannot be sold throws `InvalidOffering` at startup, one sentence per problem.
+
+## Start a tenant
+
+Call `IDefaultOffering.StartTenant(tenant, organization)` when the product has created the tenant.
+It finds the named offer among the offers the operator published and does two things:
+
+- records `TenantStartedOnDefaultOffering` in the tenant's own stream, so the tenant has the offer's
+  included seats and modules at once, with no trial;
+- publishes `TenantStartedOnOffer` to the operator, with the offer's name, included seats and
+  modules.
+
+A later operator decision such as `SeatCapacitySet` or `ModuleRevoked` supersedes what the tenant
+started with: the newest decision wins.
+
+## Failures
+
+| Failure | Meaning | Action |
+|---|---|---|
+| `DefaultOfferingNotDeclared` | The product declared no default offering. | Add `DefaultOffering(...)`. |
+| `DefaultOfferingNotPublished` | The operator has not published an offer with that name, or withdrew it. The name compares ignoring case. | Publish the offer; retry. |
+| `TenantNotStarted` | The tenant could not be started. | Read the reason; retry. |
+
+The catalog arrives after the product starts, so a name is checked when a tenant starts, not at
+startup. Nothing is published on a failure. Starting the same tenant again, also from another
+instance, returns `TenantStart.AlreadyStarted` and publishes nothing; if the product stopped
+between the two facts, starting again completes what is missing. A different default later does
+not restart a tenant.
+
+## Event store
+
+Herald, Box Office and the offering record in the host application's own event store in a host set
+up with `AddCratis` or `AddCratisChronicle`; nothing needs naming. Set `HeraldOptions.EventStore`,
+`BoxOfficeOptions.EventStore` or `OfferingOptions.EventStore` only to use another store. A host that
+registers only the Chronicle client uses the name in `ChronicleClientOptions.EventStore`.
+
+## Verify
+
+1. After the operator publishes the offer, `StartTenant` for a new tenant publishes
+   `TenantStartedOnOffer`; a second call returns `TenantStart.AlreadyStarted`.
+2. Before the offer is published, `StartTenant` throws `DefaultOfferingNotPublished` and publishes
+   nothing.

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.