toga-ai 1.0.465 → 1.0.467

package/knowledge/1.0/apps/tools/features/talos-kb-documents-admin.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-28
 owners: [jcardinal]
 files:
   - tools/mvc/talos/kb-documents/get.php
@@ -108,7 +108,7 @@ Vectors** (the canonical design — see the architecture note below), and the fl
 3. **S3 Vectors store** — create a dedicated vector bucket + index via
    `App_Talos_Bedrock::createVectorStore()`, capturing the authoritative **`indexArn`**.
 4. **VECTOR KB** — `createKnowledgeBase($bedrock, $slug, $indexArn)` (VECTOR + `S3_VECTORS`
-   storage).
+   storage), **tagged** with the mandatory `App_Talos_Bedrock::KB_TAGS` pair (see below).
 5. **wait for `ACTIVE`** (`waitForKnowledgeBaseActive`).
 6. **S3 data source** — plain `S3` connector + `BEDROCK_DATA_AUTOMATION` parsing.
 7. **`Team.KnowledgeBases`** (`db_team`, Team MySQL cluster).
@@ -163,8 +163,16 @@ orphaned KB).
   float32, euclidean), then **polls `getIndex` for the authoritative index ARN** with a short
   `NotFound` retry; returns an actionable error on `Conflict`/`AlreadyExists` from an orphaned
   prior attempt.
+- **`KB_TAGS`** — the **mandatory** tag pair stamped on every new KB:
+  `['tenant' => 'True', 'model_role' => 'knowledge_base']`. Passed as the top-level `'tags'`
+  parameter of `CreateKnowledgeBase`. Casing is load-bearing: capital-T **`True`**, snake_case
+  **`model_role`**. Verified against the live `development-team-toga-desk` KB (`ZOLCCQZZL1`) with
+  `aws bedrock-agent list-tags-for-resource --resource-arn
+  arn:aws:bedrock:us-east-1:654654170868:knowledge-base/ZOLCCQZZL1 --region us-east-1`. These tags
+  drive **cost allocation and model-inventory reporting** in the togaiq account — an untagged KB is
+  invisible to those reports.
 - `createKnowledgeBase($bedrock, string $slug, string $indexArn)` — creates the VECTOR KB with
-  `S3_VECTORS` storage (signature now takes the index ARN).
+  `S3_VECTORS` storage (signature takes the index ARN) and applies `KB_TAGS`.
 - `waitForKnowledgeBaseActive()` polls `getKnowledgeBase` every `WAIT_INTERVAL_SECONDS` (3s)
   up to **`WAIT_MAX_SECONDS` = 300**. Exits immediately on `ACTIVE`/`FAILED`. 300s sits well
   under the 900s Apache/PHP ceiling.
@@ -191,6 +199,12 @@ orphaned KB).
   `iam:PassRole` on the shared role. Its bedrock create actions were already covered by
   `AmazonBedrockFullAccess` and S3 by `AmazonS3FullAccess`. **`s3vectors` is a SEPARATE service
   NOT covered by `AmazonBedrockFullAccess`** — that was the real missing grant.
+- **⚠ `bedrock:TagResource` (new, NOT yet verified as granted).** AWS authorizes
+  **tagging-on-create separately from the create action itself**. Now that `createKnowledgeBase()`
+  sends `tags`, the `bedrock-model-accessor` user must also hold **`bedrock:TagResource`** on the
+  knowledge-base resource, or `CreateKnowledgeBase` fails with `AccessDeniedException` — even
+  though the *identical call without tags* would have succeeded. Confirm this grant with devops
+  **before the next real KB creation** (see the orphaned-vector-bucket gotcha).
 
 ## Helpers
 
@@ -277,6 +291,17 @@ orphaned KB).
   `Conflict`/`AlreadyExists` on the vector bucket (surfaced as an actionable error) or creates a
   **duplicate** Bedrock KB (Bedrock allows same-name KBs with new ids). After a failed create:
   delete the orphaned vector store + KB and re-run clean, or finish the DB rows manually.
+- **Tagging on create needs its own IAM permission, and failing it orphans a vector bucket.**
+  `bedrock:TagResource` is authorized separately from `CreateKnowledgeBase`. Because the KB is
+  created at **step 4 — after** the S3 Vectors bucket + index (step 3) — a missing `TagResource`
+  grant aborts the flow leaving an **orphaned `bedrock-knowledge-base-{slug}` vector bucket with
+  no KB and no DB rows**, and retrying the same slug then hits `Conflict`/`AlreadyExists`. If a
+  create suddenly starts failing `AccessDeniedException` right after the vector store succeeds,
+  suspect this permission first — not the tag values.
+- **Only the Bedrock KB is tagged — the per-KB S3 Vectors bucket is deliberately NOT.** Scope
+  decision (2026-07-28): `createVectorStore()` leaves `bedrock-knowledge-base-{slug}` untagged.
+  Known gap: the vector bucket is a **separate billable resource**, so vector-storage cost is not
+  attributed by `tenant`/`model_role`. Revisit if cost reporting needs it.
 - **Two prior KBs use the WRONG (fully-MANAGED) type.** `development-team-craftex` and
   `development-team-toga-desk` were created by the earlier MANAGED code and were **intentionally
   left as-is** (this session's scope was code-only). They should be **recreated later** to match
@@ -296,6 +321,14 @@ orphaned KB).
 
 ## Change history
 
+- 2026-07-28 — **Every new Bedrock KB is now tagged** `tenant=True` + `model_role=knowledge_base`
+  via the new `App_Talos_Bedrock::KB_TAGS` constant, passed as the `tags` parameter of
+  `CreateKnowledgeBase` (required for togaiq cost allocation / model-inventory reporting; values
+  and casing verified against the live `toga-desk` KB `ZOLCCQZZL1`). **New IAM prerequisite:**
+  tagging-on-create needs `bedrock:TagResource` on the `bedrock-model-accessor` user — *not yet
+  verified as granted*; without it `CreateKnowledgeBase` returns `AccessDeniedException` and, with
+  no rollback, orphans the already-created S3 Vectors bucket. Scoped decision: the per-KB S3
+  Vectors bucket is left **untagged**, so vector-storage cost is not attributed. (jcardinal)
 - 2026-07-16 — **Corrected the KB-create architecture from MANAGED to VECTOR + S3 Vectors**
   (the canonical design, from `development-team-dunn`; the earlier code was modeled on the WRONG
   `craftex`/MANAGED KB). Rewrote `App_Talos_Bedrock`: KB is now `VECTOR` + `S3_VECTORS` storage;

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.465",
+  "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",