toga-ai 1.0.248 → 1.0.250

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.250",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/skills/plan-ticket/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: plan-ticket
+description: Build an implementation plan for a ClickUp ticket end-to-end. Invoke as `/plan-ticket <TICKET-ID>` (e.g. `/plan-ticket TRUE-79868`). Retrieves the full ticket from ClickUp, interrogates Talos (meeting-notes AI) and the local codebase for context, primes team framework knowledge by self-answering /kickoff from that gathered context, synthesizes a phased plan, saves it to test/@dave/approach/<TICKET>.md, shows a preview and iterates until you approve, then pushes the approved plan as formatted rich text to the ticket's Pseudocode field. Trigger on "/plan-ticket", "plan this ticket", "build a plan for <ticket>".
+---
+
+# plan-ticket — ticket → researched plan → ClickUp Pseudocode field
+
+Given a ClickUp ticket id, produce a grounded implementation plan and write it both to
+`test/@dave/approach/<TICKET>.md` and to the ticket's **📝 Pseudocode** custom field
+(rendered, not raw markdown).
+
+Helper scripts live in `scripts/` next to this file. They are run with `node`. All Talos
+auth is automatic — see **Token handling** below; the developer should never have to paste a
+token unless the 30-day refresh token has expired.
+
+Environment used: `CLICKUP_API_KEY`, `CLICKUP_TEAM_ID` (already in the session env). Talos
+tokens live in `~/.talos/credentials.json` (NOT in the repo).
+
+---
+
+## Step 0 — Resolve the ticket id
+
+The id is the argument after `/plan-ticket` (e.g. `TRUE-79868`). If none was given, ask for it.
+
+## Step 1 — Retrieve the full ticket from ClickUp
+
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" get <TICKET>
+```
+
+This prints JSON: `{name, status, description, pseudocodeFieldId, fields:{...non-empty custom fields...}}`.
+Read **all** of it — name, user story / description, and any populated custom fields (Application,
+Requirements, Epic, Acceptance criteria, etc.). These details drive both the Talos query and the
+codebase investigation. The **Application / Client** fields here also feed the self-answered
+kickoff in Step 4. Note `pseudocodeFieldId` for the push in Step 7.
+
+## Step 2 — Investigate the local codebase FIRST (before Talos)
+
+**Do the code recon before querying Talos.** Investigating first surfaces the *specific*
+unknowns — what already exists vs. what's build-from-scratch, FK topology, schema quirks,
+sibling/precedent plans in `test/@dave/approach/`, the exact reference handlers the ticket
+mirrors — which lets Step 3 ask Talos sharp, targeted questions ("a meeting discuss the DELETE
+policy for X, given Sales/Opportunities hold RESTRICT FKs?") instead of generic ones. A generic
+Talos query usually returns "no specific notes"; a code-informed one is far more likely to hit.
+
+Ground everything in the real code. Prefer the TOGA `planner` agent for non-trivial tickets (it
+reads deep docs in its own context and returns a phased plan); for small tickets, read the
+specific files directly. Open the actual classes, schema (`dbchanges2` / the live core2 reader),
+and reference handlers the ticket touches — do not guess paths. **Come out of this step with a
+concrete list of open questions / decisions to put to Talos.**
+
+## Step 3 — Interrogate Talos (meeting-notes AI), informed by the code findings
+
+Compose the question from the ticket details **plus the specific unknowns/decisions Step 2
+surfaced** — name the concrete choices you need ruled on (delete policy, scope boundaries,
+owners, deadlines) and the architecture you found, so Talos can confirm/deny against real
+meeting notes. Then:
+
+```bash
+node ".claude/skills/plan-ticket/scripts/talos.js" query "<your code-informed question>"
+```
+
+The helper auto-refreshes the access token, opens a thread against DevCore, auto-accepts the
+agent's plan-approval interrupt, and prints the assistant's answer. Capture what it finds
+(with the meeting/date citations it gives) — and note explicitly when it finds nothing specific.
+
+> Token handling: `talos.js` reads `~/.talos/credentials.json`, and if the cached access token
+> is missing/expiring it calls `POST {apiHost}/v2/auth/refresh` with the stored refresh token to
+> mint a new one (transactionId must be unique per call — the helper generates it). If the
+> **refresh** token itself has expired (~30 days), the helper prints clear instructions: the
+> developer logs in at `talos.togaiq.com`, grabs the `accessToken` + `refreshToken` from the
+> browser (DevTools → Application/Local Storage, or any `api.togaiq.com` request's
+> `Authorization` header), and runs `node scripts/talos.js set-tokens <access> <refresh>` once.
+> Never echo tokens into chat, memory, the KB, or any committed file.
+
+## Step 4 — Prime framework context via kickoff (self-answered from Steps 1–3)
+
+Now that you hold the ticket (Step 1), the code recon (Step 2), and the Talos findings
+(Step 3), invoke **`/kickoff`** to prime the team knowledge base — but **answer its interview
+yourself from what you just gathered** so it never stops to ask the developer. Steps 1–2
+already tell you everything kickoff's Step 2 interview needs:
+
+- **Framework (1.0 / 2.0 / both)** — from the repos the code sweep landed in (`worker/`,
+  `library/`, `toga/`, etc. → 1.0; `worker2/`, `api2/`, `_underscore/`, the React SPAs → 2.0)
+  plus the ticket's **Application** field.
+- **Layer (front / back / hybrid)** — from the repo types touched (React SPA → front-end;
+  PHP API/worker → back-end; both → hybrid).
+- **Repos** — the in-scope repos the Step 2 sweep identified.
+- **Client** — from the ticket's Application/Client field or ClickUp space; use
+  **"shared / internal"** when the ticket isn't client-specific.
+
+Invoke kickoff with these pre-filled as the trailing argument so its interview is satisfied and
+it goes straight to preflight + priming, e.g.:
+
+```
+/kickoff <framework> <layer>, repos: <repos>, client: <client> — <ticket title>
+```
+
+**Only stop to ask the developer if a gate answer is genuinely ambiguous** after all three
+inputs (e.g. the code spans both frameworks and neither ticket nor Talos says which is in
+scope). Otherwise let kickoff run unattended — it checks for harness updates, resolves the
+load-set, and returns the `context-primer` briefing.
+
+**Carry the primer briefing into synthesis.** The framework rules, gotchas, and client
+variations it surfaces directly inform the plan — fold them into the **Architecture decision**
+and **Risks/gotchas** sections in Step 5. This is the payoff of priming before synthesizing.
+
+> Ordering note: the code sweep (Step 2) intentionally runs *before* kickoff. Kickoff's gate
+> hook blocks reads until it primes, and doing the recon first is exactly what lets you
+> self-answer the interview here. Once kickoff's preflight runs, the gate releases and Step 5
+> synthesis can read freely.
+
+## Step 5 — Synthesize the plan and save it
+
+Write a phased plan to `test/@dave/approach/<TICKET>.md`. Structure: a **`# <TICKET> — <title>`
+heading**, then a **one-line bold header** (`**Repos:** … · **Framework:** … · **Client:** …`,
+plus a `· **Sibling/precedent:** <TICKET>` when one exists), then Summary · Meeting-notes
+context (Talos, with citations + an explicit "no notes found" note where true) · What already
+exists · Architecture decision · Phases (each: title, exact file paths, pseudocode) · Testing ·
+Risks/gotchas · Rollout/verification · Owners/open-questions to confirm · Key files. Run any
+relevant TOGA reviewers (php-reviewer/sql-reviewer) if code-shaped decisions warrant it.
+
+> **ANY SQL SHOWN IN THE PLAN'S PSEUDOCODE MUST ALREADY FOLLOW THE TEAM SQL FORMATTING
+> CONVENTIONS — NO ONE-LINE QUERIES, EVEN IN PSEUDOCODE.** WRITE EVERY QUERY MULTI-LINE:
+> KEYWORDS UPPERCASE, EACH CLAUSE ON ITS OWN LINE, TABLE/COLUMNS INDENTED ON THEIR OWN LINES,
+> NO `SELECT *`. THE PLAN IS THE TEMPLATE THE WORK-TICKET STEP COPIES FROM, SO A SLOPPY
+> ONE-LINER HERE BECOMES A STANDARDS VIOLATION IN THE SHIPPED CODE.
+
+**No point-in-time status.** Do not record what's currently deployed / Released / live (e.g. "the enqueuer is Released only on X today", "PR #123 is merged") — it's stale the moment it's written. Describe durable mechanisms, decisions, and required steps instead. (Matches the team rule against deployment status in docs.)
+
+**Length limit: keep the plan to ≤ 150 lines.** Be terse and high-signal — favor tight
+pseudocode and bullet lists over prose, fold related points into one line, and cut anything that
+doesn't change what the implementer does. If the content can't fit, trim the lowest-value detail
+(verbose rationale, repeated caveats) rather than dropping a section. After writing, verify with
+`wc -l test/@dave/approach/<TICKET>.md` and tighten if it's over.
+
+## Step 6 — Preview & approval loop (gate — do NOT push until approved)
+
+**The plan does NOT go to ClickUp automatically.** After writing the `.md`, present it to the
+developer for review and **wait for explicit approval** before Step 7.
+
+1. Show a **preview**: the full plan content (or, if long, the Summary + Architecture decision +
+   Phase titles + Owners/open-questions, with the rest available on request) so the developer can
+   judge it in-chat. Note the line count (must be ≤150).
+2. Prompt clearly: *"Approve this plan for the TRUE-XXXXX Pseudocode field, or tell me what to
+   change?"*
+3. **Iterate**: incorporate the developer's comments — edit `test/@dave/approach/<TICKET>.md`,
+   re-investigate (codebase or Talos) if a change needs grounding, re-check ≤150 lines, and show
+   the updated preview. Go back and forth until the developer explicitly approves.
+4. Only on explicit approval ("approved", "looks good", "ship it", etc.) proceed to Step 7. Do
+   **not** push on ambiguous replies — ask.
+
+## Step 7 — Push the approved plan to the Pseudocode field (rendered)
+
+Only after Step 6 approval. ClickUp custom text fields render formatting from a **Quill Delta**
+in `value_richtext`, not markdown in `value`. The helper converts the markdown and pushes both:
+
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" push <TICKET> "test/@dave/approach/<TICKET>.md"
+```
+
+It resolves the Pseudocode field id by name, converts markdown → Delta, and POSTs
+`{value:<plain>, value_richtext:<Delta JSON string>}`. Confirm it returns 200.
+
+**Overwrite guard.** `push` **refuses** (exit 2) if the Pseudocode field already has content, to
+avoid clobbering a manual/teammate edit — it prints the existing content. If that happens: show
+the existing content to the developer, confirm it's safe to replace, and only then re-run with
+`--force`:
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" push <TICKET> "test/@dave/approach/<TICKET>.md" --force
+```
+(A prior plan *we* wrote and the developer just re-approved is fine to replace — but still
+surface it so the developer knows what's being overwritten.)
+
+## Step 8 — Report
+
+Summarize: ticket title, what Talos surfaced (or didn't), the plan's key decisions + any
+owners/open questions to confirm, and the two outputs (the `.md` path + the Pseudocode field).
+Offer `/capture` if a durable KB-worthy finding emerged.
+
+---
+
+## Notes & reuse
+
+- The markdown→Quill-Delta conversion rules and the `value_richtext` mechanism are documented in
+  the team KB (`2.0/apps/worker2/features/clickup-richtext-api.md`) and personal memory
+  (`reference_clickup_richtext_field_delta`).
+- Talos is a LangGraph Agent Protocol server (`api.togaiq.com`); DevCore is the dev-team assistant
+  wired to the meeting-notes knowledge base. Other assistants (One/Sales/HR) are in
+  `credentials.json` under `assistants` if a different one is ever needed.
+- `talos.js query` accepts an optional 2nd arg = assistant key (default `devcore`).