toga-ai 1.0.767 → 1.0.769

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-09-03
-owners: [dfranks, jcardinal, kyalamarthi]
+owners: [dfranks, jcardinal, kyalamarthi, rgirish]
 files:
   - library/app/api/netsuite/rest.php
   - library/app/netsuite.php
@@ -78,6 +78,22 @@ Forecast2 tables already store.
   a per-type factor (it double-negates reversals back to positive). The shim flips
   `amount = -foreignamount`, `costEstimate = -costestimate`.
 
+- **⚠ `->holdInvoice` on a sales-order shim is NOT a native NetSuite field — it is normalised from
+  the custom checkbox `custbody_asi_hold` (internal id 4082), and that field is SHARED by all
+  clients.** NetSuite REST exposes no top-level `holdInvoice`. The `"asi"` prefix is **Agilant
+  Solutions Inc** (the company), *not* a client prefix — do not read it as client-specific. The read
+  lives **inside the shim**, in all three fetch paths: `buildSalesOrderShims()` (~L533, feeding both
+  `listSalesOrders()` and `fetchSalesOrderByIdFull()`) and `fetchSalesOrderById()` (~L1537), so
+  callers such as `App_Api_Toga2::isTransferOrder()` read an already-normalised boolean. (An earlier
+  version read `$nsOrder->holdInvoice` in the caller with a `custbody_hold_invoice` fallback — the
+  wrong field name; commit `07c31e24`, 2026-08-19, found the real one and moved the read down here.)
+  `worker/crons/toga2/compass/edi/2_create_so_netsuite.php` **writes** the same field.
+  **⚠ The SOAP client `library/app/netsuite.php` never sets `holdInvoice` at all**, so any detection
+  that depends on it (e.g. the `zero_dollar_hold` transfer-order mode — see
+  [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)) is **silently
+  always-false** on a SOAP path. Verified not a live risk: the togasupply engine calls
+  `App_Api_Netsuite_Rest::` on every sales-order/receipt/fulfillment path.
+
 - **`createdFrom` is not a usable SuiteQL column.** `transaction.createdfrom` is **always NULL**
   in SuiteQL (26/26). It is recoverable from `previoustransactionlinelink.previousdoc` excluding
   `previoustype = 'Opprtnty'` (an invoice links to both its SO and its opportunity; REST's
@@ -307,6 +323,16 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-09-03 — Documented that a sales-order shim's **`->holdInvoice` is not a native NetSuite
+  field**: it is normalised inside the shim from the custom checkbox **`custbody_asi_hold` (id
+  4082)**, which is **shared across all clients** ("asi" = Agilant Solutions Inc, not a client
+  prefix). Set in all three fetch paths (`buildSalesOrderShims()` feeding `listSalesOrders()` /
+  `fetchSalesOrderByIdFull()`, plus `fetchSalesOrderById()`); traced to commit `07c31e24`
+  (2026-08-19), which corrected the earlier caller-side read of `custbody_hold_invoice`. Recorded the
+  trap that the **SOAP client `app/netsuite.php` never sets it**, so hold-based detection is silently
+  always-false there — verified harmless today because the togasupply engine is REST-only.
+  Read-only session; no change to `rest.php`. (rgirish)
+
 - 2026-09-03 — Recorded that **`fetchItemFulfillmentById` and `fetchInventoryAdjustmentById` omitted
   `->lastModifiedDate`** (unlike `fetchItemReceiptById`), which froze ITEM_FULFILLMENTS + INVENTORY_ADJUSTMENTS
   once the 2026-09-02 per-record cursor read that field off the by-reference record these shims replace. GroWrk

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-09-03
-owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
+owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/sync_togasupply_canon.php
@@ -463,29 +463,71 @@ the code deploy).
 
 ## Client variations
 
-- **Transfer-order routing is opt-in per wrapper (default OFF).** A client whose NetSuite
-  *transfer orders* arrive as NetSuite *sales orders* can have the importer split them into
-  `TransferOrders` vs `SalesOrders` by setting
-  `const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` before the `require_once`
-  (NYCHH's `sync_togasupply_hh.php` is the only one that does). The signal is the NetSuite custom
-  checkbox `custbody_stocking_order`, read by `App_Api_Toga2::isTransferOrder()`/`isStockingOrder()`
-  — **not** a dollar/hold heuristic. Full mechanics, PO bridges, and origin-location resolution:
-  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
-- **Transfer-order integration is governed by TWO DISTINCT wrapper flags — a master enable switch and a
-  NYCHH-only classification-mode switch (do not conflate them).**
+- **Transfer-order integration is governed by TWO DISTINCT wrapper constants — a master enable switch
+  and an explicit per-client detection MODE (do not conflate them).** These orders **masquerade as
+  NetSuite sales orders** and are split into `TransferOrders` vs `SalesOrders` by
+  `App_Api_Toga2::isTransferOrder()`.
   - **`IS_ENABLED_INTEGRATION_TRANSFER_ORDERS`** — the master "do transfer-order integration at all"
-    switch, defined in every `sync_togasupply_*.php` launcher. `true` for **GroWrk, Adyen, Elite, and
-    NYCHH**; `false` for the rest. These are the clients exercised by the shared
-    `syncTransferOrderFromNetsuite` / `getTransferOrderItemsByUuid` fixes (2026-08-30 above).
-  - **`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`** — a **separate classification-mode** switch,
-    **NYCHH-only** (`sync_togasupply_hh.php`), that makes `App_Api_Toga2::isTransferOrder()` classify by
-    the NetSuite `custbody_stocking_order` checkbox instead of the legacy rule.
-
-  These orders **masquerade as NetSuite sales orders** and are split into `TransferOrders` vs
-  `SalesOrders` by `isTransferOrder()`. The classification **SIGNAL is per-client**: **NYCHH** routes by
-  the `custbody_stocking_order` stocking flag (above); **GroWrk / Elite / Adyen** use the **legacy rule**
-  (`holdInvoice AND total === 0`). Do **not** assume one universal signal — the master enable is shared,
-  the classification mode is not.
+    switch, defined in every `sync_togasupply_*.php` launcher. `true` for **GroWrk, Adyen, and
+    NYCHH**; `false` for Elite (pre-wired, not on) and the rest. **Every one of the 7
+    `isTransferOrder()` call sites is guarded by this**, so the mode throw below can never fire for a
+    client with transfer orders off.
+  - **`TRANSFER_ORDER_DETECTION_MODE`** — the classification mode, one of two `App_Api_Toga2` class
+    constants (see next bullet). Required whenever the master switch is on.
+
+### ⚠ `TRANSFER_ORDER_DETECTION_MODE` — explicit per client, NO default, throws if unset (2026-09-03)
+
+`isTransferOrder()` used to branch on a boolean `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`
+(defined only in NYCHH's launcher) and **otherwise fall through to GroWrk's legacy `$0 total +
+holdInvoice` rule**. That made the legacy rule an **implicit, silent default**: a new client turning
+transfer orders on without the constant silently got another client's classification applied to its
+orders, on a green-looking run. That boolean is **removed everywhere**.
+
+Each launcher now declares an explicit mode before its `require_once`:
+
+```php
+const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG;
+// or
+const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD;
+```
+
+| Mode constant | Value | Rule | Clients |
+|---|---|---|---|
+| `TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG` | `'stocking_flag'` | NetSuite checkbox `custbody_stocking_order` (id 7097) — **unchecked = transfer order** | NYCHH |
+| `TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` | `'zero_dollar_hold'` | `holdInvoice === true` **AND** `total === 0` | GroWrk, Adyen, Elite (pre-set, unused — its master switch is off) |
+
+`App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODES` is the allowlist array. **`isTransferOrder()` THROWS
+when the mode is undefined or not in the allowlist** — a deliberate fail-loud, chosen over defaulting
+to the legacy rule, consistent with the 2026-08-27 "every section fails loud" policy. Consequence,
+and it is not optional: **`library` and `worker` MUST deploy together.** A worker deploy without the
+library (or vice versa) crashes GroWrk and Adyen on their next sync run.
+
+- **A separate NYCHH-only flag, `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK`,** now guards
+  `attachInventoryAdjustmentToItemFulfillment()` (the `custbody_stock_adjustment` link). The removed
+  routing boolean had been doing double duty for it; it is an unrelated feature that merely has NYCHH
+  as its only client today. See
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+
+- **`->holdInvoice` is NOT a native NetSuite field** — it is normalised by the REST shim from the
+  custom checkbox `custbody_asi_hold` (internal id **4082**), which is **shared across all clients**
+  ("asi" = Agilant Solutions Inc, the company, not a client prefix). `App_Api_Netsuite_Rest` sets it
+  in `buildSalesOrderShims()` (feeding `listSalesOrders()` + `fetchSalesOrderByIdFull()`) and in
+  `fetchSalesOrderById()`. **`app/netsuite.php` (SOAP) never sets it at all** — ZERO_DOLLAR_HOLD would
+  be silently always-false on a SOAP path. Not a live risk: `common_sync_togasupply.php` uses
+  `App_Api_Netsuite_Rest::` on **every** sales-order / receipt / fulfillment path, and all
+  transfer-order clients are on REST. Field detail:
+  [SuiteQL/REST shim](../../library/features/netsuite-suiteql-rest-shim.md).
+
+- **⚠ OPEN (pre-existing, not fixed): an absent NetSuite `total` collapses to `0.0` and can
+  misclassify.** The ZERO_DOLLAR_HOLD branch reads
+  `$total = isset($nsOrder->total) ? (float) $nsOrder->total : 0.0;`. A REST response with a
+  missing/blank `total` (transient API failure — not a real $0 order) becomes `0.0`, and combined with
+  the hold flag set, a **non-zero order classifies as a transfer order**. This line predates the mode
+  refactor and was carried across unchanged; it goes against the fail-loud rule for cron/sync code.
+  Raised with the developer, left as-is pending a decision.
+- **Full mechanics of the stocking-flag mode** (PO bridges, origin-location resolution):
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+  Legacy-rule background: [GroWrk transfer order flow](../../../clients/growrk/features/transfer-order-flow.md).
 - `isParentCustomer` — `true` walks NetSuite child customers (`listChildCustomers`); `false`
   syncs the single customer. Prudential-EDI and the live Quad wrapper use `false`.
 - The original combined-array entries used `App_Api_Toga2::CLIENT_UUID_*` consts for Quad and
@@ -1212,6 +1254,23 @@ the code deploy).
 
 ## Change history
 
+- 2026-09-03 — **Transfer-order detection is now an explicit per-client MODE with no default; the old
+  `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING` boolean is removed from both repos.**
+  `isTransferOrder()` previously branched on that boolean (NYCHH-only) and otherwise fell through to
+  GroWrk's `$0 total + holdInvoice` rule — an implicit silent default that would apply one client's
+  classification to another's orders on a green-looking run. Launchers now set
+  `TRANSFER_ORDER_DETECTION_MODE` to one of two new `App_Api_Toga2` constants
+  (`__STOCKING_FLAG` = NYCHH, `__ZERO_DOLLAR_HOLD` = GroWrk/Adyen/Elite), validated against a
+  `TRANSFER_ORDER_DETECTION_MODES` allowlist; an undefined/unknown mode **throws**. All 7 call sites
+  are guarded by `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS`, so the throw can't fire for a client with
+  TOs off. The `custbody_stock_adjustment` adjustment→fulfillment link, which the removed boolean was
+  also guarding, moved to its own `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK` (NYCHH only).
+  Also recorded: `->holdInvoice` is the REST shim's normalisation of the **shared** custom checkbox
+  `custbody_asi_hold` (id 4082, "asi" = Agilant Solutions Inc, not a client), never set on the SOAP
+  path — safe today because this engine is REST-only; and the pre-existing `total ?: 0.0` default in
+  the ZERO_DOLLAR_HOLD branch can misclassify on a transient NetSuite failure (open, unchanged).
+  **`library` + `worker` must deploy together** or GroWrk and Adyen throw on their next run. (rgirish)
+
 - 2026-09-03 — **By-reference shim wrote the cursor on the WRONG CLOCK → ITEM_RECEIPTS + ITEM_FULFILLMENTS
   re-matched the same record forever (fixed, `library` only).** Follow-on to the same-day by-reference
   fix below: the shims set `lastModifiedDate` from the REST GET (UTC), `date()`-formatted in

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: ["jcardinal", "mhammontree", "tcox", "bala", "apeterson"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -380,6 +380,14 @@ across clients, establish **which app** the missing control is in. Detail:
 [Surface Resolver](surface-resolver.md) and
 [toga25-supply side navigation](../../toga25-supply/features/side-navigation-and-default-route.md).
 
+> **Narrow scope precisely: the FLAGS are inert, the ENDPOINT is not gone.** "Dead config" above is
+> about the `navigation-*` `AclActions` flags having no effect on the 2.5 UI — that stands, verified
+> prod-wide. It is **not** a claim that `toga25-supply` has stopped calling `Page::meta`: verified
+> 2026-09-03, five of its view models still call `GET /v2/pages/meta` (nothing in `src/` reads a
+> field off the result). So a change to `Page::meta`'s request path can still reach the 2.5 app even
+> though its ACL flags cannot reach the 2.5 nav. Detail:
+> [Surface Frontend](../../toga25-supply/features/surface-frontend.md).
+
 Worked example (Quad, 2026-08-26): the vendor-items **Add and Edit buttons both** read
 `acl['vendor-items']['navigation-edit-on-vendor-items']` (AclActions id 7). `Client_Quad` had a row
 for id 5 only, so the page was reachable but button-less, even though record 19 already granted role
@@ -598,6 +606,10 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- **2026-09-03** — Scoped the "dead config in the surface-driven 2.5 app" claim: the `navigation-*`
+  **flags** are inert (unchanged), but `toga25-supply` still **calls `GET /v2/pages/meta`** from five
+  view models, so `Page::meta` is not out of that app's request path. Additive clarification only.
+  (apeterson)
 - **2026-09-01** — Four additions from a `PurchaseOrderItems._qty*` grant investigation.
   (1) **Read `Core.Records.aclDatabase` FIRST** — both databases carry an `AclFieldPermissions`
   table, so checking Core for a `CLIENT`-acl record (here `purchase-order-items`, record 18) returns

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -5,16 +5,16 @@
 | [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/providers/TalosStreamProvider.tsx |
 | [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.test.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASS/approvalActionFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASSCANADA/approvalActionFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` / `join` / `where` to request from the TOGa API for a given page — fr | toga25-supply/src/fieldsConfig/resolveApiConfig.ts, toga25-supply/src/fieldsConfig/useClientApiFields.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx |
-| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
+| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/resolveRole.ts, toga25-supply/src/globalFieldsConfig/clientLoginFields.json, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql |
 | [Force Logout on Deployment (useDeploymentGuard)](features/force-logout-on-deployment.md) | On large deployments the backend bumps the Core parameter `META_LAST_REFRESH_DATETIME`. | toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/App.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css |
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. | toga25-supply/src/routes.tsx, toga25-supply/src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts, api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.test.ts, toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.test.ts, toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Bundles/viewModel/useBundlesPageViewModel.tsx, toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host, live Aegra streaming, LangGraph→blox mapper)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/api/talos.ts, toga25-supply/src/hooks/useTalosSession.ts, toga25-supply/src/hooks/useTalosThreads.ts, toga25-supply/src/hooks/useTalosThreads.test.ts, toga25-supply/src/hooks/useTalosSurface.ts, toga25-supply/src/hooks/useTalosSurface.test.ts, toga25-supply/src/App.tsx, toga25-supply/db-migrations/PLAYBOOK.md, dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, toga25-supply/src/providers/TalosStreamProvider.tsx, toga25-supply/src/utils/talosMessages.ts, toga25-supply/src/utils/talosMessages.test.ts, toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
 | [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/PanelSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/ContactSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/SelectTargetLocationModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferItemPickerTable.tsx, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderNote.php, _underscore/Model/Client/TransferOrderNoteType.php, dbchanges2/Client/2026-09-01b - TransferOrderNotesTables.sql, dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql, dbchanges2/Core/2026-09-01c - TransferOrderNotesRecords.sql, dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql, toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, toga25-supply/src/pages/TransferOrders/TransferOrder.module.css, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/.env.development |
-| [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |
+| [Cypress Testing Harness (multi-tenant, fully stubbed)](workflows/cypress-testing.md) | The Cypress harness for `toga25-supply`: an **e2e** project and a **component** project, plus a stub layer that answers **every** `/v2` call so no test touches | toga25-supply/cypress.config.ts, toga25-supply/cypress/README.md, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/tenants.ts, toga25-supply/cypress/support/api/stubApi.ts, toga25-supply/cypress/support/api/envelope.ts, toga25-supply/cypress/support/api/users.ts, toga25-supply/cypress/support/api/surfaces.ts, toga25-supply/cypress/support/api/session.ts, toga25-supply/cypress/e2e/login.cy.ts, toga25-supply/cypress/e2e/emptyNavigation.cy.ts, toga25-supply/cypress/component/harness.cy.tsx, toga25-supply/cypress/fixtures/tenants/COMPASS/surfaces/navigation.json, toga25-supply/cypress/fixtures/tenants/COMPASSCANADA/surfaces/navigation.json, toga25-supply/cypress/fixtures/tenants/NYCHH/surfaces/navigation.json, toga25-supply/cypress/fixtures/tenants/QUAD/surfaces/navigation.json, toga25-supply/scripts/cypress.mjs, toga25-supply/tsconfig.node.json, toga25-supply/package.json |
 | [Porting a page (or query) from toga2-supply to toga25-supply](workflows/porting-a-page-from-toga2-supply.md) | `toga25-supply` re-implements pages that already exist in `toga2-supply`. | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/components/ui/Tables/hooks/useExportableData.tsx |

package/knowledge/2.0/apps/toga25-supply/architecture.md

@@ -19,6 +19,7 @@ files:
   - toga25-supply/src/hooks/useTableCellInteractions.ts
   - toga25-supply/src/providers/TalosStreamProvider.tsx
 related:
+  - workflows/cypress-testing.md
   - features/talos-integration.md
   - features/client-configurable-fields.md
   - features/meta-driven-table-data.md
@@ -70,6 +71,18 @@ toga-blox table/modal templates.
 - **UI library:** `@agilant/toga-blox` provides `PrimaryTable*Layout`, `TableRecordModal`,
   `BaseInput`, `BaseButton`, `DetailSection`, the `useTableData` hook, FontAwesome helpers, etc.
 
+### Testing
+
+Two harnesses, both fully stubbed — **no front-end test ever talks to a backend**:
+
+- **Vitest + React Testing Library** (`npm test`) for logic: hooks, view models, auth context,
+  table URL-state, error classification.
+- **Cypress** (`npm run cy:e2e:<tenant>`, `npm run cy:ct`) for the **tenant x role x feature**
+  matrix, driven by per-tenant surface **fixtures** rather than real logins or a seeded database.
+
+The full design, run commands, guardrails and traps live in
+[cypress-testing](workflows/cypress-testing.md) — read that before writing or changing a test.
+
 ## Directory layout (`src/`)
 
 - `pages/<Entity>/` — page component (thin) + `viewModel/` (the `use*PageViewModel` hook) +

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -6,10 +6,12 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-01
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - toga25-supply/src/fieldsConfig/index.ts
+  - toga25-supply/src/fieldsConfig/resolveRole.ts
+  - toga25-supply/src/globalFieldsConfig/clientLoginFields.json
   - toga25-supply/src/fieldsConfig/useClientFields.ts
   - toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/
   - toga25-supply/src/pages/Inventory/viewModel/FIELDS/
@@ -61,6 +63,37 @@ and the `useClientFields()` hook.
    const tenantFields = clientFields.salesOrdersPageFields; // your key
    ```
 
+### How `resolveRole` decides the role (verified 2026-09-03)
+
+`src/fieldsConfig/resolveRole.ts` takes `(clientSlug, user)` and reads **boolean-ish string flags
+off the `/v2/users` record** — `"1"` means set. The flag set and the returned role names **differ
+per client**, and the checks are ordered, so the first match wins:
+
+| clientSlug | flag (in order) | role returned |
+|---|---|---|
+| `COMPASS`, `COMPASSCANADA` | `_isAdmin` | `ADMIN` |
+| | `_isSuperAdmin` | `SUPERUSER` |
+| | `_isSupervisor` | `MANAGER` |
+| | none set | `USER` |
+| `QUAD` | `_isGlobalAdmin` | `GLOBALADMIN` |
+| | `_isBuyer` | `BUYER` |
+| | `_isItShopper` | `ITSHOPPER` |
+| | none set | `USER` |
+| any other client | — | `DEFAULT` |
+
+Two things follow that catch people out:
+
+- **Which flags are even requested is per-client**, declared in
+  `src/globalFieldsConfig/clientLoginFields.json` (`userApiFields`). A flag the client does not
+  request is never fetched, so `resolveRole` cannot see it. `NYCHH`, for example, has no entry, so
+  no role flags are requested and the role is always `DEFAULT`.
+- **An ungranted or unrequested field comes back ABSENT, not null**, from the API (see the
+  [ACL permission chain](../../_underscore/features/acl-permission-chain.md)) — so `user._isAdmin`
+  being `undefined` is the normal shape, not a bug.
+
+The Cypress harness mirrors this table as `roleFlags` per tenant in `cypress/support/tenants.ts`;
+keep the two in step. See [Cypress testing harness](../workflows/cypress-testing.md).
+
 ### By client × role vs. by client only
 
 - **Client × role** (e.g. `salesOrdersPageFields` — ADMIN vs MANAGER see different filter buttons):
@@ -168,6 +201,11 @@ modal's chrome from the same per-client JSON, not from the component:
   `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 2026-09-03 — Documented the actual `resolveRole` flag → role table (COMPASS/COMPASSCANADA:
+  `_isAdmin`/`_isSuperAdmin`/`_isSupervisor`, in that order, else `USER`; QUAD:
+  `_isGlobalAdmin`/`_isBuyer`/`_isItShopper`, else `USER`; every other client `DEFAULT`) and the
+  fact that which flags are requested is itself per-client, via
+  `globalFieldsConfig/clientLoginFields.json` — so NYCHH is always `DEFAULT`. (apeterson)
 - 2026-07-20 — Extracted the **API-fetch projection** out of these presentation JSON blobs into a
   new per-page `apiFields.json` + `useClientApiFields` mechanism (see
   [client-api-fetch-fields](client-api-fetch-fields.md)). The `salesOrderDetailsConfig` block was

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -28,6 +28,11 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
+  - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
+  - toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx
+  - toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx
+  - toga25-supply/src/pages/Bundles/viewModel/useBundlesPageViewModel.tsx
+  - toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
   - toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx
   - toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx
@@ -78,6 +83,7 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx
 related:
+  - ../workflows/cypress-testing.md
   - ../../_underscore/features/surface-resolver.md
   - ../../_underscore/features/sales-order-denial-reason.md
   - meta-driven-table-data.md
@@ -965,7 +971,43 @@ Final: the parameterized FE map above.
 button except **View Log** renders and does nothing on click. Whether the SR modal gets its own
 actions surface is **still an open decision**, not an oversight.
 
+## ⚠ The app still calls the legacy `GET /v2/pages/meta`
+
+Verified 2026-09-03. The Surface layer replaced `Page::meta` **as the source of nav/ACL/label
+config** — that part of the story holds — but the **endpoint is still being called**. Five view
+models call blox's `useFetchPageMeta` → `getPageMeta` → `apiGet("/pages/meta", {page, app})`:
+
+- `src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx` (fires **twice** per landing-page load)
+- `src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx`
+- `src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx`
+- `src/pages/Bundles/viewModel/useBundlesPageViewModel.tsx`
+- `src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx`
+
+**Nothing in `src/` reads any field off the result.** The only references to `pageMeta.acl` are
+*comments* in `src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts` noting it was replaced. So
+these are almost certainly dead weight left over from the Surface migration — but until they are
+removed, the app still makes the call, and a request-level change to `/pages/meta` can still hit
+this app.
+
+Two consequences:
+
+- Any test/stub layer must answer `/pages/meta` or the calls fall through (this is how it was
+  found — the Cypress fall-through guardrail flagged it on its **first** run, not a code read).
+  See [Cypress testing harness](../workflows/cypress-testing.md).
+- **Removing the five calls is separate, unstarted work.** Stubbing them is not the fix.
+
+Related: [legacy page meta](../../_underscore/features/page-meta-context-field-settings.md) and the
+[ACL permission chain](../../_underscore/features/acl-permission-chain.md) (whose "dead config"
+claim is about the `navigation-*` **flags** being inert — still true — not about the endpoint being
+unused).
+
 ## Change history
+- 2026-09-03 — Recorded that the 2.5 app **still calls `GET /v2/pages/meta`** from five view
+  models (SalesOrders — twice per load — VendorItems, Inventory, Bundles, ItemFulfillmentModal)
+  even though nothing in `src/` reads a field off the result. Found by the new Cypress
+  fall-through guardrail. Qualifies, does not overturn, the "Page::meta is replaced" claim: the
+  nav/ACL config really is surface-driven; the endpoint call is leftover. (apeterson)
+
 - 2026-09-03 — **Built the stacked-Total `+` joiner in the Approval Workflow modal**
   (`withStackedCurrencyJoiner`, new `RecordApprovalModal/helpers/stackedCurrencyJoiner.ts` + 13
   vitest cases; one-line wiring in `RecordApprovalModalLayout` `renderField`, workflow modal only —