toga-ai 1.0.449 → 1.0.451

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -6,7 +6,7 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |
-| [_ApiRequest ENCODE__JSON now sends Content-Type: application/json](features/apirequest-json-content-type.md) | `_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set a `Content-Type` header. | _underscore/ApiRequest.php |
+| [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |

package/knowledge/2.0/apps/_underscore/features/apirequest-json-content-type.md

@@ -1,21 +1,27 @@
 ---
-title: _ApiRequest ENCODE__JSON now sends Content-Type: application/json
+title: "_ApiRequest — JSON encode/decode & api-logging behavior"
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
+updated: 2026-07-28
 owners: ["jcardinal"]
 files:
   - _underscore/ApiRequest.php
 related:
   - ../../worker2/features/oneuptime-worker2-monitoring.md
+  - ../../worker2/features/creating-worker-actions.md
+  - ../../worker2/features/talos-transcript-ingestion.md
 ---
 
 ## Summary
-`_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set
+`_ApiRequest` is the 2.0 outbound HTTP client. This doc collects its non-obvious
+encode/decode/retry/logging behavior that callers keep getting bitten by; the original subject
+was the Content-Type fix below.
+
+**Original fix (2026-07-14):** `_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set
 a `Content-Type` header. cURL therefore defaulted to `application/x-www-form-urlencoded`, and
 receivers parsed the entire JSON string as a single form-field NAME — observed at OneUptime as
 `{"<json>":""}`. Every 2.0 `ENCODE__JSON` POST/PUT/PATCH caller was silently shipping
@@ -30,10 +36,40 @@ case-insensitive scan of already-set headers, so a caller-supplied `Content-Type
 - This changes the wire format of ALL existing `ENCODE__JSON` callers (they were previously
   sending form-urlencoded). This is a correction, but smoke-test heavy JSON callers post-deploy:
   ClickUp, NetSuite, Vapi.
+- **`execute()` decodes a JSON response with `json_decode($payload)` — NO assoc flag — so you
+  get `stdClass`, not an array.** Code that indexes the response as `$res['result']['x']` breaks.
+  If a caller needs arrays, don't rely on the built-in decode: leave the response handling local
+  (`json_decode($response, true)`).
+- **`ENCODE__JSON` re-encodes the payload without `JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE`.**
+  For large non-ASCII bodies (e.g. a full meeting transcript) this inflates every such char to
+  `\uXXXX`. To preserve the exact wire bytes, `json_encode` with the flags you want yourself and
+  pass the **ready JSON string with payloadEncoding left null**.
+- **`setAutoRetry()` is flat-delay and retries EVERY non-2xx.** If you need exponential backoff
+  or fail-fast on 4xx (other than 429), keep your own retry loop and construct one `_ApiRequest`
+  per attempt — that also gives you one api-log row per attempt.
+- **Transport failures surface as a thrown Exception** from `execute()` (the equivalent of
+  `curl_error()`), not a return value. Catch it if your method has an error-return contract.
+- **Api logging depends on `DB_CLIENT_LOGS` being registered.** The logging branch writes via
+  `_Model_Client_Logs_Api`, whose `DATABASE` const is `_underscore::DB_CLIENT_LOGS`. In a context
+  that hasn't registered it (most workers, CLI harnesses) logging is a **silent no-op** — or
+  throws `Unknown database 'ClientLogs'`. Either register the logs DB under that alias or pass
+  `setLogging(false)` deliberately. See
+  [Creating Worker Actions](../../worker2/features/creating-worker-actions.md#gotchas).
+- **OPEN / not fixed: logging happens in two halves around the HTTP call.** `execute()` inserts
+  the request row and **commits before** the call, then `save()`s the response fields **after**.
+  For long calls (e.g. a 600s AI timeout) that second save runs on a connection idle for
+  minutes — the classic stale-connection failure mode — leaving api-log rows with null
+  `responseCode`/`responsePayload`. The correct fix (reconnect/re-register before the post-call
+  save) lives **inside `execute()`** and would affect every framework caller, so it is deferred
+  pending architecture review. Do **not** work around it per-caller.
 
 ## Change history
+- 2026-07-28 — Broadened from the Content-Type fix to the general `_ApiRequest` contract:
+  documented the non-assoc `json_decode` response (returns `stdClass`), the `ENCODE__JSON`
+  re-encode losing `JSON_UNESCAPED_*`, `setAutoRetry()`'s flat-delay/retry-all behavior,
+  exception-on-transport-failure, the `DB_CLIENT_LOGS` dependency for api logging, and the
+  **open** two-phase logging / stale-connection issue on long calls. Surfaced migrating
+  `worker2 Worker/Team/Transcripts.php::callTalosEndpoint()` off raw curl. (jcardinal)
 - 2026-07-14 — Fixed `ENCODE__JSON` to send `Content-Type: application/json` (guarded so a
   caller-set Content-Type wins). Root-caused via OneUptime receiving `{"<json>":""}`. Affects
   all 2.0 ENCODE__JSON callers. (jcardinal)
-</content>
-</invoke>

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

@@ -10,3 +10,4 @@
 | [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 |
 | [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/features/cart-notification-emails.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
-owners: ["bala"]
+updated: 2026-07-27
+owners: ["bala", "tcox"]
 files:
   - src/pages/Cart/CartPage.tsx
   - src/pages/Cart/view/cartForm/CartForm.tsx
@@ -17,6 +17,7 @@ files:
 related:
   - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
   - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
 ---
 
 ## Summary
@@ -72,10 +73,18 @@ the message resolves to `undefined` and renders blank.
 - Adding the label to only some `CARTPAGE.ts` files leaves other client/role/language users with a
   blank message.
 - Do not use a toaster or `setError` (red) for this — product wants the sapphire info style.
+- **Now pinned by e2e.** `cypress/e2e/cartPage/cartV2.cy.ts` covers both the auto-population
+  (order-for user + supervisor emails, protected rows unremovable) and the case-insensitive
+  duplicate block surfacing the *"This email has already been added"* banner. These are exactly
+  the parity behaviors the config-cart refactor spike silently lost, so keep the spec green when
+  touching this flow (see [cypress-testing](../workflows/cypress-testing.md)).
 
 ## Change history
+- 2026-07-27 — No behavior change. This duplicate-prevention UX (email auto-population +
+  case-insensitive duplicate banner) is now covered by cart e2e slice 1 (`cartV2.cy.ts`); linked
+  the [cypress-testing](../workflows/cypress-testing.md) workflow doc. (tcox)
 - 2026-06-18 — Initial: case-insensitive de-dupe in both cart stores, sapphire `InfoBanner` message in
   CartForm, `duplicateEmailAddressError` label added to all CARTPAGE.ts variants (bala)
 
 ## Related docs
-None yet.
+- [cypress-testing](../workflows/cypress-testing.md) — e2e coverage that pins this behavior.

package/knowledge/2.0/apps/toga2-commerce/features/cart-page-config-architecture.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
-owners: ["apeterson"]
+updated: 2026-07-27
+owners: ["apeterson", "tcox"]
 files:
   - src/pages/Cart/CartPage.tsx
   - src/pages/Cart/view/cartForm/CartForm.tsx
@@ -22,6 +22,7 @@ related:
   - 2.0/apps/toga2-commerce/architecture.md
   - 2.0/apps/toga2-commerce/features/client-fields.md
   - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+  - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
   - 2.0/apps/toga25-supply/features/client-configurable-fields.md
 ---
 
@@ -140,10 +141,18 @@ behavior (email seeding, duplicate-email validation, edit-order cost-center/addr
 ### Phases
 
 **Phase 0 — Branch + safety net.** Branch `feature/cart-config-driven-form` off `_production`.
-**Pin a behavior oracle:** no tests cover the cart today, so first document both flows from the
-running app (sections shown, fields, buttons, validation messages, email auto-population, edit-order
-original address) and add RTL smoke tests rendering the cart for one tenant/role in **cart** and
-**edit-order** mode — these guard against the "renders nothing" failure the spike hit. **Inventory
+**Pin a behavior oracle:** cart **e2e slice 1 now exists** and *is* part of this oracle —
+`cypress/e2e/cartPage/cartV2.cy.ts` (12 tests, COMPASS / COMPASSCANADA admin; QUAD skipped; see
+[cypress-testing](../workflows/cypress-testing.md)). It pins seeded-items rendering, quantity /
+removal + subtotal, checkout enable/disable gating, clear- and empty-cart states, and — critically
+— the two behaviors the prior spike silently dropped: **notification-email auto-population**
+(user + supervisor rows, protected rows unremovable) and **case-insensitive duplicate-email
+surfacing**. Still **uncovered** and to be added before/with the refactor: **bundle scenarios**
+(blocked on stale Cypress bundle seeds), **expedited-shipping gating + guardrail modal**,
+**edit-order mode**, and **QUAD**. The repo has no RTL/unit runner (Cypress only), so extend the
+e2e specs — not RTL — to cover both **cart** and **edit-order** modes, and document any remaining
+flows from the running app (edit-order original address). These guard against the "renders nothing"
+failure the spike hit. **Inventory
 the hardcoded client branches (C6):** grep `src/pages/Cart` for `clientSlug`/client-name comparisons
 and per-client conditionals (start with `DuplicateKitGuardrail` and the order-for
 cost-center/manager/email seeding) — this list is the C6 work-list for Phases 3–4.
@@ -276,6 +285,12 @@ extension** of toga2.5's philosophy, not a literal copy.
    edit-order mode?
 
 ## Change history
+- 2026-07-27 — Phase 0 oracle is now partly real: cart e2e slice 1 (`cartV2.cy.ts`, 12 tests)
+  landed and pins the exact parity behaviors the prior spike lost (notification-email
+  auto-population, duplicate-email surfacing) plus render/gating/clear/empty flows. Corrected the
+  "no tests / add RTL smoke tests" note — the repo is Cypress-only; listed what slice 1 covers and
+  what remains (bundle, expedited gating, edit-order, QUAD). See the new
+  [cypress-testing](../workflows/cypress-testing.md) workflow doc. (tcox)
 - 2026-06-24 — Initial: documented the current `_production` Cart architecture (field-level config
   via `CartFormSection`, hardcoded section layout in `CartForm`, dual `EditCart`/`EditOrder` forms +
   dispatcher VM, prop-drilling), its gotchas (config-key drift, hardcoded union `defaultValues` with

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

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-27
 owners: [tcox]
 files:
   - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
@@ -16,6 +16,7 @@ files:
 related:
   - ../../../../clients/compass-usa/profile.md
   - ../../../../clients/compass-canada/profile.md
+  - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
 ---
 
 ## Summary
@@ -92,11 +93,20 @@ behavior is expressed in config, not in code branches.
   for the computer category (consistent with the existing `checkCartContainsComputerKit`
   detector). Fine today, but a miss if a `COMPUTERS` item ever lives only in a nested child
   bundle.
-- **No automated test was added.** The repo has no unit-test runner (Cypress only). Verified
-  via `tsc -b` (clean, twice) and an independent maker≠checker code review. ESLint could not
-  run locally (missing `eslint-plugin-react-compiler` — environment issue).
+- **Still no automated test for the gating itself.** The repo has no unit-test runner (Cypress
+  only). The gating shipped verified via `tsc -b` (clean, twice) and an independent maker≠checker
+  code review. ESLint could not run locally (missing `eslint-plugin-react-compiler` — environment
+  issue). **A cart Cypress e2e harness now exists** (see
+  [cypress-testing](../workflows/cypress-testing.md)) and a gating spec is now feasible: the
+  `cart/fetchUserShippingMethods.json` fixture already carries the gated option names
+  (**Next Day Air**, **2nd Day EOB**) with no `c_cost`. This gating + guardrail-modal scenario is
+  on that doc's slice-2 work-list.
 
 ## Change history
+- 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
+  [cypress-testing](../workflows/cypress-testing.md). (tcox)
 - 2026-06-30 — Built config-driven expedited-shipping gating: expedited methods shown only
   when the cart holds a COMPUTERS-category computer kit, with auto-reset to Standard Ground
   otherwise; tenant opt-in via `optionGates` (no client-slug branching). Code review fixed 3

package/knowledge/2.0/apps/toga2-commerce/workflows/cypress-testing.md

@@ -0,0 +1,209 @@
+---
+title: Cart e2e — Cypress conventions & harness (toga2-commerce)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: workflow
+status: active
+updated: 2026-07-27
+owners: [tcox]
+files:
+  - 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
+related:
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+  - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+  - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - 2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
+  - 2.0/apps/toga25-supply/workflows/cypress-testing.md
+---
+
+## What it is
+
+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, verified green by the developer in
+the live app). Read this doc before adding any new spec here. It doubles as the **Phase 0
+behavior oracle** for the planned config-driven cart refactor (see
+[cart-page-config-architecture](../features/cart-page-config-architecture.md)): the cart specs
+pin the exact parity behaviors the prior refactor spike silently lost (notification-email
+auto-population, duplicate-email error surfacing), so the refactor can restructure the DOM and
+still prove behavior parity.
+
+This is the toga2-commerce sibling of
+[toga25-supply's Cypress harness](../../toga25-supply/workflows/cypress-testing.md); the
+patterns differ because toga2-commerce is **e2e-only** (no component-test project) and is
+tenant/host-driven.
+
+## V2-only convention (V1 is dead)
+
+Only the **V2** specs are active: `homePageContentV2`, `itemViewPageV2`, `headerV2`, `footerV2`,
+`getSupportV2`, and now `cartV2`. **Every V1 spec was bulk-commented-out on 2026-03-05**
+(commit `e48c968d`, *"Comment out failing and unreliably passing Cypress tests"*) and is stale —
+do not resurrect a V1 spec; write a V2 replacement. The old fully-commented
+`cypress/e2e/cartPage/cart.cy.ts` was **deleted** this session (it violated the no-commented-code
+standard and was actually an *"add items from filter page"* flow, not a cart-page spec) and is
+superseded by `cartV2.cy.ts`.
+
+## The V2 spec pattern
+
+- `import { tenant } from '../../support/e2e';` and build **per-tenant data maps** keyed by
+  tenant.
+- `beforeEach` sets `cy.viewport(1920, 1080)` then `switch (tenant)` → the login command:
+  - `cy.compassAdminLogin(tenant, assortmentsStatus, bundlesStatus, path)` for COMPASS /
+    COMPASSCANADA admin;
+  - `cy.quadLogin(status, path)` for QUAD.
+  - The login command performs the `cy.visit(path)` itself and seeds `zu-user`, `fields-key`,
+    `current-client-id`, `synced=false`, and tokens via `onBeforeLoad` (never paste real token
+    values into a spec — the command handles auth seeding).
+- **Intercept exact URLs** — `https://api.beta.togahub.com/v2/...`. V2 replaced V1's
+  `**/`-wildcard intercepts; keep new intercepts exact so an unstubbed call surfaces instead of
+  matching a wildcard.
+- Select elements with `cy.getDataTestId(id)` — the helper takes **only** the id string (not a
+  selector), and `defaultCommandTimeout` is **8s**.
+
+### Distinguishing the order-for single-user fetch
+
+When an admin selects the "order for" user, the app fires a single-user fetch that must be
+stubbed separately from the login-user stubs. It is distinguished by its **field set** — it
+requests `c_erpEntityId`. Intercept it with a regex lookahead so it does not collide with the
+login user request:
+
+```
+/\/v2\/users\/[^?]+\?(?=.*c_erpEntityId)/
+```
+
+## Seeding the cart (localStorage + rehydrate)
+
+Seed commands live in `cypress/support/commands.ts`:
+
+- **`seedCart` / `seedSalesQuote`** — 3 standalone Compass items, subtotal **531.31**. These
+  match the **current** `CartItems` store shape and are what `cartV2.cy.ts` uses.
+- **`seedCartBundle` / `seedSalesQuoteBundle`** — ⚠ write the **LEGACY** bundle shape with a
+  top-level `uuid` field. The current `CartBundles` contract (`src/pages/Cart/types.ts`) is
+  **`bundleZuCartUuid` + `bundleProgressContents` with NO top-level `uuid`** (the
+  `bundleUuid`/`bundleZuCartUuid` identity contract — see
+  [cart-bundle-submission-and-identity](../features/cart-bundle-submission-and-identity.md)).
+  **These bundle seeds must be rebuilt to the current shape before any bundle e2e scenario.**
+- **All four seeds only write `localStorage`.** A spec **must `cy.visit('/cart')` AFTER seeding**
+  so the zustand `persist` stores rehydrate — in-app navigation does **not** re-hydrate them.
+
+**Cart seeding contract** (which keys to seed for which mode):
+
+- **Fresh cart:** `zu-cart` + `zu-user` + `fields-key`.
+- **Edit-order:** additionally `in-edit-mode-zu`, `edit-order-uuid-zu`, `zu-cart-sales-quote`,
+  `synced="true"`, and visit `/cart?uuid=<orderUuid>`.
+
+## Cart-page specifics (what to assert)
+
+The cart page fires **no order-submit API**. **"Proceed to Checkout"** only navigates to
+`/order-details?type=cart` (or `?uuid=<salesOrder>&type=editOrder` in edit mode); the actual
+submission lives in **OrderDetails**. So a cart spec asserts **navigation** plus the
+progressively-built **`zu-cart-sales-quote`** payload — not a submit request.
+
+## data-testid instrumentation (behavior-anchored selectors)
+
+The cart UI was instrumented with `data-testid` attributes so specs anchor on **behavior**, not
+DOM structure, and survive the planned config-driven refactor's DOM restructuring. Naming scheme
+(across `CartPage.tsx`, `CartForm.tsx`, `CartFormSection.tsx`, `CartContentsTable.tsx`,
+`CartTableItem.tsx`):
+
+- Actions: `proceed-to-checkout-button`, `clear-cart-button`,
+  `cart-item-delete-button-{uuid}`, `edit-order-cancel-button`, `edit-order-add-items-button`,
+  `add-new-address-button`, `edit-address-button`, `edit-original-address-button`,
+  `add-notification-email-button`, `remove-notification-email-button`.
+- Empty state: `empty-cart-message`, `empty-cart-start-shopping-button`, `empty-cart-support-link`.
+- Inputs: `select-address-input`, `shipping-method-input`, `cost-center-input`,
+  `special-instructions-input`, `notification-email-input`, `notification-email-checkbox`.
+- Rows / banners / text: `notification-email-row-{email}`, `duplicate-email-banner`,
+  `cart-form-errors-text`, `invalid-address-text`.
+- Config-driven field ids: `cart-form-input-{valueKey}`, `cart-form-display-{valueKey}`,
+  `label-button-{valueKey}`, `input-button-{valueKey}`.
+- Shared **`AdvancedInput`** gained: `advanced-input-{valueKey}`, `advanced-input-field-{valueKey}`,
+  `advanced-input-toggle-{valueKey}`, `advanced-input-clear-{valueKey}`,
+  `advanced-input-option-{optionUuid}`.
+
+`BaseButton` / `BaseText` / `BaseInput` / `InfoBanner` already accepted a `dataTestId` prop;
+`IncrementDecrement` already ships `increment-quantity-button` / `decrement-quantity-button` /
+`quantity`.
+
+## What slice 1 covers (`cartV2.cy.ts`)
+
+12 tests for **COMPASS / COMPASSCANADA admin** (**QUAD** is an explicit, visible `skip`
+placeholder):
+
+- Seeded-items render smoke (items, part numbers, prices, summary + all form sections, checkout
+  button rendered twice).
+- Quantity increment → subtotal update; item removal → subtotal update.
+- Checkout **disabled** while the form is incomplete; **enabled** once an address is picked
+  (shipping method defaults from the seeded quote; cost center auto-seeds from the user's
+  `c_erpEntityId`).
+- Clear-cart → empty state; the empty-cart state (message / start-shopping / support link).
+- Order-for user selection → notification-email auto-population (user + supervisor emails,
+  protected rows have no remove button); email add (checkbox selected); **case-insensitive
+  duplicate blocked** with the sapphire info banner (*"This email has already been added"* — see
+  [cart-notification-emails](../features/cart-notification-emails.md)); invalid email rejected;
+  an added email is removable.
+
+### Not yet covered — slice 2 work-list
+
+- **Bundle scenarios** — blocked on the stale bundle seeds (rebuild `seedCartBundle` /
+  `seedSalesQuoteBundle` first, above).
+- **Expedited-shipping gating + guardrail modal** — the `cart/fetchUserShippingMethods.json`
+  fixture already carries the gated option names (**Next Day Air**, **2nd Day EOB**) with no
+  `c_cost`, ready for a gating spec (see
+  [expedited-shipping-gating](../features/expedited-shipping-gating.md)).
+- **Edit-order mode.**
+- **QUAD tenant** (currently the visible skip placeholder).
+
+## Running the specs
+
+- The **only** npm script is `"cypress": "cypress open"` — interactive. There is **no headless
+  script and no CI wiring**; `.github/workflows` never runs Cypress. Specs are validated by
+  running them locally / interactively.
+- The **dev server must run separately** first: `npm run compass` | `npm run compasscanada` |
+  `npm run quad`.
+- **Windows invocation:** `$env:TENANT="compass"; npm run cypress` — `cross-env` is **not**
+  installed, so set the env var in the shell.
+- Requires **hosts-file entries** `127.0.0.1 compass|compasscanada|quad.togacommerce` (present on
+  this machine but **undocumented in the README** — a new dev must add them).
+
+## Gotchas
+
+- **`BaseButton` never sets the native `disabled` attribute (test-critical).**
+  `src/components/BaseButton/BaseButton.tsx` sets `aria-disabled="true"|"false"` and suppresses
+  `onClick` inside `handleClick` — it deliberately leaves the element enabled so a disabled button
+  (e.g. **Proceed to Checkout**) still receives mouse events and its `BaseTooltip` (*"Please
+  complete all required fields to proceed."*) works. Cypress assertions **MUST** use
+  `.should('have.attr', 'aria-disabled', 'true'|'false')`, **never** `.should('be.disabled')` —
+  `be.disabled` times out even though the button is visually/functionally disabled. (This cost the
+  only 2 first-run failures.)
+- **Seed → then `cy.visit('/cart')`.** The persist stores rehydrate on load only; seeding
+  `localStorage` and navigating in-app leaves the stores stale (see seeding section).
+- **Bundle seeds are on the legacy shape** — do not write a bundle spec against them until they
+  are rebuilt to the `bundleZuCartUuid` + `bundleProgressContents` contract.
+- **ESLint fails repo-wide in a fresh checkout** because `.eslintrc.cjs` references
+  `eslint-plugin-react-compiler`, which is not installed; `npm install --save-dev
+  eslint-plugin-react-compiler` fixes it. This is a local-environment issue, not a spec problem.
+
+## Change history
+- 2026-07-27 — Added the first active Cart-page e2e coverage (`cartV2.cy.ts`, 12 tests, COMPASS /
+  COMPASSCANADA admin; QUAD skipped) and documented the toga2-commerce V2 e2e conventions:
+  V2-only (V1 bulk-commented 2026-03-05, dead V1 cart spec deleted), the tenant-login/seed/
+  rehydrate contract, the order-for `c_erpEntityId` regex-lookahead intercept, the cart's
+  "navigate-not-submit" checkout, the `data-testid` instrumentation scheme, the **`BaseButton`
+  `aria-disabled` (never native `disabled`)** test-critical gotcha, the legacy bundle-seed
+  blocker, and the interactive-only runner. Slice 1 pins the refactor's Phase 0 parity oracle
+  (email auto-population, duplicate-email surfacing). (tcox)
+</content>

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-28
 owners: [jcardinal, dfranks, mhammontree]
 files:
   - worker2/Worker/
@@ -189,10 +189,29 @@ be reattempted.
   `$environment = (substr(_Environment::$name, 0, 4) === 'dev-') ? 'dev' : _Environment::$name`.
   Without it, every `_Model_Client_*` load fails. Proven pattern: `_Worker_Startech` (and
   `_Worker_Notification_EmailTemplate`). Do this in `initialize()` or at the top of the method.
+- **`_ApiRequest` logging is a silent no-op unless the Logs DB is registered as
+  `DB_CLIENT_LOGS`.** `_ApiRequest`'s logging branch writes through `_Model_Client_Logs_Api`,
+  whose `DATABASE` const is `_underscore::DB_CLIENT_LOGS`. A worker whose `initialize()` only
+  registers, say, `DB_TEAM` will produce **zero** api-log rows (or, in a CLI/test harness,
+  `Unknown database 'ClientLogs'`). So for any worker that makes outbound `_ApiRequest` calls,
+  pick one deliberately:
+  - **Want the calls logged** → register the logs DB in `initialize()`, e.g.
+    `_Database::registerDatabase(_Config::databaseLogs('Logs_True', …), _underscore::DB_CLIENT_LOGS)`
+    (proven pattern: `Worker/Team/Sprint.php::initialize()`, `Worker/Team/Transcripts.php::initialize()`).
+  - **Don't want them logged** → pass `setLogging(false)` explicitly, with a comment saying why
+    (proven: `Worker/Clickup/Fluffer.php`, `Worker/Vapi.php`, `Worker/Ai/Bdr/Vapi.php`).
+
+  Swapping raw curl for `_ApiRequest` "to get logging" without doing the first of those is the
+  common trap — the code looks right and logs nothing.
 - See [architecture.md](../architecture.md) for the always-HTTP-200 rule and the
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-07-28 — Added the **`_ApiRequest` logging / `DB_CLIENT_LOGS` gotcha**: api-log rows are
+  written via `_Model_Client_Logs_Api` (`DATABASE = DB_CLIENT_LOGS`), so a worker must either
+  register the Logs DB under that alias in `initialize()` or pass `setLogging(false)`
+  deliberately. Surfaced migrating the Talos AI caller in `Worker/Team/Transcripts.php` off raw
+  curl. (jcardinal)
 - 2026-07-21 — Documented that adding a recurring job is **pure data** (a `Core.CronJobs` row;
   CronScheduler Lambda matches via croniter every minute, no code wiring beyond the row — but
   the action must be deployed), and the **biweekly self-gating pattern**: for schedules cron

package/knowledge/2.0/apps/worker2/features/talos-transcript-ingestion.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-13
+updated: 2026-07-28
 owners: [jcardinal]
 files:
   - worker2/Worker/Team/Transcripts.php
@@ -30,6 +30,7 @@ related:
   - ./creating-worker-actions.md
   - ../architecture.md
   - ../../_underscore/features/async-query-execution.md
+  - ../../_underscore/features/apirequest-json-content-type.md
   - ../../../1.0/apps/tools/features/talos-kb-documents-admin.md
   - ../../../1.0/apps/test/features/talos-kb-pipeline.md
 ---
@@ -136,6 +137,35 @@ helpers).
    [Background Email-Template Worker](./notification-email-template.md); the template is the
    TOGA Technology `True`-client template).
 
+### `callTalosEndpoint()` — the shared low-level Talos AI caller
+The private static `callTalosEndpoint()` is the single HTTP path used by **both** AI passes
+(`callAICleaningAPI()` = clean+classify, and `buildRecapEmailBody()` = recap JSON). As of
+2026-07-28 it uses **`_ApiRequest`** instead of raw `curl_init`/`curl_exec`, so every outbound
+Talos call is recorded in the api log. Its contract to the two callers is unchanged:
+`array{success: bool, result?: array, error?: string}`.
+
+Three deliberate deviations from the usual worker2 `_ApiRequest` idiom — do not "normalize" them:
+
+1. **No `ENCODE__JSON`.** The payload is `json_encode`d by the caller with
+   `JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE` and passed as a **ready JSON string with
+   payloadEncoding left null**; the response is decoded locally with `json_decode($r, true)`.
+   Reasons: (a) `_ApiRequest::execute()` decodes JSON responses with `json_decode($payload)` —
+   **no assoc flag** — returning `stdClass`, while both callers index
+   `$res['result']['knowledge_doc']` / `$res['result']['recap_json']` as **arrays**;
+   (b) `ENCODE__JSON` re-encodes without the unescaped flags, inflating every non-ASCII char of
+   a full meeting transcript to `\uXXXX`. Pre-encoding preserves the wire bytes exactly.
+2. **The local retry loop is kept; `setAutoRetry()` is not used.** `setAutoRetry()` waits a
+   **flat** delay and retries **every** non-2xx. This endpoint needs exponential backoff
+   (`AI_BASE_DELAY_MS * 2^(n-1)`, `AI_MAX_ATTEMPTS = 2`) and must fail fast on 4xx other than
+   429. So the surrounding `for` loop is retained and **one `_ApiRequest` is constructed per
+   attempt** — which also yields one api-log row per attempt, useful for diagnosing Talos
+   flakiness.
+3. **Transport failures arrive as a thrown Exception** from `execute()` (its equivalent of
+   `curl_error()`), caught to preserve the same error-array return shape.
+
+Timeouts/attempts are class constants: `AI_DEFAULT_TIMEOUT = 600`, `AI_CONNECT_TIMEOUT = 20`,
+`AI_MAX_ATTEMPTS = 2`, `AI_BASE_DELAY_MS`.
+
 ### Organizer email resolution
 - `resolveOrganizerEmail()` calls Graph `/users/{id}?$select=mail,userPrincipalName` — but
   this needs the **`User.Read.All`** app permission, which the app registration **lacks**.
@@ -240,12 +270,40 @@ part of the ingestion loop** (raw reads removed). Credential values live only in
   `bin/sync-knowledge-bases.php`) to discover `development-team-*` KBs from Bedrock and upsert
   them into `Team.KnowledgeBases`. **Open architectural point:** two competing registries —
   `Team.KnowledgeBases` (worker2) vs `Client_True.VectorIndexes` (Tools UI).
+- **`initialize()` MUST register the Logs DB under `DB_CLIENT_LOGS` or the Talos api-logging is
+  a silent no-op.** `_ApiRequest`'s logging branch writes via `_Model_Client_Logs_Api`, whose
+  `DATABASE` const is `_underscore::DB_CLIENT_LOGS`. `Transcripts::initialize()` previously
+  registered only `DB_TEAM`, so swapping curl → `_ApiRequest` would have produced **zero** log
+  rows. It now also registers `Logs_True` under `DB_CLIENT_LOGS` via `_Config::databaseLogs(...)`
+  (same pattern as `Worker/Team/Sprint.php::initialize()`). The general rule is on
+  [Creating Worker Actions](./creating-worker-actions.md#gotchas) — other workers hitting the
+  same Talos host instead pass `setLogging(false)` deliberately
+  (`Worker/Clickup/Fluffer.php`, `Worker/Vapi.php`, `Worker/Ai/Bdr/Vapi.php`).
+- **KNOWN LIMITATION (deliberately NOT fixed — do not patch it locally): long AI calls can leave
+  api-log rows with null `responseCode`/`responsePayload`.** `_ApiRequest` logs in two halves —
+  it inserts the request row and commits **before** the HTTP call, then `save()`s the response
+  fields **after**. With `AI_DEFAULT_TIMEOUT = 600`, that second save runs on a connection idle
+  for up to 10 minutes, which is exactly the worker2 stale-connection failure mode. Expected
+  symptom: on the slowest transcripts the api-log row has a request but no response. A real fix
+  belongs **inside `_ApiRequest::execute()`** (reconnect/re-register before the post-call save)
+  and affects every framework caller, so it is deferred pending architecture review. Do **not**
+  work around it in `Transcripts.php`.
 - **Cross-ACCOUNT S3.** `togaiq` (us-east-1) approved/archive writes use the `[talos]` key;
   `CopyObject` across accounts is impossible, so archive is get(in-memory)+put. (The old
   toga-private cross-account read is no longer in the loop.)
 
 ## Change history
 
+- 2026-07-28 — **`callTalosEndpoint()` migrated from raw curl to `_ApiRequest`** so both AI
+  passes are recorded in the api log; `initialize()` now also registers `Logs_True` under
+  `_underscore::DB_CLIENT_LOGS` (without it the logging is a silent no-op). Deliberately kept
+  the pre-encoded JSON string (no `ENCODE__JSON` — `execute()` returns `stdClass`, and re-encode
+  loses `JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE`) and the local exponential-backoff loop
+  (no `setAutoRetry()` — it is flat-delay and retries every non-2xx). Also fixed an undefined
+  `$data` in the exhausted-retry error message (it was `print_r`'d before assignment; now uses
+  the raw response string) and replaced the hardcoded curl connect timeout with
+  `AI_CONNECT_TIMEOUT = 20`. Caller return contract unchanged, so no caller changed.
+  `php -l` clean; not committed. (jcardinal)
 - 2026-07-13 — Recap email **subject-line date** now displays as `n/j/y` (e.g. `7/9/26`)
   instead of `Y-m-d`, via `DateTime::createFromFormat` with a fallback to the raw
   `$dateSegment`. Cosmetic — `$dateSegment` (S3 filename, metadata sidecar, AI recap body)

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