toga-ai 1.0.832 → 1.0.833

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

@@ -2,22 +2,23 @@
 
 | Doc | Summary |
 |-----|---------|
-| [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform |
+| [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | Whole-repo map of the toga2-commerce React storefront (bootstrap, routing, MVVM pages, state, API, multi-tenant resolution); open when working anywhere in this |
 | [Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)](features/bundle-item-visibility-and-selectability.md) | Which components of a kit a shopper can see and choose is decided **entirely in the browser**. |
 | [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 |
-| [Cart Notification Emails — auto-add/remove lifecycle + duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. |
+| [Cart Notification Emails — auto-add/remove lifecycle + duplicate prevention](features/cart-notification-emails.md) | Cart Notifications section: CC-email duplicate prevention + auto-add/remove of order-for-user & delegate-manager emails; open when touching notification emails |
 | [Cart Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. |
 | [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`. |
 | [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP |
 | [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one |
-| [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`. |
+| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Per-tenant/language/role JSON config that drives almost all commerce UI text, fields, and login fetches (Layer A global + Layer B FIELDS registry); open before |
 | [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 |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | The storefront has **two distinct search entry points that render the same card component through completely different code paths and different FIELDS files**. |
+| [Header "Order for <Name>" dropdown + the pending-pick hand-off to the cart](features/header-order-for-dropdown.md) | Header pill that lets a buyer pick who they are ordering for from any page, and the in-memory store that hands that pick to the cart's order-for cascade; open b |
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | An item with **`Items.isActive = 0`** must not be viewable, addable to a cart, or orderable **as a standalone line** on the storefront — but the **same flag is |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | Submitting an order from the cart fires **two independent sync routines** — one for the sales-order header (`syncSalesOrderData`) and one for the line items (`s |
 | [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | On the toga2-commerce **Cart** page, a shipping option's **cost** can be waived by config using the same `PrimaryItemShippingRule` vocabulary that drives expedi |
 | [Storefront persona gating — the Home page's kit / category / item counts, and the persona switcher](features/storefront-persona-gating-and-home-counts.md) | What a storefront user sees on the Home page is decided **in the front end**, from `user._personaIds`, not by the API's ACL. |
 | [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**. |
-| [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | The Cypress **e2e** convention set for `toga2-commerce`, and the first **active** e2e coverage for the **Cart** page (`cartV2.cy.ts`, slice 1 — 12 tests, verifi |
+| [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | Cypress e2e conventions + the Cart harness (cartV2.cy.ts) for toga2-commerce; read before adding any spec here, and note it doubles as the config-cart refactor |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | When a Chromium browser (Chrome / Edge) shows **`ERR_HTTP2_PROTOCOL_ERROR`** loading a `*.togacommerce.com` tenant for **one client/network but works for the TO |

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

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: architecture
 status: active
-updated: 2026-07-28
+updated: 2026-09-17
 owners: ["apeterson", "tcox"]
 files:
   - src/main.tsx
@@ -29,22 +29,15 @@ related:
   - 2.0/apps/toga2-commerce/features/filter-search-results-page.md
 ---
 
+Whole-repo map of the toga2-commerce React storefront (bootstrap, routing, MVVM pages, state, API, multi-tenant resolution); open when working anywhere in this repo.
+
 ## Summary
 
-`toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the
-customer-facing **B2B commerce storefront** of the 2.0 platform. It is a **React 18 + TypeScript +
-Vite 5 single-page app** styled with **Tailwind**, and it is the React front end in the 2.0
-"decoupled" architecture: it talks to **`api2`** (the TOGa v2 JSON API) for all data, and renders
-nothing server-side.
+`toga2-commerce` (npm package **`commerce2-react`**, product **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform: a **React 18 + TypeScript + Vite 5 SPA** styled with **Tailwind**. It is the React front end in the 2.0 "decoupled" architecture — talks to **`api2`** (the TOGa v2 JSON API) for all data, renders nothing server-side. It is a 2.0 *app with no PHP*: registry `dependsOn` is `api2`; it consumes `_underscore`/`api2` over HTTP but contains no framework PHP classes.
 
-It is **multi-tenant**: a single codebase serves several clients (currently **COMPASS**,
-**COMPASSCANADA**, **QUAD**, plus a **DEFAULT** fallback). The tenant is resolved at runtime from
-the **hostname** and drives three independent systems — the API base URL, the theme, and the
-per-tenant field/content config. See [multi-tenant-theming](features/multi-tenant-theming.md) and
-[client-fields](features/client-fields.md) for those subsystems in depth.
+**Multi-tenant:** one codebase serves several clients (**COMPASS**, **COMPASSCANADA**, **QUAD**, plus a **DEFAULT** fallback). The tenant is resolved at runtime from the **hostname** and drives three independent systems — API base URL, theme, per-tenant field/content config. See [multi-tenant-theming](features/multi-tenant-theming.md) and [client-fields](features/client-fields.md).
 
-> Note: this is a **2.0 *app* with no PHP**. Its registry `dependsOn` is `api2`; it consumes the
-> `_underscore`/`api2` backend over HTTP but contains no framework PHP classes itself.
+**Critical rules:** Tenant is derived from hostname only (`hostname.toUpperCase().split(".")[0]`) — wrong host = wrong tenant, and `localhost` falls back (fields→COMPASS, theme→DEFAULT). The single `QueryClient` uses a **24h default `staleTime`** and persists the whole cache to **`localStorage["commerce"]`**, so catalog AND config/copy (FIELDS) can be up to 24h stale for a returning user — verify any data/copy change after `localStorage.removeItem('commerce')` or logout, never on a warm browser. `AuthLayout` never remounts, so `refetchOnMount` fires once per session — route-change refreshes must be wired explicitly. The registry French language key is **`fr-CA`**, not `fr` — branch on `startsWith("fr")`. api2 returns the standard `{success,data,errors}` envelope; do not break the shape.
 
 ## Tech stack (verified versions, package.json)
 
@@ -67,10 +60,8 @@ E2E tests use **Cypress** (`cypress/`, `cypress.config.ts`).
 
 ## Bootstrap & provider stack
 
-- `src/main.tsx` — initializes **Sentry** (browser tracing + replay) and mounts `<App/>` in React
-  `StrictMode`; imports global CSS.
-- `src/App.tsx` — creates a single `QueryClient` (default `staleTime: 24h`) and a
-  `createSyncStoragePersister` (localStorage key **`"commerce"`**). Provider nesting, **outermost → innermost**:
+- `src/main.tsx` — initializes **Sentry** (browser tracing + replay), mounts `<App/>` in React `StrictMode`, imports global CSS.
+- `src/App.tsx` — creates a single `QueryClient` (default `staleTime: 24h`) and a `createSyncStoragePersister` (localStorage key **`"commerce"`**). Provider nesting, **outermost → innermost**:
 
   ```
   PersistQueryClientProvider (client=queryClient, persister → localStorage "commerce")
@@ -81,13 +72,8 @@ E2E tests use **Cypress** (`cypress/`, `cypress.config.ts`).
     + ReactQueryDevtools (initialIsOpen=false)
   ```
 
-  `App` also runs a mount effect managing **edit-order mode**: it reads a `localStorage.synced`
-  flag and calls `exitEditOrderModeGlobalSyncReset()` when an edit-order session was abandoned
-  outside `/cart`, and subscribes to `useReturnOriginalUserFromViewAsStore` (the "view-as" feature).
-
-> The cache is **persisted**: query results survive refreshes via `PersistQueryClientProvider`.
-> Combined with the 24h default `staleTime`, catalog data is aggressively cached — invalidate
-> deliberately with `queryClient.invalidateQueries(...)` when freshness matters.
+- `App` runs a mount effect managing **edit-order mode**: reads a `localStorage.synced` flag and calls `exitEditOrderModeGlobalSyncReset()` when an edit-order session was abandoned outside `/cart`; subscribes to `useReturnOriginalUserFromViewAsStore` (the "view-as" feature).
+- The cache is **persisted**: query results survive refreshes. Combined with the 24h default `staleTime`, catalog data is aggressively cached — invalidate deliberately with `queryClient.invalidateQueries(...)` when freshness matters.
 
 ## Routing (`src/routes.tsx`, createBrowserRouter)
 
@@ -97,17 +83,11 @@ Public:
 - `/reset-password` → `ResetPasswordPage`
 
 Authenticated (wrapped by `PrivateRoute` → `AuthLayout`):
-- `/home`, `/bundle-view`, `/filter`, `/cart`, `/get-support`, `/account`, `/item-view`,
-  `/order-details`, `/privacy-policy`, `/terms-conditions`; unmatched → `Navigate to="/home"`.
+- `/home`, `/bundle-view`, `/filter`, `/cart`, `/get-support`, `/account`, `/item-view`, `/order-details`, `/privacy-policy`, `/terms-conditions`; unmatched → `Navigate to="/home"`.
 
 Mechanics:
-- **`PrivateRoute`** gates on `useAuth().isAuthenticated` + `useAuthenticationFlow().isLoading`;
-  shows an `AuthLoading` spinner while loading, redirects to `/login` if unauthenticated.
-- **`AuthLayout`** wraps every authenticated route and **stays mounted across route changes**
-  (header, footer, nav, notifications live here). Its `errorElement` renders `<ErrorMessage errorType={500}/>`.
-  ⚠️ Because it never remounts, React Query `refetchOnMount` only fires **once per session** for
-  queries owned by AuthLayout — route-change refreshes must be wired explicitly (e.g. the
-  notifications query invalidates on route change keyed on `user?.uuid`).
+- **`PrivateRoute`** gates on `useAuth().isAuthenticated` + `useAuthenticationFlow().isLoading`; shows an `AuthLoading` spinner while loading, redirects to `/login` if unauthenticated.
+- **`AuthLayout`** wraps every authenticated route and **stays mounted across route changes** (header, footer, nav, notifications live here). Its `errorElement` renders `<ErrorMessage errorType={500}/>`. Because it never remounts, `refetchOnMount` fires **once per session** for queries owned by AuthLayout — route-change refreshes must be wired explicitly (e.g. the notifications query invalidates on route change keyed on `user?.uuid`).
 - Routes are **statically imported** (no `React.lazy`); Vite handles chunking at build time.
 
 ## Page architecture — MVVM convention
@@ -128,10 +108,7 @@ src/pages/<Page>/
 └── helpers/                    # pure compute/format helpers
 ```
 
-Pages: `Account, BundleView, Cart, Filter, GetSupport, Home, ItemsView, Login, OrderDetails,
-PrivacyPolicy, ResetPassword, TermsConditions`. The **ViewModel hook is the seam**: it calls
-`useAssignClientFields(fieldKey, language, user)` to load the right tenant/role/language content,
-runs the page's queries, and returns ready-to-render data to the View. (See client-fields doc.)
+Pages: `Account, BundleView, Cart, Filter, GetSupport, Home, ItemsView, Login, OrderDetails, PrivacyPolicy, ResetPassword, TermsConditions`. The **ViewModel hook is the seam**: it calls `useAssignClientFields(fieldKey, language, user)` to load the right tenant/role/language content, runs the page's queries, and returns ready-to-render data to the View. (See client-fields doc.)
 
 ## State management
 
@@ -147,6 +124,7 @@ Most use the `persist` middleware (localStorage). Verified files:
 | `useEditOrderZu` | "Edit existing order" mode flag + original snapshot |
 | `useEditOrderUuidStore` | UUID of the order being edited |
 | `useSelectedUserZu` | "Order for" user selected in cart |
+| `useOrderForZu` | Header "order for" **pending pick** handed to the cart cascade — **in memory only, never `persist`ed** |
 | `useReturnOriginalUserFromViewAsStore` | "View as another user" return-to-self tracking |
 | `useEmailOptionsStore` | Notification CC email options (see cart-notification-emails) |
 | `useBundleBuilderZu` | Bundle-builder wizard selections |
@@ -159,59 +137,35 @@ Most use the `persist` middleware (localStorage). Verified files:
 - Cache persisted to localStorage (`"commerce"`); rehydrated on load.
 - Page queries are typically `enabled` on `isAuthenticated && user?.uuid && !settingsModalEnabled`.
 
-**Two-layer state model:** React Query owns *server* state (catalog, orders, user); Zustand owns
-*local* state (cart, selected user, edit mode, tenant/language). The cart is synced to the backend
-sales order via `src/api/syncSalesOrder*.ts` helpers.
+**Two-layer state model:** React Query owns *server* state (catalog, orders, user); Zustand owns *local* state (cart, selected user, edit mode, tenant/language). The cart is synced to the backend sales order via `src/api/syncSalesOrder*.ts` helpers.
 
 ## API layer (`src/api/`)
 
-`src/api/axiosInstance.ts` is the shared client. Key behaviors (all verified):
-- **Base URL by tenant:** `host = "VITE_API_" + window.location.hostname.toUpperCase().split(".")[0]`;
-  `baseURL = import.meta.env[host] || import.meta.env.VITE_API`. So `compass.togacommerce` →
-  `VITE_API_COMPASS`, falling back to `VITE_API`. `timeout: 180000`.
+`src/api/axiosInstance.ts` is the shared client. Verified behaviors:
+- **Base URL by tenant:** `host = "VITE_API_" + window.location.hostname.toUpperCase().split(".")[0]`; `baseURL = import.meta.env[host] || import.meta.env.VITE_API`. So `compass.togacommerce` → `VITE_API_COMPASS`, falling back to `VITE_API`. `timeout: 180000`.
 - **Transaction id:** a request interceptor stamps every call with `params.transactionId = uuidv4()`.
-- **Auth token:** a second request interceptor attaches `Authorization: Bearer <token>` — using the
-  stored `accessToken` if a `user` exists in localStorage, otherwise fetching a **public token** via
-  `POST {baseURL}/auth/public`.
+- **Auth token:** a second request interceptor attaches `Authorization: Bearer <token>` — using the stored `accessToken` if a `user` exists in localStorage, otherwise fetching a **public token** via `POST {baseURL}/auth/public`.
 - **1 ms delay interceptor:** a third request interceptor `await delay(1)` before sending.
-- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh
-  token) once (`_retry`), retries the original request on success, else calls `performLogout()`
-  (clears all auth + cart + `commerce` cache keys and redirects to `/`).
+- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh token) once (`_retry`), retries the original request on success, else calls `performLogout()` (clears all auth + cart + `commerce` cache keys and redirects to `/`).
 - Failures are reported to **Sentry** with `errorType: "API"` tags.
 
-The backend (`api2`) returns the standard 2.0 envelope (`success`/`data`/`errors`; see api2 arch);
-generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `saveData`, `updateData`,
-`deleteData`, optional `?depth=-1` for nested responses).
+The backend (`api2`) returns the standard 2.0 envelope (`success`/`data`/`errors`; see api2 arch); generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `saveData`, `updateData`, `deleteData`, optional `?depth=-1` for nested responses).
 
 ## Authentication & roles
 
-- `src/contexts/AuthContext.tsx` derives `host` from the hostname (`hostname.toUpperCase().split(".")[0]`),
-  loads `getClientLoginFields(host)` (tenant config), decides persona-switcher visibility
-  (`determineShouldShowPersonaSwitcher` — QUAD special-cased), then runs
-  `getLoginSettings(...)` which writes `useFieldsStore.fieldKey = host` and the language, and
-  hydrates `useUserStore`.
-- `src/hooks/useAuthenticationFlow.ts` orchestrates the post-login fetch sequence
-  (user data → persona → contact → settings).
+- `src/contexts/AuthContext.tsx` derives `host` from the hostname (`hostname.toUpperCase().split(".")[0]`), loads `getClientLoginFields(host)` (tenant config), decides persona-switcher visibility (`determineShouldShowPersonaSwitcher` — QUAD special-cased), then runs `getLoginSettings(...)` which writes `useFieldsStore.fieldKey = host` and the language, and hydrates `useUserStore`.
+- `src/hooks/useAuthenticationFlow.ts` orchestrates the post-login fetch sequence (user data → persona → contact → settings).
 - **Role flags** on the user object are tenant-specific:
-  - COMPASS / COMPASSCANADA → `ADMIN` (`_isAdmin`), `SUPERUSER` (`_isSuperAdmin`),
-    `MANAGER` (`_isSupervisor`), else `USER`.
+  - COMPASS / COMPASSCANADA → `ADMIN` (`_isAdmin`), `SUPERUSER` (`_isSuperAdmin`), `MANAGER` (`_isSupervisor`), else `USER`.
   - QUAD → `GLOBALADMIN` (`_isGlobalAdmin`), `BUYER` (`_isBuyer`), `ITSHOPPER` (`_isItShopper`), else `USER`.
-- **Personas:** `user._personaIds` is a colon-delimited string; `getLoginSettings` has special
-  handling collapsing persona-24 cases for non-QUAD tenants.
+- **Personas:** `user._personaIds` is a colon-delimited string; `getLoginSettings` has special handling collapsing persona-24 cases for non-QUAD tenants.
 
 ## Build & deploy
 
-- **Per-tenant dev/build scripts** (`package.json`): `compass`, `compasscanada`, `quad`,
-  `togacommerce` run `vite --mode development --host <tenant>.togacommerce`; production builds are
-  `build` / `buildAlpha` / `buildBeta` / `buildGamma` / `buildQcSecurity` (each installs the matching
-  `@agilant/toga-blox` npm channel, then `tsc` + `vite build --mode <env>`).
-- `vite.config.ts`: React plugin + Sentry Vite plugin (sourcemap upload); dev `server.allowedHosts`
-  = `compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`; PostCSS via
-  `postcss.config.cjs`; `optimizeDeps.include: ["react-router-dom"]`.
-- Local dev requires `*.togacommerce` hostnames to resolve to localhost (hosts file) so tenant
-  resolution works.
-- Deployment runs on **AWS Amplify** — see [amplify-build-and-deploy](workflows/amplify-build-and-deploy.md).
-  A `Dockerfile`/`docker-compose.yml` also exist for containerized dev.
+- **Per-tenant dev/build scripts** (`package.json`): `compass`, `compasscanada`, `quad`, `togacommerce` run `vite --mode development --host <tenant>.togacommerce`; production builds are `build` / `buildAlpha` / `buildBeta` / `buildGamma` / `buildQcSecurity` (each installs the matching `@agilant/toga-blox` npm channel, then `tsc` + `vite build --mode <env>`).
+- `vite.config.ts`: React plugin + Sentry Vite plugin (sourcemap upload); dev `server.allowedHosts` = `compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`; PostCSS via `postcss.config.cjs`; `optimizeDeps.include: ["react-router-dom"]`.
+- Local dev requires `*.togacommerce` hostnames to resolve to localhost (hosts file) so tenant resolution works.
+- Deployment runs on **AWS Amplify** — see [amplify-build-and-deploy](workflows/amplify-build-and-deploy.md). A `Dockerfile`/`docker-compose.yml` also exist for containerized dev.
 
 ## Directory map (`src/`)
 
@@ -234,26 +188,8 @@ generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `save
 
 ## Gotchas
 
-- **`AuthLayout` never remounts** → `refetchOnMount` fires once per session; wire explicit
-  invalidation for data that must refresh on navigation.
-- **24h `staleTime` + persisted cache** → users can see stale catalog/pricing; invalidate on the
-  events that should bust it. **This also masks config/copy deploys:** `FIELDS` is served *through*
-  the `["clientFields", …]` query, so a returning user rehydrates the old labels from
-  `localStorage["commerce"]` and sees stale copy for up to 24h after a build that contains the new
-  JSON. Verify any FIELDS change after `localStorage.removeItem('commerce')` or a logout, never on a
-  warm browser. A build-version `buster` in `persistOptions` would fix this at deploy time but
-  invalidates every persisted query app-wide — **open team decision, not implemented.**
-- **Tenant resolution depends on the hostname.** On `localhost` with no `*.togacommerce` host the
-  first DNS label won't match a tenant, so config falls back (`getClientLoginFields` → COMPASS,
-  theme → DEFAULT). Use the per-tenant dev scripts.
-- **Theme vs. fields language keys differ** — theme/field *folder* names are uppercase
-  (`COMPASSCANADA`, `ENGLISH`/`FRENCH`) but the runtime `FIELDS` registry keys language as
-  `en` / **`fr-CA`** (not `fr`). Any language branch must use `startsWith("fr")` — a `=== "fr"`
-  comparison silently never matches. See the client-fields doc.
-
-## Change history
-- 2026-07-28 — Gotchas: recorded that the 24h persisted React Query cache also masks `FIELDS`
-  config/copy deploys (verify after clearing `localStorage["commerce"]`; `persistOptions.buster` is
-  an open team decision), and corrected the runtime language key to `fr-CA` requiring
-  `startsWith("fr")` (tcox)
-</content>
+- **`AuthLayout` never remounts** → `refetchOnMount` fires once per session; wire explicit invalidation for data that must refresh on navigation.
+- **24h `staleTime` + persisted cache** → users can see stale catalog/pricing; invalidate on the events that should bust it. **This also masks config/copy deploys:** `FIELDS` is served *through* the `["clientFields", …]` query, so a returning user rehydrates the old labels from `localStorage["commerce"]` and sees stale copy for up to 24h after a build that contains the new JSON. Verify any FIELDS change after `localStorage.removeItem('commerce')` or a logout, never on a warm browser. A build-version `buster` in `persistOptions` would fix this at deploy time but invalidates every persisted query app-wide — **open team decision, not implemented.**
+- **Tenant resolution depends on the hostname.** On `localhost` with no `*.togacommerce` host the first DNS label won't match a tenant, so config falls back (`getClientLoginFields` → COMPASS, theme → DEFAULT). Use the per-tenant dev scripts.
+- **Theme vs. fields language keys differ** — theme/field *folder* names are uppercase (`COMPASSCANADA`, `ENGLISH`/`FRENCH`) but the runtime `FIELDS` registry keys language as `en` / **`fr-CA`** (not `fr`). Any language branch must use `startsWith("fr")` — a `=== "fr"` comparison silently never matches. See the client-fields doc.
+- **Tailwind: not every `<n>px` name is a token.** `max-h-300px` does not exist (300px is only on the height/width scales) — write `max-h-[300px]`. `w-345px`, `h-300px`, `border-1` and `shadow-subMenu` do exist. A non-existent class silently renders unstyled.

package/knowledge/2.0/apps/toga2-commerce/features/cart-notification-emails.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-17
 owners: ["bala", "tcox"]
 files:
   - src/pages/Cart/CartPage.tsx
@@ -19,84 +19,47 @@ files:
 related:
   - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
   - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/features/header-order-for-dropdown.md
   - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
 ---
 
+Cart Notifications section: CC-email duplicate prevention + auto-add/remove of order-for-user & delegate-manager emails; open when touching notification emails on the cart.
+
 ## Summary
-On the cart "Notifications" section a user can add CC email addresses to an order. Two jobs live
-here:
-
-1. **Duplicate prevention.** Adding the same address twice (often with different casing) used to
-   slip through to the API and blow up on submit with a MySQL 1062 duplicate-key error on the
-   `SalesOrderEmailAddresses.salesOrderId_emailAddress` unique index (collation
-   `utf8mb4_0900_ai_ci` is case-insensitive). The frontend blocks duplicates case-insensitively and
-   shows a sapphire info message instead of letting the error reach the user.
-2. **Auto-add/remove lifecycle.** Picking an **order-for user** or a **Delegate Manager**
-   auto-adds their notification emails. **Changing the pick must remove the previous person's
-   auto-added emails.** Until 2026-09-10 it did not: the old person and their manager stayed in the
-   list, still checked, and still in the submit payload — so notifications went to the wrong
-   people unless the buyer noticed and unchecked them.
-
-## Key files / entry points
-- `CartPage.tsx` — `handleAddEmail`: validates the email regex, then on success calls
-  `addEmailOption` (UI options list) and `addEmail` (the cart sales-quote store that builds the
-  `salesOrderEmailAddresses` payload). Normalizes the input once with `.trim()`.
-- `CartForm.tsx` — owns the duplicate UX. `handleAddEmailWithDuplicateCheck` wraps the passed-in
-  `handleAddEmail`: it case-insensitively checks the existing `emails` list and, on a match, shows
-  the message instead of adding. The **Add Email** button calls this wrapper.
-- `CartPage.tsx` — also owns the **Delegate Manager** lifecycle:
-  `advancedSelectConfig.delegateManager.onSelect` / `.onClearInput`, the
-  `lastDelegateManagerEmailRef` (useRef), the `removeDelegateManagerEmail` guard, the
-  `watch("hasDelegateManager")` and `watch("delegateManager")` effects, and `handleClearUser`.
-- `EditCart.tsx` — cart-checkout mode. The order-for change effect (`onSuccess` of the user fetch)
-  owns add **and** remove of the order-for user's emails, plus the local `ensureEmailSelected`
-  helper and the `orderForUserChanged` flag.
-- `EditOrder.tsx` — edit-order mode. Still has the **original add-only** order-for pattern.
-- `useEmailOptionsStore.ts` — `addEmailOption` de-dupes the checkbox list; `removeEmailOption`
-  removes case-insensitively; `selectEmailOption(email)` marks an option checked (idempotent —
-  never toggles).
-- `useCartSalesQuoteZu.ts` — `addEmail` de-dupes and `removeEmail` removes from the actual
-  `salesOrderEmailAddresses` payload, both case-insensitively.
+
+On the cart "Notifications" section a user can add CC email addresses to an order. Two jobs live here:
+
+1. **Duplicate prevention.** Adding the same address twice (often with different casing) used to slip through to the API and blow up on submit with a MySQL 1062 duplicate-key error on the `SalesOrderEmailAddresses.salesOrderId_emailAddress` unique index (collation `utf8mb4_0900_ai_ci` is case-insensitive). The frontend blocks duplicates case-insensitively and shows a sapphire info message instead of letting the error reach the user.
+2. **Auto-add/remove lifecycle.** Picking an **order-for user** or a **Delegate Manager** auto-adds their notification emails. **Changing the pick must remove the previous person's auto-added emails.** Until 2026-09-10 it did not: the old person and their manager stayed in the list, still checked, and still in the submit payload — so notifications went to the wrong people unless the buyer noticed and unchecked them.
 
 ## How it works
 
+### Key files / entry points
+- `CartPage.tsx` — `handleAddEmail`: validates the email regex, then on success calls `addEmailOption` (UI options list) and `addEmail` (the cart sales-quote store that builds the `salesOrderEmailAddresses` payload). Normalizes the input once with `.trim()`.
+- `CartForm.tsx` — owns the duplicate UX. `handleAddEmailWithDuplicateCheck` wraps the passed-in `handleAddEmail`: it case-insensitively checks the existing `emails` list and, on a match, shows the message instead of adding. The **Add Email** button calls this wrapper.
+- `CartPage.tsx` — also owns the **Delegate Manager** lifecycle: `advancedSelectConfig.delegateManager.onSelect` / `.onClearInput`, the `lastDelegateManagerEmailRef` (useRef), the `removeDelegateManagerEmail` guard, the `watch("hasDelegateManager")` and `watch("delegateManager")` effects, and `handleClearUser`.
+- `EditCart.tsx` — cart-checkout mode. The order-for change effect (`onSuccess` of the user fetch) owns add **and** remove of the order-for user's emails, plus the local `ensureEmailSelected` helper and the `orderForUserChanged` flag.
+- `EditOrder.tsx` — edit-order mode. Still has the **original add-only** order-for pattern.
+- `useEmailOptionsStore.ts` — `addEmailOption` de-dupes the checkbox list; `removeEmailOption` removes case-insensitively; `selectEmailOption(email)` marks an option checked (idempotent — never toggles).
+- `useCartSalesQuoteZu.ts` — `addEmail` de-dupes and `removeEmail` removes from the actual `salesOrderEmailAddresses` payload, both case-insensitively.
+
 ### Duplicate prevention
-1. **Before (manual add):** clicking Add Email runs `handleAddEmailWithDuplicateCheck` in
-   `CartForm`. It compares `(e.email ?? "").trim().toLowerCase()` against the normalized input. On a
-   match it sets `duplicateEmailMessage` and returns (does not add).
-2. **After (auto-add on user select):** when the order user is chosen, their email (and manager's)
-   is auto-added via `addEmailOption`. Both stores de-dupe case-insensitively, so a case-variant of
-   an already-present address is silently dropped rather than duplicated.
-3. **Display:** the message renders via the shared `InfoBanner` component (the same one used for the
-   "view as" / "edit order" banners), styled `text-sapphire-700 text-xs`, no icon. It is NOT a
-   toaster and NOT a red `setError` validation — it is a sapphire info message.
-4. The message text comes from the `notifications.duplicateEmailAddressError.label` field config,
-   present in every `CARTPAGE.ts` (all client/role/language variants, English + French).
-5. A `useEffect` clears the message when the input, selected user (`orderForUser?.uuid`), or email
-   list (`emails.length`) changes.
+1. **Manual add:** clicking Add Email runs `handleAddEmailWithDuplicateCheck` in `CartForm`. It compares `(e.email ?? "").trim().toLowerCase()` against the normalized input. On a match it sets `duplicateEmailMessage` and returns (does not add).
+2. **Auto-add on user select:** when the order user is chosen, their email (and manager's) is auto-added via `addEmailOption`. Both stores de-dupe case-insensitively, so a case-variant of an already-present address is silently dropped rather than duplicated.
+3. **Display:** the message renders via the shared `InfoBanner` component (the same one used for the "view as" / "edit order" banners), styled `text-sapphire-700 text-xs`, no icon. It is NOT a toaster and NOT a red `setError` validation — it is a sapphire info message.
+4. The message text comes from the `notifications.duplicateEmailAddressError.label` field config, present in every `CARTPAGE.ts` (all client/role/language variants, English + French).
+5. A `useEffect` clears the message when the input, selected user (`orderForUser?.uuid`), or email list (`emails.length`) changes.
 
 ### Order-for user — add AND remove (`EditCart.tsx`, cart-checkout mode only)
-Auto-added set per user: **their email**, `supervisorUser.email`, and
-`c_supportedByUserId.email`.
-
-1. On success of the order-for user fetch, read the **previous** user from
-   `useSelectedUserZu.getState().selectedUser` — the store, **not** the render closure (the closure
-   is stale inside the query callback).
-2. If the previous uuid differs from the new one (`orderForUserChanged`), remove that person's three
-   auto-added addresses from **both** `useEmailOptionsStore` and
-   `useCartSalesQuoteZu.salesOrder.salesOrderEmailAddresses`. **Never remove the logged-in user's
-   own address** even if it matches one of the three.
-3. Re-seed the new user's addresses through the local **`ensureEmailSelected(email)`** helper:
-   `addEmailOption` → `selectEmailOption` → `addEmail`. Idempotent, so re-running it is safe.
-4. The seeding block runs when `salesOrderEmailAddresses` is empty **or** when
-   `orderForUserChanged`. Before the fix it ran only on empty, so the second pick's emails were
-   added **un-checked** and never reached the payload.
+Auto-added set per user: **their email**, `supervisorUser.email`, and `c_supportedByUserId.email`.
+
+1. On success of the order-for user fetch, read the **previous** user from `useSelectedUserZu.getState().selectedUser` — the store, **not** the render closure (the closure is stale inside the query callback).
+2. If the previous uuid differs from the new one (`orderForUserChanged`), remove that person's three auto-added addresses from **both** `useEmailOptionsStore` and `useCartSalesQuoteZu.salesOrder.salesOrderEmailAddresses`. **Never remove the logged-in user's own address** even if it matches one of the three.
+3. Re-seed the new user's addresses through the local **`ensureEmailSelected(email)`** helper: `addEmailOption` → `selectEmailOption` → `addEmail`. Idempotent, so re-running it is safe.
+4. The seeding block runs when `salesOrderEmailAddresses` is empty **or** when `orderForUserChanged`. Before the fix it ran only on empty, so the second pick's emails were added **un-checked** and never reached the payload.
 
 ### Delegate Manager email lifecycle (`CartPage.tsx`, cart-checkout mode)
-"Associate" in the Compass UI = Delegate Manager. Its email is tracked by
-**`lastDelegateManagerEmailRef`** (a `useRef`), because the form value cannot be used (see
-Gotchas). The email is parsed out of the option label, which has the shape
-`"First Last (email)"`.
+"Associate" in the Compass UI = Delegate Manager. Its email is tracked by **`lastDelegateManagerEmailRef`** (a `useRef`), because the form value cannot be used (see Gotchas). The email is parsed out of the option label, which has the shape `"First Last (email)"`.
 
 | Action | What happens |
 |---|---|
@@ -106,80 +69,33 @@ Gotchas). The email is parsed out of the option label, which has the shape
 | Clear the order-for user | `handleClearUser` also un-checks the box, empties the field, and clears the ref |
 | Restore a saved cart | the `watch("delegateManager")` effect seeds the ref; a restored name has no `"(email)"`, so it falls back to `salesOrder.approvalUser.email` |
 
-**`removeDelegateManagerEmail` never removes an address that is also** the order-for user's, their
-supervisor's, their support tech's, or the logged-in user's — those are owned by the order-for
-lifecycle above.
-
-## Data model
-Frontend only. The payload list maps to the `SalesOrderEmailAddresses` table (api2/backend), which
-has a case-insensitive unique index on `(salesOrderId, emailAddress)`.
-
-## Client variations
-The de-dupe mechanism is uniform across clients. Only the message label text differs per client
-config: English `"This email has already been added"`; French (Compass Canada)
-`"Cette adresse e-mail a déjà été ajoutée"`. The label must exist in every `CARTPAGE.ts` variant or
-the message resolves to `undefined` and renders blank.
-
-## Gotchas / known issues
-- The real source of the 1062 was `useCartSalesQuoteZu.addEmail` comparing with `===`
-  (case-sensitive). Both stores must compare case-insensitively; fixing only the UI list is not
-  enough because `addEmail` builds the payload.
-- **Removes must be case-insensitive too, not just adds.** Both stores' *adds* were already
-  case-insensitive while their *removes* used exact match, so a hand-typed `Bob@X.com` survived a
-  remove of `bob@x.com` and shipped in the payload. `removeEmailOption` and `removeEmail` are now
-  case-insensitive.
-- **`handleEmailChange` TOGGLES — never use it to seed.** Re-running it on an already-checked
-  address **un-checks** it. Use the idempotent `ensureEmailSelected` /
-  `selectEmailOption` path for any auto-seeding.
-- **`CartFormSection` overwrites the form value BEFORE your handler runs.** It calls
-  `field.onChange(value)` and *then* `config.onSelect(value, valueKey)` (same for
-  `field.onChange(null)` before `config.onClearInput`). So
-  `formMethods.getValues("delegateManager")` inside those handlers already holds the **new** value
-  — you **cannot** read the previous pick from the form. Keep the previous value in a `useRef`.
-- **Read the previous order-for user from the store, not the closure.** Inside the user-fetch
-  `onSuccess` the render closure's `selectedUser` is stale; use
-  `useSelectedUserZu.getState().selectedUser`.
-- **`delegateManager` defaults to a truthy object** (`{uuid:"",name:""}`) now that it is a typed
-  form field, so `if (formValues.delegateManager)` is always true. Check
-  `formValues.delegateManager?.uuid` instead (3 call sites: `EditCart.tsx` ×2, `EditOrder.tsx` ×1).
-- **`EditOrder.tsx` (edit-order mode) still has the add-only order-for pattern** — the same
-  wrong-recipient bug very likely exists there. Left alone deliberately: edit-order has different
-  manager rules (`assignedTo`). Fix it as its own task.
-- Normalize with `(x ?? "").trim().toLowerCase()`, not `x?.trim().toLowerCase()` — both are
-  nullish-safe (optional chaining short-circuits the whole chain, it does not throw), but `(x ?? "")`
-  guarantees a string and avoids an `undefined === undefined` match edge.
-- Adding the label to only some `CARTPAGE.ts` files leaves other client/role/language users with a
-  blank message.
+**A failed order-for user fetch runs the same `handleClearUser()`** (plus an error toast) instead of only reporting to Sentry, so the ref, the emails and the field are cleared on that path too. Same doc for the other new entry point: the header pill sets `orderFor` through `useOrderForZu`, then this identical cascade runs — see [header-order-for-dropdown](header-order-for-dropdown.md). Both are branch `TRUE-81851`, not yet merged.
+
+**`removeDelegateManagerEmail` never removes an address that is also** the order-for user's, their supervisor's, their support tech's, or the logged-in user's — those are owned by the order-for lifecycle above.
+
+### Data model
+Frontend only. The payload list maps to the `SalesOrderEmailAddresses` table (api2/backend), which has a case-insensitive unique index on `(salesOrderId, emailAddress)`.
+
+### Client variations
+The de-dupe mechanism is uniform across clients. Only the message label text differs per client config: English `"This email has already been added"`; French (Compass Canada) `"Cette adresse e-mail a déjà été ajoutée"`. The label must exist in every `CARTPAGE.ts` variant or the message resolves to `undefined` and renders blank.
+
+## Gotchas
+
+- The real source of the 1062 was `useCartSalesQuoteZu.addEmail` comparing with `===` (case-sensitive). Both stores must compare case-insensitively; fixing only the UI list is not enough because `addEmail` builds the payload.
+- **Removes must be case-insensitive too, not just adds.** Both stores' *adds* were already case-insensitive while their *removes* used exact match, so a hand-typed `Bob@X.com` survived a remove of `bob@x.com` and shipped in the payload. `removeEmailOption` and `removeEmail` are now case-insensitive.
+- **`handleEmailChange` TOGGLES — never use it to seed.** Re-running it on an already-checked address **un-checks** it. Use the idempotent `ensureEmailSelected` / `selectEmailOption` path for any auto-seeding.
+- **`CartFormSection` overwrites the form value BEFORE your handler runs.** It calls `field.onChange(value)` and *then* `config.onSelect(value, valueKey)` (same for `field.onChange(null)` before `config.onClearInput`). So `formMethods.getValues("delegateManager")` inside those handlers already holds the **new** value — you **cannot** read the previous pick from the form. Keep the previous value in a `useRef`.
+- **Read the previous order-for user from the store, not the closure.** Inside the user-fetch `onSuccess` the render closure's `selectedUser` is stale; use `useSelectedUserZu.getState().selectedUser`.
+- **`delegateManager` defaults to a truthy object** (`{uuid:"",name:""}`) now that it is a typed form field, so `if (formValues.delegateManager)` is always true. Check `formValues.delegateManager?.uuid` instead (3 call sites: `EditCart.tsx` ×2, `EditOrder.tsx` ×1).
+- **`EditOrder.tsx` (edit-order mode) still has the add-only order-for pattern** — the same wrong-recipient bug very likely exists there. Left alone deliberately: edit-order has different manager rules (`assignedTo`). Fix it as its own task.
+- Normalize with `(x ?? "").trim().toLowerCase()`, not `x?.trim().toLowerCase()` — both are nullish-safe (optional chaining short-circuits the whole chain, it does not throw), but `(x ?? "")` guarantees a string and avoids an `undefined === undefined` match edge.
+- Adding the label to only some `CARTPAGE.ts` files leaves other client/role/language users with a blank message.
 - Do not use a toaster or `setError` (red) for this — product wants the sapphire info style.
-- **e2e coverage is branch-dependent — check before you rely on it.** On `_production`,
-  `cypress/e2e/cartPage/cartV2.cy.ts` covers both the auto-population (order-for user + supervisor
-  emails, protected rows unremovable) and the case-insensitive duplicate block surfacing the
-  *"This email has already been added"* banner — the exact parity behaviors the config-cart
-  refactor spike silently lost, so keep it green (see
-  [cypress-testing](../workflows/cypress-testing.md)). But on `#sprint86` that file **does not
-  exist** and every spec in `cypress/e2e/cartPage/cart.cy.ts` is **commented out**, so there is no
-  net for this flow there. Verify manually on such a branch.
-- **ESLint cannot run in this repo checkout** (pre-existing): `.eslintrc.cjs` references
-  `eslint-plugin-react-compiler`, which is not installed. Type-check with
-  `npx tsc --noEmit -p tsconfig.app.json` instead.
-
-## Change history
-- 2026-09-10 — FIXED: changing the order-for user or the Delegate Manager left the previous
-  person's auto-added emails checked and in the submit payload, so notifications went to the wrong
-  people (reported by a Compass USA user on `compass.togacommerce.com`; fix is client-neutral).
-  Order-for path (`EditCart.tsx`) now removes the prior user's three auto-added addresses and
-  re-seeds via the idempotent `ensureEmailSelected` (replacing the toggling `handleEmailChange`),
-  and seeds on `orderForUserChanged` as well as on empty. Delegate Manager path (`CartPage.tsx`)
-  gained `lastDelegateManagerEmailRef` + `removeDelegateManagerEmail` covering pick / re-pick / X /
-  un-check / clear-user / restore. Stores: added `selectEmailOption`, made `removeEmailOption` and
-  `removeEmail` case-insensitive. `hasDelegateManager` / `delegateManager` are now typed form fields
-  with defaults, so delegate checks moved to `?.uuid`. Edit-order mode not fixed (different manager
-  rules). (tcox)
-- 2026-07-27 — No behavior change. This duplicate-prevention UX (email auto-population +
-  case-insensitive duplicate banner) is now covered by cart e2e slice 1 (`cartV2.cy.ts`); linked
-  the [cypress-testing](../workflows/cypress-testing.md) workflow doc. (tcox)
-- 2026-06-18 — Initial: case-insensitive de-dupe in both cart stores, sapphire `InfoBanner` message in
-  CartForm, `duplicateEmailAddressError` label added to all CARTPAGE.ts variants (bala)
-
-## Related docs
+- **e2e coverage is branch-dependent — check before you rely on it.** On `_production`, `cypress/e2e/cartPage/cartV2.cy.ts` covers both the auto-population (order-for user + supervisor emails, protected rows unremovable) and the case-insensitive duplicate block surfacing the *"This email has already been added"* banner — the exact parity behaviors the config-cart refactor spike silently lost, so keep it green (see [cypress-testing](../workflows/cypress-testing.md)). But on `#sprint86` that file **does not exist** and every spec in `cypress/e2e/cartPage/cart.cy.ts` is **commented out**, so there is no net for this flow there. Verify manually on such a branch.
+- **ESLint cannot run in this repo checkout** (pre-existing): `.eslintrc.cjs` references `eslint-plugin-react-compiler`, which is not installed. Type-check with `npx tsc --noEmit -p tsconfig.app.json` instead.
+
+## Related
+
+- [cart-page-config-architecture](cart-page-config-architecture.md)
+- [client-fields](client-fields.md)
 - [cypress-testing](../workflows/cypress-testing.md) — e2e coverage that pins this behavior.