toga-ai 1.0.247 → 1.0.249

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
+updated: 2026-06-30
 owners: ["jcardinal", "bala", "mhammontree"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
@@ -14,6 +14,7 @@ files:
   - _underscore/Email.php
 related:
   - ../../worker2/features/notification-email.md
+  - ../../worker2/features/notification-email-template.md
 ---
 
 ## Summary
@@ -100,9 +101,40 @@ can keep using `sendEmail($api, ...)`.
   Any fire-and-forget caller now propagates that exception, which is intended (so an email is
   never silently marked as sent). Blast radius is every client, including the Compass/Quad
   `SalesOrder`/`ApprovalDecision` order-placed emails.
+- **`_Email::send()` does not set PHPMailer `CharSet=UTF-8`.** Non-ASCII subjects/body (em
+  dash, curly quotes, accented names) **mojibake** (e.g. `—` → `—`). Scoped workaround:
+  use ASCII-only content. Recommended **root-cause fix**: set `$mailer->CharSet = 'UTF-8'` in
+  `_Email::send()` — but that affects **every** client, so it should be a separate, tested
+  change rather than a drive-by edit.
+- **`clientIdentifier` does NOT pick the template DB.** `_Email::send()` uses
+  `clientIdentifier` only for CloudWatch logging/validation. The template loads from whatever
+  DB the `DB_CLIENT` alias points at — so register the right `Client_<x>` schema before
+  calling `send()`, or you'll load (or fail to find) the wrong tenant's template.
+
+## Local test harness (2.0 worker2 / _underscore)
+
+To exercise `send()` locally without enqueuing onto SQS:
+
+1. `putenv('ENVIRONMENT=dev-<machine>')` — the framework reads `getenv('ENVIRONMENT')` and
+   `_Environment::initialize` throws if it's unset.
+2. Add `C:\WWW\_underscore` to `include_path`; `chdir` to the app root (`worker2`) so
+   `./Config` and `./_.php` resolve.
+3. `require vendor/autoload.php` **then** `_underscore/_underscore.php`.
+4. `_Database::register('Client_Rate','localhost','root','',null,null,_underscore::DB_CLIENT)`.
+5. `_Model_Client_EmailTemplate::send('Rate', $uuid, $to, [], [], ...$vars)`.
+
+Dev config has `debug_mode=1` + `send_debug_emails_to`, so `_Email::send()` routes **all**
+mail to that address. **CAVEAT:** do **not** test via `_Worker::runTask` locally — the dev
+`[cloud] aws_worker_queue_url` points at the **production** SQS queue. Call `send()` (or the
+worker method) in-process instead.
 
 ## Change history
 
+- 2026-06-30 — Documented the **`CharSet=UTF-8` mojibake gotcha** (`_Email::send()` doesn't
+  set it → non-ASCII content garbles; scoped workaround = ASCII-only, root-cause = set
+  `$mailer->CharSet` as a separate tested change), clarified that `clientIdentifier` does not
+  select the template DB (`DB_CLIENT` does), and added the **local in-process test harness**.
+  Surfaced building the Rate service-purchase emails (TRUE-79251). (mhammontree)
 - 2026-06-24 — Added the **branded-wrapper** path: `WRAPPER_UUID` + `renderWrappedBody()` load a
   reserved per-client `EmailTemplates` row and inject `{subject}`/`{body}`. Consumed by the new
   worker2 `_Worker_Notification_Email::Send` for internal/notification mail; the wrapper row is

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -8,5 +8,5 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-06-30
-owners: [jcardinal]
+owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
@@ -15,6 +15,7 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/surface/actionRegistry.ts
+  - toga25-supply/src/surface/componentRegistry.tsx
   - toga25-supply/src/surface/SurfaceActionBar.tsx
   - toga25-supply/src/surface/SurfaceSection.tsx
   - toga25-supply/src/surface/resolve.ts
@@ -50,16 +51,35 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   meta. Loading a different *record* into the same surface reuses cached meta. Builds the URL as
   `/surfaces/meta?slug=...` (query string), **not** `/surfaces/<slug>/meta` (the path form makes the
   engine parse the slug as a record uuid → 404 EV-6). Unwraps the bundle via **`extractBundle()`**,
-  which locates the bundle by its **structural fingerprint** (the `elements` array) across
-  `raw` / `raw.data` / `raw.data.<route-key>` — because V2 nests a scripted-API return value one
-  level deeper, under a route-keyed slot of `data` (e.g. `data.meta`, `data.surfaces`). On a malformed
-  payload it falls back to an empty-elements bundle so the page never crashes.
+  which uses a recursive **`findBundle(raw, predicate, depth=4)`** to walk the envelope (replacing the
+  old hard-coded `raw`/`raw.data`/`raw.data.<key>` probing) and locates the bundle by its
+  **structural fingerprint**: `looksLikeBundle` now requires **both** an `elements` array **and** a
+  `surface` descriptor object (not the `elements` array alone — see the decoy gotcha below).
+  `extractBundle(raw, slug)` then **prefers** the bundle whose `surface.slug === slug`, falling back to
+  first-found, so a stray sibling bundle can't win. `looksLikeGroup` requires the documented `group`
+  discriminator key so a single-bundle envelope is not mistaken for a group. On a malformed payload it
+  falls back to a safe empty bundle (empty `elements` + empty `messages`/`theme`/`vocabularies` maps)
+  so the page never crashes.
 - **`useFetchSurfaceMetaGroup(slugs[])`** — the grouped sibling of `useFetchSurfaceMeta`, for a screen
   needing many section surfaces at once. **Order-insensitive** (the slug list is normalized so cache
   hits don't depend on argument order), `staleTime: Infinity`, hits the grouped endpoint
   `GET /v2/surfaces/meta-group?slugs=...`, and extracts the `{surfaces}` map via `extractGroup()` /
   `looksLikeGroup()` (the same structural-fingerprint approach as `extractBundle`). Returns `{}` for
   unmigrated screens (`enabled:false`), so a non-roster client does no fetch.
+- **`componentRegistry`** (`src/surface/componentRegistry.tsx`) — the **presentation sibling** of
+  `actionRegistry`, both keyed by the surface meta's `action.key`. `actionRegistry` maps key→behavior
+  handler; `componentRegistry` maps key→custom React component. `SurfaceActionBar.renderElement` calls
+  `getSurfaceComponent(element.action?.key)` and renders the registered component (in a keyed Fragment)
+  **before** falling through to the default icon button — so `action.key` drives **both** which
+  component renders and its behavior, while `messages.label` supplies its text and clicks route through
+  the same `handle`→dispatch path. First entry: `"salesOrder.viewLog"` → `<ViewLogButton>`. Extending
+  is one surface element in meta + one registry entry (same model as `actionRegistry` and the Pattern-3
+  cell registry).
+- **element `config` vs `action.payload`.** Per-element `config` (`Record<string,unknown>|null`) is the
+  opaque element-level seed bag (the SurfaceElements JSON long-tail). At runtime the **backend resolver
+  merges the Action's own config with the element `config` to produce `action.payload`**, which is what
+  the FE consumes — the FE renderer never reads `element.config` directly. A separate surface-level
+  `surface.config` lives on the descriptor (e.g. Inventory's `groupByLabels`/`entityTags`).
 - **`evaluateSurfaceRule`** — the Tier-1 rule evaluator: a **frozen `all/any/none` + `{field,op,value}`
   grammar** that **throws on an unknown op** (generalized from the SalesOrders
   `buildPatchedTenantFields`/`evaluateEnableRule`/`resolveFlag` helpers). Evaluated client-side against
@@ -155,6 +175,25 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
 
 ## Gotchas
 
+- **The single-meta envelope can hide the real bundle behind a DECOY `elements: []`.** The V2 envelope
+  can arrive as `{ surfaces: { meta: <real-bundle> }, elements: [] }` — a decoy empty `elements: []`
+  sits at the top level with **no `surface` descriptor**. A `looksLikeBundle` check matching on
+  `Array.isArray(value.elements)` alone short-circuits on the decoy and never finds the real nested
+  bundle → the action bar renders nothing. Fix: `looksLikeBundle` must require **both** `elements` AND
+  a `surface` descriptor; use recursive `findBundle` + slug-preferring `extractBundle` (see How it
+  works). The durable backend follow-up is to confirm/stabilize the single-meta envelope contract.
+- **The surface `record` shape must match the rule field namespace — wrap as `{ order }`.** Seeded
+  Tier-1 rules namespace their field as `order._status`, so `getByPath(record, "order._status")` only
+  resolves if the host passes `record={{ order }}`. Passing the bare order object resolves to
+  `order.order._status` = undefined → every `in`/`eq` op is false → buttons hidden. The fix is at the
+  **host** (`SalesOrderTopBar.tsx`: `record={order ? { order } : null}`), **not** in
+  `evaluateSurfaceRule.ts` (the evaluator was correct).
+- **`tokens.icon` is a LITERAL FontAwesome icon name, not a theme-token slug.** Only `tokens.color` and
+  `tokens.bg` are theme slugs resolved via `resolveThemeToken(theme, ...)` (the `theme` map only holds
+  `color.status.*`/`bg.status.*` keys). `tokens.icon` is a direct name (e.g. `check`, `xmark`,
+  `clipboardListCheck`, `penToSquare`) and must be used as-is (`element.tokens?.icon ?? "check"`).
+  Running it through `resolveThemeToken` misses on every icon and silently falls back to `"check"` for
+  every button.
 - **Scripted-API GET return values land under `data.<scriptRoute>`, not `data` directly.** V2 nests a
   scripted-API return value inside the envelope under a route-keyed slot of `data` (e.g. `data.meta`,
   `data.surfaces`), one level deeper than a normal data fetch. The bundle hook unwraps this with
@@ -179,6 +218,17 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   don't inherit Compass's shared base. Deleted the migrated section blocks from COMPASS/COMPASSCANADA/
   QUAD `orderViewFields.json` (data-wiring kept; DEFAULT intact). Action-bar/approval-modal still
   JSON. (jcardinal)
+- 2026-06-30 — Debugged + extended the client-side action-bar renderer (no client-specific work).
+  Fixed three rendering bugs: (1) the single-meta envelope's **decoy `elements: []`** masked the real
+  nested bundle — `looksLikeBundle` now requires `elements` AND a `surface` descriptor, with recursive
+  `findBundle(depth=4)` + slug-preferring `extractBundle` + `group`-discriminator `looksLikeGroup` +
+  safe empty `messages`/`theme`/`vocabularies` fallback (`useFetchSurfaceMeta.ts`); (2) Tier-1 rules
+  always false because the host passed the bare order object instead of the `{ order }` envelope the
+  `order.*` field namespace requires (`SalesOrderTopBar.tsx`); (3) every action icon rendered as
+  `check` because `tokens.icon` (a literal FA name) was wrongly run through `resolveThemeToken`
+  (`SurfaceActionBar.tsx`). Built `componentRegistry.tsx` — the presentation sibling of
+  `actionRegistry`, key→custom component (`salesOrder.viewLog` → `ViewLogButton`). Clarified element
+  `config` vs backend-merged `action.payload`. (apeterson)
 - 2026-06-29 — Migrated VendorItems (screen 2, recipe-exact) and Inventory (screen 3,
   **presentation-only by decision** — fetch topology stays JSON; only title/buttons/modal copy/entity
   tags moved). Fixed the "s.elements is not iterable" crash: `extractBundle()` now finds the bundle by

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -16,6 +16,7 @@
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
+| [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
+updated: 2026-06-30
 owners: [jcardinal, dfranks, mhammontree]
 files:
   - worker2/Worker/
@@ -159,10 +159,21 @@ be reattempted.
 - Class must be **`abstract`** and methods **`public static`** or routing fails.
 - Webhook headers are **lowercased** by API Gateway (`X-GitHub-Event` → `x-github-event`).
 - If the action needs a client DB, register it in `initialize()` — it runs before the method.
+- **Worker actions do NOT auto-register `DB_CLIENT`.** The dispatcher registers only
+  `DB_CLIENT_LOGS`. A worker that loads a `Client_*` model must register the concrete client
+  schema itself — `_Database::registerClientDatabases($clientId, $environment)`, where
+  `$environment = (substr(_Environment::$name, 0, 4) === 'dev-') ? 'dev' : _Environment::$name`.
+  Without it, every `_Model_Client_*` load fails. Proven pattern: `_Worker_Startech` (and
+  `_Worker_Notification_EmailTemplate`). Do this in `initialize()` or at the top of the method.
 - See [architecture.md](../architecture.md) for the always-HTTP-200 rule and the
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-06-30 — Added the **`DB_CLIENT` auto-registration gotcha**: the dispatcher registers only
+  `DB_CLIENT_LOGS`, so a worker loading a `Client_*` model must call
+  `_Database::registerClientDatabases($clientId, $environment)` itself (proven by
+  `_Worker_Startech` / `_Worker_Notification_EmailTemplate`). Surfaced building the Rate
+  service-purchase email worker (TRUE-79251). (mhammontree)
 - 2026-06-24 — Clarified that the dispatcher spreads the string-keyed `parameters` as PHP **named
   arguments** (`$class::$method(...$parameters)`), so parameter names are the queue contract — do
   not collapse a multi-param action into a single `array` arg. (mhammontree)

package/knowledge/2.0/apps/worker2/features/notification-email-template.md

@@ -0,0 +1,105 @@
+---
+title: "Background Email-Template Worker (_Worker_Notification_EmailTemplate)"
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-30
+owners: ["mhammontree"]
+files:
+  - worker2/Worker/Notification/EmailTemplate.php
+  - _underscore/Model/Client/EmailTemplate.php
+related:
+  - ./notification-email.md
+  - ./creating-worker-actions.md
+  - ../../_underscore/features/email-template-sending.md
+---
+
+## Summary
+
+`_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined
+`EmailTemplates` row off-thread** as a background WorkerJob. It is the generic/reusable
+companion to `_Worker_Notification_Email::Send` (see
+[`notification-email.md`](./notification-email.md)): where that one wraps an ad-hoc
+subject/body in the client's branded shell for *internal* notices, this one dispatches a
+**complete pre-authored transactional template by UUID** (e.g. a client-facing purchase
+confirmation). It is **not** specific to any client — any client's stored `EmailTemplates`
+row can be sent through it.
+
+Decoupling the send from whatever triggers it (e.g. an entitlement save) means an SMTP /
+template failure becomes a **visible failed `WorkerJobs` row** rather than blocking — or
+silently riding inside — the originating transaction.
+
+## Key files / entry points
+
+- `worker2/Worker/Notification/EmailTemplate.php` —
+  `abstract class _Worker_Notification_EmailTemplate`. One method:
+  `public static Send(string $clientIdentifier, string $uuid, $to, $cc, $bcc, ...$args): string`.
+  - Resolves the numeric `clientId` from `$clientIdentifier` via a Core query.
+  - Registers the client DB with
+    `_Database::registerClientDatabases($clientId, $environment)` (see the DB-registration
+    note below — worker actions do **not** get the client DB for free).
+  - Calls `_Model_Client_EmailTemplate::send($clientIdentifier, $uuid, $to, $cc, $bcc, ...$args)`.
+  - The variadic `...$args` forwards the template's `{placeholder}` values straight through
+    the model's named-argument dispatch contract — so the queued `parameters` keys *are* the
+    template variables.
+- `_underscore/Model/Client/EmailTemplate.php` — `send()` does the actual load / placeholder
+  substitution / `_Email` send. Documented in
+  [`email-template-sending.md`](../../_underscore/features/email-template-sending.md).
+
+## How it works
+
+1. **Resolve the client.** Query Core to turn `clientIdentifier` (e.g. `'Rate'`) into the
+   numeric `clientId`.
+2. **Register the client DB.** `_Database::registerClientDatabases($clientId, $environment)`,
+   where
+   `$environment = (substr(_Environment::$name, 0, 4) === 'dev-') ? 'dev' : _Environment::$name`.
+   The worker dispatcher only registers `DB_CLIENT_LOGS` for you — the concrete `Client_<x>`
+   schema that `_Model_Client_EmailTemplate` reads from is **your** responsibility (proven
+   pattern: `_Worker_Startech`). See
+   [`creating-worker-actions.md`](./creating-worker-actions.md).
+3. **Dispatch the template.** `_Model_Client_EmailTemplate::send()` loads the `EmailTemplates`
+   row by UUID, substitutes `{placeholder}` vars from `...$args`, and sends via `_Email`.
+
+### Enqueuing it
+
+`_Worker::runTask('Notification/EmailTemplate/Send', ['clientIdentifier'=>'Rate',
+'uuid'=>'<template-uuid>', 'to'=>'…', 'cc'=>[], 'bcc'=>[], '<var1>'=>…, '<var2>'=>…])`
+inserts a WorkerJob. The dispatcher spreads the string-keyed `parameters` as PHP **named
+arguments**, so each `parameters` key binds to a method parameter — and the leftover keys
+flow into `...$args` as the template variables.
+
+## Gotchas / known issues
+
+- **Worker actions do not auto-register `DB_CLIENT`.** The dispatcher registers only
+  `DB_CLIENT_LOGS`; a worker that loads a `Client_*` model must call
+  `_Database::registerClientDatabases($clientId, $environment)` itself or the
+  `_Model_Client_*` load fails. (Captured as a standalone gotcha in
+  [`creating-worker-actions.md`](./creating-worker-actions.md).)
+- **Don't test this via `_Worker::runTask` locally.** The dev `[cloud]
+  aws_worker_queue_url` points at the **production** SQS queue, so a local `runTask` enqueues
+  onto prod. Call `Send()` (or `_Model_Client_EmailTemplate::send()`) in-process instead —
+  see the local harness in
+  [`email-template-sending.md`](../../_underscore/features/email-template-sending.md#local-test-harness-2-0-worker2--underscore).
+
+## Change history
+
+- 2026-06-30 — Built the generic background email-template worker
+  `_Worker_Notification_EmailTemplate::Send` (TRUE-79251): resolves the client, registers the
+  client DB via `registerClientDatabases`, and dispatches a stored `EmailTemplates` row by
+  UUID through `_Model_Client_EmailTemplate::send`, forwarding `{placeholder}` values via
+  `...$args`. Sits beside `_Worker_Notification_Email::Send` (internal/branded-wrapper path).
+  First consumer: Rate service-purchase confirmation emails — see
+  [`clients/rate/features/service-purchase-emails.md`](../../../clients/rate/features/service-purchase-emails.md).
+  (mhammontree)
+
+## Related docs
+
+- [`notification-email.md`](./notification-email.md) — the internal/branded-wrapper sibling
+  (`_Worker_Notification_Email::Send`).
+- [`creating-worker-actions.md`](./creating-worker-actions.md) — worker dispatch + the
+  client-DB registration gotcha.
+- [`2.0/apps/_underscore/features/email-template-sending.md`](../../_underscore/features/email-template-sending.md)
+  — the `_Model_Client_EmailTemplate` model this worker dispatches.

package/knowledge/2.0/apps/worker2/features/notification-email.md

@@ -16,6 +16,7 @@ files:
 related:
   - ../../_underscore/features/email-template-sending.md
   - ./creating-worker-actions.md
+  - ./notification-email-template.md
 ---
 
 ## Summary
@@ -23,7 +24,10 @@ related:
 Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated,
 not client-facing transactional mail) are sent through one worker action,
 `_Worker_Notification_Email::Send(...)`, which wraps a plain subject/body in the client's
-**DB-stored branded shell** before sending via `_Email`. The branded shell used to be a
+**DB-stored branded shell** before sending. (For sending a **complete pre-authored stored
+template by UUID** off-thread — e.g. client-facing transactional mail — use the sibling
+worker [`_Worker_Notification_EmailTemplate::Send`](./notification-email-template.md)
+instead.) The branded shell used to be a
 hardcoded PHP class (`_Email_Template`, now **deleted**); it now lives in the client DB as a
 reserved `EmailTemplates` row so the branding can change without a code deploy. This is a
 **shared/core 2.0 mechanism** — every client inherits the wrapper row from the dbchanges2

package/knowledge/INDEX.md

@@ -16,8 +16,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 19 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 23 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 20 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 24 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/rate/INDEX.md

@@ -7,4 +7,5 @@
 | [Rate SalesOrder → NetSuite CashSale Export (postPost)](features/netsuite-cashsale-export.md) | 2.0 | Rate sells home-warranty / home-tech-support products. | _underscore/Model/Rate/SalesOrder.php, _underscore/Model/Rate/Item.php |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
+| [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/service-purchase-emails.md

@@ -0,0 +1,137 @@
+---
+title: "Rate Service-Purchase Confirmation Emails (Tech / Warranty)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-30
+owners: [mhammontree]
+files:
+  - _underscore/Model/Rate/Entitlement.php
+  - worker2/Worker/Notification/EmailTemplate.php
+  - dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql
+related:
+  - clients/rate/profile.md
+  - clients/rate/features/aig-contract-creation.md
+  - ../../../2.0/apps/worker2/features/notification-email-template.md
+  - ../../../2.0/apps/_underscore/features/email-template-sending.md
+---
+
+## Summary
+
+When a Rate customer purchases a service, a confirmation email is sent. There are two
+products, each with its own template:
+
+- **Whole Home Tech Services** ("1 Year Unlimited Tech Support") — the *tech* email.
+- **Whole Home Warranty** — the *warranty* email. (AIG is the warranty provider behind this
+  product; not the separate `aig` Staples client.)
+
+The send is triggered from the existing Rate entitlement interceptor
+(`_Model_Rate_Entitlement::postPost`) and dispatched **off-thread** through the generic
+[`_Worker_Notification_EmailTemplate::Send`](../../../2.0/apps/worker2/features/notification-email-template.md)
+worker. The email content lives in DB-stored `Client_Rate.EmailTemplates` rows so it can be
+edited without a deploy.
+
+## How it works
+
+1. **Trigger.** `postPost` (`_underscore/Model/Rate/Entitlement.php`) runs after an
+   entitlement save. It calls `sendPurchaseEmail($payload)` **after** the existing
+   AIG-contract block, via helpers:
+   - `resolvePurchaseProduct()` — warranty vs. tech detection.
+   - `buildPurchaseEmailParameters()` — assemble the template `{placeholder}` values.
+   - `sendPurchaseEmail()` — enqueue
+     `_Worker::runTask('Notification/EmailTemplate/Send', [...])`, wrapped in `try/catch` so a
+     send failure **never blocks the save**.
+2. **Fires on purchase, independent of the AIG contract outcome.** Tech has no AIG contract
+   at all; the warranty email still sends even if the AIG contract call failed (that path is
+   monitored separately by `_Worker_Monitors_RateEntitlement` — see
+   [`aig-contract-creation.md`](./aig-contract-creation.md)).
+3. **Dispatch + send.** The worker resolves the `Rate` client, registers `Client_Rate`, and
+   sends the stored template by UUID with the assembled variables.
+
+### Product detection (the entitlement / product model)
+
+In `Client_Rate`: `Entitlements.saleItemId → Items.id`. **There is no product-type column** —
+the discriminator is **`Items.title`**. Detection mirrors toga2-view's `detectServiceType`:
+
+- title contains `"warranty"` → **warranty**;
+- else `"tech"` / `"support"` → **tech**.
+
+Live titles: `"1 Year Unlimited Tech Support - Annual/Monthly"` and
+`"Whole Home Warranty - Monthly"`. The entitlement's client identifier is `'Rate'`.
+
+### Constants (in `_Model_Rate_Entitlement`)
+
+- `EMAIL_TEMPLATE_TECH_PURCHASE` / `EMAIL_TEMPLATE_WARRANTY_PURCHASE` — the template UUIDs.
+  **Kept in sync with the dbchanges2 rows** (tech `2c4f8a1e-…`, warranty `5d9e3f72-…`).
+- `CLIENT_IDENTIFIER_RATE = 'Rate'`, `PORTAL_URL_TECH` / `PORTAL_URL_WARRANTY`,
+  `SUPPORT_PHONE = '1-206-260-6187'`.
+
+## Templates (dbchanges2)
+
+`dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql` (new `Client_Rate`
+migration folder) inserts two transactional HTML emails via
+`INSERT … ON DUPLICATE KEY UPDATE` (fixed UUIDs). `isActive` is **intentionally excluded**
+from the `ON DUPLICATE UPDATE` list so a re-run never silently re-activates a row that was
+turned off. Responsive 600px table-based HTML faithful to the Figma.
+
+- **Warranty template** keeps the "Renewal Notice" / "Renewal Summary" verbiage per PM/design
+  but **drops the "Renewed" row** — a first purchase has no prior renewal. **Next Charge** is
+  the date shown.
+
+## Brand assets (toga-public S3)
+
+2.0 transactional-email images are hosted on the public bucket **`toga-public`** (us-west-2),
+same convention as the Compass emails (`compass/Email/…`). Rate assets live under
+`rate/Email/`: `rate-header-logo.png` (white "Rate" + red house composited onto header
+`#2c2926`), `toga-technology-footer.png` (white TOGA wordmark composited onto footer
+`#21292d`), `check-circle.png` (green `#226257` circle + white check), `ProximaNovaRegular.woff`.
+
+**Recipe for a transparent/SVG brand asset on a dark email region:** rasterize/flatten the
+asset onto the **exact region background color** so it renders identically across clients
+(Figma SVG → rasterize via Node `sharp` with `flatten: <bgcolor>`).
+
+### Figma fonts (TOGa View 2.0 email designs)
+
+- **Figtree** — content area (headline/body/summary). Free Google Font.
+- **Proxima Nova** — button + footer "Contact us" / copyright. toga2-view self-hosts
+  `ProximaNovaRegular.woff` at `toga2-view/src/fonts/`.
+- **Axiforma** — "Powered By" + the "TOGA TECHNOLOGY" wordmark. **Not in repo, not free** — so
+  the footer wordmark is rendered as the **logo image** (Axiforma baked in) rather than live
+  text.
+
+Email web-font reality: Gmail/Outlook strip web fonts and fall back; Apple Mail/iOS honor
+`@font-face`/`<link>`. Design for the fallback.
+
+## Gotchas / known issues
+
+- **`border-radius` on a `<td>` renders SQUARE in many clients (Outlook).** Use an `<img>` for
+  circular badges/icons (e.g. the green circle-check) instead of a CSS-rounded table cell.
+- **ASCII-only subjects (mojibake workaround).** `_Email::send()` does not set PHPMailer
+  `CharSet=UTF-8`, so non-ASCII subjects/body (em dash, curly quotes, accents) mojibake. This
+  workflow uses ASCII-only subjects; the proper root-cause fix is tracked on
+  [`email-template-sending.md`](../../../2.0/apps/_underscore/features/email-template-sending.md).
+- **Worker DB registration** — see
+  [`notification-email-template.md`](../../../2.0/apps/worker2/features/notification-email-template.md):
+  worker actions do not auto-register `DB_CLIENT`.
+
+## Go-live TODOs (TRUE-79251, flagged in-code as `TODO TRUE-79251`)
+
+Not yet durable knowledge — open items before go-live:
+
+- AIG Terms & Conditions URL — `{termsUrl}` currently `'#'`.
+- From-address / name — currently `donotreply@togatech.com` / "Rate".
+- Confirm the **Next Charge** source field — currently `dateCoverageEnd`.
+
+(Support phone is resolved: `1-206-260-6187`.)
+
+## Change history
+
+- 2026-06-30 — Built the Rate service-purchase confirmation email workflow (TRUE-79251):
+  `postPost` trigger + helpers in `_Model_Rate_Entitlement`, two DB-stored `Client_Rate`
+  templates (tech / warranty) dispatched off-thread via
+  `_Worker_Notification_EmailTemplate::Send`, brand assets on `toga-public/rate/Email/`.
+  Fires on purchase independent of the AIG-contract outcome. Tested locally with a real send
+  to the dev team. (mhammontree)

package/knowledge/clients/rate/profile.md

@@ -12,7 +12,7 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-29
+updated: 2026-06-30
 owners: ["rgirish", "bala", "mhammontree"]
 files: []
 related:
@@ -21,6 +21,7 @@ related:
   - clients/rate/features/netsuite-cashsale-export.md
   - clients/rate/features/service-card-entitlements.md
   - clients/rate/features/aig-contract-creation.md
+  - clients/rate/features/service-purchase-emails.md
 ---
 
 ## Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.247",
+  "version": "1.0.249",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",