toga-ai 1.0.832 → 1.0.834

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

@@ -61,5 +61,5 @@
 | [USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)](features/usps-dpv-deliverability.md) | **USPS returning HTTP 200 with a populated address is NOT evidence that the address is deliverable.** The authoritative signal is USPS's **DPV (Delivery Point V |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, |
 | [Deleting a shared branch does not remove bad commits — a stale local clone merges them back](workflows/recreated-shared-branch-stale-local-remerge.md) | **Deleting and recreating a shared environment branch removes only the *ref*.** Every teammate who still has that branch checked out locally keeps the full pre- |
-| [Rotating Public TLS Certificates (ACM, CloudFront, ALB, Elastic Beanstalk)](workflows/rotating-public-tls-certificates.md) | How to replace the public TLS certificates that terminate HTTPS for TOGa front-end domains (togahub, togacommerce, togadesk, togaretail, togasupply, togaview, t |
+| [Rotating Public TLS Certificates (ACM, CloudFront, ALB, Elastic Beanstalk, API Gateway)](workflows/rotating-public-tls-certificates.md) | How to replace the public TLS certificates that terminate HTTPS for TOGa front-end domains (togahub, togacommerce, togadesk, togaretail, togasupply, togaview, t |
 | [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. |

package/knowledge/2.0/apps/_underscore/workflows/rotating-public-tls-certificates.md

@@ -1,12 +1,12 @@
 ---
-title: Rotating Public TLS Certificates (ACM, CloudFront, ALB, Elastic Beanstalk)
+title: Rotating Public TLS Certificates (ACM, CloudFront, ALB, Elastic Beanstalk, API Gateway)
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-09-17
 owners: ["rgirish"]
 files: []
 related:
@@ -27,13 +27,15 @@ This runbook was written from the 2026-09-16 rotation in AWS account **654654170
 one IMPORTED multi-domain cert (14 SANs, copied into us-east-1, us-west-2 and eu-west-1) served
 4 CloudFront distributions and 12 ALB listeners and expired the same day.
 
-**The three things that bite you:**
+**The four things that bite you:**
 1. **Elastic Beanstalk keeps its own saved cert setting**, separate from the ALB listener. Fixing
    the listener is not enough — the next deploy puts the old cert straight back.
 2. **CloudFront holds exactly ONE cert per distribution.** There is no staging. The swap *is* the
    cutover, and it takes 5-15 minutes.
 3. **An ACM wildcard matches exactly one label.** `*.togasupply.com` covers
    `elite.togasupply.com` but **not** `compass.beta.togasupply.com`.
+4. **API Gateway custom domains hold their own cert** and are invisible to a CloudFront/ALB/EB
+   sweep. This is what the 2026-09-16 rotation missed — see step 6b.
 
 **Root cause to avoid repeating:** an **IMPORTED** ACM cert never auto-renews. Always replace with
 **Amazon-issued, DNS-validated** ACM certs, which renew themselves.
@@ -123,6 +125,60 @@ one), and every environment stayed Green/Ok through the update — no traffic di
 **Gotcha:** an EB environment whose CloudFormation stack is in `DELETE_FAILED` cannot be updated at
 all — `update-environment` is refused. That needs separate stack cleanup.
 
+## Step 6b — Audit API Gateway custom domains (the 2026-09-16 miss)
+
+**API Gateway is a FOURTH resource type.** The 2026-09-16 rotation swept CloudFront, ALB listeners
+and EB saved configs, and reported "0 endpoints at risk". The next morning `webhook.togahub.com`
+was hard-down — it is an API Gateway custom domain, so none of those three sweeps could ever have
+found it. Proof of the failure, not just a stale cert:
+
+```
+$ curl -sS -o /dev/null -w "http=%{http_code} ssl=%{ssl_verify_result}\n" https://webhook.togahub.com/
+curl: (60) SSL certificate problem: certificate has expired
+http=000 ssl=10
+```
+
+**Find them from DNS — an API Gateway domain CNAMEs to `*.execute-api.<region>.amazonaws.com`:**
+
+```
+aws route53 list-resource-record-sets --hosted-zone-id <zid> --max-items 400 \
+  --query "ResourceRecordSets[?Type=='CNAME'].[Name,ResourceRecords[0].Value]" --output text \
+  | grep -i execute-api
+```
+
+Across all seven TOGa zones this found exactly one: `webhook.togahub.com` →
+`d-yiy4od2ade.execute-api.us-east-1.amazonaws.com`.
+
+**An unknown account ID in `InUseBy` can be AWS itself.** The expired cert's `InUseBy` listed 3
+ALBs in account **250044486744**, which no one has a profile for. That is AWS-managed edge
+infrastructure — an edge-optimized API Gateway domain terminates TLS on AWS's own load balancers.
+Treat it as a pointer to API Gateway, **not** as a rogue account to go hunt credentials for.
+
+**Permissions block this from the CLI.** The `GoAgilant-Developers` SSO role has **no**
+`apigateway:GET` in any of the three accounts (654654170868, 502614707982, 975050298201) —
+`get-domain-names`, `get-domain-name` and the `apigatewayv2` equivalents all return
+`AccessDeniedException`. The domain cannot be listed, read or fixed with the standard developer
+role. Use the Console, or get `apigateway:GET` + `apigateway:PATCH` added first.
+
+**Check the endpoint type FIRST — it decides which field you patch.** `get-domain-name` returns
+`endpointConfiguration.types`. An **EDGE** domain reads its cert from `us-east-1` and uses
+`/certificateArn`; a **REGIONAL** domain reads from its own region and uses
+`/regionalCertificateArn`. Patching the wrong field silently does nothing useful.
+`webhook.togahub.com` turned out to be **REGIONAL** (us-east-1), despite `InUseBy` showing
+AWS-managed edge ALBs — so do not infer the type from `InUseBy`.
+
+```
+aws apigateway get-domain-name --domain-name webhook.togahub.com \
+  --query 'endpointConfiguration.types'
+
+aws apigateway update-domain-name --domain-name webhook.togahub.com \
+  --patch-operations op=replace,path=/regionalCertificateArn,value=<new-arn>
+```
+
+The domain goes `UPDATING` and takes a few minutes to return to `AVAILABLE` (~4 min observed).
+Poll `domainNameStatus` before verifying — checking too early shows the old cert and looks like a
+failed patch. No downtime beyond the already-broken TLS; base path mappings are untouched.
+
 ## Step 7 — Check alias coverage before any CloudFront swap
 
 CloudFront **rejects** an update if any alias on the distribution is not covered by the new cert.
@@ -155,11 +211,22 @@ echo | openssl s_client -servername HOST -connect HOST:443 2>/dev/null \
   | openssl x509 -noout -issuer -enddate
 ```
 
+`openssl` shows you the cert, but it does **not** prove a client can connect. Add a real verify —
+and treat a known-bad host as the control that proves your check actually fails:
+
+```
+curl -sS -o /dev/null -w "http=%{http_code} ssl=%{ssl_verify_result}\n" https://HOST/
+```
+
+A live expired cert returns `http=000` with `SSL certificate problem: certificate has expired`.
+
 Also run it **without** `-servername` to check the no-SNI / default-cert path — that path can still
 be serving the old cert after everything else looks fine.
 
-Finish by re-running the step 1 audit: every CloudFront distribution, every ALB listener, and every
-EB saved config should name a cert with a future `NotAfter`.
+Finish by re-running the step 1 audit: every CloudFront distribution, every ALB listener, every
+EB saved config **and every API Gateway custom domain** should name a cert with a future
+`NotAfter`. A sweep that omits any one of those four resource types is not a clean result — it is
+an untested one.
 
 ## Gotchas
 
@@ -170,9 +237,28 @@ EB saved config should name a cert with a future `NotAfter`.
 - **CloudFront takes one cert; ALBs take many.** Two completely different risk profiles in the same
   rotation — plan them separately.
 - **Wildcards match one label only.** Verify alias coverage with code, not by eye.
+- **API Gateway custom domains are a fourth resource type.** A CloudFront + ALB + EB sweep misses
+  them completely. Find them by `execute-api` CNAMEs in Route 53. See step 6b.
+- **An unknown account ID in `InUseBy` may be AWS itself.** `250044486744` is AWS-managed edge
+  infrastructure for API Gateway, not a rogue account. See step 6b.
+- **The `GoAgilant-Developers` role needs `apigateway:GET` + `apigateway:PATCH`** on
+  `arn:aws:apigateway:*::/domainnames*`. Added to the permission set 2026-09-17; it was missing
+  during the rotation. Granted via IAM Identity Center, then **provisioned** to the account — the
+  provision step is what actually applies it. See step 6b.
+- **Patch the field that matches the endpoint type.** REGIONAL uses `/regionalCertificateArn`,
+  EDGE uses `/certificateArn`. See step 6b.
+- **`openssl` is not proof of health.** It prints the cert even when clients cannot connect. Use
+  `curl` and check for `http=000`. See step 9.
 - **Expired certs hide.** Sweep the whole account; do not trust `InUseBy`.
 
 ## Change history
+- 2026-09-17 — Added step 6b (API Gateway custom domains) after `webhook.togahub.com` was found
+  serving an expired cert and failing TLS the day after the rotation reported all-clear; added the
+  `curl` proof step, the AWS-owned-account `InUseBy` tell, and the missing `apigateway` permission.
+  **Fixed the same day:** `apigateway:GET`/`PATCH` added to the permission set, domain confirmed
+  REGIONAL, `regionalCertificateArn` swapped to the Amazon-issued `*.togahub.com` cert
+  (`a53d1ff6-...`, expires 2027-03-31). Verified `http=404 ssl=0` (was `http=000 ssl=10`), with
+  `expired.badssl.com` as the control that still fails. (rgirish)
 - 2026-09-16 — Created from the account 654654170868 rotation: replaced an expiring 14-SAN IMPORTED
   cert with 6 per-domain Amazon-issued DNS-validated certs, relinked 12 ALB listeners, 6 CloudFront
   distributions and 11 EB environment configs; documented the EB saved-config trap. (rgirish)

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.