toga-ai 1.0.239 → 1.0.241

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

@@ -5,7 +5,7 @@
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
-| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
+| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, _underscore/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -6,10 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-06-30
 owners: [dfranks]
 files:
   - test/@dave/checker.php
+  - _underscore/Component/Forecast/SaleImport/SaleImport.php
   - test/@dave/looper.php
   - test/@dave/reconcile_netsuite_totals.php
   - test/@dave/fixer.php
@@ -32,6 +33,7 @@ related:
   - ../architecture.md
   - ../../library/features/netsuite-suiteql-rest-shim.md
   - ../../library/features/netsuite-suiteql-api-reference.md
+  - ../../_underscore/features/forecast-sale-import.md
 ---
 
 ## Summary
@@ -202,6 +204,47 @@ by reconciling a chosen tranDate range directly against NetSuite.
   on `tranDate`, not NS `lastmodifieddate`, so a **symmetric** lastmodified fingerprint isn't possible — it
   would require NS-pull-then-id-lookup or the recency-pruned approach.
 
+- **JOURNAL ENTRIES are reconciled WITHIN the SALES category, not as a separate category (TRUE-79862
+  architecture decision, dfranks).** A JE is **not its own reconciliation category** — JE rows live in
+  the **same `Forecast.Sales` table** as the four sale types (`netsuiteTransactionType='journalEntry'`),
+  written by the same `_Component_Forecast_SaleImport` importer (see the sale-import doc's *JournalEntry
+  import* section). So the **sales pass covers the WHOLE `Sales` table**, sale-types + JEs together:
+  - **`fixer.php`** — `findSalesDiscrepancies` merges, on the **NS side**, the sale-type per-line aggregate
+    with `journalEntryNsTotals()` (a GL-account-grouped JE helper); the **FC side reads ALL `Sales` rows**
+    (no type filter); each discrepancy is tagged **`kind` (`'sale'` | `'je'`)**. The FIX dispatch routes
+    sale ids to `fixSales()` and JE ids to `fixJournalEntries()`. The per-corrector DELETE scoping stays
+    **per-type** (`fixSales` delete-candidates scoped to the 4 sale types; `fixJournalEntries` scoped to
+    `'journalEntry'`) so neither corrector deletes the other's rows.
+  - **`checker.php`** — the sales `nsSub` is a **`UNION ALL`** of the sale-type arm and a JE arm; the sales
+    `fcSub` reads **all `Sales` rows**. checker needs **no per-item/JE-specific logic** because its
+    fingerprint compares per-transaction (per-id) totals + the id-set, which are **item-agnostic**.
+- **JE→`Forecast.Sales` reconciliation math + scope (mirrors `_Component_Forecast_SaleImport::buildJournalEntryRows`).**
+  Only JE lines posting to the revenue/cost **account-NUMBER allowlist** are sales-relevant: revenue
+  `41100/41300/41500`, cost `51100/51200` (exact-number, never prefix — see the sale-import doc for the
+  sub-account traps). `revenue = Σ(−foreignamount)` over revenue-acct lines; `profit = Σ(−foreignamount)`
+  over **all** allowlisted lines (cost lines net profit down via debit-positive `foreignamount`). Group by
+  **(local salesRep, item)** → one Sales row per group; synthetic `lineNumber` from
+  `ksort(json_encode([salesRepId,itemId]))` then `1..N` — **fixer MUST key identically** or its upsert
+  dupes against the webhook importer's rows. JE `foreignamount`s are **cent-precision**, so a per-JE
+  sum-then-round equals the importer's per-salesRep round-then-sum **exactly** — this is what keeps
+  checker's "in sync" == fixer's "nothing to fix" for JEs (the compute-identically invariant applied to JEs).
+  Scope facts: of **~1235 JEs** in 2025-01-01..present, only **~295** touch a revenue/cost account; **~34**
+  of those net to **0 rev AND 0 profit** and import no rows. JEs hitting only bank/equity/tax/AP accounts
+  are correctly excluded **by design** (e.g. JE 7213407 = a Bank↔Equity reclass, 0 allowlist lines → never
+  imported — not a miss). An accrual JE and its NetSuite auto-reversal are **separate transactions**, each
+  reconciled independently by its own `internalId`.
+- **JE item dimension is NULL today; here is how to enable it later.** `itemId` is null on JE Sales rows
+  because the JE import path reads item **only** via the configurable `JE_LINE_ITEM_FIELD` (currently null)
+  — it does **not** read native `transactionline.item`, so even a populated native `tl.item` would NOT flow
+  through. To enable: (1) set `JE_LINE_ITEM_FIELD` to the source field (`'item'` for native, or a
+  `custcol_*` if a custom column is added) — `journalLineLookup` then resolves it via
+  `lookupId('Items','netsuiteItemInternalId',…)` and the group key already carries the item slot; AND (2)
+  update **`fixer.php`** to SELECT the item column in its JE SuiteQL, resolve NS item→local id (reuse
+  `createMissingForecastItemFromNetSuite` self-heal), and extend the group key to `(salesRep, item)`.
+  **`checker.php` needs no change.** Consider whether item should self-heal (salesRep does **not** — see
+  the sale-import doc). The salesRep dimension itself is the JE line custom column `custcol_sales_rep_line`
+  (wired under TRUE-79862).
+
 ## Data model
 
 `Forecast.Sales`, `Forecast.OpenOrderItems` on the **core2** cluster
@@ -214,6 +257,16 @@ None — Forecast2 is a single shared dataset.
 
 ## Gotchas / known issues
 
+- **CROSS-TYPE CONTAMINATION: once JEs share `Forecast.Sales`, any FC Sales read missing a type scope
+  treats JE rows as rogue sales.** Discovered live (TRUE-79862): the SALES fix **deleted 74 JE rows
+  (8 JEs) as "stale sales"** because `findSalesDiscrepancies`'s FC query had **no type filter**, so JE
+  rows looked like FC-only sales that the NS-sales aggregate never returns. **Correct resolution is NOT
+  to filter JEs OUT of the sales pass** — it is to reconcile the **whole table together** (NS side =
+  sale-types `UNION` JE; FC side = all rows) and **route the FIX by `kind`** (`'sale'`→`fixSales`,
+  `'je'`→`fixJournalEntries`), keeping each corrector's DELETE scoping per-type so neither deletes the
+  other's rows. (See the JE-within-Sales architecture under *How it works*.) General lesson: when two
+  transaction families share one table, an audit read with no type scope manufactures phantom FC-only
+  deltas for the other family.
 - **An NS-DELETED invoice leaves STALE cost-only `Forecast.Sales` rows the add/update-only import can
   never remove.** The 5-min `import_sales.php` cron is **add/update-only — it has no delete path** (only
   the nightly discrepancy-fix deletes). So when an invoice is **deleted in NetSuite**, its already-imported
@@ -420,6 +473,24 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-06-30 — **Folded JOURNAL ENTRIES into the SALES reconciliation in `fixer.php` + `checker.php`
+  (TRUE-79862).** Architecture decision (dfranks): a JE is **not its own category** — JE rows live in the
+  same `Forecast.Sales` table (`netsuiteTransactionType='journalEntry'`) as the four sale types, so the
+  sales pass reconciles the **whole table**. `fixer.findSalesDiscrepancies` merges the NS sale-type
+  aggregate with `journalEntryNsTotals()`, reads ALL FC Sales rows, tags each diff `kind` (`sale`|`je`),
+  and routes the FIX (`fixSales`/`fixJournalEntries`) with per-type DELETE scoping. `checker`'s sales
+  `nsSub` becomes a `UNION ALL` (sale-types + JE) over all FC Sales rows — no JE-specific logic since its
+  fingerprint is per-id/item-agnostic. **Gotcha recorded: cross-type contamination** — the initial
+  un-typed FC Sales read deleted 74 JE rows (8 JEs) as "stale sales"; fixed by reconciling the families
+  together + routing by kind, not by filtering JEs out. **JE math/scope** (mirrors
+  `buildJournalEntryRows`): allowlist accts 41100/41300/41500 rev + 51100/51200 cost; group by
+  (salesRep,item) with `ksort(json_encode([salesRep,item]))` synthetic lineNumber — fixer keys identically
+  to the importer or it dupes; cent-precision foreignamounts make sum-then-round == importer round-then-sum
+  (compute-identically holds for JEs). Of ~1235 JEs (2025→present) only ~295 hit a rev/cost acct, ~34 net
+  to $0 and import nothing; bank/equity/tax/AP-only JEs excluded by design (not misses). Accrual + NS
+  auto-reversal reconcile independently per internalId. **Item dimension is null today** (`JE_LINE_ITEM_FIELD`
+  null; native `tl.item` not read); enabling it needs the importer field set AND fixer SELECT/resolve/group-
+  by-(salesRep,item) — checker needs no change. (dfranks)
 - 2026-06-29 — **Recorded that `fixer.php`'s OOI path lacks `locationId`/`quantityBackordered`/
   `amountDue`** (planning for TRUE-79162). The Sales path already handles anchor-line `amountDue`
   behind a `forecastColumnExists('Sales','amountDue')` guard; the OpenOrderItems path (lookup SELECT,

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

@@ -9,3 +9,4 @@
 | [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/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/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.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/surface/useFetchSurfaceMeta.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, 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/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 |
+| [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 |

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -141,7 +141,22 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   configs must use a `scope` discriminator in the query key or they overwrite each other's cache
   (record modal vs. approval modal: the approval modal omitting item-image fields blanked the
   record modal's images until scoping isolated the entries).
+- **`poNumber` does NOT go through the approval modal.** `SalesOrderView` routes
+  `activeModal === "poNumber"` to a **separate** `EnterPoNumberModal` and explicitly excludes it
+  from `SalesOrderApprovalModalsLayout` (`activeModal !== "poNumber"`). The approval-modal
+  `modalSelected` union still lists `"poNumber"`, but that path is handled by the PO modal, not
+  the approval flow — don't add PO-number handling to the approval layout.
+- **Approval submit payload: workflow vs single decision differ.** A single approve/deny posts a
+  **boolean** `isApproved` (`true`/`false`). The workflow path
+  (`handleFormatApprovalWorkflowPayload`) posts a **string** `"1"`/`"0"`, emits a request **only**
+  for stages whose `note` / `assignedTo` / `decision` actually changed, and chooses verb by
+  `stage.ApprovalDecisions.uuid` — `null` → POST `/approval-decisions`, otherwise PUT
+  `/approval-decisions/{uuid}`.
 
 ## Change history
+- 2026-06-30 — Recorded two behaviors confirmed while building approval-modal tests: `poNumber`
+  is handled by a separate `EnterPoNumberModal` (excluded from the approval layout), and the
+  workflow vs single-decision submit payloads differ (string `"1"`/`"0"` + changed-stages-only +
+  POST/PUT by decision uuid, vs boolean `isApproved`). (apeterson)
 - 2026-06-23 — Documented from CLAUDE.md Modal Patterns 1–5 + the `create-record-modal` skill during
   initial knowledge seed. (apeterson)

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

@@ -0,0 +1,143 @@
+---
+title: Cypress Testing Harness (component + e2e)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-06-30
+owners: [apeterson]
+files:
+  - 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
+related:
+  - ../features/record-modals-and-nested-tables.md
+  - ../features/action-button-rule-engine.md
+  - ../architecture.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`.
+
+## 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.
+
+## 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)

package/knowledge/INDEX.md

@@ -28,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 7 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 7 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 8 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework

package/package.json

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