toga-ai 1.0.778 → 1.0.780

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
-| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, dbchanges2/Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql |
 | [Address Uniqueness Normalization (unit identifier + 5-digit ZIP comparison)](features/address-uniqueness-normalization.md) | When a business rule says *"only one X per physical address"*, comparing address rows field-for-field does **not** work: the same dwelling is spelled many diffe | _underscore/Model/Rate/Entitlement.php |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php |
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, _underscore/Component/Api/Clickup/Clickup.php |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -22,6 +22,7 @@ files:
   - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
   - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
   - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
+  - dbchanges2/Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql
 ---
 
 ## Summary
@@ -97,6 +98,17 @@ Two distinct failure shapes, and the second is a page-killer:
   `undefined`. Code that checks `=== null` will not detect it.
 - **A requested JOINED field with no grant fails the ENTIRE request with `EZ-2`.** One missing grant
   on one joined column therefore blanks every record the page asked for — not just that column.
+- **⚠ An ungranted `uuid` fails the ENTIRE request too — even though you never asked for it.**
+  `uuid` is V2's `IDENTIFIER_FIELD` (`api2 Component/Api/V2/V2.php:13`) and is **force-added to every
+  record read**, so it is always "requested" whether or not it appears in your `fields=` list. If the
+  calling role has no `AclFieldPermissions` grant on that record's `uuid` RecordField, the response is
+  **403 `EZ-2`** naming `"fields": ["uuid"]`. This is the opposite of the first bullet: an ordinary
+  ungranted field is silently dropped, `uuid` is fatal.
+
+  **Rule: grant the `uuid` RecordField alongside every field you actually read.** Seen 2026-09-03 on
+  `/transfer-order-statuses` — the fetch asked only for `slug,name,colorHex` and still 403'd on
+  `uuid`. The error text is self-diagnosing here: an `EZ-2` whose `fields` list contains a field you
+  never sent is this.
 
 **Two practices follow directly:**
 
@@ -652,6 +664,14 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-09-04 — ⚠ Recorded that an **ungranted `uuid` 403s the whole request**, unlike an ordinary
+  ungranted field which is silently dropped: `uuid` is V2's `IDENTIFIER_FIELD`
+  (`api2 Component/Api/V2/V2.php:13`) and is force-added to **every** record read, so a role with no
+  `AclFieldPermissions` row on that record's `uuid` RecordField gets `EZ-2` listing
+  `"fields": ["uuid"]` even when `uuid` was never requested. Hit on `/transfer-order-statuses` while
+  wiring the transfer-order status badge (the fetch asked only for `slug,name,colorHex`). Rule: grant
+  the `uuid` RecordField alongside the fields you read; and an `EZ-2` naming a field you never sent
+  is this. (apeterson)
 - 2026-09-04 — Recorded the **custom-field silent-omission trap** after a production incident (Rate
   AIG): a `c_` field with no `AclCustomFieldPermissions` row for the calling role is **dropped from a
   GET response with HTTP 200** and a correct `totalRecordCount` when `fields=` is not sent — the

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [jcardinal, apeterson, bala]
 files:
   - _underscore/Model/Client/Language.php
@@ -155,6 +155,32 @@ boolean rows; the item-record modal (the first boolean consumer) exposed the gap
 `_underscore`, so it takes effect only once the framework branch is deployed (framework is pulled at
 deploy).
 
+### 🚨 A message key inside `config` JSON is NEVER resolved — copy must ride a `*MessageId` column
+
+`_buildBundle`/`_serializeElement` build `bundle.messages` by scanning **exactly six columns** on
+`SurfaceElements` — `labelMessageId`, `tooltipMessageId`, `placeholderMessageId`,
+`disabledTooltipMessageId`, `trueMessageId`, `falseMessageId` (`Surface.php` ~L600). **`config` is
+passed through untouched and is never scanned for message keys.** A key written into `config`
+therefore ships to the frontend with **no value behind it**, and the screen renders the raw key.
+
+This is a load-bearing constraint on how *any* surface-driven copy is modelled: **one string = one
+`SurfaceElement` message column.** There is no way to attach copy to a nested `config` blob.
+
+**Real case (2026-09-03).** The Columns modal rendered `common.columns.modal.apply` as its Apply
+button label. `Core/2026-08-28b` had put the seven `common.columns.modal.*` keys inside the
+`columnsButton` element's `config.modal` — data that looks right and can never resolve. The chosen
+fix was **not** to teach the resolver to scan `config` (that widens the message-resolution contract
+for every surface); it was to give the modal **its own MODAL Surface** so every string rides a real
+`*MessageId` on its own element and the existing collector resolves it with **zero `_underscore`
+change**. See
+[column-visibility](../../toga25-supply/features/column-visibility.md).
+
+**Diagnostic order.** When the FE shows a raw message key, first check whether the key rides a
+`*MessageId` column — *before* suspecting an unrun seed. The resolved bundle in the API response is
+the proof: if the element is present but `bundle.messages` has no entry for the key, the seed ran and
+the modelling is wrong. (This session's first diagnosis — "the seed hasn't run" — was wrong, and the
+pasted API response is what disproved it.)
+
 ## FIELD elements bound to a RecordField — see the dedicated doc
 
 A `renderType = FIELD` element with a non-null `recordFieldId` gets `Core.RecordFields` metadata and
@@ -755,6 +781,13 @@ full stop. See
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-09-03 — Recorded a **hard constraint on message resolution**: the resolver collects
+  `bundle.messages` from **only** the six `*MessageId` columns on `SurfaceElements`; a message key
+  placed inside `config` JSON is **never** resolved and renders raw on screen. Found when the Columns
+  modal displayed `common.columns.modal.apply`; `Core/2026-08-28b` had seeded those keys into
+  `config.modal`. Fixed in data, not in the framework — the modal became its own MODAL Surface
+  (Core 60) so each string rides a real `*MessageId`. Also recorded the diagnostic order: a raw key
+  means "check the modelling" before "check whether the seed ran". (apeterson)
 - 2026-09-01 — Split the new **FIELD ↔ RecordField binding** capability out into its own doc
   ([surface-field-recordfield-binding](surface-field-recordfield-binding.md)) rather than growing this
   one: for a `renderType=FIELD` element with a `recordFieldId`, `_buildBundle` now folds on

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

@@ -12,7 +12,7 @@
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [/auth/login resolves the client from the email domain, not the Bearer token (cross-client user path)](features/login-cross-client-user-resolution.md) | `POST /v2/auth/login` (email/password user login) can silently swap the target client mid-request. | api2/Component/Api/V2/V2.php, _underscore/String.php |
 | [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |
-| [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ContactEmailAddress.php |
+| [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ContactEmailAddress.php, _underscore/Model/Client/TransferOrderStage.php |
 | [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Query.php |
 | [V2 Request Logging & Where Requests Land (client vs core log DB)](features/request-logging.md) | The V2 engine logs **every inbound request** — success *and* failure, with response code and payload — and routes each log entry to the **client** log or the ** | api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Client/Logs/Api.php, _underscore/Model/Core/Logs/Api.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,11 +6,12 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-26
-owners: ["bala", "mhammontree", "tcox"]
+updated: 2026-09-04
+owners: ["bala", "mhammontree", "tcox", "apeterson"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/ContactEmailAddress.php
+  - _underscore/Model/Client/TransferOrderStage.php
 related:
   - ../architecture.md
   - ../../toga2-supply/features/currency-amount-lines-editor.md
@@ -311,6 +312,33 @@ completely invisible to the UI — see
 Same family as the 201-with-dropped-data case above: **a success status from V2 proves only that the
 parent was written.** Assert child row counts, or write children explicitly.
 
+## ⚠ Not every record can be linked by `uuid` — read `searchableIdentifierFields`
+
+`{ uuid }` is the house convention for a nested FK, and it works so consistently that it reads like a
+platform guarantee. **It is not.** A record is linkable only by the fields flagged as identifiers,
+and a handful of lookup tables have **no `uuid` identifier at all**. Sending `{ uuid }` to one of
+those is a **400 `EV-12`**, not a silent miss.
+
+```
+// WRONG — TransferOrderStages has no uuid identifier
+transferOrderStage: { uuid: "…" }
+// → 400 EV-12, "searchableIdentifierFields": ["id","c_netsuiteInternalTransferOrderStatus"]
+
+// CORRECT
+transferOrderStage: { id: 7 }
+```
+
+- **The error body is self-diagnosing — read `searchableIdentifierFields` first.** It lists exactly
+  what that record accepts. No DB query needed.
+- **When you fall back to `id`, resolve it at request time by a stable natural key (name/slug), never
+  hardcode it.** `id` values differ per tenant database, so a literal that works in one client DB
+  points at a different row (or nothing) in another. The transfer-order create modal looks its
+  opening stage up by name `"Pending"` on each request for exactly this reason.
+- **The other EV-12 flavor is different.** `searchableIdentifierFields: ["id"]` on a nested FK
+  resolved *through* a custom field means a `c_` field is missing `isIdentifier = 1` — that is a
+  metadata bug to fix (see above), whereas "this record genuinely has no `uuid`" is a payload shape
+  to accept.
+
 ## Gotcha
 
 - **Nested write with only a non-identifier field silently creates duplicates.** This is a
@@ -322,6 +350,14 @@ parent was written.** Assert child row counts, or write children explicitly.
 
 ## Change history
 
+- 2026-09-04 — ⚠ Recorded that **`{ uuid }` is a convention, not a guarantee**: some lookup records
+  (e.g. `TransferOrderStages`) have **no `uuid` identifier**, so a nested `{ uuid }` is a hard 400
+  `EV-12` naming `searchableIdentifierFields: ["id","c_netsuiteInternalTransferOrderStatus"]`. Read
+  that list first — it is self-diagnosing — and when falling back to `{ id }`, resolve the id at
+  request time from a stable natural key (name/slug), because ids differ per tenant DB. Distinguished
+  this from the existing `searchableIdentifierFields: ["id"]` flavor, which is a missing
+  `isIdentifier` on a `c_` field. Found building the transfer-order create POST. (apeterson)
+
 - 2026-08-26 — Added: **the UPDATE path sets status 200 unconditionally after its children loop**, so
   a nested `PUT` reports success even when a child write failed (unique-key rejection, ACL denial).
   Any parent-with-children editor that needs to know whether the children landed must write them

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [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/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.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 | dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, 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 |
+| [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 | dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, 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, dbchanges2/Core/2026-09-03c - ColumnsModalSurfaceSeed.sql, dbchanges2/Core/2026-09-03d - ColumnsModalRetireConfigModal.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, _underscore/Model/Client/RecordFieldSetting.php, _underscore/Model/Client/ClientRecordFieldSetting.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, dbchanges2/Client/2026-08-13a - UserNavPreferencesClientTable.sql, dbchanges2/Client/2026-08-13c - PersonaNavVisibilityClientTable.sql |

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

@@ -278,6 +278,17 @@ concluding a migration is production-safe.
   **`(id, uuid, dtCreated, messageKey, name, defaultValue)`** — a guess of `slug` / `message`
   (inferred from a sibling's values row) died on `Unknown column 'slug'`. When in doubt,
   `SHOW COLUMNS FROM <Table>` costs one round-trip.
+- **⚠ Rewriting a `VALUES` seed as `INSERT … SELECT` silently FLATTENS per-row columns.** The rewrite
+  is the normal way to add a `NOT EXISTS` guard, and it is easy to carry one row's value into the
+  constant list for every row. Caught 2026-09-03: converting a `Core.SurfaceElements` seed hardcoded
+  `'NEUTRAL'` as the `variant` for all 11 elements, losing the `PRIMARY` / `SECONDARY` ones. Nothing
+  errors — the enum accepts it. **Diff the rewritten file column-by-column against the original
+  `VALUES` rows before running it**, and treat any column that differed between rows as suspect.
+- **⚠ A scalar sub-select for a foreign key writes `NULL` when it misses — it does not fail.**
+  `(SELECT id FROM Core.Messages WHERE messageKey = '…')` returns `NULL` if the key was never seeded,
+  and a nullable FK column takes it, leaving a structurally broken row that looks inserted. Prefer a
+  `JOIN` (so a missing lookup inserts **no row** at all) or add the lookup to the guard's
+  `WHERE EXISTS`.
 - **`Core.RecordFields` has NO `sql` column.** A calculated field's SQL is **not** stored in
   metadata — it lives in the `_underscore` model as a `FIELD_SQL` static method. Do not go looking
   for a migration to change a calculated field's expression; there is none. See
@@ -288,7 +299,11 @@ concluding a migration is production-safe.
   `SEQ_IN_INDEX = 1`**, not on `INDEX_NAME` — an existing index under a different name goes
   undetected by a name-based guard and you add a duplicate. Found while sizing (and then dropping)
   the Compass `Users` search indexes. (ajean)
-
+- 2026-09-03 — Two silent-failure traps found self-auditing a `Core.SurfaceElements` seed against the
+  team rules: (1) rewriting a `VALUES` seed into `INSERT … SELECT` to add the `NOT EXISTS` guard
+  **flattened** the per-row `variant` to a constant `'NEUTRAL'`, dropping `PRIMARY`/`SECONDARY` with
+  no error; (2) a scalar sub-select used for a message FK writes `NULL` rather than failing when the
+  key is missing. Both leave a row that looks inserted and is wrong. (apeterson)
 - 2026-09-01 — Added the **fan-out rollback rule**: a `Client/` grant migration that fans out across
   every tenant must use **hardcoded v4 uuid literals**, not the generator, so its rollback
   (`DELETE … WHERE uuid IN (…)`) can only touch rows that file created. A natural-key rollback on

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

@@ -101,10 +101,13 @@ files:
   - dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql
   - dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql
   - dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql
+  - dbchanges2/Core/2026-09-03c - ColumnsModalSurfaceSeed.sql
+  - dbchanges2/Core/2026-09-03d - ColumnsModalRetireConfigModal.sql
 related:
   - ../../_underscore/features/surface-resolver.md
   - ../../_underscore/features/sales-order-denial-reason.md
   - ../../toga25-supply/features/transfer-orders-page.md
+  - ../../toga25-supply/features/column-visibility.md
 ---
 
 ## What it is
@@ -1292,7 +1295,64 @@ before your own run — that handoff is a snapshot, and the migrations that cons
 uncommitted at the time. See
 [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 
+## A MODAL that needs surface-driven copy becomes its OWN Surface (`columns-modal`, Core 60, 2026-09-03)
+
+**Rule: never park copy in `config` JSON.** The resolver collects `bundle.messages` from **only** the
+six `*MessageId` columns on `SurfaceElements`; `config` is passed through untouched and is never
+scanned. A message key seeded into `config` therefore has no value behind it and the screen renders
+the raw key. `Core/2026-08-28b` had put the seven `common.columns.modal.*` keys inside the
+`columnsButton` element's `config.modal` — data that looks right and can never resolve. See
+[surface-resolver](../../_underscore/features/surface-resolver.md).
+
+The fix is a **data** fix, not a framework fix: `Core/2026-09-03c - ColumnsModalSurfaceSeed.sql`
+creates a shared `columns-modal` MODAL surface where **every string rides its own element's
+`labelMessageId`**, which the existing collector already resolves.
+
+- **Surface 60** `columns-modal`; **Messages 293–298**; **SurfaceElements 222–232** (11 elements,
+  `config.role` = `shownSection`, `hideAll`, `hiddenSection`, `showAll`, `reorder`, `pinToggle`,
+  `visibilityToggle`, `reset`, `cancel`, `apply`, `close`).
+- **Elements are matched by `config.role`** — `SurfaceElements` has no `slug` column and the bundle
+  exposes only a uuid as `key`. Same convention as `filterButton` / `columnsButton`.
+- **Element visibility gates CAPABILITY, not just chrome.** `isVisible = 0` on `pinToggle` removes
+  pinning; on `reorder` removes drag-to-reorder. A tenant switches a feature off from data — the same
+  marker-element idea as the Talos feature switch above, applied inside a shared component.
+
+### Split the seed from the cleanup so the rollout is order-independent
+
+Retiring the dead `config.modal` is a **second** file, `Core/2026-09-03d -
+ColumnsModalRetireConfigModal.sql`, which must run **only after toga25-supply is deployed**. With the
+two split, either order is safe: seed-then-deploy leaves a harmless unused `config`, and
+deploy-then-seed is the normal path. Putting both in one file would make the migration a
+deploy-blocker.
+
+> ⚠ Neither file has been run on **any** environment yet (as of 2026-09-03).
+
+### Id block consumed — and PROD did not match sandbox
+
+The first id choice **collided on production**: `Messages` 289–294 had four already taken
+(`MAX(id)` = 292) and `Surfaces` **59 was taken**. Renumbered after querying the **production Core
+reader**. Sandbox Core differed substantially from prod — surface 59 was free on prod but taken on
+sandbox, and the `common.columns.modal.*` keys sit at **different ids per environment**.
+
+This is the third confirmation of the rule above: verify a reserved block is free on **every**
+environment and take the **highest** `MAX(id)+1`, never the one in front of you, and never the repo.
+
+**Handoff published (verify before your own run):** next `Core.Surfaces.id` = **61**, next
+`Core.SurfaceElements.id` = **233**, next `Core.Messages.id` = **299**. Both consuming files were
+still unrun at the time, so this is a reservation, not a deployed state.
+
 ## Change history
+- 2026-09-03 — Recorded the rule that **a modal needing surface-driven copy becomes its own Surface**:
+  the resolver reads messages only from `*MessageId` columns and never from `config`, so
+  `Core/2026-08-28b`'s `config.modal` keys could never resolve and the Columns modal rendered raw
+  keys. `Core/2026-09-03c` seeds a shared `columns-modal` MODAL surface (**60**, Messages **293–298**,
+  SurfaceElements **222–232**) with one message column per string; elements are matched by
+  `config.role`, and `isVisible = 0` on `pinToggle` / `reorder` gates those **capabilities** per
+  tenant. Cleanup of the dead `config.modal` is deliberately a separate file (`Core/2026-09-03d`) that
+  runs only after the FE deploy, so the rollout is safe in either order. The first id block collided
+  on **production** (Messages `MAX(id)` = 292, Surfaces 59 taken) while sandbox looked free — third
+  confirmation to verify a block on every environment. Handoff: next Surfaces = **61**,
+  SurfaceElements = **233**, Messages = **299** (both files still unrun everywhere). (apeterson)
 - 2026-09-03 — Flagged that the Compass / Compass Canada stacked-Total `CONFIG` override must **not**
   gain a `"suffix":"+"`: blox renders a field `suffix` unconditionally while the stacked lease line
   auto-hides on null/0, so a seeded `+` dangles on non-lease orders. The joiner is conditional FE code

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: [apeterson]
 files:
   - api2/Config/production.ini
@@ -65,6 +65,20 @@ setpw() {
 `MYSQL_PWD` keeps the password out of `ps` and history the same way a defaults file does — use it
 when the client rejects `--defaults-extra-file` (some builds do).
 
+**Check the password's line SHAPE without ever seeing the value.** Mask every character that is not
+a space, tab, `;`, or `"` — you learn whether the value is quote-wrapped and whether an inline `;`
+comment is in play, and the secret never reaches your screen or scrollback:
+
+```bash
+awk -v S=database '$0=="["S"]"{f=1;next} /^\[/{f=0} f && /^password/{
+  k=$0; sub(/=.*/,"=",k); v=$0; sub(/^[^=]*=/,"",v); gsub(/[^ \t;"]/,"x",v);
+  print "[" k v "]"; exit}' Config/production.ini
+```
+
+On `production.ini` `[database]` this printed `[password = "xxxxxxxx"]` (checked 2026-09-04): the
+double-quote wrap is real, and there is **no inline `;` comment** on password lines — so `setpw`
+above, which strips quotes only, is correct as written and needs no comment handling.
+
 **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:
 
@@ -93,10 +107,25 @@ Delete the file when you are done.
 
 ## Resetting a shared environment from production (dump → drop → reload)
 
-Used 2026-09-03 to bring sandbox-client's stale `Client_Nychh` TableViews back in line with prod.
-The developer runs every one of these; do not execute them for them.
-
-1. **Dump each source database**, one file each — prod `Core` from
+Used 2026-09-03 to bring sandbox-client's stale `Client_Nychh` TableViews back in line with prod,
+and again 2026-09-04 (`Core` + `Client_Nychh`). The developer runs every one of these; do not
+execute them for them.
+
+1. 🚨 **Inventory what the reset will DESTROY — before you drop anything.** A shared non-prod
+   environment is normally *ahead* of prod, because that is where changes get tried first, so a
+   prod→sandbox reload silently rolls that lead back. List every `dbchanges2` file dated after the
+   last prod release, plus anything parked in `git stash`, and decide which ones must be re-run.
+   Candidates from the 2026-09-04 sandbox-client reset, all *potentially* sandbox-only:
+   - `Core/` — 2026-09-01a, -01c, -01d, -02a, -02b, -03a, -03b, -03c, -03d
+   - `Client/` — 2026-09-01b, -01c, -02a
+   - `Client_Nychh/` — 2026-09-02a, -03a, -03b
+   - `dbchanges2` `stash@{0}` ("TO qty fulfilled core seed"), which is applied nowhere
+
+   **Verify every candidate against the environment — never assume the list.** After this reset
+   sandbox read `Core.Surfaces` = 54, which means some of those Core surface files were **already in
+   prod** and must not be re-run. The repo records intent, not deployed state — see
+   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
+2. **Dump each source database**, one file each — prod `Core` from
    `reader1.core.database.togahub.com`, prod tenant from `reader1.client.database.togahub.com`:
    ```
    mysqldump --single-transaction --quick --routines --triggers --events \
@@ -104,14 +133,17 @@ The developer runs every one of these; do not execute them for them.
    ```
    `--set-gtid-purged=OFF` because RDS has GTID on; `--no-tablespaces` because the `admin` user
    lacks `PROCESS` (otherwise **error 1227**).
-2. 🚨 **`tail -1` every dump file and confirm it ends with `-- Dump completed` BEFORE you drop
+3. 🚨 **`tail -1` every dump file and confirm it ends with `-- Dump completed` BEFORE you drop
    anything.** A truncated dump loads without complaining. DNS dropped mid-session on a host that
    had resolved seconds earlier (`ERROR 2005 Unknown MySQL server host`) — the dump just stops.
-3. **Prove which environment each connection actually reached.** Better than `@@hostname`: check the
+4. **Prove which environment each connection actually reached.** Better than `@@hostname`: check the
    resolved IP — production resolves into **`10.201.x`**, sandbox into **`10.200.x`**.
-4. **Drop + create the target schema, then pipe the dump in.**
-5. **Verify with a row count known to differ** (step 1 of the procedure above), against the schema
-   you intended to copy.
+5. **Drop + create the target schema, then pipe the dump in.**
+6. **Verify with a row count known to differ** (step 1 of *before you trust ANY tenant dump*,
+   above), against the schema you intended to copy.
+7. **Re-run the step-1 migrations that prod did not already have, in `Core/` → `Client/` fan-out →
+   `Client_<Tenant>/` order.** Client files reference Core record ids, and the client work needs the
+   columns the `Client/` fan-out adds — any other order fails or half-applies.
 
 ### ⚠ Which `mysql` / `mysqldump` binary you are running is load-bearing
 
@@ -120,10 +152,23 @@ The developer runs every one of these; do not execute them for them.
   `xamppfiles/bin/mysqldump` is **MariaDB 10.4** (rejects the flag);
   `xamppfiles/mysql/bin/mysqldump` is **MySQL 8.0.44** (correct). Run `mysqldump --version` before
   you trust it.
-- **A shell alias can hijack a remote connection.** XAMPP's `mysql` alias hardcodes
-  `-uroot -pmysql --socket=…`, so a command you wrote for a remote host silently talks to localhost.
-  Call the client by **full path** for anything remote — and remember an exact match with your local
-  DB is evidence of a bad restore, not a good one (see the gotcha below).
+- 🚨 **A shell alias hijacks a remote connection — and the error names the wrong problem.** On an
+  XAMPP machine `~/.zshrc:31` defines
+  `alias mysql='/Applications/XAMPP/xamppfiles/mysql/bin/mysql -u root -p<pw> --socket=…'`. A later
+  `-u admin` on the command line wins for the **user**, but the alias's `-p<pw>` **overrides
+  `MYSQL_PWD`** — so every `mysql -h <remote-host> -u admin …` dies with
+  `ERROR 1045 (28000): Access denied for user 'admin'@'<your ip>' (using password: YES)`, *against
+  the correct remote host*. That reads as a rotated credential, a missing grant, a VPN problem, or
+  the double-quote trap above, and it is none of them. (The same alias can also silently talk to
+  localhost when its `--socket` wins — two symptoms, one cause.)
+  - **The tell: `mysqldump` to the SAME host with the SAME `MYSQL_PWD` succeeds while `mysql`
+    1045s.** Only `mysql` is aliased, not `mysqldump`. "Dump works, `mysql` denied" identifies the
+    alias immediately — check that before you go near the password extractor or the ini quoting.
+  - **Fix:** call the binary by full path
+    (`MYSQL=/Applications/XAMPP/xamppfiles/mysql/bin/mysql`). `\mysql` or `command mysql` also skip
+    alias expansion.
+  - An exact match with your local DB is evidence of a bad restore, not of a good one (see the
+    gotcha below).
 
 ## Gotchas
 
@@ -137,6 +182,12 @@ The developer runs every one of these; do not execute them for them.
   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 reference counts written down here go stale too.** After the 2026-09-04 reset,
+    sandbox-client read `Core.Surfaces` = **54** and `Client_Nychh.TransferOrders` = **1,932**,
+    against the prod figures previously recorded here — 53 (2026-09-03) and 1,927 (2026-08-31).
+    Prod itself moved on. Restored counts landing slightly **above** an older recorded prod number
+    is the expected pattern, not evidence of a bad restore. Re-read the count from the source at
+    reset time instead of comparing to a number in this doc.
 - 🚨 **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
@@ -157,6 +208,17 @@ The developer runs every one of these; do not execute them for them.
   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
 
 ## Change history
+- 2026-09-04 — Second sandbox-client reset (`Core` + `Client_Nychh`) from prod; the procedure held,
+  three gaps closed. Added a mandatory **step 1 — inventory what the reset will destroy** (a shared
+  non-prod environment is normally ahead of prod, so the reload rolls that lead back), with the
+  2026-09-04 candidate file list and the unapplied stash, plus a **step 7** to re-run them in
+  `Core/` → `Client/` → `Client_<Tenant>/` order. Sharpened the shell-alias bullet: the real symptom
+  is **`ERROR 1045` against the CORRECT remote host** (the alias's `-p<pw>` beats `MYSQL_PWD`), not a
+  silent localhost connection — and the tell is that `mysqldump` works while `mysql` is denied,
+  because only `mysql` is aliased. Added a value-safe way to inspect an ini password's line shape
+  (confirms the double-quote wrap and that there is no inline `;` comment, so `setpw` needs no
+  change). Refreshed the expected-drift numbers and noted that recorded reference counts age.
+  (apeterson)
 - 2026-09-03 — Added the **reset-a-shared-environment-from-production** procedure (the `mysqldump`
   flag set, `--set-gtid-purged=OFF` for RDS GTID, `--no-tablespaces` for the missing `PROCESS`
   grant, the mandatory `tail -1` "`-- Dump completed`" check because a truncated dump loads

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

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-03
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/components/BaseButton
@@ -135,6 +135,28 @@ declares, on class names `getStickyClass` never emits. Dead rules like this look
 someone greps for the divider. Both were deleted 2026-08-31; grep the emitting code before trusting a
 CSS rule, and check the token it names actually exists in a host theme.
 
+### 6. Button HEIGHT is a literal with no token — a toolbar cannot be sized from the host theme
+
+Defect 4 is about swapping variants; this is the shape of the same problem for a consumer who never
+swaps anything. Measured 2026-09-03 in
+`dist/components/BaseButton/BaseButton.module.css`:
+
+- `.secondaryBtnAction` hard-codes **`height: 26px`** — **no `var(--…)`, so no host token can reach
+  it**.
+- `.primaryBtn` declares **no height at all** (computes to ~25px).
+- `font-size` **is** tokened (14px default).
+
+**Consumer symptom.** One page toolbar renders its buttons at three different heights, and the
+developer cannot fix it from `themeConfig.json` — the number they need to change is not exposed.
+Nothing in the theme layer hints that geometry is off-limits, so the time is lost hunting the app's
+own CSS.
+
+**Fix direction.** Same as defect 5: convert both to `var(--baseButton-height, <existing literal>)`
+(and give `.primaryBtn` the same base height), which is non-breaking because the fallback preserves
+today's look. Until then a consumer must own the chrome: `toga25-supply` built its own
+`ToolbarButton` rather than retheme tokens shared by ~all buttons in the app — see
+[toolbar button chrome](../../toga25-supply/features/toolbar-button-chrome.md).
+
 ## Already-known authoring items (carried over from §22)
 
 These are long-standing and were previously recorded only as consumer-side advice:
@@ -168,6 +190,12 @@ These are long-standing and were previously recorded only as consumer-side advic
   time**, with no PR. Sequence auth fixes deliberately.
 
 ## Change history
+- 2026-09-03 — Added styling defect **6: button height is a literal with no token**.
+  `.secondaryBtnAction` hard-codes `height: 26px` and `.primaryBtn` sets no height at all, so a
+  consumer cannot size a toolbar from the host theme and the cause is invisible from the theme layer.
+  Found building toga25-supply's page toolbar (three buttons, three heights); compensated by an
+  app-owned `ToolbarButton`, not by retheming shared tokens. Fix direction is defect 5's:
+  `var(--baseButton-height, <literal>)`, non-breaking via the fallback. (apeterson)
 - 2026-08-31 — Added styling defect **5: hardcoded visual values in the shared stylesheets cannot be
   removed by a consumer** — a literal has no host-token escape hatch. Worked example: the `supply`
   table card shadow, which a toga25-supply design review needed gone; converted to

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -8,7 +8,7 @@
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. | toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/api/CartApi.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
-| [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP | toga2-commerce/src/App.tsx, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |
+| [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP | toga2-commerce/src/App.tsx, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/api/axiosInstance.ts, toga2-commerce/src/hooks/useAuthenticationFlow.ts, toga2-commerce/src/components/NavIcons/NavIconList.tsx, toga2-commerce/src/pages/BundleView/hooks/useBundleQueryData.ts, toga2-commerce/src/pages/Home/viewModel/useHomeViewModel.ts, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |
 | [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one | src/pages/Filter/api/FilterApi.ts, src/pages/Filter/viewModel/useFilterViewModel.ts, api2/Component/Api/V2/V2.php, toga2-supply/src/pages/Items/api/itemsApi.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/contexts/helpers/getLoginSettings.ts, src/pages/Account/viewModel/useAccountViewModel.ts, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json, src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HEADERFIELDS.json, src/components/AuthLayout/AuthLayout.tsx |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |