@alvera-ai/platform-sdk 0.12.1 → 0.13.0-next.gf3d2a4a

package/.agent/ai_sandbox.md

@@ -72,9 +72,9 @@ Liquid's stock tag set (`{% if %}`, `{% for %}`, `{% assign %}`,
 `{% capture %}` writes to a Liquid-scope variable; it is not a
 runtime eval escape hatch.
 
-### The 11-filter custom allowlist
+### The 13-filter custom allowlist
 
-Beyond stock Liquid, the platform exposes exactly **eleven**
+Beyond stock Liquid, the platform exposes exactly **thirteen**
 custom filters. Adding new ones requires a platform release —
 consumers cannot extend the set:
 
@@ -101,6 +101,13 @@ consumers cannot extend the set:
    now           Current UTC datetime, ISO 8601.
                  Example:  {{ '' | now }}  →  2026-03-15T14:30:00Z
 
+   minutes_ago   Unix ms N minutes before a unix-ms input. Bounds
+                 the start of an ActionStatusUpdater poll window.
+                 Example:  {{ now | minutes_ago: 45 }}  →  1773585000000
+
+   hours_ago     Unix ms N hours before a unix-ms input.
+                 Example:  {{ now | hours_ago: 2 }}  →  1773578400000
+
    uuid          Generate a new v4 UUID.
                  Example:  {{ '' | uuid }}  →  a1b2c3d4-…
 
@@ -218,7 +225,7 @@ it sits inside the same Layer-3 boundary:
                         │
    ┌────────────────────▼────────────────────────┐
    │  Layer 2 — Liquid sandbox                   │
-   │    11-filter allowlist                      │
+   │    13-filter allowlist                      │
    │    + parse-on-write                         │
    │    + render-time output_schema check        │
    │  Decides: what the consumer-authored body   │
@@ -260,7 +267,7 @@ guarantees it captures back-stop Layer 1.
    `'regulated'` only when the action genuinely needs raw
    values, and pair with a session role that's authorised.
 
-2. **Use only the 11 custom filters** named in Layer 2. Bodies
+2. **Use only the 13 custom filters** named in Layer 2. Bodies
    that reference other filter names will silently fall through
    to stock Liquid behavior and produce malformed output.
 

package/.agent/async.md

@@ -40,10 +40,16 @@ resource-specific. Common examples:
 | Resource                          | Terminal success | Terminal failure        |
 |-----------------------------------|------------------|-------------------------|
 | Datalake (create + migrate)       | `ready`          | — (no terminal failure) |
-| Data Activation Client run        | `success`        | `error`                 |
-| AWS Lambda tool deploy            | `deployed`       | `failed`                |
+| AWS Lambda tool deploy            | `create_complete`| `create_failed`         |
 | Workflow run                      | `completed`      | `failed`                |
 
+**A data-activation-client run is NOT on this list — it is not a
+`waitUntilReady` status-poll target.** `.ingest` / `.ingestFile` /
+`.runManually` return a `202` + a `batch_id` (not a saved row and not
+a pollable status enum); progress is tracked by diffing the DAC's log
+and dataset rows by that `batch_id`, not by polling a `success`/`error`
+status. See `data_activation_clients.md` §6.
+
 The Datalake row is the odd one: its top-level `status` enum is
 `new | processing | ready` only — there is no terminal failure
 value. A migration that fails leaves the datalake at
@@ -59,7 +65,10 @@ CloudFormation deploy status nested under the polymorphic
 `body`), not on the top-level `tool.status` enum (which is
 `draft | active | inactive | error | marked_for_deletion`).
 `tool.status` flips to `'active'` after a successful deploy
-but `stack_status` is the more precise readiness signal — see
+but `stack_status` is the more precise readiness signal: its
+terminal-success value is the CloudFormation `create_complete`
+(`update_complete` on a redeploy), and a failed deploy lands on
+a `*_failed` state (`create_failed`, `rollback_failed`, …) — see
 `tools.md` §2 for the per-body field set.
 
 Each resource's MD §5 (Lifecycle) names its terminal-success
@@ -79,9 +88,10 @@ the caller.
 ## Idempotency on create
 
 `create()` calls are NOT idempotent by default. Repeating a
-`create()` with the same body yields a 422 on uniqueness fields
-(typically the name within scope). Consumers handling retry
-should:
+`create()` with the same body yields a **409 Conflict** on
+uniqueness fields (typically the name within scope — uniqueness
+collisions are 409, not 422; see `errors.md`). Consumers handling
+retry should:
 
 1. Catch the thrown error after the call returns (see `errors.md`).
 2. Inspect for a uniqueness `detail` on a `source.pointer`

package/.agent/connected_apps.md

@@ -27,6 +27,15 @@ The namespace splits into **two roles**:
   machine-to-machine API key) when a customer hits a magic link. Uses the app's
   `slug` as the path key.
 
+**Connected apps are single-tenant, full stop.** A connected app
+belongs to exactly ONE tenant (and one datalake under it): its
+auto-provisioned M2M key is tenant-scoped, its magic links resolve
+against that tenant's data, and its publishable browser key carries
+that tenant's origin allowlist. Do NOT design a connected app that
+serves multiple tenants from one deployment — per tenant, register
+a separate connected app (separate keys, separate routes). There is
+no cross-tenant resolution path, by construction.
+
 Connected apps are **Datalake-DB-resident** — the parent datalake
 must be `status: 'ready'` before you `create()`.
 
@@ -79,6 +88,15 @@ or multiple primaries returns a 422 on `/urls`.
 Additional URLs (staging, preview) are stored for reference but
 aren't used for route discovery or link minting.
 
+**`urls` models environments, NOT tracking domains.** The list is
+production / staging / preview deployments of the *same* app — and the
+one flagged `is_primary` silently becomes the domain of **every** magic
+link this app mints (see §6). It is NOT a way to serve links from
+several tracking domains: to mint links on two different domains you
+need **two connected apps**, one per domain. An agent that sees
+`urls: [...]` and reaches for "add another tracking domain here" gets
+this wrong — reach for a second connected app instead.
+
 ### Route discovery is automatic + re-triggerable
 
 ```
@@ -219,7 +237,8 @@ and can be retried via `.syncRoutes`.
 ### Read shapes — management
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
 .get(tenantSlug, datalakeSlug, id)           One row, by UUID
 .metadata(tenantSlug, datalakeSlug)          Markdown catalog
 .metadataDetails(tenantSlug, datalakeSlug,   Markdown for one app
@@ -246,6 +265,13 @@ lands `status: 'synced'` (or `'error'`) on the app row asynchronously.
 Poll `.get()` for the outcome. Use it after deploying a new manifest,
 fixing a primary URL outage, or recovering from `status: 'error'`.
 
+**Route-sync is the only "does this domain work" check the platform
+performs — there is NO DNS verification.** The platform never resolves
+or validates the primary URL's DNS/ownership; it just attempts the
+HTTP fetch of `/.well-known/routes.json`. A `status: 'synced'` means
+"the manifest was fetched and parsed", not "this domain is verified as
+yours". Domain trust is your responsibility, not a platform gate.
+
 Discovery failure modes the platform handles explicitly — each
 leaves the row at `status: 'error'` with `error` populated:
 
@@ -294,7 +320,62 @@ Delete latency depends on the app's `mode`:
   `'deploying'` (during teardown) before disappearing. Poll
   `.get()` until 404 to confirm removal.
 
-## 6. Runtime: how magic links resolve
+## 6. How a tracked link is minted
+
+Before the runtime resolve flow, understand what the platform does at
+fire time to produce the link. When a workflow action that carries a
+`connected_app_id` executes, the platform mints a **page token** and
+injects its URL into the message body:
+
+```
+   action fires
+      │  action.connected_app_id + connected_app_route
+      │  + rendered connected_app_metadata_template (Liquid → JSON)
+      ▼
+   page token row  ── keyed on the MDM SUBJECT id + the route,
+      │              carrying the rendered metadata JSON INSIDE it
+      ▼
+   {{ connected_app_form_url }}  =  https://<primary-url>/t/<url_hash>
+      │  (primary-url = the connected app's is_primary URL)
+      ▼
+   message row created with the link in its body
+      │
+      ▼
+   page token backfilled with that message's id  ← wires token → message
+```
+
+Key consequences to design around:
+
+- **The `connected_app_metadata_template` is how per-recipient data
+  reaches the app without hard-coding a URL.** It's a Liquid template
+  that renders to a JSON object, stored *inside* the page token; the
+  app reads it back at `resolvePage` time (as `page.metadata`) and uses
+  it to prefill / redirect that specific recipient. This is the
+  mechanism for "send each recipient to their own destination" — put
+  the per-recipient values in the metadata template, not in the URL.
+
+- **No MDM subject ⇒ no page token ⇒ no link.** The page token
+  *requires* a subject id (it is keyed on the resolved MDM subject). If
+  the row didn't resolve to a subject, the mint fails — but **the send
+  still goes out**: the mint failure is a logged warning, not an action
+  failure, so `{{ connected_app_form_url }}` simply renders **empty**
+  and the recipient gets a message with a missing link. A
+  message-with-no-link is the symptom of a workflow whose
+  `skip_mdm_resolution` was left `true`, or whose row carries no entity
+  FK (see `workflows.md` §3). If your action mints links, the workflow
+  MUST resolve a subject.
+
+- **Tracked links expire — 7 days by default.** The page token is
+  stamped with a TTL (604,800 s) at mint; `resolvePage` checks
+  `expires_at` and an expired token fails to resolve (HTTP 410).
+  "How long does a campaign link stay live?" — a week, unless the
+  platform default changes. Long-lead campaigns must account for it.
+
+The `{{ connected_app_form_url }}` variable is available only in action
+bodies whose action has a `connected_app_id`; it renders empty
+otherwise.
+
+## 7. Runtime: how magic links resolve
 
 This section covers the runtime callers — the connected app
 deployment itself, not the admin.
@@ -343,7 +424,16 @@ await api.connectedApps.updateMessageTracking(
 
 Both calls are authenticated with the connected app's
 auto-provisioned machine-to-machine API key (typically configured as
-`ALVERA_API_KEY` in the deployment environment).
+`ALVERA_API_KEY` in the deployment environment). Both are also on
+the `public_api` (publishable-key) allowlist — alongside `ingest`,
+`ingest-file`, and `mdm/verify` — so a browser-side app holding
+only a publishable key can call them.
+
+**This is the engagement seam.** `updateMessageTracking` writes
+`opened_at` / `form_submitted_at` onto the message row — the
+open/click/conversion half of campaign analytics — and it NEVER
+changes `status` (delivery truth belongs to the action status
+updater; see `messages.md` §1 for who writes which field).
 
 ### Workflow-side wiring
 
@@ -362,7 +452,7 @@ connected_app_metadata_template  string — Liquid template rendering a JSON
 
 See `workflows.md` §7 for the action-level field detail.
 
-## 7. Gotchas
+## 8. Gotchas
 
 1. **Exactly one URL must be `is_primary: true`.** Zero or
    multiple primaries returns 422. The primary is what the
@@ -406,3 +496,25 @@ See `workflows.md` §7 for the action-level field detail.
 8. **Route manifests must be JSON arrays, not objects.** A
    common mistake is wrapping the routes in `{ "routes": [...] }`
    — the manifest's top-level must be the array itself.
+
+9. **No MDM subject ⇒ no link (but the message still sends).** Minting
+   a page token needs the resolved MDM subject; if the workflow row
+   didn't resolve one, the mint is skipped with a logged warning and
+   `{{ connected_app_form_url }}` renders empty — the recipient gets a
+   linkless message, not an error. If an action mints links, the
+   workflow must resolve a subject (`skip_mdm_resolution: false` + an
+   entity FK on the row; see `workflows.md` §3). See §6.
+
+10. **Tracked links expire (7-day default TTL).** A page token is valid
+    for 604,800 s from mint; `resolvePage` returns 410 for an expired
+    token. Account for it on long-lead campaigns.
+
+11. **`urls` are environments, not tracking domains.** The `is_primary`
+    URL becomes the domain of every minted link; the others are
+    reference-only. Multiple tracking domains = multiple connected apps
+    (see §2).
+
+12. **No DNS verification exists.** `status: 'synced'` means the
+    manifest was fetched and parsed, not that the domain is verified as
+    yours. Route-sync is the only reachability check the platform runs
+    (see §5).

package/.agent/cookbook/_fixtures/README.md

@@ -88,19 +88,19 @@ The `contact-us-triage-with-llm` cookbook ingests into a generic
 table via the auto-provisioned identity contract, so it loads no
 vendored template.
 
-### `accounts_receivable/`
+### `subscription/`
 
 | File | Consumed by cookbook(s) | Source-of-truth |
 |---|---|---|
-| `_customers_accounts_receivable_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_customer.liquid` |
-| `_customers_accounts_receivable_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_mdm.liquid` |
-| `stripe_customers_batch1.csv` (data) | `bulk-ingest` | `integration-tests/tests/accounts_receivable/fixtures/csv/stripe_customers_batch1.csv` |
+| `_customers_subscription_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/subscription/stripe/_customers_subscription_customer.liquid` |
+| `_customers_subscription_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/subscription/stripe/_customers_subscription_mdm.liquid` |
+| `stripe_customers_batch1.csv` (data) | `bulk-ingest` | `integration-tests/tests/subscription/fixtures/csv/stripe_customers_batch1.csv` |
 
-### `payment_risk/`
+### `payments/`
 
 | File | Consumed by cookbook(s) | Source-of-truth |
 |---|---|---|
-| `_payment_accounts_payment_risk_payment_account.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_payment_accounts_payment_risk_payment_account.liquid` |
-| `_payment_accounts_payment_risk_mdm.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_payment_accounts_payment_risk_mdm.liquid` |
-| `_compliance_screenings_payment_risk_compliance_screening.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_compliance_screenings_payment_risk_compliance_screening.liquid` |
-| `_compliance_screenings_payment_risk_mdm.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_compliance_screenings_payment_risk_mdm.liquid` |
+| `_payment_accounts_payments_payment_account.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_payment_accounts_payments_payment_account.liquid` |
+| `_payment_accounts_payments_mdm.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_payment_accounts_payments_mdm.liquid` |
+| `_compliance_screenings_payments_compliance_screening.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_compliance_screenings_payments_compliance_screening.liquid` |
+| `_compliance_screenings_payments_mdm.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_compliance_screenings_payments_mdm.liquid` |

package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid → payments/_compliance_screenings_payments_compliance_screening.liquid}

@@ -1,4 +1,4 @@
-{% comment %}Atomic FI ComplianceScreenings → PaymentRisk ComplianceScreening attrs
+{% comment %}Atomic FI ComplianceScreenings → Payments ComplianceScreening attrs
 
 Source: GET /api/compliance-screenings on Atomic FI (paginated; the
 fetch pipeline extracts the `data` array via the response_extractor_key

package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_mdm.liquid → payments/_compliance_screenings_payments_mdm.liquid}

@@ -1,4 +1,4 @@
-{% comment %}Atomic FI ComplianceScreenings → PaymentRisk MDM Input
+{% comment %}Atomic FI ComplianceScreenings → Payments MDM Input
 
 A CS row from Atomic FI references an account_holder UUID
 (`p.account_holder_id`). MDM-resolution side uses that as the external

package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_mdm.liquid → payments/_payment_accounts_payments_mdm.liquid}

@@ -1,4 +1,4 @@
-{% comment %}Atomic FI PaymentAccount → PaymentRisk MDM Input
+{% comment %}Atomic FI PaymentAccount → Payments MDM Input
 
 A PaymentAccount row from Atomic FI references an account_holder UUID
 (`p.account_holder_id`) — that's the canonical external identity used by

package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_payment_account.liquid → payments/_payment_accounts_payments_payment_account.liquid}

@@ -1,4 +1,4 @@
-{% comment %}Atomic FI PaymentAccount → PaymentRisk PaymentAccount attrs
+{% comment %}Atomic FI PaymentAccount → Payments PaymentAccount attrs
 
 Source: GET /api/payment-accounts on Atomic FI (paginated; the fetch
 pipeline extracts the `data` array via the response_extractor_key and

package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_customer.liquid → subscription/_customers_subscription_customer.liquid}

@@ -1,4 +1,4 @@
-{% comment %}Stripe Customers → Accounts Receivable Customer attrs{% endcomment %}
+{% comment %}Stripe Customers → Subscription Customer attrs{% endcomment %}
 {% assign p = msg %}
 {
   "customer_type": "{{ p.customer_type | default: "individual" | json_escape }}",

package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_mdm.liquid → subscription/_customers_subscription_mdm.liquid}

@@ -1,4 +1,4 @@
-{% comment %}Stripe Customers → Accounts Receivable MDM Input{% endcomment %}
+{% comment %}Stripe Customers → Subscription MDM Input{% endcomment %}
 {% assign p = msg %}
 {
   "identifiers": [

package/.agent/cookbook/_setup/foundation.md

@@ -35,13 +35,15 @@ having to copy-paste this prelude.
 ## 001 — root admin signs in and provisions a fresh industry-admin user
 
 Authenticate as the platform's root admin (`admin@dev.local` /
-`devpassword` in local dev). Then sign up a per-run industry-admin
+`devpassword` in local dev) via the tenantless bootstrap login —
+keyless by structural necessity (no tenant exists yet to scope a
+key to), and a dev/test-only surface. Then sign up a per-run industry-admin
 user (`sarah`) under a unique email derived from `runSuffix`, and
 confirm them so they can sign in. Both the signup and the confirm
 endpoints require root scope.
 
 ```typescript
-ctx.rootSession = await createSession({
+ctx.rootSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: process.env.ALVERA_ROOT_EMAIL!,
   password: process.env.ALVERA_ROOT_PASSWORD!,
@@ -49,12 +51,13 @@ ctx.rootSession = await createSession({
 ctx.rootApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.rootSession.sessionToken,
+  apiKey: '',
 })
 
 ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
 ctx.sarahPassword = 'CookbookPass1!'
 
-const signUpResp = await ctx.rootApi.auth.signUp({
+const signUpResp = await ctx.rootApi.admin.signUp({
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   first_name: 'Cookbook',
@@ -72,7 +75,7 @@ foundation tenant. The tenant's server-derived `slug` is captured
 into the closure-scoped `tenantSlug` slot for downstream steps.
 
 ```typescript
-ctx.sarahTenantlessSession = await createSession({
+ctx.sarahTenantlessSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
@@ -80,6 +83,7 @@ ctx.sarahTenantlessSession = await createSession({
 ctx.sarahTenantlessApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.sarahTenantlessSession.sessionToken,
+  apiKey: '',
 })
 
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
@@ -96,15 +100,28 @@ is assigned to the closure-scoped `api` slot so the scenario
 cookbook's steps inherit it via inlining.
 
 ```typescript
+// A tenant-scoped login requires X-API-Key — mint a public_api key for
+// the fresh tenant via the platform-admin side door (root Bearer). In the
+// web console this is Settings -> API Keys; any of the tenant's keys
+// satisfies the login gate, and the minted Bearer inherits this key's
+// origin policy.
+const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: `Cookbook Bootstrap Key ${runSuffix}`,
+  data_access_mode: 'unregulated',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
 const sarahTenantSession = await createSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   tenantSlug,
+  apiKey: ctx.tenantApiKey,
 })
 api = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: sarahTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
 })
 ```
 
@@ -262,6 +279,9 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
   credentials (kept on `ctx` because no scenario cookbook needs
   to re-authenticate by default)
+- `ctx.tenantApiKey` — the tenant's publishable API key (minted in
+  setup via `admin.createTenantApiKey`); thread it into any
+  additional tenant-scoped `createSession` a scenario performs
 
 Scenario cookbooks under `industry: foundation` start at their own
 `§001` with these slots already populated.

package/.agent/cookbook/_setup/healthcare.md

@@ -35,13 +35,15 @@ having to copy-paste this prelude.
 ## 001 — root admin signs in and provisions a fresh industry-admin user
 
 Authenticate as the platform's root admin (`admin@dev.local` /
-`devpassword` in local dev). Then sign up a per-run industry-admin
+`devpassword` in local dev) via the tenantless bootstrap login —
+keyless by structural necessity (no tenant exists yet to scope a
+key to), and a dev/test-only surface. Then sign up a per-run industry-admin
 user (`sarah`) under a unique email derived from `runSuffix`, and
 confirm them so they can sign in. Both the signup and the confirm
 endpoints require root scope.
 
 ```typescript
-ctx.rootSession = await createSession({
+ctx.rootSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: process.env.ALVERA_ROOT_EMAIL!,
   password: process.env.ALVERA_ROOT_PASSWORD!,
@@ -49,12 +51,13 @@ ctx.rootSession = await createSession({
 ctx.rootApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.rootSession.sessionToken,
+  apiKey: '',
 })
 
 ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
 ctx.sarahPassword = 'CookbookPass1!'
 
-const signUpResp = await ctx.rootApi.auth.signUp({
+const signUpResp = await ctx.rootApi.admin.signUp({
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   first_name: 'Cookbook',
@@ -72,7 +75,7 @@ healthcare tenant. The tenant's server-derived `slug` is captured
 into the closure-scoped `tenantSlug` slot for downstream steps.
 
 ```typescript
-ctx.sarahTenantlessSession = await createSession({
+ctx.sarahTenantlessSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
@@ -80,6 +83,7 @@ ctx.sarahTenantlessSession = await createSession({
 ctx.sarahTenantlessApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.sarahTenantlessSession.sessionToken,
+  apiKey: '',
 })
 
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
@@ -96,15 +100,28 @@ is assigned to the closure-scoped `api` slot so the scenario
 cookbook's steps inherit it via inlining.
 
 ```typescript
+// A tenant-scoped login requires X-API-Key — mint a public_api key for
+// the fresh tenant via the platform-admin side door (root Bearer). In the
+// web console this is Settings -> API Keys; any of the tenant's keys
+// satisfies the login gate, and the minted Bearer inherits this key's
+// origin policy.
+const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: `Cookbook Bootstrap Key ${runSuffix}`,
+  data_access_mode: 'unregulated',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
 const sarahTenantSession = await createSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   tenantSlug,
+  apiKey: ctx.tenantApiKey,
 })
 api = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: sarahTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
 })
 ```
 
@@ -263,6 +280,9 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
   credentials (kept on `ctx` because no scenario cookbook needs
   to re-authenticate by default)
+- `ctx.tenantApiKey` — the tenant's publishable API key (minted in
+  setup via `admin.createTenantApiKey`); thread it into any
+  additional tenant-scoped `createSession` a scenario performs
 
 Scenario cookbooks under `industry: healthcare` start at their own
 `§001` with these slots already populated.