toga-ai 1.0.692 → 1.0.693

package/knowledge/2.0/apps/api2/features/tableview-field-metadata.md

@@ -235,10 +235,41 @@ Applied for Quad: the sales-orders listing now defaults to `dateOrder DESC` (mos
 first) instead of `number DESC` (`dbchanges2/Client_Quad/2026-08-18c -
 SalesOrderListingSortByDateOrderDesc.sql`).
 
+### 🚨 An ACL gap on the DEFAULT-SORT column surfaces as a 500 SQL error, not an authorization message
+
+Found 2026-08-28 on the NYCHH `transfer-orders` view. The two mechanisms are individually sane and
+compose into a MySQL 1054:
+
+1. **`AclFieldPermissions` filters the SELECT column list, and an ungranted field is dropped
+   SILENTLY** — no message, no `EZ-2`. (That is the same silent-drop behaviour as a missing
+   `AclRecordPermissions` grant deleting a *join*.)
+2. **`_Model_Client_TableView::meta()` still emits `table.sort` naming that field's slug.** The sort
+   block (`TableView.php:343`) sits **OUTSIDE** the permitted-field branch, so it does not know the
+   column was just filtered away.
+3. blox's `getDataTableData` then misses on `lookupTableViewFieldsBySlug`, **`console.warn`s — and
+   pushes `"-" + undefined` anyway**, producing `ORDER BY TransferOrders.undefined DESC` →
+   **MySQL 1054**, surfaced as a 500.
+
+So the visible failure is a broken SQL query while the actual defect is one missing field grant, on
+one column, in one tenant. **Any tenant missing a field grant on its view's default-sort column hits
+this** — it is not transfer-order-specific.
+
+Two candidate fixes, neither applied yet (worth a ticket):
+
+- **Backend:** emit `meta.table.sort` only for fields that survived the ACL filter.
+- **Frontend (blox):** skip a sort whose slug does not resolve — it *already* warns; it just pushes
+  the bad value regardless.
+
+Until one lands, treat "table 500s with `ORDER BY <table>.undefined`" as a **field-ACL diagnosis**,
+not a SQL-authoring one.
+
 ## Gotchas / known issues
 
 - **Default-sort updates must JOIN `TableViewFields`, not subquery `TableViews`** — a subquery
   on the same view triggers MySQL error 1093. See *Default sort* above.
+- **`ORDER BY <table>.undefined` (MySQL 1054) means a missing FIELD GRANT, not a bad migration.**
+  The default-sort column was dropped from the projection by `AclFieldPermissions` while
+  `meta.table.sort` kept naming it. See *An ACL gap on the default-sort column* above.
 - **`recordFieldId` is cross-DB** — it indexes `Core.RecordFields`, not anything in the client DB.
   Resolve the id in `Core`, but insert the `TableViewFields` row in the client DB.
 - **Don't assume `Core.RecordFields`/`Core.Records` ids are stable across environments** — look them
@@ -255,6 +286,14 @@ SalesOrderListingSortByDateOrderDesc.sql`).
   *and* that query — and a grep for the property alone under-reports what a missing column breaks.
 
 ## Change history
+- 2026-08-28 — Recorded a **platform bug worth a ticket**: a missing `AclFieldPermissions` grant on a
+  view's **default-sort** column produces a 500 (MySQL 1054), not an authorization message. The ACL
+  filter drops the column from the SELECT silently, `TableView::meta()`'s sort block
+  (`TableView.php:343`) sits outside the permitted-field branch and still emits `table.sort` for it,
+  and blox's `getDataTableData` warns but pushes `"-" + undefined` anyway →
+  `ORDER BY <table>.undefined`. Two candidate fixes noted (emit the sort only for surviving fields;
+  or have blox skip an unresolvable sort slug). Found on the NYCHH `transfer-orders` view.
+  (apeterson)
 - 2026-08-28 — Pinned **where `isGroupable` actually exists**: present on local and sandbox-client
   (both hand-applied), **absent on production and beta**. So a `TableViewFields` INSERT naming the
   column passes locally and fails on prod — omit it from new TableView migrations until the fan-out

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

@@ -3,8 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Re-runnable additive INSERTs (uuid4 in SQL, guards, and the DISTINCT trap)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Client_Compass/2026-08-28 - GrantViewOrdersRoleSalesOrdersNavigation.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql |
+| [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Client_Compass/2026-08-28 - GrantViewOrdersRoleSalesOrdersNavigation.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [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, 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 |

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -1,5 +1,5 @@
 ---
-title: Re-runnable additive INSERTs (uuid4 in SQL, guards, and the DISTINCT trap)
+title: Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)
 framework: "2.0"
 repo: dbchanges2
 project: Database Changes
@@ -163,6 +163,43 @@ open-orders cron that reads the dimension it fills runs at 3:00 AM.
 **Test a registration file twice against a throwaway local copy of the table**: the first run must
 insert exactly one row, the second must insert zero and raise no error. That is the whole contract.
 
+### Re-runnable ALTERs: MySQL 8 has no `ADD COLUMN IF NOT EXISTS`
+
+A `Client/` file runs against **every tenant**, and tenants disagree about which columns they
+already have — so a bare `ALTER TABLE … ADD COLUMN` breaks on the tenants that already have it and
+aborts the rest of the file. MySQL 8 offers no `IF NOT EXISTS` for `ADD COLUMN` (MariaDB does; do
+not copy MariaDB SQL here). Gate each ALTER on `information_schema` and run it through
+`PREPARE`/`EXECUTE`, so it compiles to a harmless `DO 0` where the column already exists:
+
+```sql
+SET @sql = (
+	SELECT IF(
+		COUNT(*) = 0,
+		'ALTER TABLE TransferOrderItems ADD COLUMN dtCreated DATETIME NULL',
+		'DO 0'
+	)
+	FROM information_schema.COLUMNS
+	WHERE
+		TABLE_SCHEMA = DATABASE() AND
+		TABLE_NAME = 'TransferOrderItems' AND
+		COLUMN_NAME = 'dtCreated'
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+```
+
+- **`TABLE_SCHEMA = DATABASE()`** keeps it cluster-safe — the file never names a database, so the
+  same statement is correct in every `Client_*` schema.
+- Guard **indexes** the same way against `information_schema.STATISTICS` (and remember a composite
+  unique key is only recorded against its first column — see
+  [tableview-field-metadata](../../api2/features/tableview-field-metadata.md)).
+- The `PREPARE` shape is what makes the guard work at all: **DDL cannot sit inside an `IF`** in a
+  plain script, so the condition has to select the *statement text*, not branch around it.
+
+Worked example: `Client/2026-08-28b - TransferOrderItemsTimestamps.sql` (adds
+`TransferOrderItems.dtCreated`/`dtUpdated` + indexes, and a guarded `qtyCommitted`). **The existing
+`Client/2026-08-18` `qtyCommitted` file uses a bare `ALTER` and is exactly the shape this avoids** —
+it is not the template to copy.
+
 ### `LAST_INSERT_ID()` into a session variable ties the whole file to one session
 
 The common shape — `INSERT` a parent, `SET @parentId = LAST_INSERT_ID();`, then insert children
@@ -201,6 +238,14 @@ concluding a migration is production-safe.
   [dbchanges2 architecture](../architecture.md).
 
 ## Change history
+- 2026-08-28 — Added **conditional (re-runnable) ALTERs**: MySQL 8 has no
+  `ADD COLUMN IF NOT EXISTS`, so a `Client/` all-tenant file must gate each `ALTER` on
+  `information_schema` (with `TABLE_SCHEMA = DATABASE()` for cluster safety) and run it through
+  `PREPARE`/`EXECUTE`, compiling to `DO 0` where the column already exists — DDL cannot sit inside an
+  `IF`, which is why the condition selects the statement *text*. From
+  `Client/2026-08-28b - TransferOrderItemsTimestamps.sql`; the existing `Client/2026-08-18`
+  `qtyCommitted` file's bare `ALTER` is the anti-pattern it replaces. Retitled the doc, since it now
+  covers re-runnable migrations generally rather than INSERTs only. (apeterson)
 - 2026-08-28 — Added the **local dry-run pattern for destructive/rebuild migrations**: replay the
   file against a local copy inside `START TRANSACTION; … ROLLBACK;`, then prove idempotence by
   concatenating the file to itself and running both copies in one transaction. Used while writing

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -14,6 +14,7 @@ files:
   - dbchanges2/Client_Compass/
   - dbchanges2/Client_CompassCanada/
   - dbchanges2/Client_Quad/
+  - dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql
   - dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql
   - dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql
   - dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql
@@ -181,6 +182,14 @@ it `isVisible: true`. Both `Core/2026-06-29a` (Item) and `Core/2026-06-29d` (Ven
 off." A client opts a role in via a `SurfaceOverride` (`IS_VISIBLE=1`), scoped by role/persona. This is
 the seed-authoring corollary of the Core neutral-default re-baseline recorded in the resolver doc.
 
+**Neutral does NOT automatically mean OFF — test (b), not the habit (2026-08-28).** The rule is
+"universal **and** safe-if-silently-inherited", so a control that passes both seeds **ON**.
+`Core/2026-08-28b` seeds the three `transfer-orders-list-actions` buttons (Refresh / Columns /
+Transfer Order) **`isVisible = 1`**: a list screen with no refresh and no create is not a useful
+neutral default, none of the three is an unsafe affordance to inherit, and only NYCHH can reach the
+page at all. Contrast the record-modal **Edit** button, which fails (b) outright. State which of the
+two tests you applied in the file header.
+
 ## Sales-order button overrides — element identities & the id-agnostic authoring house style
 
 When a client opts its roles into the sales-order action/filter buttons (the resolved per-client
@@ -589,7 +598,11 @@ See [sales-order-status-filter-surface](../../_underscore/features/sales-order-s
 
 Blocks assigned by `Core/2026-08-28a - TransferOrderSurfaceSeed.sql`: **`Core.Messages` 227–250**,
 **`Core.Surfaces` 47–51**, **`Core.SurfaceElements` 170–186** (the `transfer-orders` nav element +
-the LIST surface + 4 record-modal SECTION surfaces + the `transfer-order-stage` vocabulary). See
+the LIST surface + 4 record-modal SECTION surfaces + the `transfer-order-stage` vocabulary), then
+**extended the same day** by `Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql` to
+**`Messages` 227–260**, **`Surfaces` 47–52**, **`SurfaceElements` 170–189** (the
+`transfer-orders-list-actions` BUTTON_BAR + the shared columns-modal messages). Every id was
+verified free on **local AND production** before authoring. See
 [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 
 **⚠ The reserved blocks are not an inventory of every surface id — pre-2026-08-21 surfaces sit
@@ -905,6 +918,41 @@ next reserved block, and a second confirmation of the "verify the block is free
 environment, not just yours" rule from the 2026-08-24 incident — sandbox-client's lower ceiling would
 have made 45–46 look free.
 
+### SHARED (`common.*`) message keys — guard on `messageKey`, not on `id`
+
+Copy that belongs to a **generic component** rather than to one record type is seeded under a
+**shared `common.*` key**, alongside the existing `common.yes` / `common.no` / `common.active` /
+`common.inactive`. `Core/2026-08-28b` moved the seven column-visibility modal strings to
+**`common.columns.modal.*`** for exactly this reason: a tenant then translates them **once for every
+list screen** instead of once per record type. (The older per-record
+`items.columns.modal.*` / `salesOrder.columns.modal.*` keys are left alone — folding those three
+shipped screens onto the common keys is a clean follow-up.)
+
+**The guard changes with the key's ownership.** A record-scoped seed can be guarded on its literal
+reserved `id`; a **shared** key cannot, because another seed may legitimately create it first, at a
+different id. So guard a `common.*` insert with `NOT EXISTS (… WHERE messageKey = '…')` — the
+*semantic* key — and accept that the row may end up outside your reserved block.
+
+### A partial-migration cleanup: fix the ENVIRONMENT, not the migration file
+
+When a developer has already run an **earlier revision** of a seed, re-running the corrected file
+hits `Duplicate entry '251' for key 'messages.PRIMARY'`. The resolution that keeps the repo honest:
+
+- **Leave the migration file UNCHANGED.** It is correct for a fresh environment, and prod/sandbox
+  never ran it. Editing it to dodge one developer's local state corrupts the record of intent (see
+  the 2.0 standard: *migrations record intent, not deployed state*).
+- **Hand over a scratchpad-only undo** — never a committed file, because the executor runs every
+  folder against production.
+- **Delete BY UUID, never by id range.** Per the 2026-08-24 incident, an id-range cleanup nearly
+  took the legitimate deny-action toast rows with it.
+- **Delete in FK order: `SurfaceElements` → `Surfaces` → `Messages`.** Both
+  `SurfaceElements.labelMessageId` and `SurfaceElements.surfaceId` are `RESTRICT`.
+
+> ⚠ **`SurfaceOverrides.surfaceElementId` is a SOFT FK — no constraint.** So an override written
+> against a deleted element **survives the delete** and silently re-attaches to whatever row takes
+> that id next. This is the same failure shape as the NYCHH inventory-topology landmine above:
+> sweep the overrides yourself when you delete elements; the database will not.
+
 ## A new-vertical Core seed: two authoring rules confirmed on the transfer-order build (2026-08-28)
 
 - **A TABLE surface names its view by SLUG, never by `tableViewId`.** `Core/2026-08-28a` seeds
@@ -922,8 +970,28 @@ have made 45–46 look free.
   the same distinction). ⚠ Any `Client/` file writing to `ThemeTokens` inherits a dependency on
   `Client/2026-06-25a - SurfaceClientTables.sql` having run in that schema — audit the tenant list
   before a prod run.
+- **A BUTTON_BAR element needs an `Actions` row only when it needs a REGISTRY HANDLER.** The three
+  `transfer-orders-list-actions` elements seed with **no `Actions` rows at all**: with nothing
+  registered in the FE `actionRegistry`, `SurfaceActionBar` falls through to
+  `onDispatch(config.valueKey)`, which is precisely the host-owned behaviour Refresh / Columns /
+  Create want. Seed an `Action` when the *behaviour* lives in the registry; seed a bare
+  `config.valueKey` when it lives in the page.
 
 ## Change history
+- 2026-08-28 — **Extended the transfer-order reserved blocks** to `Messages` **227–260**, `Surfaces`
+  **47–52**, `SurfaceElements` **170–189** (`Core/2026-08-28b`, the `transfer-orders-list-actions`
+  BUTTON_BAR; all ids verified free on local **and** production first). Three authoring rules added:
+  a **neutral default can be ON** — apply the safe-if-inherited test rather than the seed-OFF habit
+  (the three list-action buttons seed `isVisible=1`; a record-modal Edit button still seeds off);
+  a BUTTON_BAR element needs an **`Actions` row only when it needs a registry handler**, otherwise a
+  bare `config.valueKey` falls through to `onDispatch`; and **shared `common.*` Messages must be
+  guarded on `messageKey`, not id**, since another seed may create the key first at a different id
+  (the columns-modal copy moved to `common.columns.modal.*` so a tenant translates it once for every
+  list screen). Also recorded the **partial-migration cleanup** procedure — leave the migration file
+  unchanged, hand over a scratchpad-only undo, delete **by uuid** in FK order
+  (`SurfaceElements` → `Surfaces` → `Messages`, both element FKs are RESTRICT) — and that
+  **`SurfaceOverrides.surfaceElementId` is a soft FK with no constraint**, so an override outlives a
+  deleted element and silently re-attaches to whatever takes that id next. (apeterson)
 - 2026-08-28 — Registered the **transfer-order reserved blocks** (`Messages` 227–250, `Surfaces`
   47–51, `SurfaceElements` 170–186, `Core/2026-08-28a`) and recorded the read-only ceiling snapshot
   taken before reserving them: local **and** production identical at 46/169/226 while sandbox-client

package/knowledge/2.0/apps/dbchanges2/workflows/client-onboarding.md

@@ -84,6 +84,15 @@ Order matters — each step assumes the prior one ran.
 - **Drift before consolidation** — loose `Client/` files must already be applied to all existing
   clients before they're consolidated/archived (otherwise the new blank diverges from live
   clients). See the dbchanges2 architecture doc.
+- **🚨 The blank can be WRONG, not just behind — an open example (2026-08-28).**
+  `Client/2026-06-03- BLANK_CLIENT_DATABASE.sql` creates `TransferOrderItems` (`CREATE` at ~line
+  9462) **without `dtCreated`/`dtUpdated`**, but `_Model_Client_TransferOrderItem` declares them as
+  `FIELD_DATETIME_CREATED`/`FIELD_DATETIME_UPDATED`, so `_Model` puts them in **every SELECT it
+  builds**. **Every tenant provisioned from this blank therefore has a table the model cannot
+  read** — nothing in a request has to ask for the columns. `Client/2026-08-28b -
+  TransferOrderItemsTimestamps.sql` repairs existing tenants; **the blank itself is still unfixed**,
+  so the next onboarding reproduces it. When a model-vs-blank mismatch like this is found, fix
+  **both**: a catch-up `Client/` file for live tenants *and* the blank.
 
 ## Gotchas
 
@@ -100,6 +109,12 @@ Order matters — each step assumes the prior one ran.
 
 ## Change history
 
+- 2026-08-28 — Recorded an **open blank-template defect**: `TransferOrderItems` is created without
+  the `dtCreated`/`dtUpdated` columns the model declares as `FIELD_DATETIME_CREATED/UPDATED` and
+  therefore selects on every read, so every tenant built from the blank ships a table the model
+  cannot read. Live tenants are repaired by `Client/2026-08-28b`; the blank is still unfixed. Added
+  the general rule: a model-vs-blank mismatch needs **both** a catch-up `Client/` file and a blank
+  fix. (apeterson)
 - 2026-07-20 — Noted that a local browser wizard now automates steps 2–9 and the dbchanges2 blank
   consolidation (TRUE-79864). (mhammontree)
 - 2026-06-23 — Initial capture from the Fordham onboarding (TRUE-79702). (mhammontree)

package/knowledge/2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-11
+updated: 2026-08-28
 owners: ["bala", "mhammontree", "apeterson"]
 files:
   - dbchanges2/Client_Growrk/2026-05-28.sql
@@ -101,6 +101,33 @@ part, and it is what makes a missing column fatal. Standard, non-`c_` fields use
 `Core.RecordFields` + `AclFieldPermissions` instead; see
 [ACL permission chain](../../_underscore/features/acl-permission-chain.md).)
 
+## The drift can run the OTHER way: prod has state the repo never created
+
+Everything above assumes the client DB is **behind** the repo. The mirror case is just as common and
+harder to see: **production carries hand-applied state that no migration file creates**, so the
+*fresh* environment is the broken one.
+
+Worked example (NYCHH transfer orders, 2026-08-28) — four layers, all applied by hand when the
+NetSuite TransferOrder POST was enabled, none of them in `dbchanges2`: `AclRecordPermissions` for
+records 312/313, their `AclLogicGroups`/`AclLogicGroupExpressions`/`AclRecordExpressions` chain,
+`AclFieldPermissions` for all 17 of their `RecordFields`, and the
+`TransferOrderItems.dtCreated`/`dtUpdated` columns. Local had none of it and **failed one layer at a
+time, each with a completely different-looking error**.
+
+Three things this changes about the audit:
+
+- **ACL rows are drift too, not just columns.** An `information_schema` diff will never find a
+  missing `AclFieldPermissions` row. Diff the ACL tables for the records in scope as well.
+- **Diff the WHOLE feature area up front rather than chasing one 500 at a time.** One systematic
+  local-vs-prod diff of every table (and ACL row) the feature touches is cheaper than four
+  sequential debugging sessions, and it is the only way to find layers that have not failed *yet*.
+- **The blast radius is never just the screen you are on.** The same missing rows meant the NetSuite
+  transfer-order **importer** could not be stood up in a fresh environment either.
+
+The repair is a **faithful reproduction** file — same roles, same permission bits as prod, no
+widening — anti-joined on natural keys so it is a no-op where the state already exists. Detail:
+[NYCHH transfer-order inventory & quantities](../../../../clients/nychh/features/transfer-order-inventory-quantities.md).
+
 ## Steps
 
 1. **Get the real exception first.** Resolve `error.id` from the response envelope against
@@ -162,6 +189,15 @@ part, and it is what makes a missing column fatal. Standard, non-`c_` fields use
 
 ## Change history
 
+- 2026-08-28 — Added the **inverse drift direction**: production carrying hand-applied state the repo
+  never created, so the *fresh* environment is the broken one. From the NYCHH transfer-order case —
+  four untracked layers (record ACL for 312/313, their logic-group/expression chain, field ACL for
+  all 17 RecordFields, and two `TransferOrderItems` timestamp columns) that failed locally one at a
+  time with different-looking errors. Durable additions: **ACL rows are drift too** and an
+  `information_schema` diff will never see them; **diff the whole feature area up front** instead of
+  chasing sequential 500s; the blast radius extends past the UI (the NetSuite importer was equally
+  unbuildable); and the repair is a **faithful reproduction** — same roles, same bits, no widening,
+  anti-joined so it no-ops where the state exists. (apeterson)
 - 2026-08-27 — Added a pointer to the **third drift direction**: when the 1054 starts right after a
   deploy, is not client-specific, and the column exists in no environment, the **framework branch is
   ahead of schema** and the repair is a branch merge, not a catch-up file — see

package/knowledge/2.0/apps/toga-blox/INDEX.md

@@ -7,7 +7,7 @@
 | [AdvancedSelect (virtualized single/multi select)](features/advanced-select.md) | `AdvancedSelect<T>` is a **fully controlled, virtualized** single/multi select built from scratch (not react-select) on **`@tanstack/react-virtual`**, for large | toga-blox/src/components/AdvancedSelect/AdvancedSelect.tsx, toga-blox/src/components/AdvancedSelect/AdvancedSelect.types.ts, toga-blox/src/components/AdvancedSelect/AdvancedSelect.module.css |
 | [API client (axios wrapper, auth, table-data fetchers)](features/api-client.md) | `src/api/` is a thin **axios** wrapper that standardizes the **2.0 API envelope**, manages auth (Bearer + refresh), serializes complex query options, and provid | toga-blox/src/reactQuery/queryHelpers.ts, toga-blox/src/api/index.ts, toga-blox/src/api/axiosInstance.ts, toga-blox/src/api/apiFunctions.ts, toga-blox/src/api/auth.ts, toga-blox/src/api/genericApi.ts, toga-blox/src/api/types.ts, toga-blox/src/api/tableData |
 | [BaseInput (react-hook-form field factory)](features/base-input.md) | `BaseInput` is a **form-field factory** driven by react-hook-form. | toga-blox/src/components/BaseInput/BaseInput.tsx, toga-blox/src/components/BaseInput/BaseInput.types.ts, toga-blox/src/components/BaseInput/BaseInput.module.css, toga-blox/src/components/BaseInput/components |
-| [blox authoring defect backlog (fix IN blox, not around it)](features/blox-authoring-defects.md) | The standing list of **defects to fix inside `@agilant/toga-blox`**. | toga-blox/src/api/auth.ts, toga-blox/src/api/axiosInstance.ts, toga-blox/src/reactQuery/queryHelpers.ts, toga-blox/src/components/BaseInput, toga-blox/tsconfig.json, toga-blox/package.json |
+| [blox authoring defect backlog (fix IN blox, not around it)](features/blox-authoring-defects.md) | The standing list of **defects to fix inside `@agilant/toga-blox`**. | toga-blox/src/components/BaseButton, toga-blox/src/api/auth.ts, toga-blox/src/api/axiosInstance.ts, toga-blox/src/reactQuery/queryHelpers.ts, toga-blox/src/components/BaseInput, toga-blox/tsconfig.json, toga-blox/package.json |
 | [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | `src/templates/PrimaryTable/` is the **production, wired-up table** built on the [Table component](table.md). | toga-blox/src/components/Table/themeConfig/toga.module.css, toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx, toga-blox/src/templates/PrimaryTable/types.ts |
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |
@@ -15,4 +15,4 @@
 | [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |
 | [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml |
-| [Local-linking an unpublished blox into a consumer app (incl. a React 19 / Next host)](workflows/local-link-into-a-consumer-app.md) | How to develop a **blox component that is not published yet** against a real consuming app, on Windows, including the hard case: a **React 19 / Next.js (Turbopa | toga-blox/package.json, toga-blox/postcss.config.cjs |
+| [Local-linking an unpublished blox into a consumer app (incl. a React 19 / Next host)](workflows/local-link-into-a-consumer-app.md) | How to develop a **blox component that is not published yet** against a real consuming app, on Windows, including the hard case: a **React 19 / Next.js (Turbopa | toga-blox/package.json, toga-blox/postcss.config.cjs, toga25-supply/vite.config.ts |

package/knowledge/2.0/apps/toga-blox/features/blox-authoring-defects.md

@@ -6,9 +6,10 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
+updated: 2026-08-28
 owners: [apeterson]
 files:
+  - toga-blox/src/components/BaseButton
   - toga-blox/src/api/auth.ts
   - toga-blox/src/api/axiosInstance.ts
   - toga-blox/src/reactQuery/queryHelpers.ts
@@ -89,6 +90,24 @@ mechanism), and a **fix direction** (a suggestion, not a decision). Every one of
   today's `"/"` for compatibility), or have `performLogout` simply not navigate and let the caller's
   `onLogout` own it.
 
+## Styling defects
+
+### 4. `BaseButton` — `primary` and `primaryAction` are NOT interchangeable variants
+
+**Mechanism.** The two class names look like a naming pair but carry different property sets:
+`.primaryBtnAction` sets a **font-size** (default 14px) **and** `height: 26px`; `.primaryBtn` sets
+**neither** — it inherits font-size from context and has no height at all.
+
+**Consumer symptom.** Switching a button between the two variants — the obvious move when a surface
+element is seeded `PRIMARY` — silently changes **type size and button height**, with nothing in the
+prop name suggesting geometry is involved. It reads as a CSS bug in the consuming app.
+
+**Fix direction.** Make the two variants differ in **colour only**, moving the shared size/height
+declarations to the base button class. Until then a consumer must compensate at the instance —
+`toga25-supply`'s `SurfaceActionBar` variant map pins `fontSize: 14px` for `primary` (see
+[surface-frontend](../../toga25-supply/features/surface-frontend.md)). **Do not patch the shared blox
+stylesheet from a consumer**: every one of the ~40 call sites inherits it.
+
 ## Already-known authoring items (carried over from §22)
 
 These are long-standing and were previously recorded only as consumer-side advice:
@@ -122,6 +141,11 @@ These are long-standing and were previously recorded only as consumer-side advic
   time**, with no PR. Sequence auth fixes deliberately.
 
 ## Change history
+- 2026-08-28 — Added styling defect **4: `BaseButton` `primary` vs `primaryAction` are not
+  interchangeable** — `.primaryBtnAction` sets font-size **and** `height: 26px`, `.primaryBtn` sets
+  neither, so swapping variants silently changes type size and button height. Found wiring the
+  `transfer-orders-list-actions` PRIMARY button in toga25-supply; compensated at the instance (the
+  `SurfaceActionBar` variant map pins 14px) rather than by editing the shared stylesheet. (apeterson)
 - 2026-08-27 — Created the doc §22 had been pointing at since 2026-08-18. Seeded with the three auth
   defects found while debugging toga25-supply SSO (`handleClientAuthentication`'s misleading name +
   untyped return, `fetchPublicToken` persisting the public token to `localStorage`,

package/knowledge/2.0/apps/toga-blox/workflows/local-link-into-a-consumer-app.md

@@ -7,10 +7,11 @@ client: shared
 type: workflow
 status: active
 updated: 2026-08-28
-owners: [tcox]
+owners: [tcox, apeterson]
 files:
   - toga-blox/package.json
   - toga-blox/postcss.config.cjs
+  - toga25-supply/vite.config.ts
 related:
   - ./dynamic-publish-pipeline.md
   - ../features/talos-assistant.md
@@ -59,6 +60,35 @@ Result: exactly one React in the graph. **framer-motion 11 and Pro FontAwesome b
 React 19** — the `^18` peer range is a declaration, not a runtime wall (a published consumer
 still needs the peer range widened).
 
+### 2b. Vite consumers: dedupe EVERY peer that carries a React context — not just React
+
+**The rule: any peer dep that provides a React context or hooks must be in `resolve.dedupe` when
+blox is consumed through a symlink.** It is not enough that blox declares the peer correctly — Vite
+resolves a symlinked package's imports **relative to the link target**, so blox's hooks pick up
+whatever sits in `toga-blox-npm/node_modules`, and you end up with two copies of the library.
+
+Worked example (toga25-supply, 2026-08-28) — **"No QueryClient set, use QueryClientProvider" with
+`QueryClientProvider` plainly visible in the component stack.** Two copies of
+`@tanstack/react-query`: the app's provider wrote one React context while blox's hooks
+(`useFetchTablePageMeta`, `useTableData`) read another. `vite.config.ts` deduped
+`react` / `react-dom` / `@tanstack/react-table` but **not react-query**.
+
+```ts
+dedupe: [
+  "react", "react-dom", "@tanstack/react-table",
+  "@tanstack/react-query",                    // ← the fix
+  "@tanstack/react-query-persist-client",
+  "@tanstack/react-query-devtools",
+]
+```
+
+- **Editing `dedupe` is not enough on its own — `rm -rf node_modules/.vite` and hard-reload.** The
+  duplicate is baked into Vite's **pre-bundle**, so the old graph is served until the cache is
+  cleared.
+- **This only reproduces on machines using the local checkout**, so across a team it reads as an
+  *intermittent* bug that "works for everyone else." A `QueryClient`/context error with the provider
+  visibly mounted is almost always this.
+
 ### 3. Disable blox's PostCSS config while linked
 
 Rename `toga-blox-npm/postcss.config.cjs` to `postcss.config.cjs.off` for the duration.
@@ -89,6 +119,13 @@ The consumer reads blox's `dist`, so rebuild blox after every change.
   drags every component's CSS into the consumer bundle.
 
 ## Change history
+- 2026-08-28 — Added the Vite half of the one-copy rule: **every peer carrying a React context must
+  be in `resolve.dedupe`**, not just React. `toga25-supply` threw "No QueryClient set" **with
+  `QueryClientProvider` visibly in the stack** because `@tanstack/react-query` was missing from
+  `dedupe` while `react-table` was there — the app's provider and blox's hooks held different
+  contexts. Fix = add the react-query family to `dedupe` **and** `rm -rf node_modules/.vite` (the
+  duplicate is baked into the pre-bundle). Reproduces only on machines using the local checkout, so
+  it presents as intermittent across a team. (apeterson)
 - 2026-08-27 — Initial doc. Recorded the procedure proven while wiring blox `Talos` into `ai-bdr`
   from an unpublished branch: junction the checkout in, junction the host's React 19 over blox's
   bundled React 18 (keeping `.r18` originals) so there is one React, and rename blox's Tailwind

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

@@ -6,7 +6,7 @@
 | [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` / `join` / `where` to request from the TOGa API for a given page — fr | toga25-supply/src/fieldsConfig/resolveApiConfig.ts, toga25-supply/src/fieldsConfig/useClientApiFields.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx |
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
-| [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/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
+| [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 |
@@ -14,7 +14,7 @@
 | [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/App.tsx, 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 + adapter wiring)](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/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/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/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.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 |
+| [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/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/useTransferableItemRows.ts, 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/column-visibility.md

@@ -6,17 +6,23 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-08-28
 owners: [apeterson]
 files:
   - 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
 related:
   - ../architecture.md
   - client-configurable-fields.md
   - meta-driven-table-data.md
+  - surface-frontend.md
+  - transfer-orders-page.md
+  - ../../dbchanges2/features/surface-layer-schema.md
 ---
 
 ## What it is
@@ -75,11 +81,40 @@ const isFieldVisible = (f) => visibleSlugSet ? visibleSlugSet.has(f.slug) : f.is
 6. **Verify:** `npx tsc --noEmit`, validate each JSON parses, click live (toggle, Apply, copy URL,
    reload → state persists).
 
+## Where the copy comes from — SHARED Core Messages, and NO FE fallbacks (2026-08-28)
+
+Step 5's per-page `FIELDS/<CLIENT>/…` block is the **legacy** source. New screens take the modal's
+copy from the **Surface layer**, under **shared `common.columns.modal.*` `Core.Messages` keys**
+(`Core/2026-08-28b`).
+
+- **Why `common.*` and not per-record.** Every page previously hardcoded the same seven strings,
+  which put the English **in the bundle, where `MessageTranslations` can never reach it**. Shared
+  keys — the pattern already used by `common.yes` / `common.no` / `common.active` /
+  `common.inactive` — mean a tenant translates the modal **once for every list screen** instead of
+  once per record type.
+- **The English fallbacks were removed from the FE deliberately.** A hardcoded default silently
+  masks a missing seed and reintroduces the second source of truth this whole migration exists to
+  delete. **Trade-off accepted and recorded: an unseeded environment renders the raw message key.**
+  (This is a deliberate divergence from the generic surface guidance that every consumer keeps a
+  design-literal fallback — for *this* component the missing seed must be visible.)
+- **`useColumnVisibilityModalConfig`** (`src/surface/`, exported from the `@/surface` barrel) is the
+  reusable reader: given any `BUTTON_BAR` bundle carrying a `config.role = 'columnsButton'` element,
+  it reads that element's `config.modal` and resolves the copy + icon. It lives with the other
+  surface infra and carries the same `TODO(blox)` promotion marker.
+- **Seed guard:** because these are shared keys, the `INSERT` is `NOT EXISTS`-guarded on
+  **`messageKey`**, not on a literal id — another seed may legitimately create them first at a
+  different id. See
+  [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
+- **Follow-up (clean, not done):** the three shipped screens still on
+  `items.columns.modal.*` / `salesOrder.columns.modal.*` can fold onto the common keys + this hook.
+  Those older keys were deliberately left alone.
+
 ## Gotchas
 
 - **No hardcoded copy in the component** — every user-facing string (incl. Close `aria-label`) is a
-  required `labels` prop from client FIELDS; fallbacks live in the view model's resolution, not the
-  component, not default prop values. Only structural glyphs (checkbox tick, close `xmark`) stay.
+  required `labels` prop. On the **legacy** path the fallbacks live in the view model's resolution
+  (never in the component or default props); on the **surface** path there are **no fallbacks at
+  all** (see above). Only structural glyphs (checkbox tick, close `xmark`) stay.
 - **Remount key is REQUIRED.** toga-blox's `PrimaryTableRow` memoizes
   `useMemo(() => row.getVisibleCells(), [row])`; TanStack caches `row` by data, so a columns-only
   change doesn't change `row` → stale cells. Symptom: **toggling off removes the header but leaves the
@@ -95,4 +130,14 @@ const isFieldVisible = (f) => visibleSlugSet ? visibleSlugSet.has(f.slug) : f.is
   meta later won't appear for an old link until Reset (intended).
 
 ## Change history
+- 2026-08-28 — Modal copy moved from per-page hardcoded strings / client `FIELDS` to **shared
+  `common.columns.modal.*` `Core.Messages`** (`Core/2026-08-28b`), so a tenant translates it once for
+  every list screen instead of per record type — the old strings sat in the bundle where
+  `MessageTranslations` could never reach them. **Removed the English FE fallbacks deliberately**: a
+  hardcoded default masks a missing seed and recreates the second source of truth; the accepted
+  trade-off is that an unseeded environment renders the raw key. Added
+  `useColumnVisibilityModalConfig` (`src/surface/`, barrel-exported) as the reusable reader for any
+  `BUTTON_BAR` slug carrying a `columnsButton` element. Seed is guarded on `messageKey` rather than a
+  literal id because the keys are shared. Folding the three shipped screens off
+  `items.columns.modal.*` / `salesOrder.columns.modal.*` is an open follow-up. (apeterson)
 - 2026-06-23 — Documented from the `add-column-visibility` skill during initial knowledge seed. (apeterson)

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

@@ -574,6 +574,24 @@ developer asked for the **whole component**, not just badges. The old
   [surface-resolver](../../_underscore/features/surface-resolver.md) — terms are Core-global, no
   per-term gating).
 
+## `SurfaceActionBar` labeled mode honours `element.variant` (2026-08-28)
+
+`renderMode="labeled"` previously hardcoded `variant="secondaryAction"` for **every** button, so a
+surface element seeded `PRIMARY` could never render as primary — the seed was silently ignored.
+There is now an **`element.variant` → `BaseButton` variant map**, falling back to `secondaryAction`,
+so Sales Orders / Items / Vendor Items render exactly as before while the new
+`transfer-orders-list-actions` PRIMARY create button renders correctly.
+
+The map also **pins `fontSize: 14px` for the `primary` variant**, because blox's two "primary"
+classes are not interchangeable — see
+[blox authoring defects](../../toga-blox/features/blox-authoring-defects.md): `.primaryBtnAction`
+sets font-size **and** `height: 26px`; `.primaryBtn` sets **neither**. Swapping the variant silently
+changes type size and button height. The compensation belongs **at the instance / in this map**, not
+in an edit to the shared blox stylesheet.
+
+⚠ This is **shared infra** — `SurfaceActionBar` renders every migrated screen's chrome, so a change
+here is a cross-screen change. Re-check Sales Orders, Items and Vendor Items after touching it.
+
 ## Gotchas
 
 - **The VIP `/contacts` API call is gated by an approval-details element's `labelSuffix.valueKey`,
@@ -778,6 +796,13 @@ button except **View Log** renders and does nothing on click. Whether the SR mod
 actions surface is **still an open decision**, not an oversight.
 
 ## Change history
+- 2026-08-28 — **`SurfaceActionBar` labeled mode now honours `element.variant`** (shared infra):
+  `renderMode="labeled"` had hardcoded `variant="secondaryAction"` for every button, so a `PRIMARY`
+  seed could never render as primary. Added an `element.variant` → `BaseButton` variant map with a
+  `secondaryAction` fallback (Sales Orders / Items / Vendor Items unchanged), pinning
+  `fontSize: 14px` for `primary` because blox's `.primaryBtn` sets neither font-size nor height while
+  `.primaryBtnAction` sets both — compensated at the instance rather than by editing the shared blox
+  stylesheet. Driven by the new `transfer-orders-list-actions` bar. (apeterson)
 - 2026-08-28 — Recorded two durable FE surface rules from the denial-reason investigation (research
   only; no code written). (1) **A hidden marker's RULE can select a MODE**, not just a section on/off
   — el **108** `sectionLayoutRule` (`renderType TEXT`, `isVisible=0`) is the live precedent; reach for

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

@@ -17,20 +17,30 @@ 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/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferableItemRows.ts
+  - 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
 related:
   - ./surface-frontend.md
   - ./meta-driven-table-data.md
   - ./record-modals-and-nested-tables.md
+  - ./column-visibility.md
   - ../../dbchanges2/features/surface-layer-schema.md
   - ../../_underscore/features/surface-resolver.md
   - ../../_underscore/features/tableview-joins.md
   - ../../api2/features/v2-rest-query-contract.md
+  - ../../api2/features/tableview-field-metadata.md
   - ../../../../clients/nychh/profile.md
+  - ../../../../clients/nychh/features/transfer-order-inventory-quantities.md
 ---
 
 ## Summary
@@ -43,12 +53,16 @@ reserved-id seed → per-tenant TableView → per-tenant nav opt-in → surface-
 **It was fully greenfield.** An audit of production, beta, sandbox-client **and all 36 client
 databases** on 2026-08-28 found **no transfer-order TableView anywhere**. Nothing was extended.
 
+A **Create Transfer Order** modal was started the same day: the UI and its interaction rules are
+built, the data layer is **disabled behind a flag** pending three unanswered data-model questions
+(see below).
+
 The vertical is **platform-shared with NYCHH as the first (and today only) tenant**: the Core
 surfaces and the stage theme tokens are neutral/shared, and only the TableView and the navigation
 opt-in are `Client_Nychh`. That is the same shape as the Sales Order surfaces with Compass as first
 tenant.
 
-## The four migrations
+## The migrations
 
 | File | DB scope | What it does |
 |---|---|---|
@@ -56,8 +70,11 @@ tenant.
 | `Core/2026-08-28a - TransferOrderSurfaceSeed.sql` | Core | nav element, LIST surface, 4 record surfaces, stage vocabulary, 24 Messages |
 | `Client/2026-08-28a - TransferOrderStageThemeTokens.sql` | all tenants (template) | 5 `color.transferStage.*` tokens |
 | `Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql` | one tenant | the single `SurfaceOverrides` row that reveals the nav item |
+| `Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql` | one tenant | reproduces the **untracked** record/field ACL prod already has for records 312/313 |
+| `Client/2026-08-28b - TransferOrderItemsTimestamps.sql` | all tenants (template) | `TransferOrderItems.dtCreated`/`dtUpdated` (+ indexes), guarded `qtyCommitted` |
+| `Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql` | Core | the `transfer-orders-list-actions` BUTTON_BAR + `common.columns.modal.*` Messages |
 
-All four were audited against the cluster-isolation HARD RULE: **no `Core.*` reference in any
+All of them were audited against the cluster-isolation HARD RULE: **no `Core.*` reference in any
 `Client_*` file** (the only such strings are inside comments), no `UUID()`, all table references
 unqualified.
 
@@ -191,6 +208,94 @@ 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 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,
+because production and sandbox-client carry transfer-order state that **no `dbchanges2` file
+creates**. It was all hand-applied when the NetSuite TransferOrder POST was enabled:
+
+1. `AclRecordPermissions` for records **312** (`transfer-orders`) and **313**
+   (`transfer-order-items`), roles 1 and 3;
+2. their `AclLogicGroups` → `AclLogicGroupExpressions` → `AclRecordExpressions` chain;
+3. `AclFieldPermissions` for **all 17 `RecordFields`** of 312/313 (roles 1 and 3, `isWritable = 1`);
+4. the `TransferOrderItems.dtCreated` / `dtUpdated` **columns**.
+
+So **a fresh environment cannot reproduce production** — and the blast radius is bigger than this
+UI: the NetSuite transfer-order importer cannot be stood up in a fresh environment either.
+`Client_Nychh/2026-08-28c` reproduces layers 1–3 faithfully (**same roles, same permission bits as
+prod — not a widening**; role 2 *Developer* is deliberately **not** granted because prod/sandbox
+don't have it and role 1 satisfies the UI), anti-joined on natural keys: 2 expressions + 4 record
+permissions + 34 field permissions insert on local, **0 on sandbox** — dry-run verified in both
+directions. Layer 4 is `Client/2026-08-28b`. Client-side detail:
+[NYCHH transfer-order inventory & quantities](../../../../clients/nychh/features/transfer-order-inventory-quantities.md).
+
+**Follow-up recorded, not done:** run a systematic `information_schema` diff of local vs prod for
+the whole transfer-order area rather than discovering the gaps one 500 at a time — see
+[client schema drift audit](../../dbchanges2/workflows/client-schema-drift-audit.md).
+
+## The list-actions BUTTON_BAR (`Core/2026-08-28b`)
+
+`transfer-orders-list-actions`, **Surface 52**, elements **187–189**: Refresh (`SECONDARY`,
+`config.valueKey 'refresh'`), Columns (`SECONDARY`, `config.role 'columnsButton'` +
+`config.modal` message keys), Transfer Order (`PRIMARY`, `config.valueKey 'createTransferOrder'`).
+This closes the "no BUTTON_BAR surface" gap the first build left open.
+
+- **No `Actions` rows are needed.** With no handler registered in the FE `actionRegistry`,
+  `SurfaceActionBar` already falls through to `onDispatch(valueKey)` — which is exactly the
+  host-owned behaviour these three want. Only a control that needs a *registry handler* needs an
+  `Action` row.
+- **Seeded `isVisible = 1`, deliberately against the usual Core-OFF default.** A list screen with
+  no refresh and no create is not a useful neutral default, and none of the three is unsafe if
+  inherited — only NYCHH can reach the page at all. See
+  [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md) for when Core-neutral
+  means OFF and when it does not.
+- The Columns button's copy comes from **shared `common.columns.modal.*` Messages**, consumed
+  through the new `useColumnVisibilityModalConfig` hook — see
+  [column-visibility](./column-visibility.md).
+
+## Create Transfer Order modal — UI built, data layer deliberately NOT faked
+
+`view/CreateTransferOrderModal/` (+ `hooks/useTransferableItemRows.ts`), opened from the header
+button seeded above. The interaction rules are the durable part:
+
+- **Single-source lock.** The first checked row fixes the source location for the whole order.
+  Source Location is **derived and read-only — never picked**; the Location filter is pinned and
+  disabled while locked, and **restores its pre-lock value** when the lock releases.
+- **A row is an ITEM AT A LOCATION**, kept only where availability >= 1.
+- **Dirty means "different from the state the form OPENED IN"**, not "different from empty" — so a
+  pre-scoped open is clean, which is what makes the discard guard trustworthy.
+- **Qty error state machine:** touched on first keystroke; the error surfaces on **blur** only if
+  touched; then it live-revalidates.
+- **The Review gate names the FIRST unmet condition** rather than a generic "incomplete".
+
+**Three open questions block the data layer** (the picker + fetch are written but **disabled behind
+a flag** — nothing is stubbed with fake data):
+
+1. **Availability per (item, location) has no API.** `Item._qtyAvailable` is item-level with no
+   location dimension; the real source is `Units` (carries `itemId` + `locationId` + a
+   disposition). Unresolved: which `UnitDispositions` slug counts as available, and whether to
+   aggregate client-side or add a grouped table view. NYCHH has **3,226 active items**, so
+   browser-side grouping will not hold.
+2. **The design's target-location picker is a TREE** (breadcrumbs, drill-down, ancestor path), but
+   **no parent FK was found on `_Model_Client_Location`**. If Locations are flat, the dialog has to
+   become a searchable select and the design needs revisiting. Picker left disabled.
+3. **Commit flips unit dispositions to In Transit — a real inventory mutation.** Unresolved whether
+   the API owns that or a worker does.
+
+### Line-item fetch is off behind a FLAG, not commented out
+
+`TRANSFER_ORDER_LINES_ENABLED = false` until `Client/2026-08-28b` is applied everywhere. A flag,
+not a commented-out call: the repo rule bans committed commented-out code, and a flag keeps the
+hook typechecked.
+
+> ⚠ **A DISABLED React Query v5 query reports `status: 'pending'` FOREVER.** Any `isLoading` derived
+> from it must be read **through the flag**, or the UI hangs on its skeleton. This is the **third**
+> place in this codebase to hit it (`useFetchSurfaceMetaGroup` already documents it).
+
+With lines off, the three summary tiles render an **em-dash, not `0`** — all three are derived from
+the lines, so `0` would be a *wrong* number rather than a missing one — and the empty row reads
+"temporarily unavailable", not "no items".
+
 ## v1 scope — seeded but hidden
 
 Money (Unit Value / Total / Total Value) and Target Contact are **dropped for v1 but seeded as real
@@ -208,15 +313,21 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
 
 ## Rollout status & open items
 
-- **Applied and verified on LOCAL only.** Not run on sandbox-client or production. Nothing committed
-  to git as of 2026-08-28. `npx tsc --noEmit` exits 0; the UI has **not** been exercised in a browser.
+- **Applied and verified on LOCAL only.** Not run on sandbox-client or production.
+- **Git (2026-08-28):** commit **`9293904`** on branch `TRUE-80852` in toga25-supply (3 files — the
+  surface-driven header + the extracted hook), **not pushed**. The dbchanges2 migrations are
+  uncommitted in a separate repo, and **the FE commit is inert without `Core/2026-08-28b`**, so the
+  two must land together (the commit body names the dependency). `.env.development` was
+  **deliberately excluded** from the commit — its diff repoints every developer's dev server, which
+  must not ride inside a feature ticket (see
+  [amplify-deployment](../workflows/amplify-deployment.md)).
 - **Beta is blocked.** It lacks the `TransferOrderStages` table entirely (the `Client/2026-08-18*`
   files never landed there), so `Client_Nychh/2026-08-28a` would fail on a missing FK target.
 - **Open dependency:** `Client/2026-08-28a` writes to `ThemeTokens`, a table created by
   `Client/2026-06-25a - SurfaceClientTables.sql`. Any prod tenant that never received `2026-06-25a`
   will error, and the full 36-tenant list was **not** audited.
-- **No `transfer-orders-list-actions` BUTTON_BAR surface**, so Refresh/Columns are plain buttons
-  rather than `SurfaceActionBar`-driven like Sales Orders and Vendor Items.
+- ~~No `transfer-orders-list-actions` BUTTON_BAR surface~~ — **closed** by `Core/2026-08-28b`
+  (Surface 52, elements 187–189); the header is now `SurfaceActionBar`-driven like Sales Orders.
 - **Test data lives in the session scratchpad, never in dbchanges2** (24 seed orders + an unseed
   script). The dbchanges2 executor runs **every** folder against production, so throwaway fixtures
   must not be committed there. Origin/destination were picked by co-prime strides over ranked active
@@ -226,6 +337,13 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
 
 - **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
+  field is dropped from the SELECT list silently, but `TableView::meta()` still emits
+  `table.sort` naming its slug → the FE builds `ORDER BY TransferOrders.undefined` → MySQL 1054.
+  Mechanism and the two candidate platform fixes:
+  [tableview-field-metadata](../../api2/features/tableview-field-metadata.md).
+- **A disabled React Query v5 query is `pending` forever** — derive `isLoading` through the flag,
+  never from the query alone (see the line-item flag above).
 - **Never bind a Core TABLE surface to a `tableViewId`** — TableView ids are per-tenant and would not
   survive the Core/Client cluster split. Use `config.tableViewSlug`.
 - **Renaming a `TransferOrderStages` row silently greys out the badge** — the vocabulary matches the
@@ -241,6 +359,23 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
   earlier migration without names, so a name-based lookup on them finds nothing.
 
 ## Change history
+- 2026-08-28 — Second pass, same day. Discovered the vertical sits on **four untracked layers** of
+  prod/sandbox state (record + field ACL for records 312/313 and their logic-group chain, plus the
+  `TransferOrderItems.dtCreated/dtUpdated` columns) — a fresh environment cannot reproduce
+  production, and the NetSuite importer is blocked by the same gap; wrote `Client_Nychh/2026-08-28c`
+  (faithful reproduction, role 2 deliberately excluded) and `Client/2026-08-28b`. Closed the
+  BUTTON_BAR gap with `Core/2026-08-28b` (`transfer-orders-list-actions`, Surface 52, elements
+  187–189, seeded **visible** and needing no `Actions` rows because unregistered keys fall through to
+  `onDispatch(valueKey)`). Started the **Create Transfer Order modal** — interaction rules
+  implemented (single-source lock with a derived read-only Source Location, dirty-vs-opened-state,
+  the qty touched/blur error machine, a Review gate that names the first unmet condition) with the
+  data layer **disabled behind a flag rather than faked**, blocked on three open questions: no
+  per-(item, location) availability API (`Units` + a disposition is the real source; 3,226 active
+  items rules out client-side grouping), no parent FK found on `_Model_Client_Location` so the
+  design's location *tree* may not be buildable, and unowned responsibility for the In-Transit
+  disposition flip. Recorded the React-Query-v5 disabled-query `pending` trap (third occurrence) and
+  the ACL-gap-on-default-sort 500. Committed `9293904` (TRUE-80852), not pushed;
+  `.env.development` deliberately left out. (apeterson)
 - 2026-08-28 — First capture: built the Transfer Orders vertical from scratch after confirming no
   transfer-order TableView existed in prod, beta, sandbox-client or any of the 36 client DBs. Seeded
   the `Client_Nychh` `transfer-orders` TableView (3 joins, 4 columns) plus the full 4-table ACL chain

package/knowledge/2.0/apps/toga25-supply/workflows/amplify-deployment.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-08-27
+updated: 2026-08-28
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/amplify.yml
@@ -14,8 +14,11 @@ files:
   - toga25-supply/src/hooks/useAuthenticationFlow.ts
   - toga25-supply/vite.config.ts
   - toga25-supply/package.json
+  - toga25-supply/.env.development
 related:
   - ../architecture.md
+  - ../features/transfer-orders-page.md
+  - ../../toga-blox/workflows/local-link-into-a-consumer-app.md
 ---
 
 ## What it is
@@ -90,6 +93,22 @@ i.e. an optional per-subdomain override, falling back to `VITE_API`. The `.env.<
 are committed and git-tracked; they contain **only public `VITE_API` base URLs, no secrets**,
 and are the single source of truth for environment API endpoints.
 
+## Local development — `npm run dev` does NOT point at your local API
+
+`npm run dev` runs Vite in mode **`development`**, so **`.env.development` wins**, and that file
+ships `VITE_API = https://api.dev.sandbox.togahub.com/v2`. A developer who assumes "dev = my
+machine" is reading and writing **dev-sandbox** data.
+
+Worse, **`.env.development` is git-TRACKED**, so developers keep flipping it to their local API —
+which generates noise diffs and accidental commits, and a stray commit **repoints every other
+developer's dev server**. (This is why the transfer-orders FE commit deliberately excluded it; see
+[Transfer Orders page](../features/transfer-orders-page.md).)
+
+**Suggested fix, not yet done:** keep a neutral committed default in `.env.development` and let each
+developer override in a **gitignored `.env.development.local`** (Vite loads `.local` last and it is
+the intended per-developer layer). Until that lands, check `git status` before committing on any
+branch where you pointed the dev server at localhost.
+
 ## Adding a new environment
 
 1. Create `.env.<mode>` with the public `VITE_API` base URL.
@@ -131,6 +150,12 @@ and are the single source of truth for environment API endpoints.
   has ever been developed against a linked local checkout.
 
 ## Change history
+- 2026-08-28 — Recorded that **`npm run dev` does not point at a local API**: mode `development`
+  loads the tracked `.env.development`, which ships
+  `VITE_API = https://api.dev.sandbox.togahub.com/v2` — so "dev" reads/writes dev-sandbox data. The
+  file being tracked is itself a hazard (flip-and-commit noise repoints everyone's dev server);
+  suggested a neutral committed default plus a gitignored `.env.development.local` — not done.
+  (apeterson)
 - 2026-08-27 — Fixed `_production` never declaring `@agilant/toga-blox` (no dependency entry, no
   lock entry, ~200 imports) — it resolved only via a local **symlink**, and `npm ci` in `preBuild`
   would have failed. Added blox plus the four peers the symlink had masked

package/knowledge/clients/nychh/INDEX.md

@@ -4,5 +4,5 @@
 |-----|-----------|---------|-------|
 | [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
-| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql |
-| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql |
+| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
+| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.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, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |

package/knowledge/clients/nychh/features/transfer-order-inventory-quantities.md

@@ -6,18 +6,23 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-27
-owners: [jcardinal]
+updated: 2026-08-28
+owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Nychh/Item.php
   - _underscore/Model/Nychh/TransferOrder.php
   - _underscore/Model/Nychh/TransferOrderStage.php
   - _underscore/Model/Client/TransferOrder.php
+  - _underscore/Model/Client/TransferOrderItem.php
   - dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql
   - dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql
+  - dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql
+  - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql
 related:
   - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
   - ../../../2.0/apps/api2/features/v2-api-error-codes.md
+  - ../../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md
+  - ../../../2.0/apps/toga25-supply/features/transfer-orders-page.md
   - ../../growrk/features/transfer-order-flow.md
   - ./netsuite-transfer-order-import.md
   - ../profile.md
@@ -31,6 +36,10 @@ that let a NetSuite-sourced TransferOrder actually POST through the V2 API. The
 feeds these POSTs is in
 [NYCHH NetSuite → TransferOrders import](./netsuite-transfer-order-import.md).
 
+> 🚨 **Most of that enablement was hand-applied and never written into `dbchanges2`** (four layers —
+> see below). It was reconstructed on 2026-08-28; until those files run, a fresh environment can
+> reproduce neither the UI nor the importer.
+
 The general, framework-level lessons from the field-exposure work here are recorded on the shared
 [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md) and
 [V2 API error codes](../../../2.0/apps/api2/features/v2-api-error-codes.md) docs; this doc keeps the
@@ -83,6 +92,51 @@ peeled in order:
 > dead end.) Recorded framework-wide on the
 > [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
 
+## 🚨 The enablement above was HAND-APPLIED — four layers exist on prod with no migration behind them
+
+Discovered 2026-08-28 while standing the Transfer Orders UI up locally: beyond the two 08-27 files,
+**production and sandbox-client carry transfer-order state that no `dbchanges2` file creates.** It
+was all applied by hand when the NetSuite TransferOrder POST was enabled:
+
+| Layer | What is missing from the repo |
+|---|---|
+| a | `AclRecordPermissions` for records **312** (`transfer-orders`) / **313** (`transfer-order-items`), roles **1** and **3** |
+| b | their `AclLogicGroups` → `AclLogicGroupExpressions` → `AclRecordExpressions` chain |
+| c | `AclFieldPermissions` for **all 17 `RecordFields`** of 312/313 (roles 1 and 3, `isWritable = 1`) |
+| d | the `TransferOrderItems.dtCreated` / `dtUpdated` **columns** |
+
+**Consequence: a fresh environment cannot reproduce production**, and that is not just a UI problem
+— **the NetSuite transfer-order importer cannot be stood up in a fresh environment either.** Local
+had none of it and failed **one layer at a time, each with a different-looking error** (a dropped
+column, an `EZ-1`, a 500), which is what makes this class of drift so expensive to diagnose.
+
+**`Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql`** reproduces (a)–(c) **faithfully — same
+roles, same permission bits as prod. It is not a widening.** Role **2** (Developer) is deliberately
+**not** granted: prod and sandbox don't have it, and role 1 satisfies the UI. Every statement is
+anti-joined on natural keys, so it inserts **2 expressions + 4 record permissions + 34 field
+permissions on local and 0 on sandbox** — dry-run verified in both directions.
+Layer (d) is `Client/2026-08-28b` (see the next section).
+
+**Follow-up, recorded not done:** a systematic `information_schema` diff of local vs prod across the
+whole transfer-order area, instead of discovering gaps one 500 at a time — procedure in
+[client schema drift audit](../../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md).
+
+## `TransferOrderItems` is missing `dtCreated`/`dtUpdated` in the BLANK TEMPLATE — every tenant
+
+`_Model_Client_TransferOrderItem` declares `dtCreated`/`dtUpdated` as
+`FIELD_DATETIME_CREATED`/`FIELD_DATETIME_UPDATED`, so `_Model` puts them in **every SELECT it
+builds** — nothing in a request has to ask for them. But the blank-client template
+(`Client/2026-06-03- BLANK_CLIENT_DATABASE.sql`, `CREATE` at ~line 9462) **does not create them**.
+So **every tenant provisioned from the template has a table the model cannot read.** This is not
+NYCHH-specific; NYCHH is just where it surfaced.
+
+`Client/2026-08-28b - TransferOrderItemsTimestamps.sql` adds both columns (+ their indexes) and,
+guarded, `qtyCommitted`. ⚠ **The template itself still needs fixing** or the next new tenant
+reproduces the defect — not done (it is a generated dump plus an already-run migration). Recorded on
+[new-client onboarding](../../../2.0/apps/dbchanges2/workflows/client-onboarding.md); the
+conditional-`ALTER` authoring technique the file uses is in
+[re-runnable additive migrations](../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md).
+
 ## `isActive` is defaulted in the ORM, not sent in the payload (shared model)
 
 `TransferOrders.isActive` is **NOT NULL**, but `isActive` is **not a registered/writable V2 field** —
@@ -104,6 +158,16 @@ pattern (default a NOT NULL non-writable column in the model, never send it) is
 
 ## Change history
 
+- 2026-08-28 — Discovered that the transfer-order enablement on **prod and sandbox-client is
+  UNTRACKED**: record ACL for 312/313 (roles 1 and 3), their logic-group/expression chain, field ACL
+  for all 17 RecordFields, and the `TransferOrderItems.dtCreated`/`dtUpdated` columns all exist with
+  **no `dbchanges2` file behind them** — so a fresh environment can reproduce neither the UI nor the
+  NetSuite importer, and local failed one layer at a time with a different-looking error each time.
+  Wrote `Client_Nychh/2026-08-28c` (faithful reproduction of the ACL layers — same roles, same bits,
+  role 2 deliberately excluded; 2+4+34 rows on local, 0 on sandbox) and `Client/2026-08-28b` for the
+  columns. Root cause of the column gap is the **blank-client template**, which never creates the two
+  timestamps the model always selects — every tenant is affected and the template is still unfixed.
+  (apeterson)
 - 2026-08-27 — Built the NYCHH two-branch inventory quantity model on `_Model_Nychh_Item` (on hand =
   received − fulfilled; available = on hand − committed; fulfilled = Σ shipped TO fulfillments;
   backordered = ordered − received; added `_qtyOnOrder`), per the 2026-08-17 TOGa Supply meeting.

package/knowledge/clients/nychh/profile.md

@@ -25,6 +25,8 @@ files:
   - dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.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
+  - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/tableview-joins.md
@@ -72,8 +74,17 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   tenant already grants Sales Orders and Inventory — NYCHH does not scope navigation by role). The
   Core surfaces and the stage colour tokens are **shared/neutral**, hidden for every other client
   until they opt in. Not yet run on sandbox-client or production; **beta is blocked** because it
-  lacks the `TransferOrderStages` table. See
+  lacks the `TransferOrderStages` table. A **Create Transfer Order** modal is started (UI built, data
+  layer flagged off pending three open data-model questions). See
   [Transfer Orders page](../../2.0/apps/toga25-supply/features/transfer-orders-page.md).
+- 🚨 **The transfer-order ACL + schema on prod/sandbox are UNTRACKED (2026-08-28).** Record and field
+  ACL for records 312/313, their logic-group/expression chain, and the
+  `TransferOrderItems.dtCreated`/`dtUpdated` columns were all hand-applied when the NetSuite
+  TransferOrder POST was enabled — **no `dbchanges2` file creates any of it**, so a fresh environment
+  can reproduce neither the UI nor the importer. Reconstructed in `Client_Nychh/2026-08-28c` (ACL,
+  faithful — role 2 deliberately excluded) and `Client/2026-08-28b` (columns; root cause is the blank
+  client template, which affects **every** tenant). See
+  [NYCHH transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
 - **Two-branch inventory quantities + TransferOrder V2 enablement** — NYCHH-only on-hand/available/
   fulfilled/backordered model on `_Model_Nychh_Item`, plus the client-override models + ACL rows that
   let a NetSuite TransferOrder POST succeed. See

package/package.json

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