toga-ai 1.0.615 → 1.0.617

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

@@ -5,6 +5,7 @@
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
 | [Cart 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 Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. | toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/api/CartApi.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 |
 | [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP | toga2-commerce/src/App.tsx, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |
 | [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one | src/pages/Filter/api/FilterApi.ts, src/pages/Filter/viewModel/useFilterViewModel.ts, api2/Component/Api/V2/V2.php, toga2-supply/src/pages/Items/api/itemsApi.ts |
@@ -14,6 +15,7 @@
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | An item with **`Items.isActive = 0`** must not be viewable, addable to a cart, or orderable **as a standalone line** on the storefront — but the **same flag is | toga2-commerce/src/utils/checkIsItemPurchasable.ts, toga2-commerce/src/api/fetchItemsActiveStatus.ts, toga2-commerce/src/hooks/useCartReconciliation.ts, toga2-commerce/src/stores/useCartStoreZu.ts, toga2-commerce/src/pages/ItemsView/api/ItemsApi.ts, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts, toga2-commerce/src/pages/ItemsView/ItemViewPage.tsx, toga2-commerce/src/components/AuthLayout/AuthLayout.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartTableBundleItem.tsx, toga2-commerce/src/api/syncSalesOrderFromApiToLocalStorage.ts, _underscore/Model/Compass/SalesOrder.php, dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql |
 | [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 |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | Submitting an order from the cart fires **two independent sync routines** — one for the sales-order header (`syncSalesOrderData`) and one for the line items (`s | toga2-commerce/src/pages/OrderDetails/hooks/useSubmitOrder.ts, toga2-commerce/src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts, toga2-commerce/src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
+| [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | On the toga2-commerce **Cart** page, a shipping option's **cost** can be waived by config using the same `PrimaryItemShippingRule` vocabulary that drives expedi | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [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 |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | When a Chromium browser (Chrome / Edge) shows **`ERR_HTTP2_PROTOCOL_ERROR`** loading a `*.togacommerce.com` tenant for **one client/network but works for the TO |  |

package/knowledge/2.0/apps/toga2-commerce/features/cart-order-total-computation.md

@@ -0,0 +1,57 @@
+---
+title: Cart Order-Total & Shipping Computation
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-19
+owners: [apeterson]
+files:
+  - toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts
+  - toga2-commerce/src/pages/Cart/CartPage.tsx
+  - toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx
+  - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/api/CartApi.ts
+related:
+  - 2.0/apps/toga2-commerce/features/shipping-cost-waiver-gating.md
+  - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+---
+
+## Summary
+The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from
+`cartData`. `cartData.total` is computed in `useCartViewModel` as `subtotal + tax + shipping`,
+where `shipping` is read from `salesOrder.shipping` in the zustand cart/sales-quote store —
+**not** directly from the selected dropdown option. A `CartPage` effect is the bridge: it
+watches the selected shipping method, looks up the matching fetched option, reads its `c_cost`,
+applies waiver cost-gates, and calls `setShipping()` to write `salesOrder.shipping`.
+
+## How it works
+1. `CartForm.tsx` renders the summary purely from `cartData` (subtotal/shipping/tax/total).
+2. `useCartViewModel.ts` computes `cartData.total = subtotal + tax + shipping`, with `shipping`
+   derived from `salesOrder.shipping` (zustand store).
+3. `CartPage.tsx` has an effect watching the selected `shippingMethod`: it finds the matching
+   fetched option, reads `c_cost`, applies waiver cost-gates (see
+   [shipping-cost-waiver-gating](shipping-cost-waiver-gating.md)), then `setShipping()` writes
+   `salesOrder.shipping`. So the dropdown never feeds the total directly — it flows through the
+   store.
+
+## Gotchas
+- **`c_cost` is ACL-gated per tenant, and a missing grant silently zeroes shipping.** Only the
+  **Compass USA** CARTPAGE configs request fields `["uuid","name","c_cost"]` in
+  `fetchShippingMethod`. **Compass Canada** and **Quad** request only `["uuid","name"]`, so
+  their fetched options carry no `c_cost`; `Number(undefined) → NaN → "0"`, and shipping falls
+  back to `"0"` with no error. This is a **latent gap** for those tenants — if they are meant to
+  charge shipping, their CARTPAGE `fetchShippingMethod` field list must include `c_cost`.
+- **Shipping lives in the store, not the dropdown.** Reading the selected option's cost alone
+  will not tell you the order total — always trace through `setShipping()` →
+  `salesOrder.shipping` → `useCartViewModel`.
+
+## Change history
+- 2026-08-19 — Documented the previously-undocumented cart total/shipping computation path
+  while fixing the Compass USA Standard Ground waiver. Recorded the `c_cost` ACL-gating latent
+  gap for Compass Canada and Quad (their fetched options have no `c_cost`, so shipping silently
+  resolves to "0"). (apeterson)
+</content>

package/knowledge/2.0/apps/toga2-commerce/features/expedited-shipping-gating.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-27
-owners: [tcox]
+updated: 2026-08-19
+owners: [tcox, apeterson]
 files:
   - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
   - toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts
@@ -27,8 +27,12 @@ selected expedited method auto-resets to **"Standard Ground"**. The behavior is
 driven** — a tenant opts in per shipping-method field via an `optionGates` entry; there is no
 `if (clientSlug === ...)` branching. Omitting `optionGates` means expedited is always shown.
 
-Applies today to all three tenants: **COMPASS**, **COMPASSCANADA** (English + French), and
-**QUAD**.
+Applies today to: **COMPASS** (USER/MANAGER/SUPERUSER — **not ADMIN**, see below),
+**COMPASSCANADA** (English + French), and **QUAD**. Because configs are **per role**
+(`.../FIELDS/<CLIENT>/<LANG>/<ROLE>/CARTPAGE.ts`), opting a single role out of the gate is done
+by dropping `optionGates: [EXPEDITED_SHIPPING_GATE]` from that one role's shipping-method field —
+no shared-logic or client-branching change. **Compass USA ADMIN** now omits the gate, so admins
+always see every method (Standard Ground + both expedited) in both regular and edit-order mode.
 
 ## Key files / entry points
 - `src/pages/Cart/helpers/shippingOptionGates.ts` (NEW) — pure helpers + types:
@@ -40,8 +44,10 @@ Applies today to all three tenants: **COMPASS**, **COMPASSCANADA** (English + Fr
   `EXPEDITED_SHIPPING_GATE` config constant: `optionNames` `["2nd Day EOB","Next Day Air"]`,
   `visibleWhen { item: "primaryItem", path: "item.itemCategory.name", operator: "equals",
   value: "COMPUTERS" }`.
-- 15 `CARTPAGE.ts` files (COMPASS x4 roles, COMPASSCANADA ENGLISH x4 + FRENCH x4, QUAD x3) —
-  each shipping-method field opts in via `optionGates: [EXPEDITED_SHIPPING_GATE]`.
+- `CARTPAGE.ts` files (COMPASS USER/MANAGER/SUPERUSER — **ADMIN opted out**, COMPASSCANADA
+  ENGLISH x4 + FRENCH x4, QUAD x3) — each shipping-method field opts in via
+  `optionGates: [EXPEDITED_SHIPPING_GATE]`. `COMPASS/ENGLISH/ADMIN/CARTPAGE.ts` intentionally
+  omits it (and its now-unused import).
 - `src/pages/Cart/view/cartForm/CartForm.tsx` — filters `shippingMethodOptions` through the
   gates (reactive on `cartData.cartBundles`) before the select renders; resolves the shipping
   field via `findShippingMethodField`; uses `SHIPPING_OPTION_LABEL_SEPARATOR` for the
@@ -103,6 +109,18 @@ behavior is expressed in config, not in code branches.
   on that doc's slice-2 work-list.
 
 ## Change history
+- 2026-08-19 — **Compass USA ADMIN role opted out of the expedited gate.** Removed
+  `optionGates: [EXPEDITED_SHIPPING_GATE]` (and the now-unused import) from
+  `COMPASS/ENGLISH/ADMIN/CARTPAGE.ts`, so admins always see Standard Ground + Next Day Air +
+  2nd Day EOB in both regular commerce mode **and** edit-order mode. Because configs are per
+  role, dropping the gate on the ADMIN config alone is the scoped customization — no
+  shared-logic or client-branching change. Side effect: in edit-order mode an existing order's
+  expedited selection is no longer hidden/reset to Standard Ground for admins.
+  USER/MANAGER/SUPERUSER still gate expedited behind a computer kit. (apeterson)
+- 2026-08-19 — No change to expedited visibility. Noted that the shared shipping-rule type
+  gained an optional `requireNoOtherItemsInKit` flag (+ `bundleHasOtherItems()` helper) used by
+  the separate Standard Ground cost waiver — see
+  [shipping-cost-waiver-gating](shipping-cost-waiver-gating.md). (apeterson)
 - 2026-07-27 — No behavior change. Noted that a cart Cypress e2e harness now exists and a
   gating + guardrail-modal spec is feasible (the `cart/fetchUserShippingMethods.json` fixture
   already ships the gated names with no `c_cost`); it is on the slice-2 work-list. Linked

package/knowledge/2.0/apps/toga2-commerce/features/shipping-cost-waiver-gating.md

@@ -0,0 +1,93 @@
+---
+title: Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-19
+owners: [apeterson]
+files:
+  - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/CartPage.tsx
+related:
+  - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - 2.0/apps/toga2-commerce/features/cart-order-total-computation.md
+  - ../../../../clients/compass-usa/profile.md
+---
+
+## Summary
+On the toga2-commerce **Cart** page, a shipping option's **cost** can be waived by config
+using the same `PrimaryItemShippingRule` vocabulary that drives expedited-option visibility.
+The **Compass USA** carts attach a cost gate `STANDARD_GROUND_FREE_FOR_COMPUTER_KITS` to the
+*Shipping Method* field so that **Standard Ground** ships free for a bare computer kit. The
+waiver is config-driven (no `if (clientSlug === ...)` branching) and is referenced only by the
+four Compass USA role configs (USER/ADMIN/MANAGER/SUPERUSER).
+
+## Key files / entry points
+- `src/pages/Cart/helpers/shippingOptionGates.ts` — `PrimaryItemShippingRule` type,
+  `evaluateShippingOptionRule`, and the `bundleHasOtherItems()` helper.
+- `src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts` — the
+  `STANDARD_GROUND_FREE_FOR_COMPUTER_KITS` gate constant (primary item
+  `itemCategory.name === "COMPUTERS"`, with `requireNoOtherItemsInKit: true`).
+- `src/pages/Cart/CartPage.tsx` — the effect that reads the selected option's `c_cost` and
+  applies waiver cost-gates before calling `setShipping()` (see
+  [cart-order-total-computation](cart-order-total-computation.md)).
+
+## How it works
+1. A cost gate matches a bundle when its **primary item** (`bundleItemGroup.slug === "primary"`)
+   satisfies the `{ item, path, operator, value }` rule — here
+   `item.itemCategory.name === "COMPUTERS"`.
+2. The **optional `requireNoOtherItemsInKit` flag** on `PrimaryItemShippingRule` narrows the
+   match: when set, the bundle qualifies only if the primary item matches **and** the kit has
+   no other items. `bundleHasOtherItems()` returns true when `bundleProgressContents` contains
+   any entry whose `bundleItemGroup.slug !== "primary"` (fees are already excluded from
+   `bundleProgressContents` upstream).
+3. `evaluateShippingOptionRule` qualifies a bundle only when the primary item matches AND, if
+   `requireNoOtherItemsInKit` is set, the kit is bare. Existing cart-wide "any qualifying
+   bundle" semantics for multi-bundle carts are preserved.
+4. When the selected method qualifies, the effect in `CartPage` waives its `c_cost` to 0 before
+   writing `salesOrder.shipping`.
+
+Resulting Compass USA behavior (full truth table, confirmed complete — no further code change):
+- **Solo computer kit on Standard Ground** → **$0** (waived; the freight is covered by the
+  `LT-FREIGHT` fee). "Solo" is scoped to the **kit** (`bundleProgressContents` has no non-primary
+  items), not the whole order.
+- **Computer kit WITH other items in the kit, or any non-computer kit** → charged Standard
+  Ground **$10** (not waived).
+- **Expedited (Next Day Air / 2nd Day EOB) + computers** → charged the method's `c_cost`
+  (2nd Day **$50**, Next Day **$100**), **never waived**.
+
+All dollar amounts live in **`ShippingMethods.c_cost` in the Compass USA client DB** (developer
+confirmed correct), **not** in frontend code — the waiver logic only zeroes a `c_cost`, it never
+sets a price.
+
+## Gotchas
+- **The waiver only means what the flag says.** Before this fix the gate had no
+  `requireNoOtherItemsInKit`, so Standard Ground (the default selection) was waived for **any**
+  cart whose primary bundle item was in `COMPUTERS` — computer kits loaded at $0 shipping and
+  stayed there regardless of what else was in the kit. Always set `requireNoOtherItemsInKit`
+  when a waiver is meant only for a bare kit.
+- **`bundleProgressContents` is the source of truth for "other items"** — it already excludes
+  fees, so a fee line does not make a kit count as "having other items." If that upstream
+  exclusion ever changes, the waiver's narrowing changes with it.
+- **Waiver correctness depends on `COMPUTERS` categorization**, same as the expedited gate —
+  a computer kit mis-categorized in the catalog will neither waive nor gate.
+
+## Change history
+- 2026-08-19 — Confirmed the Compass USA shipping-charge truth table is fully satisfied by the
+  existing logic (no code change): solo computer kit on Standard Ground → $0 (waived, covered by
+  `LT-FREIGHT`); kit with other items or any non-computer kit → $10; expedited + computers →
+  method `c_cost` (2nd Day $50 / Next Day $100), never waived. Documented that all dollar amounts
+  live in `ShippingMethods.c_cost` in the Compass USA client DB, not in frontend code, and that
+  "solo computer" is scoped to the kit not the order. (apeterson)
+- 2026-08-19 — Fixed an over-broad Standard Ground waiver for Compass USA computer-kit carts:
+  added the optional `requireNoOtherItemsInKit` flag on `PrimaryItemShippingRule` and the
+  `bundleHasOtherItems()` helper, and set the flag on
+  `STANDARD_GROUND_FREE_FOR_COMPUTER_KITS`. Bare computer kits now ship free; kits with other
+  items are charged. Config-driven, Compass USA only, no client branching. No test harness in
+  the repo (no vitest/jest); verified by review. (apeterson)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -29,7 +29,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) — 9 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 17 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 19 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) — 9 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.615",
+  "version": "1.0.617",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",