toga-ai 1.0.765 → 1.0.767

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [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, worker/crons/infrastructure/execute_dbchanges.php, worker/.ebextensions/030_dbchanges.config |
+| [Canon received-PO → NetSuite sales order sync](features/canon-received-po-netsuite-order-sync.md) | A 1.0 `worker` cron that reads Canon customer purchase orders out of the **Vision** databases and creates the matching **sales order in NetSuite**. | worker/crons/sync/sync_received_po.php, library/netsuitetoolkit/NSPHPClient.php |
 | [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, worker/schedules/cron.worker.sync.json |
 | [Compass Manager Approval Reminder Emails (1.0 worker crons)](features/compass-manager-approval-reminder-emails.md) | Two 1.0 worker crons nag approvers about sales orders still waiting on a decision — one per Compass tenant. | worker/crons/toga2/compass/compass_email_reminders.php, worker/crons/toga2/compasscanada/compass_email_reminders.php, worker/schedules/cron.worker.sync.json, worker1.5/crons/toga2/compass/compass_email_reminders.php, worker1.5/schedules/cron.worker.json |
 | [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/compass/send_delivered_email.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php |

package/knowledge/1.0/apps/worker/features/canon-received-po-netsuite-order-sync.md

@@ -0,0 +1,112 @@
+---
+title: Canon received-PO → NetSuite sales order sync
+framework: "1.0"
+repo: worker
+project: Worker
+client: canon
+type: feature
+status: active
+updated: 2026-09-03
+owners: ["mhammontree"]
+files:
+  - worker/crons/sync/sync_received_po.php
+  - library/netsuitetoolkit/NSPHPClient.php
+related:
+  - ./netsuite-togasupply-per-client-sync.md
+  - ../../../clients/canon/profile.md
+---
+
+## Summary
+A 1.0 `worker` cron that reads Canon customer purchase orders out of the **Vision** databases and
+creates the matching **sales order in NetSuite**. Before it can create the order it must turn every
+Vision part number into a real NetSuite item — bundles are exploded into components and prefixes are
+stripped. If any line cannot be matched, no order is created and operations gets a "not every part
+number could be located" email.
+
+**Critical rule:** the prefix strip list (`ASI-`, `/4YR`, `TOGA-`) appears **twice** in the file —
+line ~54 and line ~233. A new SKU prefix must be added to **both** or the sync silently searches
+NetSuite for the bundle name itself and fails.
+
+## Key files / entry points
+- `worker/crons/sync/sync_received_po.php` — the whole sync (selection, bundle explode, NetSuite
+  item lookup, order create, all three emails).
+- `library/netsuitetoolkit/NSPHPClient.php` line 200 — sets `SOAP_SINGLE_ELEMENT_ARRAYS`.
+
+## How it works
+1. **Selection.** Picks up rows from `Vision.CustomerPurchaseOrders` joined to
+   `CustomerPurchaseOrderItems` on `customerPurchaseOrderId`, where
+   `companyId = 13785 AND amiExportEnabled = 1 AND exportedToAmi = 0 AND IFNULL(netsuiteOrderNumber,'') LIKE ''`.
+2. **Bundle explode.** Custom-catalog bundles are expanded into their component part numbers
+   **before** any NetSuite search, using `Vision_Catalog.CustomProducts` joined through
+   `CustomCatalogCache` → `Products` for Canon companies **13785 / 18610**.
+3. **Prefix normalization.** Both the explode map (line ~54) and the per-line lookup (line ~233) run
+   `trim(str_replace(['ASI-', '/4YR', 'TOGA-'], '', $partNumber))`.
+4. **NetSuite item lookup** (~line 250) walks the search results and deliberately **skips
+   `ItemGroup` records**: `if (get_class($record) != 'ItemGroup') { $internalId = $record->internalId; break; }`.
+   If nothing is left, `$allItemsLocated` goes false and the failure email fires.
+5. **Quantity.** `billTo` selects the NetSuite customer and whether `$enforceQuantityOne` is set:
+   - `HPFS-LEASES` → 2839 — `enforceQuantityOne = true`
+   - `ACH-ASILEASE` → 28537 — `enforceQuantityOne = true`
+   - `ACH-HP-ACCESSOR` → 21908 if the order number starts with `9`, else 21055 — `false`
+   With `enforceQuantityOne = true` an exploded **bundle** line is written at quantity 1.
+6. **Price.** The exploded bundle's main line is priced from
+   `IFNULL(CustomProducts.listPrice, PriceProfilePartRules.rate)` — the Vision catalog price is
+   taken as-is; the sync does **not** compute cost + margin.
+7. **Email.** Three distinct bodies: SUCCESSFUL, a generic FAILED, and the "not every part number
+   could be located" FAILED that lists `$partNumbersCouldNotFind`. **Only the third names part
+   numbers** — that is the tell for a lookup miss vs. a NetSuite write failure. Recipients are
+   hardcoded near the top (`$emailOrdersTo` mfrye, cmullen; CC jblevins, sking).
+
+## Data model
+- `Vision.CustomerPurchaseOrders`, `Vision.CustomerPurchaseOrderItems` (schema `Vision`,
+  environment `legacy`).
+- `Vision_Catalog.CustomProducts`, `CustomCatalogCache`, `Products`, `PriceProfilePartRules`.
+- Canon's catalog is 21 parts: 19 plain, 1 `ASI-` prefixed, and exactly one `TOGA-` prefixed
+  (`TOGA-MGEE4LL/A`) — the only entry with both `assetTagging` and `biosTagging` set.
+
+## Client variations
+Canon-only cron (`companyId 13785`, catalog companies 13785 / 18610). No other client runs it.
+
+## Gotchas / known issues
+- **A missing prefix makes the bundle name look like a part number.** `TOGA-MGEE4LL/A` was searched
+  literally; in NetSuite that name is an **Item Group** (internal id 1609121) whose components are
+  `MGEE4LL/A`, `SVC-TS-BIOSTAG`, `SVC-TS-ASSETTAG`. Because the lookup skips `ItemGroup`, the search
+  "found" the item and still returned nothing usable. The real item is `MGEE4LL/A`
+  (Serialized Inventory Item, internal id 1607214). Add any new prefix to **both** `str_replace`
+  arrays.
+- **Quantity 12 on a lease PO means 12 monthly payments for ONE machine, not 12 machines.** Verified
+  against the manually keyed records for PO 9318575 (PO 169288 TD Synnex, SO 285071) — both show
+  `MGEE4LL/A` qty 1. Do **not** "fix" `$enforceQuantityOne` to pass the PO quantity through.
+  **Non-bundle** parts are not exploded and therefore DO keep the PO quantity (e.g. older
+  `ASI-MW1H3LL/A` orders imported at qty 12).
+- **Catalog price can be stale, and that is accepted.** `TOGA-MGEE4LL/A` `listPrice` is $5,118.45;
+  the manually keyed SO 285071 used $5,106.45 (TD Synnex cost $4,749.00 + 7% margin = $357.45 GP).
+  Decision 2026-09-03: ship as-is — the sync should not compute margin; a reviewer adjusts the
+  auto-created order.
+- **⚠ OPEN LATENT BUG (not fixed, needs its own ticket).** In the per-line NetSuite lookup, if
+  `$response->searchResult->status->isSuccess` is FALSE the code does **nothing** — the line is
+  silently skipped, `$allItemsLocated` stays TRUE, and the sales order is created in NetSuite
+  **missing that line**, with no email and no error. A NetSuite search outage or throttled call
+  produces a silently short order. This violates the fail-loud rule in `1.0/standards/backend-php.md`
+  via an implicit no-op rather than an explicit catch.
+- **A fixed PO does not re-run.** Rows are flagged `exportedToAmi = 1` even when the export failed,
+  so deploying a fix does **not** replay them. POs 9318538, 9318575 and 9318670 (all
+  `TOGA-MGEE4LL/A`, qty 12, `netsuiteOrderNumber` NULL) were already flagged and need manual entry
+  or a flag reset. 9318575 is in NetSuite as SO 285071, keyed manually.
+- **Ruled out — do not re-investigate.** (a) The single-result SOAP array trap does not apply: the
+  lookup is guarded by `is_array($response->searchResult->recordList->record)`, and
+  `library/netsuitetoolkit/NSPHPClient.php` line 200 sets `SOAP_SINGLE_ELEMENT_ARRAYS`, so a
+  one-record search is still an array. (b) Commit `a3e33776c` (TRUE-75559, 2026-03-17) did not
+  introduce the skip-ItemGroup behavior — it only deleted a commented-out block; the older
+  commented version actually *preferred* the ItemGroup, so the flip happened years earlier under a
+  different file path.
+
+## Change history
+- 2026-09-03 — Added `TOGA-` to the prefix strip list at both line 54 and line 233 so Canon's new
+  bundle SKU `TOGA-MGEE4LL/A` resolves to `MGEE4LL/A` instead of the NetSuite Item Group; documented
+  the qty-1 lease rule, the accept-catalog-price decision, and the silent `isSuccess=false` skip
+  (TRUE-80811, mhammontree).
+
+## Related docs
+- [NetSuite → TOGa Supply per-client sync](./netsuite-togasupply-per-client-sync.md)
+- [Canon profile](../../../clients/canon/profile.md)

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

@@ -10,5 +10,5 @@
 | [Framework branch running AHEAD of schema — environment-wide 1054/EO-1 after a deploy](workflows/framework-branch-ahead-of-schema.md) | A **third** kind of 2.0 schema drift, distinct from the two already documented: nobody's database went backwards — **the code went forwards**. | _underscore/Model/Core/RecordField.php, _underscore/Model/Client/TableViewField.php, _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/Urgency.php, _underscore/Model/Client/RecordFieldSetting.php, _underscore/Model/Client/ClientRecordFieldSetting.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, dbchanges2/Client/2026-08-13a - UserNavPreferencesClientTable.sql, dbchanges2/Client/2026-08-13c - PersonaNavVisibilityClientTable.sql |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Aig/_modules.txt, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |
-| [Targeting the right database (tenant restores, and running a change file against the wrong DB)](workflows/targeting-the-right-database.md) | Two ways to point at the wrong database — a dump taken from the wrong host, and a change file piped into the wrong schema. | api2/Config/production.ini, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql |
+| [Targeting the right database (tenant restores, and running a change file against the wrong DB)](workflows/targeting-the-right-database.md) | Two ways to point at the wrong database — a dump taken from the wrong host, and a change file piped into the wrong schema. | api2/Config/production.ini, api2/Config/sandbox-client.ini, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql |
 | [Verifying whether a dbchanges2 migration actually ran in an environment](workflows/verifying-a-migration-ran.md) | dbchanges2 has no execution ledger you can query — "did this file run here?" has to be answered from the **rows the file would have produced**. | Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql |

package/knowledge/2.0/apps/dbchanges2/workflows/targeting-the-right-database.md

@@ -6,10 +6,11 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - api2/Config/production.ini
+  - api2/Config/sandbox-client.ini
   - dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql
 related:
   - ../architecture.md
@@ -39,6 +40,30 @@ Connection **locations** only — passwords live in the config file, never here.
 
 Username is `admin`. **The password is in the matching section of
 `api2/Config/production.ini` — read it from there; never paste it anywhere, including here.**
+The sandbox-client host's password lives in `api2/Config/sandbox-client.ini` `[database]`; DNS
+resolves `client.sandbox.database.togahub.com` to the **writer**, so `DROP`/`CREATE` work against
+that same hostname.
+
+🚨 **The password values in these ini files are WRAPPED IN DOUBLE QUOTES.** An extractor that only
+strips `password[ \t]*=[ \t]*` keeps the quotes and you get
+`ERROR 1045 (28000): Access denied for user 'admin'@'<ip>' (using password: YES)`. The password *is*
+being sent — just with literal `"` around it — so it reads like a permissions or VPN problem and is
+not one. **Strip the quotes.** Also compare the whole section header (`$0 == "[" S "]"`), or
+`[database]` matches `[databaseClient]` / `[databaseLogs]` and you extract the wrong password:
+
+```bash
+# zsh/bash: export the password for one section of one ini, quotes stripped
+setpw() {
+  local pw
+  pw=$(awk -v S="$2" '$0=="["S"]"{f=1;next} /^\[/{f=0} f && /^password/{
+         sub(/^password[ \t]*=[ \t]*/,""); gsub(/[ \t\r]+$/,""); print; exit}' "$1")
+  pw=${pw%\"}; pw=${pw#\"}
+  export MYSQL_PWD="$pw"
+}
+```
+
+`MYSQL_PWD` keeps the password out of `ps` and history the same way a defaults file does — use it
+when the client rejects `--defaults-extra-file` (some builds do).
 
 **Keep the password out of your shell history and out of `ps`** by building a throwaway
 credentials file from the ini instead of passing `-p` on the command line:
@@ -66,6 +91,40 @@ Delete the file when you are done.
 4. **Verify the restored copy against the SOURCE you intended**, repeating step 1 against the
    restored schema.
 
+## Resetting a shared environment from production (dump → drop → reload)
+
+Used 2026-09-03 to bring sandbox-client's stale `Client_Nychh` TableViews back in line with prod.
+The developer runs every one of these; do not execute them for them.
+
+1. **Dump each source database**, one file each — prod `Core` from
+   `reader1.core.database.togahub.com`, prod tenant from `reader1.client.database.togahub.com`:
+   ```
+   mysqldump --single-transaction --quick --routines --triggers --events \
+             --set-gtid-purged=OFF --no-tablespaces <DB> > <DB>.sql
+   ```
+   `--set-gtid-purged=OFF` because RDS has GTID on; `--no-tablespaces` because the `admin` user
+   lacks `PROCESS` (otherwise **error 1227**).
+2. 🚨 **`tail -1` every dump file and confirm it ends with `-- Dump completed` BEFORE you drop
+   anything.** A truncated dump loads without complaining. DNS dropped mid-session on a host that
+   had resolved seconds earlier (`ERROR 2005 Unknown MySQL server host`) — the dump just stops.
+3. **Prove which environment each connection actually reached.** Better than `@@hostname`: check the
+   resolved IP — production resolves into **`10.201.x`**, sandbox into **`10.200.x`**.
+4. **Drop + create the target schema, then pipe the dump in.**
+5. **Verify with a row count known to differ** (step 1 of the procedure above), against the schema
+   you intended to copy.
+
+### ⚠ Which `mysql` / `mysqldump` binary you are running is load-bearing
+
+- **A MariaDB-branded `mysqldump` rejects `--set-gtid-purged=OFF`.** Both TOGA clusters are **MySQL
+  8.0.42**, so use a **MySQL 8.0** client. On an XAMPP machine both ship and neither is on `PATH`:
+  `xamppfiles/bin/mysqldump` is **MariaDB 10.4** (rejects the flag);
+  `xamppfiles/mysql/bin/mysqldump` is **MySQL 8.0.44** (correct). Run `mysqldump --version` before
+  you trust it.
+- **A shell alias can hijack a remote connection.** XAMPP's `mysql` alias hardcodes
+  `-uroot -pmysql --socket=…`, so a command you wrote for a remote host silently talks to localhost.
+  Call the client by **full path** for anything remote — and remember an exact match with your local
+  DB is evidence of a bad restore, not a good one (see the gotcha below).
+
 ## Gotchas
 
 - 🚨 **A wrong-source restore is silent and total.** A dump taken from `127.0.0.1`, believed to be
@@ -98,6 +157,17 @@ Delete the file when you are done.
   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
 
 ## Change history
+- 2026-09-03 — Added the **reset-a-shared-environment-from-production** procedure (the `mysqldump`
+  flag set, `--set-gtid-purged=OFF` for RDS GTID, `--no-tablespaces` for the missing `PROCESS`
+  grant, the mandatory `tail -1` "`-- Dump completed`" check because a truncated dump loads
+  silently, and the resolved-IP environment check: prod `10.201.x` vs sandbox `10.200.x`). Recorded
+  two traps that both masquerade as something else: **the ini password values are wrapped in double
+  quotes**, so a naive extractor produces `ERROR 1045 Access denied` that looks like a permissions
+  or VPN problem (fixed extractor + `MYSQL_PWD` for clients that reject `--defaults-extra-file`);
+  and **which client binary you run matters** — a MariaDB `mysqldump` rejects
+  `--set-gtid-purged=OFF`, and a shell alias hardcoding `-uroot --socket=…` hijacks a remote
+  connection to localhost. Captured while resetting sandbox-client (`Core` +
+  `Client_Nychh`) from prod after its `purchase-orders` TableView was found stale. (apeterson)
 - 2026-09-01 — Added the **backup-database hazard for `Client/` fan-outs**: the production client
   cluster hosts dated snapshots alongside live tenants (`Client_Compass_20260831_120000`, found
   during a 36-database ACL survey), and a naive "every `Client_*` schema" loop will run against

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

@@ -9,12 +9,12 @@
 | [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/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 |
+| [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 |
 | [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/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 |
+| [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 |
 | [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/features/record-modals-and-nested-tables.md

@@ -24,6 +24,7 @@ files:
   - 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
@@ -166,6 +167,37 @@ interactions so both are reachable on one nested row (Inventory `items-for-purch
   projection: a **hidden (`isVisible=0`) `Items.uuid` column** is added to the table view — see
   [tableview-field-metadata](../../api2/features/tableview-field-metadata.md).
 
+### Deep-linking from a modal INTO a nested table (close, then navigate — never both)
+
+A value inside one record modal can link to a filtered, pre-expanded row on another page's
+`GenericNestedTables` grid. Reference: the Transfer Order modal's Purchase Order value →
+Inventory (`src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts`).
+
+The URL is built from three `useServerTableUrlState` params, and each one has a rule:
+
+| Param | Shape | Rule |
+|---|---|---|
+| grouping | `grouping=<elementKey>` | **Pin it.** The default is whichever grouping the client's surface returns first, so a reseed can silently aim the link at a view without the level you want. An unknown key falls back to the default anyway. |
+| column filter | `<slug>_<columnId>_filter=<mode>:<value>` | Set it through `URLSearchParams.set` with the value `mode + ":" + encodeURIComponent(value)` — the same serializer `useServerTableUrlState` uses. Hand-writing the query string double-encodes, or breaks a value containing `:` / `,`. `<columnId>` is the **table-meta column id**, not the record field name. |
+| active row | `<slug>=<uuid>` | Named **exactly** the table slug (`activeRowUuid = searchParams.get(slug)`). On an `"expand"` level this **opens the child sub-table inline on load** — the same effect as a row click. Omit it when the uuid is unknown; the filter alone still lands on the row, collapsed. |
+
+**Sequencing: hold the target in a `useRef`, fire it from `onClosed`, and RETURN instead of calling
+`onClose()`.** Never `setTimeout` to match the slide-down: a timer either cuts the animation short or
+fires after the user opened something else.
+
+```tsx
+const pendingNavigation = useRef<string | null>(null);
+
+<TableRecordModal
+  onClosed={() => {
+    const target = pendingNavigation.current;
+    pendingNavigation.current = null;
+    if (target) { navigate(target); return; }   // NOT onClose() first
+    onClose();
+  }}
+/>
+```
+
 ## Pattern 6 — Create/edit record modal (form-driven)
 
 Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLayout/`). Form-driven
@@ -205,6 +237,19 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   **suffix** can't be used because `useServerTableUrlState`'s columnFilters parser treats any
   `${slug}_*` key as a column filter — hence a prefix.
 - **`additionalData` in the query key is mandatory** for WHERE-filtered modal tables (Pattern 4).
+- 🚨 **Never call `onClose()` and then `navigate()` — it races two navigations and strips your
+  params.** `onClose` is `handleModalClose` in `src/hooks/useServerTableUrlState.ts`, which clears
+  the URL with `setSearchParams`. That queues a **second** navigation in the same tick as yours, both
+  racing to own the URL; the loser silently drops the grouping / filter / active-row params, so a
+  deep link lands on the page with its sub-table collapsed (or unfiltered). Navigating away replaces
+  the whole query string anyway, so clearing it first is pointless as well as risky. **Navigate and
+  return.**
+- **A bordered scroll box inside a modal must be `flex: 0 1 auto`, not `flex: 1`.** The element that
+  carries the border is the table the user sees: `flex: 1` stretches it to the bottom of the modal,
+  so a single row renders inside a box of empty white. Put `flex: 1` on the wrapper that draws
+  nothing, and keep `min-height: 0` + `overflow: auto` on the bordered box so it still shrinks and
+  scrolls when the rows outgrow the space. Hit on the Transfer Order modal's items table; the design
+  agrees (its items table passes no `fillerHeight`, so it reserves no rows it does not have).
 - **Per-consumer cache `scope`** — two consumers fetching the same record with different field
   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
@@ -286,6 +331,14 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   [Transfer Orders page](transfer-orders-page.md).
 
 ## Change history
+- 2026-09-03 — Added the **deep-link-from-a-modal-into-a-nested-table** pattern (pin `grouping`;
+  build the column-filter chip with the `useServerTableUrlState` serializer, keyed by the table-meta
+  **column id**; set `<slug>=<uuid>` to pre-expand the row) and the rule that makes it work:
+  **hold the target in a `useRef`, fire it from `onClosed`, and `return` — never `onClose()` then
+  `navigate()`**, because `onClose` clears the URL with `setSearchParams` and the two navigations
+  race, stripping the link's params. Also recorded the modal scroll-box flex rule (`flex: 0 1 auto`
+  on the bordered box, `flex: 1` on the wrapper). Found wiring the Transfer Order modal's Purchase
+  Order value to Inventory. (apeterson)
 - 2026-09-03 — Documented that the FE **appends `.uuid`** to a `GenericNestedTables` swap level's
   `additionalDataSlug`, so the stored `Core.SurfaceElements.config` value must be the **bare table
   name** (`PurchaseOrders`), not `<Table>.uuid` — a `.uuid` in the stored value produces a doubled

package/knowledge/2.0/apps/toga25-supply/features/transfer-orders-page.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-02
+updated: 2026-09-03
 owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
@@ -29,6 +29,8 @@ files:
   - 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
@@ -261,6 +263,79 @@ fields. One FK hop out from the order they need `calcDepth 2`; at the default of
 the loaded state swaps element types at the same tree position and replays the slide-up animation —
 see the gotcha in [record-modals-and-nested-tables](./record-modals-and-nested-tables.md).
 
+### The items table HUGS its rows — `flex: 0 1 auto`, not `flex: 1`
+
+`TransferOrder.module.css`. **`.tableScroll` is the box that carries the border, so it is the table
+the user sees — it must size to its rows.** Under `flex: 1` it stretched to the bottom of the modal,
+so a one-line transfer drew a bordered box with ~400px of empty white under its single row.
+
+- `.tableScroll` → **`flex: 0 1 auto`**: sizes to content, and still **shrinks** (paired with the
+  existing `min-height: 0`) when the rows outgrow the space, at which point `overflow: auto` scrolls
+  under the sticky header.
+- `.tableRegion` keeps **`flex: 1`** and absorbs the slack. It draws nothing, so stretching it is
+  invisible.
+- Everything above the table (`.reviewCards`, `.sectionHead`, `.itemsHeadFlush`) already carries
+  `flex-shrink: 0`, so the table shrinking never squashes them.
+
+**Ground truth:** the design's `TransferItemsTable` (`demo/transfer-modal.jsx:598`) passes **no
+`fillerHeight`** to `SupplyTable` — it reserves no rows it does not have. Only `CmFulTable` reserves,
+and it asks for it explicitly. The Create modal's picker (`TransferItemPickerTable.tsx`) hugs the
+same way.
+
+### The Purchase Order value deep-links into Inventory, scoped to that PO
+
+`helpers/buildInventoryPurchaseOrderUrl.ts` (new) + `TransferOrderRecordModalLayout.tsx`.
+`onOpenPurchaseOrder` had been **declared** on `TransferOrderRecordView` and threaded to
+`TransferReviewBody`'s `purchaseOrder.onOpen` since the modal was built, but nothing ever passed it —
+so the PO always rendered as plain text. It now navigates:
+
+```
+/inventory?grouping=posByItems&purchase-orders_customerPurchaseOrder_filter=includes%3A<number>&purchase-orders=<uuid>
+```
+
+Three params, all addressing Inventory grouping `posByItems` level 0 (`fetchSlug: purchase-orders`):
+
+- **`grouping=posByItems` is PINNED, not left to the default.** It *is* the default today
+  (`groupingOptions[0]` in `useInventoryPageViewModel`), but that default is whichever grouping the
+  client's surface returns first — a reseed that reorders them would silently aim the link at a view
+  with no `purchase-orders` level. An unknown key falls back to the default, so pinning can only help.
+- **The filter chip is set through `URLSearchParams.set`, with the value
+  `"includes:" + encodeURIComponent(number)`** — mirroring the serializer in `hooks/useServerTableUrlState.ts` exactly. Hand-writing the query string
+  double-encodes, or breaks a value containing `:` or `,`. The key's middle segment is the **column
+  id from the table meta** (`customerPurchaseOrder`), not the record field name — renaming that
+  `TableViewFields` column breaks the link with nothing to warn you.
+- **`purchase-orders=<uuid>` is the active-row param**, named **exactly** the table slug
+  (`activeRowUuid = searchParams.get(slug)`). That level's `rowInteraction` is the default `"expand"`,
+  so setting it **opens the child sub-table inline on page load** — the same thing a row click does.
+  Omitted when the uuid is unknown; the filter alone still lands on the row, just collapsed.
+
+The uuid is read off the record (`transferOrder.purchaseOrder.uuid`, already in the record fetch — no
+API change), **not** off the surface: the surface says *which number to show*; the route it navigates
+to is FE wiring (the config/logic boundary, [frontend standard](../../../standards/frontend.md) §20).
+
+> ⚠ **Never `onClose()` before `navigate()`.** See the gotcha below — it races two navigations and
+> silently strips the params the link is made of.
+
+### Blank Item column in the RECORD modal too — `COLUMN_FALLBACK_KEYS`
+
+Same NYCHH data gap as the picker, different table. Confirmed on client-sandbox: `transfer-order-items`
+line 1 returns `"title": null` with a real `partNumber`. `item.description` was added to
+`TRANSFER_ORDER_ITEM_FIELDS` (`hooks/useTransferOrderRecord.ts`), and `TransferOrderRecordView` gained:
+
+```ts
+const COLUMN_FALLBACK_KEYS: Record<string, string[]> = { item: ["item.description"] };
+```
+
+tried in order when a column's own surface `valueKey` resolves empty.
+
+- **Deliberately a FLAT MAP keyed by `config.columnKey`** — *not* string surgery on the valueKey.
+  Deriving `item.description` by swapping the tail of `item.title` breaks silently the day a tenant
+  repoints that column.
+- Same chain the Create modal's picker already uses, except the record modal keeps its **em-dash**
+  for both-empty rather than `"(untitled item)"`.
+- **No part-number fallback** — Part Number has its own column, so that would duplicate a cell
+  instead of naming the item. The real fix is still populating `Items.title`.
+
 ## The prod-only state this vertical sits on top of — four UNTRACKED layers
 
 Standing the page up locally failed **one layer at a time**, each with a different-looking error,
@@ -570,11 +645,24 @@ column binds the parent order's `purchaseOrder.number` and repeats on every row.
 resolves NULL because their PO links are **upstream** — see
 [NYCHH PO direction](../../../../clients/nychh/features/po-number-upstream-direction.md). It is left
 visible in Core (neutral default; other tenants populate `TransferOrders.purchaseOrderId` normally).
+**The header's PO value is now a link into Inventory** (above); for NYCHH it is the same null, so
+nothing renders there for this tenant yet.
 
 ## Rollout status & open items
 
-- **Run state after sandbox-client was reset from production (2026-08-31).** Nothing has been run on
-  **production**. On **sandbox-client** the three `Client_Nychh` layers are already satisfied — the
+- 🚨 **CORRECTED 2026-09-03 — the Core seeds ARE on production.** The line below said "nothing has
+  been run on production"; that was true on 2026-08-31 and is **stale**. Verified live on
+  `reader1.core.database.togahub.com`: `Core.Surfaces` = 53 rows and
+  `slug LIKE 'transfer-order%' OR 'talos%'` returns **`transfer-orders-list`,
+  `transfer-orders-list-actions`, `transfer-order-record-header`, `transfer-order-details`,
+  `transfer-order-summary`, `transfer-order-items`, `transfer-order-create-items`** and
+  `talos-assistant`. Someone ran them on prod between 2026-08-31 and 2026-09-03. Note
+  **`transfer-order-create-items` is a surface this doc's table never listed.** Prod `Client_Nychh`
+  also carries **12 `SurfaceOverrides`** rows and **1,930 `TransferOrders`** (1,927 on 2026-08-31 —
+  the tenant is live). *A migration's run status in this doc or in `dbchanges2` is never evidence
+  about an environment — read the environment.*
+- **Run state as of 2026-08-31 (superseded for production by the line above).** On **sandbox-client**
+  the three `Client_Nychh` layers are already satisfied — the
   `transfer-orders` TableView (**22**, 4 fields) plus **4 `AclRecordPermissions` and 34
   `AclFieldPermissions`** for records **312/313** — and `TransferOrderItems` already carries
   `dtCreated` / `dtUpdated` / `qtyCommitted`, all pulled back in by the reset from prod's hand-applied
@@ -665,6 +753,14 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
 
 - **⚠ An empty dropdown with no request in the network tab is a numeric `where` value or a
   non-zero `staleTime`** — see the section above. Neither logs anything.
+- **⚠ A bordered scroll box must be `flex: 0 1 auto`, never `flex: 1`.** `flex: 1` on the element
+  that carries the border stretches the *visible* table to the bottom of the modal, so one row draws
+  a box full of white. Put `flex: 1` on the wrapper that draws nothing.
+- **⚠ Closing a modal and navigating in the same tick races two navigations.** `onClose` clears the
+  URL with `setSearchParams`; if you also `navigate()`, the loser strips the params your link is made
+  of. Navigate **and return** — skip `onClose()` entirely.
+- **A deep link's filter key uses the table-meta COLUMN id, not the record field name.** Renaming
+  the `TableViewFields` column breaks the link silently.
 - **A missing `AclRecordPermissions` grant on a joined record deletes a column, not a request.** The
   Status column would have silently vanished; record 351 had no grants at all.
 - **A missing `AclFieldPermissions` grant on the DEFAULT-SORT column is a 500, not a 403.** The
@@ -706,6 +802,22 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
   earlier migration without names, so a name-based lookup on them finds nothing.
 
 ## Change history
+- 2026-09-03 — **CORRECTED the production run state:** the Core transfer-order surfaces (all six
+  record/list surfaces **plus `transfer-order-create-items`**) and `talos-assistant` **are on
+  production** — verified live on `reader1.core.database.togahub.com` (`Surfaces` = 53). The
+  2026-08-31 "nothing has been run on production" line is stale and is now marked so. Record-modal
+  work, all **uncommitted on branch `TRUE-80852`**: (1) the items table now **hugs its rows** —
+  `.tableScroll` moved from `flex: 1` to `flex: 0 1 auto` so a one-line transfer stops drawing ~400px
+  of empty bordered white (ground truth: the design's `TransferItemsTable` passes no `fillerHeight`);
+  (2) the header's **Purchase Order value now deep-links into Inventory**, scoped to that PO —
+  `grouping=posByItems` pinned, a `slug_column_filter=includes:<number>` chip built through the same
+  serializer as `useServerTableUrlState`, and `purchase-orders=<uuid>` (the active-row param, named
+  exactly the slug) to expand the child table on load; (3) **fixed a race in that first pass** —
+  `onClose()` before `navigate()` queues two navigations in one tick and the loser strips the link's
+  params, so the navigation now returns early instead of closing; (4) the record modal's **Item
+  column no longer blanks when `Items.title` is NULL** (NYCHH) — added `item.description` to the
+  fetch and a flat `COLUMN_FALLBACK_KEYS` map keyed by `columnKey`, deliberately not string surgery
+  on the surface `valueKey`. (apeterson)
 - 2026-09-02 — **Finished the Create Transfer Order modal end to end** (front end + framework model +
   Core metadata + client schema) and **closed both required POST changes**: the transfer now writes
   header and every line in **ONE `POST /transfer-orders`** with the lines nested under

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 24 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 32 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 33 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 13 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/clients/canon/profile.md

@@ -8,11 +8,12 @@ project: Worker
 client: canon
 type: profile
 status: active
-updated: 2026-08-29
-owners: ["jcardinal"]
+updated: 2026-09-03
+owners: ["jcardinal", "mhammontree"]
 files: []
 related:
   - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../1.0/apps/worker/features/canon-received-po-netsuite-order-sync.md
 ---
 
 ## Summary
@@ -32,3 +33,7 @@ full mechanics and the diagnosis playbook live in
 ## Integration touchpoints
 
 - **`worker` / `library` (1.0)** — the shared togasupply sync engine + `App_Api_Toga2` bridge.
+- **`worker` (1.0) — received-PO → NetSuite sales orders.** `crons/sync/sync_received_po.php` reads
+  Canon POs from the **Vision** databases (`companyId 13785`, catalog companies 13785 / 18610),
+  explodes custom-catalog bundles into components, and creates the NetSuite sales order. See
+  [Canon received-PO → NetSuite sales order sync](../../1.0/apps/worker/features/canon-received-po-netsuite-order-sync.md).

package/knowledge/clients/nychh/profile.md

@@ -75,13 +75,30 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   seeds a **Developer-role (role 2)** record ACL grant chain (`AclRecordPermissions` →
   `AclLogicGroups` → `AclLogicGroupExpressions`, reusing record 17's `all` expression) and reads
   `AclFieldPermissions` for the displayed fields, resolving `roleId` by role **name**. Written
-  idempotent / uuid-keyed; applied to **prod and client-sandbox**.
+  idempotent / uuid-keyed; applied to **prod**.
+  🚨 **client-sandbox was NOT rebased on 2026-09-03** (an earlier note here claiming it was is
+  **stale**). Verified live: prod `Client_Nychh.TableViews` id **15** `purchase-orders` sits at
+  `recordId` **17** with `apiWhereClause (vendorId:eq:172)`, while sandbox-client still rendered the
+  pre-rebase column set *Purchase Order · Order Date · Order · Est. Total · Ship To* — the rebased
+  view is **number · dateOrder · total** (the rebase drops the sales-order "Order" column and omits
+  Ship To on purpose). **The symptom was a uuid mismatch, not a visibly wrong grid:** the PO row uuid
+  on the sandbox Inventory grid (`9056ea7b-…`) did not match the transfer order's
+  `purchaseOrder.uuid` (`ea8419cd-…`) — same PO number displayed, two different records — so a deep
+  link by uuid expanded the wrong row or none. Fixed by **resetting sandbox-client (Core +
+  `Client_Nychh`) from production** on 2026-09-03; see
+  [targeting the right database](../../2.0/apps/dbchanges2/workflows/targeting-the-right-database.md).
+  🚩 **OPEN, not investigated:** that prod view's `apiWhereClause (vendorId:eq:172)` means a PO from
+  any other vendor **does not appear in the Inventory grid at all**, so a deep link to it lands on an
+  empty list no matter how correct the uuid is.
 - **NYCHH is the ONLY tenant granted the Talos AI assistant (2026-09-02).** Talos is seeded **off
   in Core for every client** and enabled per tenant with 5 `SurfaceOverrides` rows on the
   `talos-assistant` surface; `Client_Nychh/2026-09-02a - TalosAssistantEnable.sql` is the only grant
   file. The grants are **client-wide** (`roleId` NULL), so every NYCHH user including devteam gets
-  it — matching how this tenant already grants navigation. **Applied on LOCAL only; beta and prod
-  are not run**, and the element ids are per-environment. Their Aegra `assistant_id` is
+  it — matching how this tenant already grants navigation. ~~Applied on LOCAL only; beta and prod are
+  not run~~ — **STALE. Corrected 2026-09-03: the `talos-assistant` surface IS on production**
+  (verified live on `reader1.core.database.togahub.com`; `Core.Surfaces` = 53 rows and
+  `talos-assistant` is among them), and prod `Client_Nychh` carries **12 `SurfaceOverrides`** rows.
+  Someone ran it between 2026-08-31 and 2026-09-03. Element ids are still per-environment. Their Aegra `assistant_id` is
   `c7981164-1fe9-5878-b115-85c38dadad43` (`TOGa Supply`), and thread auto-titles are broken
   **server-side** on that assistant. See
   [NYCHH Talos enablement](./features/talos-assistant-enablement.md).
@@ -97,10 +114,12 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   items 1129/1129, VendorItems 2414/2414) so both stay INNER. Seeds Developer-role record grants for
   records 18 and 19 (both had only Base+API) plus Developer read on `PurchaseOrderItems.quantity`
   (field 94); roles resolved by name, uuid-keyed, idempotent. Mechanism:
-  [tableview-joins](../../2.0/apps/_underscore/features/tableview-joins.md). **Applied to prod AND
-  client-sandbox** — both verified rebased 2026-09-03 (view 16 at base recordId 18, no PurchaseOrders
-  join). An earlier note here said this rebase was prod-only / not on client-sandbox; that is **stale**
-  — client-sandbox is also rebased. **OPEN:** the parent `purchase-orders` view filters to vendor 172
+  [tableview-joins](../../2.0/apps/_underscore/features/tableview-joins.md). **Applied to prod** — prod re-verified
+  2026-09-03 on `reader1.client.database.togahub.com` (view 16 at base `recordId` **18**, no
+  `apiWhereClause`). Its client-sandbox state has flipped in the notes more than once; the parent
+  `purchase-orders` view was found **stale** on sandbox-client the same day, which is why
+  sandbox-client was reset from production on 2026-09-03. **Read the environment before trusting
+  either claim.** **OPEN:** the parent `purchase-orders` view filters to vendor 172
   (`apiWhereClause
   (vendorId:eq:172)`); this item view has no `apiWhereClause`, so it lists items for all POs — left
   unfiltered (mirrors prior state), flagged as a decision for the dev. A "3L-2250" error reported
@@ -214,6 +233,11 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   [NYCHH PO Number direction](./features/po-number-upstream-direction.md).
 
 ## Notes
+- **`Items.title` is NULL on most NYCHH rows — `description` is the populated label field.** Confirmed
+  2026-09-03 on client-sandbox (a `transfer-order-items` line returned `"title": null` with a real
+  `partNumber`). Every screen that labels an item for this tenant needs the
+  `title || description` chain — the Transfer Order record modal and the Create modal's item picker
+  both carry it. The real fix is populating `Items.title`.
 - **Role ids in `Client_Nychh` (verified 2026-09-01):** `1 = Base`, `2 = Developer`, `3 = API`.
   Role ids differ per client DB — resolve by **name** in migrations, never hard-code these.
 - **PO Number is upstream-sourced** (`PurchaseOrders_SalesOrders`), which is why the downstream

package/package.json

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