toga-ai 1.0.248 → 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/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.248",
+  "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",