toga-ai 1.0.466 → 1.0.467

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

@@ -6,8 +6,9 @@
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
-| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts |
+| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |
+| [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**. | src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/useFilterViewModel.ts, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/COMPASSCANADA/FRENCH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/QUAD/ENGLISH/BUYER/FILTERPAGEFIELDS.json, src/components/Header/Header.tsx, src/pages/Home/view/components/BundlesSection.tsx, src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HOMEPAGEFIELDS.json, src/components/Cards/BundleViewCard.tsx, src/utils/renderBadge.tsx, src/hooks/useAssignClientFields.ts |
 | [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 |
 | [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 | toga2-commerce/cypress/e2e/cartPage/cartV2.cy.ts, toga2-commerce/cypress/fixtures/cart/fetchSingleUserAdmin.json, toga2-commerce/cypress/fixtures/cart/fetchLocations.json, toga2-commerce/cypress/fixtures/cart/fetchUserShippingMethods.json, toga2-commerce/cypress/support/commands.ts, toga2-commerce/cypress/support/e2e.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartFormSection.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartContentsTable.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartTableItem.tsx, toga2-commerce/src/components/Inputs/AdvancedInput.tsx, toga2-commerce/src/components/BaseButton/BaseButton.tsx |

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

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: architecture
 status: active
-updated: 2026-06-23
-owners: ["apeterson"]
+updated: 2026-07-28
+owners: ["apeterson", "tcox"]
 files:
   - src/main.tsx
   - src/App.tsx
@@ -26,6 +26,7 @@ related:
   - 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
+  - 2.0/apps/toga2-commerce/features/filter-search-results-page.md
 ---
 
 ## Summary
@@ -236,11 +237,23 @@ generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `save
 - **`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.
+  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
-  lowercase `en`/`fr`. See the client-fields doc.
+  `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>

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

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-28
 owners: ["apeterson", "tcox", "bala"]
 files:
   - src/pages/Account/view/MySettingsView.tsx
@@ -31,11 +31,15 @@ files:
   - src/pages/GetSupport/GetSupportPage.tsx
   - src/pages/GetSupport/viewModel/useGetSupportViewModel.ts
   - src/queries/queries.ts
+  - src/App.tsx
+  - src/pages/Filter/FilterPage.tsx
+  - src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json
 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
   - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+  - 2.0/apps/toga2-commerce/features/filter-search-results-page.md
   - 2.0/apps/_underscore/features/persona-name-translation.md
 ---
 
@@ -226,6 +230,26 @@ Any code that branches on the current language must compare against **`"fr-CA"`*
 `language.startsWith("fr")`, **never `language === "fr"`** (that comparison silently fails and was the
 root cause of the Get Support image bug — see gotchas).
 
+### FIELDS ride the persisted React Query cache — config fixes can appear not to deploy
+
+`FIELDS` is statically bundled, but it is **served through a React Query query**
+(`["clientFields", clientName, language, role]`). `src/App.tsx` sets the QueryClient default
+`staleTime` to **24h** and persists the entire cache to `localStorage` under the key **`"commerce"`**
+via `createSyncStoragePersister` + `PersistQueryClientProvider`. Consequence: a **returning** user
+rehydrates the *old* fields object from localStorage and keeps seeing **stale labels for up to 24
+hours after a deploy**, even though the new JSON is in the shipped bundle.
+
+This is the single most common false negative when verifying a FIELDS/copy change — QA reports "your
+fix didn't ship" on a browser that simply replayed the persisted cache.
+
+- **Clear it manually:** `localStorage.removeItem('commerce')` then refresh.
+- **Logging out also clears it** — both `src/contexts/AuthContext.tsx` (logout path) and
+  `src/api/axiosInstance.ts` call `localStorage.removeItem("commerce")`.
+- **Proper deploy-time fix — not implemented, team decision pending:** pass a build-version `buster`
+  string in `persistOptions` in `App.tsx`. It is one line, but it invalidates **every** persisted query
+  app-wide on each deploy (losing all warm cache, not just fields), so it needs a deliberate call
+  rather than a drive-by change.
+
 ## What's inside a FIELDS JSON
 
 Shape varies by page, but common forms:
@@ -322,6 +346,21 @@ on switch.
   untranslated on purpose (the dropdown *contents* are translated). It is not a localization gap.
 - **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.
+- **No fallback for an individual *key* either — and that failure is silent.** The "no fallback" rule
+  applies one level deeper than the section lookup: a key missing from an otherwise-present page JSON
+  just yields `undefined`, which the consuming component happily interpolates. Real symptoms shipped
+  2026-07-28: `renderBadge(undefined)` rendered a structurally-present but **empty, uncolored,
+  icon-less** badge, and a card template `` `${count} ${label}s` `` rendered **"3 undefineds"**. Nothing
+  throws, nothing logs, TypeScript is clean (the lookups are optional-chained `any`). When adding a
+  card/label key, add it to **every** tenant × language × role file for that page — 12 for Compass
+  (COMPASS/ENGLISH × 4 roles + COMPASSCANADA/{ENGLISH,FRENCH} × 4), 3 for QUAD. See
+  [filter-search-results-page](filter-search-results-page.md).
+- **Key names are per page, not global — the same UI element can have different key names in two
+  pages' JSON.** The kit badge is `bundleBadge` in `HOMEPAGEFIELDS` but `kitBadge` in
+  `FILTERPAGEFIELDS`. Never assume a label added for one page covers another; grep the consuming
+  component for the exact `fields?.<key>` it reads.
+- **A stale persisted cache masks FIELDS deploys** — see the persisted-cache section above; verify
+  copy changes after `localStorage.removeItem('commerce')` or a logout, never on a warm browser.
 - 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.
@@ -339,6 +378,14 @@ on switch.
   slip. Do not "reconcile" the two lists.
 
 ## Change history
+- 2026-07-28 — Documented two failure modes found while fixing the header-search kit card: (1) there is
+  **no fallback for an individual key** inside a present page JSON — a missing key silently yields
+  `undefined` (empty uncolored badge, `"3 undefineds"`), and key names differ per page
+  (`bundleBadge` in HOMEPAGEFIELDS vs `kitBadge` in FILTERPAGEFIELDS); (2) FIELDS are served *through*
+  the `["clientFields", …]` React Query, whose cache is persisted to `localStorage["commerce"]` with a
+  24h `staleTime`, so returning users see **stale labels for up to 24h after a deploy** — clear with
+  `localStorage.removeItem('commerce')` or a logout. Recorded the pending team decision on adding a
+  build-version `buster` to `persistOptions` in `App.tsx`. (tcox)
 - 2026-07-23 — **Correction:** clarified that `LANGUAGE_SENSITIVE_QUERY_KEYS` alone does **not**
   refresh the persona name on language switch — `user._personaOptions` lives in the persisted Zustand
   `user` store (populated once at login), not a live React Query, so nothing in the allow-list owns it.

package/knowledge/2.0/apps/toga2-commerce/features/filter-search-results-page.md

@@ -0,0 +1,150 @@
+---
+title: Filter / Search-Results Page & the Two Search Entry Points
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-07-28
+owners: ["tcox"]
+files:
+  - src/pages/Filter/FilterPage.tsx
+  - src/pages/Filter/viewModel/useFilterViewModel.ts
+  - src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json
+  - src/pages/Filter/viewModel/FIELDS/COMPASSCANADA/FRENCH/USER/FILTERPAGEFIELDS.json
+  - src/pages/Filter/viewModel/FIELDS/QUAD/ENGLISH/BUYER/FILTERPAGEFIELDS.json
+  - src/components/Header/Header.tsx
+  - src/pages/Home/view/components/BundlesSection.tsx
+  - src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HOMEPAGEFIELDS.json
+  - src/components/Cards/BundleViewCard.tsx
+  - src/utils/renderBadge.tsx
+  - src/hooks/useAssignClientFields.ts
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+---
+
+## Summary
+
+The storefront has **two distinct search entry points that render the same card component through
+completely different code paths and different FIELDS files**. That split is the single most important
+fact about this page: a search-results defect almost always reproduces on **one** path only, and the
+first diagnostic question is *"which search box did you use?"*
+
+| Entry point | Component | Route | FIELDS section read |
+|---|---|---|---|
+| **Home page lower search bar** | `src/pages/Home/view/components/BundlesSection.tsx` | stays on `/home`, filters **in place** | `HOMEPAGEFIELDS` |
+| **Header search bar** (global, every authenticated page) | `src/components/Header/Header.tsx` → `src/pages/Filter/FilterPage.tsx` | **navigates** to `/filter?search=<text>&category=all` | `FILTERPAGEFIELDS` |
+
+Both then render the shared **`src/components/Cards/BundleViewCard.tsx`**. Because the two callers
+populate that shared card's props from two different JSON files, the card can render correctly from
+one entry point and be broken from the other — which is exactly the 2026-07-28 "3 undefineds" kit-card
+bug (see Change history).
+
+## How it works
+
+### Header search → `/filter`
+
+`Header.tsx` navigates to `` `/filter?search=${encodeURIComponent(inputValue)}` + "&category=all" ``.
+`FilterPage.tsx` reads the query string, and `useFilterViewModel.ts` runs the catalog query and calls
+`useAssignClientFields(fieldKey, language, user)` to resolve `FILTERPAGEFIELDS` for the current
+tenant × language × role (see [client-fields](client-fields.md) for the resolver). `FilterPage`
+`renderBundles` maps each result to a `BundleViewCard`.
+
+### Home search → in-place filter
+
+The Home page's own lower search bar never leaves `/home`. `BundlesSection.tsx` reads
+`HOMEPAGEFIELDS` (already loaded by the Home ViewModel) and renders the same `BundleViewCard`.
+
+### The shared card contract (`BundleViewCard`)
+
+The card is a dumb presentational component — every label is a prop. Two props matter for kit cards:
+
+- `includedItems` — the count.
+- `includedItemsText` — the **singular** noun, e.g. `"included item"`.
+
+The card composes them itself, in **two places** (mobile and desktop blocks, ~lines 112 and 191):
+
+```tsx
+text={`${includedItems} ${includedItemsText}${includedItems == 1 ? "" : "s"}`}
+```
+
+So a caller that forgets `includedItemsText` renders **"3 undefineds"** — the literal string
+`undefined` plus the appended `s`. There is no default and no runtime guard.
+
+### Badges are keyed off the badge *text*
+
+`src/utils/renderBadge.tsx` takes the resolved label string and derives **everything** from it:
+
+- `badgeTextMapping` / `badgeTextMappingFrench` — display text (French is looked up by the **English**
+  key, e.g. `Kit → "Trousse"`), falling back to the raw string.
+- `getBadgeClasses(badgeText)` — a `switch` on the text for background/foreground colors (it accepts
+  both English and French spellings: `"Kit"`, `"Trousse"`, `"Ensemble"`).
+- `getBadgeIcon(badgeText)` — a `switch` on the text for the FontAwesome icon; only `"Kit"` and
+  `"VIP"` match.
+
+`renderBadge(undefined, "")` therefore renders a **structurally present but empty and uncolored
+badge**: no text, no icon, and the `default:` class branch (no color). Nothing throws and nothing
+logs — the bug looks like a CSS problem and is actually a missing config key.
+
+### The badge key is named differently on each page
+
+Same visual badge, two different FIELDS key names — do not assume one:
+
+- Home / `HOMEPAGEFIELDS` → **`bundleBadge`** (`fields?.bundleBadge?.label`)
+- Filter / `FILTERPAGEFIELDS` → **`kitBadge`** (`fields?.kitBadge?.label`)
+
+## Gotchas
+
+- **A missing *key* inside a present FIELDS file fails silently.** The known "no fallback" rule for
+  `FIELDS[tenant][language][role]` also applies one level deeper: an individual key absent from a
+  page's JSON yields `undefined`, which renders as an empty badge or `"N undefineds"`. Any card-label
+  key must exist in **every** tenant × language × role file for that page — 12 files for Compass
+  (COMPASS/ENGLISH × 4 roles, COMPASSCANADA/ENGLISH × 4, COMPASSCANADA/FRENCH × 4) and 3 for QUAD
+  (QUAD/ENGLISH/{GLOBALADMIN,BUYER,ITSHOPPER}).
+- **Adding a label to one page's FIELDS does not cover the other page.** `HOMEPAGEFIELDS` and
+  `FILTERPAGEFIELDS` are independent files with independent key sets; a label added for the Home card
+  must be added again (possibly under a different key name) for the Filter card.
+- **French pluralization is broken by design in the shared card.** `BundleViewCard` blindly appends
+  `"s"`, so `"articles inclus"` renders as **"3 articles incluss"** in fr-CA. This pre-dates the
+  Filter-page fix (the Compass Canada *home* page has always shown it) and the Filter page now
+  mirrors it for parity. The real fix is pre-pluralized per-language labels (or a singular/plural pair)
+  in the card contract — **follow-up ticket, not yet filed.**
+- **French kit badge loses its icon.** The FRENCH JSONs store the label `"Trousse"`, so
+  `getBadgeClasses` still colors it but `getBadgeIcon` (which only matches `"Kit"`) returns `null` — no
+  BoxesStacked icon in French. Storing the English `"Kit"` in the French file would get both the icon
+  *and* auto-translated text via `badgeTextMappingFrench`. Current behavior matches the Home page, so
+  it was left alone; treat it as a known cosmetic gap, not a regression.
+- **Persisted React Query cache hides FIELDS fixes for up to 24h after deploy.** FIELDS are served
+  *through* a query (`["clientFields", tenant, language, role]`) and the whole cache is persisted to
+  `localStorage["commerce"]` with a 24h `staleTime`, so a returning user rehydrates the **old** labels
+  even though the new JSON is in the bundle. When QA says "your config fix didn't ship", have them run
+  `localStorage.removeItem('commerce')` and refresh (logging out also clears it). See
+  [client-fields](client-fields.md).
+
+## Known open items
+
+- **QUAD has the same missing-key bug, unfixed.** All three
+  `src/pages/Filter/viewModel/FIELDS/QUAD/ENGLISH/{GLOBALADMIN,BUYER,ITSHOPPER}/FILTERPAGEFIELDS.json`
+  still lack `kitBadge` and `includedItemsText`, so a header-search kit card on QUAD renders the empty
+  badge + `"3 undefineds"`. The fix is the identical two-entry JSON addition; it was left out because
+  the 2026-07-28 session was scoped to Compass.
+- French pluralization (`"3 articles incluss"`) — needs a card-contract change, see gotchas.
+
+## Change history
+- 2026-07-28 — Fixed header-search kit cards for Compass USA + Compass Canada. Two defects in the
+  Filter path: (1) `FilterPage.tsx` rendered `BundleViewCard` without passing `includedItemsText`
+  → `"3 undefineds"` (added `const includedItemsText = fields?.includedItemsText?.label;` beside the
+  existing `kitBadgeLabel` read and passed it through in `renderBundles`); (2) the `kitBadge` key was
+  missing from every `FILTERPAGEFIELDS.json` except COMPASSCANADA/ENGLISH/ADMIN, so
+  `renderBadge(undefined)` produced an empty uncolored badge. Added `kitBadge` ("Kit"/"Trousse") and
+  `includedItemsText` ("included item"/"articles inclus") to all **12** Compass FILTERPAGEFIELDS
+  files, copied from the working HOMEPAGEFIELDS labels so both search paths render identically. The
+  code change is a no-op for tenants whose config lacks the keys, so QUAD is unchanged (still buggy —
+  see Known open items). `npx tsc --noEmit` clean. (tcox)
+- 2026-07-28 — Initial doc: recorded the two search entry points (Home in-place vs. header →
+  `/filter`), the shared `BundleViewCard` label contract, text-keyed badge rendering in
+  `renderBadge.tsx`, the `bundleBadge` vs `kitBadge` key-name split, and the silent-`undefined`
+  failure mode for a missing per-key FIELDS entry. (tcox)

package/knowledge/INDEX.md

@@ -28,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 7 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) — 8 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 10 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 11 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 11 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 8 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)

package/package.json

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