toga-ai 1.0.418 → 1.0.419

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

@@ -22,7 +22,7 @@
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
-| [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22a - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22b - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22a - PersonaTranslationsFrench.sql |
+| [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |

package/knowledge/2.0/apps/_underscore/features/persona-name-translation.md

@@ -6,14 +6,15 @@ project: _Underscore
 client: shared
 type: feature
 status: draft
-updated: 2026-07-22
-owners: ["tcox"]
+updated: 2026-07-23
+owners: ["tcox", "bala"]
 files:
   - _underscore/Model/Client/PersonaTranslation.php
-  - dbchanges2/Client/2026-07-22a - PersonaTranslations.sql
+  - dbchanges2/Client/2026-07-22b - PersonaTranslations.sql
   - dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql
-  - dbchanges2/Client/2026-07-22b - PersonaTranslationsAcl.sql
-  - dbchanges2/Client_CompassCanada/2026-07-22a - PersonaTranslationsFrench.sql
+  - dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql
+  - dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql
+  - toga2-commerce/src/pages/Account/view/MySettingsView.tsx
 related:
   - ./assortment-name-translation.md
   - ../../api2/features/language-translation-layer.md
@@ -31,25 +32,28 @@ pattern. English stays in `Personas.name`; the sidecar holds only non-English ov
 English fallback). Because the translation layer is fully metadata-driven (see
 [Language Translation Layer](../../api2/features/language-translation-layer.md)), wiring this up
 required **no api2 PHP logic change**: `GET /personas` names flow through `getTranslatedFieldValue`
-at the top-level serialization sites. Compass Canada's French (fr-CA) persona names are the first
-(and so far only) intended consumer.
-
-> **Status (2026-07-22): DRAFTED / DEFERRED — not committed, not run.** All five artifacts live in
-> local working trees only; the developer explicitly deferred the backend/DB changes this session.
-> `sql-reviewer` verdict was **SAFE TO MERGE (0 critical)**. See **Rollout / pre-run verification**
-> before executing — several ids and row-matches are *assumed* and must be confirmed against the live
-> DB first. DB verification could not be completed this session: all RDS endpoints (prod readers,
-> global, sandbox) are VPC-restricted from the dev machine — needs VPN or the claude.ai TOGa DB
-> connector.
+at the top-level serialization sites. Only `Personas.name` is translatable — `Personas.number` is a
+code, not display text, and is left untranslated. Compass Canada's French (fr-CA) persona names are
+the first (and so far only) intended consumer.
+
+> **Status (2026-07-23): backend artifacts FINALIZED (ids verified against prod), NOT yet run;
+> fr-CA seed values PENDING business sign-off.** The Core ids were re-based this session against a
+> confirmed prod snapshot — `MAX(Core.Records) = 346`, `MAX(Core.RecordFields) = 2462` at capture
+> time — and the sidecar now takes **Record 348 / RecordFields 2469–2473**, following the
+> `NotificationTranslations` sidecar (347 / 2463–2468) that landed just ahead of it. The five
+> artifacts still live in working trees (not deployed). The French persona names are **proposed
+> translations that still need Compass business sign-off** — brand/sector proper nouns (Eurest,
+> Chartwells, ESFM, Foodbuy) must be confirmed before the seed is run. Deploy order:
+> **table → record → acl → French backfill.**
 
 ## Key files / entry points
 
 - `_underscore/Model/Client/PersonaTranslation.php` — the sidecar model
   (`_Model_Client_PersonaTranslation`), a declarative copy of `AssortmentTranslation.php`.
-- `dbchanges2/Client/2026-07-22a - PersonaTranslations.sql` — the sidecar table (every client DB).
+- `dbchanges2/Client/2026-07-22b - PersonaTranslations.sql` — the sidecar table (every client DB).
 - `dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql` — Core record + fields + the field link.
-- `dbchanges2/Client/2026-07-22b - PersonaTranslationsAcl.sql` — Base-role ACL grant (every client DB).
-- `dbchanges2/Client_CompassCanada/2026-07-22a - PersonaTranslationsFrench.sql` — fr-CA seed.
+- `dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql` — Base-role ACL grant (every client DB).
+- `dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql` — fr-CA seed.
 
 ## How it works
 
@@ -64,9 +68,12 @@ The mechanism itself is the data-driven translation layer documented in
 2. **Model.** `_Model_Client_PersonaTranslation` is the ORM model for the sidecar (declarative copy
    of `AssortmentTranslation.php`).
 3. **Core record registration.** `Core.Records` registers route `persona-translations` →
-   model `\_Model_Client_PersonaTranslation` at record **id 346** (assumed next-free), with
-   `Core.RecordFields` rows **2458–2462** for `id`, `uuid`, `personaId`, `languageId`, `name`, and an
-   `UPDATE ... JOIN` that sets `translationRecordFieldId` on the `Personas.name` RecordField.
+   model `\_Model_Client_PersonaTranslation` at record **id 348** (verified next-free after
+   `NotificationTranslations` = 347), with `Core.RecordFields` rows **2469–2473** for `id`, `uuid`,
+   `personaId`, `languageId`, `name`, and an `UPDATE ... JOIN` that sets `translationRecordFieldId`
+   on the `Personas.name` RecordField (source route `personas`, field `name`). These ids are
+   **env-specific** — they follow prod's confirmed maxima at capture time (`Records` 346 /
+   `RecordFields` 2462) and the intervening `NotificationTranslations` record (347 / 2463–2468).
 4. **The field link (what makes it translate automatically).** The translatable `Personas.name`
    RecordField gets its `Core.RecordFields.translationRecordFieldId` set to the sidecar's `name`
    RecordField. The api2 V2 layer reads `translationRecordFieldId` for every field and automatically
@@ -76,57 +83,84 @@ The mechanism itself is the data-driven translation layer documented in
    (Contrast the assortment sidecar, which additionally needed a `join=`/joined-select fix — persona
    names are not surfaced via a joined-select read path, so that 5th-serialization-site concern does
    not apply here.)
-5. **ACL.** A full ACL chain grants the **Base** role read/write on the new record. Because the
-   record's `aclDatabase = 'CLIENT'`, the grant lives in each client DB — see
-   [ACL Permission Chain](./acl-permission-chain.md).
+5. **ACL.** A full ACL chain grants the **Base** role CRUD on the new record (field perms: `id`/`uuid`
+   read-only, the rest writable). Because the record's `aclDatabase = 'CLIENT'`, the grant lives in
+   each client DB — see [ACL Permission Chain](./acl-permission-chain.md). The chain binds
+   `AclLogicGroups`/`AclLogicGroupExpressions` by **UUID** rather than `MAX(id)` — the newer, safer
+   pattern that avoids cross-wiring when ACL inserts are interleaved.
 
 ## Data model
 
 - `Client.PersonaTranslations` — `id, uuid, dtCreated, dtUpdated, personaId (FK Personas),
   languageId (FK Languages), name`; `UNIQUE(personaId, languageId)`; `utf8mb4_unicode_ci`. English
   stays in `Personas.name`; sidecar holds only non-English overlays (null → English fallback).
-- `Core.Records` **346** (assumed) = `persona-translations` (`aclDatabase = 'CLIENT'`);
-  `Core.RecordFields` **2458–2462** (assumed) for id/uuid/personaId/languageId/name.
+- `Core.Records` **348** = `persona-translations` (`aclDatabase = 'CLIENT'`);
+  `Core.RecordFields` **2469–2473** for id/uuid/personaId/languageId/name (env-specific — follow
+  `NotificationTranslations` 347 / 2463–2468, which follows prod max `Records` 346 / `RecordFields` 2462).
 - `Personas.name` RecordField → `translationRecordFieldId` points at the sidecar `name` RecordField.
+  Only `Personas.name` is translatable (`Personas.number` is a code, left as-is).
 
 ## Rollout / pre-run verification (do this BEFORE executing)
 
-The ids and several row-matches in these migrations are **assumptions from a repo scan**, not
-confirmed against the live DB. Before running:
-
-1. **Verify next-free Core ids.** Confirm live `MAX(Core.Records.id) = 345` and
-   `MAX(Core.RecordFields.id) = 2457` so that 346 and 2458–2462 are actually free. (Consistent with
-   the feature-translation work, which used Records 343/344/345 + RecordFields 2442–2457.) If the live
-   maxima differ, renumber the record/field ids in `PersonaTranslationsRecord.sql` and the ACL SQL.
-2. **Verify the 3 out-of-band personas.** The fr-CA seed matches 30 personas by known `Personas.uuid`
-   (from the 2025-12-19 Personas seed), plus **3 personas matched by exact English name** — *Admin
-   Canada*, *MacBooks*, *Managers/VIPs* — that exist only in the live DB (no repo migration). Confirm
-   those three exist with those exact names and that `Personas` has **no duplicate names** (the
-   name-match would double-seed otherwise).
-3. **Confirm the glossary is complete.** The business-glossary screenshot the fr-CA text came from was
-   cut off after "Managers/VIPs → Gestionnaires/VIP" — confirm there are no additional personas below
-   that line before treating the seed as complete.
+Before running:
+
+1. **Core ids are re-based (env-specific).** Ids were confirmed against a prod snapshot this session —
+   `MAX(Core.Records) = 346`, `MAX(Core.RecordFields) = 2462` — so the sidecar takes Record **348** /
+   RecordFields **2469–2473**, immediately after the `NotificationTranslations` sidecar (347 /
+   2463–2468). If the target env's maxima differ, renumber the record/field ids in
+   `PersonaTranslationsRecord.sql` and the ACL SQL.
+2. **French names need Compass business sign-off.** The fr-CA seed backfills **all 34 Canada personas**,
+   but the French text is **proposed**, not approved. Brand/sector proper nouns (Eurest, Chartwells,
+   ESFM, Foodbuy) in particular must be confirmed with Compass before running the backfill.
+3. **Confirm no duplicate persona names** if any rows are matched by name rather than uuid (a name-match
+   would double-seed).
 
 fr-CA is `languageId 2` (same as the item-feature translations — see the Compass Canada profile and
 `UserGlobalSettings.settingId = 2`).
 
 ## Frontend consumption (toga2-commerce)
 
-For the translated names to appear on the storefront **without a full reload** after a language
-switch, the persona React Query caches must be language-sensitive. The persona query keys
-`userPersonaDataOnLogin` and `userPersonaDataOnViewAs` were added to `LANGUAGE_SENSITIVE_QUERY_KEYS`
-in `src/queries/queries.ts` (toga2-commerce) so they refetch on language change — see
-[Client Fields](../../toga2-commerce/features/client-fields.md). This frontend change shipped this
-session; the backend above did not.
+Getting the translated name to appear on the storefront **without a full reload** after a language
+switch is subtler than cache-invalidation alone. The displayed persona name comes from
+`user._personaOptions` in the **persisted Zustand `user` store** (localStorage), which is populated
+**once at login** (`getLoginSettings` → `NavIconList`; `LoginSettingsSwitcher` only fetches
+`if (!user._personaOptions)`) and is **not** driven by a live React Query. So adding the persona
+query keys to `LANGUAGE_SENSITIVE_QUERY_KEYS` in `src/queries/queries.ts` is **not sufficient** —
+those keys don't exist for `_personaOptions`, and invalidation cannot refresh a value that no live
+query owns. (Before the fix, switching language in My Settings left the old-language persona name
+on screen until a full re-login.)
+
+**The fix (surgical, language-branch only, safe for all clients).** In
+`src/pages/Account/view/MySettingsView.tsx`, `saveAllChanges` `case 'language'`: after
+`invalidateLanguageSensitiveQueries` and after `refreshAuthTokens` (so the new JWT carries the new
+`id.language`), explicitly **refetch `fetchUserPersona(user)`** with the refreshed token and assign
+`userUpdates._personaOptions` (applied by the existing `setUser` spread). The refetch is wrapped in
+its **own try/catch** so a persona-refresh failure never rolls back the just-saved language. The
+canonical `_personaOptions` shape is `{ number, name }[]` (`globalTypes.ts`).
+
+The **same latent gap still exists** in `components/LoginSettingsSwitcher/LoginSettingsSwitcher.tsx`
+(the login-modal switcher), left unchanged this session by request. See
+[Client Fields](../../toga2-commerce/features/client-fields.md) for the storefront language-switch
+machinery. This frontend fix shipped this session; the backend sidecar above did not.
 
 ## Client variations
 
-- **Compass Canada** is the intended first consumer: `2026-07-22a - PersonaTranslationsFrench.sql`
-  seeds fr-CA names for 33 personas (30 by uuid + 3 by exact English name). Deferred / not yet run —
-  see the Compass Canada profile.
+- **Compass Canada** is the intended first consumer: `2026-07-22 - PersonaTranslationsFrench.sql`
+  seeds fr-CA names for all **34** Canada personas. Not yet run; the French text is proposed and
+  needs Compass business sign-off — see the Compass Canada profile.
 
 ## Change history
 
+- 2026-07-23 — Re-based the Core ids against a confirmed prod snapshot (max `Records` 346 /
+  `RecordFields` 2462): the sidecar now takes Record **348** / RecordFields **2469–2473**, following
+  the `NotificationTranslations` sidecar (347 / 2463–2468). ACL chain now binds
+  `AclLogicGroups`/`AclLogicGroupExpressions` by **UUID** (not `MAX(id)`). fr-CA seed expanded to all
+  **34** Canada personas (French text still **proposed**, needs Compass sign-off). Fixed the
+  storefront language switch: `_personaOptions` lives in the persisted Zustand `user` store (not a
+  live React Query), so `LANGUAGE_SENSITIVE_QUERY_KEYS` alone can't refresh it — `MySettingsView.tsx`
+  `case 'language'` now explicitly refetches `fetchUserPersona(user)` with the refreshed JWT (own
+  try/catch). The `LoginSettingsSwitcher` modal has the same gap, left unchanged by request. Backend
+  sidecar still not run. (bala)
 - 2026-07-22 — Drafted the `PersonaTranslations` sidecar end-to-end following the
   `AssortmentTranslations` pattern exactly: sidecar table + `_Model_Client_PersonaTranslation` model +
   Core record 346 / RecordFields 2458–2462 registration + `translationRecordFieldId` link on

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

@@ -137,12 +137,37 @@ no extra model load, output unchanged). This is why a metadata-only sidecar (e.g
 still needed an api2 code change to translate on the `join=` read path even though FK/top-level reads
 worked with no code change.
 
+**Sidecar source-FK derivation.** `loadTranslationSidecar()` figures out which sidecar column holds
+the source row's id **generically** — it takes the sidecar record's FK field that is **not**
+`languageId` as the source FK, then loads the sidecar row by `(sourceFkField = sourceId, languageId)`
+via `_Model::load()` (no JOIN), cached per source row. This is why a new sidecar needs no per-table
+wiring in api2: as long as the sidecar has exactly `{sourceFkId, languageId, <translated fields>}`,
+the layer discovers the source FK from metadata.
+
 **Write path.** On create and update, `extractTranslationWrites()` pulls translatable fields out of
 the write set for a non-base language (so the English source is never overwritten), and after the
 source row saves, `saveTranslationWrites()` upserts them into the sidecar for the current language.
 Nested-child translatable writes are NOT auto-redirected — use the dedicated `/v2/item-translations`
 endpoint for those.
 
+**Adding a new translatable field is DB-metadata-only (no api2 edit) for top-level/FK reads.** The
+whole layer is data-driven, so making a new field translatable requires **no PHP change in api2** when
+the field is emitted at a top-level or FK serialization site (only the `join=`/joined-select read path,
+site 5, ever needed a code change — see the joined-select note above). The recipe:
+
+1. Set `Core.RecordFields.translationRecordFieldId` on the source field's RecordField to point at the
+   sidecar's translated-field RecordField (an `UPDATE … JOIN` matching source route + field name).
+2. Create the `<Entity>Translations` sidecar table (`{ …, <entity>Id FK, languageId FK, <fields> }`,
+   `UNIQUE(<entity>Id, languageId)`) and its `_Model_Client_<Entity>Translation` model.
+3. Register the Core `Record` + `RecordFields` for the sidecar route.
+4. Grant the Base-role ACL chain on the new record (client DB).
+5. Backfill the non-English overlay rows.
+
+`getTranslatedFieldValue()`/`shouldTranslate()` then substitute the sidecar value on read for
+non-base languages automatically; English/API/public traffic is byte-identical. The
+[Persona Name Translation](../../_underscore/features/persona-name-translation.md) sidecar is a
+worked example of this recipe (and confirmed it needed **zero** api2 changes).
+
 ## Data model
 
 - `Client.ItemTranslations` — `id, uuid, dtCreated, dtUpdated, itemId (FK Items, RESTRICT),
@@ -239,6 +264,12 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 
 ## Change history
 
+- 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
+  `translationRecordFieldId` + sidecar table/model + Core record/fields + ACL + backfill) with **no api2
+  edit** for top-level/FK reads — only the `join=` read path (site 5) ever needed code. Confirmed via the
+  `PersonaTranslations` sidecar, which required zero api2 changes. (bala)
 - 2026-07-21 — Wired translation into the **joined-select-fields** path (the 5th and final read-path
   serialization site) in `V2.php` `processRoutePairs` (joined-select SQL build ~L3700-3800, serialization
   ~L4038-4060). `join=` fields (e.g. `Assortments.name`) previously copied the raw SQL column straight into
@@ -285,3 +316,5 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 
 - [ACL Permission Chain](./acl-permission-chain.md)
 - [api2 Architecture](../architecture.md)
+- [Persona Name Translation](../../_underscore/features/persona-name-translation.md) — metadata-only
+  worked example (no api2 change).

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -6,7 +6,7 @@
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
-| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts |
+| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |

package/knowledge/2.0/apps/toga2-commerce/features/client-fields.md

@@ -6,9 +6,10 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-22
-owners: ["apeterson", "tcox"]
+updated: 2026-07-23
+owners: ["apeterson", "tcox", "bala"]
 files:
+  - src/pages/Account/view/MySettingsView.tsx
   - src/fieldsConfig/index.ts
   - src/fieldsConfig/getClientLoginFields.ts
   - src/fieldsConfig/clientFields/COMPASS.json
@@ -292,9 +293,21 @@ via the [Persona Name Translation](../_underscore/features/persona-name-translat
 cached by React Query and does **not** refetch on a language switch by default. `src/queries/queries.ts`
 keeps a `LANGUAGE_SENSITIVE_QUERY_KEYS` allow-list of query keys to invalidate/refetch when the
 language changes. The persona query keys `userPersonaDataOnLogin` and `userPersonaDataOnViewAs` were
-added to it 2026-07-22 so translated persona names appear after a language switch without a full page
-reload. When you add a new API-driven string that must respond to the language switcher, add its query
-key here.
+added to it 2026-07-22. When you add a new API-driven string that must respond to the language
+switcher, add its query key here.
+
+**Caveat — invalidation only refreshes values a live query actually owns.** This allow-list is
+necessary but **not sufficient** for the persona *name*: the displayed name comes from
+`user._personaOptions` in the **persisted Zustand `user` store** (localStorage), populated once at
+login and **not** driven by a live React Query — so no key in `LANGUAGE_SENSITIVE_QUERY_KEYS` refreshes
+it. Switching language must **explicitly refetch** the persona list:
+`src/pages/Account/view/MySettingsView.tsx` `saveAllChanges` `case 'language'` now calls
+`fetchUserPersona(user)` (with the post-`refreshAuthTokens` JWT) and reassigns `_personaOptions` via
+`setUser`, in its own try/catch so a persona-refetch failure can't roll back the saved language. The
+login-modal `LoginSettingsSwitcher.tsx` still has this gap. Before this fix the persona name stayed in
+the old language until a full re-login. Takeaway: for translated data held in a **persisted store**
+rather than a live query, a `LANGUAGE_SENSITIVE_QUERY_KEYS` entry does nothing — refetch it explicitly
+on switch.
 
 ## Gotchas
 
@@ -326,6 +339,13 @@ key here.
   slip. Do not "reconcile" the two lists.
 
 ## Change history
+- 2026-07-23 — **Correction:** clarified that `LANGUAGE_SENSITIVE_QUERY_KEYS` alone does **not**
+  refresh the persona name on language switch — `user._personaOptions` lives in the persisted Zustand
+  `user` store (populated once at login), not a live React Query, so nothing in the allow-list owns it.
+  `MySettingsView.tsx` `case 'language'` now explicitly refetches `fetchUserPersona(user)` with the
+  refreshed JWT and reassigns `_personaOptions` (own try/catch); the `LoginSettingsSwitcher` modal
+  still has the gap. General rule recorded: translated data in a persisted store must be refetched
+  explicitly on switch. (bala)
 - 2026-07-22 — **Correction:** the registry French key for COMPASSCANADA is **`fr-CA`, not `fr`**
   (verified `src/fieldsConfig/index.ts`); documented language persistence (zustand `persist` key
   `"fields-key"`, `setLanguage` stores the option uuid `en`/`fr-CA`) and the `startsWith("fr")` rule —

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

@@ -14,7 +14,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-07-22
+updated: 2026-07-23
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
@@ -70,11 +70,14 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   (16 rows seeded). French was extracted from the old bilingual `"English/French"` `Assortments.name`
   values, which were then cleaned to English-only. See
   [Assortment Name Translation](../../2.0/apps/_underscore/features/assortment-name-translation.md).
-- **Persona names (fr-CA) — DRAFTED / DEFERRED, not yet run.** A `PersonaTranslations` sidecar copying
-  the assortment pattern (Core record 346, fr-CA seed for 33 personas) is fully drafted in working
-  trees and `sql-reviewer`-approved but **not committed or run** — ids and 3 name-matched personas need
-  live-DB verification first (RDS was VPC-unreachable). The storefront side (persona query keys made
-  language-sensitive) already shipped. See
+- **Persona names (fr-CA) — backend finalized, NOT yet run; French text needs business sign-off.** A
+  `PersonaTranslations` sidecar copying the assortment pattern (Core record **348** / RecordFields
+  2469–2473, after `NotificationTranslations` 347; ids re-based against a confirmed prod snapshot) with
+  a fr-CA seed for all **34** Canada personas is fully built in working trees but **not deployed**. The
+  French persona names are **proposed** and still need Compass business sign-off (brand/sector proper
+  nouns: Eurest, Chartwells, ESFM, Foodbuy). The storefront side is fixed: `MySettingsView` now
+  explicitly refetches the persona list on language switch (the persisted-store `_personaOptions` isn't
+  refreshed by cache invalidation alone). See
   [Persona Name Translation](../../2.0/apps/_underscore/features/persona-name-translation.md).
 - **Storefront French localization** (labels, submenus, orders-for-others, Get Support illustration) is
   driven by the COMPASSCANADA FIELDS JSON; the registry language key is **`fr-CA`** (not `fr`). See

package/package.json

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