toga-ai 1.0.747 → 1.0.749

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

@@ -11,7 +11,7 @@
 | [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | `src/templates/PrimaryTable/` is the **production, wired-up table** built on the [Table component](table.md). | toga-blox/src/components/Table/themeConfig/toga.module.css, toga25-supply/src/themeConfig.json, toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx, toga-blox/src/templates/PrimaryTable/types.ts |
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |
-| [Talos AI-Assistant Component (launcher + docked/drawer chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a chat panel (`TalosPanel`) tha | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/Talos/TalosPanel.test.tsx, toga-blox/src/components/index.ts, toga-blox/src/components/Talos/README.md |
+| [Talos AI-Assistant Component (launcher + docked/drawer chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a chat panel (`TalosPanel`) tha | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/Talos/TalosPanel.test.tsx, toga-blox/src/components/index.ts, toga-blox/src/components/Talos/README.md, toga-blox/src/components/TableRecordModal/TableRecordModal.tsx |
 | [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |
 | [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml |

package/knowledge/2.0/apps/toga-blox/features/table-record-modal.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-09-02
 owners: [apeterson]
 files:
   - toga-blox/src/components/TableRecordModal/TableRecordModal.tsx
@@ -15,6 +15,8 @@ files:
 related:
   - ../architecture.md
   - table.md
+  - talos-assistant.md
+  - ../../toga25-supply/features/talos-integration.md
 ---
 
 ## Summary
@@ -58,6 +60,29 @@ it opens the modal with `isOpen={!!selectedRow}` and renders the record inside `
 (often using the same `tableViewFields` metadata to format fields). `utils/resolveModalType.tsx`
 and `types.ts` are present but **empty/reserved** for a future field-type→renderer mapping.
 
+## `data-blox-modal-open` — the root-element marker (2026-09-02)
+
+While open, `TableRecordModal` sets **`data-blox-modal-open` on `document.documentElement`**. Other
+blox CSS reacts to it — today the Talos launcher dims under `:root[data-blox-modal-open]` (see
+[Talos assistant](talos-assistant.md)).
+
+**Why an attribute on the root element and not a prop or context.** The things that must react to
+"a modal is open" render **outside this component's subtree** — the Talos launcher lives in the app
+**header**. No shared React state reaches it. Threading a prop down would have touched **every
+modal layout in the consuming app**. This is the same boundary-crossing trick as the existing
+`--talos-dock-width` custom property.
+
+**It is a COUNTER, not a boolean.** Modals stack — a record modal can open a create modal — and the
+marker must **survive the inner one closing**. So:
+
+- Each instance holds a **`holdsModalMarker` ref**, so a re-render cannot double-count and a close
+  cannot decrement twice.
+- The marker is cleared at **three** points: the open→false transition's **animation end**, an
+  **unmount** safety net, and the **count reaching 0**.
+
+Anything else that reads the marker gets stacking correctness for free. (Note this fixes stacking
+for the *marker* only — the body-overflow gotcha below is unchanged.)
+
 ## Gotchas
 
 - **No portal** — renders inline in the React tree; a parent `overflow: hidden` can clip it.
@@ -66,4 +91,12 @@ and `types.ts` are present but **empty/reserved** for a future field-type→rend
 - CSS-variable defaults are hardcoded fallbacks; set vars on the DOM before mount to change sizes.
 
 ## Change history
+- 2026-09-02 — Added **`data-blox-modal-open` on `document.documentElement`** while a modal is open,
+  so chrome rendered **outside** the modal subtree can react (first consumer: the Talos launcher dims
+  under `:root[data-blox-modal-open]`). Chosen over a prop/context because the launcher lives in the
+  app **header** — no shared React state reaches it, and threading a prop would touch every modal
+  layout in the host. It is a **counter, not a boolean**, because modals stack and the marker must
+  survive the inner one closing; each instance holds a `holdsModalMarker` ref so a re-render cannot
+  double-count and a close cannot decrement twice, and the marker clears at three points (open→false
+  animation end, unmount safety net, count reaching 0). (apeterson)
 - 2026-06-23 — Documented TableRecordModal as a generic modal shell: positions, render-prop children, body-scroll lock, and consumer-owned field rendering / a11y (apeterson).

package/knowledge/2.0/apps/toga-blox/features/talos-assistant.md

@@ -21,7 +21,9 @@ files:
   - toga-blox/src/components/Talos/TalosPanel.test.tsx
   - toga-blox/src/components/index.ts
   - toga-blox/src/components/Talos/README.md
+  - toga-blox/src/components/TableRecordModal/TableRecordModal.tsx
 related:
+  - table-record-modal.md
   - ../architecture.md
   - ../workflows/dynamic-publish-pipeline.md
   - ../workflows/local-link-into-a-consumer-app.md
@@ -254,9 +256,42 @@ threadsStatus?: "loading" | "error" | "ready";
 `DEFAULT_SUGGESTIONS` — four hardcoded **TOGa Supply** questions — was **removed**. Tenant
 business copy must not sit inside a library five apps consume: any host that mounted the panel
 silently inherited Supply's prompts. `suggestions` now defaults to an **empty module-level
-constant**, and the host supplies the chips (supply reads them from the surface layer — see
+constant**, and the host supplies the chips (supply reads them from the surface layer as **one
+authored, ordered set per tenant** — see
 [Talos integration](../../toga25-supply/features/talos-integration.md)).
 
+### The launcher is DISABLED under an open modal — and the cause was NOT z-index (2026-09-02)
+
+The launcher stayed bright and looked clickable while a record modal was open. The obvious diagnosis
+(and the developer's first guess) was z-index. **It was wrong.** Checked, not assumed:
+
+- `.launcher` has **no `z-index`** at all.
+- blox `.header` has **no `z-index` and no `position`**; supply's `.headerActions` has neither.
+- The modal `.backdrop` is `position: fixed; z-index: 40`.
+
+So the launcher was **already painted under the backdrop and its clicks were already being
+swallowed by it.** The real cause is purely visual: `.backdrop-right` / `.backdrop-left` is only
+`rgba(0, 0, 0, 0.2)`, and a 20% black wash over a **white** button still reads as active next to
+dimmed header chrome.
+
+**Fix — a real disabled state, not a z-index change.** `TableRecordModal` sets
+**`data-blox-modal-open` on `document.documentElement`**, and `Talos.module.css` dims the launcher
+under `:root[data-blox-modal-open]`: `opacity: .5`, `filter: grayscale(1)`,
+`pointer-events: none`, plus **stopping the `.launcher::before` orbit animation** (a spinning ring
+on a greyed-out button still reads as live). Marker mechanics and why it is a **counter**:
+[TableRecordModal](table-record-modal.md).
+
+This applies to **every** `TableRecordModal` in a host app automatically.
+
+🚨 **Known gap, left unfixed.** The launcher is still **keyboard-reachable** behind a modal —
+`pointer-events: none` stops the **mouse only**. Supply's header takes `inert` for the side nav but
+not for modals, and closing that is a **host** change affecting all header controls, so it was
+flagged to the developer rather than patched here.
+
+**Reusable lesson:** before reaching for z-index, read the actual computed stack. "Looks clickable"
+and "is clickable" are different bugs, and a translucent scrim is a *contrast* problem, not a
+*stacking* one.
+
 ### Tests (first ever for this component)
 
 `TalosPanel.test.tsx` — **31 Vitest + RTL Talos tests** as of 2026-09-02 (8 at inception), all
@@ -324,6 +359,20 @@ Rollup *"failed to resolve import"* for a component they never referenced). blox
   currently consumes it via a local symlink.
 
 ## Change history
+- 2026-09-02 — **FIXED the launcher staying bright and clickable-looking under an open record
+  modal — and the cause was NOT z-index.** `.launcher` has no `z-index`, blox `.header` has no
+  `z-index`/`position`, and the modal `.backdrop` is `fixed; z-index: 40`, so the launcher was
+  **already** behind the backdrop with its clicks **already** swallowed. The real cause was contrast:
+  `.backdrop-right`/`-left` is only `rgba(0,0,0,0.2)` and a 20% wash over a white button still reads
+  as active. Fix is a real disabled state — `TableRecordModal` sets **`data-blox-modal-open` on
+  `document.documentElement`** (a **counter**, since modals stack) and `Talos.module.css` applies
+  `opacity: .5` / `grayscale(1)` / `pointer-events: none` and **stops the `.launcher::before` orbit
+  animation** under `:root[data-blox-modal-open]`. A root attribute rather than a prop because the
+  launcher renders in the host **header**, outside the modal subtree — the same trick as
+  `--talos-dock-width`. Applies to every `TableRecordModal` automatically. **Known gap flagged, not
+  fixed:** the launcher is still **keyboard**-reachable behind a modal; `pointer-events: none` stops
+  the mouse only, and adding `inert` is a host-header change. Suite at **31 Talos + TableRecordModal
+  tests**; blox `dist/` rebuilt. (apeterson)
 - 2026-09-02 — **FIXED the `renderMessages` slot silently killing the in-flight loading UI**: the
   bubble is synthesized from `isStreaming`/`progress` into the panel's internal `msgs` array, and the
   host-render branch replaced that whole array, so a run showed **no feedback between submit and

package/knowledge/clients/nychh/INDEX.md

@@ -5,7 +5,7 @@
 | [NYCHH inventory-adjustment → item-fulfillment linking (direct FK columns, REST)](features/netsuite-inventory-adjustment-fulfillment-link.md) | 1.0 | For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item Fulfillment** it corrects, on the multi-select body custom field | library/app/api/toga2.php, library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php |
 | [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 Talos AI Assistant Enablement (the only granted tenant)](features/talos-assistant-enablement.md) | 2.0 | **NYCHH is the only tenant granted the Talos AI assistant in TOGa 2.5 Supply.** The feature is seeded **OFF in Core for every client** and turned on per tenant | dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, toga25-supply/src/hooks/useTalosSurface.ts, toga25-supply/src/providers/TalosStreamProvider.tsx, toga25-supply/db-migrations/PLAYBOOK.md |
+| [NYCHH Talos AI Assistant Enablement (the only granted tenant)](features/talos-assistant-enablement.md) | 2.0 | **NYCHH is the only tenant granted the Talos AI assistant in TOGa 2.5 Supply, and it AUTHORS ITS OWN suggestion questions.** The feature is seeded **OFF in Core | dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, toga25-supply/src/hooks/useTalosSurface.ts, toga25-supply/src/hooks/useTalosSurface.test.ts, toga25-supply/src/providers/TalosStreamProvider.tsx, toga25-supply/db-migrations/PLAYBOOK.md |
 | [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, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, _underscore/Model/Client/PurchaseOrderItem.php |
 | [NYCHH TransferOrder → NetSuite push (location roles, interceptor row 312, metadata state)](features/transfer-order-netsuite-push.md) | 2.0 | NYCHH is the **first and only** client on the outbound transfer-order push. | _underscore/Model/Client/TransferOrder.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.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-09-02a - TransferOrderNetsuitePushInterceptor.sql, dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql, 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, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql |

package/knowledge/clients/nychh/features/talos-assistant-enablement.md

@@ -12,6 +12,7 @@ files:
   - dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql
   - dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql
   - toga25-supply/src/hooks/useTalosSurface.ts
+  - toga25-supply/src/hooks/useTalosSurface.test.ts
   - toga25-supply/src/providers/TalosStreamProvider.tsx
   - toga25-supply/db-migrations/PLAYBOOK.md
 related:
@@ -24,21 +25,26 @@ related:
 
 ## Summary
 
-**NYCHH is the only tenant granted the Talos AI assistant in TOGa 2.5 Supply.** The feature is
-seeded **OFF in Core for every client** and turned on per tenant with `SurfaceOverrides` rows on
-the `talos-assistant` surface. Developer instruction, verbatim: *"in core all clients should have
-it toggled off. and then we will toggle it on specifically for nychh in supply."*
+**NYCHH is the only tenant granted the Talos AI assistant in TOGa 2.5 Supply, and it AUTHORS ITS
+OWN suggestion questions.** The feature is seeded **OFF in Core for every client** and turned on
+per tenant with `SurfaceOverrides` rows on the `talos-assistant` surface. Developer instruction,
+verbatim: *"in core all clients should have it toggled off. and then we will toggle it on
+specifically for nychh in supply."*
 
-Everything shared — the surface, the elements, the blox panel, the supply provider — is
-tenant-neutral. Only the five grant rows are NYCHH's.
+Everything shared — the surface, the two elements, the blox panel, the supply provider — is
+tenant-neutral. Only NYCHH's **three** override rows are NYCHH's.
 
 ## How it works
 
-1. **Core** (`Core/2026-09-02a`) seeds surface `talos-assistant` (type `DRAWER`, not
-   record-bound) with 5 elements, all `isVisible = 0`: one `config.role='featureEnabled'` marker
-   (the master switch) and four `config.role='suggestion'` chips.
-2. **NYCHH** (`Client_Nychh/2026-09-02a`) inserts **5 `SurfaceOverrides` rows**, all
-   `IS_VISIBLE = '1'`, one per element.
+1. **Core** (`Core/2026-09-02a`) seeds surface `talos-assistant` (type `DRAWER`, not record-bound)
+   with **two** elements, both `isVisible = 0`:
+   - `config.role='featureEnabled'`, `config.key='feature'` — the master switch.
+   - `config.role='suggestion'`, `config.key='suggestions'` — **the whole chip row in one element**,
+     its questions in `config.items` (an ordered array of `{label, prompt, icon}`).
+2. **NYCHH** (`Client_Nychh/2026-09-02a`) inserts **three rows**:
+   - `IS_VISIBLE = '1'` on `feature`
+   - `IS_VISIBLE = '1'` on `suggestions`
+   - a **`CONFIG` override** on `suggestions` carrying **NYCHH's own three questions**.
 3. The supply FE reads the marker via `useTalosSurface()` and **fails closed** — no bundle, failed
    fetch, missing marker, or still-loading all mean disabled. `TalosStreamProvider`'s `enabled`
    prop means an ungranted tenant never even calls Aegra's `/assistants`.
@@ -47,6 +53,53 @@ Mechanism and seeding rules:
 [surface-layer-schema](../../../2.0/apps/dbchanges2/features/surface-layer-schema.md).
 FE wiring: [Talos integration](../../../2.0/apps/toga25-supply/features/talos-integration.md).
 
+## NYCHH's three questions — it does NOT inherit Core's default
+
+| Label | Icon |
+|---|---|
+| How many orders have been placed in the last year? | `lock` |
+| Show me orders pending fulfillment | `truck` |
+| How many orders are in each status? | `chartSimple` |
+
+Developer instruction, verbatim: *"now for nychh, i need the array to be this instead: …"*. NYCHH's
+`CONFIG` override **replaces** Core's default set outright.
+
+`icon` is a **literal FontAwesome name**, and `label` is a **raw string, not a `Messages` key** —
+so `MessageTranslations` cannot translate these. That trade is recorded in the schema doc.
+
+### 🚨 The override MUST restate `"role":"suggestion"`
+
+A `CONFIG` override **replaces `config` wholesale — it does not merge** (`_underscore
+Model/Core/Surface.php:839` assigns the decoded JSON over `$config`; there is no `array_merge`).
+Send only `items` and `config.role` is **wiped**, the element stops matching in the frontend, and
+**the chips silently disappear with no error anywhere**. A bare top-level JSON array also passes
+that check, which is why it is the tempting wrong move.
+
+The JSON goes in **`c_longValue`, never `value`** — `value` is `varchar(255)` and any real chip set
+overflows it.
+
+**That is why the verify query asserts the role survived, not just that the row exists:**
+
+```sql
+JSON_UNQUOTE(JSON_EXTRACT(o.c_longValue, '$.role'))   -- must be non-NULL
+```
+
+### Changing NYCHH's chips later
+
+The file carries a `CHANGING NYCHH'S CHIPS LATER` block with two recipes:
+
+- **Reword / add / reorder a chip** → `UPDATE` the `CONFIG` row's `c_longValue`. Order is **array
+  order**; there is no per-chip `sortOrder`. No Core deploy.
+- **Fall back to Core's default set** → **`DELETE` the `CONFIG` row.** Do **not** write an empty
+  `items` array — that renders an **empty chip row**, not the default.
+
+### Section shape (prod cannot cross clusters)
+
+Section **A2** is the single-cluster form (local/beta). Section **C2** is the prod literal-id form,
+because Core and `Client_*` are on **separate clusters** in production. Section B reads the element
+ids off the Core cluster first. Full three-section rule:
+[surface-layer-schema](../../../2.0/apps/dbchanges2/features/surface-layer-schema.md).
+
 ## The grants are CLIENT-WIDE — no role scoping
 
 `roleId` / `personaId` / `languageId` are **NULL**, so **every NYCHH user, including internal
@@ -55,6 +108,22 @@ grants navigation (NYCHH does not scope navigation by role). **Per-role gating w
 it is ever needed, the grants have to be widened/narrowed at the *same* tier (see the shadowing rule
 in the schema doc).
 
+⚠ Note for whoever *does* scope it: chip **sets** are scopable, individual chips are not, and two
+role-scoped `CONFIG` rows resolve by `ORDER BY (roleId IS NULL) DESC, (personaId IS NULL) DESC,
+id ASC` — for a user holding both roles the **higher id simply wins**. The `feature` marker is a
+plain boolean grant precisely so *access* keeps the clean grant-only rules.
+
+## Teardown — order matters
+
+Both SQL files carry a commented `TEARDOWN`. Run it in this order:
+
+1. `DELETE` the `Client_Nychh.SurfaceOverrides` rows.
+2. `DELETE` the Core `SurfaceElements` rows.
+3. `DELETE` the `Surfaces` row.
+
+Reverse it and the grants point at element ids that no longer exist. The `talos.feature.name`
+`Message` is **left behind on purpose** — harmless, and re-used on a re-run.
+
 ## Aegra side
 
 - **`assistant_id` `c7981164-1fe9-5878-b115-85c38dadad43`** — name `TOGa Supply`,
@@ -70,24 +139,39 @@ in the schema doc).
 
 ## Run state — 🚨 beta and prod are NOT done
 
-Verified on **local only** (2026-09-02, developer ran the SQL):
+Verified on **local only** (2026-09-02, developer ran the SQL; the full teardown + re-run worked end
+to end and NYCHH's three chips render):
 
 - `navigation` surface = **id 39**, `appId` **1**.
-- Talos seed produced `SurfaceElements` **216–220** (feature / pendingApproval / blockedApprovals /
-  pendingFulfillment / statusCounts), `sortOrder` 1 / 10 / 20 / 30 / 40, all `isVisible = 0`, all
-  labels non-NULL.
-- `Client_Nychh` grants: **5 rows, all `IS_VISIBLE = '1'` on 216–220**.
+- `Client_Nychh` overrides: **3 rows** — `IS_VISIBLE='1'` on `feature` and `suggestions`, plus the
+  `CONFIG` row carrying NYCHH's three items.
 - **Beta and production: NOT YET RUN.**
 
-**Element ids are per-environment** (`AUTO_INCREMENT`), so local / sandbox / prod will differ. Do
-**not** copy 216–220 into a prod run — that is precisely why the client grant file's Section B reads
-the ids off the Core cluster first.
+**Do NOT copy any element id from this doc or from a teammate's local DB.** Element ids are
+`AUTO_INCREMENT` and therefore **per-environment**. The first attempt of this feature consumed
+`SurfaceElements` **216–220** under the old per-chip shape; those were torn down and re-created under
+the two-element shape, so local ids advanced **again**. That is exactly why the client grant file's
+Section B reads the ids off the Core cluster at run time.
 
 ## Change history
-- 2026-09-02 — First record. NYCHH became the **only** tenant granted Talos: Core seeds the
-  `talos-assistant` surface OFF for all clients, `Client_Nychh/2026-09-02a` adds the 5 client-wide
-  `IS_VISIBLE=1` grants (`roleId` NULL — every NYCHH user incl. devteam; per-role gating not built).
-  Verified on **local only** — surface elements **216–220**, `navigation` surface 39/appId 1; **beta
-  and prod not yet run**, and element ids are per-environment so prod must read them off Core.
-  Recorded the NYCHH `assistant_id` and that thread auto-titles are broken **server-side** on that
-  assistant, not in supply. (apeterson)
+- 2026-09-02 — **CORRECTED to the final shape (the per-chip design recorded earlier is
+  superseded).** NYCHH now writes **three** rows, not five: `IS_VISIBLE='1'` on the `feature` and
+  `suggestions` elements plus **one `CONFIG` override authoring NYCHH's own three questions** ("How
+  many orders have been placed in the last year?" / lock, "Show me orders pending fulfillment" /
+  truck, "How many orders are in each status?" / chartSimple). Core seeds **two** elements — the
+  `featureEnabled` marker and **one** `suggestion` element whose `config.items` is an ordered array
+  of `{label, prompt, icon}` — replacing the five-element, one-chip-per-element first cut, which
+  meant only **Core** could author a tenant's wording. 🚨 The override **must restate
+  `"role":"suggestion"`**: a `CONFIG` override replaces `config` wholesale (`Surface.php:839`, no
+  merge), so omitting it wipes the role and the chips **silently vanish** — hence the verify query
+  now asserts `JSON_EXTRACT(c_longValue,'$.role')` is non-NULL, and the JSON lives in `c_longValue`
+  (not the varchar(255) `value`). Added a `CHANGING NYCHH'S CHIPS LATER` block (`UPDATE` to reword,
+  `DELETE` to fall back to Core's default — **never** an empty `items` array, which renders an empty
+  row) and a commented **TEARDOWN** whose order is load-bearing (client `SurfaceOverrides` → Core
+  `SurfaceElements` → `Surfaces`). Chip labels are raw strings, so `MessageTranslations` cannot
+  translate them; chip **sets** are scopable but individual chips are not, and a multi-role user
+  resolves arbitrarily (higher id wins) — which is why the `feature` marker stays a plain boolean
+  grant. Re-verified on **local only** after a full teardown + re-run; element ids advanced again and
+  remain per-environment, so prod must read them off Core in Section B. **Beta and prod still not
+  run.** Recorded the NYCHH `assistant_id` and that thread auto-titles are broken **server-side** on
+  that assistant, not in supply. (apeterson)

package/knowledge/sessions/2026-09-02-transfer-order-create-modal-apeterson.md

@@ -0,0 +1,106 @@
+---
+type: session
+slug: transfer-order-create-modal
+title: Create Transfer Order modal — single-POST create + design-matched UI
+author: apeterson
+repos: [toga25-supply, _underscore, dbchanges2, api2]
+framework: "2.0"
+client: nychh
+status: active
+created: 2026-09-02
+updated: 2026-09-02
+---
+
+# Session: transfer-order-create-modal
+**Date:** 2026-09-02
+**Project/Repo:** toga25-supply (+ _underscore, dbchanges2, api2) — 2.0
+**Task:** Build the Create Transfer Order modal for NYCHH end to end — one atomic POST, the three new `TransferOrders` columns behind it, and the picker/dropdown UI matched to the Claude Design mockup.
+
+---
+
+## What WORKED
+
+- **Single POST create.** `useCreateTransferOrder.ts` now posts header + lines in one request to `/transfer-orders`, lines nested under `transferOrderItems`. Verified against the engine, not guessed: `api2/Component/Api/V2/V2.php:3248` converts the inherent child's `route` kebab→camel, and `:5241` uses the SAME lookup on the CREATE path (`$childrenToCreate[$key] = $val`). Jeff's nesting row exists — `InherentRecordChildren` id 152, parent record 312 → child 313, route `transfer-order-items` (confirmed by query).
+- **Three new columns.** `_underscore/Model/Client/TransferOrder.php` has `contactId` (FK Contacts), `createdByUserId` (FK Users), `description` (varchar 255). Migrations written and guarded with `INFORMATION_SCHEMA` checks.
+- **Core ids verified against production before use.** `Records` MAX(id) = 358; RecordFields 2561–2563 free. Handoff for the team: next `Records.id` = 359, next `RecordFields.id` = 2564.
+- **TransferOrderNotes tables + metadata ran clean.** `Client/2026-09-01b` and `Core/2026-09-01c` are applied (Records 357/358, RecordFields 2550–2560). Both tables ship empty. NOTE: now unused — see Decisions.
+- **Target Location picker.** `SelectTargetLocationModal.tsx` — flat list, 250 ms debounced search, breadcrumb path built from `parentLocation.uuid` with a cycle guard.
+- **Contact scoping.** Contacts come from `Contacts` through the `Contacts_Locations` junction, scoped to the chosen location (`useLocationContacts.ts`).
+- **One select control for the whole modal.** New app-local `PanelSelect.tsx` — 38px trigger, search box inside the panel, green check on the chosen row, optional pinned footer, optional clear (×). `ContactSelect.tsx` is now a thin mapping over it. The PO filter uses it at 200px with "All POs" as a row in the list. Matches the mockup's `window.FormSelect` / `FilterLockSelect`.
+- **"Show more" on the item cell.** `TransferItemPickerTable.tsx`, rules copied from blox `PrimaryTableBodyCell`: offered only when text is really clipped (measured on hover), collapsed visibility is CSS `group-hover` not state, expanded wraps above a "Show less" toggle and grows the row (body cells align top), toggle `stopPropagation`s so it never checks the row. Cells cap at 300px so clipping can happen at all in an auto-layout table. Items table max height 355px.
+- **Blank Item column fixed.** Label chain is `item.title || item.description || "(untitled item)"`, and `vendorItem.item.description` was added to the requested fields.
+- **Verification each time:** `npx tsc --noEmit` exits 0; `npx eslint src/pages/TransferOrders/view/CreateTransferOrderModal` stays at the same 8 pre-existing errors (2 `set-state-in-effect`, 1 `react-hooks/refs`, 4 `no-explicit-any`, 1 `react-refresh/only-export-components`). Baseline was established with `git stash`, so "zero new errors" is measured, not assumed.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Three sequential POSTs to create a transfer.** Abandoned: it can leave a half-written transfer behind. The inherent-child single POST is one API transaction, which the front controller commits on success and rolls back on failure.
+- **A scripted API endpoint for transfer create.** Not needed once the inherent child works. Developer decided no.
+- **`useCallback` around the modal's `submit`.** React Compiler bailed with "Compilation Skipped: Existing memoization could not be preserved." Fixed by making `submit` a plain function. Do not wrap it again.
+- **A `useEffect` that called `close()` when the select went disabled.** Tripped `react-hooks/set-state-in-effect`. Replaced with derived state: `const isPanelOpen = isOpen && !disabled;`.
+- **Bare FK column names in the `fields` option.** I wrote `parentLocationId` and it returned nothing. This repo uses dotted paths — `parentLocation.uuid`, `vendorItem.item.title` — and FKs POST as nested `{ uuid }` objects.
+- **A native `<select>` for the PO filter.** Looked like a different control next to the custom contact select. The mockup draws both with the same `FormSelect`.
+- **Falling back to a part number for the item label.** Part Number already has its own column, so it duplicates a cell instead of naming the item.
+- **`Locations.primaryContactId` as a default-contact FK.** Developer rejected it: `Contacts_Locations` is the right place.
+- **A unique index on `Contacts_Locations (locationId, type)`.** Wrong — it is many-to-many, many contacts per location. Only `isPrimary` is viable.
+- **My `_qty*` diagnosis "no ItemReceiptItems exist, it's data."** Wrong. The developer's query returned `216 | 80622 | 3270.00 | 27 | 3270.00` — receipts do exist. The seed-the-receipts plan built on that was also scrapped.
+- **`AUTO_INCREMENT` / repo-derived ids for `Records` / `RecordFields`.** Never do this. They are the only two tables platform-wide with team-assigned ids; ask the developer, and the repo lags production.
+- **Python heredoc edits that assume indentation depth.** Failed twice (`AssertionError: ('type', 0)`) — assumed 4 tabs where it was 3, and 10 where it was 11. Print `repr()` first or slice by index. The asserts fire before the write, so no file was corrupted.
+
+## Not tried yet (candidates for next session)
+
+- A live POST of the create flow. **Nothing in this modal has been sent to a real API yet.** Blocked on the two pending migrations + the `_underscore` deploy.
+- Setting `transferOrderStageId` on create — unknown which stage row NYCHH seeds as the opening one.
+- Minting `TransferOrders.number`. Deliberately not done client-side: two concurrent creates would race. Needs a server-side owner.
+- Stamping `createdByUserId` from the JWT server-side instead of from the browser's `user` localStorage key.
+- Dropping the now-unused `TransferOrderNotes` / `TransferOrderNoteTypes` tables and their Core metadata (Records 357/358, RecordFields 2550–2560).
+- Adding the ACL grant for NYCHH on records 357/358 — currently missing (only needed if the notes tables stay).
+- Adding the magnifier icon inside the item search box (the mockup has one on the left; ours has none).
+- Populating `Items.title` for NYCHH — the real fix behind the description fallback.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `toga25-supply/.../CreateTransferOrderModal/hooks/useCreateTransferOrder.ts` | Modified | Single POST; exports `DESCRIPTION_MAX_LENGTH = 255`; omits `number` on purpose |
+| `toga25-supply/.../hooks/usePurchaseOrderItemRows.ts` | Modified | `item.description` fallback; `VITE_TRANSFER_IGNORE_AVAILABILITY` escape hatch |
+| `toga25-supply/.../hooks/useTargetLocationOptions.ts` | Modified | `parentLocation.uuid` dotted path; breadcrumb path + cycle guard |
+| `toga25-supply/.../hooks/useLocationContacts.ts` | Modified | Contacts via `Contacts_Locations`, scoped to the location |
+| `toga25-supply/.../hooks/useCreateLocationContact.ts` | Modified | Inline add-contact |
+| `toga25-supply/.../view/SelectTargetLocationModal.tsx` | Created | Flat picker, debounced search, 720px card |
+| `toga25-supply/.../view/PanelSelect.tsx` | Created | The one select control; `// TODO(blox): promote once stable` |
+| `toga25-supply/.../view/ContactSelect.tsx` | Rewritten | Now a thin wrapper over `PanelSelect` |
+| `toga25-supply/.../view/TransferItemPickerTable.tsx` | Modified | 355px max height, column lines, `ExpandableText` show-more, `align-top` cells |
+| `toga25-supply/.../view/TransferNotesField.tsx` | Modified | Optional `maxLength`, wired to 255 |
+| `toga25-supply/.../CreateTransferOrderModal.tsx` | Modified | `PanelSelect` for PO (200px, "All POs" row), plain `submit`, inline error |
+| `_underscore/Model/Client/TransferOrder.php` | Modified | `contactId`, `createdByUserId`, `description` — **not deployed** |
+| `_underscore/Model/Client/TransferOrderNote.php` | Created | Mirrors `PurchaseOrderNote` — currently unused |
+| `_underscore/Model/Client/TransferOrderNoteType.php` | Created | Mirrors `PurchaseOrderNoteType` — currently unused |
+| `dbchanges2/Client/2026-09-01b - TransferOrderNotesTables.sql` | Applied | Ran |
+| `dbchanges2/Core/2026-09-01c - TransferOrderNotesRecords.sql` | Applied | Ran — Records 357/358, RecordFields 2550–2560 |
+| `dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql` | **Not run** | 7 `INFORMATION_SCHEMA`-guarded sections; run on every client DB |
+| `dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql` | **Not run** | RecordFields 2561–2563 on record 312 + ACL roles 1 and 3 |
+
+All application-repo changes sit uncommitted in the working tree on branch `features-talos-transferorders`. Nothing was committed or pushed.
+
+## Decisions made
+
+- **One POST, not a scripted endpoint.** The inherent child gives the same all-or-nothing write, so a custom endpoint buys nothing. Rejected: three sequential POSTs (can half-write), a scripted API method.
+- **The modal's Notes box writes `TransferOrders.description`, not a note row.** A transfer carries one free-text description, not a thread of typed notes from different authors. Consequence: `TransferOrderNotes` / `TransferOrderNoteTypes` are now unused even though they are already migrated. Rejected: posting a `TransferOrderNotes` row per create.
+- **`createdByUserId` is client-supplied** (read from the `user` localStorage key), matching the SalesOrders precedent. It is only as trustworthy as this client — still open for Jeff. Rejected for now: JWT-stamped server-side.
+- **`number` is left NULL.** Minting max+1 from the browser races two concurrent creates. Rejected: client-side minting.
+- **The contact list lives in `Contacts_Locations`,** not a `Locations` FK — the developer's call. Many contacts per location, so only `isPrimary` can mark a default.
+- **`PanelSelect` is app-local, not blox.** Front-end standard §21: build it here, promote after a second consumer. blox's `AdvancedSelect` has `renderOption` but no footer slot, and a sentinel row inside `data` gets filtered out by the very search that makes you need it.
+- **Grid geometry stays in the front end.** Cell max width, table max height and column lines are presentation, not surface metadata.
+- **`VITE_TRANSFER_IGNORE_AVAILABILITY` is local-only.** It disables the guard that stops a transfer asking for more than can be dispatched. **Never set it in a deployed environment.**
+
+## Blockers
+
+- **`_qty*` returns 0 for every NYCHH PO line.** For PurchaseOrderItem `715ef031-003d-6742-871d-0d20de2fa40f` (PO 80622, line 21) the API gives `quantity: 3270` but `_qtyReceived` / `_qtyOnHand` / `_qtyAvailable` / `_qtyFulfilled` are all `0`, while SQL on `Client_Nychh` gives received 3270. A literal `0` (not absent) rules out field ACL and `calcDepth`. Physical shadowing columns also ruled out (the blank template has 7 columns on `PurchaseOrderItems`). The team KB already has the cause from 2026-09-01: the deployed `_Model_Nychh_PurchaseOrderItem` INNER JOINs `InventoryAdjustmentItems.itemFulfillmentItemId`, which is NULL on 100% of rows. Talk to Jeff as "this narrows the known blocker", not as a new bug. Worked around locally with `VITE_TRANSFER_IGNORE_AVAILABILITY=true`.
+- **Two migrations + one deploy are pending,** so the create path cannot be tested live yet (see next step).
+
+## Exact next step
+
+> Run the pending rollout, in this order: (1) deploy `_underscore` so `TransferOrder.php` carries `contactId` / `createdByUserId` / `description`; (2) run `dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql` on every client DB; (3) run `dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql` on Core; (4) post `next Records.id = 359` / `next RecordFields.id = 2564` to the team; (5) create one test transfer in the modal with `VITE_TRANSFER_IGNORE_AVAILABILITY=true` and confirm the row has `contactId`, `createdByUserId`, `description`, and its `TransferOrderItems` rows written in the same request.
+
+---
+_Saved by /session-save on 2026-09-02_

package/package.json

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