toga-ai 1.0.166 → 1.0.167

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

@@ -2,5 +2,8 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [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 | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
 | [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 |
+| [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/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.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/architecture.md

@@ -0,0 +1,246 @@
+---
+title: TOGa Commerce (toga2-commerce / commerce2-react) Architecture
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: architecture
+status: active
+updated: 2026-06-23
+owners: ["apeterson"]
+files:
+  - src/main.tsx
+  - src/App.tsx
+  - src/routes.tsx
+  - src/contexts/AuthContext.tsx
+  - src/contexts/helpers/getLoginSettings.ts
+  - src/api/axiosInstance.ts
+  - src/stores/
+  - src/themeConfig/ThemeContext.tsx
+  - src/fieldsConfig/index.ts
+  - src/hooks/useAssignClientFields.ts
+  - vite.config.ts
+  - package.json
+related:
+  - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/workflows/amplify-build-and-deploy.md
+  - 2.0/apps/api2/architecture.md
+---
+
+## 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.
+
+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.
+
+> 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.
+
+## Tech stack (verified versions, package.json)
+
+| Concern | Library | Version |
+|---|---|---|
+| UI | react / react-dom | ^18.3.1 |
+| Routing | react-router-dom | ^7.5.1 |
+| Server state / cache | @tanstack/react-query (+ persist-client, sync-storage-persister) | ^5.59.19 |
+| Client state | zustand | ^4.5.4 |
+| HTTP | axios | 1.7.7 |
+| Forms | react-hook-form | ^7.53.1 |
+| Animation | framer-motion | ^11.0.18 |
+| Styling | tailwindcss | ^3.4.4 |
+| Errors / monitoring | @sentry/react | ^8.50.0 |
+| Build / tooling | vite ^5.4.10, typescript ^5.8.2 |
+| Tables | @tanstack/react-table, react-table (v7), react-table-sticky |
+| Misc | dayjs, react-select, nouislider, classnames, uuid, react-lottie, @agilant/toga-blox, FontAwesome Pro |
+
+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**:
+
+  ```
+  PersistQueryClientProvider (client=queryClient, persister → localStorage "commerce")
+    └─ AuthProvider            (contexts/AuthContext.tsx — auth state, tenant/login resolution)
+        └─ ThemeProvider       (themeConfig/ThemeContext.tsx — CSS-variable theming)
+            └─ ToasterProvider (contexts/ToasterContext.tsx — toast notifications)
+                └─ RouterProvider (routes.tsx)
+    + 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.
+
+## Routing (`src/routes.tsx`, createBrowserRouter)
+
+Public:
+- `/` → `AuthRedirect` (→ `/home` if authenticated, else renders nothing while the auth flow runs)
+- `/login` → `LoginRoute` (→ `/home` if already authenticated, else `<Login/>`)
+- `/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"`.
+
+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`).
+- Routes are **statically imported** (no `React.lazy`); Vite handles chunking at build time.
+
+## Page architecture — MVVM convention
+
+Every page under `src/pages/<Page>/` follows the same shape (View ← ViewModel ← API ← FIELDS):
+
+```
+src/pages/<Page>/
+├── <Page>Page.tsx / index.ts   # View — layout & rendering only
+├── types.ts                    # page-local TS types
+├── view/                       # sub-components, modals, loading skeletons
+├── viewModel/
+│   ├── use<Page>ViewModel.ts   # state + React Query hooks + business logic
+│   ├── index.ts
+│   └── FIELDS/<CLIENT>/[<LANGUAGE>/][<ROLE>/]*.json|*.ts   # per-tenant content/config
+├── api/<Page>Api.ts            # axios calls for this page
+├── hooks/                      # page-scoped hooks
+└── 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.)
+
+## State management
+
+### Zustand stores (`src/stores/`)
+Most use the `persist` middleware (localStorage). Verified files:
+
+| Store | Responsibility |
+|---|---|
+| `useUserStore` | Logged-in user (persona ids, role flags, currency) |
+| `useCartStoreZu` | Cart items + bundles, per-item quantity-change loading |
+| `useCartSalesQuoteZu` | Active sales order (ship-to, contact, cost center, notes, emails) |
+| `useCartOverlayZu` | Cart preview overlay state |
+| `useEditOrderZu` | "Edit existing order" mode flag + original snapshot |
+| `useEditOrderUuidStore` | UUID of the order being edited |
+| `useSelectedUserZu` | "Order for" user selected in cart |
+| `useReturnOriginalUserFromViewAsStore` | "View as another user" return-to-self tracking |
+| `useEmailOptionsStore` | Notification CC email options (see cart-notification-emails) |
+| `useBundleBuilderZu` | Bundle-builder wizard selections |
+| `useFieldsStore` | **`fieldKey` (tenant) + `language`** — drives field/theme resolution (persist key `fields-key`) |
+| `useSettingsModalStore` | Login/settings modal open flag |
+| `useSettingsErrorStore` | Settings validation errors (suppresses data queries when set) |
+
+### React Query (`src/queries/`, `src/hooks/useApiQuery.ts`, `useApiMutation.ts`)
+- Global default `staleTime` 24h; per-query overrides (user/persona data fetched fresh on login).
+- 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.
+
+## 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`.
+- **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`.
+- **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 `/`).
+- 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).
+
+## 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).
+- **Role flags** on the user object are tenant-specific:
+  - 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.
+
+## 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.
+
+## Directory map (`src/`)
+
+| Path | Purpose |
+|---|---|
+| `main.tsx` / `App.tsx` | bootstrap, Sentry, provider stack |
+| `routes.tsx` | router + route guards |
+| `api/` | axios instance, generic CRUD, sales-order sync helpers |
+| `contexts/` | `AuthContext`, `ToasterContext` (+ `helpers/getLoginSettings.ts`) |
+| `stores/` | Zustand stores (see table) |
+| `queries/` | login/prefetch React Query definitions |
+| `hooks/` | shared hooks (`useAssignClientFields`, `useAuthenticationFlow`, `useApiQuery/Mutation`, `useBreakpoint`, `useDynamicConditionalFieldOptions`, `useCancelEditOrder`) |
+| `pages/` | feature pages (MVVM) |
+| `components/` | shared UI (Base* atoms, `AuthLayout`, `Header`/`Footer`, `ThemeSwitcher`, `BaseDetailField`, guardrails, error messages, address forms, cards) |
+| `themeConfig/` | `themes.json`, `ThemeContext.tsx`, `types.ts` (theming) |
+| `fieldsConfig/` | global per-tenant client config + the master `FIELDS` registry |
+| `styles/`, `fonts/`, `assets/` | global CSS, web fonts, images/SVGs (some per-tenant) |
+| `utils/` | formatting, cart/address/persona helpers, query helpers |
+| `globalTypes.ts` | shared TS types (API envelope, User, Address, Item/Bundle, SalesOrder, …) |
+
+## 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.
+- **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
+  lowercase `en`/`fr`. See the client-fields doc.
+</content>

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

@@ -0,0 +1,187 @@
+---
+title: Client Fields — per-tenant / language / role content & config
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["apeterson"]
+files:
+  - src/fieldsConfig/index.ts
+  - src/fieldsConfig/getClientLoginFields.ts
+  - src/fieldsConfig/clientFields/COMPASS.json
+  - src/fieldsConfig/clientFields/COMPASSCANADA.json
+  - src/fieldsConfig/clientFields/QUAD.json
+  - src/hooks/useAssignClientFields.ts
+  - src/hooks/useDynamicConditionalFieldOptions.ts
+  - src/stores/useFieldsStore.ts
+  - src/components/BaseDetailField/BaseDetailField.tsx
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+  - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+---
+
+## Summary
+
+Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. Instead
+each page's labels, field lists, validation, visibility, and static content come from **JSON config
+resolved per tenant, per language, and per role**. There are **two layers**:
+
+- **Layer A — global client config** (`src/fieldsConfig/clientFields/<TENANT>.json`): a small file
+  per tenant controlling the language switcher and which user API fields to fetch at login.
+- **Layer B — the per-page `FIELDS` registry** (`src/fieldsConfig/index.ts` → `FIELDS`): the big
+  `tenant → language → role → page-section` object that every page ViewModel reads.
+
+## Layer A — global client config
+
+`src/fieldsConfig/clientFields/{COMPASS,COMPASSCANADA,QUAD}.json`, each:
+
+```json
+{
+  "languageSwitcher": { "uuid": "1", "isEnabled": true|false },
+  "userApiFields": ["firstName", "lastName", "email", "uuid", "_isAdmin", ...]
+}
+```
+
+- `languageSwitcher.isEnabled` — **only COMPASSCANADA is `true`** (English/French). COMPASS and
+  QUAD are `false`.
+- `userApiFields` — the allow-list of user columns fetched at login; importantly it includes the
+  tenant's **role flags**: COMPASS/COMPASSCANADA carry `_isAdmin`, `_isSupervisor`, `_isSuperAdmin`;
+  QUAD carries `_isGlobalAdmin`, `_isItShopper`, `_isBuyer`. All include `_personaIds`.
+
+Resolved by **`src/fieldsConfig/getClientLoginFields.ts`** — a `switch(client)` returning the JSON;
+**default is `COMPASS`** (not DEFAULT). Called from `AuthContext` as `getClientLoginFields(host)`.
+The `languageSwitcher.isEnabled` value feeds the login-settings branch in `getLoginSettings.ts`.
+
+## Layer B — the per-page FIELDS registry
+
+`src/fieldsConfig/index.ts` (~1100 lines) imports every page's per-tenant field constants (which
+themselves wrap the on-disk JSON under `pages/<Page>/viewModel/FIELDS/...`) and assembles one object:
+
+```ts
+export const FIELDS: Record<string, any> = {
+  COMPASS: {
+    en: {
+      ADMIN:     { HEADERFIELDS, HOMEPAGEFIELDS, ORDERDETAILS, CARTPAGEFIELDS, /* ~20 sections */ },
+      SUPERUSER: { ... },
+      MANAGER:   { ... },
+      USER:      { ... },
+    },
+  },
+  COMPASSCANADA: { en: { ADMIN, SUPERUSER, MANAGER, USER }, fr: { ... } },
+  QUAD: { en: { GLOBALADMIN, BUYER, ITSHOPPER /*, USER */ } },
+};
+```
+
+### Resolution dimensions & order
+
+`FIELDS[ tenant ][ language ][ role ]` → an object of **page-section** constants
+(`HEADERFIELDS`, `HOMEPAGEFIELDS`, `FOOTERFIELDS`, `ITEMSPAGE`, `ORDERDETAILS`, `GETSUPPORTPAGE`,
+`BUNDLEDETAILSPAGE`, `FILTERPAGEFIELDS`, `CARTPAGEFIELDS`, `NEWUSERFORMFIELDS`, `CANTFINDUSERFIELDS`,
+`PRIVACYPOLICYPAGEFIELDS`, `TERMSCONDITIONSPAGEFIELDS`, `ACCOUNTTABFIELDS`, `MYACCOUNTFIELDS`,
+`ORDERHISTORYFIELDS`, `ADD/EDIT/SELECTNEWPRIMARY/SHIPPINGADDRESSESFIELDS`, `CARTOVERLAY`,
+`ERRORFIELDS`, `LOGINSETTINGSFIELDS`, …).
+
+- **Tenant** keys: `COMPASS`, `COMPASSCANADA`, `QUAD`.
+- **Language** keys are **lowercase `en` / `fr`** in the registry. ⚠️ This differs from the on-disk
+  **folder** names, which are uppercase `ENGLISH` / `FRENCH`. Only COMPASSCANADA has `fr`.
+- **Role** keys: COMPASS/COMPASSCANADA → `ADMIN`, `SUPERUSER`, `MANAGER`, `USER`;
+  QUAD → `GLOBALADMIN`, `BUYER`, `ITSHOPPER` (+ `USER`).
+
+On disk the JSON lives at `pages/<Page>/viewModel/FIELDS/<CLIENT>/[<LANGUAGE>/][<ROLE>/]<NAME>FIELDS.json`,
+and **not every page uses every dimension**:
+- Pages with full role split: Home, OrderDetails, BundleView, Filter, Cart, Account.
+- Pages with **no role layer** (role-neutral content): PrivacyPolicy, GetSupport, ItemsView,
+  TermsConditions, ResetPassword (resolved at tenant/language level, shared across roles).
+- Language layer (`ENGLISH`/`FRENCH` folders) only exists for COMPASSCANADA; COMPASS and QUAD put
+  files directly under the tenant (their registry language is `en`).
+
+## The resolver — `useAssignClientFields`
+
+`src/hooks/useAssignClientFields.ts` is called by **every page ViewModel** (and several form
+ViewModels) with `(fieldKey, language, user)`:
+
+```ts
+let role: string;
+if (clientName === "COMPASS" || clientName === "COMPASSCANADA") {
+  if (user?._isAdmin === "1") role = "ADMIN";
+  else if (user?._isSuperAdmin === "1") role = "SUPERUSER";
+  else if (user?._isSupervisor === "1") role = "MANAGER";
+  else role = "USER";
+} else { // QUAD (and any non-Compass tenant)
+  if (user?._isGlobalAdmin === "1") role = "GLOBALADMIN";
+  else if (user?._isBuyer === "1") role = "BUYER";
+  else if (user?._isItShopper === "1") role = "ITSHOPPER";
+  else role = "USER";
+}
+
+// wrapped in React Query, keyed for caching:
+const queryKey = ["clientFields", clientName, language, role];
+const data = FIELDS?.[clientName]?.[language]?.[role] || null;
+```
+
+Inputs:
+- **`clientName`** = `useFieldsStore.fieldKey` (the tenant `host`, set at login — see architecture doc).
+- **`language`** = `useFieldsStore.language` (default `"en"`; set to `"fr"` etc. via `setLanguage`
+  from the login settings switcher or `MySettingsView`).
+- **`user`** = the logged-in user (role flags).
+
+It returns `{ fields, loading, error, resetFieldsMapCache }`; `resetFieldsMapCache` invalidates the
+`["clientFields"]` query (used when role/language/tenant changes mid-session). Page ViewModels then
+pluck the section they need, e.g. `fieldsCall["MYACCOUNTFIELDS"]`.
+
+## What's inside a FIELDS JSON
+
+Shape varies by page, but common forms:
+- **Static content pages** (PrivacyPolicy, TermsConditions, GetSupport): headings + text/HTML blocks
+  (`label` may contain HTML).
+- **Form pages** (ResetPassword, address forms, NewUser): `formFields[]` with
+  `inputType`, `isRequired`, `validationRequirements[]`, labels, placeholders.
+- **Data/detail pages** (Account, OrderDetails): field descriptors mapping data to display, e.g.
+  `{ uuid, label, valueKey, valueType: "currency"|"address"|"status", icon, colSpan, classes }`,
+  plus `pageSettings` (e.g. which API fields to fetch: `fetchUserDataFields`, `fetchUserOrdersDetailsApiFields`).
+
+Common field attributes: `uuid`, `label`, `valueKey` (path into the data object), `inputType`,
+`valueType` (render hint), `colSpan`/`classes` (Tailwind), `isRequired`, `icon`, `options[]`.
+
+## Consumers
+
+- **`src/components/BaseDetailField/`** (`BaseDetailField.tsx`, `renderBaseDetailFieldLabel`,
+  `renderBaseDetailFieldValue`) — generic renderer: takes a field descriptor + data object, applies
+  `valueType` formatting (currency/address/status) and the descriptor's Tailwind classes.
+- **`src/pages/BundleView/hooks/useBundleFields.ts`** — wraps `useAssignClientFields` and reads
+  bundle quantity rules from `BUNDLEDETAILSPAGE.pageSettings`.
+- **`src/hooks/useDynamicConditionalFieldOptions.ts`** — swaps dependent select options at runtime
+  (e.g. state/province options change with the selected country).
+
+## Onboarding / editing fields — practical notes
+
+- **New tenant:** add `clientFields/<TENANT>.json`, a `getClientLoginFields` case, a `<TENANT>`
+  branch in `FIELDS` (with the tenant's role keys), and the per-page `FIELDS/<TENANT>/...` JSON +
+  the corresponding imports in `index.ts`.
+- **New role:** extend the role-derivation in `useAssignClientFields.ts` **and** add the role key
+  under each `FIELDS[tenant][lang]` branch + per-page role folders.
+- **New language:** set `languageSwitcher.isEnabled` in the tenant's `clientFields` JSON, add the
+  `fr`/`xx` branch to `FIELDS[tenant]`, and the `<LANGUAGE>` on-disk folders.
+- **Editing copy:** change the page's `FIELDS/<CLIENT>/[<LANG>/][<ROLE>/]<NAME>FIELDS.json`. Remember
+  to update **all** affected role/language variants — there is no inheritance/fallback between roles.
+
+## Gotchas
+
+- **`en`/`fr` (registry) vs `ENGLISH`/`FRENCH` (folders)** — mismatching these is the classic bug;
+  the runtime lookup uses lowercase.
+- **No fallback** in `FIELDS[client][language][role]` — a missing tenant/role/language combo returns
+  `null` and the page renders empty. Keep all role variants in sync.
+- Role is derived from string `"1"` flags on the user (`user?._isAdmin === "1"`), not booleans.
+- `getClientLoginFields` defaults to **COMPASS** for an unknown host, which can mask a
+  misconfigured tenant in local dev.
+
+## Change history
+- 2026-06-23 — Initial: documented the two-layer field system (global `clientFields/<TENANT>.json`
+  + the per-page `FIELDS` registry), the `tenant→language→role` resolution in `useAssignClientFields`,
+  the `en`/`fr` vs `ENGLISH`/`FRENCH` distinction, role derivation per tenant, and field JSON shapes
+  (apeterson)
+</content>

package/knowledge/2.0/apps/toga2-commerce/features/multi-tenant-theming.md

@@ -0,0 +1,142 @@
+---
+title: Multi-Tenant Resolution & Theming
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["apeterson"]
+files:
+  - 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
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+---
+
+## Summary
+
+`toga2-commerce` serves multiple clients from one codebase. A request's **tenant** is derived
+from the **hostname**, and that single tenant string fans out into three independent systems:
+
+1. **API base URL** — `axiosInstance.ts` picks `VITE_API_<TENANT>`.
+2. **Theme** — `ThemeContext` applies the tenant's color set as CSS variables.
+3. **Fields/content** — the per-tenant field config (separate doc: [client-fields](client-fields.md)).
+
+Current tenants: **COMPASS**, **COMPASSCANADA**, **QUAD**, plus a **DEFAULT** fallback theme.
+
+## Tenant resolution — the hostname is the source of truth
+
+The same derivation appears in three places (intentionally — there is no single shared tenant util):
+
+```ts
+const fullHostName = window.location.hostname.toUpperCase(); // "COMPASS.TOGACOMMERCE"
+const host = fullHostName.split(".")[0];                     // "COMPASS"
+```
+
+- **`src/api/axiosInstance.ts`** (lines ~8-11): `const host = "VITE_API_" + hostName[0];`
+  → `baseURL = import.meta.env[host] || import.meta.env.VITE_API`. So the API endpoint is
+  tenant-specific (`VITE_API_COMPASS`, `VITE_API_QUAD`, …) with `VITE_API` as fallback.
+- **`src/contexts/AuthContext.tsx`** (lines ~68-70): derives `host` and uses it for
+  `getClientLoginFields(host)`, persona-switcher logic, and to set `fieldKey` (see below).
+- **`src/themeConfig/ThemeContext.tsx`** (lines ~13-15): derives `host` as the **default** theme key.
+
+This is why the per-tenant **dev scripts** matter: `npm run compass` runs
+`vite --host compass.togacommerce`, and `vite.config.ts` `server.allowedHosts` permits
+`compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`. Plain `localhost`
+won't match a tenant, so it falls back (theme → DEFAULT, fields → COMPASS).
+
+### From hostname to active theme — `fieldKey` is the real trigger
+
+The theme is **not** applied directly from the raw hostname at mount. The chain is:
+
+1. On login, `AuthContext` → `getLoginSettings(...)` writes `useFieldsStore.fieldKey = host`.
+2. **`src/components/AuthLayout/AuthLayout.tsx`** runs:
+   ```ts
+   const { theme, loadThemeForClient } = useThemeContext();
+   useEffect(() => { loadThemeForClient(fieldKey); }, [fieldKey, loadThemeForClient]);
+   ```
+   So whenever `fieldKey` resolves, the matching theme loads.
+3. **On first mount**, `ThemeProvider` loads `localStorage["current-client-id"]` (set by a prior
+   `loadThemeForClient`) or **`"DEFAULT"`** — not the hostname — so the very first paint before
+   login uses the last-saved or default theme.
+
+## Theme config & data shape
+
+- **`src/themeConfig/themes.json`** — top-level keys `DEFAULT`, `COMPASS`, `COMPASSCANADA`, `QUAD`.
+  Each entry: `{ id, name, colors: {...} }`.
+- **`src/themeConfig/types.ts`** (`ClientTheme`) — the `colors` object is the only themed data.
+  Token groups (each typically with `default/hover/disabled/active` states, some with `bg-`,
+  `text-`, `border-`, `icon-` prefixes):
+  - `primary` (a numeric color scale, e.g. `50`/`500`/`900`)
+  - `btn` (`primary`, `tertiary`), `btn-nav`, `btn-nav-badge`, `btn-tabView-alt1`
+  - `input`, `checkBox`, `tile`, `text` (`body-primary`/`secondary`/`tertiary`)
+
+> The theme controls **colors only**. Fonts, spacing, etc. are global Tailwind config / `@font-face`
+> in `src/fonts/`, not per-tenant theme data.
+
+## How the theme is applied — CSS variables on `<html>`
+
+`ThemeContext.applyThemeToDOM` recursively flattens `themeData.colors` into CSS custom properties
+on `document.documentElement`:
+
+```ts
+// leaf string → root.style.setProperty(`--${prefix}-${key}`, value)
+// nested object → recurse with prefix `${prefix}-${key}`
+applyNestedColors(themeData.colors, "color");
+```
+
+So `colors.btn.primary["bg-default"]` becomes `--color-btn-primary-bg-default`. **`tailwind.config.js`**
+maps semantic color tokens to these variables (`var(--color-...)`), so components style with normal
+Tailwind classes and automatically pick up the active tenant's palette. `loadThemeForClient` also
+persists the chosen key to `localStorage["current-client-id"]`.
+
+## ThemeSwitcher
+
+`src/components/ThemeSwitcher/ThemeSwitcher.tsx` is a manual `<select>` over `availableThemes`
+(from `Object.values(themes.json)`) calling `loadThemeForClient(e.target.value)`. It's an override
+/ dev-testing affordance for previewing tenants — normal users get their theme from `fieldKey`.
+
+## Per-tenant assets
+
+Logos and some imagery are **hard-coded imports with conditional rendering** keyed on `theme?.id`
+(e.g. AuthLayout selects the QUAD logo vs. the Compass logo). They are not part of `themes.json`.
+
+## Onboarding a new tenant — checklist
+
+1. **Theme** — add a new top-level key to `src/themeConfig/themes.json` with the full `colors` set
+   (copy DEFAULT/COMPASS and recolor); confirm `tailwind.config.js` tokens cover any new groups.
+2. **API env** — add `VITE_API_<TENANT>` to the `.env.<mode>` files (else it falls back to `VITE_API`).
+3. **Dev script + allowedHosts** — add `"<tenant>": "vite --mode development --host <tenant>.togacommerce"`
+   to `package.json` and `<tenant>.togacommerce` to `vite.config.ts` `server.allowedHosts`; add the
+   host to the local hosts file.
+4. **Client login config** — add `src/fieldsConfig/clientFields/<TENANT>.json` and a `case` in
+   `src/fieldsConfig/getClientLoginFields.ts` (see client-fields doc).
+5. **Fields** — add the `<TENANT>` branch to the master `FIELDS` registry and the per-page
+   `FIELDS/<TENANT>/...` JSON (see client-fields doc).
+6. **Roles** — if the tenant's role flags differ from COMPASS/QUAD, extend the role-derivation
+   in `src/hooks/useAssignClientFields.ts` and `AuthContext`'s persona logic.
+7. **Assets** — add tenant logos and wire the conditional `theme?.id` rendering.
+
+## Gotchas
+
+- Tenant detection is **hostname-only** — there is no env-var or build-flag override of the tenant
+  at runtime. Wrong host = wrong tenant.
+- The theme's first paint uses `localStorage["current-client-id"]` or DEFAULT, *then* corrects to
+  `fieldKey` once `AuthLayout` mounts — expect a brief default-themed flash pre-login.
+- Adding a color token group to `themes.json` does nothing visually unless `tailwind.config.js`
+  references the corresponding `--color-*` variable.
+
+## Change history
+- 2026-06-23 — Initial: documented hostname→tenant resolution (axios/AuthContext/ThemeContext),
+  `fieldKey`-driven theme application via AuthLayout, CSS-variable flattening of `themes.json` colors,
+  ThemeSwitcher, and the new-tenant onboarding checklist (apeterson)
+</content>

package/knowledge/INDEX.md

@@ -26,7 +26,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 5 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 

package/package.json

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