toga-ai 1.0.377 → 1.0.378

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

@@ -3,5 +3,5 @@
 | 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/ |
-| [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/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 |
+| [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/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 |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

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-07-17
+updated: 2026-07-20
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -38,6 +38,13 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -167,6 +174,45 @@ to `{}` so Core carries **no** `_status` default. Every client — even Quad, wh
 old default — now declares the full filter config via its own `CONFIG` override. This makes the Core
 seed a true neutral default for the filter button, matching the action-button rule above.
 
+## Display-section visibility — two patterns (marker vs field-driven)
+
+A record-modal **display SECTION**'s own `Surfaces.isVisible` can never be client-overridden (the
+cascade keys on `surfaceElementId`, never a Surface's own `isVisible` — see gotcha). Section
+visibility is therefore always carried by an **element**, in one of two patterns depending on whether
+the section has per-client field content:
+
+- **Marker pattern (whole-section on/off)** — a section with fixed content (invoices / shipments /
+  additional-order-details / admin-notes) carries a single hidden TEXT **`sectionVisibility` marker
+  element** (`config.role='sectionVisibility'`); that element's `isVisible` *is* the section's
+  visibility. A client flips the section by overriding the marker's `IS_VISIBLE`.
+- **Field-driven pattern (per-client field set)** — a section whose fields vary per client (notes)
+  models **each field as a real `FIELD` `SurfaceElement`** (the source of truth for that field's label
+  + visibility). No marker element: the FE **DERIVES** the section's visibility as "visible iff ≥1
+  field element is visible" (see
+  [surface-frontend](../../toga25-supply/features/surface-frontend.md)). This is the third section
+  pattern, alongside the card sections (`cardType` → grid renderer) and the marker toggles.
+
+### Core neutral default + client opt-in (admin-notes & notes, 2026-07-20)
+Both sections follow the Core-neutral-default → client-opt-in rule (the same rule as the action/filter
+buttons above): Core seeds the section **off**, each client opts in via a `SurfaceOverride`.
+
+- **admin-notes (marker pattern).** `Core/2026-07-20a` flips the admin-notes section's
+  `sectionVisibility` marker `isVisible=0`, so the section is **hidden by default**. Resolved
+  **id-agnostically** by `Surfaces.slug='admin-notes'` + `config.role='sectionVisibility'` (never a
+  hardcoded element id). **Compass + Compass Canada** opt the section back on with a client-wide
+  `IS_VISIBLE='1'` override on that same element (`Client_Compass/2026-07-20a`,
+  `Client_CompassCanada/2026-07-20a`); every other client stays hidden.
+- **notes (field-driven pattern).** `Core/2026-07-20b` migrates the two previously-hardcoded FE fields
+  (`reasonForRequest`, `shippingInstructions`) into two `FIELD` `SurfaceElements` under the `notes`
+  surface, both `isVisible=0` in Core (**default = neither field → the section is hidden**). Per-client
+  `IS_VISIBLE` overrides: **Quad → shippingInstructions only** (`Client_Quad/2026-07-20a`); **Compass +
+  Compass Canada → both** (`Client_Compass/2026-07-20b`, `Client_CompassCanada/2026-07-20b`).
+- **A note field's value binding is a nested-array lookup, not a flat column.** Note text lives in
+  `order.salesOrderNotes[]` (each entry has `salesOrderNoteType.slug` + `note`), not a flat order
+  field. Each notes `FIELD` element names its note type in **`config.noteTypeSlug`** (`request` /
+  `shipping`); the FE resolves `salesOrderNotes[].note` by that slug (client-agnostic). Per-client slug
+  variance is handled by a **`CONFIG` override** on the element (REPLACE semantics) — no FE change.
+
 ## ThemeTokens — per-tenant, physically isolated in each client DB
 
 `ThemeTokens` lives **inside each tenant's own database** (`Client_Compass.ThemeTokens`,
@@ -320,6 +366,18 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-20 — Applied the Core-neutral-default → client-opt-in pattern to two SalesOrder display
+  sections. **admin-notes** (marker pattern): `Core/2026-07-20a` hides it by default (marker
+  `isVisible=0`, resolved id-agnostically by `Surfaces.slug`+`config.role='sectionVisibility'`);
+  Compass + Compass Canada opt back in via a client-wide `IS_VISIBLE` override
+  (`Client_Compass`/`Client_CompassCanada/2026-07-20a`). **notes** (new field-driven pattern):
+  `Core/2026-07-20b` migrates the two hardcoded FE note fields into `FIELD` SurfaceElements (both
+  `isVisible=0` = neither by default), with per-client `IS_VISIBLE` overrides — Quad = shipping only
+  (`Client_Quad/2026-07-20a`), Compass + Compass Canada = both (`Client_*/2026-07-20b`). Documented the
+  two display-section visibility patterns (marker for whole-section on/off vs field-driven where the FE
+  derives section visibility from "≥1 field visible") and note-field value binding via
+  `config.noteTypeSlug` into `order.salesOrderNotes[]` (per-client slug variance via a `CONFIG`
+  override). (apeterson)
 - 2026-07-17 — Applied the Core-neutral-default → client-opt-in pattern to the sales-order action &
   filter buttons across Compass, CompassCanada, and Quad (`Client_*/2026-07-17a`+`b`). Cleared the
   Core approvals-filter `_status` default (`Core/2026-07-17h`) so every client declares its own filter

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

@@ -9,6 +9,6 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.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/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.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/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-13
+updated: 2026-07-20
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -16,6 +16,8 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx
+  - toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/surface/actionRegistry.ts
@@ -173,6 +175,31 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   `sectionVisibility` marker element). **Decision (confirmed by the developer this session): KEEP the
   adapter approach — do NOT replace it with a direct `<SurfaceSection>` swap.** The bespoke grid
   renderers and the `TenantFields` seam are the deliberate integration point.
+
+### `displayToggle` sections — marker vs field-driven (the notes section)
+`buildSection`'s `displayToggle` branch handles **two** shapes (mirroring the schema's two
+display-section patterns — see
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)):
+- **Field-carrying section (notes)** — the branch maps every `FIELD`-`renderType` element to a field
+  config via `elementToFieldConfig` (now carrying **`config.noteTypeSlug`**) and **DERIVES** the
+  section's `isVisible` as `fields.some(f => f.isVisible)` — no `sectionVisibility` marker needed. It
+  emits both `isVisible` and the `fields[]` array.
+- **Pure-toggle section (invoices / shipments / additional-order-details / admin-notes)** — no `FIELD`
+  elements, so it falls back to the single `sectionVisibility` marker element's `isVisible`.
+
+**`SalesOrderNotesSection`** consumes the field-driven shape: it renders **only the visible note
+slots** and resolves each value from `order.salesOrderNotes[]` by
+`salesOrderNoteType.slug === field.noteTypeSlug` (note text is a nested-array entry, not a flat order
+column). When no surface `fields` are supplied it falls back to the **legacy flat props**
+(`reasonForRequest` / `shippingInstructions`, flattened by `cleanOrder`) so non-migrated JSON clients
+still render — see the `cleanOrder` slug gotcha below.
+
+**Reusable pattern (field-driven display section):** for a section whose content varies per client,
+model each field as a `FIELD` element (label + visibility source of truth), derive section visibility
+from "≥1 field visible", and bind an array-derived value via element `config` (here `noteTypeSlug`)
+resolved on the FE. This is the presentation counterpart of the schema's field-driven pattern and the
+third section pattern alongside card sections (`cardType` → grid renderer) and marker toggles.
+
 - **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
   in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
   `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
@@ -222,6 +249,14 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   intentionally gated in `getDetailSections`: `shipments` is **permanently hidden** (the view-model
   hardcodes `shipmentsData: []` and `useShipments` is commented out; the section gates on
   `shipmentsData.length > 0`), and `invoices` is data-gated on `invoiceData.length > 0`.
+- **`cleanOrder.ts` flattens notes by the WRONG note-type slugs (latent blank-notes bug).**
+  `cleanOrder` builds the legacy flat `order.reasonForRequest` / `order.shippingInstructions` via
+  `getNoteBySlug(notes, "reasonForRequest")` / `("shippingInstructions")`, but the API's actual
+  `salesOrderNoteType.slug` values are **`request`** / **`shipping`**. So for any client whose notes
+  use the real slugs (e.g. Compass) those flat fields resolve to `""` and the legacy notes render
+  blank. The new field-driven notes path resolves by the element's `config.noteTypeSlug` (the correct
+  slug) so it is unaffected; the flat path only survives as the non-migrated-client fallback in
+  `SalesOrderNotesSection`. Fixing `cleanOrder`'s slugs is the durable follow-up for JSON clients.
 - **The surface `record` shape must match the rule field namespace — wrap as `{ order }`.** Seeded
   Tier-1 rules namespace their field as `order._status`, so `getByPath(record, "order._status")` only
   resolves if the host passes `record={{ order }}`. Passing the bare order object resolves to
@@ -258,6 +293,18 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-20 — Made the SalesOrders `notes` display section **field-driven** per client.
+  `buildSection`'s `displayToggle` branch now handles field-carrying sections: it maps each `FIELD`
+  element to a field config (`elementToFieldConfig` now carries `config.noteTypeSlug`) and **derives**
+  section visibility as "≥1 field visible" — no `sectionVisibility` marker needed (pure-toggle sections
+  invoices/shipments/additional-order-details/admin-notes still fall back to their marker element).
+  `SalesOrderNotesSection` renders only the visible note slots and resolves each value from
+  `order.salesOrderNotes[].note` by `salesOrderNoteType.slug === config.noteTypeSlug`, with a legacy
+  flat-prop fallback for non-migrated JSON clients. Recorded the reusable field-driven-display-section
+  pattern (third section pattern, alongside card sections and marker toggles). Discovered a latent
+  blank-notes bug in `cleanOrder.ts` (flattens by the wrong slugs
+  `reasonForRequest`/`shippingInstructions` vs the API's actual `request`/`shipping`) — the surface
+  resolver reads by the correct slug and bypasses it. (apeterson)
 - 2026-07-13 — Fixed two SalesOrders row-actions bugs: (1) the portal dismiss overlay in
   `SurfaceRowActions.tsx` propagated an outside-click up the React component tree to the row handler
   and opened the record modal — added `e.stopPropagation()` (+ close) on the overlay `onClick`;

package/package.json

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