toga-ai 1.0.712 → 1.0.713

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

@@ -3,11 +3,12 @@
 | 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 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 |
+| [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/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 |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Aig/_modules.txt, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |
+| [Targeting the right database (tenant restores, and running a change file against the wrong DB)](workflows/targeting-the-right-database.md) | Two ways to point at the wrong database — a dump taken from the wrong host, and a change file piped into the wrong schema. | api2/Config/production.ini, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql |
 | [Verifying whether a dbchanges2 migration actually ran in an environment](workflows/verifying-a-migration-ran.md) | dbchanges2 has no execution ledger you can query — "did this file run here?" has to be answered from the **rows the file would have produced**. | Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql |

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

@@ -6,11 +6,10 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [bala, kyalamarthi]
+updated: 2026-08-31
+owners: [bala, kyalamarthi, apeterson]
 files:
   - 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
 related:
   - ../architecture.md

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/db-migrations/PLAYBOOK.md
@@ -563,7 +563,10 @@ All four gated buttons (17/18/19/21) carry the **Core** rule `order._status in [
 so on a **canceled** order the approval-workflow button is **hidden**.
 
 **Next free Core ids in PROD, 2026-08-28:** `Surfaces` **47**, `SurfaceElements` **170**, `Messages`
-**227**, `Actions` **17**. (Re-verify per the 🚨 rule below before writing a seed — "next free" vs
+**227**, `Actions` **17**. **Superseded — on 2026-08-31 (sandbox-client, freshly reset from prod) the
+MAX ids were `Surfaces` 52 / `SurfaceElements` 189 / `Messages` 260, and `Core/2026-08-28a`+`b` then
+claimed `Surfaces` 53–57 / `SurfaceElements` 190–206 / `Messages` 261–284.** (Re-verify per the 🚨
+rule below before writing a seed — "next free" vs
 "highest used" is exactly what caused the 2026-08-24 collision.)
 
 **Per-tenant overrides, as they actually exist in prod:**
@@ -605,6 +608,41 @@ the LIST surface + 4 record-modal SECTION surfaces + the `transfer-order-stage`
 verified free on **local AND production** before authoring. See
 [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 
+#### ⚠ Those blocks were RENUMBERED on 2026-08-31 — a reservation expires when someone else ships
+
+The 2026-08-28 blocks above were reserved from a **2026-08-28 snapshot** of production, and were
+**claimed by another feature before the transfer-order files shipped**: `sales-order-denial-details`
+took `Surfaces` **47**, `SurfaceElements` **170–176** and `Messages` **227–232**. Re-verified against
+sandbox-client (freshly reset from production) on 2026-08-31, where MAX ids were `Surfaces` **52** /
+`SurfaceElements` **189** / `Messages` **260**, the two transfer-order files were renumbered to a
+contiguous block above MAX:
+
+| | Reserved 2026-08-28 (stale) | **Live, as committed 2026-08-31** |
+|---|---|---|
+| `Core.Messages` | 227–260 | **261–284** |
+| `Core.Surfaces` | 47–52 | **53–57** |
+| `Core.SurfaceElements` | 170–189 | **190–206** |
+
+`Surfaces` 48–51, `SurfaceElements` 177–186 and `Messages` 233–250 are deliberately left as **unused
+gaps** rather than back-filled — a contiguous block above MAX is trivially verifiable and trivially
+reversible; hunting free holes is neither.
+
+Two durable rules:
+
+1. **A reserved block is a snapshot, not a lock.** Nothing in Core enforces it. **Re-verify the block
+   is still free immediately before the file runs**, not just when it is written, and say so in the
+   file header. The longer a seed sits unmerged, the more likely its block is gone.
+2. **Renumbering is cheap; colliding is not.** Because these seeds use literal ids with plain
+   `INSERT`, a stale block fails loudly on the primary key — which is the designed behavior and the
+   reason `INSERT IGNORE` is banned here (see the 2026-08-24 incident below). Bump to a fresh block
+   above MAX rather than trying to reuse the gap.
+
+> These explicit ids are **correct and required**, not a portability bug. `Core.Surfaces` /
+> `Core.SurfaceElements` / `Core.Messages` are reserved-literal tables precisely so a `Client_*`
+> override file can inline them without a cross-cluster `Core.*` read. Do not "fix" a surface seed
+> into a `messageKey`-resolving `INSERT … SELECT`: the client-side references have no way to resolve
+> a Core id at runtime.
+
 **⚠ The reserved blocks are not an inventory of every surface id — pre-2026-08-21 surfaces sit
 outside them.** The reserved-id discipline begins at the reseed, so surfaces seeded before it took
 plain `AUTO_INCREMENT` ids: the **`navigation`** TAB_STRIP is `Core.SurfaceElements` **109–114**
@@ -978,6 +1016,15 @@ hits `Duplicate entry '251' for key 'messages.PRIMARY'`. The resolution that kee
   `config.valueKey` when it lives in the page.
 
 ## Change history
+- 2026-08-31 — **Renumbered the transfer-order reserved blocks** to `Messages` **261–284**,
+  `Surfaces` **53–57**, `SurfaceElements` **190–206**: the 2026-08-28 blocks were reserved from a
+  snapshot and `sales-order-denial-details` claimed `Surfaces` 47 / `SurfaceElements` 170–176 /
+  `Messages` 227–232 first. New rule — **a reserved block is a snapshot, not a lock; re-verify it is
+  free immediately before the file RUNS, not just when it is written**, and bump to a contiguous
+  block above MAX (leaving gaps) rather than back-filling. Also recorded explicitly that literal
+  Core ids in a surface seed are **required, not a portability bug**, so nobody "fixes" one into a
+  `messageKey`-resolving `INSERT … SELECT`. From `Core/2026-08-28a`/`b`, committed in `dbchanges2`
+  `1c3fe2e`. (apeterson)
 - 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:

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

@@ -0,0 +1,99 @@
+---
+title: "Targeting the right database (tenant restores, and running a change file against the wrong DB)"
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-08-31
+owners: [apeterson]
+files:
+  - api2/Config/production.ini
+  - dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql
+related:
+  - ../architecture.md
+  - ./verifying-a-migration-ran.md
+  - ../features/surface-layer-schema.md
+  - ../../../clients/nychh/profile.md
+---
+
+## Summary
+
+Two ways to point at the wrong database — a dump taken from the wrong host, and a change file piped
+into the wrong schema. **Both "succeed."** One of them silently overwrites a shared environment with
+your laptop's data; the other fails with an error that names the wrong problem. This is the
+procedure that catches each before it costs a day.
+
+## Where the databases are
+
+Connection **locations** only — passwords live in the config file, never here.
+
+| Cluster | Host | Config section (`api2/Config/production.ini`) |
+|---|---|---|
+| Core | `reader1.core.database.togahub.com` | `[database]` |
+| Client (tenant) — read | `reader1.client.database.togahub.com` | `[databaseClient]` |
+| Client (tenant) — write | `writer.client.database.togahub.com` | `[databaseClient]` |
+| Logs | — | `[databaseLogs]` |
+| Client sandbox | `client.sandbox.database.togahub.com` | (sandbox config) |
+
+Username is `admin`. **The password is in the matching section of
+`api2/Config/production.ini` — read it from there; never paste it anywhere, including here.**
+
+**Keep the password out of your shell history and out of `ps`** by building a throwaway
+credentials file from the ini instead of passing `-p` on the command line:
+
+```bash
+# awk the password out of the [databaseClient] section into a 0600 defaults file
+umask 077
+awk '/^\[databaseClient\]/{s=1} s&&/^password/{print; exit}' Config/production.ini \
+  | sed 's/ *= */=/' > /tmp/my.cnf.$$
+printf '[client]\nhost=reader1.client.database.togahub.com\nuser=admin\n' | cat - /tmp/my.cnf.$$ > /tmp/creds.cnf
+mysql --defaults-extra-file=/tmp/creds.cnf Client_Nychh -e 'SELECT COUNT(*) FROM TransferOrders'
+```
+
+Delete the file when you are done.
+
+## Steps — before you trust ANY tenant dump
+
+1. **Prove which environment you actually reached, with a row count known to DIFFER between
+   environments.** Not a table list, not a schema diff — a *count*. Worked example (2026-08-31):
+   `Client_Nychh.TransferOrders` = **1,927 rows in production** and **24 `TO-SEED-*` rows locally**.
+   One `SELECT COUNT(*)` settles it.
+2. **Re-check the host you typed.** `-h127.0.0.1` / `-hlocalhost` in a command you believed was
+   pointed at prod is the whole failure mode; a defaults file (above) removes the chance to fumble it.
+3. **Restore.** Drop + restore will run perfectly whatever the source was — success proves nothing.
+4. **Verify the restored copy against the SOURCE you intended**, repeating step 1 against the
+   restored schema.
+
+## Gotchas
+
+- 🚨 **A wrong-source restore is silent and total.** A dump taken from `127.0.0.1`, believed to be
+  production, was restored onto sandbox-client `Client_Nychh`. Both the drop and the restore
+  succeeded; sandbox simply became a copy of the developer's laptop, carrying local `TO-SEED-*`
+  transfer orders into a shared environment. **The tell was that sandbox matched local EXACTLY** —
+  353 tables, identical row counts. An exact match with your local DB is evidence of a bad restore,
+  not of a good one.
+- **A small post-restore drift vs. live prod is EXPECTED, not an error.** `--single-transaction`
+  makes the dump a point-in-time snapshot, so a live table keeps moving after it: `Units` read 8,627
+  on prod and 8,618 on the restored sandbox. Do not chase that; only a *category* difference
+  (missing tables, order-of-magnitude counts) means the restore was wrong.
+- 🚨 **The `dbchanges2` folder name IS the target database — pipe each folder to its own DB.**
+  `Core/` → `Core`, `Client_<Name>/` → that one tenant, `Client/` → **every** tenant. Files reference
+  tables **unqualified** by design (the cluster-isolation rule), so running a `Core/` file against a
+  client DB does not complain about the database — it fails as
+  `Table 'Client_Nychh.Messages' doesn't exist`, which names a missing table rather than the real
+  mistake. If you see "table doesn't exist" for a table you know is in Core, check which schema you
+  piped the file into before you touch the SQL.
+- **The repo is evidence of intent, never of what an environment contains.** Confirming a file ran
+  is its own procedure — see
+  [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
+
+## Change history
+- 2026-08-31 — Initial. Captured after a dump taken from `127.0.0.1` was restored onto sandbox-client
+  `Client_Nychh` believing it was production (the tell: sandbox matched local exactly). Records the
+  verify-by-differing-row-count check, the `--single-transaction` snapshot-drift caveat, the
+  prod/sandbox cluster hostnames + which config section holds each password, the
+  `--defaults-extra-file` recipe that keeps the password out of history and `ps`, and the
+  folder-name-is-the-target-database rule with its misleading "table doesn't exist" error.
+  (apeterson)

package/knowledge/2.0/apps/toga-blox/workflows/dynamic-publish-pipeline.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-27
+updated: 2026-08-31
 owners: [jcardinal, apeterson]
 files:
   - toga-blox/.github/workflows/publish.yml
@@ -85,6 +85,14 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
 
 ## Gotchas
 
+- **⚠ There is a STALE UNDERSCORED dist-tag on the registry — `_sandbox-client` (with the
+  underscore) is NOT the channel.** Verified 2026-08-31, the registry carries **both**
+  `_sandbox-client` = `1.0.316-sandbox-client.1` (vestigial, predates the current pipeline) **and**
+  `sandbox-client` = `1.1.1-sandbox-client.140` (the live channel head). Branch `_<mode>` maps to
+  channel `<mode>` with the underscore **stripped** (same convention as `amplify.yml`), so the
+  **branch** `_sandbox-client` tracks the **tag** `sandbox-client`. Asking npm for "the latest
+  `_sandbox-client` tag" literally installs something **139 publishes behind**. Always resolve the
+  head with `npm view @agilant/toga-blox dist-tags` and install the underscore-less name.
 - **Publish before build.** `npm install @agilant/toga-blox@<mode>` fails `ETARGET No matching
   version` in the app build until this repo has published that channel. GitHub Actions runs the
   workflow version *on the pushed branch*, so the branch must carry the current `publish.yml`.
@@ -192,6 +200,10 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   you push to a release branch.
 
 ## Change history
+- 2026-08-31 — Recorded the **stale underscored dist-tag trap**: the registry carries both
+  `_sandbox-client` (`1.0.316-sandbox-client.1`, vestigial) and `sandbox-client`
+  (`1.1.1-sandbox-client.140`, live head). Installing the underscored name silently pins 139
+  publishes back. (apeterson)
 - 2026-08-27 — Released blox **1.1.0** on `_production` (published `1.1.1-production.139`) and fixed
   a shipped-broken tarball: the `feature-new-table` → `_production` merge left `global.css` at the
   repo root with `import "../global.css"`, so the emitted `dist/index.js` referenced a path outside

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

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: [tcox, apeterson]
 files:
   - toga-blox/package.json
@@ -88,6 +88,29 @@ dedupe: [
 - **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.
+- **Version parity is a red herring — module IDENTITY is what matters.** In the reproduction both
+  copies were `@tanstack/react-query` **5.101.4**. Identical versions still mean two physical
+  directories, two module instances, and two React contexts. Do not clear the theory because
+  `npm ls` shows one version.
+- **`dedupe` alone was not sufficient here — alias too.** Follow-up 2026-08-31: pin every
+  **context-bearing** peer with **both** `resolve.alias` (absolute path into the app's
+  `node_modules`, the same treatment `react`/`react-dom` already had) **and** `resolve.dedupe`:
+  `@tanstack/react-query`, `@tanstack/react-query-persist-client`, `@tanstack/react-table`,
+  `react-hook-form`. `react-hook-form` was nested under blox as well — the same latent bug for
+  `BaseInput` / `useFormContext`, just not throwing yet.
+- **`optimizeDeps.include` is why the throw appears to come from inside blox.** With blox in
+  `optimizeDeps.include`, esbuild pre-bundles blox **together with its nested copy**, so the error
+  surfaces from `@agilant_toga-blox.js` rather than from app code, and the `?v=<hash>` in the error
+  URL is the pre-bundle cache key (which is why a config change with a stale
+  `node_modules/.vite` looks like it did nothing).
+- **Verification technique — prove there is exactly one copy.** After rebuilding deps, confirm that
+  **exactly one** chunk under `node_modules/.vite/deps` contains the string `No QueryClient set`,
+  then confirm `@agilant_toga-blox.js`, `@tanstack_react-query.js` and
+  `@tanstack_react-query-persist-client.js` all import **that same** chunk. Before the fix blox
+  imported its own.
+- **Installing blox from the registry replaces the symlink with a real directory**, which removes
+  this root cause outright — the alias/dedupe belt-and-braces is what keeps the *linked* dev loop
+  safe.
 
 ### 3. Disable blox's PostCSS config while linked
 
@@ -119,6 +142,14 @@ 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-31 — Closed out the duplicate-`react-query` case with the parts that made it hard:
+  **both copies were the SAME version (5.101.4)** — identity, not version, is what breaks context;
+  `optimizeDeps.include` pre-bundles blox with its nested copy so the throw appears to originate
+  inside `@agilant_toga-blox.js`; the fix needs `resolve.alias` (absolute path) **as well as**
+  `resolve.dedupe` for every context-bearing peer (react-query, react-query-persist-client,
+  react-table, **react-hook-form** — also nested, same latent bug for `BaseInput`); and a concrete
+  one-copy verification (exactly one `.vite/deps` chunk containing `No QueryClient set`, imported by
+  blox and both react-query chunks). (apeterson)
 - 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

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [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 |
+| [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.test.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASS/approvalActionFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASSCANADA/approvalActionFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` / `join` / `where` to request from the TOGa API for a given page — fr | toga25-supply/src/fieldsConfig/resolveApiConfig.ts, toga25-supply/src/fieldsConfig/useClientApiFields.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx |
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
 | [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 |

package/knowledge/2.0/apps/toga25-supply/features/action-button-rule-engine.md

@@ -6,16 +6,22 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-08-31
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.test.ts
   - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
+  - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASS/approvalActionFields.json
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASSCANADA/approvalActionFields.json
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx
 related:
   - client-configurable-fields.md
+  - record-modals-and-nested-tables.md
   - ../architecture.md
+  - ../../../clients/compass-usa/features/approval-decision-flow.md
 ---
 
 ## What it is
@@ -55,8 +61,11 @@ type FieldOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte"
 - **`RuleContext`** is `{ order, currentStage?, stages? }`. `currentStage`/`stages` carry
   approval-workflow state when available.
 - **Named rules** (`{ type }`) are bespoke leaf checks that a field predicate cannot express
-  — they live in the `NAMED_RULES` registry. Currently only `stepTwoAssigned` (walks the
-  approval stages to confirm a step-2 assignee exists). An unknown `type` resolves to `true`.
+  — they live in the `NAMED_RULES` registry. Members (both walk the approval stages, which a
+  field predicate cannot express):
+  - `stepTwoAssigned` — a step-2 assignee exists.
+  - `stepOneUndecided` — step 1 carries **no** decision yet.
+  An unknown `type` resolves to `true`.
 
 ### Resolution primitives
 
@@ -78,6 +87,25 @@ type FieldOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte"
 It returns a new `tenantFields` with a patched `recordActionFields.actionOptions`. Callers:
 `useSalesOrderRecordModalLayoutModel.tsx` and `useApprovalModalViewModel.tsx`.
 
+### It also resolves flags on approval-workflow STAGE INPUTS
+
+`buildPatchedTenantFields` additionally walks
+`recordActionFields.approvalWorkflow.stages[].inputs[]` and resolves each input's flags the same
+way. This placement is deliberate and is the layering rule to preserve: **rule evaluation stays in
+the `pages/SalesOrders` layer, so the shared `layout/RecordApprovalModal` receives only plain
+booleans and holds no tenant logic.** A shared-layout component must never import the rule engine
+or read tenant config; if it needs a new gate, resolve the flag here and pass it down.
+
+`ApprovalFlowDetailInputs.tsx` consumes one such resolved boolean: a resolved `isEnabled === true`
+on a stage's `assignedTo` input **overrides the decided-stage lock** —
+
+```ts
+isAssignedToDisabled = areInputsDisabled && !isAssignedToUnlocked
+```
+
+The note textarea and the approve/deny controls stay locked regardless, so a recorded decision can
+never be flipped — only the assignee is reopened.
+
 ### Back-compat shim
 
 The previous single-purpose `EnableRule` grammar (`alwaysEnabled`, `requireStepTwoAssigned`,
@@ -103,6 +131,14 @@ Retire the shim once all configs express flags as `Rule`.
 
 ## Gotchas
 
+- **⚠ Both Compass `approvalActionFields.json` files repeat the heading string
+  `"Approval: Manager Approval"` on step 1 AND step 2** (in the `MANAGER` role block). A
+  text/heading-anchored edit therefore silently patches the **wrong stage**. Target stages by
+  **structure** (`stage.valueKey === "2"`) and assert placement afterwards.
+- **A tenant opts into a stage-input gate by config only.** Adding
+  `"isEnabled": { "type": "stepOneUndecided" }` to a step-2 `assignedTo` input changes that tenant
+  and nothing else: tenants that omit the key hit `resolveFlag`'s `false` fallback and keep their
+  existing behaviour exactly (DEFAULT and QUAD were left untouched for this reason).
 - **`recordActionFields` is the current key** (renamed from `approvalActionFields` /
   `orderViewFields`-era naming). `buildPatchedTenantFields` reads
   `recordActionFields.actionOptions`; missing config falls back to `[]`.
@@ -116,4 +152,17 @@ Retire the shim once all configs express flags as `Rule`.
   default.
 
 ## Change history
+- 2026-08-31 — **Added named rule `stepOneUndecided` and extended `buildPatchedTenantFields` to
+  resolve flags on `approvalWorkflow.stages[].inputs[]`**, so a VIP-pre-approved step-2 manager can
+  be reassigned (Compass USA + Compass Canada). `ApprovalFlowDetailInputs` now treats a resolved
+  `isEnabled === true` on a stage's `assignedTo` as an override of the decided-stage lock while the
+  note and approve/deny controls stay locked. Both tenants opt in via config only (step-2
+  `assignedTo`, ADMIN + MANAGER blocks); DEFAULT and QUAD unchanged. **The rule deliberately does
+  NOT key on `isPreApproved`** — blox derives that solely from
+  `!!stage.ApprovalDecisionTypes.name`, which is NULL on precisely the broken orders (see
+  [Compass Approval-Decision Flow](../../../clients/compass-usa/features/approval-decision-flow.md));
+  "step 1 undecided" is the safe equivalent because an order cannot legitimately be past step 2
+  while step 1 is pending. Recorded the duplicate-heading trap in both Compass config files and the
+  keep-rules-out-of-`RecordApprovalModal` layering rule. Verified: `tsc -b` clean, 44/44 vitest
+  (10 new in `evaluateEnableRule.test.ts`), `vite build --mode sandbox-client` clean. (apeterson)
 - 2026-06-25 — Documented the generic Flag/Rule engine: combinators, field predicates, named-rule registry, `resolveFlag`/`buildPatchedTenantFields`, and the legacy `EnableRule` back-compat shim. (apeterson)

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

@@ -238,6 +238,16 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   join is not feasible for a list, so that column needs the backend field (promote `_purchaseOrders`
   to base `_Model_Client_SalesOrder`) or be hidden for Quad. **Not addressed** — open follow-up.
 
+- **A decided stage's `assignedTo` can be selectively UNLOCKED — and the emitted PUT must stay
+  assignee-only.** `ApprovalFlowDetailInputs` unlocks just the assignee when the stage input's
+  resolved `isEnabled` is `true` (Compass USA/Canada step 2; see
+  [Action-Button Rule Engine](action-button-rule-engine.md)), leaving note + approve/deny locked.
+  The payload consequence is load-bearing: the request carries **only `assignedToUserId` and never
+  `isApproved`**, because `_Model_Compass_ApprovalDecision::_evaluateManagerVip` **early-returns
+  when `isset($api->httpPayload->isApproved)`**. Keeping `isApproved` out is what lets `postPut` →
+  `handleManagerReassignment` run and revoke a VIP auto-approval for a non-VIP / over-limit new
+  manager. Adding `isApproved` "for completeness" would silently disable that backend rule.
+
 - **ONE `TableRecordModal` must own every state — loading, error and loaded.** Rendering a second
   `TableRecordModal` for the loaded state puts a **different element type at the same position in the
   tree**, so React unmounts the first and mounts the second: the CSS keyframe restarts and the user
@@ -252,6 +262,9 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   [Transfer Orders page](transfer-orders-page.md).
 
 ## Change history
+- 2026-08-31 — Recorded the **selectively-unlocked `assignedTo` on a decided approval stage** and
+  the rule that its PUT must remain assignee-only (`isApproved` present makes
+  `_evaluateManagerVip` early-return, killing the reassignment revoke path). (apeterson)
 - 2026-08-28 — Added two modal rules confirmed on the Transfer Orders build: **one
   `TableRecordModal` owns loading/error/loaded** (a second one at the same tree position swaps
   element types and replays the slide-up animation), and a record whose children are **not** declared

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/TransferOrders/TransferOrders.tsx
@@ -115,9 +115,22 @@ bind to whichever Locations join happened to be first.
 
 ## The Core surface vertical
 
-Reserved id blocks (verified free on local, sandbox-client **and** production before writing):
-**`Messages` 227–250, `Surfaces` 47–51, `SurfaceElements` 170–186**, all literal ids with plain
-`INSERT` — never `INSERT IGNORE`.
+Reserved id blocks, **as committed** (`dbchanges2` `1c3fe2e`, 2026-08-31): `Core/2026-08-28a` +
+`2026-08-28b` together claim **`Messages` 261–284, `Surfaces` 53–57, `SurfaceElements` 190–206**, all
+literal ids with plain `INSERT` — never `INSERT IGNORE`.
+
+⚠ **These are NOT the 227–250 / 47–51 / 170–186 blocks the first draft reserved.** Those were taken
+from a 2026-08-28 prod snapshot and `sales-order-denial-details` shipped into them first
+(`Surfaces` 47, `SurfaceElements` 170–176, `Messages` 227–232). Re-verified on sandbox-client
+(freshly reset from prod) 2026-08-31 — MAX was `Surfaces` 52 / `SurfaceElements` 189 / `Messages`
+260 — and renumbered to a contiguous block above MAX, leaving the old range as unused gaps. Any
+surface/element id quoted below is from the original draft numbering; **read the file, not this
+table, for the live id**. Re-verify the block is free again immediately before running. See
+[Surface Layer Schema](../../dbchanges2/features/surface-layer-schema.md).
+
+**Run order: `Core/` → `Client/` (fan-out) → `Client_Nychh/`.** The client files reference Core
+record ids, and the NYCHH TableView + ACL depend on columns the fan-out files add. Within `Client/`,
+the stages table must precede the file that adds the stage-id FK column.
 
 | Surface | id | Type | Notes |
 |---|---|---|---|
@@ -359,6 +372,12 @@ 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-31 — **Committed the seven-file migration set** (`dbchanges2` `1c3fe2e`, branch
+  `TRUE-80852`, pushed) and **renumbered the Core reserved blocks** to `Messages` 261–284 /
+  `Surfaces` 53–57 / `SurfaceElements` 190–206 — the 2026-08-28 blocks had been claimed by
+  `sales-order-denial-details` before this shipped. Recorded the **`Core/` → `Client/` →
+  `Client_Nychh/` run order**. Also corrected the prod picture: `Client_Nychh.TransferOrders` holds
+  **1,927 production rows** — only the UI vertical is new, the data is long-live. (apeterson)
 - 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

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-28
+updated: 2026-08-31
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/amplify.yml
@@ -17,6 +17,7 @@ files:
   - toga25-supply/.env.development
 related:
   - ../architecture.md
+  - ../../toga-blox/workflows/dynamic-publish-pipeline.md
   - ../features/transfer-orders-page.md
   - ../../toga-blox/workflows/local-link-into-a-consumer-app.md
 ---
@@ -109,6 +110,56 @@ developer override in a **gitignored `.env.development.local`** (Vite loads `.lo
 the intended per-developer layer). Until that lands, check `git status` before committing on any
 branch where you pointed the dev server at localhost.
 
+## ⚠ The build spec and the `.env` set are NOT reliably present on a branch
+
+Verified 2026-08-31 on `_sandbox-client`, and this is the failure mode to check **first** when a
+deploy misbehaves:
+
+- **`amplify.yml` existed in exactly ONE commit (`5a276be`) and was absent from the root of EVERY
+  remote branch — including `_production`.** So Amplify had been building from a **console-stored**
+  build spec, which means the fail-loud `_<mode>` guardrail above was **not actually running**. It
+  was recreated on `_sandbox-client`. Note the recreated spec runs **`npx tsc -b` before
+  `vite build`**, which the previously documented version did not: **a type error now fails the
+  deploy.**
+- **TWO competing `.env` conventions coexist across branches.** The `_<mode>` convention needs
+  `sandbox-client`, `sandbox-dev`, `client-*`, `qa-*`, `qc-*`, `production`, `demo`, `stage`. But
+  `_sandbox-client`, `_production`, `_beta` and `_main` carry an **OLD** set
+  (`.env.alpha` / `.beta` / `.gamma` / `.sprint` / `.test`); only `_stage`, `_sandbox-dev` and the
+  snapshot `_sandbox-client-backup820` carry the new 21-mode set. Dry-running the derivation across
+  all **27** remote `_*` branches, only **`_beta` and `_stage`** would have built. A "reset from
+  prod" is how a branch loses the new set.
+- **The audit — dry-run the guardrail locally before landing the spec.** For every remote `_*`
+  branch: `VITE_MODE="${b#_}"; [ -f ".env.$VITE_MODE" ]`. That tells you exactly which branches
+  would fail, in seconds, without a deploy.
+- Restoration is a verbatim copy, not a rewrite: `git checkout <known-good-ref> -- .env.<mode> …`
+  (19 files restored from `origin/_sandbox-client-backup820`, comments intact). Do **not** overwrite
+  files that already exist (`.env`, `.env.development`, `.env.stage` were left alone). Env-file
+  format is `VITE_API = 'https://...'` — spaces around `=`, single-quoted — and they contain only
+  public base URLs, no secrets.
+- **⚠ Open data issue, needs a human:** on `_sandbox-client`, `.env.stage` points at
+  `https://api.dev.sandbox.togahub.com/v2` (**dev-sandbox**) while the backup has
+  `https://api.stage.togahub.com/v2`. As-is, `_stage` would deploy pointing at dev-sandbox. Also 4
+  orphan old-convention files remain with no matching `_<mode>` branch
+  (`.env.alpha`/`.gamma`/`.sprint`/`.test`; `.env.beta` still has one).
+
+## Deleting a remote branch silently breaks its Amplify deploy trigger
+
+An Amplify branch is **its own resource with its own webhook association** — it is **not** inferred
+from the repo. Deleting the git branch either deletes the Amplify branch resource (when automatic
+branch deletion is enabled) or leaves it with a stale association. Either way **re-creating the git
+branch does NOT reconnect it**: pushes land in GitHub and Amplify ignores them entirely.
+
+- **A missing `amplify.yml` is NOT the cause of a missing trigger** — a build would still start and
+  fall back to the console spec. Don't conflate the two.
+- **Diagnose:** GitHub → *Settings → Webhooks* → the Amplify webhook → **Recent Deliveries**. A
+  delivery with `200` and no Amplify job = the branch is not connected; **no delivery at all** = the
+  webhook is gone. Or `aws amplify list-apps` then `aws amplify list-branches --app-id <id>`.
+- **Fix:** reconnect the branch in the Amplify console **and re-add its domain association** — a
+  deleted branch loses its subdomain mapping, so the build can go **green while the URL still
+  404s**.
+- Amplify also **dedupes by commit SHA**, so a recreated branch pointing at an already-built SHA is
+  **skipped** — push a new commit to force a build.
+
 ## Adding a new environment
 
 1. Create `.env.<mode>` with the public `VITE_API` base URL.
@@ -144,12 +195,45 @@ branch where you pointed the dev server at localhost.
   (the legacy v7 table stack). All three `react-table` v7 packages were **already** declared at
   identical versions on `_sandbox-client` — `_production` was the outlier. Fixed in `92644c8`
   (pushed), verified with a clean vite build (1761 modules).
+- **⚠ The missing-blox-declaration defect RECURS per branch — it is not fixed once.** Verified
+  2026-08-31: `_sandbox-client` **also** had no `@agilant/toga-blox` dependency entry and no lock
+  entry despite ~200 imports, exactly as `_production` had (fixed there in `92644c8`). The symlink
+  is what hides it, so **re-run the audit on every branch you deploy**. Fixed by installing the
+  **exact** pin `1.1.1-sandbox-client.140` (never a caret — some published versions ship an empty
+  `dist`). That install surfaced one more masked peer: **`react-day-picker`** (blox peer `^9.5.1`)
+  was neither declared nor present in the app's own `node_modules`; added at `^9.14.0`. All 19 blox
+  peers are now declared. Installing from the registry also replaced the symlink with a real
+  directory, which independently removed the duplicate-`@tanstack/react-query` root cause (see
+  [local-link-into-a-consumer-app](../../toga-blox/workflows/local-link-into-a-consumer-app.md)).
+  Verified after install: `tsc -b` clean, 44/44 tests, `vite build --mode sandbox-client` clean
+  (1773 modules), exactly one react-query copy.
+- **⚠ Latent and NOT fixed — `framer-motion` peer mismatch.** The app declares `^12.35.0`; blox's
+  peer range is `^11.0.8`; `legacy-peer-deps=true` silenced the warning, so blox installed a
+  **nested framer-motion v11**. framer-motion provides React context (`AnimatePresence`,
+  `MotionConfig`) — i.e. the **same duplicate-instance bug class**, just not throwing today. Fix
+  direction: widen blox's peer to `^11 || ^12`, **or** add `framer-motion` to the app's
+  dedupe/alias list (which forces blox onto v12 — needs testing).
 - **The audit that catches the above — reusable for any blox consumer.** Enumerate the shared lib's
   `peerDependencies` from `node_modules/<pkg>/package.json`, then check each one for a **real
   directory** (not a symlink passthrough) in the *app's* `node_modules`. Do this whenever a repo
   has ever been developed against a linked local checkout.
 
 ## Change history
+- 2026-08-31 — Restored the branch's deploy inputs and recorded three systemic findings.
+  (1) **`amplify.yml` was absent from the root of every remote branch** (it lived in a single commit
+  `5a276be`), so Amplify had been building from a **console-stored spec** and the fail-loud
+  `_<mode>` guardrail was never actually running; recreated it, and the new spec adds `npx tsc -b`
+  before `vite build` so a type error now fails the deploy. (2) **Two competing `.env` conventions
+  coexist across branches** — a dry-run of the derivation across all 27 remote `_*` branches showed
+  only `_beta` and `_stage` would build; restored 19 `.env.<mode>` files verbatim from
+  `origin/_sandbox-client-backup820`, and recorded the local dry-run audit. (3) **Deleting a remote
+  branch silently breaks its Amplify trigger** — the branch resource/webhook association is not
+  inferred from the repo, re-creating the git branch does not reconnect it, the domain association
+  must be re-added (green build, 404 URL), and Amplify dedupes by commit SHA. Also: the
+  missing-`@agilant/toga-blox`-declaration defect **recurred** on `_sandbox-client` (fixed with the
+  exact pin `1.1.1-sandbox-client.140`, plus the masked peer `react-day-picker`), and logged the
+  **latent, unfixed `framer-motion` v11-vs-v12 duplicate-context risk**. Flagged an open data issue:
+  `_sandbox-client`'s `.env.stage` points at dev-sandbox. (apeterson)
 - 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

package/knowledge/INDEX.md

@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **_underscore** (_Underscore) _(framework core)_ — 71 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 58 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 14 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 15 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 5 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -22,7 +22,7 @@
 | [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is **inserted as a brand-new `Users` row** by the PEOPLE importer i | _underscore/Model/Compass/ApprovalDecision.php, worker2/Worker/Client/Compass/ApprovalReassignment.php, worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
-| [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. | dbchanges2/Client_Compass/2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql, dbchanges2/Client_Compass/2026-08-28 - GrantViewOrdersRoleSalesOrdersNavigation.sql, dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, dbchanges2/Client_Compass/2026-02-25 - AgilantUsersViewAccess.sql, dbchanges2/Client_Compass/2026-08-11 - CompassODPViewVendorItemsAccess.sql, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql |
+| [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. | dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, dbchanges2/Client_Compass/2026-02-25 - AgilantUsersViewAccess.sql, dbchanges2/Client_Compass/2026-08-11 - CompassODPViewVendorItemsAccess.sql, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql |
 | [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
 | [Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)](workflows/odp-edi-import-recovery.md) | 1.0 | How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron **3a** created the ODP SalesOrder header, the follow-up item | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json |

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
@@ -17,6 +17,7 @@ files:
   - _underscore/Model/Quad/SalesOrder.php
 related:
   - mr-ma-order-approval-and-status.md
+  - ../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md
   - ../../../2.0/apps/_underscore/features/sales-order-denial-reason.md
   - people-file-user-lifecycle.md
   - stranded-approval-reassignment.md
@@ -342,6 +343,45 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
     [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
   - Real incident: order SA134461 — VIP manager Spyros Gravas, subtotal $926.47 (both auto-approve
     conditions met) still required manual override because the requester had no supervisor.
+- **⚠ The `!$hasManager` branch strands orders in an unrecoverable decided-but-untyped state — the
+  worst of the no-supervisor family.** When the "Order for" contact is changed to a user with **no**
+  `Users.supervisorUserId`, `_Model_Compass_SalesOrder::postPut`'s `!$hasManager` branch
+  (`Model/Compass/SalesOrder.php` ~L1018) PUTs `assignedToUser`, `decidedByUser`, `isApproved`,
+  `approvalDecisionType`, `note` **and** `dtDecision` all to `null` — deliberately wiping an existing
+  VIP auto-approval. A later **manual** approval then sets `isApproved = 1` + `decidedByUserId` but
+  never stamps `approvalDecisionTypeId` (correct — it is not a *system* decision). End state:
+  `isApproved = 1`, `approvalDecisionTypeId = NULL`, and frequently a **stale** "Auto-approved:
+  Manager is VIP and order total <= 5000" note left behind.
+  - **Frontend consequence (the part that makes it unrecoverable):** blox derives `isPreApproved`
+    from `!!stage.ApprovalDecisionTypes.name`, so it is `false`. The approval modal therefore locks
+    the stage's inputs **and hides the Stage Actions block that contains the only "Reset to Pending"
+    control** — no admin action can recover the order. This is why the 2026-08-31 frontend fix gates
+    on `stepOneUndecided` rather than on `isPreApproved` (see
+    [Action-Button Rule Engine](../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md)).
+  - **Diagnostic signature in the order activity log**, in order: `"Manager approval skipped due to
+    VIP logic"` (creation-time VIP auto-approve), then `"Manager assignment cleared: new user has no
+    supervisor"` **and** `"VIP auto-approval removed: new user has no supervisor"` (written **only**
+    by that `!$hasManager` branch), then `"Manager Approved by <admin>"` (the manual approval).
+  - **Prod evidence 2026-08-31** (`Client_Compass`, orders **SA136701 / SA136702**): step-1 decision
+    NULL; step-2 `isApproved = 1`, `approvalDecisionTypeId = NULL`, `decidedByUserId = 152887` (the
+    admin, **not** the assigned manager), assignee `JEFF.KRAUSE@COMPASS-USA.COM` with `c_isVip = 1`,
+    and the VIP auto-approve text still in `note`. **Caveat: for those two specific orders the writer
+    was NOT positively identified** (no log access; prod RDS is unreachable from a laptop). The
+    mechanism above is proven from a **third** order's activity log — treat it as the mechanism, not
+    as confirmed provenance of those two rows.
+  - **Still open (not addressed):** nothing stops **new** orders reaching this state — the
+    `!$hasManager` branch should either re-derive a manager for the new contact or leave a clean
+    *pending* stage instead of a half-cleared one. And once step 1 **is** approved, a decided stage
+    still hides its own "Reset to Pending" control.
+- **Two dead theories — do not re-derive them.** Both were chased against api2's write path
+  (`Component/Api/V2/V2.php` ~L4858-5040) and are false:
+  1. api2 **does** accept a bare numeric FK id on write (it falls through to `$model->$key = $val`),
+     so passing `'approvalDecisionType' => 1` as a scalar through `internalApiRequest` is **not**
+     silently dropped.
+  2. In api2's write path an **unknown** field or a **non-writable** field is a **hard error**
+     (`unknownFields` / `fieldsNotWritable` → an `EZ`/`EV` message, whole request fails), never a
+     silent strip. So a row that saved its other fields **cannot** have had one field quietly
+     discarded by ACL.
 - **Never drop the order requester from notifications on manager reassignment.** If the outgoing
   manager happens to also be the order requester (same email), deleting the old-manager address
   from `SalesOrderEmailAddresses` would silently remove the requester from all order notifications.
@@ -397,6 +437,16 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   approve as manager on his behalf. (Fixed 2026-07-23.)
 
 ## Change history
+- 2026-08-31 — **Root-caused the "decided but untyped" step-2 approvals that no admin can recover**
+  (both tenants, via the shared parent). `_Model_Compass_SalesOrder::postPut`'s `!$hasManager` branch
+  nulls the entire step-2 decision when the "Order for" contact has no `supervisorUserId`; a
+  subsequent manual approval sets `isApproved = 1` without `approvalDecisionTypeId`, so the frontend
+  reads `isPreApproved = false`, locks the stage **and** hides the only "Reset to Pending" control.
+  Recorded the three-note activity-log signature, prod evidence SA136701/SA136702 (with the caveat
+  that the writer of those two rows was not positively identified), the still-open prevention gap,
+  and two **dead** api2 theories (a bare numeric FK id **is** accepted on write; an unknown or
+  non-writable field is a hard error, never a silent strip). Investigation only — no backend change;
+  the frontend mitigation shipped in `toga25-supply`. (apeterson)
 - 2026-08-28 — Recorded that this flow's `buildRejectionNoteHtml()` path is the **only** consumer of
   `ApprovalDecisions.note` anywhere in the platform — no supply or commerce frontend renders the
   denial reason (and Quad reaches it through its **own** `_Model_Quad_ApprovalDecision`, not this

package/knowledge/clients/compass-usa/workflows/granting-navigation-access.md

@@ -6,11 +6,9 @@ project: Database Changes
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: [apeterson, bala]
 files:
-  - dbchanges2/Client_Compass/2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql
-  - dbchanges2/Client_Compass/2026-08-28 - GrantViewOrdersRoleSalesOrdersNavigation.sql
   - dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql
   - dbchanges2/Client_Compass/2026-02-25 - AgilantUsersViewAccess.sql
   - dbchanges2/Client_Compass/2026-08-11 - CompassODPViewVendorItemsAccess.sql
@@ -253,6 +251,15 @@ tenant-wide behavior change and needs its own ticket and sign-off.
   `AclActionPermissions` when a menu item is missing. It is always a `SurfaceOverrides` row.
 
 ## Change history
+- 2026-08-31 — 🚨 **Both migration files this doc describes are GONE.** Verified with
+  `git log --all`: neither `Client_Compass/2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql`
+  nor `Client_Compass/2026-08-28 - GrantViewOrdersRoleSalesOrdersNavigation.sql` was ever committed on
+  any branch, and neither is in the working tree — the 08-27a file was deleted this session at the
+  developer's request (local backup only), and a third untracked file,
+  `2026-08-28a - ViewOrdersRoleReadOnlySurface.sql`, was deleted with it. Removed both from `files:`.
+  **The recipes and the role/element analysis below still stand — the SQL must be rewritten before it
+  can ship.** General lesson: an uncommitted migration is not a deliverable; a doc that cites one is
+  citing something that may not exist tomorrow. (apeterson)
 - 2026-08-28 — Added the **reverse case**: a role with no `SurfaceOverrides` nav row leaves the user
   with zero menu items, which `toga25-supply` renders as a **blank page with no error** and users
   report as *"cannot log in"* (a fresh `Users.dtLastLogin` proves auth succeeded). Identified the

package/knowledge/clients/nychh/INDEX.md

@@ -6,4 +6,4 @@
 | [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, worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql |
 | [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/PurchaseOrderItem.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 |
+| [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-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/profile.md

@@ -16,13 +16,11 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - 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
@@ -68,14 +66,26 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   arrive as sales orders; the 1.0 importer routes them by the `custbody_stocking_order` flag (not the
   dollar amount), bridges the PO, and resolves origin/destination locations. See
   [NYCHH NetSuite → TransferOrders import](./features/netsuite-transfer-order-import.md).
-- **Transfer Orders is an NYCHH-only screen (2026-08-28, local only).** NYCHH is the first — and
+- 🚨 **`Client_Nychh.TransferOrders` HAS production data — 1,927 rows (verified 2026-08-31 on
+  `reader1.client.database.togahub.com`).** The transfer-order *tables and data* have been live in
+  prod for a while (the 1.0 NetSuite importer writes them); only the **2026-08-28 UI vertical**
+  (TableView, Core surfaces, nav override) is new. An earlier version of this profile said transfer
+  orders were "local only … not yet run on sandbox-client or production", and that stale line
+  produced a wrong recommendation this session — that a prod-to-local restore would *wipe* the
+  transfer-orders feature. **Never infer prod state from this repo or from a migration's run
+  status; read prod.** Restoring or overwriting `Client_Nychh` destroys real transfer-order rows.
+- **The Transfer Orders SCREEN is NYCHH-only and new (2026-08-28).** NYCHH is the first — and
   today the only — tenant with a `transfer-orders` TableView (`Client_Nychh/2026-08-28a`, which also
   seeds the ACL chain for record 351 that the Status column silently depends on) and the one
   `SurfaceOverrides` row that reveals the nav item (`2026-08-28b`, client-wide, matching how this
   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. A **Create Transfer Order** modal is started (UI built, data
+  until they opt in. The seven migration files were **committed 2026-08-31** (`dbchanges2` commit
+  `1c3fe2e`, branch `TRUE-80852`, pushed); run order is **`Core/` → `Client/` fan-out →
+  `Client_Nychh/`**, because the client files reference Core record ids and the NYCHH TableView/ACL
+  need the columns the fan-out files add. Run state per environment must be **verified against that
+  environment**, never assumed from the repo. **beta is blocked** because it 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
@@ -122,4 +132,14 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   ship in the same release as that Core file.** NYCHH was the only drifted client (Client_Elite's
   equivalents are correct). See
   [Surface Layer Schema](../../2.0/apps/dbchanges2/features/surface-layer-schema.md).
+  **Where that file actually lives (checked 2026-08-31):** `Client_Nychh/2026-08-24 -
+  FixInventoryGroupingsUnitsTopologyOverrideIds.sql` is committed on branch **`TRUE-81190`** only —
+  it is **not on `_main`**, so shipping `Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql`
+  without merging `TRUE-81190` is the exact break described above.
+- 🚨 **Two NYCHH migrations named in earlier notes were never committed anywhere** (`git log --all`,
+  2026-08-31): `Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql` and
+  `Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql`. Zero commits touch either
+  path on any branch, and neither is in the working tree — so the transfer-order **custom-field
+  write permission** and the **stage status identifier** are, like the ACL layers above, prod/local
+  state with no file behind them. Rewrite them before anyone builds a fresh environment.
 - This profile is a starting point; expand as more NYCHH-specific behavior is captured.

package/package.json

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