@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/templates.md

@@ -4,9 +4,8 @@ Templates are an **INFRASTRUCTURE** building block: the platform
 ships a library of Liquid templates that other infrastructure
 resources consume — interoperability contracts, AI agent prompts,
 workflow definitions, status poller bodies. Templates are
-**read-only** from the SDK; the platform composes them
-per-industry, and each datalake's `data_domain` selects which
-surface in its catalog.
+**read-only** from the SDK — they ship with the platform and a
+datalake's catalog is whatever the platform exposes to it.
 
 SDK namespace: `api.templates`.
 
@@ -21,14 +20,15 @@ Three discovery methods, two complementary response shapes —
 structured (for code) and markdown (for agents):
 
 ```typescript
-import type { SystemTemplate } from '@alvera-ai/platform-sdk'
+// The systemTemplates catalog response has no exported type on the
+// public surface yet — `catalog` is inferred from the call.
 
 // Structured catalog
 const { data: catalog } = await api.templates.systemTemplates(
   tenantSlug,
   datalakeSlug,
 )
-// catalog.data: SystemTemplate[]  — the full in-scope list, NOT paginated
+// catalog.data — the full in-scope list, NOT paginated
 //   { path, content, output_schema }
 //     path           category/sub-category/name segment string
 //     content        Liquid template body
@@ -59,10 +59,12 @@ const { data: templateMd } = await api.templates.metadataDetails(
 Template paths follow `<category>/<sub-category>/<name>`.
 Categories the SDK exposes include
 `data_activation/interoperability/`, `ai_agents/`, `workflows/`,
-`status_poller/`. Categories with an industry segment (e.g.
-`ai_agents/<industry>/*`) filter to the datalake's `data_domain`;
-categories without (e.g. `status_poller/*/*`) are globals
-present in every catalog.
+`status_poller/`. Path segments below the category are platform-owned and have
+outlived at least one naming scheme, so **discover paths via
+`api.templates` rather than constructing them.** The
+`data_domain` filter that used to select a datalake's slice of
+the catalog was removed with GH-859; what remains is
+server-decided.
 
 ## 3. Lifecycle
 
@@ -84,10 +86,9 @@ trying to add to the catalog.
    `'data_activation_interoperability'`). Check the typed
    parameter for the valid set; multiple templates can share a
    basename across intents. Within a single intent, the basename
-   must resolve uniquely under its `<intent>+<data_domain>`
-   prefix — if two sub-directories under that prefix ship the same
-   basename (e.g. two vendors under
-   `data_activation/interoperability/<industry>/`),
+   must resolve uniquely under its `<intent>` prefix — if two
+   sub-directories under that prefix ship the same basename (e.g.
+   two vendors under `data_activation/interoperability/`),
    `metadataDetails` returns `409 Conflict` with the candidate
    paths; a missing basename returns `404`.
 

package/.agent/tools.md

@@ -116,17 +116,27 @@ mistake with a consequence: a `rest_api` Twilio sender has no
 happened to it** — no delivery status, no reconciliation.
 
 ```typescript
+import { ToolIntent } from '@alvera-ai/platform-sdk'
+
 await api.tools.create(tenantSlug, datalakeSlug, {
   name: 'Campaign Sender — Main Line',
-  intent: 'sms',
-  tool_body_type: 'twilio',
-  variant_type: 'primary',
-  account_sid: 'AC…',           // "AC" + 32 hex
-  auth_token: '…',              // writeOnly — never comes back on a read
-  from_number: '+15550000001',  // XOR with messaging_service_sid
-  // base_url    — nullable; blank means https://api.twilio.com
-  // timeout_ms  — 1..300000, nullable
-  // base_message — ComplexTemplateConfig
+  description: 'Twilio sender for the campaign workflow.',
+  intent: ToolIntent.SMS,
+  status: 'active',
+  datalake_id: datalakeId,
+  // The provider-specific fields are NESTED under `body`, discriminated by
+  // `tool_body_type` — they are not top-level keys on the create request.
+  // Flattening them is the most common 422 on this endpoint.
+  body: {
+    tool_body_type: 'twilio',
+    variant_type: 'primary',
+    account_sid: 'AC…',           // "AC" + 32 hex
+    auth_token: '…',              // writeOnly — never comes back on a read
+    from_number: '+15550000001',  // XOR with messaging_service_sid
+    // base_url    — nullable; blank means https://api.twilio.com
+    // timeout_ms  — 1..300000, nullable
+    // base_message — ComplexTemplateConfig
+  },
 })
 ```
 
@@ -627,13 +637,34 @@ await api.tools.testInvocation(
 inlines the value verbatim; `type: 'system'` references a
 platform-shipped template (see `templates.md`).
 
-**Test-invocation accepts exactly FIVE `tool_call_type` variants** —
-the interactive ones. Its request casts into a `ManualToolInvocation`
-embed (`on_type_not_found: :raise`) whose polymorphic set is
-`sms_request`, `mms_request`, `email_request`, `restapi_request`,
-`aws_lambda_request`. A tool whose body is SFTP / S3 / SQL /
-SharePoint has **no** test-invocation variant and cannot be exercised
-through this endpoint (same shape as the `status_poller` case below).
+**Test-invocation accepts SIX `tool_call_type` variants** — the
+interactive ones. Its request casts into a `ManualToolInvocation` embed
+(`on_type_not_found: :raise`) whose polymorphic set is `sms_request`,
+`mms_request`, `email_request`, `restapi_request`, `aws_lambda_request`
+and `sql_query`.
+
+THREE LISTS LIVE HERE and conflating them is the mistake this paragraph
+used to make. `tool_body_type` says what a tool IS (12 variants — `sns`,
+`twilio`, `s3`, `sql_database`, `sftp`, `sharepoint`, `manual_upload`, …).
+`tool_call_type` says how a CALL is shaped (9). Test-invocation accepts a
+subset of the call types (6). They do not map one-to-one: `sns` and
+`twilio` are both bodies that send SMS, so both call through
+`sms_request`; the `sql_database` body calls through `sql_query`.
+
+So a tool whose body is **S3, SFTP or SharePoint** has no test-invocation
+variant and cannot be exercised through this endpoint (same shape as the
+`status_poller` case below). SFTP and SharePoint are coming; S3 is not
+currently reachable this way either.
+
+**`manual_upload` is the exception worth knowing.** It is excluded from
+test-invocation, but it is NOT unexecutable — it has a real executor
+(`Platform.Tools.ManualUpload`, protocols.ex:105) which routes to the
+`ingest_json` path rather than the automated fetch pipeline. There is
+nothing to dial interactively because the input is a file someone
+supplies; the tool still runs. A born-red contract that demands a
+test-invocation smoke for a manual-upload tool is therefore asking for
+something that cannot exist, and the cure is to assert the tool's
+configuration and its provenance binding instead.
 Those config shapes still exist — but on the broader **workflow-action
 `ToolCallConfig`** surface (see `tool-call-configs.md`), not here. The
 per-branch required-list for the five test-invocable variants:
@@ -661,10 +692,18 @@ per-branch required-list for the five test-invocable variants:
 
    tool_call_type: 'restapi_request'
      required:   path, method, pagination_context_template
-     enums:      method ∈ HTTP methods (GET, POST, PUT, PATCH, DELETE,
-                 HEAD, OPTIONS)
-     optional:   body, params (each TemplateConfig — 'identity' or
-                 'custom' both accepted)
+     enums:      method ∈ 'head' | 'get' | 'put' | 'post' | 'delete' |
+                 'patch' — LOWERCASE. 'POST' is rejected as
+                 `/tool_call/method — Invalid value for enum`.
+     optional:   body, params
+     shapes:     path, body, params and pagination_context_template are
+                 EACH a TemplateConfig ({ type, body }) — 'identity' or
+                 'custom' both accepted. `path` is NOT a plain string;
+                 passing one is `/tool_call/path — Invalid value: Invalid
+                 object. Got: string`. It is an envelope so a path can be
+                 interpolated per row.
+                 pagination_context_template is required even with nothing
+                 to paginate — `{ type: 'null' }` is how you say so.
 
    tool_call_type: 'aws_lambda_request'
      required:   payload (TemplateConfig — 'identity' acceptable)
@@ -714,9 +753,12 @@ that is the cheapest way to prove its credentials:
 await api.tools.testInvocation(tenantSlug, datalakeSlug, pollerId, {
   tool_call: {
     tool_call_type: 'restapi_request',
-    method: 'get',
+    method: 'get' as const,
     path: { type: 'custom', body: '/v3/YOUR-DOMAIN/events' },
     params: { type: 'custom', body: '{"limit": 1}' },   // keep it read-only
+    // REQUIRED, even for a one-shot probe: a REST call must always say
+    // whether there is another page. Omit it and the create is refused.
+    pagination_context_template: { type: 'custom', body: '{"has_next": false}' },
   },
 })
 ```

package/.agent/type_naming.md

@@ -91,26 +91,26 @@ The canonical pattern — capture both returned identifiers and use
 each for the calls it keys:
 
 ```typescript
-// 1. create — id AND slug are both returned in the response
+// 1. create — every response carries `id`; only SOME carry `slug`.
 const { data: created } = await api.tools.create(
   tenantSlug, datalakeSlug, body,
 )
-const toolId = created.id       // <-- CRUD + cross-resource refs
-const toolSlug = created.slug   // <-- human handle; ops verbs on
-                                //     resources that expose them
+const toolId = created.id!      // <-- CRUD + cross-resource refs
+
+// A tool has NO slug, and neither does a generic table — they are
+// addressed by id and by name respectively. The slug-bearing responses
+// are the ones whose ops verbs take a slug in the path: datalakes,
+// workflows, data activation clients, connected apps, AI agents and
+// interoperability contracts. Reach for `.slug` only on those, and
+// note every id and slug is optional on the wire, so a strict consumer
+// needs the `!` (or a guard) that the cookbooks use.
 
 // 2a. CRUD reads/updates key on the UUID id
 await api.tools.get(tenantSlug, datalakeSlug, toolId)
 
-// 2b. downstream resources reference the tool by id
-await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
-  updater_tool_id: toolId,
-  action_log_config: {
-    type: 'custom',
-    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
-  },
-  // …
-})
+// 2b. downstream resources reference the tool by ID, never by name or
+//     slug — see action_status_updaters.md for the full body:
+//       updater_tool_id: toolId
 ```
 
 Never:

package/.agent/workflows.md

@@ -37,8 +37,8 @@ connected apps, AI agents) must exist before you `create()`.
 
 ```typescript
 import type {
-  WorkflowRequestWritable,
-  WorkflowResponse,
+  AgenticWorkflowRequestWritable,
+  AgenticWorkflowResponse,
 } from '@alvera-ai/platform-sdk'
 
 const { data: created } = await api.workflows.create(
@@ -47,12 +47,23 @@ const { data: created } = await api.workflows.create(
   {
     name: 'Appointment Review SMS',
     description: 'Send a review-request SMS after a fulfilled appointment',
-    dataset_type: 'appointment',            // the dataset this workflow listens on
+
+    // The workflow listens on ONE generic table, named by id. The
+    // platform's own dataset types (legal_entity, message,
+    // action_log, ...) are the other legal values — see §4.
+    dataset_type: 'generic_table',
+    generic_table_id: appointmentsTableId,
+
+    // Load-bearing whenever an action mints a per-subject
+    // `connected_app_form_url`: resolution is what attaches the row
+    // to its legal entity. See §2.
+    skip_mdm_resolution: false,
+
     status: 'live',                         // 'live' | 'draft' | 'manual' (see §5)
     tags: ['appointments', 'sms'],          // REQUIRED on every write — [] if untagged (see §2)
     filter_config: {
       type: 'custom',
-      body: `{% if appointment.source_uri == "12345.example.com" %}true{% endif %}`,
+      body: '{% if event_dataset.status == "fulfilled" %}true{% endif %}',
       // NO output_schema here — filter_config takes { type, body } only.
       // See §2: output_schema is server-pinned for filter_config, not a
       // request field.
@@ -65,30 +76,37 @@ const { data: created } = await api.workflows.create(
     context_datasets: [
       {
         dataset_type: 'message',
-        where_clause: `rm.patient_id = '{{ patient_id }}' AND rm.sent_at > NOW() - INTERVAL '6 months'`,
+        where_clause:
+          `m.legal_entity_id = '{{ legal_entity_id }}' ` +
+          `AND m.sent_at > NOW() - INTERVAL '6 months'`,
         limit: 1,
         position: 0,
       },
     ],
     actions: [
       {
-        action_type: 'sms',
+        action_type: ActionType.SMS,
         tool_id: smsToolId,
         decision_key: 'send_appointment_review_sms',
         position: 0,
         trigger_template: 'now',                // 'now' = next available slot
         action_window_start: 9,                 // send only 09:00–20:59 in the
         action_window_end: 21,                  //   datalake tz (SMS quiet-hours failsafe; see §2)
+
+        // Row identity for a generic_table workflow is the event
+        // row's own unique column. There is no {{ subject_id }} —
+        // see §2, and note an unknown binding renders EMPTY.
         idempotency_template:
-          '{{ patient_id }}-{{ appointment.unregulated_appointment_id }}-{{ decision_key }}',
+          '{{ event_dataset.appointment_id }}-{{ decision_key }}',
+
         connected_app_id: connectedAppId,
         connected_app_route: '/forms/review',
         connected_app_metadata_template:
-          '{"appointment_id":"{{ appointment.unregulated_appointment_id }}"}',
+          '{"appointment_id":"{{ event_dataset.appointment_id }}"}',
         tool_call: {
           tool_call_type: 'sms_request',
-          to:   { type: 'custom', body: '{{ patient_phone }}' },
-          body: { type: 'custom', body: 'Hi {{ patient_first_name }}, please share your feedback at {{ connected_app_form_url }}' },
+          to:   { type: 'custom', body: '{{ event_dataset.patient_mobile | e164 }}' },
+          body: { type: 'custom', body: 'Hi {{ event_dataset.patient_name | split: " " | first }}, please share your feedback at {{ connected_app_form_url }}' },
           sms_type: 'transactional',
         },
       },
@@ -176,13 +194,21 @@ dataset row; the platform deduplicates so the same idempotency
 key never fires twice. Typical recipe:
 
 ```
-'{{ <subject_id> }}-{{ <event_id> }}-{{ decision_key }}'
+'{{ <row identity> }}-{{ action_id }}-{{ decision_key }}'
 ```
 
-The placeholder names depend on the workflow's `dataset_type`
-(patient_id + appointment.unregulated_appointment_id for an
-appointment-driven workflow, customer_id + invoice.id for an
-invoice-driven workflow, etc.).
+The row identity depends on the workflow's `dataset_type`. For a
+`generic_table` workflow it is the event row's unique column —
+`{{ event_dataset.submission_id }}`, `{{ event_dataset.customer_number }}`;
+for a `legal_entity` workflow the row IS the subject, so it is
+`{{ legal_entity.id }}`.
+
+**There is no `{{ subject_id }}`.** GH-859 removed it along with the
+per-domain subjects (`patient_id`, `customer_id`, `party_id`), and it is a
+trap rather than merely a rename: an unknown binding renders EMPTY instead of
+failing, so a template still using one produces a key that is missing the very
+component it exists to key on — and nothing anywhere says so. If two rows that
+should dedupe are firing twice, look here first.
 
 ### Two scheduling levers, and they answer different questions
 
@@ -358,9 +384,10 @@ are removed, and re-supplied ones are repositioned.
 ```typescript
 await api.workflows.create(tenantSlug, datalakeSlug, {
   name: 'Contact-Us Triage',
-  dataset_type: 'generic_table',
+  description: 'Triages inbound contact-us messages.',
+  dataset_type: 'generic_table' as const,
+  status: 'live' as const,
   tags: [],
-  // …other workflow fields…
   workflow_ai_agents: [
     {
       ai_agent_id: aiAgentId,                      // UUID from api.aiAgents.create
@@ -402,7 +429,7 @@ variable. Field paths match the columns of the workflow's
 `dataset_type`:
 
 ```
-   dataset_type: 'appointment'  → event_dataset.id, event_dataset.start, ...
+   dataset_type: 'legal_entity'  → event_dataset.id, event_dataset.name, ...
    dataset_type: 'generic_table' → event_dataset.<column_name> for each
                                    column on the bound table
 ```
@@ -534,7 +561,7 @@ for a time, or at `scheduled_at` if you did.
 const { data: run } = await api.workflows.run(
   tenantSlug, datalakeSlug, workflowSlug,
   {
-    sql_where_clause: `ra.id = '${appointmentId}'`,  // run against the regulated tables
+    sql_where_clause: `le.id = '${legalEntityId}'`,  // fragment against the dataset's alias
     mode: 'live',                                    // 'live' | 'dry_run'
     manual_override: false,                          // see below
     scheduled_at: '2026-08-12T09:00:00+01:00',       // OPTIONAL — see below
@@ -616,11 +643,17 @@ worker — both sides contend on one conditional update, so exactly one wins
 and the loser is told. Treat a refusal as a normal outcome to surface, not
 an error to retry.
 
-`sql_where_clause` accepts a fragment against the dataset's
-regulated tables (`ra` for appointments, `rp` for patients,
-etc. — same alias scheme as `data_activation_clients.md` §6.5).
-The id column is ambiguous across joins; always prefix
-(`ra.id`, `rp.id`).
+`sql_where_clause` accepts a fragment against the dataset's own
+tables. For a **platform dataset** the server assigns the alias
+(`le` legal entities, `m` messages, `al` action logs, `d` documents,
+`bo` beneficial owners — same scheme as `data_activation_clients.md`
+§6.5), and `id` is ambiguous across the base query's joins, so always
+prefix it: `le.id`.
+
+For a **generic-table** workflow there is no alias — the run selects
+on the table's own columns directly, as the cookbooks do
+(`customer_number IN (…)`). Prefixing one is an error, not a
+precaution.
 
 `manual_override: true` bypasses **dedupe/idempotency ONLY** —
 the same row may fire again even though its idempotency tuple
@@ -647,9 +680,9 @@ context build + AI enrichment**, and the action's own
 
 ```typescript
 const { data: result } = await api.workflows.execute(
-  tenantSlug, workflowSlug,
+  tenantSlug, datalakeSlug, workflowSlug,
   {
-    dataset_id: unregulatedAppointmentId,           // UNREGULATED id (not regulated)
+    dataset_id: appointmentRowId,                   // the row's id — see below
     decision_key: 'send_appointment_review_sms',
     mode: 'live',                                   // 'live' | 'dry_run' (same enum as .run)
     manual_override: true,                          // load-bearing on re-fires
@@ -666,11 +699,22 @@ const { data: result } = await api.workflows.execute(
 // result.scheduled_job_id             — background job id (null when count 0)
 ```
 
-Note that `dataset_id` is the **unregulated** id, not the
-regulated one. The unregulated tier is what the workflow
-runtime reads its action context from; passing the regulated
-id will fail to resolve. Issue a `dataAccessMode: 'unregulated'`
-search to obtain the right id.
+`dataset_id` is simply the row's id, and **there is only one.** An
+older version of this guide said to pass a tokenized-tier id and
+warned that the raw one would not resolve. That was true of a design
+with paired schemas and two rows per subject; GH-859 removed it.
+Today the derived lakes are replicated copies that preserve the primary
+key, so every lake reports the same id. And the lookup does not consult
+a mode at all: `validate_dataset_exists/4` passes `:raw` as a **literal**
+in both of its clauses — there is no branch, no mode argument threaded
+in, and no third clause. Every dataset type resolves against the raw
+lake.
+
+So an id from a tokenized or redacted search is already the id
+`.execute` wants. The re-search the old advice called for was not
+merely unnecessary; it was answering a question the code never asks.
+`primary-care` §029 reads one row through all three lakes on a single
+slug, which is the direct evidence that the key survives replication.
 
 `manual_override: true` on `.execute` sets the unique-key
 constraint to `false` on the per-row job, allowing re-fires
@@ -745,16 +789,14 @@ Each log carries:
 - `error_message` — coarse failure summary (e.g.
   `"AI enrichment failed: <agent_name>"`); rich detail lives
   in `error.json` (§ Per-step artifacts below)
-- `action_execution_logs` — nested rows, one per action that fired
-  (`message_body` virtual field is rendered when read via the
-  `dataAccessMode: 'regulated'` mode)
+- `action_execution_logs` — nested rows, one per action that fired,
+  carrying the `message_body` virtual field
 
 Methods:
 
 ```
 .list(tenantSlug, datalakeSlug, workflowSlug, query?)          Paged
-.get(tenantSlug, datalakeSlug, workflowSlug, logId,
-     { dataAccessMode? })                                      One row
+.get(tenantSlug, datalakeSlug, workflowSlug, logId)            One row
 .download(tenantSlug, datalakeSlug, workflowSlug, logId)       The run's artifact
 ```
 
@@ -774,17 +816,20 @@ await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, slug, {
 `filters` uses the Flop empty-bracket serialization on the wire —
 the SDK's serializer handles it; never hand-roll the query string.
 
-The `dataAccessMode` query parameter on `.get` controls how
-`message_body` is rendered:
-- `'regulated'` — raw rendered body (with the resolved short
-  path `/t/<token>`)
-- `'unregulated'` — tokenised display body
+`.get` takes NO `dataAccessMode`. It used to; the platform removed the
+`data_access_mode` query from this endpoint, and the generated type is now
+`query?: never`, so passing one no longer compiles.
+
+An execution log is workflow bookkeeping rather than lake rows, so there is
+no tier to select. Choosing a tier belongs to the reads that return data —
+`datasets.search` and `datalakes.executeSql` both take a mode, and that is
+where `'raw' | 'tokenized' | 'redacted'` still applies.
 
 ### Per-step artifacts (event, filter, enrichment, error)
 
-For each workflow execution, the platform writes JSON artifacts
-to the datalake's regulated cloud-storage bucket. The keys
-follow a fixed convention:
+For each workflow execution, the platform writes JSON artifacts to
+the datalake's cloud-storage bucket. The keys follow a fixed
+convention:
 
 ```
 workflows/<workflow_id>/executions/<execution_log_id>/<step>.json
@@ -798,7 +843,7 @@ Fetch them via the datalake's `createDownloadLink`:
 ```typescript
 const { data: link } = await api.datalakes.createDownloadLink(
   tenantSlug, datalakeSlug,
-  { bucket: regulatedBucket, key: 'workflows/.../filter.json' },
+  { bucket: datalakeBucket, key: 'workflows/.../filter.json' },
 )
 const artifact = await (await fetch(link.url)).json()
 ```
@@ -984,15 +1029,16 @@ row doesn't swallow it. When counting "what actually went out", filter
    (Nested `workflow_ai_agents` follow the same whole-array-replace
    rule — re-supply the full set on every `update()`; see §3.)
 
-3. **`sql_where_clause` ids require an alias prefix.** `id` is
-   ambiguous across the multi-JOIN base query; use
-   `<base_alias>.id` (`ra.id`, `rp.id`, `rc.id`, etc.).
+3. **`sql_where_clause` ids require an alias prefix — on a platform
+   dataset.** `id` is ambiguous across the multi-JOIN base query, so
+   use `<base_alias>.id` (`le.id`, `m.id`). A generic-table workflow
+   has no alias and takes bare column names.
 
-4. **`.execute` takes the UNREGULATED dataset id, `.run` takes
-   the REGULATED id.** This asymmetry traps consumers who
-   reuse the id they got from a regulated-mode search. Issue
-   a fresh search with `dataAccessMode: 'unregulated'` before
-   calling `.execute`.
+4. **`.execute` and `.run` take the same id.** They once did not, and
+   an older version of this guide described the asymmetry at length.
+   The paired schemas that caused it are gone: the derived lakes
+   preserve the primary key, so there is one id per row and no
+   re-search is needed before calling `.execute`.
 
 5. **`manual_override: true` on `.execute` is required for
    re-fires.** Without it, the per-row job dedupes against the

package/README.md

@@ -39,8 +39,8 @@ const api: PlatformApi = createIsolatedPlatformApi({
 // 3. call resources — every nested resource is tenant + datalake scoped
 const { data: datalake } = await api.datalakes.create(tenantSlug, {
   name: 'Production Lake',
-  data_domain: 'subscription',
-  // …database + storage credentials…
+  type: 'raw',
+  // …db_reader_* / db_writer_* + cloud_storage credentials…
 })
 
 const { data, meta } = await api.tools.list(tenantSlug, datalake.slug)

package/dist/bin/platform-sdk.mjs

@@ -28,53 +28,39 @@ function buildManagedBlock() {
 		"composing API calls for a scenario from primitives, start from the",
 		"closest recipe and diverge only with a stated reason.",
 		"",
-		"### Recipes by use case",
-		"",
-		"**Healthcare**",
-		"",
-		`- \`${corpus}/cookbook/appointment-review-sms-workflow.md\` — send a`,
-		"  patient review-request SMS after a fulfilled appointment,",
-		"  deep-linked to a connected-app feedback form.",
-		`- \`${corpus}/cookbook/contact-us-triage-with-llm.md\` — triage inbound`,
-		"  contact-us messages into three priority buckets (appointment /",
-		"  job-application / spam) via an LLM agent, route each to a tailored",
-		"  SMS action.",
-		"",
-		"**Subscription**",
-		"",
-		`- \`${corpus}/cookbook/welcome-sms-for-customers.md\` — send a welcome`,
-		"  SMS to newly contracted customers with a self-serve billing-portal",
-		"  link.",
-		`- \`${corpus}/cookbook/dunning-sms-for-delinquent.md\` — send a`,
-		"  payment-reminder SMS to delinquent customers (filtered on",
-		"  phone-on-file and tax-id-verified) with a pay-invoice link.",
-		`- \`${corpus}/cookbook/triage-prospects-by-priority.md\` — triage`,
-		"  inbound AR customers into priority bands (high / medium / low) via",
-		"  an LLM agent, route each band to a tailored SMS action.",
-		"",
-		"**Payments**",
-		"",
-		`- \`${corpus}/cookbook/kyc-notification-on-account-activation.md\` —`,
-		"  send a KYC-notification SMS when a payment account transitions to",
-		"  active status.",
-		`- \`${corpus}/cookbook/sanctions-screening-with-agent-review.md\` —`,
-		"  disambiguate gray-zone sanctions screenings via an LLM agent, route",
-		"  confirmed-clean and confirmed-block outcomes to distinct SMS",
-		"  actions.",
-		"",
-		"**Foundation**",
-		"",
-		`- \`${corpus}/cookbook/birthday-greeting-sms-trigger.md\` — send a`,
-		"  happy-birthday SMS on each contact's next birthday using a",
-		"  pure-Liquid trigger (year-roll math).",
-		`- \`${corpus}/cookbook/score-leads-with-llm-categorization.md\` — score`,
-		"  inbound leads into four bands (hot / warm / cold / spam) via an LLM",
-		"  agent, route each band to a tailored SMS action.",
-		`- \`${corpus}/cookbook/marketing-campaign-send.md\` — send an A/B`,
-		"  marketing campaign across SMS and email: the suppression and",
-		"  reachability gates and the A/B split all live in the workflow, each",
-		"  send carries a per-recipient short link, and the reply re-attaches",
-		"  to the customer who sent it.",
+		"### The four cookbooks",
+		"",
+		"One per use case. Each stands up its own tenant, datalake and",
+		"resources and shares nothing with the others — read one end to end",
+		"and you need no second file. Duplication between them is deliberate.",
+		"",
+		`- \`${corpus}/cookbook/organic-marketing.md\` — score inbound leads`,
+		"  into four bands with an LLM agent, schedule a birthday greeting a",
+		"  year out with a pure-Liquid trigger, and run an A/B campaign whose",
+		"  suppression gates and split live in the workflow. Ends with",
+		"  delivery reconciliation and a natural-language read of the lake.",
+		"  One raw datalake.",
+		`- \`${corpus}/cookbook/payments-compliance.md\` — disambiguate`,
+		"  gray-zone sanctions screenings with an LLM agent that never sees",
+		"  who was screened, and fire a KYC notification on account",
+		"  activation. Ends by reading one row through raw, tokenized and",
+		"  redacted to show what each reader gets. Three datalakes.",
+		`- \`${corpus}/cookbook/subscription-saas.md\` — one customers table`,
+		"  and three workflows over it: a welcome SMS gated on reachability,",
+		"  a dunning reminder gated on reachability AND KYC, and an LLM agent",
+		"  banding accounts by priority. Then the same table filled three",
+		"  more ways — inline, bulk CSV, REST fetch — and a teammate invited",
+		"  onto the tenant. One raw datalake.",
+		`- \`${corpus}/cookbook/primary-care.md\` — a review request that only`,
+		"  reaches patients whose visit actually happened, an LLM agent",
+		"  triaging inbound messages off the tokenized projection, and a",
+		"  vision agent reading a scanned document. Three datalakes.",
+		"",
+		"**Capabilities are inside the cookbooks, not beside them.** Bulk",
+		"upload, REST fetch, team invitations, action status updaters,",
+		"paginated pollers, text-to-SQL and agent file-invocation each live in",
+		"the cookbook whose use case motivates them, as numbered steps. There",
+		"is no separate per-capability file to consult.",
 		"",
 		"### Top-3 consumer gotchas",
 		"",