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

package/.agent/cookbook/dunning-sms-for-delinquent.md

@@ -1,16 +1,16 @@
 ---
 title: Send a payment-reminder SMS to delinquent customers with a pay-invoice link
 summary: End-to-end standard workflow — provision a Dunning SMS workflow over the AR customer dataset, ingest two Stripe customer rows (one phone + tax-id verified, one missing tax-id) through a customer interop contract, run the workflow so the SMS-reachable-and-KYC-complete filter routes each row, read the rendered SMS back from the message dataset, and close the connected-app reply loop. No agent, no LLM.
-industry: accounts_receivable
+industry: subscription
 slug: dunning-sms-for-delinquent
 vitest_source:
-  - integration-tests/tests/accounts_receivable/dunning-sms-workflow.test.ts
-  - integration-tests/tests/accounts_receivable/interoperability-contracts.test.ts
-  - integration-tests/tests/accounts_receivable/run-dac-single.test.ts
-  - integration-tests/tests/accounts_receivable/create-dac.test.ts
-  - integration-tests/tests/accounts_receivable/tools.test.ts
-  - integration-tests/tests/accounts_receivable/data-sources.test.ts
-  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+  - integration-tests/tests/subscription/dunning-sms-workflow.test.ts
+  - integration-tests/tests/subscription/interoperability-contracts.test.ts
+  - integration-tests/tests/subscription/run-dac-single.test.ts
+  - integration-tests/tests/subscription/create-dac.test.ts
+  - integration-tests/tests/subscription/tools.test.ts
+  - integration-tests/tests/subscription/data-sources.test.ts
+  - integration-tests/tests/subscription/bootstrap.test.ts
 status: green
 ---
 
@@ -45,10 +45,10 @@ connected-app deep-link the SMS carries — closing the SMS → reply
 loop.
 
 The scenario is anchored to
-`platform/integration-tests/tests/accounts_receivable/dunning-sms-workflow.test.ts`
+`platform/integration-tests/tests/subscription/dunning-sms-workflow.test.ts`
 — a green end-to-end test (§1–§8) that exercises this exact shape.
 This cookbook is a prose re-presentation of what that test walks.
-The setup file `_setup/accounts_receivable.md` already provisioned
+The setup file `_setup/subscription.md` already provisioned
 the tenant, datalake, and industry-admin client; this cookbook
 starts from there.
 
@@ -64,7 +64,7 @@ starts from there.
 | Stripe Customer interop contract | build       |
 | Manual-upload DAC                | build       |
 
-The setup file `_setup/accounts_receivable.md` already
+The setup file `_setup/subscription.md` already
 provisioned the tenant + datalake + tenant-scoped client; this
 cookbook starts from there.
 
@@ -269,17 +269,17 @@ customer or an existing one.
 const { readFileSync } = await import('node:fs')
 const { join } = await import('node:path')
 const customerTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'accounts_receivable/_customers_accounts_receivable_customer.liquid'),
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'subscription/_customers_subscription_customer.liquid'),
   'utf8',
 )
 const mdmTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'accounts_receivable/_customers_accounts_receivable_mdm.liquid'),
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'subscription/_customers_subscription_mdm.liquid'),
   'utf8',
 )
 
 const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
   name: `Cookbook Stripe Customer Contract ${runSuffix}`,
-  description: 'Stripe customers → AccountsReceivable Customer (custom Liquid + MDM input).',
+  description: 'Stripe customers → Subscription Customer (custom Liquid + MDM input).',
   resource_type: 'customer',
   template_config: { type: 'custom', body: customerTemplate },
   mdm_input_config: { type: 'custom', body: mdmTemplate },
@@ -561,7 +561,7 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 # Rollback
 
 The cookbook doctest harness does not currently tear down created
-resources. The `_setup/accounts_receivable.md` setup file's
+resources. The `_setup/subscription.md` setup file's
 runSuffix-scoped tenant / datalake / user names mean each run is
 naturally isolated; the seeded local DB is cheap to reset
 (`mix ecto.reset` on the platform repo).
@@ -570,8 +570,8 @@ naturally isolated; the seeded local DB is cheap to reset
 
 After this cookbook's thirteen steps run green:
 
-- An accounts-receivable tenant exists with an
-  accounts-receivable-domain datalake
+- An subscription tenant exists with an
+  subscription-domain datalake
 - An SMS tool, a Dunning payment-portal connected app, and a
   Dunning SMS standard workflow (status `live`, `customer`
   dataset) are registered
@@ -595,7 +595,7 @@ link — is demonstrated end-to-end, not merely provisioned.
 
 # See also
 
-- `_setup/accounts_receivable.md` — the inlined bootstrap that
+- `_setup/subscription.md` — the inlined bootstrap that
   provisions the tenant + datalake this cookbook starts from
 - `welcome-sms-for-customers.md` — the sibling AR cookbook; same
   customer-dataset shape, a simpler phone-only filter
@@ -609,11 +609,11 @@ link — is demonstrated end-to-end, not merely provisioned.
   interop contract → DAC ingestion chain
 - `.agent/workflows.md` — standard workflow primitive (filter +
   decision + actions), `context_datasets`, `workflows.run`
-- `.agent/cookbook/_fixtures/accounts_receivable/` — the vendored
+- `.agent/cookbook/_fixtures/subscription/` — the vendored
   Stripe customer / MDM Liquid templates §006 loads
-- `integration-tests/tests/accounts_receivable/dunning-sms-workflow.test.ts` —
+- `integration-tests/tests/subscription/dunning-sms-workflow.test.ts` —
   the anchor green test (§1–§8) these snippets are lifted from
-- `integration-tests/tests/accounts_receivable/interoperability-contracts.test.ts`,
+- `integration-tests/tests/subscription/interoperability-contracts.test.ts`,
   `run-dac-single.test.ts`, `create-dac.test.ts`, `tools.test.ts`,
   `data-sources.test.ts` — the per-resource create + ingest
   snippets §004–§009 are lifted from

package/.agent/cookbook/{custom-tables.md → generic-tables.md}

@@ -1,11 +1,11 @@
 ---
-title: "Capability: stand up a custom table the platform doesn't model"
-summary: A capability walk for generic tables. Create a custom table with typed, privacy-tagged columns (`api.genericTables.create`), wait for it to deploy, use the default ingestion client the platform auto-provisions for it, ingest a row (`api.dataActivationClients.ingest`), and read it back by its unique key (`api.datasets.search`). For data the built-in datasets don't cover.
-industry: accounts_receivable
-slug: custom-tables
+title: "Capability: stand up a generic table the platform doesn't model"
+summary: A capability walk for generic tables. Create a generic table with typed, privacy-tagged columns (`api.genericTables.create`), wait for it to deploy, use the default ingestion client the platform auto-provisions for it, ingest a row (`api.dataActivationClients.ingest`), and read it back with read-only SQL (`api.datalakes.executeSql`). For data the built-in datasets don't cover.
+industry: subscription
+slug: generic-tables
 vitest_source:
-  - integration-tests/tests/accounts_receivable/generic-tables.test.ts
-  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+  - integration-tests/tests/subscription/generic-tables.test.ts
+  - integration-tests/tests/subscription/bootstrap.test.ts
 status: green
 ---
 
@@ -23,17 +23,17 @@ The lifecycle is:
    **auto-provisions a default Data Activation Client** bound to an identity
    contract — no tool, contract, or DAC to wire by hand.
 3. `dataActivationClients.ingest(...)` a row through that default client.
-4. `datasets.search(...)` it back by its unique column.
+4. `datalakes.executeSql(...)` reads it back by its unique column with read-only SQL.
 
 This is **global** to every datalake — only the table's domain meaning differs.
 See `generic_tables.md` for the column reference.
 
 # Walkthrough
 
-The `_setup/accounts_receivable.md` bootstrap left `api`, `tenantSlug`, and
+The `_setup/subscription.md` bootstrap left `api`, `tenantSlug`, and
 `datalakeSlug` populated.
 
-## 001 — list existing custom tables (sanity)
+## 001 — list existing generic tables (sanity)
 
 `genericTables.list` returns the paginated `{ data, meta }` envelope. A fresh
 datalake has none; the call just confirms the surface is reachable.
@@ -45,7 +45,7 @@ if (!Array.isArray(existing.data)) {
 }
 ```
 
-## 002 — create the custom table
+## 002 — create the generic table
 
 Declare the table with a `title` and `columns`. Each column has a `type`, an
 `is_unique` flag, and — load-bearing — a `privacy_requirement` that decides how
@@ -115,7 +115,7 @@ while (Date.now() < deadline && !defaultDacSlug) {
   if (!defaultDacSlug) await new Promise((r) => setTimeout(r, 1_000))
 }
 if (!defaultDacSlug) {
-  throw new Error('default DAC for the custom table was not provisioned within 30s')
+  throw new Error('default DAC for the generic table was not provisioned within 30s')
 }
 ctx.defaultDacSlug = defaultDacSlug
 ```
@@ -144,34 +144,34 @@ if (!ingest.batch_id) {
 }
 ```
 
-## 006 — read the row back by its unique key
+## 006 — read the row back with read-only SQL
 
-Search the `generic_table` dataset, scoped to this table via `generic_table_id`,
-filtering on the regulated table name (`regulated_<table_name>`) and the unique
-column. `createUserSearch` compiles the query; `search` returns rows once
-ingestion has landed — poll until the row appears.
+`executeSql` runs a read-only statement against the datalake and returns a page
+as `{ data, meta }` — `data` is an array-of-arrays aligned positionally to
+`meta.columns`. `mode: 'unregulated'` runs it against the unregulated schema, so
+you reference the table by its server-derived `name` (the `alvera_custom_…`
+value from §002 — `mode` selects the schema, so no `regulated_`/`unregulated_`
+prefix). Ingestion is async, so poll until the row lands.
 
 ```typescript
-const { data: userSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'generic_table', {
-  search_query: `regulated_${ctx.tableName}.submission_id = '${ctx.submissionId}'`,
-  generic_table_id: genericTableId,
-})
-if (userSearch.status !== 'completed') {
-  throw new Error(`user-search did not compile: ${userSearch.status}`)
-}
-
 const deadline = Date.now() + 45_000
-let rows: Array<Record<string, unknown>> = []
-while (Date.now() < deadline && rows.length === 0) {
-  const { data: page } = await api.datasets.search(tenantSlug, datalakeSlug, 'generic_table', {
-    userSearchId: userSearch.id!,
-    dataAccessMode: 'unregulated',
+let row: Record<string, unknown> | undefined
+while (Date.now() < deadline && !row) {
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT submission_id, customer_name, source_channel
+          FROM ${ctx.tableName}
+          WHERE submission_id = '${ctx.submissionId}'`,
+    mode: 'unregulated',
   })
-  rows = (page.data ?? []) as Array<Record<string, unknown>>
-  if (rows.length === 0) await new Promise((r) => setTimeout(r, 1_000))
+  // JSON envelope (a `string` only for `{ format: 'csv' }`); zip the positional
+  // row back into an object keyed by meta.columns.
+  if (typeof result !== 'string' && result.data.length > 0) {
+    row = Object.fromEntries(result.meta.columns.map((c, i) => [c, result.data[0][i]]))
+  }
+  if (!row) await new Promise((r) => setTimeout(r, 1_000))
 }
-if (!rows.some((r) => r.submission_id === ctx.submissionId)) {
-  throw new Error('ingested row not found in the custom table within 45s')
+if (!row || row.submission_id !== ctx.submissionId) {
+  throw new Error('ingested row not found in the generic table within 45s')
 }
 ```
 
@@ -182,20 +182,23 @@ if (!rows.some((r) => r.submission_id === ctx.submissionId)) {
   free text is scrubbed, `none` passes through. Dropping it silently changes who
   can see what.
 - **The table name is server-derived, never set by you.** The platform slugifies
-  the title and prefixes `alvera_custom_`. Read `name` off the create response;
-  the search query uses `regulated_<name>`.
+  the title and prefixes `alvera_custom_`. Read `name` off the create response and
+  reference it directly in `executeSql`; `mode` selects the schema, so you don't
+  add a `regulated_`/`unregulated_` prefix yourself.
 - **You don't create the ingestion client.** Deploying the table auto-provisions
   a default DAC + identity contract. Find it by name; don't build one.
-- **Two async waits.** Wait for `:deployed` before ingesting, then poll the
-  search until the row materializes — ingestion is async like every other
+- **Two async waits.** Wait for `:deployed` before ingesting, then poll
+  `executeSql` until the row materializes — ingestion is async like every other
   ingest path.
-- **`generic_table_id` on the search is required.** It routes the query to your
-  table's dataset; omitting it searches the wrong scope.
+- **`mode` picks the schema, and `tokenize` columns come back masked.** In
+  `mode: 'unregulated'` the read runs against the tokenized view, so filter and
+  assert on a `none` column (here `submission_id`); a `tokenize` column like
+  `customer_name` returns its token, not the raw value.
 
 # See also
 
 - `generic_tables.md` — column types, `privacy_requirement`, lifecycle reference
 - `data_activation_clients.md` — the `.ingest` runtime verb + dataset search
-- `_setup/accounts_receivable.md` — the bootstrap this walk starts from
-- `integration-tests/tests/accounts_receivable/generic-tables.test.ts` — the
+- `_setup/subscription.md` — the bootstrap this walk starts from
+- `integration-tests/tests/subscription/generic-tables.test.ts` — the
   green test these calls are lifted from

package/.agent/cookbook/invite-team.md

@@ -1,11 +1,11 @@
 ---
 title: "Capability: invite a teammate into your tenant"
 summary: A capability walk for multi-user onboarding. An admin invites a colleague by email (`api.invitations.create`), the colleague signs up and is confirmed, signs in without a tenant to find the pending invite (`invitations.list`), accepts it (`invitations.accept`), and finally signs in tenant-scoped as a member. Shows the three session scopes — root, tenantless, tenant-scoped — in one flow.
-industry: accounts_receivable
+industry: subscription
 slug: invite-team
 vitest_source:
-  - integration-tests/tests/accounts_receivable/invite-team.test.ts
-  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+  - integration-tests/tests/subscription/invite-team.test.ts
+  - integration-tests/tests/subscription/bootstrap.test.ts
 status: green
 ---
 
@@ -18,7 +18,7 @@ The flow touches all three session scopes (see `AGENTS.md` § SDK auth):
 
 - **tenant-scoped** (the admin) — `api.invitations.create(tenantSlug, { email, role })`
 - **root** — signs the new user up and confirms them
-  (`api.auth.signUp` + `api.admin.confirmUser`)
+  (`api.admin.signUp` + `api.admin.confirmUser`)
 - **tenantless** (the invitee, before they belong anywhere) — lists pending
   invites and accepts one (`api.invitations.list` / `api.invitations.accept`)
 
@@ -27,7 +27,7 @@ This capability is **global** — it works the same on every datalake's tenant.
 
 # Walkthrough
 
-The `_setup/accounts_receivable.md` bootstrap already provisioned the tenant and
+The `_setup/subscription.md` bootstrap already provisioned the tenant and
 left `api` as the admin's tenant-scoped client, with `tenantSlug` and
 `ctx.sarahEmail` / `ctx.sarahPassword` populated. Root credentials come from the
 `ALVERA_ROOT_EMAIL` / `ALVERA_ROOT_PASSWORD` env vars the validator already
@@ -83,7 +83,7 @@ root-scoped actions, so build a root client from the `ALVERA_ROOT_*` credentials
 and use it. `confirmUser` activates the account so the invitee can sign in.
 
 ```typescript
-const rootSession = await createSession({
+const rootSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: process.env.ALVERA_ROOT_EMAIL!,
   password: process.env.ALVERA_ROOT_PASSWORD!,
@@ -91,9 +91,10 @@ const rootSession = await createSession({
 const rootApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: rootSession.sessionToken,
+  apiKey: '',
 })
 
-const { data: emmaUser } = await rootApi.auth.signUp({
+const { data: emmaUser } = await rootApi.admin.signUp({
   email: ctx.emmaEmail,
   password: ctx.emmaPassword,
   first_name: 'Emma',
@@ -105,16 +106,16 @@ await rootApi.admin.confirmUser(emmaUser.id!)
 ## 004 — teammate signs in WITHOUT a tenant and finds the invite
 
 The invitee has an account but belongs to no tenant yet, so they sign in
-**tenantless** — `createSession` with no `tenantSlug`. The resulting session has
+**tenantless** — `createBootstrapSession` (`createSession` is tenant login
+only since the universal-key contract). The resulting session has
 `tenant: null`. A tenantless client can list the invitations waiting for that
 user. Find the one for this tenant by matching `tenant.slug`.
 
 ```typescript
-const emmaTenantless = await createSession({
+const emmaTenantless = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.emmaEmail,
   password: ctx.emmaPassword,
-  // no tenantSlug → tenantless session
 })
 if (emmaTenantless.tenant !== null) {
   throw new Error('expected a tenantless session (tenant should be null)')
@@ -122,6 +123,7 @@ if (emmaTenantless.tenant !== null) {
 const emmaTenantlessApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: emmaTenantless.sessionToken,
+  apiKey: '',
 })
 ctx.emmaTenantlessToken = emmaTenantless.sessionToken
 
@@ -142,6 +144,7 @@ the new `role` and the `tenant.slug` the user just joined.
 const emmaTenantlessApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.emmaTenantlessToken,
+  apiKey: '',
 })
 
 const { data: membership } = await emmaTenantlessApi.invitations.accept(ctx.invitationId)
@@ -153,7 +156,9 @@ if (membership.tenant?.slug !== tenantSlug || membership.role !== 'member') {
 ## 006 — teammate signs in tenant-scoped as a member
 
 Now that the membership exists, the invitee re-authenticates **with** the
-tenant slug. The new session carries `tenant.slug` and a `member` role — they
+tenant slug — which requires the tenant's API key (`ctx.tenantApiKey`, minted
+during setup): tenant-scoped sign-in is 401'd without a resolvable
+`X-API-Key`. The new session carries `tenant.slug` and a `member` role — they
 are in.
 
 ```typescript
@@ -162,6 +167,7 @@ const emmaScoped = await createSession({
   email: ctx.emmaEmail,
   password: ctx.emmaPassword,
   tenantSlug,
+  apiKey: ctx.tenantApiKey,
 })
 if (emmaScoped.tenant?.slug !== tenantSlug) {
   throw new Error(`expected a tenant-scoped session on ${tenantSlug}`)
@@ -189,6 +195,6 @@ if (!/member/i.test(emmaScoped.role?.name ?? '')) {
 
 - `AGENTS.md` § SDK auth + client construction — root / tenantless / tenant-scoped
 - `account_management.md` — users, roles, invitations reference
-- `_setup/accounts_receivable.md` — the bootstrap this walk starts from
-- `integration-tests/tests/accounts_receivable/invite-team.test.ts` — the green
+- `_setup/subscription.md` — the bootstrap this walk starts from
+- `integration-tests/tests/subscription/invite-team.test.ts` — the green
   test these calls are lifted from

package/.agent/cookbook/kyc-notification-on-account-activation.md

@@ -1,16 +1,16 @@
 ---
 title: Send a KYC-notification SMS when a payment account becomes active
-summary: End-to-end standard workflow — provision a KYC-notification workflow over the payment-risk payment_account dataset, ingest two Atomic FI payment-account rows (one active, one suspended) through a payment_account interop contract, run the workflow so the status filter routes each row, read the rendered SMS back from the message dataset, and close the connected-app reply loop. No agent, no LLM.
-industry: payment_risk
+summary: End-to-end standard workflow — provision a KYC-notification workflow over the payments payment_account dataset, ingest two Atomic FI payment-account rows (one active, one suspended) through a payment_account interop contract, run the workflow so the status filter routes each row, read the rendered SMS back from the message dataset, and close the connected-app reply loop. No agent, no LLM.
+industry: payments
 slug: kyc-notification-on-account-activation
 vitest_source:
-  - integration-tests/tests/payment_risk/standard-workflow.test.ts
-  - integration-tests/tests/payment_risk/interoperability-contracts.test.ts
-  - integration-tests/tests/payment_risk/run-dac-single.test.ts
-  - integration-tests/tests/payment_risk/create-dac.test.ts
-  - integration-tests/tests/payment_risk/tools.test.ts
-  - integration-tests/tests/payment_risk/data-sources.test.ts
-  - integration-tests/tests/payment_risk/bootstrap.test.ts
+  - integration-tests/tests/payments/standard-workflow.test.ts
+  - integration-tests/tests/payments/interoperability-contracts.test.ts
+  - integration-tests/tests/payments/run-dac-single.test.ts
+  - integration-tests/tests/payments/create-dac.test.ts
+  - integration-tests/tests/payments/tools.test.ts
+  - integration-tests/tests/payments/data-sources.test.ts
+  - integration-tests/tests/payments/bootstrap.test.ts
 status: green
 ---
 
@@ -28,7 +28,7 @@ active ones to an SMS sender — with the status gate living in
 application code.
 
 The Alvera platform's standard workflow primitive keeps that gate
-inside the platform. A payment-risk `payment_account` dataset is
+inside the platform. A payments `payment_account` dataset is
 the workflow's event source; a pure-Liquid filter gates on
 `payment_account.status == "active"`; a single SMS action carries
 a deep-link to a connected-app KYC portal. The
@@ -43,10 +43,10 @@ the message dataset, and finally resolves the connected-app
 deep-link the SMS carries — closing the SMS → reply loop.
 
 The scenario is anchored to
-`platform/integration-tests/tests/payment_risk/standard-workflow.test.ts`
+`platform/integration-tests/tests/payments/standard-workflow.test.ts`
 — a green end-to-end test (§1–§7) that exercises this exact shape.
 This cookbook is a prose re-presentation of what that test walks.
-The setup file `_setup/payment_risk.md` already provisioned the
+The setup file `_setup/payments.md` already provisioned the
 tenant, datalake, and industry-admin client; this cookbook starts
 from there.
 
@@ -62,7 +62,7 @@ from there.
 | Atomic FI Payment Account interop contract | build |
 | Manual-upload DAC                    | build       |
 
-The setup file `_setup/payment_risk.md` already provisioned the
+The setup file `_setup/payments.md` already provisioned the
 tenant + datalake + tenant-scoped client; this cookbook starts
 from there.
 
@@ -133,7 +133,7 @@ so the recipient knows which account activated, and
 `{{ connected_app_form_url }}` so the platform can bake in the
 `/t/<token>` KYC-portal link.
 
-`dataset_type: 'payment_account'` makes the payment-risk payment
+`dataset_type: 'payment_account'` makes the payments payment
 account dataset the event source; the workflow context injects
 the payment account row under the `payment_account` key, so the
 filter reads `payment_account.status` directly. A
@@ -142,7 +142,7 @@ KYC-notification SMS already sent to the same legal entity in the
 last six months — the platform's built-in guard against
 re-notifying. On a fresh tenant that lookup returns empty, which
 is harmless. The SMS `to` is a fixed inbox number because a
-payment-risk legal entity's contact fields are tokenized and not
+payments legal entity's contact fields are tokenized and not
 resolved into the SMS templating context here.
 
 ```typescript
@@ -250,7 +250,7 @@ ctx.manualUploadToolId = manualUploadToolResp.data.id!
 
 The interoperability contract is the row-shaping rule: a Liquid
 template that maps an inbound Atomic FI payment-account row into a
-payment-risk `PaymentAccount` upsert. This cookbook loads the
+payments `PaymentAccount` upsert. This cookbook loads the
 production Atomic FI payment-account + MDM templates from the
 vendored fixtures directory rather than inlining the Liquid.
 
@@ -266,17 +266,17 @@ to.
 const { readFileSync } = await import('node:fs')
 const { join } = await import('node:path')
 const paTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payment_risk/_payment_accounts_payment_risk_payment_account.liquid'),
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments/_payment_accounts_payments_payment_account.liquid'),
   'utf8',
 )
 const mdmTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payment_risk/_payment_accounts_payment_risk_mdm.liquid'),
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments/_payment_accounts_payments_mdm.liquid'),
   'utf8',
 )
 
 const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
   name: `Cookbook Atomic FI Payment Account Contract ${runSuffix}`,
-  description: 'Atomic FI payment-accounts → PaymentRisk PaymentAccount (custom Liquid + MDM input).',
+  description: 'Atomic FI payment-accounts → Payments PaymentAccount (custom Liquid + MDM input).',
   resource_type: 'payment_account',
   template_config: { type: 'custom', body: paTemplate },
   mdm_input_config: { type: 'custom', body: mdmTemplate },
@@ -559,7 +559,7 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 # Rollback
 
 The cookbook doctest harness does not currently tear down created
-resources. The `_setup/payment_risk.md` setup file's
+resources. The `_setup/payments.md` setup file's
 runSuffix-scoped tenant / datalake / user names mean each run is
 naturally isolated; the seeded local DB is cheap to reset
 (`mix ecto.reset` on the platform repo).
@@ -568,7 +568,7 @@ naturally isolated; the seeded local DB is cheap to reset
 
 After this cookbook's thirteen steps run green:
 
-- A payment-risk tenant exists with a payment-risk-domain
+- A payments tenant exists with a payments-domain
   datalake
 - An SMS tool, a KYC-portal connected app, and a KYC-notification
   standard workflow (status `live`, `payment_account` dataset)
@@ -594,10 +594,10 @@ demonstrated end-to-end, not merely provisioned.
 
 # See also
 
-- `_setup/payment_risk.md` — the inlined bootstrap that
+- `_setup/payments.md` — the inlined bootstrap that
   provisions the tenant + datalake this cookbook starts from
 - `sanctions-screening-with-agent-review.md` — the agent-driven
-  payment-risk cookbook; an LLM agent disambiguates gray-zone
+  payments cookbook; an LLM agent disambiguates gray-zone
   sanctions screenings
 - `.agent/tools.md` — SMS (`tool_body_type: sns`) and
   manual-upload tool body shapes; intent classification
@@ -609,11 +609,11 @@ demonstrated end-to-end, not merely provisioned.
   interop contract → DAC ingestion chain
 - `.agent/workflows.md` — standard workflow primitive (filter +
   decision + actions), `context_datasets`, `workflows.run`
-- `.agent/cookbook/_fixtures/payment_risk/` — the vendored Atomic
+- `.agent/cookbook/_fixtures/payments/` — the vendored Atomic
   FI payment-account / MDM Liquid templates §006 loads
-- `integration-tests/tests/payment_risk/standard-workflow.test.ts` —
+- `integration-tests/tests/payments/standard-workflow.test.ts` —
   the anchor green test (§1–§7) these snippets are lifted from
-- `integration-tests/tests/payment_risk/interoperability-contracts.test.ts`,
+- `integration-tests/tests/payments/interoperability-contracts.test.ts`,
   `run-dac-single.test.ts`, `create-dac.test.ts`, `tools.test.ts`,
   `data-sources.test.ts` — the per-resource create + ingest
   snippets §004–§009 are lifted from