@alvera-ai/platform-sdk 0.16.3 → 0.17.0-next.g00fdd4c

package/.agent/AGENTS.md

@@ -231,17 +231,16 @@ What changes between them is only *where you put the calls* (a component
 handler vs. a test body), never the calls themselves. The cookbooks under
 `cookbook/` read as test-style sequences because that is how they are
 validated, but every step is a plain `api.*` call you can lift into an app
-unchanged. The per-capability docs (e.g. `bulk-ingest.md`, `ai-agent-invoke.md`)
-show one capability at a time; the cookbooks weave capabilities into a
-business outcome.
+unchanged. Capabilities are not documented separately — each lives as
+numbered steps inside the cookbook whose use case motivates it.
 
 ## Resources
 
 ```
    INFRASTRUCTURE  (stood up before data flows)
    ──────────────
-   datalakes.md                  Storage layer; regulated +
-                                  unregulated tiers.
+   datalakes.md                  Storage layer; the raw lake and
+                                  its tokenized + redacted copies.
    data_sources.md               External ingestion endpoints.
    tools.md                      Authenticated connections for
                                   action execution.
@@ -323,12 +322,13 @@ at runtime.
 
 Each cookbook structure:
 
-- **Front matter** — `title`, `summary`, `industry`, `slug`,
+- **Front matter** — `title`, `summary`, `use_case`, `slug`,
   `vitest_source` (list of integration-test files the snippets
-  are lifted from, anchor file first), `status`. The `industry:`
-  field also drives automatic discovery of the per-industry
-  bootstrap setup file at `_setup/<industry>.md` — see
-  "Industry-derived setup files" below.
+  are lifted from, anchor file first), `status`. `use_case` is one
+  of the four surfaces — `organic-marketing`,
+  `subscription-saas`, `payments-compliance`,
+  `primary-care-feedback` — and there is exactly one cookbook per
+  use case, at `cookbook/<use-case>.md`.
 - **Problem** — the business-outcome statement in domain terms,
   sourced from the anchor vitest's behaviour (not from
   customer-narrative documentation).
@@ -349,44 +349,33 @@ Each cookbook structure:
 - **See also** — links to relevant per-resource reference MDs
   and to the anchor + ancillary vitest files.
 
-### Industry-derived setup files
-
-Cookbook authoring uses per-industry bootstrap setup files
-under `.agent/cookbook/_setup/<industry>.md` to DRY out the
-auth + tenant + datalake + dataset-seeding steps every
-scenario in an industry shares. The convention matches the
-markdown-doctest ecosystem pattern — setup belongs to a
-scope (the industry), and any cookbook in that scope
-inherits the setup by being there. No per-cookbook opt-in
-field is required.
-
-- Setup files live under `_setup/`. The leading underscore on
-  the directory marks them as fragments (not standalone
-  scenarios); the validator's discovery walk skips them and
-  the corpus index does not list them under "Available
-  cookbooks."
-- The validator reads each scenario cookbook's existing
-  `industry:` front-matter field and auto-discovers the
-  setup file at `_setup/<industry>.md`. A cookbook in an
-  industry that has no setup file gets nothing inlined; the
-  validator does not fail if the setup file is absent.
-  Cookbook authors write no additional front-matter for
-  setup inclusion — the relationship is implicit, by
-  convention.
-- The validator inlines the setup file's numbered `it()`
-  blocks BEFORE the scenario's own numbered `it()` blocks
-  inside the same `describe(...)`. Each `it()` label is
-  prefixed with its source slug so failure output
-  unambiguously points at the file to open (e.g.
-  `_setup/foundation §001 — auth` versus
-  `birthday-greeting-sms-trigger §001 — create workflow`).
-  Cookbook authors keep clean local §001-§00N numbering
-  inside their own markdown.
-- An agent reading a scenario cookbook discovers the matching
-  setup file at the predictable conventional path
-  `_setup/<industry>.md` — one extra file open at a
-  fixed-by-convention location, not via cookbook-specific
-  metadata the agent has to learn.
+### Every cookbook is self-reliant, and repeats what it needs
+
+A cookbook stands up **its own** tenant, datalake and resources in
+its own numbered steps. There is no shared setup file, no setup
+group and no bootstrap phase: everything the walk depends on is
+in the walk.
+
+That means the auth + tenant + datalake preamble is **duplicated
+across all four cookbooks, deliberately.** This corpus is read by
+someone — or something — that opens one file and works through it,
+and for that reader a shared setup is not a saving. It is a second
+file to find, a second convention to learn, and a hidden dependency
+on steps they never see. Four documents repeating a preamble is the
+cheaper trade, and it is the trade this corpus makes. Do not
+re-factor it out.
+
+Two consequences worth stating plainly:
+
+- **Write for idempotence, not just for a clean run.** Use stable
+  names and create-or-reuse: look the resource up, create it only
+  if it is absent, and assert the end state either way. A step that
+  mints a fresh random name works once and litters forever —
+  nothing in the product reclaims an abandoned datalake. Ask of
+  every creating step: what does this do on run two?
+- **Label numbering is local and clean.** Each cookbook numbers its
+  own steps `§001…§00N` from the top, and a failure names the file
+  and the step directly.
 
 ### Vendored fixtures (Liquid templates, CSV bodies)
 
@@ -417,7 +406,7 @@ repo's own integration tests use.
   const LE_TEMPLATE = fs.readFileSync(
     path.join(
       process.env.COOKBOOK_FIXTURES_DIR!,
-      'foundation/_lead_submissions_foundation_legal_entity.liquid',
+      'organic-marketing/_lead_submissions_foundation_legal_entity.liquid',
     ),
     'utf8',
   )
@@ -439,109 +428,58 @@ repo's own integration tests use.
   template plus the cookbooks that depend on it. No need to
   read cookbook code first to know what fixtures exist.
 
-### Two kinds of doc here: business cookbooks vs. capability docs
+### The four cookbooks
 
-The `cookbook/` directory holds two kinds of recipe, both validated by
-`make validate-cookbook`:
+`cookbook/` holds **four files, one per use case**, and nothing else that
+runs. Each is self-reliant: it stands up its own tenant, datalake and
+resources in its own numbered steps and shares nothing with its siblings.
+A reader reads one file end to end and needs no second one. The
+duplicated bootstrap across them is deliberate — four repeated preambles
+are cheaper than one shared setup every reader must go and understand
+first.
 
-- **Business cookbooks** (`<use-case>.md`) — one real business outcome each,
-  told as a numbered API-call sequence (e.g. `welcome-sms-for-customers`,
-  `dunning-sms-for-delinquent`). Read these to see how resources compose into
-  an outcome.
-- **Capability docs** (`<capability>.md`) — one platform capability each,
-  shown as the minimal call sequence that proves it (e.g. `bulk-ingest`,
-  `ai-agent-invoke`, `generic-tables`, `invite-team`). Read these to learn one
-  capability in isolation; cookbooks weave them into outcomes.
+There is no separate per-capability file. Bulk upload, REST fetch, team
+invitations, action status updaters, paginated pollers, text-to-SQL and
+agent file-invocation each live as numbered steps inside the cookbook
+whose use case motivates them, because a capability shown without a
+reason to use it is the thing readers skip.
 
-### Available cookbooks
-
-The ten business-cookbook scenarios. Each is anchored to a green
-end-to-end vitest scenario in the platform's integration-tests suite and is
-verified at dev time by `make validate-cookbook` at the platform-sdk repo root.
-This index is mirrored into the managed block `alvera llm-export` writes to
-consumer `AGENTS.md` files (`buildManagedBlock` in both the SDK and CLI
-packages — kept in sync by hand; the llm-export test suites pin the shipped
-copy, so a dropped entry breaks a test).
+All four are verified at dev time by `make validate-cookbook` at the
+repo root; every numbered step is one test.
 
 <!-- BEGIN:cookbook-index -->
 
-**Healthcare**
-
-- [appointment-review-sms-workflow](./cookbook/appointment-review-sms-workflow.md)
-  — Send a patient review-request SMS after a fulfilled
-  appointment, deep-linked to a connected-app feedback form.
-- [contact-us-triage-with-llm](./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**
-
-- [welcome-sms-for-customers](./cookbook/welcome-sms-for-customers.md)
-  — Send a welcome SMS to newly contracted customers with a
-  self-serve billing-portal link.
-- [dunning-sms-for-delinquent](./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.
-- [triage-prospects-by-priority](./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**
-
-- [kyc-notification-on-account-activation](./cookbook/kyc-notification-on-account-activation.md)
-  — Send a KYC-notification SMS when a payment account
-  transitions to active status.
-- [sanctions-screening-with-agent-review](./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**
-
-- [birthday-greeting-sms-trigger](./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).
-- [score-leads-with-llm-categorization](./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.
-- [marketing-campaign-send](./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.
+- [organic-marketing](./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.
+- [payments-compliance](./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.
+- [subscription-saas](./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.
+- [primary-care](./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.
 
 <!-- END:cookbook-index -->
 
-### Capability docs
-
-One platform capability each — the minimal call sequence that proves it,
-anchored to a green vitest scenario. Read the matching reference MD for the
-full wire shape.
-
-- [bulk-ingest](./cookbook/bulk-ingest.md) — load a whole file of records in
-  one upload (presigned link → PUT → `ingestFile` → search by batch).
-- [rest-fetch](./cookbook/rest-fetch.md) — pull records from a third-party REST
-  API on demand (Bearer + OAuth2), no file upload.
-- [ai-agent-invoke](./cookbook/ai-agent-invoke.md) — read an uploaded
-  document/image and pull structured JSON out of it (`aiAgents.invoke` with
-  files). The correct file-vision path — the agent reads the file; the DAC
-  ingests it.
-- [generic-tables](./cookbook/generic-tables.md) — stand up a generic table the
-  built-in datasets don't model; deploy → ingest → read back via executeSql.
-- [action-status-updaters](./cookbook/action-status-updaters.md) — reconcile
-  the delivery status of messages you send, on a schedule.
-- [system-templates](./cookbook/system-templates.md) — discover the platform's
-  built-in row-mapping Liquid templates.
-- [invite-team](./cookbook/invite-team.md) — invite a teammate into your tenant
-  (root / tenantless / tenant-scoped sessions in one flow).
-- [talk-to-data](./cookbook/talk-to-data.md) — turn a datalake conversational:
-  natural language → reviewable SQL (`datalakes.textToSql`, data-free by
-  construction) → read-only execution returning a `{ data, meta }` row page or a
-  CSV export (`datalakes.executeSql`).
+This index is mirrored into the managed block `alvera llm-export` writes
+to consumer `AGENTS.md` files — `buildManagedBlock`, duplicated in both
+the SDK and CLI packages and kept in sync by hand. **Both suites now
+assert every cookbook named in the block exists on disk, and that every
+cookbook on disk is named.** They previously pinned names against the
+block string alone, which is how the index went on advertising four
+deleted files without a single test failing.
 
 ## Utility namespaces
 
@@ -576,6 +514,13 @@ of restating:
 | Async + readiness                             | `async.md`       |
 | Debugging (HTTP interceptor + safe redaction) | `debugging.md`   |
 | Type naming + server-derived fields           | `type_naming.md` |
+| Local mock surfaces (WireMock / LocalStack)   | `mock-services.md` |
+
+`mock-services.md` answers the local-development questions the other
+pages assume away: how the platform reaches mocked third-party APIs on
+a laptop, the `endpoint_url` override on the sender tools, and why End
+User Messaging points at WireMock rather than LocalStack. It is fetched
+from the platform-metadata channel, not authored here.
 
 ## Just getting started?
 

package/.agent/account_management.md

@@ -86,7 +86,7 @@ platform-admin side door (a root Bearer):
 ```typescript
 const { data: minted } = await rootApi.admin.createTenantApiKey(tenantSlug, {
   name: 'Bootstrap Key',
-  data_access_mode: 'unregulated',
+  data_access_mode: 'raw',
 })
 // minted.api_key — the publishable key value (thread into createSession)
 ```
@@ -329,7 +329,7 @@ What you SUBMIT when creating an invitation. The
 | Invitation `role` | Result on accept                       |
 |-------------------|----------------------------------------|
 | `'member'`        | Standard tenant user                   |
-| `'researcher'`    | Tokenized-only access; blocked from regulated schema |
+| `'researcher'`    | Ceiling of `tokenized`; cannot read the raw lake |
 | `'admin'`         | Full tenant management                 |
 
 ```typescript

package/.agent/action_logs.md

@@ -39,7 +39,7 @@ batch_id            — the run this outcome belongs to; THE
 decision_key        — which action fired
 context_key         — companion string key; like decision_key, it is
                       SQL-lane only (neither is Flop-filterable, §5)
-mdm_subject_id, subject_name, session_id
+legal_entity_id, subject_name, session_id
 action_type ('sms'|'email'|'voice'|'data_exchange'), channel,
 classification
 status              — see §3
@@ -92,17 +92,17 @@ message.
 // dataset type is SINGULAR 'action_log' (the table is plural)
 const { data: search } = await api.datasets.createUserSearch(
   tenantSlug, datalakeSlug, 'action_log',
-  { search_query: `ral.batch_id = '${batchId}'` },
+  { search_query: `al.batch_id = '${batchId}'` },
 )
 const { data: page } = await api.datasets.search(
   tenantSlug, datalakeSlug, 'action_log',
-  { userSearchId: search.id, dataAccessMode: 'unregulated' },
+  { userSearchId: search.id, dataAccessMode: 'tokenized' },
 )
 ```
 
 Filterable columns (Flop, the full set): `id`, `inserted_at`,
 `action_type`, `channel`, `status`, `batch_id`, `classification`,
-`workflow_id`, `sent_at`, `external_id`, `mdm_subject_id`. Note
+`workflow_id`, `sent_at`, `external_id`, `legal_entity_id`. Note
 there is **no `global_search`** here (unlike the message dataset) —
 `decision_key`/`context_key` are not in this set either; scope them
 via the `search_query` SQL fragment above.

package/.agent/ai_agents.md

@@ -31,7 +31,7 @@ const { data: created } = await api.aiAgents.create(
     tool_id: chatCompletionToolId,                  // see §2 — must be a tool with intent: 'llm_enrichment'
 
     model: 'qwen3-vl:8b-instruct',                   // provider-specific model identifier
-    data_access: 'unregulated',                      // 'unregulated' | 'regulated' (compliance gate)
+    data_access: 'tokenized',                        // 'raw' | 'tokenized' (compliance gate)
     temperature: 0.0,
     max_tokens: 2048,
     enabled: true,
@@ -125,25 +125,30 @@ referenced by the prompt body resolves to a property declared in
 ### `data_access` is the compliance gate
 
 ```
-data_access: 'unregulated'   — the LLM call receives tokenized,
-                                redacted data; safe for any LLM
-                                (third-party, on-prem, …).
-                                Default for triage / categorization
-                                / lead-scoring workflows.
-data_access: 'regulated'     — the LLM call receives raw values;
-                                MUST be paired with an LLM the
-                                operator trusts with this tier
-                                (typically an on-prem deployment).
-                                Use for compliance workflows that
-                                need raw values — sanctions
-                                screening, manual review, KYC.
+data_access: 'tokenized'  — the LLM call reads the tokenized lake:
+                             each masked column arrives as a stable
+                             tok_<hash>. Safe for any LLM, including
+                             third-party. The right choice for triage,
+                             categorization and lead scoring, where the
+                             model reads free text and has no business
+                             knowing whose it is.
+data_access: 'raw'        — the LLM call receives real values. MUST be
+                             paired with an LLM the operator trusts
+                             with them (typically on-prem). For work
+                             that genuinely needs the value — sanctions
+                             screening, manual review, KYC — and for
+                             prompts that carry no identity at all, so
+                             there is nothing to hold back.
+
+An agent is never pointed at the redacted lake: its placeholders are
+unjoinable by design, which makes them useless to a model.
 ```
 
 **The platform does NOT enforce `data_access` as immutable — a PUT
 `update()` can change it today.** The field is cast by the same
 changeset that `update()` uses and carries no immutability guard (and
-isn't `readOnly` on the wire), so an update can flip `regulated ↔
-unregulated`, which changes whether the agent sees raw or tokenized
+isn't `readOnly` on the wire), so an update can flip `raw ↔
+tokenized`, which changes whether the agent sees real or masked
 values. **Treat it as immutable by discipline** — a data source
 built expecting one tier shouldn't be silently re-tiered under it —
 but know the platform won't stop a flip, so guard it in your own
@@ -209,9 +214,10 @@ const { data: workflow } = 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: createdAgentId,
@@ -305,7 +311,7 @@ name                  required string
 description           optional string
 tool_id               required UUID  — must be intent: llm_enrichment
 model                 required string — provider-specific identifier
-data_access           required enum  — 'unregulated' | 'regulated'
+data_access           required enum  — 'raw' | 'tokenized' (no default)
 temperature           required number
 max_tokens            required number
 enabled               required bool
@@ -417,8 +423,9 @@ usage        object  — { model, input_tokens, output_tokens, total_tokens,
 
 Invoke passes NO `context_mapping_config` — `input` is validated
 directly against `input_schema` (unlike the nested workflow path,
-which remaps host context first). See the `ai-agent-invoke`
-cookbook for the full upload → tool → agent → invoke walk.
+which remaps host context first). See `cookbook/primary-care.md`
+§025–028 for the full upload → tool → agent → invoke walk, including
+the input-gate refusal.
 
 ### Drift checksum
 
@@ -544,7 +551,7 @@ with `{ status: 'skipped' }` and no per-agent entries.
 6. **`data_access` is immutable by convention only — the platform
    won't stop a PUT from flipping it.** There's no immutability
    guard in the changeset, so an `update()` can change the
-   compliance tier (`regulated ↔ unregulated`) and re-tier what the
+   compliance tier (`raw ↔ tokenized`) and re-tier what the
    agent sees. Enforce it in your own change-control (or delete +
    recreate); don't rely on the platform to reject the flip (§2).
 

package/.agent/ai_sandbox.md

@@ -17,16 +17,16 @@ the worst case — and they compose into defense-in-depth.
 
 ## Layer 1 — Compliance gates (who sees what)
 
-Two consumer-set fields decide whether a request reaches raw
-PHI/PII/PCI or only the tokenized projection. Both must
-authorize regulated reach for raw data to flow:
+Two consumer-set fields decide whether a request reaches the raw
+lake or only the tokenized projection. Both must authorize raw reach
+for real values to flow:
 
 ```
    session role           AI agent data_access     →  outcome
    ──────────────         ───────────────────         ───────
-   member or admin        regulated                   regulated reachable
-   member or admin        unregulated                 tokenized only
-   member or admin        (no agent on path)          regulated reachable
+   member or admin        raw                         raw reachable
+   member or admin        tokenized                   tokenized only
+   member or admin        (no agent on path)          raw reachable
    researcher             any value                   tokenized only
 ```
 
@@ -34,21 +34,28 @@ authorize regulated reach for raw data to flow:
   time (vocabulary A — `'member' | 'researcher' | 'admin'`; the
   resulting session carries the corresponding role-record name
   — see `account_management.md` §3).
-- **AI agent `data_access`** is `'regulated' | 'unregulated'`,
-  pinned at agent creation (immutable post-create — see
-  `ai_agents.md`). Default is `'unregulated'`; `'regulated'` is
-  opt-in.
-
-A `researcher` session can never reach raw PHI regardless of how
-the agent is configured. An `'unregulated'` agent can never
-reach raw PHI regardless of session role. Tenant isolation
-(every row carries a tenant id; queries filter on the session's
-tenant) AND-composes with both of these so a request only sees
-the slice that *all three* allow.
-
-The composition rule is fail-safe: a workflow spec that omits
-`data_access` is treated as `'unregulated'`. Author-side
-mistakes default to less reach, never more.
+- **AI agent `data_access`** is `'raw' | 'tokenized'`, set at agent
+  creation. **The platform does not enforce it as immutable** — one
+  `changeset/2` serves create and update, and nothing refuses a PUT
+  that flips the tier, so treat it as immutable by your own
+  change-control rather than by the platform's (see `ai_agents.md`
+  §2). An
+  agent is **never pointed at the redacted lake**: that copy is for a
+  person to glance at, and its values are unjoinable by design.
+
+  **There is no default — the field is required.** Omitting it is a
+  422 at create, not a quiet fall-back to the safer tier. That is a
+  deliberate change from an older design that defaulted to the
+  tokenized side: a default meant an author could get a compliance
+  tier without ever deciding on one, and the reviewer reading the
+  spec could not tell an intentional choice from an omission. Being
+  made to say it is the point.
+
+A `researcher` session can never reach real values regardless of how
+the agent is configured. A `'tokenized'` agent can never reach them
+regardless of session role. Tenant isolation (every row carries a
+tenant id; queries filter on the session's tenant) AND-composes with
+both, so a request only sees the slice that *all three* allow.
 
 ## Layer 2 — Liquid sandbox (what can execute)
 
@@ -156,10 +163,9 @@ fragments. Either path lands at the same boundary.
 
 ### What SQL fragments CAN do
 
-- SELECT against the regulated tables exposed by the dataset
-  search aliases (`rp` for `regulated_patients`, `rc` for
-  `regulated_customers`, etc. — see `data_activation_clients.md`
-  §6.5 SQL aliases).
+- SELECT against the tables exposed by the dataset search aliases
+  (`le` for legal entities, `m` for messages, `al` for action logs
+  — see `data_activation_clients.md` §6.5 SQL aliases).
 - Filter results into the platform's `search_results`
   accumulator scoped to the materialised search id. This is the
   one write the query path performs, and the platform builds it
@@ -199,15 +205,15 @@ it sits inside the same Layer-3 boundary:
   only the natural-language `prompt` plus the datalake **schema**
   to the LLM — never rows. The model returns SQL for review; no
   datalake data ever crosses the LLM boundary, so generation is
-  safe in both `regulated` and `unregulated` mode. The two-call
+  safe in every mode. The two-call
   split (generate, then execute) exists so a human or agent can
   inspect and edit the SQL before any data is read.
 - **Execution is read-only and mode-routed.** `executeSql` runs the
   statement against the mode-appropriate schema with a read-only
   connection: INSERT/UPDATE/DELETE/DDL are rejected (app-layer
   `@deny` + a read-only DB transaction + an EXPLAIN preflight), and
-  `mode` (`regulated` vs `unregulated`) plus the session's tenant
-  (RLS) decide which schema and which rows are reachable — the same
+  `mode` (`raw`, `tokenized` or `redacted`) plus the session's tenant
+  (RLS) decide which lake and which rows are reachable — the same
   Layer-1 compliance gates that govern every other read.
 - **Pagination caps blast radius.** `page` / `page_size` map to a
   server-side `LIMIT/OFFSET` window capped at the platform default,
@@ -220,9 +226,9 @@ it sits inside the same Layer-3 boundary:
    │  Layer 1 — compliance gates                 │
    │    session role  AND  agent data_access     │
    │    AND  tenant id (RLS)                     │
-   │  Decides: which schema (regulated vs        │
-   │  unregulated) and which tenant the query    │
-   │  hits.                                      │
+   │  Decides: which lake (raw / tokenized /     │
+   │  redacted) and which tenant the query hits. │
+   │                                             │
    └────────────────────┬────────────────────────┘
                         │
    ┌────────────────────▼────────────────────────┐
@@ -248,9 +254,9 @@ it sits inside the same Layer-3 boundary:
 
 Each layer is independently sufficient: bypassing any single
 layer still leaves the other two enforcing the contract. The
-compound rule is "all three must permit" — read PHI requires
-authorising session role AND regulated-mode agent (when an
-agent is on the path) AND tenant id match.
+compound rule is "all three must permit" — reading real values
+requires an authorising session role AND a `raw` agent (when an
+agent is on the path) AND a tenant id match.
 
 ## Auditability
 
@@ -259,15 +265,19 @@ recorded with cloud-storage pointers to the exact input payload
 the agent received and the exact response the provider
 returned. The audit record outlives the host run that produced
 it — a compliance auditor can later replay any agent's input
-and verify what data class (regulated vs tokenized) actually
-reached the model. The audit surface is admin-facing today; the
+and verify which lake (raw vs tokenized) actually fed the model. The audit surface is admin-facing today; the
 guarantees it captures back-stop Layer 1.
 
 ## Consumer takeaways
 
-1. **Default to `'unregulated'` agent `data_access`.** Opt into
-   `'regulated'` only when the action genuinely needs raw
-   values, and pair with a session role that's authorised.
+1. **Reach for `'tokenized'` agent `data_access` first.** The field
+   is required, so this is a decision you must make rather than
+   inherit; choose `'raw'` only when the prompt genuinely needs real
+   values, and pair it with a session role that is authorised. The
+   tier should follow what the prompt can actually reach — an agent
+   whose prompt carries only an account number and a type has no
+   identity to protect, and one reading free-text patient messages
+   has plenty.
 
 2. **Use only the 13 custom filters** named in Layer 2. Bodies
    that reference other filter names will silently fall through

package/.agent/connected_apps.md

@@ -398,14 +398,14 @@ resolves the page:
 
 ```typescript
 const { data: page } = await api.connectedApps.resolvePage(
-  tenantSlug, slug,                                 // tenant + connected-app slug
+  tenantSlug, datalakeSlug, slug,                   // tenant + datalake + app slug
   {
     short_path: '<the-short-path-from-the-URL>',
     user_agent: req.headers.get('user-agent') ?? '',
   },
 )
 // page.message            — the rendered message row
-// page.message.body       — the regulated rendered body (raw)
+// page.message.body       — the rendered body, real values (raw lake)
 // page.route_path         — the route the link was minted against
 //                            (e.g. '/forms/review')
 // page.metadata           — parsed `connected_app_metadata_template`
@@ -418,7 +418,7 @@ the customer opens or submits the form:
 
 ```typescript
 await api.connectedApps.updateMessageTracking(
-  tenantSlug, slug,
+  tenantSlug, datalakeSlug, slug,
   {
     short_path: '<same-short-path>',
     opened_at: new Date().toISOString(),

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

@@ -27,7 +27,7 @@ import path from 'node:path'
 const LE_TEMPLATE = fs.readFileSync(
   path.join(
     process.env.COOKBOOK_FIXTURES_DIR!,
-    'foundation/_lead_submissions_foundation_legal_entity.liquid',
+    'organic-marketing/_lead_submissions_foundation_legal_entity.liquid',
   ),
   'utf8',
 )