toga-ai 1.0.466 → 1.0.468

package/knowledge/1.0/apps/library/INDEX.md

@@ -9,7 +9,7 @@
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
-| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
+| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |

package/knowledge/1.0/apps/library/features/netsuite-item-isfulfillable-sync.md

@@ -6,15 +6,17 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-28
 owners: [bala]
 files:
   - library/app/netsuite.php
   - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php
 related:
   - toga2-api-client-and-bridge.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../worker/workflows/isfulfillable-multi-client-backfill.md
   - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
 ---
 
@@ -26,24 +28,43 @@ item** in the 2.0 platform. The client-facing copy is reached separately by the
 which walks the supply chain up from the source item. Only the source item is stamped here.
 
 ## Key files / entry points
-- `library/app/netsuite.php` — `App_NetSuite::getItemIsFulfillable($itemInternalId): bool|null`.
-  A SOAP `ItemSearchBasic` by internal id; returns the boolean (or `null` when unknown). Mirrors
-  the existing `getItemIsSerialized` exactly — the only prior item flag the sync read.
-- `library/app/api/toga2.php` — `getCreateItem` (~line 4364). During item create/update the sync
-  now reads `$isFulfillableItem = App_NetSuite::getItemIsFulfillable($nsItemInternalId)` and, when
-  **non-null**, stamps `$payload['isFulfillable']` on the create/update PUT|POST to api2. The
-  NetSuite internal id is resolved from the order line or from the part number
-  (`getItemInternalIdFromPartNumber` / `getItemGroupInternalIdFromPartNumber`). Stores
-  `c_netsuiteInternalItemId` on the item.
-- `worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php` — one-time backfill (see below).
+- `library/app/netsuite.php`
+  - `App_NetSuite::getItemIsFulfillable($itemInternalId): bool|null` — a SOAP `ItemSearchBasic` by
+    internal id; returns the boolean (or `null` when unknown). Mirrors `getItemIsSerialized`.
+  - `App_NetSuite::getItemSerializedAndFulfillable($itemInternalId)` — **combined lookup** returning
+    **both** flags from **one** `ItemSearchBasic` (serialized via `instanceof SerializedInventoryItem`,
+    fulfillable via the record's `isFulfillable`). `getCreateItem` now calls this once instead of the
+    two separate SOAP searches (`getItemIsSerialized` + `getItemIsFulfillable`) — halves the per-line
+    NetSuite round-trips now that the sync reads fulfillability for every line (see refresh below).
+- `library/app/api/toga2.php` — three item-creation paths now stamp `isFulfillable`:
+  - `getCreateItem` (~line 4364) — reads both flags via `getItemSerializedAndFulfillable` and, when
+    fulfillable is **non-null**, stamps `$payload['isFulfillable']` on the create/update PUT|POST. It
+    now also **refreshes the flag on EXISTING items** when NetSuite's value differs from the stored
+    value (not only on create), mirroring how the serialized flag works. Because the PUT is
+    diff-only, a re-sync with an unchanged value is a no-op. NetSuite internal id is resolved from the
+    order line or part number (`getItemInternalIdFromPartNumber` / `getItemGroupInternalIdFromPartNumber`);
+    stores `c_netsuiteInternalItemId`.
+  - `syncItemFulfillmentFromNetsuite` (~line 3562) and `syncInventoryAdjustmentFromNetsuite`
+    (~line 3882) — the two **other** direct `/items` creation paths now also stamp `isFulfillable` on
+    create. Previously only `getCreateItem` did, so items first created via these flows stayed **NULL**.
+- `worker/crons/toga2/netsuite/common_sync_togasupply.php` — `isFulfillable` was added to the bulk
+  `/items` GET field list so the existing-item refresh has the stored value to compare NetSuite's
+  against (without it, the refresh has nothing to diff).
+- `worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php` — one-time Compass backfill (see below).
+  The later **multi-client** catch-up lives in its own worker workflow doc
+  ([isFulfillable multi-client backfill](../../worker/workflows/isfulfillable-multi-client-backfill.md)).
 
 ## How it works
 1. Item sync resolves the NetSuite internal id for the item (order line, else part-number lookup).
-2. `getItemIsFulfillable` SOAP-searches the item and returns the flag.
-3. If non-null, `getCreateItem` adds `isFulfillable` to the item PUT/POST payload to api2. api2's
-   Items interceptor then propagates it up-chain (Phase 2).
-4. Going forward the **daily sync** handles new items automatically; existing items are caught up
-   by the one-time backfill.
+2. `getItemSerializedAndFulfillable` SOAP-searches the item **once** and returns both the serialized
+   and fulfillable flags.
+3. If fulfillable is non-null, `getCreateItem` adds `isFulfillable` to the item PUT/POST payload to
+   api2 — on **create**, and on **update** whenever the stored value differs from NetSuite's (the
+   existing-item refresh). api2's Items interceptor then propagates it up-chain (Phase 2). The two
+   other creation paths (`syncItemFulfillmentFromNetsuite`, `syncInventoryAdjustmentFromNetsuite`)
+   also stamp it on create.
+4. Going forward the **daily sync** handles new items and keeps existing items current (the refresh);
+   items that predate the feature are caught up by the one-time backfills.
 
 ### One-time backfill (July 5+ orders)
 `backfill_isfulfillable_jul5.php` catches up Agilant items on SalesOrders since **2026-07-05**:
@@ -85,6 +106,14 @@ nearly everything resolves to `fulfillable = 1`.**
   in `Client_Compass.Apis` (name `Agilant`) — never reproduce the secret value.
 
 ## Change history
+- 2026-07-28 — Code-review hardening: (1) `getCreateItem` now **refreshes `isFulfillable` on
+  existing items** when NetSuite's value differs (not create-only), mirroring the serialized flag;
+  diff-only PUT keeps re-syncs no-op. (2) The two other `/items` creation paths
+  (`syncItemFulfillmentFromNetsuite`, `syncInventoryAdjustmentFromNetsuite`) now also stamp the flag
+  on create — they previously left it NULL. (3) Added `isFulfillable` to the worker sync's bulk
+  `/items` GET field list so the refresh has a stored value to diff. (4) New combined
+  `App_NetSuite::getItemSerializedAndFulfillable` returns both flags from one `ItemSearchBasic`, so
+  `getCreateItem` no longer makes two SOAP searches per line. (bala)
 - 2026-07-20 — Added `App_NetSuite::getItemIsFulfillable` (SOAP `ItemSearchBasic`, mirrors
   `getItemIsSerialized`) and wired `getCreateItem` to stamp `isFulfillable` on the item PUT/POST to
   api2 when non-null (internal id from order line or part-number lookup; stores
@@ -100,3 +129,5 @@ nearly everything resolves to `fulfillable = 1`.**
 - [NetSuite → TOGa Supply Per-Client Sync](../../worker/features/netsuite-togasupply-per-client-sync.md)
   — the sync engine this item flag rides in.
 - [Phase 2 — isFulfillable propagation up the SO↔PO chain (2.0)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md).
+- [isFulfillable multi-client backfill (worker)](../../worker/workflows/isfulfillable-multi-client-backfill.md)
+  — the cross-client catch-up cron and its client-DB / catalog-matching gotchas.

package/knowledge/1.0/apps/worker/INDEX.md

@@ -10,4 +10,5 @@
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
+| [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/workflows/isfulfillable-multi-client-backfill.md

@@ -0,0 +1,90 @@
+---
+title: isFulfillable Multi-Client Backfill (all togasupply clients)
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-07-28
+owners: [bala]
+files:
+  - worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php
+  - library/app/api/toga2.php
+related:
+  - ../features/netsuite-togasupply-per-client-sync.md
+  - ../../library/features/netsuite-item-isfulfillable-sync.md
+  - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
+  - ../../../clients/compass-usa/profile.md
+---
+
+## Summary
+One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17
+togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health, ERAU, GroWrk, NYC Health +
+Hospitals, Masonite, Miami-Dade, NCCI, Prudential, Quad, SBA, SHRSS, S&P Global, Trividia Health,
+and Compass). It is the multi-client successor to the Compass-only `backfill_isfulfillable_jul5.php`
+(see the [Phase 1 library doc](../../library/features/netsuite-item-isfulfillable-sync.md)). Like that
+one, it re-PUTs each Agilant **source** item to api2 `/items` so the **api2 interceptor does the
+recursive up-chain propagation** — it never writes the DB directly and never walks the chain itself.
+
+## Steps (how the cron runs)
+1. **Scope each client's Agilant-catalog items directly from that client's DB** — NOT via api2 —
+   keyed by `c_netsuiteInternalItemId`. Direct DB is required because that field is not an api2 GET
+   field (see gotchas). The Agilant catalog is matched by **`Catalogs.name = 'Agilant'`**, not by id.
+2. **Read `isFulfillable` from NetSuite by internal id** via SuiteQL `WHERE id IN (...)`, **cached
+   across clients** so a shared internal id is fetched once for the whole run.
+3. **PUT each source item to api2 `/items`** (`App_Api_Toga2::send`). The Items interceptor then
+   propagates the value up the SO↔PO chain onto every client-facing item (Phase 2).
+4. **Per-client scoping rule:**
+   - **Compass** — limited to orders since a cutoff (~**2026-06-20**); it was already partly
+     backfilled and only orders after that had correct chain linkage to propagate up to the client
+     items.
+   - **Every other client** — takes **ALL** its Agilant items (never previously backfilled).
+5. **Resilience:** clients whose DB read fails are **skipped and reported**, not fatal. Supports
+   `DRY_RUN`, `DB_HOST_PREFERENCE` (`localhost` / `writer.client` / `sandbox-dev`), and
+   `API_ENDPOINT_OVERRIDE` (the **9th arg** of `App_Api_Toga2::send`) so the run can target prod or a
+   beta/sandbox endpoint.
+
+## Gotchas / known issues
+- **Agilant catalog is matched by NAME, not id.** `Catalogs.name = 'Agilant'` is stable across every
+  client, but the `catalogId` **differs per client** — **Quad = 2, all other clients = 1** (verified
+  across all 17 client DBs). Hardcoding `catalogId = 2` would silently hit only Quad and miss the
+  other 16. Always resolve the catalog by name.
+- **`c_netsuiteInternalItemId` is NOT an api2 GET field** — there is no `Core.RecordField` for it, so
+  it can only be read by direct DB query. That is why the backfill scopes items via direct DB reads
+  rather than an api2 `/items` GET.
+- **Client DB names don't always follow the client identifier.** Compass's identifier is
+  `Compass_Usa` but its database is **`Client_Compass`**. All client DBs live on **one cluster**
+  (prod `prod-client`), so a single host/user/pass with a swapped **database name** reaches them all.
+- **⚠ Environment must be fully deployed, or the backfill can't propagate.** PUTting `isFulfillable`
+  to `api.beta.togahub.com` returns **EV-9 "no write permission"** — the field exists but the write
+  ACL was never deployed there (only `dev-sandbox` had field + interceptor + ACL). The Core
+  RecordField, the `ApiPayloadInterceptors` rows, **and** the client column + write ACL must all be
+  present on the **same** environment, and the run must scope from that same cluster. Deploy order:
+  dbchanges (field/ACL/interceptors) before running the backfill. See the
+  [Phase 2 deploy gotchas](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md).
+- **🔐 Credentials.** The cron reuses the per-client api uuids/secrets already embedded in the
+  `sync_togasupply_*` crons; the api secrets live in each `Client_<client>.Apis` (name `Agilant`) —
+  never reproduce a secret value in code or docs.
+
+## Run status
+- 2026-07-28 — Ran across all NetSuite/togasupply clients. Compass scoped to orders after
+  ~2026-06-20 (only those had correct chain linkage to propagate up to the client items); every other
+  client backfilled from all its Agilant items.
+
+## Change history
+- 2026-07-28 — Built and ran the multi-client `backfill_isfulfillable_all_clients.php`: direct
+  client-DB scoping of Agilant-catalog items (matched by `Catalogs.name`, not id) keyed by
+  `c_netsuiteInternalItemId`, NetSuite reads by internal id (cached across clients), re-PUT to api2 so
+  the interceptor recurses. Per-client scope (Compass ~post-2026-06-20, all others full), DRY_RUN /
+  DB_HOST_PREFERENCE / API_ENDPOINT_OVERRIDE knobs, failed-DB clients skipped + reported. Recorded the
+  catalog-by-name (Quad catalogId=2), `c_netsuiteInternalItemId`-not-a-GET-field, Compass DB-name, and
+  beta EV-9 deploy-gap gotchas. (bala)
+
+## Related docs
+- [isFulfillable from NetSuite during item sync (Phase 1, library)](../../library/features/netsuite-item-isfulfillable-sync.md)
+  — where the value is sourced and the earlier Compass-only backfill.
+- [isFulfillable propagation up the SO↔PO chain (Phase 2, _underscore)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md)
+  — the api2 interceptor this backfill relies on to do the recursion.
+- [NetSuite → TOGa Supply Per-Client Sync](../features/netsuite-togasupply-per-client-sync.md)
+  — the steady-state sync whose credentials/config this backfill reuses.

package/knowledge/2.0/apps/_underscore/features/fulfillable-item-propagation.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-28
 owners: [bala]
 files:
   - _underscore/Model/Client/Item.php
@@ -50,7 +50,14 @@ same bridge topology, walked for a different payload (a scalar flag rather than
    one-time backfill) send that field, so day-to-day item edits skip the walk entirely.
 2. **Load the source item** by uuid → `id` + `isFulfillable`. If the value is **NULL**, return
    (nothing authoritative to propagate).
-3. **Walk the chain UP** with a `WITH RECURSIVE ChainSalesOrderItems` CTE:
+   - **Writer-routed (read-your-writes).** Both this source read **and** the chain-walk CTE below
+     call `->setisReadHostEnabled(false)` so they execute on the **writer**, not a read replica.
+     `_Query` routes SELECTs to a read replica by default (`Query.php` ~line 273) — a separate
+     connection that cannot see this request's still-open write transaction and can lag replication,
+     so a replica read could return the *pre-write* value (or NULL for a brand-new item) and
+     propagate the wrong value or skip. The UPDATE was already writer-routed; now read + update share
+     the one request transaction.
+3. **Walk the chain UP** with a `WITH RECURSIVE ChainSalesOrderItems` CTE (also writer-routed, see above):
    - **Anchor:** `SalesOrderItems WHERE itemId = <sourceItemId>`.
    - **Recursive step:** join `PurchaseOrderItems_SalesOrderItems` (PSO) then
      `SalesOrderItems_PurchaseOrderItems` (SPO) to climb one tier
@@ -93,6 +100,20 @@ uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfilla
 - Engine itself is shared `_Model_Client_Item` logic; any client with the schema present gets it.
 
 ## Gotchas / known issues
+- **⚠ Propagation reads MUST be writer-routed.** `_Query` SELECTs default to a read replica
+  (`Query.php` ~line 273), a separate connection that can't see the current request's open write
+  transaction and may lag replication. The interceptor runs inside the write request, so a
+  replica-routed read here can see the **pre-write** value (or NULL on a just-created item) and
+  propagate wrongly or skip. Both SELECTs in `propagateFulfillableAcrossChain` therefore set
+  `setisReadHostEnabled(false)`. Any future read added to an interceptor that must see the same
+  request's writes needs the same treatment.
+- **⚠ Beta deploy gap — EV-9 "no write permission" (write ACL not deployed).** PUTting
+  `isFulfillable` to `api.beta.togahub.com` returns **EV-9**: the field *exists* there but its write
+  ACL was never deployed (only `dev-sandbox` had the full field + interceptor + ACL from earlier
+  work). The three pieces — Core RecordField, `ApiPayloadInterceptors` rows, **and** the client
+  column + write ACL — must all be present on the **same** environment (and a backfill run must scope
+  from that same cluster) or the write is rejected and nothing propagates. Reinforces the deploy-order
+  dependency: dbchanges (field + ACL + interceptors) before the code/backfill that writes the field.
 - **⚠ Interceptors are DB-driven.** The `postPost`/`postPut` PHP does nothing without the
   `ApiPayloadInterceptors` rows in the **target env's Core DB**. Missing rows → the hook never
   fires **and** api2 EV-8's the unknown `isFulfillable` field, **403-ing the whole request** (not
@@ -108,6 +129,12 @@ uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfilla
   vs. using `itemtype` to hide services — is **pending product confirmation**.
 
 ## Change history
+- 2026-07-28 — Fixed a **read-replica routing** bug: `propagateFulfillableAcrossChain`'s source-item
+  read and the recursive chain-walk CTE now `setisReadHostEnabled(false)` so they run on the writer
+  and see the request's own open write transaction (read-your-writes) — a replica read could return
+  the pre-write value or NULL and propagate wrongly/skip. Recorded the **beta EV-9 write-ACL deploy
+  gap** (field present but write ACL undeployed on `api.beta.togahub.com`; all three deploy pieces
+  must land on the same env). (bala)
 - 2026-07-20 — Built the isFulfillable up-chain propagation engine:
   `propagateFulfillableAcrossChain` + the payload-gated `postPost`/`postPut` interceptor on Items
   (recursive SOI↔POI CTE, diff-only `UPDATE`), plus the Compass `parent::` fix so the price-override

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

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 14 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 16 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 17 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 10 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/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.468",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",