toga-ai 1.0.747 → 1.0.748

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/package.json

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