@cratis/pi 7.127.0 → 7.128.0

package/package/corpus/skills/cratis-onboarding-runtime/SKILL.md

@@ -13,7 +13,7 @@ that read one contract, produced from the model and a Cratis environment:
 |---|---|---|
 | **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`. |
+| **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);
@@ -29,7 +29,7 @@ persona and invitation-type checks. The **application** owns the persona list (t
 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
+`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.
 
@@ -46,6 +46,12 @@ for the table before configuring anything.
 - 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
@@ -76,6 +82,7 @@ with its AuthProxy when the application has `authentication` and its own Ante wh
 - 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
@@ -90,5 +97,6 @@ with its AuthProxy when the application has `authentication` and its own Ante wh
 - 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/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/sign-up-review.md

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

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

@@ -69,7 +69,7 @@ block. The diagnostics for each rule are in that reference. The rules that decid
   `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.
+- `file` paths are repository-relative, like handler files. `offering` is the name of an offer the operator publishes in Box Office; a rendered application starts each new tenant on it. `signupDeclined` is sent when the host declines a held sign-up (review is not modeled; see `cratis-onboarding-runtime`).
 
 ## Environment keys
 

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

@@ -66,7 +66,7 @@ Syntax and meaning of each line of the `onboarding` block. All lines are optiona
 | `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. |
+| `offering` | `offering <Id>` | The Box Office offer a new tenant starts on. Absent means no licensing. |
 | `emails` | body of `<email> file <path>` lines and `images <folder>` | Templates for `invitation`, `welcome` and `signupDeclined`, and the folder they take images from. |
 
 ## What the block deliberately lacks

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

@@ -12,6 +12,10 @@ as events in the application's own Chronicle event store. It is not a service.
 
 **Requires** `Cratis.Showrunner.Herald` 1.10.0 or later and an application that is a Chronicle
 client (`AddCratis` or `AddCratisChronicle`); check the package reference in the `.csproj`.
+Herald records in the host application's own event store, without naming it again; set
+`HeraldOptions.EventStore` only to use another store. Showrunner 1.13.0 or later takes the host's
+store; an older release takes the name from the Chronicle client options, which an ASP.NET Core
+host leaves empty, so set `EventStore` explicitly there.
 
 ## Add it
 
@@ -41,6 +45,7 @@ builder.AddHerald(herald =>
   validated at startup and the error names the option.
 - Defaults worth knowing: `DefaultLanguage` `en`, `Transport` `Smtp`, `Smtp.Security` `StartTls`,
   `Retry.MaxAttempts` 6, `PollingInterval` 5 seconds. Read [options](references/options.md) for the full table.
+- A `signupDeclined` email is sent from `OrganizationRegistrationDeclined` with the reviewer's message as a value; see `cratis-onboarding-runtime`.
 - Chronicle finds Herald's events through type discovery of referenced `Cratis*` packages.
 - Run the worker in **one** application instance: delivery is at least once.
 

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/rendered-application.md

@@ -127,15 +127,24 @@ Requires cratis CLI 3.116.0 with Stage 4.211.0 (`cratis --version`); older relea
 - Only provider kinds AuthProxy supports render (`EntraId`, `GitHub`, `Google`, `Apple`,
   `OpenId`). Another kind is left out with `STAGE-AUTH-001`; a persona that is not a
   requirement on authentication, roles or claims is never matched (`STAGE-AUTH-002`).
-- `offering` renders nothing (`STAGE-ONBOARDING-001`): tenants are provisioned without
-  licensing. `STAGE-ONBOARDING-002` to `-006` cover a tenant invitation with no command,
+- `offering <Name>` renders against Box Office: the default offering is declared, and a
+  retrying reactor on tenant provisioning starts each new tenant on it (`StartTenant`) as soon as
+  the operator publishes the offer. Provisioning and the welcome email do not wait for it.
+  `STAGE-ONBOARDING-008` is information: the operator must publish an offer with that name, and
+  Box Office seat and compute policies are not rendered. Requires Stage 4.212.0
+  for the offering and the declined email; older renderers render neither.
+  `STAGE-ONBOARDING-002` to `-006` cover a tenant invitation with no command,
   a sign-up without a first-member persona, a legal document count other than two, a
-  missing email template and an invitation without inviters.
+  missing email template and an invitation without inviters. `-001` and `-007` are retired
+  and never reused.
 - An invitation Ante rejects (a persona or invitation type the model does not allow) is a
   mistake in the invitation, not a decision about the person: the application records
   `OnboardingInvitationRejected` and logs a warning for an administrator, and emails no
-  one. The `signupDeclined` template renders but is not sent until Ante publishes a
-  declined sign-up (`STAGE-ONBOARDING-007`).
+  one.
+- The `signupDeclined` template is sent on `OrganizationRegistrationDeclined`, with the
+  reviewer's message as `decline.message`, once per registration. Ante publishes that only
+  when sign-up review is on; the model has no review syntax, so a rendered application leaves
+  review off and the host adds approve and decline commands by hand (`cratis-onboarding-runtime`).
 - An application with onboarding pins a newer Chronicle client and kernel image than
   other applications; read them from the rendered files.
 - Realization needs the model folder: email images are read from the model root.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.127.0",
+  "version": "7.128.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [