toga-ai 1.0.501 → 1.0.503

package/knowledge/1.0/apps/togadesk/INDEX.md

@@ -7,6 +7,7 @@
 | [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairorder.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
 | [Managed Service Order Create Flow (New MSO modal → tickets/add)](features/managed-service-order-create.md) | The **Managed Service Order (MSO) create flow** is how a TOGa Desk user manually creates a managed service order: pick an End User (or a Client Location), choos | desk/includes/controllers/actions/tickets/add.php, desk/template/modals/tickets/addNew.php, desk/template/pages/managed.php, desk/template/pages/getinfo.php, desk/template/footer.php, library/app/model/togadesk/repairorder.php |
 | [Ticket Email Notifications (notifications table)](features/notifications.md) | Which TOGa Desk emails fire for a given client is driven **entirely by data**, not code: the `TOGaDeskSupport.notifications` table holds one row per `(clientid, | desk/includes/classes/class.notification.php, crons/tickets.php, crons/tickets_prod.php |
+| [Per-Client Hostname Restriction (getRestrictedClient)](features/per-client-host-restriction.md) | TOGa Desk supports **per-client branded URLs** (e.g. | desk/includes/functions.php, desk/template/header.php, _/browser/datatable/tickets, desk/includes/classes/class.ticket.php, ebs/setup_phpini.php, ebs/http_to_https.php, desk/template/modals/kb/viewDocument.php, desk/template/modals/files/aws-view.php, desk/template/modals/files/contract-view.php, template/pages/documents/view.php, template/pages/tasks/view.php |
 | [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |
 | [Ticket Lifecycle (class.ticket.php)](features/ticket-lifecycle.md) | All TOGa Desk ticket creation and reply handling funnels through `Ticket` in `desk/includes/classes/class.ticket.php`. | desk/includes/classes/class.ticket.php, desk/includes/controllers/actions.php, desk/includes/controllers/actions/tickets/addReply.php, desk/api/resources/tickets.php, desk/api/resources/ticket_replies.php, crons/tickets.php, crons/pipe.php, desk/includes/controllers/actions/tickets/merge.php |

package/knowledge/1.0/apps/togadesk/features/per-client-host-restriction.md

@@ -0,0 +1,107 @@
+---
+title: Per-Client Hostname Restriction (getRestrictedClient)
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: feature
+status: active
+updated: 2026-08-04
+owners: ["mhammontree"]
+files:
+  - desk/includes/functions.php
+  - desk/template/header.php
+  - _/browser/datatable/tickets
+  - desk/includes/classes/class.ticket.php
+  - ebs/setup_phpini.php
+  - ebs/http_to_https.php
+  - desk/template/modals/kb/viewDocument.php
+  - desk/template/modals/files/aws-view.php
+  - desk/template/modals/files/contract-view.php
+  - template/pages/documents/view.php
+  - template/pages/tasks/view.php
+related:
+  - ../architecture.md
+  - ../../togaview/architecture.md
+---
+
+## Summary
+
+TOGa Desk supports **per-client branded URLs** (e.g. `rumcsi.togadesk.togatech.com`). The whole
+mechanism is host-based: `getRestrictedClient()` in `desk/includes/functions.php` (~L1513-1592)
+derives a single "restricted client" from the request hostname, and `restrictByClient()` (L1508)
+is the gate used throughout the UI. Adding a new per-client URL is therefore **one switch case
+plus a lot of non-application work** (cert, sessions, hardcoded legacy domains).
+
+This contradicts the impression that togadesk has no host-based logic — it does, and this is the
+only place a new subdomain gets registered.
+
+## How it works
+
+1. `getRestrictedClient()` lowercases `$_SERVER['HTTP_HOST']`, strips the port, and matches a long
+   **hardcoded switch of per-client subdomains**, returning a `CLIENT_*` constant or `null`.
+2. Client-ID constants are defined in the same file (~L1488-1506):
+   `CLIENT_AGILANT=2`, `CLIENT_OFFICEDEPOT=3`, `CLIENT_RUMCSI=146`, `CLIENT_IMHOUSTON=167`,
+   `CLIENT_FORDHAM=179`.
+3. `restrictByClient()` (L1508) wraps that result and gates:
+   - navigation/menus in `desk/template/header.php` (~L1638-1665), and
+   - the ticket datatables under `_/browser/datatable/tickets/*`.
+4. Post-login data filtering keys off the **session `clientid`**, not the host — the host
+   restriction is a UI/entry gate, not the record-level tenancy boundary.
+
+**TOGa View resolves its host separately.** `togaview/_/app/framework.php` has its own
+`switch($_SERVER['HTTP_HOST'])` that sets `$_SESSION['stylePath']` and selects the RUMCSI SAML
+branch; an unregistered hostname falls through to default branding and **skips SAML**. So a
+togadesk-side DNS record is safe on its own, but any new *togaview* hostname must be added there
+too. _(Carried from the togaview architecture doc — not re-verified in code on 2026-08-04.)_
+
+## Adding a new per-client TOGa Desk URL — checklist
+
+The app code is the easy part. What actually bites:
+
+- **Register the host** in the `getRestrictedClient()` switch (and add a `CLIENT_*` constant if the
+  client is new). Verified 2026-08-04: `rumcsi.togadesk.togatech.com` is **already a case**, so the
+  RUMCSI AWS DNS record needs no code change.
+- **TLS cert.** A 4-label host such as `rumcsi.togadesk.togatech.com` is **not** covered by a
+  `*.togatech.com` wildcard. You need `*.togadesk.togatech.com` or an exact SAN on the ALB
+  listener, plus a host-header rule.
+- **Sessions log everyone out on a domain change.** `ebs/setup_phpini.php` sets
+  `session.save_handler=rediscluster` but sets **no `session.cookie_domain`**, and there is no
+  `session_set_cookie_params()` anywhere — the cookie is host-scoped. Worse, `people.sessionid` is a
+  **single column**, so logging in on a second domain invalidates the session on the first.
+- **Smoke-test Office document previews.** `desk/template/modals/kb/viewDocument.php`,
+  `modals/files/aws-view.php`, `modals/files/contract-view.php`, `template/pages/documents/view.php`
+  and `template/pages/tasks/view.php` embed `https://{HTTP_HOST}/...` into third-party viewers
+  (`docs.google.com/gview`, `view.officeapps.live.com`) which fetch **server-side**. On a host with
+  an untrusted cert, Word/Excel/PPT previews fail **silently** while same-origin PDF iframes still
+  work — making this the best post-cutover check.
+- **Keep the old domain resolvable.** `class.ticket.php` L485-486 and L886-887 hardcode
+  `https://togadesk[-env].agilantsolutions.com/uploads/` when rewriting inline ticket images, so
+  outbound ticket emails keep serving images from the old domain. Other hardcoded legacy domains:
+  `csat.agilantsolutions.com`, `toga.agilantsolutions.com`,
+  `yourcloudhq.togaview.agilantsolutions.com`, and `toga_payment_easyurl` / `fullurl` in every
+  `config.*.ini`.
+
+## Gotchas / known issues
+
+- **Cross-tenant login hole (pre-existing, NOT fixed — deserves its own ticket).** The
+  password-login access condition in `desk/includes/functions.php` (~L627-631) is a chain of ORs,
+  and two clauses grant access **regardless of which client's subdomain is in use**:
+  `getRestrictedClient() != CLIENT_AGILANT && $restrictedClientId == CLIENT_IMHOUSTON` lets an IM
+  Houston user log in on the RUMCSI host, and
+  `getRestrictedClient() != CLIENT_FORDHAM && $restrictedClientId == CLIENT_FORDHAM` does the same
+  for Fordham. Post-login filtering keys off the session `clientid`, so it is not an immediate
+  record leak, but it **defeats the per-client URL restriction and contradicts the comment directly
+  above it** (L627-629). Recommended fix: replace with an explicit per-restricted-client allowlist
+  using guard clauses. Anyone touching login or adding a client URL must know this.
+- **`siteURL()` emits `http://` behind the ALB.** `desk/includes/functions.php` (~L22-31) only emits
+  `https` when `$_SERVER['HTTPS'] == 'on'`; behind the ALB only `X-Forwarded-Proto` is set (see
+  `ebs/http_to_https.php`). It currently has **no callers** in togadesk — a latent trap for any new
+  absolute-link code.
+- The host switch and the client-ID constants are hardcoded — there is no DB-driven mapping, so
+  every new branded URL is a code change.
+
+## Change history
+
+- 2026-08-04 — Documented from a read-only review (TRUE-80139) of the RUMCSI branded-URL cutover;
+  recorded the add-a-hostname checklist and the cross-tenant login hole. No code changed. (mhammontree)

package/knowledge/1.0/apps/worker/INDEX.md

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config, worker/crons/infrastructure/execute_dbchanges.php, worker/.ebextensions/030_dbchanges.config |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
-| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
+| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php |
 | [Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync](features/elite-togadesk-attachment-sync.md) | `sync_togadesk_elite_attachments.php` is a standalone cron (every 5 minutes) that syncs file attachments from TOGA 2.0 into TOGaDeskSupport for Elite. | worker/crons/toga2/elite/sync_togadesk_elite_attachments.php, worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/reconcile_drift_2023plus.php, test/@dave/probe_invoice_gap_2026.php, test/@dave/probe_creditmemo_gap_detail.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.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_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |

package/knowledge/1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md

@@ -6,12 +6,18 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
+updated: 2026-08-03
 owners: ["bala"]
 files:
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
+  - worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php
   - worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php
-related: []
+  - worker/crons/toga2/compasscanada/send_delivered_email.php
+  - worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php
+  - worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php
+  - library/app/client/compasscanada.php
+related:
+  - ../../../clients/compass-canada/features/french-order-email-localization.md
 ---
 
 ## Summary
@@ -95,6 +101,12 @@ the tracking number as emailed (it retries next run).
 - **Compass Canada** — EN/FR by `UserGlobalSettings.settingId = 2` (FR when the value starts
   with `fr`); French section labels and a French (HTML-entity) status message; uses
   `htmlentities` in the section header builder and a 7-param French-aware `buildPackageBlockHtml`.
+  Language is resolved through the shared 1.0 helper
+  `App_Client_CompassCanada::resolveUserLanguageCode($userId, $databaseLink)`
+  (`library/app/client/compasscanada.php`), wrapped in `try/catch` → default English at every call
+  site. **Item rows are localized too** as of 2026-08-03: titles come from the `ItemTranslations`
+  sidecar and the `P/N:` / `Qty:` labels are translated (`N/P` / `Qté`) — see
+  [Compass Canada French order emails](../../../clients/compass-canada/features/french-order-email-localization.md).
 
 ## Gotchas / known issues
 
@@ -109,9 +121,29 @@ the tracking number as emailed (it retries next run).
   clients — that is correct and unrelated to the package-contents source.
 - **Not yet deployed.** These crons depend on the api2 POST scripted-API change and its
   `RecordScripts`/`AclRecordScripts` registration — see related docs.
+- **⚠ The Compass Canada crons now hard-depend on `library`'s `App_Client_CompassCanada`.** All 8
+  `crons/toga2/compasscanada/` scripts call it for language resolution, and as of 2026-08-03 that
+  class change is **uncommitted on `_production`** with no `TRUE-80543` branch. Merging the `worker`
+  PR without the `library` change **fatals** every Compass Canada cron. Ship `library` first or in
+  the same release.
+- **A language lookup must never abort the run.** `App_Query::execute()` (1.0,
+  `library/app/query.php`) throws on any MySQL error, and an unguarded throw here aborts every
+  remaining order in that cron tick. Every call site wraps the lookup in `try/catch`, defaults to
+  base English, and `error_log`s.
+- **Pick the template from the language of the person actually being emailed.** The manager-approval
+  reminder cron (`compass_email_reminders.php`) selected the template from the **requester's**
+  language even though the mail goes to the **manager**. Fixed 2026-08-03.
 
 ## Change history
 
+- 2026-08-03 — Compass Canada **item rows are now localized**: titles resolved from the
+  `ItemTranslations` sidecar (two-column select + PHP fallback, never a mixed-collation SQL
+  `COALESCE`) and translated `N/P` / `Qté` labels; language resolution moved onto the shared 1.0
+  helper `App_Client_CompassCanada::resolveUserLanguageCode()` with `try/catch` → English at every
+  call site so a lookup failure can't abort the rest of the run. Item text is entity-escaped for the
+  iso-8859-1 send. Flagged the **`library` deployment dependency** (uncommitted on `_production`;
+  all 8 Canada crons fatal without it). TRUE-80543, not yet deployed. Detail lives on
+  [Compass Canada French order emails](../../../clients/compass-canada/features/french-order-email-localization.md). (bala)
 - 2026-06-18 — Switched Canada `getOrderFulfillmentData` from the ASN chain to the
   `ItemFulfillmentItems` line bridge (match Compass USA); item info all 14px. (bala)
 - 2026-06-18 — Brought both prod crons to parity: per-package partial assembly, `buildTrackingUrl`

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

@@ -11,6 +11,7 @@
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
+| [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the | _underscore/Database.php, _underscore/Environment.php, api2/Initialize.php |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, api2/Component/Api/Netsuite/Netsuite.php |
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.php |

package/knowledge/2.0/apps/_underscore/features/cli-script-bootstrap.md

@@ -0,0 +1,84 @@
+---
+title: Running 2.0 code from a bare CLI script (bootstrap + transactions)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-03
+owners: ["bala"]
+files:
+  - _underscore/Database.php
+  - _underscore/Environment.php
+  - api2/Initialize.php
+related:
+  - ./model-interceptor-unit-testing.md
+  - ./database-alias-repointing.md
+  - ./email-template-sending.md
+---
+
+## Summary
+
+A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real
+2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the same as a web request. `_Route`
+does several things for a request that nothing does for `php script.php`, and the two that bite
+hardest are the **transaction** and the **`ENVIRONMENT`** variable. This is the minimum recipe
+plus the traps.
+
+For DB-**free** unit tests of interceptor logic, use the PHPUnit scaffold instead — see
+[DB-free unit testing for model interceptors](./model-interceptor-unit-testing.md).
+
+## How it works
+
+1. Set the environment **before** anything loads: `putenv('ENVIRONMENT=<envSlug>')` (or export it).
+   `_Environment` **fatals** if `getenv('ENVIRONMENT')` is unset.
+2. `chdir` to the **api2 root** so relative `./Config` / bootstrap paths resolve, then
+   `require 'Initialize.php'`.
+3. Point `DB_CLIENT` at the client schema you want:
+   `_Database::registerClientDatabases('<envSlug>', <clientId>)`.
+4. **Open and close the transaction yourself:** `_Database::transactionStart()` before the writes
+   and `_Database::transactionCommit()` after. A web request gets this from `_Route`; a CLI script
+   does not.
+5. Read-only scripts need neither, but see the write-drop gotcha below before assuming a script is
+   read-only.
+
+## Gotchas / known issues
+
+- **Without an explicit `transactionStart()` + `transactionCommit()`, CLI writes silently vanish.**
+  The auto-increment advances (so ids are consumed and the write *looks* like it worked), but no row
+  persists, and reading back a just-inserted row returns **0 rows** in the same script. No error is
+  raised. This is the CLI face of the lazy-transaction behavior documented on
+  `_underscore/architecture.md` — `_Database::register()` starts a lazy transaction that MySQL rolls
+  back when the connection closes uncommitted.
+- **`ENVIRONMENT` must be set before the framework loads**, not after — `_Environment::initialize`
+  fatals on a missing value rather than defaulting.
+- **Local MySQL and PROD both run `sql_mode = ''`**, so `ONLY_FULL_GROUP_BY` is **not** enforced in
+  either. A local test of a `GROUP BY` change therefore proves nothing unless the script does an
+  explicit `SET SESSION sql_mode = 'ONLY_FULL_GROUP_BY,…'` first. (Relevant to any query that
+  selects non-aggregated columns alongside an aggregate.)
+- **1.0 sibling trap (`worker` tier):** reference `App_Framework_Worker::initialize()` **before**
+  anything touches `App_Framework`. `__APPROOT__/app/framework.php` shadows the library file for
+  *both* class names, so resolving `App_Framework` first loads the app file and the library
+  definition never arrives.
+- Do not drive a local harness through `_Worker::runTask` — the dev config's
+  `[cloud] aws_worker_queue_url` points at the **production** SQS queue. Call the target method
+  in-process. (Also noted on [email-template-sending.md](./email-template-sending.md).)
+
+## Change history
+
+- 2026-08-03 — Created: recorded the bare-CLI bootstrap recipe (`ENVIRONMENT` first → `chdir` api2
+  root + `require Initialize.php` → `registerClientDatabases`) and the traps found building a
+  Compass Canada email render harness: CLI scripts must call `_Database::transactionStart()` **and**
+  `transactionCommit()` themselves or writes silently roll back while auto-increment still advances;
+  local **and** prod run `sql_mode = ''` so a local `GROUP BY`/`ONLY_FULL_GROUP_BY` test proves
+  nothing without `SET SESSION sql_mode`; and the 1.0 `App_Framework_Worker`-before-`App_Framework`
+  load-order trap. (bala)
+
+## Related docs
+
+- [DB-free unit testing for _underscore model interceptors](./model-interceptor-unit-testing.md)
+- [Database alias repointing](./database-alias-repointing.md)
+- [Client Email Template Sending](./email-template-sending.md) — its local test-harness section.
+- [French (fr-CA) Order Email Localization (Compass Canada)](../../../clients/compass-canada/features/french-order-email-localization.md)
+  — the work these traps surfaced in.

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-29
+updated: 2026-08-03
 owners: ["bala", "tcox", "dfranks"]
 files:
   - _underscore/Email.php
@@ -15,6 +15,7 @@ related:
   - email-template-sending.md
   - ../../worker2/features/all-client-email-queue-monitor.md
   - ../../ai-bdr/features/web-funnel-app.md
+  - ../../../clients/compass-canada/features/french-order-email-localization.md
 ---
 
 ## Summary
@@ -56,6 +57,29 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
 - **The Send worker forces HTML mode.** `sendEmail()` calls `$mailer->IsHTML(true)`
   **unconditionally**, ignoring the sender's `setIsHtml(false)`. A caller that queued a
   "plain-text" message is still transmitted HTML-mode. Author bodies accordingly.
+- **⚠ The whole chain sends as iso-8859-1 — escape non-ASCII, or it mojibakes.** **Neither**
+  `_Email::send()` (queue side) **nor** `_Worker_Infrastructure_Email_Send::Run()` (transmit side)
+  sets `$mailer->CharSet`, so PHPMailer's default **iso-8859-1** applies end to end. Any raw UTF-8
+  in the rendered body (accented French text, em dash, curly quotes) arrives garbled. Two
+  consequences for anything building an email body in PHP:
+  - **Escape dynamic text as HTML entities** with exactly
+    `htmlentities($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false)`. Both non-default
+    arguments are required:
+    - `double_encode = false` — some stored data (e.g. `ItemTranslations.title` in one
+      environment) already holds **literal HTML entities as text**; re-encoding turns `é`
+      into `é`, which the recipient reads as a literal `é`.
+    - `ENT_SUBSTITUTE` — passing explicit flags **drops** PHP 8.1's default `ENT_SUBSTITUTE`, and
+      `htmlentities()` returns an **empty string** on invalid UTF-8, so a single bad byte silently
+      blanks the entire field.
+  - **Stored `EmailTemplates` bodies should be pure ASCII.** A raw non-breaking space (U+00A0) or a
+    stray `Â` (U+00C2) pasted into a template body renders as mojibake in the delivered mail — use
+    ` ` / `é` entities instead. Real defect: 8 Compass Canada French templates carried a
+    `Â`+NBSP sequence before the colon in `"Commande :"`.
+
+  The root-cause fix is still to set `$mailer->CharSet = 'UTF-8'` — but that changes **every**
+  client's mail, so it must be its own tested change, not a drive-by. See
+  [`email-template-sending.md`](email-template-sending.md) and
+  [Compass Canada French order emails](../../../clients/compass-canada/features/french-order-email-localization.md).
 - **⚠ SECURITY — hardcoded AWS SES SMTP credentials in `_underscore/Email.php`.** The
   `SMTP_USERNAME` / `SMTP_PASSWORD` class constants hold **real** SES SMTP credentials committed
   in source, violating the no-secrets-in-code rule. Documenting the **location only** — do not
@@ -102,6 +126,14 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
     for a hotfix.
 
 ## Change history
+- 2026-08-03 — Documented the **full encoding chain** (no code change): neither `_Email::send()` nor
+  the worker2 Send action sets `$mailer->CharSet`, so mail transmits as **iso-8859-1** end to end.
+  Recorded the required escape for dynamic body text —
+  `htmlentities($v, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false)`, where `double_encode = false`
+  avoids `é` on already-entity-encoded data and `ENT_SUBSTITUTE` (dropped when explicit
+  flags are passed) stops an invalid-UTF-8 byte returning an empty string — and that stored
+  `EmailTemplates` bodies should be pure ASCII (a raw NBSP/`Â` mojibakes). Surfaced fixing Compass
+  Canada's French order emails. (bala)
 - 2026-07-29 — Noted that the SES SMTP credentials/settings now have a **non-PHP consumer**: the
   BDR funnel sends via nodemailer against the same SES host (us-west-2, port 587, TLS) using
   `TOGA_SMTP_*` env vars, so a rotation must be coordinated with BDR's `.env.local` + Amplify

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-07-28
+updated: 2026-08-03
 owners: ["jcardinal", "bala", "mhammontree"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
@@ -114,6 +114,11 @@ can keep using `sendEmail($api, ...)`.
   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.
+  - **The transmit side doesn't set it either**, so the effective wire charset is **iso-8859-1**
+    end to end. For a body that genuinely needs accents (e.g. French), the working escape is
+    `htmlentities($v, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false)` — both non-default arguments
+    matter. See the encoding-chain gotcha on
+    [`email-send-pipeline.md`](email-send-pipeline.md) for why.
 - **⚠ SECURITY — live AWS SES SMTP credentials are hardcoded in `_underscore/Email.php`.**
   The `SMTP_USERNAME` / `SMTP_PASSWORD` class constants (near the top of `_Email`) hold
   **real** AWS SES SMTP credentials committed in source, violating the team no-secrets-in-code
@@ -146,6 +151,10 @@ worker method) in-process instead.
 
 ## Change history
 
+- 2026-08-03 — Refined the `CharSet` gotcha: the **transmit** side doesn't set it either, so the
+  effective wire charset is **iso-8859-1**, and a body that needs accents should escape with
+  `htmlentities($v, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false)` (details on
+  [`email-send-pipeline.md`](email-send-pipeline.md)). Doc only. (bala)
 - 2026-07-28 — Clarified that `_Email::send()` **queues** a `PENDING` `Logs_[Client].Email` row
   rather than transmitting; the actual SES SMTP send/retry/`SENT`/`FAILED` happens in the worker2
   `Infrastructure/Email/Send` cron (~1-min latency). Added the new

package/knowledge/2.0/apps/api2/features/language-translation-layer.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-08-03
 owners: ["jcardinal", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -230,10 +230,27 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   (`itemCategoryFeatureGroup.name`, e.g. "Processeur"/"Mémoire") stayed English, because the group
   object serialized through the all-fields branch. **Not a query-depth problem** — a commerce-side
   `depth:6` theory was wrong and reverted; the fix returns French headers at the default `meta.depth 3`.
-- **Sidecar/source collation mismatch.** The translation sidecar tables use `utf8mb4_unicode_ci`
-  (matching `ItemTranslations`) while the source fields are `utf8mb4_0900_ai_ci`. Ad-hoc queries that
-  compare a sidecar string against a source string must add `COLLATE utf8mb4_bin` or MySQL throws a
-  collation-mismatch error.
+- **Sidecar/source collation mismatch — and the collations DIFFER PER CLIENT DATABASE.** The
+  sidecar tables use `utf8mb4_unicode_ci` (matching `ItemTranslations`) while the source field's
+  collation varies by tenant: verified in prod **and** dev-sandbox, `Client_CompassCanada.Items.title`
+  is `utf8mb4_0900_ai_ci` but `Client_Compass.Items.title` is `utf8mb4_unicode_ci`. So a hardcoded
+  `COLLATE utf8mb4_bin` "fix" is brittle — it happens to work in one client DB and is unnecessary or
+  wrong in another. Consequences:
+  - **Never build a mixed-collation fallback expression in SQL.**
+    `COALESCE(NULLIF(ItemTranslations.title, ''), Items.title)` produces a result whose collation is
+    forced to `utf8mb4_bin` (MySQL cannot reconcile the two inputs). Plain `SELECT`ing it works, so it
+    looks fine — but **any** comparison, `ORDER BY`, `GROUP BY` or `DISTINCT` on that expression throws
+    **MySQL error 1267 "Illegal mix of collations"**. Reproduced against prod. It is a latent landmine:
+    the query ships green and fails the first time someone sorts or dedupes on it.
+  - **Do the fallback in PHP instead** — select `Items.title` and `ItemTranslations.title AS
+    translatedTitle` as **separate columns** and resolve (with a `trim`, so a whitespace-only
+    translation falls back) in code. This is the same choice the layer already makes on its read path
+    (`_Model::load()` per row, deliberately not a JOIN/COALESCE), so a hand-written query that needs a
+    translated value should follow the layer, not invent a SQL fallback. Worked example:
+    `_Model_Compass_SalesOrder::resolveItemTitle()` — see
+    [Compass Canada French order emails](../../../clients/compass-canada/features/french-order-email-localization.md).
+  - An ad-hoc **comparison** across the two (not a fallback) still needs an explicit `COLLATE` — pick
+    it after checking that specific client DB's collation, don't assume.
 - **GROUP BY gotcha on translatable joined fields (site 5).** The sibling joined-field code pushes each
   selected joined field into `$groupBy` under aggregates; the hidden PK column added for translation must
   **also** be pushed to `$groupBy` when `!empty($aggregateFunctionFields)`, or a non-English list request
@@ -264,6 +281,14 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 
 ## Change history
 
+- 2026-08-03 — Corrected and extended the **collation** gotcha (doc only): the source-field collation
+  **differs per client database** (`Client_CompassCanada.Items.title` = `utf8mb4_0900_ai_ci` vs
+  `Client_Compass.Items.title` = `utf8mb4_unicode_ci`, sidecar `utf8mb4_unicode_ci` in both, verified
+  prod + dev-sandbox), so a hardcoded `COLLATE utf8mb4_bin` is brittle. Added the concrete trap: a
+  `COALESCE(NULLIF(sidecar, ''), source)` expression resolves to `utf8mb4_bin` and `SELECT`s fine but
+  throws **MySQL 1267** on any comparison / `ORDER BY` / `GROUP BY` / `DISTINCT` — so hand-written
+  queries must select both columns and fall back in PHP, matching the layer's own `_Model::load()`
+  approach. Surfaced building the Compass Canada French order-email item block. (bala)
 - 2026-07-23 — Documented (no code change) that the layer is fully generic: `loadTranslationSidecar()`
   derives the source FK as "the sidecar FK that is not `languageId`" and loads by `(sourceFk, languageId)`
   via `_Model::load()`, so adding a new translatable field is **DB-metadata-only** (set

package/knowledge/INDEX.md

@@ -8,7 +8,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **worker** (Worker) — 18 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
-- **togadesk** (TOGa Desk) — 10 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
+- **togadesk** (TOGa Desk) — 11 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 42 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 43 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 21 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 5 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -56,6 +56,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 - **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
+- **Richmond University Medical Center** (`rumcsi`) → [clients/rumcsi/INDEX.md](clients/rumcsi/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 - **TOGA Technology** (`true`) → [clients/true/INDEX.md](clients/true/INDEX.md)
 - **Walmart Client Profile** (`walmart`) → [clients/walmart/INDEX.md](clients/walmart/INDEX.md)

package/knowledge/clients/compass-canada/INDEX.md

@@ -3,5 +3,6 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [French (fr-CA) Item Feature Translations (Compass Canada)](features/french-item-feature-translations.md) | 2.0 | Renders item **feature** text on the Compass Canada French storefront — feature names, feature-group headers (e.g. | _underscore/Model/Compass/Canada/Feature.php, _underscore/Model/Compass/Canada/ItemCategoryFeatureGroup.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, worker2/Worker/Etilize/ItemTranslations.php, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql, dbchanges2/Client_CompassCanada/2026-07-13 - FeatureAttributeCustomFields.sql, dbchanges2/Client_CompassCanada/2026-07-13 - DedupeItemFeaturesAndGroups.sql, dbchanges2/Client_CompassCanada/2026-07-13 - SeedFrenchFeatureTranslations.sql |
+| [French (fr-CA) Order Email Localization (Compass Canada)](features/french-order-email-localization.md) | 2.0 | Compass Canada order emails (order requested, manager-approval request, approved/rejected, in-transit, delivered, reminders) are sent in **each recipient's own | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/ApprovalDecision.php, library/app/client/compasscanada.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/compass_email_reminders.php, worker/crons/toga2/compasscanada/compass_cancel_pending_approval_orders.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_email_previews_prod.php |
 | [Grand & Toy ASN Import (Compass Canada)](features/grand-and-toy-asn-import.md) | 2.0 | Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. | worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/Canada/AdvanceShippingNotice.php, dbchanges2/Client_CompassCanada/ |
 | [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |  |

package/knowledge/clients/compass-canada/features/french-item-feature-translations.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-canada
 type: client-feature
 status: active
-updated: 2026-07-14
+updated: 2026-08-03
 owners: ["bala"]
 files:
   - _underscore/Model/Compass/Canada/Feature.php
@@ -74,8 +74,12 @@ Prod rollout is deferred until explicitly requested; the dev/beta build (beta DB
 
 ## Gotchas / known issues
 - **Sidecar/source collation mismatch.** Sidecar tables are `utf8mb4_unicode_ci` (matching
-  `ItemTranslations`); the source fields are `utf8mb4_0900_ai_ci`. Any ad-hoc query comparing across the
-  two needs `COLLATE utf8mb4_bin` or MySQL throws a collation-mismatch error.
+  `ItemTranslations`); in `Client_CompassCanada` the source fields are `utf8mb4_0900_ai_ci`, so an
+  ad-hoc query **comparing** across the two needs an explicit `COLLATE`. Two corrections since:
+  the source collation **differs per client DB** (so don't copy a `COLLATE utf8mb4_bin` literal
+  around), and a `COALESCE(NULLIF(sidecar, ''), source)` **fallback** expression must not be built
+  in SQL at all — it throws MySQL 1267 on any sort/compare. See the canonical gotcha on
+  [Language Translation Layer](../../../2.0/apps/api2/features/language-translation-layer.md).
 - **Etilize attribute ids of the form `34xxxxxx` are NOT corrupted** (false alarm resolved). A manual
   XML showing `32xxxxxx` came from a different Etilize view; the worker's Etilize endpoint returns
   `34xxxxxx` consistently for both backfill and import, so translations match. Do not "fix" them.
@@ -84,6 +88,8 @@ Prod rollout is deferred until explicitly requested; the dev/beta build (beta DB
   correct value is `1086408433`. Fixed by a single `UPDATE` — this was a data error, not a code bug.
 
 ## Change history
+- 2026-08-03 — Corrected the collation gotcha to point at the canonical (now per-client-aware) version
+  on the shared translation-layer doc; no code or rollout change. (bala)
 - 2026-07-13 — Built the fr-CA item-feature translation path end-to-end on dev/beta: shared feature
   sidecar tables + Core wiring, Compass-only `c_etilizeAttributeId` / `c_etilizeAttributeGroupId` custom
   fields, worker2 backfill + feature-translation import, dedup of ~7700 dup features / ~2100 dup groups,

package/knowledge/clients/compass-canada/features/french-order-email-localization.md

@@ -0,0 +1,246 @@
+---
+title: French (fr-CA) Order Email Localization (Compass Canada)
+framework: "2.0"
+project: _Underscore
+client: compass-canada
+type: client-feature
+status: active
+updated: 2026-08-03
+owners: ["bala"]
+files:
+  - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/ApprovalDecision.php
+  - library/app/client/compasscanada.php
+  - worker/crons/toga2/compasscanada/send_delivered_email.php
+  - worker/crons/toga2/compasscanada/compass_email_reminders.php
+  - worker/crons/toga2/compasscanada/compass_cancel_pending_approval_orders.php
+  - worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php
+  - worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php
+  - worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php
+  - worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php
+  - worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php
+  - worker/crons/toga2/compasscanada/workflow/test_email_previews_prod.php
+related:
+  - ../profile.md
+  - ../../compass-usa/features/approval-decision-flow.md
+  - ../../../2.0/apps/api2/features/language-translation-layer.md
+  - ../../../2.0/apps/_underscore/features/email-send-pipeline.md
+  - ../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md
+---
+
+## Summary
+
+Compass Canada order emails (order requested, manager-approval request, approved/rejected,
+in-transit, delivered, reminders) are sent in **each recipient's own language**. The French
+*wrapper* (subject + body template) was already selected correctly; what was broken was the
+**`{orderItems}` item block**, which was built from `Items.title` and never consulted the
+`ItemTranslations` sidecar, with hardcoded English `P/N:` / `Qty:` labels. So a French user
+received a French email containing English product names.
+
+Two things are load-bearing here and are easy to get wrong again:
+
+1. **Language is per recipient, not per order.** One order's requester and manager can have
+   different languages, so the item block must be rebuilt for each recipient.
+2. **These emails go out as iso-8859-1**, so French text must be HTML-entity-escaped with an
+   exact flag set (see *Encoding*) or the recipient sees mojibake or a blank product title.
+
+Spans both tiers: **2.0** (`_underscore` Compass models, order/approval interceptors) and
+**1.0** (`library` helper + the Compass Canada worker crons).
+
+## Key files / entry points
+
+**2.0 (`_underscore`)**
+- `_underscore/Model/Compass/SalesOrder.php`
+  - `buildOrderItemsHtmlForRecipient(&$api, $salesOrderId, ?int $recipientUserId)` — **the entry
+    point every email site should call.** Resolves that recipient's language first, then builds
+    the block.
+  - `buildOrderItemsHtml($salesOrderId, string $languageCode)` — the builder; conditionally
+    `LEFT JOIN`s `ItemTranslations` and selects `translatedTitle` as a **separate column**.
+  - `resolveItemTitle(?string $baseTitle, ?string $translatedTitle)` — PHP-side fallback
+    (trims, so a whitespace-only translation falls back to English).
+  - `resolveItemTranslationLanguageId(string $languageCode)` — `Languages.code → id`, returns
+    `0` for base English / unknown / lookup failure (0 means "no translation join").
+  - `resolveOrderItemLabels(string $languageCode)` — the label pair; constants
+    `ORDER_ITEM_LABEL_PART_NUMBER__FRENCH = 'N/P'`, `ORDER_ITEM_LABEL_QUANTITY__FRENCH = 'Qté'`
+    (stored as the `é` entity).
+- `_underscore/Model/Compass/ApprovalDecision.php`
+  - `resolveRecipientLanguageCode(&$api, ?int $userId)` — the single language resolver
+    (`UserGlobalSettings.settingId = 2` INNER JOIN `Languages ON code = value`). Returns `en`
+    for any non-`Compass_Canada` client, an empty `$userId`, no row, or a thrown query.
+  - `resolveEmailTemplateUuid(&$api, $templateKey, ?int $userId)` — picks the EN/FR template for
+    **that** recipient, off the same resolver.
+
+**1.0 (`library` + `worker`)**
+- `library/app/client/compasscanada.php` — `App_Client_CompassCanada::resolveUserLanguageCode(int $userId, string $databaseLink)`
+  plus `SETTING_ID__LANGUAGE = 2`, `LANGUAGE_CODE__BASE`/`__FRENCH_CANADA`, and
+  `isFrenchLanguageCode()` (prefix match on `fr`). **All 8 Compass Canada crons depend on this
+  class** — see *Deployment status*.
+- The crons that render or send a localized order email: `send_delivered_email.php`,
+  `compass_email_reminders.php`, `compass_cancel_pending_approval_orders.php`,
+  `update_salesorder_status_from_odp.php`, `workflow/3_…grand_and_toy.php`,
+  `workflow/4_import_…advance_shipping_notices.php`, and the two partial-email test scripts.
+
+## How it works
+
+1. **Resolve the recipient.** Each email site knows *who* it is emailing (requester = order
+   `contactId → Users`, manager = `ManagerDecision.assignedToUserId`, etc.) and passes that
+   `userId` in. 2.0 uses `resolveRecipientLanguageCode()`; the 1.0 crons use
+   `App_Client_CompassCanada::resolveUserLanguageCode()`.
+2. **Pick the template** for that language (`resolveEmailTemplateUuid`), and
+3. **Build the item block for that same recipient** (`buildOrderItemsHtmlForRecipient`). Steps 2
+   and 3 read the *same* resolver, so the wrapper language and the item language can never
+   disagree.
+4. **Titles:** for a non-base language the query `LEFT JOIN`s `ItemTranslations` on
+   `(itemId, languageId)` and selects `Items.title` **and** `ItemTranslations.title AS
+   translatedTitle` as two columns; `resolveItemTitle()` does the fallback in PHP. Do **not**
+   collapse this into a SQL `COALESCE` — see *Gotchas*.
+5. **Escape for the wire:** every item string is run through
+   `htmlentities($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false)` before it enters the HTML.
+6. `_Email::send()` queues a `PENDING` `Logs_CompassCanada.Email` row; the worker2
+   `Infrastructure/Email/Send` cron transmits it ~1 minute later. See
+   [2.0 Email Send Pipeline](../../../2.0/apps/_underscore/features/email-send-pipeline.md).
+
+### Encoding — why those exact `htmlentities` flags
+
+Compass emails are transmitted as **iso-8859-1**: neither `_Email::send()` nor
+`_Worker_Infrastructure_Email_Send::Run()` sets `$mailer->CharSet`, so PHPMailer's default
+applies. Any raw UTF-8 accent in the rendered body therefore arrives as mojibake. Entity-escaping
+the dynamic text sidesteps it — but both non-default arguments are required:
+
+- **`double_encode = false`** — in some environments `ItemTranslations.title` holds *literal HTML
+  entities as text*. Re-encoding those produced `é`, which the recipient reads as a
+  literal `é`. (Prod and dev-sandbox data is clean raw-accent UTF-8; a stale local dataset
+  had 71 of 215 rows entity-encoded. The flag makes the code correct under either data shape.)
+- **`ENT_SUBSTITUTE`** — passing explicit flags **drops** PHP 8.1's default `ENT_SUBSTITUTE`, and
+  `htmlentities()` returns an **empty string** on invalid UTF-8. Omitting it silently blanks the
+  whole product title.
+
+### Resilience — a language lookup must never break the caller
+
+`App_Query::execute()` (1.0, `library/app/query.php`) genuinely throws on any MySQL error, so this
+is a real failure mode, not a theoretical one. The guard is placed differently per tier, on purpose:
+
+- **1.0 crons:** each of the six call sites wraps `resolveUserLanguageCode()` in `try/catch`,
+  defaults to base English and `error_log`s. An unguarded throw there aborts the remaining orders
+  in that run.
+- **2.0:** the guard lives **inside** the two helpers (`ApprovalDecision::resolveRecipientLanguageCode()`
+  and `SalesOrder::resolveItemTranslationLanguageId()`) so every caller inherits it. These run
+  inside `postPost`/`postPut` interceptors — an unguarded throw would fail the customer's **order
+  submission** or an admin's **approval click**.
+
+### Prod-safe email preview harness
+
+`worker/crons/toga2/compasscanada/workflow/test_email_previews_prod.php` renders Order Requested,
+In Transit and Delivered in EN and FR **from real prod data**. Its safety design is worth copying
+for any future prod preview script:
+
+- a single hardcoded `TEST_RECIPIENT` (an internal `@togatech.com` address), **no CC/BCC**;
+- an **abort guard** that refuses to run if the recipient's domain is a client domain
+  (`compass-canada.com`, `compass-usa.com`, `compassdigital.io`);
+- `DRY_RUN` ships **true** — flip it to `false` only for the real send, then flip it back;
+- **SELECT-only**: no `cronInitialization`, no status/flag writes, reads off the read cluster;
+- fully self-contained, so it runs against prod **without** any undeployed code.
+- **Caveat:** a real send still inserts a row in `Logs_CompassCanada.Email` — that table is the
+  customer email audit log, so a preview send is visible there.
+
+## Data model
+
+- `UserGlobalSettings.settingId = 2` = `language`; values `en` / `fr-CA`. `Settings.id = 2` is the
+  `language` setting in **both** prod and dev-sandbox, so the hardcoded id is safe.
+- `Languages` (client DB) — `code` → `id`; fr-CA is `languageId 2` for Compass Canada.
+- `ItemTranslations` (client DB) — the item-text sidecar (`itemId`, `languageId`, `title`, …).
+  Shared layer: [Language Translation Layer](../../../2.0/apps/api2/features/language-translation-layer.md).
+- `EmailTemplates` (client DB) — 23 Compass Canada template UUIDs are hardcoded across the code
+  (EN + FR pairs). `Logs_CompassCanada.Email` is the send queue / audit log.
+
+## Gotchas / known issues
+
+- **Never build one item block per order.** A single shared `$orderItemsHtml` was reused for the
+  requester email *and* the manager email, so when their languages differed one of them got the
+  wrong language. Always call `buildOrderItemsHtmlForRecipient(..., $recipientUserId)` per
+  recipient.
+- **Pick the template from the ACTUAL recipient's language.** The 1.0 manager-approval reminder
+  cron (`compass_email_reminders.php`) chose the template from the **requester's** language even
+  though the email is sent to the **manager**. Same class of bug as the item block; now uses the
+  manager's language.
+- **Do not `COALESCE` the sidecar title with the source title in SQL.**
+  `COALESCE(NULLIF(ItemTranslations.title, ''), Items.title)` yields a `utf8mb4_bin` result (MySQL
+  cannot reconcile the two input collations). `SELECT`ing it works, but **any** comparison,
+  `ORDER BY`, `GROUP BY` or `DISTINCT` on that expression throws **MySQL 1267 "Illegal mix of
+  collations"** — reproduced against prod. Worse, the collations **differ per client database**
+  (`Client_CompassCanada.Items.title` = `utf8mb4_0900_ai_ci`, `Client_Compass.Items.title` =
+  `utf8mb4_unicode_ci`, `ItemTranslations.title` = `utf8mb4_unicode_ci` in both), so a hardcoded
+  `COLLATE` clause is brittle. Select the two columns separately and fall back in PHP — which is
+  also what the shared translation layer does (`_Model::load()`, deliberately not a JOIN/COALESCE).
+- **The `{role}` token appears TWICE in the French rejection template, with different grammar.**
+  The second occurrence is `par un <strong>{role} TechHub</strong>`, which is already correct. So
+  the missing elision must be fixed **in the template**, never by moving an article into the PHP
+  role constant — that would break the second slot (`par un l'admin TechHub`). The template now
+  reads `Refus&eacute;e par&nbsp;: {role}`, which is correct for both `admin` and `gestionnaire`.
+- **⚠ Do NOT "fix" the `approvalManagerId` subquery in `_Model_Compass_SalesOrder::postPut`.** It
+  reads the step-2 `ApprovalDecision.decidedByUserId` (not `assignedToUserId`), which is `NULL`
+  while the decision is pending — so `$managerEmail` stays empty and that arm never sends. That
+  looks like a bug but is exactly what **prevents duplicate manager emails**: the canonical
+  manager approval-request email is sent by `_Model_Compass_ApprovalDecision`, which correctly uses
+  `ManagerDecision.assignedToUserId`. Switching the column would send a second manager email on
+  every subsequent `SalesOrders` PUT. Evidence: prod `Logs_CompassCanada.Email` held 461 emails
+  over ~3 weeks including 113 manager-approval emails, with **zero** duplicate `(to, subject)`
+  pairs. Also recorded on
+  [Approval-Decision Flow](../../compass-usa/features/approval-decision-flow.md).
+- **French template bodies must be pure ASCII.** Under the iso-8859-1 send, a raw non-breaking
+  space in a stored template body renders as mojibake. Eight Compass Canada French templates
+  carried a stray `Â` (U+00C2) immediately followed by a raw NBSP (U+00A0) before the colon in
+  `"Commande :"` (10 occurrences); replacing that 4-byte sequence with the `&nbsp;` entity makes
+  those bodies ASCII. Applied to prod **and** dev-sandbox. Check for this whenever a French
+  template is authored or pasted from Word/Docs.
+- **Compass US is provably unaffected.** `Client_Compass` has **0** `ItemTranslations` rows and only
+  `en` in `Languages`, and every language branch is gated on
+  `clientIdentifier === 'Compass_Canada'`, so the French path cannot alter a US email.
+
+## Verified state (2026-08-03, read-only checks)
+
+- All **23** Compass Canada template UUIDs hardcoded in the code exist and are `isActive` in **prod
+  and dev-sandbox**; all **8** Compass US ones exist and are active in prod.
+- Prod Compass Canada: **220** fr-CA `ItemTranslations` rows and **100% coverage** of every item ever
+  ordered (1178 item rows across 699 orders, zero fallbacks). dev-sandbox: 215 rows, 985 item rows /
+  585 orders, zero fallbacks.
+- Verification run: a 20-scenario local regression suite (20/20) against a prod-shaped dataset, ~20
+  read-only prod + dev-sandbox data checks, and an end-to-end render into the local email queue
+  confirming **zero raw UTF-8 bytes and zero double-encoded entities**.
+
+## Deployment status (open risk)
+
+**Not deployed.** The code is committed on branch **`TRUE-80543`** in `_underscore` and `worker`.
+The `library` change (`App_Client_CompassCanada`) is still **UNCOMMITTED on `_production`** and has
+**no `TRUE-80543` branch** — and **all 8 worker crons depend on that class**, so merging the worker
+PR without the library change would **fatal** every Compass Canada cron. Ship `library` first (or in
+the same release). The `EmailTemplates` data fixes (stray `Â`+NBSP, the `{role}` elision) are
+already applied to prod and dev-sandbox.
+
+## Change history
+
+- 2026-08-03 — Localized the Compass Canada `{orderItems}` email block: titles now come from the
+  `ItemTranslations` sidecar (two-column select + PHP `resolveItemTitle()` fallback, never a
+  mixed-collation SQL `COALESCE`) and the `P/N:`/`Qty:` labels are translated. Made language
+  **per recipient** via `buildOrderItemsHtmlForRecipient()` / `resolveRecipientLanguageCode()`
+  (one shared block had been reused for requester + manager), and fixed the 1.0 manager-reminder
+  cron choosing the template from the requester's instead of the manager's language. Escaped item
+  text with `htmlentities(..., ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false)` for the iso-8859-1
+  send. Added try/catch fallback-to-English around every language lookup (per call site in the 1.0
+  crons, inside the helpers in 2.0). Fixed 8 French `EmailTemplates` bodies (stray `Â` + raw NBSP →
+  `&nbsp;`) and the rejection template's `Refus&eacute;e par&nbsp;: {role}` elision in prod +
+  dev-sandbox. Built the prod-safe `test_email_previews_prod.php` preview harness. Deliberately left
+  the `postPut` `approvalManagerId` subquery alone (it prevents duplicate manager emails).
+  TRUE-80543, not yet deployed. (bala)
+
+## Related docs
+
+- [Compass Canada profile](../profile.md)
+- [Compass Approval-Decision Flow](../../compass-usa/features/approval-decision-flow.md) — the
+  shared parent that sends the approval/notification emails and resolves EN/FR templates.
+- [Language Translation Layer](../../../2.0/apps/api2/features/language-translation-layer.md) — the
+  `ItemTranslations` sidecar and its PHP-side fallback rule.
+- [2.0 Email Send Pipeline](../../../2.0/apps/_underscore/features/email-send-pipeline.md) — the
+  queue + Send worker, and the missing `CharSet` that makes these emails iso-8859-1.
+- [Compass Partial In-Transit & Delivered Emails](../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md)
+  — the 1.0 crons whose item rows this localizes.

package/knowledge/clients/compass-canada/profile.md

@@ -10,16 +10,18 @@ apps:
   - worker
   - worker2
   - dbchanges2
+  - library
 project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-07-23
+updated: 2026-08-03
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - ../compass-usa/profile.md
   - ../compass-usa/features/approval-decision-flow.md
+  - features/french-order-email-localization.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md
@@ -34,7 +36,10 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
 - **2.0:** `_underscore` backend, prod schema `Client_CompassCanada` (archive
   `Archive_CompassCanada`, logs `Logs_CompassCanada`). Client-specific model overrides live
   under `_underscore/Model/Compass/Canada/` (a sub-client of the Compass model tree).
-- **1.0:** worker crons under `worker/crons/toga2/compasscanada/`.
+- **1.0:** worker crons under `worker/crons/toga2/compasscanada/`, plus the shared client helper
+  `App_Client_CompassCanada` in **`library`** (`library/app/client/compasscanada.php`) — language
+  resolution + client constants that all 8 Canada crons depend on. `library` is in `apps` for that
+  reason.
 
 ## Vendors & integrations
 - **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
@@ -59,7 +64,10 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   client role 1, id-agnostic + NOT-EXISTS-guarded, beta only). Exposes surfaces to role 1 only, vs
   Compass USA's 1/3/4. See [Surface Resolver](../../2.0/apps/_underscore/features/surface-resolver.md).
 - Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
-  facing emails are sent in EN or FR accordingly.
+  facing emails are sent in EN or FR accordingly — **per recipient**, including the `{orderItems}`
+  block, and entity-escaped because the send is iso-8859-1. See
+  [French Order Email Localization](features/french-order-email-localization.md). French
+  `EmailTemplates` bodies must be pure ASCII.
 - **Approval decisions use the shared Compass parent.** `_Model_Compass_Canada_ApprovalDecision`
   is an empty subclass of `_Model_Compass_ApprovalDecision`; the entire approval/notification/
   manager-reassignment/VIP-auto-approve flow lives in the parent and branches at runtime on
@@ -87,4 +95,7 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   Compass Canada's own IF lifecycle stages (picked/packed/shipped) + shipped backfill are seeded by
   `dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql`.
   See [IF stage lifecycle & order status](../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md).
+- **Item titles in customer emails** come from the `ItemTranslations` sidecar (prod: 220 fr-CA rows,
+  100% coverage of every item ever ordered). Resolve the English/translated fallback **in PHP**, never
+  as a SQL `COALESCE` — the two columns' collations differ and differ *per client DB*.
 - Related: [Compass USA](../compass-usa/profile.md).

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-23
+updated: 2026-08-03
 owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
@@ -16,6 +16,7 @@ files:
 related:
   - mr-ma-order-approval-and-status.md
   - ../../compass-canada/profile.md
+  - ../../compass-canada/features/french-order-email-localization.md
   - ../../../2.0/apps/_underscore/features/email-template-sending.md
 ---
 
@@ -47,9 +48,16 @@ Compass US and Compass Canada resolve to different model classes at request time
 (`_Model_Compass_Usa_ApprovalDecision` / `_Model_Compass_Canada_ApprovalDecision`), but both are
 empty shells extending `_Model_Compass_ApprovalDecision`. All behavior is inherited. Where the two
 tenants differ, the **parent** branches on `$api->client->clientIdentifier === 'Compass_Canada'`:
-- **Email-template resolution** — `resolveEmailTemplateUuid()` picks the tenant's template UUID.
-- **EN/FR localization** — user language is read from `UserGlobalSettings` (`settingId = 2`;
-  `en` / `fr-CA`) so Canadian notifications go out in the recipient's language.
+- **Email-template resolution** — `resolveEmailTemplateUuid(&$api, $templateKey, ?int $userId)` picks
+  the tenant's template UUID, **for that recipient's language**.
+- **EN/FR localization** — one resolver,
+  `resolveRecipientLanguageCode(&$api, ?int $userId)`, reads the language from `UserGlobalSettings`
+  (`settingId = 2`; `en` / `fr-CA`) and returns `en` for any non-Canada client, an empty `$userId`,
+  no row, or a thrown query (it catches + `error_log`s, because it runs inside an interceptor). The
+  template UUID **and** the `{orderItems}` block
+  (`_Model_Compass_SalesOrder::buildOrderItemsHtmlForRecipient()`) both read this same resolver, so
+  wrapper language and item language can never disagree — see
+  [Compass Canada French order emails](../../compass-canada/features/french-order-email-localization.md).
 - **Web-link host resolution** — `_Model_Compass_SalesOrder::resolveSupplyHost()` /
   `resolveCommerceHost()` pick the tenant's supply/commerce domain for the links embedded in
   approval and order-status emails (see below).
@@ -138,6 +146,19 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   requester/new-manager guards.
 - **Don't put tenant behavior in the empty subclasses.** `Usa`/`Canada` `ApprovalDecision` are
   intentionally empty; the tenant branch lives in the parent on `clientIdentifier`.
+- **⚠ DO NOT "fix" the `approvalManagerId` subquery in `_Model_Compass_SalesOrder::postPut`.** It
+  reads the step-2 `ApprovalDecision.decidedByUserId` (aliased `approvalManagerId`) rather than
+  `assignedToUserId`. Because `decidedByUserId` is `NULL` while a step-2 decision is still pending,
+  `$managerEmail` stays empty and that manager arm **never sends**. It reads like an obvious bug — it
+  is in fact what **prevents duplicate manager emails**: the canonical manager approval-request email
+  is sent by `_Model_Compass_ApprovalDecision`, which correctly uses `ManagerDecision.assignedToUserId`.
+  Switching the column would fire a **second** manager email on every subsequent `SalesOrders` PUT.
+  Evidence (2026-08-03): prod `Logs_CompassCanada.Email` held 461 emails over ~3 weeks, including 113
+  manager-approval emails, with **zero** duplicate `(to, subject)` pairs. If this arm ever *should*
+  send, remove it or gate it explicitly — don't change the column.
+- **Localize per recipient, not per order.** An order's requester and manager can have different
+  languages. Anything that builds shared email HTML once and reuses it for both recipients will send
+  one of them the wrong language (this was a live bug in the `{orderItems}` block, fixed 2026-08-03).
 - **Never hardcode the web host in email links.** The email links previously used string literals
   `compass.togasupply.com` / `compass.togacommerce.com` in the parent classes. Because the tenant
   subclasses are empty, **Compass Canada orders inherited the US links** and sent Canada
@@ -148,6 +169,16 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   approve as manager on his behalf. (Fixed 2026-07-23.)
 
 ## Change history
+- 2026-08-03 — Recorded that the `postPut` `approvalManagerId` subquery reading
+  `ApprovalDecision.decidedByUserId` (not `assignedToUserId`) is **deliberately left alone** — it is
+  what stops a duplicate manager email on every subsequent `SalesOrders` PUT (verified: 113
+  manager-approval emails in 3 weeks of prod `Logs_CompassCanada.Email`, zero duplicate
+  `(to, subject)` pairs). Also documented the single per-recipient language resolver
+  `resolveRecipientLanguageCode(&$api, ?int $userId)` (interceptor-safe: catches and defaults to
+  `en`) that now drives **both** the template UUID and the `{orderItems}` block, and the
+  localize-per-recipient rule. Compass US behavior unchanged (all language branches are gated on
+  `clientIdentifier === 'Compass_Canada'`, and `Client_Compass` has no translations and only `en` in
+  `Languages`). TRUE-80543. (bala)
 - 2026-07-23 — Fixed Compass approval/status **email links** being hardcoded to the US domains
   (`compass.togasupply.com` / `compass.togacommerce.com`) in the parent classes, so Compass Canada
   orders (empty `Canada` subclass) inherited US links and Canada recipients were sent to a site

package/knowledge/clients/rumcsi/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Richmond University Medical Center `rumcsi`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Richmond University Medical Center](profile.md) | 1.0 | Richmond University Medical Center (**RUMCSI**) is a framework **1.0** client served by **TOGa Desk** (staff/analyst side) and **TOGa View** (client portal). |  |

package/knowledge/clients/rumcsi/profile.md

@@ -0,0 +1,44 @@
+---
+title: "Richmond University Medical Center"
+framework: "1.0"
+apps:
+  - togadesk
+  - togaview
+  - library
+project: TOGa Desk
+client: rumcsi
+type: profile
+status: active
+updated: 2026-08-04
+owners: ["mhammontree"]
+files: []
+related:
+  - ../../1.0/apps/togadesk/features/per-client-host-restriction.md
+  - ../../1.0/apps/togadesk/architecture.md
+  - ../../1.0/apps/togaview/architecture.md
+---
+
+## Summary
+
+Richmond University Medical Center (**RUMCSI**) is a framework **1.0** client served by
+**TOGa Desk** (staff/analyst side) and **TOGa View** (client portal). Its TOGa Desk
+`clients.clientId` is **146**, exposed in code as the constant `CLIENT_RUMCSI` in
+`desk/includes/functions.php`.
+
+## Platform footprint
+
+- **Branded per-client URL.** RUMCSI is one of the clients gated by TOGa Desk's host-based
+  restriction: `rumcsi.togadesk.togatech.com` is already a case in `getRestrictedClient()`, which
+  returns `CLIENT_RUMCSI` and drives `restrictByClient()` nav/menu and ticket-datatable scoping.
+  See [Per-client hostname restriction](../../1.0/apps/togadesk/features/per-client-host-restriction.md)
+  for the full add-a-hostname checklist (cert scope, host-scoped sessions, hardcoded legacy domains).
+- **TOGa View SAML.** `togaview/_/app/framework.php` has a RUMCSI-specific host branch that selects
+  branding (`$_SESSION['stylePath']`) and the SAML login path — an unregistered togaview hostname
+  falls through to default branding and skips SAML.
+- **Hardcoded client-ID branching.** RUMCSI appears in TOGa Desk's hardcoded client-ID branching
+  (`central` dispatch, `tickets/add`) — verify the RUMCSI arm before changing shared logic.
+
+## Change history
+
+- 2026-08-04 — Client profile created during the TRUE-80139 read-only review of the RUMCSI branded
+  TOGa Desk URL. (mhammontree)

package/package.json

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