toga-ai 1.0.768 → 1.0.770

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 —

package/knowledge/2.0/apps/toga25-supply/workflows/cypress-testing.md

@@ -1,143 +1,280 @@
 ---
-title: Cypress Testing Harness (component + e2e)
+title: Cypress Testing Harness (multi-tenant, fully stubbed)
 framework: "2.0"
 repo: toga25-supply
 project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-06-30
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - toga25-supply/cypress.config.ts
+  - toga25-supply/cypress/README.md
   - 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
+  - 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
 related:
-  - ../features/record-modals-and-nested-tables.md
-  - ../features/action-button-rule-engine.md
+  - ../features/surface-frontend.md
+  - ../features/client-configurable-fields.md
+  - ../features/side-navigation-and-default-route.md
+  - ../features/sso-redirect-and-session-gating.md
+  - ../features/force-logout-on-deployment.md
   - ../architecture.md
+  - ../../../2.0/standards/frontend.md
 ---
 
 ## What it is
 
-The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch
-(`cypress` was already a dependency but there was no config, no `cypress/` dir, and zero
-tests anywhere in the repo). It defines **both** a `component` project (Vite devServer,
-mounts a single component) and an `e2e` project, plus reusable support code for mounting
-components with the app's providers, mocking a component's data hook without a network or
-tenant config, and sharing fixtures. The first specs cover the Sales Order **approval
-modal flow**. Use this doc when adding any new test to the repo.
-
-## How the harness is wired
-
-### `cypress.config.ts` — two projects
-
-- **`component`** — `devServer: { framework: "react", bundler: "vite" }` with a `viteConfig`
-  that **mirrors the app's `vite.config.ts`**: the `@` → `src` alias, the regex aliases that
-  force a single React copy, `optimizeDeps.exclude: ["@agilant/toga-blox"]` +
-  `optimizeDeps.include: ["dayjs"]`. This is the load-bearing part — toga-blox must resolve
-  the same way it does under `npm run dev`, or mounted components fail to bundle or get a
-  second React copy.
-- **`e2e`** — standard `baseUrl` + `supportFile` setup for full-journey specs.
-
-### `cypress/support/component.tsx` + `commands.ts` — mounting with providers
-
-`cy.mountWithProviders` is a custom command that wraps the mounted component in
-`QueryClientProvider` + `ToasterProvider`. It accepts an **injectable `queryClient`** so a
-spec can `cy.spy()` on `removeQueries` / `invalidateQueries` and assert the cache routine a
-component runs on success. The default QueryClient is configured with `retry: false` for
-determinism. Support also imports `@/index.css` (styling) and `@/api/api` — the latter so
-toga-blox's `apiPost` / `apiPut` have a configured axios instance available during component
-tests.
-
-### Window-backed hook-mock pattern (key technique)
-
-`cypress/support/mocks/useApprovalModalViewModel.ts` lets you unit-test a data-binding
-component **without** a network or tenant config. The component devServer aliases the
-component's **relative** import of its view model to the mock:
-
-```ts
-// in the component viteConfig resolve.alias
-{ find: /^\.\/viewModel\/useApprovalModalViewModel$/, replacement: "<abs>/cypress/support/mocks/useApprovalModalViewModel.ts" }
-```
-
-The mock returns whatever the spec parked on `window.__approvalModalViewModel`. In Cypress
-component testing the spec and the component share the **same `window`**, so a plain
-assignment before `cy.mount` is visible to the hook. Helpers `setApprovalModalViewModel` /
-`resetApprovalModalViewModel` set and clear it. To mock a different component's hook, add a
-parallel regex alias + a parallel `window.__<name>` mock.
-
-### `cypress/support/fixtures.ts` — shared fixtures
-
-Imports the **real shipped** tenant config
-`src/pages/SalesOrders/.../viewModel/FIELDS/QUAD/approvalActionFields.json` as
-`recordActionFields`, so tests track the actual field / label / guardrail config the app
-ships (not a hand-rolled copy that drifts). Adds synthetic order / approval-stages / PO
-fixtures alongside it. (The QUAD file is reused only as a representative real config — this
-harness is generic test infra, not Quad-specific behavior.)
-
-## What the specs cover
-
-- **`SalesOrderApprovalModalsLayout.cy.tsx`** (component) — the sales-order binding:
-  null-guards, `isApproveButtonEnabled` derivation, and the documented `onSuccess` cache
-  routine asserted via the spied QueryClient.
-- **`RecordApprovalModalLayout.cy.tsx`** (component) — the generic approval modal flow: deny
-  requires a reason (approve optional), submit fires the decision API + `onSuccess`/`onClose`,
-  discard-reason guardrail on Cancel/backdrop, workflow approve-enablement, deep workflow
-  stage editing (deny one stage with a required note → submits only that stage; an empty
-  required note blocks submit), and the **decision-failure path** (500 → modal stays open,
-  `onSuccess`/`onClose` not called).
-- **`EnterPoNumberModal.cy.tsx`** (component) — the PO-number action: create requires a PO#,
-  POST `/purchase-orders/`, credit-card flag `0`/`1`, edit → PUT.
-- **`salesOrderApproval.cy.ts`** (e2e) — full journey: seed auth via
-  `localStorage.accessToken`, row-action menu → Deny → submit, stubbing only the write.
-
-## Conventions for writing tests here
-
-- **Component test of a data-binding component** → use the window-backed hook mock so you
-  never need a real network/tenant config; park state on `window.__<hook>` before `cy.mount`.
-- **Asserting a cache side-effect** (invalidate/remove queries on success) → inject a spied
-  `queryClient` into `cy.mountWithProviders`.
-- **Testing an async error path** → use `cy.on("uncaught:exception", ...)` to swallow the
-  rejected `mutateAsync` so the rejection doesn't fail the spec, then assert the modal stayed
-  open and `onSuccess`/`onClose` were not called.
-- **e2e auth** → seed `localStorage.accessToken`; stub only the write request, let reads hit
-  the configured backend (document any backend prerequisites in the spec).
-- **Keep the component devServer config in sync with `vite.config.ts`** — when the app's
-  Vite aliases or `optimizeDeps` change, mirror the change into `cypress.config.ts` or
-  component mounts break.
-
-## package.json scripts
-
-`cy:open`, `cy:run:ct` (component), `cy:run:e2e`, `test:ct`.
-`.gitignore` excludes `cypress/videos|screenshots|downloads`.
+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 a backend. It exists to test
+the thing that actually breaks in this app — **tenant × role × feature** — without needing real
+logins or a seeded database.
+
+Current state (2026-09-03, branch `TRUE-81735`, working tree only): **26 tests green** —
+6 e2e specs × 4 tenants (COMPASS, COMPASSCANADA, NYCHH, QUAD) + 2 component tests.
+`cypress/README.md` is the hands-on version of this doc for a developer working without Claude
+(run commands, recipes, traps). Read that to *write* a test; read this to understand *why* it is
+shaped this way.
+
+> **This replaces the earlier harness.** A first harness (approval-modal component specs, a
+> window-backed hook-mock pattern) was built on branch **`TRUE-79813`** (commit `962a41d`
+> "Save") and **never merged** — it is not on `_main`, `_production`, or any other branch, and
+> its mirrored Vite config is now stale (hardcoded `optimizeDeps.exclude` for blox, 3-member
+> `dedupe`). The decision was to **build fresh on `TRUE-81735`** rather than port it. If you go
+> looking for `cy.mountWithProviders` or `cypress/support/mocks/`, that is where it lives — a
+> stranded branch, not the live harness.
+
+## The three multi-tenant axes (the core design)
+
+The app is multi-tenant along three axes, and **each has a different source of truth**, so each
+is modelled in a different place. Get this and the rest of the harness follows.
+
+| Axis | Source of truth in the app | Modelled in the harness as |
+|---|---|---|
+| **Client** | `window.location.hostname` — `useHostnameStore` takes the first label, upper-cased | the **`baseUrl`** Cypress visits (`TENANT` env var → `TENANT_HOSTS` in `cypress.config.ts`) |
+| **Role** | flags on the `/users` record, resolved client-side by `src/fieldsConfig/resolveRole.ts` | `roleFlags` per tenant in `cypress/support/tenants.ts` (mirrors that function) |
+| **Features / permissions** | 100% backend — the **Surface** bundles (there is no front-end roster any more) | per-tenant JSON **fixtures** under `cypress/fixtures/tenants/<SLUG>/surfaces/` |
+
+**One tenant per run.** Because the client *is* the URL, and Cypress allows one superdomain per
+spec (`compass.togasupply` and `nychh.togasupply` are different superdomains), the runner targets
+a single tenant per invocation: `npm run cy:e2e:compass`, `…:compasscanada`, `…:nychh`, `…:quad`,
+and `cy:e2e:all` chains them. `cypress/support/e2e.ts` has a `before()` that fails the run if
+`Cypress.env("tenant")` and `baseUrl` disagree.
+
+**One dev server serves every tenant.** It binds `127.0.0.1` and `vite.config.ts` sets
+`allowedHosts: ['.togasupply']`. So `npm run dev` **once**, then run any tenant. Each tenant host
+needs a `127.0.0.1` line in `/etc/hosts`.
+
+**Adding a tenant = 3 edits, no spec changes:** one entry in `TENANTS` (`support/tenants.ts`),
+one fixture folder, and one **static** import + map entry in `support/api/surfaces.ts` (Cypress
+bundles the support file with esbuild, so the imports cannot be dynamic). The specs read the
+registry, so they pick it up.
+
+## Derived vs fixtured — the split, and why
+
+- **`/users` records are DERIVED.** `support/api/users.ts` builds them from the tenant's
+  `roleFlags` **plus the app's own `src/globalFieldsConfig/clientLoginFields.json`**, so a new
+  login field there is picked up automatically instead of drifting. Critically, the builder
+  returns **only the fields that client requests** — an ungranted or unrequested field comes back
+  **ABSENT (not null)** from the real API, so a stub that always returned every flag would hide
+  that whole class of bug.
+- **Surface bundles are FIXTURED.** They carry real per-client config that cannot be derived
+  from anything on the client — they *are* the thing being simulated. Copy a real
+  `GET /v2/surfaces/meta` bundle into the fixture folder and edit it.
+- **A slug with no fixture resolves to an EMPTY bundle** (`emptyBundle()` in
+  `support/api/surfaces.ts`) — which is the real "client not seeded / not granted" state and
+  exercises the FE's design-literal fallbacks. Leaving a slug unfixtured is the *correct* way to
+  test an un-onboarded client (`e2e/emptyNavigation.cy.ts` does exactly this).
+
+## The stub layer
+
+`cy.stubApi({ tenant?, role?, surfaces?, user?, domainIsValid? })` registers a catch-all plus a
+handler for every endpoint the app calls: `auth/public`, `auth/refresh`, `auth/login`, `users`,
+`surfaces/meta`, `surfaces/meta-group`, `core-parameters`, `pages/meta`, `table-views/meta`,
+`domains`, `client-authentications/singleSignOnServiceUrl`.
+
+`support/api/envelope.ts` builds the V2 wrapper (`v2Envelope` / `v2Empty` / `v2Failure`). blox's
+`apiGet`/`apiPost` return `response.data` — i.e. the **whole envelope** — so app code reads
+`envelope.data.<route>`; a stub that puts the payload anywhere else reads back `undefined` and
+the failure looks like a front-end bug.
+
+Three custom commands: `cy.stubApi()`, `cy.visitAsGuest(path)` (storage cleared → anonymous),
+`cy.loginAs(role, path)` (seeds a session, lands signed in), plus `cy.getByTestId()` and
+`cy.allowUnstubbedApiCalls()`. Selector convention: prefer `data-testid`, but use an existing
+stable semantic attribute (`input[name]`, `button[type=submit]`, `a[href]`) rather than adding a
+testid for its own sake.
+
+## Guardrails built into the suite
+
+### The fall-through check (the main one)
+
+A catch-all intercept **scoped to the `/v2` path** answers anything not modelled — with an empty
+**success** envelope — and **records the URL**. A global `afterEach` in `support/e2e.ts` fails the
+test if that list is non-empty.
+
+- **Why a catch-all at all:** an un-stubbed request would otherwise escape to the real backend —
+  slow, non-deterministic, and it can **write real data**.
+- **Why it must be registered FIRST:** Cypress matches intercepts in **reverse order of
+  definition**.
+- **Why it is path-scoped:** a bare `**` would also swallow the Vite dev server's own HTML/JS/CSS.
+- **Why the check is worth it:** one check catches **four** bugs — a non-matching intercept
+  pattern, a typo'd path, a wrong HTTP method, and an endpoint the app newly calls that nobody
+  stubbed. All four are otherwise **completely silent**: the catch-all answers 200 with an empty
+  envelope, so the app just behaves as though the record did not exist and the spec goes green on
+  wrong behaviour. It was chosen over a lint/text-grep rule because it checks the **real failure**
+  ("a call fell through") rather than one way of causing it.
+- **Trade-offs, know them:** (a) a failed `afterEach` **aborts the remaining tests in that spec
+  file** (Mocha behaviour), so the first fall-through hides the other results; (b) it is strict —
+  when the app starts calling something new the suite fails until someone stubs it. That is the
+  intent.
+- **Escape hatch:** `cy.allowUnstubbedApiCalls()` opts **one** test out. Use it only when the
+  un-modelled call *is* the point.
+
+### The once-per-test check
+
+`cy.stubApi()` must be called **exactly once per test** — a second call registers a **second
+catch-all**, and the resulting match order stops the specific intercepts from winning, so a call
+that **is** stubbed falls through anyway. This bit the author's own spec: `stubApi()` ran in both
+`beforeEach` and the test body, `/surfaces/meta?slug=login` fell through, and **the test still
+passed — for the wrong reason**. Fixed by giving that test its own `describe` + `beforeEach`;
+`stubApi()` now **throws** on a second call with the fix in the message. Per-test state is reset
+**only** from the global `beforeEach`, deliberately *not* inside `stubApi()`, so a double call is
+detectable instead of silently self-healing.
+
+### The component canary
+
+`cypress/component/harness.cy.tsx` mounts a blox component and asserts one React + one
+QueryClient. It fails when the component-test Vite config drifts from `vite.config.ts`.
+
+### Not built: CI
+
+There is **no** CI for this yet. Worth knowing before you plan it: a workflow must add the four
+`*.togasupply` `/etc/hosts` entries as a step (the tenant is resolved from the hostname) and serve
+a build (`vite preview` / `start-server-and-test`).
+
+## How to run it
+
+1. `npm run dev` once (any tenant — one server serves all of them).
+2. `npm run cy:e2e:compass` (or `:compasscanada`, `:nychh`, `:quad`, or `cy:e2e:all`).
+3. `npm run cy:ct` for component tests; `cy:open` / `cy:open:<tenant>` for the GUI.
+4. `npm run test:types:cypress` type-checks the specs (`tsc --noEmit -p cypress/tsconfig.json`).
+
+Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the first gotcha below.
 
 ## Gotchas
 
-- **Cypress's bundled Electron cannot launch in the sandboxed macOS dev environment** — it
-  fails the pre-run smoke test (`bad option: --no-sandbox / --smoke-test / --ping`), which
-  blocks **all** specs before any run. The specs in this harness were validated by
-  `tsc -p cypress/tsconfig.json` (0 errors) and `eslint cypress` (clean) but **could not be
-  executed in that sandbox** — run them locally with `npm run cy:run:ct`.
-- **`eslint.config.js` is protected by a config-protection hook.** When a spec/support file
-  trips a lint rule (e.g. `no-explicit-any`), **fix the source to satisfy the linter** (use
-  `unknown` / typed shapes) — do **not** weaken the shared eslint config to make tests pass.
-  The override edit to `eslint.config.js` is blocked by the hook by design.
-- **`@agilant/toga-blox` consumes `dist/`** — same as the app, the harness sees built
-  toga-blox, so a toga-blox source change needs a rebuild before tests observe it.
+- **⚠ `bad option: --no-sandbox` is `ELECTRON_RUN_AS_NODE`, NOT a macOS sandbox problem.**
+  Cypress fails in *"Verifying Cypress can run"* with
+  `.../Cypress.app/Contents/MacOS/Cypress: bad option: --no-sandbox` (also `--smoke-test`,
+  `--ping=NNN`). **Cause:** VS Code exports `ELECTRON_RUN_AS_NODE=1` into its integrated terminal
+  and into shells its extensions spawn; Cypress's bundled Electron reads it and runs as plain
+  Node, which rejects Electron's own flags. **The tell is the wording** — `bad option:` is
+  *Node's* format for an unknown CLI flag. Verified 2026-09-03: disabling the tool sandbox does
+  **not** help; `env -u ELECTRON_RUN_AS_NODE npx cypress run` works immediately. **Fixed
+  permanently** by `scripts/cypress.mjs`, which deletes the variable before spawning (the same
+  trap exists on Windows, hence a Node wrapper rather than `env -u`), and all `cy:*` scripts route
+  through it. *(This doc previously recorded it as an unfixable environment blocker — it is a
+  one-line fix.)*
+- **⚠ NEVER match an intercept with a URL glob — match on `pathname`.** Every request carries a
+  query string (blox's axios interceptor appends `transactionId`; `assembleOptions` serializes
+  `fields`/`join`/`where` into it) and **some values contain a slash**. Real captured `/domains`
+  example: `…AND,SelfDomains.domain:like:http://compass%2Etogasupply)&transactionId=…`.
+  minimatch's `*` does not cross `/`, so `**/v2/domains*` **silently fails to match** and the
+  catch-all answers instead — which made the login form show *"Error validating domain"* and made
+  one test pass for the wrong reason. Use
+  `cy.intercept({ method: "GET", pathname: apiPath("domains") }, …)`. Confirmed by mutation:
+  reverting one intercept to the glob form made the fall-through guardrail fail and print the URL.
+- **The session key is `user`, not `accessToken`.** blox's `fetchPublicToken` writes an
+  `accessToken` (and `refreshToken`) for **logged-out** requests, so a token alone makes an
+  anonymous visitor look signed in. `AuthContext` and `useAuthenticationFlow` both key on
+  **`user`**. A seeded session must write `accessToken`, `refreshToken`, `user`, `zu-user` (the
+  zustand `useUserStore` persist key — the side-nav footer reads name/initials there) and
+  `deployment-version` (keeps `useDeploymentGuard` inert).
+- **Seed in `cy.visit`'s `onBeforeLoad`.** Zustand `persist` and the persisted React Query cache
+  both rehydrate on **page load only** — an in-app navigation will not pick up storage you wrote
+  mid-test.
+- **Clear the persisted query cache between tests.** It lives in localStorage under
+  `supply-chain-query-cache`. `src/App.tsx` excludes `surface-meta` / `surface-meta-group` from
+  persistence, but **`currentUser` — which carries the ROLE FLAGS — is persisted**, so one test's
+  role bleeds into the next unless storage is cleared.
+- **Nav links exist but are not visible.** The side nav is a native `popover="auto"` element (blox
+  `SideNav.Content`), so assert `exist`, **not** `be.visible`, unless the test opens the hamburger.
+  Items render as `<a href="/path">` because `SideNav.NavigationItem` passes
+  `{ as: NavLink, to: path }` through blox's polymorphic `BaseButton`.
+- **Stub `/table-views/meta` with `isSuccess: false`.** blox's `getDataTableMeta` maps that to
+  `{ table: null }`, which `useFetchTablePageMeta` documents as the "meta not ready" path. An
+  empty **success** envelope instead leaves `table` **undefined**, slips past every downstream
+  guard, and crashes in `buildUrl` (`route.includes` on `undefined`).
+- **The envelope's data key is the route name in camelCase:** `purchase-orders` →
+  `purchaseOrders`, `core-parameters` → `coreParameters`, `client-authentications` →
+  `clientAuthentications`, `table-views` → `tableViews`.
+- **`GET /v2/domains` has two callers with different field sets** — blox `validateEmailDomain`
+  (the login form) and `useAuthenticationFlow.checkSsoAuth`, which reads
+  `domains[0].ClientAuthentications.type` and **redirects to the IdP** when it is `SSO`. One
+  stubbed row typed `PASSWORD` satisfies both and keeps the suite on the local login form. Also:
+  `useAuthenticationFlow` returns early when `pathname === "/login"`, so visiting `/login`
+  directly never triggers the SSO check.
+- **`surfaces/meta-group`: do not add a sibling key whose value is `null`.** `findSurfaceMap`
+  treats a map containing an explicit null as the slug-keyed one, so a `group: null` sibling wins
+  over the real map.
+- **Config files type-check green by never being compiled.** `cypress.config.ts` and
+  `vitest.config.ts` were checked by **nothing** until both were added to
+  `tsconfig.node.json`'s `include` — the same false-green class already documented for this repo
+  (the root `tsconfig.json` is references-only, so a bare `npx tsc --noEmit` always exits 0).
+- **`cypress.config.ts` is loaded as NATIVE ESM** by Cypress (`package.json` is `type: module`),
+  unlike `vite.config.ts` which Vite transpiles — so `__dirname` does not exist there. Derive it
+  with `fileURLToPath(import.meta.url)`.
+- **The component-test Vite config MUST mirror `vite.config.ts`, including the `isBloxLinked`
+  branch.** Otherwise mounted components get a second copy of React / react-query — "Invalid hook
+  call", or "No QueryClient set" with the provider plainly visible in the stack.
+  `component/harness.cy.tsx` is the canary that fails when it drifts.
+- **Scrub captured payloads.** Copying a real body out of Chrome DevTools (Network → filter
+  `/v2/` → Response → Copy response) is the fastest way to build a fixture — but those payloads
+  carry **real customer data**. Remove emails, names, addresses and tokens before committing.
+
+## Rest of the repo's test state (for context)
+
+- **Vitest is the other half.** `npm test` (`vitest run`) currently has **one failing test file**:
+  `src/hooks/useTalosSurface.test.ts` fails with
+  `TypeError: Unknown file extension ".css"` on `@agilant/toga-blox/dist/global.css`. 89 tests pass
+  across the other 13 files. **Pre-existing** — the file was last touched in commit `604a779` and
+  the Cypress work changed neither it nor `vitest.config.ts`. Needs a separate fix (Vitest CSS
+  handling for blox imports).
+- **No other mechanical guardrails exist in this repo:** no `.github/workflows`, no husky, no
+  lint-staged. The only `.git/hooks/pre-commit` is a machine-local `code-review-graph` shim that
+  always exits 0 and is not checked in.
+- **Green FE tests do not mean a client gets a feature.** Real rollout is a role-scoped
+  `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`; the fixture only simulates the grant.
 
 ## Change history
-- 2026-06-30 — Bootstrapped the Cypress harness from scratch (dual component + e2e config,
-  `cy.mountWithProviders`, window-backed hook-mock pattern, shared fixtures off the real
-  QUAD `approvalActionFields.json`) and added the first specs for the Sales Order approval
-  modal flow. Documented the sandbox-Electron blocker and the protected-eslint decision.
-  (apeterson)
+- 2026-09-03 — **Rebuilt the harness from scratch on `TRUE-81735`** (the `TRUE-79813` harness this
+  doc used to describe was never merged and is stranded there). New shape: all `/v2` calls stubbed,
+  four tenants (COMPASS/COMPASSCANADA/NYCHH/QUAD), the three-axes model (client = baseUrl, role =
+  `roleFlags` mirroring `resolveRole`, features = surface fixtures), derived `/users` vs fixtured
+  surface bundles, and the fall-through + once-per-`stubApi()` guardrails. 26 tests green.
+  **Corrected** the old "Cypress's Electron cannot launch in the sandboxed macOS environment"
+  gotcha: it is `ELECTRON_RUN_AS_NODE=1` inherited from the VS Code shell, fixed by
+  `scripts/cypress.mjs`. Recorded the `pathname`-not-glob intercept rule, the `user`-key session
+  facts, and the pre-existing `useTalosSurface.test.ts` Vitest failure. (apeterson)
+- 2026-06-30 — First harness bootstrapped on branch `TRUE-79813` (approval-modal component specs,
+  `cy.mountWithProviders`, window-backed hook mocks, fixtures off the real QUAD
+  `approvalActionFields.json`). **Never merged**; superseded by the 2026-09-03 rebuild. (apeterson)

package/knowledge/2.0/standards/frontend.md

@@ -672,20 +672,96 @@ consuming app, guard against them and move on.
 
 ---
 
+## 23. Front-end test layering — **MUST / SHOULD**
+
+Pick the layer by **what the test is actually checking**, not by habit. Three layers, three jobs:
+
+| Layer | Use it for | Tooling |
+|---|---|---|
+| **Unit / logic** | hooks, view models, resolvers, error classification, URL-state | **Vitest + React Testing Library** (jsdom, co-located `*.test.ts(x)`) |
+| **Component** | the **tenant x role x feature** matrix — the thing that actually breaks | **Cypress component tests** |
+| **e2e** | a handful of real user journeys, end to end | **Cypress e2e** |
+
+**MUST — the tenant x role x feature matrix belongs in COMPONENT tests, not e2e.** This is the
+rule most often gotten wrong. Multi-tenant, role-scoped rendering is a *rendering* question: mount
+the component with a tenant + role + surface bundle and assert what appears. Driving that same
+matrix through e2e multiplies runtime and flake for no extra signal, and e2e can only cover one
+tenant per spec anyway (the client *is* the hostname, and Cypress allows one superdomain per spec).
+
+**SHOULD — reserve e2e for a few genuine journeys** (log in, land on the default route, navigate).
+Rule of thumb: **no URL change or page transition => it is not an e2e test.** If the assertion is
+"this field/button/column renders for this client and role," that is a component test.
+
+**MUST — STUB the surface bundles; never point a front-end test at a backend.** Features and
+permissions are 100% server-driven (the Surface bundles — there is no front-end roster any more),
+so a front-end test must supply them as **fixtures**. A test that reaches a real API is slow,
+non-deterministic, and **can write real data**. Two consequences worth internalizing:
+
+- Answer **every** API call, including a **path-scoped catch-all registered first**, and fail the
+  test when anything falls through. One check catches four otherwise-silent bugs: a non-matching
+  intercept pattern, a typo'd path, a wrong HTTP method, and an endpoint the app newly calls that
+  nobody stubbed. All four are silent because the catch-all answers 200 with an empty envelope, so
+  the app behaves as if the record did not exist and the spec goes **green on wrong behaviour**.
+- **Derive what you can, fixture only what you must.** Build user/permission records from the
+  app's own config so a new field is picked up instead of drifting; fixture only the payloads that
+  cannot be derived from anything on the client. Return a field **absent, not null**, when the real
+  API would omit it — a stub that always returns everything hides that entire class of bug.
+
+**MUST — every new test is SEEN TO FAIL before it is allowed to pass.** A test written straight to
+green has proven nothing; on a stubbed harness a test can easily pass for the wrong reason. Break
+the thing under test on purpose, watch the test go red, then restore it. The two mutations actually
+run against the reference implementation on 2026-09-03, both of which produced the expected red:
+
+1. **Break the config the test reads.** The tenant registry was edited to claim `QUAD` is granted
+   `transfer-orders` while its surface fixture still withheld it. The nav test failed with
+   `Expected to find element: a[href="/transfer-orders"], but never found it.` — proving the test
+   reads the real resolved nav, not the registry it was seeded from.
+2. **Break the app code the test covers.** `getUserFieldsForClient` was forced to always return the
+   `DEFAULT` field list, dropping every role flag. The user-fields test failed with
+   `expected 'firstName,lastName,email,uuid' to include '_isAdmin'` — proving it would catch a real
+   regression that silently demotes every admin to `USER`.
+
+Mutate **the thing under test**, not the harness. Verifying a *guardrail* (e.g. reverting an
+intercept to a URL glob to confirm the fall-through check fires) is a separate and also worthwhile
+exercise, but it proves the guard works — not that any test does.
+
+**MUST — every config file is type-checked.** A config that no `tsconfig` includes is compiled by
+**nothing** and is green by default — the same false-green class as running bare `npx tsc --noEmit`
+against a references-only root `tsconfig.json` (§2). Add `vite.config.ts`, `vitest.config.ts` and
+`cypress.config.ts` to `tsconfig.node.json`'s `include`, and type-check test specs with their own
+project (`tsc --noEmit -p cypress/tsconfig.json`).
+
+- ⚠ **`cypress.config.ts` is loaded as NATIVE ESM** by Cypress when `package.json` is
+  `type: module` — unlike `vite.config.ts`, which Vite transpiles. So **`__dirname` does not exist
+  there**; derive it with `fileURLToPath(import.meta.url)`.
+
+> ⚠ **Green front-end tests do NOT mean a client gets a feature.** The fixture only *simulates*
+> the grant. Real rollout is a **role-scoped `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`**.
+> Never close a client-enablement ticket on a passing front-end suite.
+
+**Reference implementation:** the worked harness for all of the above is
+[toga25-supply Cypress testing](../apps/toga25-supply/workflows/cypress-testing.md) — three-axis
+tenant model, the stub layer, the fall-through and once-per-`stubApi()` guardrails, and the traps.
+Copy from there rather than reinventing.
+
+**Do not** conflate any of this with the team's unresolved **backend** testing question — that is
+**PHP-only** and settled nothing here.
+
+---
+
 # Part 3 — Open items
 
 *(Described and flagged. NOT prescribed as settled.)*
 
-- **Front-end testing — SHOULD-lean, not yet a settled standard.** The reality (verified
-  2026-08-18): `toga25-supply` **and** `toga-blox-npm` both run **Vitest + React Testing Library**
-  (jsdom, `globals: true`, a setup file, co-located `*.test.ts(x)`). Supply has **real tests on the
-  tricky bits** — auth context, table URL-state, error classification — with `@vitest/coverage-v8`;
-  blox configures istanbul coverage. `toga25-desk` has **no test script and an empty Cypress
-  scaffold**. Recommendation: **Vitest + RTL for unit / logic-hook tests** — a firm SHOULD, since it
-  is real in 2 of 3 sources and mirrors how `backend-testing.md` prescribes a path even without a
-  formal harness — with **Cypress reserved for E2E** (acknowledged empty today). A dedicated
-  `frontend-testing.md` sibling is the likely eventual home. **Do not** conflate this with the
-  team's unresolved *backend* testing question — that is PHP-only.
+- **Front-end testing — SETTLED; moved to §23.** No longer an open item. Test layering (Vitest +
+  RTL for logic, Cypress **component** tests for the tenant x role x feature matrix, Cypress e2e
+  for a few real journeys), fully-stubbed surface bundles, the see-it-fail rule and config
+  type-checking are now prescribed in
+  [§23 Front-end test layering](#23-front-end-test-layering--must--should), with the worked harness
+  in [toga25-supply Cypress testing](../apps/toga25-supply/workflows/cypress-testing.md). A
+  dedicated `frontend-testing.md` sibling remains the likely eventual home if §23 outgrows this
+  doc. Still **not** to be conflated with the unresolved *backend* testing question — that is
+  PHP-only.
 - **`eslint-plugin-jsx-a11y` not configured** (§10) — a11y is convention-only, not lint-enforced in
   any of the three repos. Recommend adopting it.
 - **Client error-reporting gap.** Verified 2026-08-18: all three repos depend on `@sentry/react`
@@ -709,6 +785,23 @@ consuming app, guard against them and move on.
 
 ## Change history
 
+- 2026-09-03 — §23 correction: replaced the two "seen to fail" worked examples. The first pass
+  listed a guardrail check plus an **unverified** component-config mutation; both are now the two
+  mutations that were actually run and observed red (a registry/fixture nav mismatch, and forcing
+  the `DEFAULT` user field list). Added the distinction that mutating the harness verifies a
+  **guard**, not a **test**. (apeterson)
+- 2026-09-03 — **Front-end testing promoted from an open item to §23 (MUST/SHOULD).** Settles the
+  layering: Vitest + RTL for logic, Cypress **component** tests for the tenant x role x feature
+  matrix (**not** e2e), e2e for a few real journeys only, with the rule of thumb "no URL or page
+  transition => not an e2e test". Adds the MUSTs to **stub the surface bundles and never point a
+  front-end test at a backend** (path-scoped catch-all registered first + fall-through failure;
+  derive what you can, fixture what you must, return absent-not-null), to have **every new test
+  seen to fail before it passes** (two worked mutation examples: glob-vs-`pathname` intercept
+  matching, and the blox-linked component-config drift canary), and to **type-check every config
+  file** — including that `cypress.config.ts` loads as native ESM so `__dirname` is unavailable.
+  Warns that green front-end tests do not enable a feature for a client — that is a role-scoped
+  `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`. Reference implementation:
+  `../apps/toga25-supply/workflows/cypress-testing.md`. (apeterson)
 - 2026-09-03 — §11: replaced supply's stale three-member `dedupe` list with the verified
   seven-member one and added `react-hook-form` (it was in neither `dedupe` nor `alias` while 24
   `src` files import it and blox's `BaseInput` calls `useFormContext()`). Added a SHOULD for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.768",
+  "version": "1.0.770",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",