toga-ai 1.0.746 → 1.0.748

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

@@ -33,6 +33,7 @@
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, _underscore/Trait/Netsuite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Worker/Netsuite/Opportunity.php |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
+| [Note records have NO author — every `*Notes` model's `contactId` is unwritten](features/note-record-authorship.md) | **"Who wrote this note?" is currently unanswerable from TOGa 2.0 data.** Every note model in the framework declares a `contactId` foreign key to `Contacts` — th | _underscore/Model/Client/SalesOrderNote.php, _underscore/Model/Client/PurchaseOrderNote.php, _underscore/Model/Client/TransferOrderNote.php, _underscore/Model/Client/TicketNote.php, _underscore/Model/Client/UnitNote.php, _underscore/Model/Client/ServiceRequestNote.php, _underscore/Model/Client/PartRequestNote.php |
 | [Outbound third-party API rate budget (_Component_Api_RateBudget) — designed + staged, NOT merged](features/outbound-api-rate-budget.md) | A **shared outbound rate budget for every third-party API** we call from 2.0 (ClickUp, NetSuite, FedEx, UPS, …): one small component plus one `Core` table, keye | _underscore/Component/Api/RateBudget/RateBudget.php, _underscore/Component/Api/Clickup/Clickup.php, _underscore/Route.php, _underscore/Query.php, dbchanges2/Core/2026-09-01a - Add ApiRateBudget table.sql, worker2/Worker/Clickup/Api.php |
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php, toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Model.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |

package/knowledge/2.0/apps/_underscore/features/note-record-authorship.md

@@ -0,0 +1,101 @@
+---
+title: "Note records have NO author — every `*Notes` model's `contactId` is unwritten"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-02
+owners: [apeterson]
+files:
+  - _underscore/Model/Client/SalesOrderNote.php
+  - _underscore/Model/Client/PurchaseOrderNote.php
+  - _underscore/Model/Client/TransferOrderNote.php
+  - _underscore/Model/Client/TicketNote.php
+  - _underscore/Model/Client/UnitNote.php
+  - _underscore/Model/Client/ServiceRequestNote.php
+  - _underscore/Model/Client/PartRequestNote.php
+related:
+  - ../../toga-blox/features/add-notes-template.md
+  - ../../toga25-supply/features/transfer-orders-page.md
+  - ../features/sales-order-denial-reason.md
+  - ../../../clients/compass-usa/features/approval-decision-flow.md
+---
+
+## Summary
+
+**"Who wrote this note?" is currently unanswerable from TOGa 2.0 data.**
+
+Every note model in the framework declares a `contactId` foreign key to `Contacts` — the field that
+*looks* like note authorship — and **no code anywhere writes it.** Note rows are created with the
+body, a type and a timestamp, and no author. Read that as a schema affordance that was never wired
+up, not as a column you can query.
+
+Found 2026-09-01 while building `TransferOrderNote` / `TransferOrderNoteType` as faithful mirrors of
+the purchase-order pair; the gap turned out to be platform-wide, not new.
+
+## The seven models, all the same shape
+
+Verified against `_underscore` (`grep contactId Model/Client/*Note.php`) — **all seven** declare it:
+
+```php
+public $contactId = [self::FIELD_FOREIGNKEY, self::FIELDOPT_FOREIGNKEY_MODEL => '\_Model_Client_Contact'];
+```
+
+| Model | Table |
+|---|---|
+| `_Model_Client_SalesOrderNote` | `SalesOrderNotes` |
+| `_Model_Client_PurchaseOrderNote` | `PurchaseOrderNotes` |
+| `_Model_Client_TransferOrderNote` | `TransferOrderNotes` |
+| `_Model_Client_TicketNote` | `TicketNotes` |
+| `_Model_Client_UnitNote` | `UnitNotes` |
+| `_Model_Client_ServiceRequestNote` | `ServiceRequestNotes` |
+| `_Model_Client_PartRequestNote` | `PartRequestNotes` |
+
+The rest of the shape is uniform too: `<parent>Id`, `<parent>NoteTypeId`, `dtStamp`
+(`FIELD_DATETIME_CREATED`), `note`. So `dtStamp` tells you **when**, the type tells you **what kind**
+— and nothing tells you **who**.
+
+## The consequence, and the workaround that exists in production
+
+Because the column is empty, any "submitted by" display has to recover the author from the note
+**body text**. Compass does exactly that: it **regex-scrapes email addresses out of the note body**.
+That works only because their notes happen to contain an address; it is not a pattern to copy, and it
+fails silently on any note that does not.
+
+So before building anything that shows or filters by note author:
+
+- **Do not assume `contactId` is populated** — check the actual rows for the tenant first. It will be
+  NULL.
+- **Do not add a per-tenant body-text scrape.** That is the existing workaround, and it is the reason
+  this gap has stayed invisible.
+- **The real fix is to write `contactId` on create**, from the authenticated identity, in whichever
+  layer creates the note. That is unclaimed platform work — it also needs a backfill decision for the
+  existing rows, which cannot be recovered except by scraping.
+
+## Why a transfer's Notes box does not use these tables at all
+
+The toga25-supply Create Transfer Order modal deliberately writes **`TransferOrders.description`**
+(one `varchar(255)` free-text field) instead of note rows: a transfer carries one description, not a
+thread of typed notes from different authors. The authorship gap documented here is part of why —
+a note thread whose entries have no author is a weaker record than a single description field. The
+`TransferOrderNotes` tables and their Core metadata were built anyway and are currently **unused**;
+see [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
+
+## Gotchas
+
+- **`contactId` on a `*Notes` model is an unwritten FK — treat it as always NULL.** Seven models,
+  zero writers.
+- **A notes list UI has no author to show.** Design for it, or the field silently renders blank for
+  every row.
+- **`dtStamp` is `FIELD_DATETIME_CREATED`**, so it is stamped by the ORM on insert and is the only
+  provenance a note actually carries.
+
+## Change history
+- 2026-09-02 — First capture. Recorded that **all seven** `*Notes` models (`SalesOrderNote`,
+  `PurchaseOrderNote`, `TransferOrderNote`, `TicketNote`, `UnitNote`, `ServiceRequestNote`,
+  `PartRequestNote`) declare a `contactId` FK to `Contacts` that **no code writes**, so note
+  authorship is unrecoverable from the data; Compass works around it by regex-scraping email
+  addresses out of the note body. Surfaced while building the (now unused) `TransferOrderNote` /
+  `TransferOrderNoteType` pair for NYCHH transfer orders. (apeterson)

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -143,6 +143,21 @@ GET /v2/transfer-orders/{uuid}/transfer-order-items
 - **The JSON key of an inherent child is the camelCase of the child ROUTE**, not of the table or the
   model (`V2.php` ~L6310, via `_String::CASE_KEBAB` → `CASE_CAMEL`). `transfer-order-items` →
   `transferOrderItems`.
+- **🚨 The same route-derived key governs the WRITE path — so the ROUTE is the payload contract.**
+  `V2.php:3248` builds `$lookupInherentChildByFieldName` by converting each inherent child's `route`
+  kebab→camel, and the **CREATE** branch reuses that *same* lookup at `V2.php:5241`
+  (`$childrenToCreate[$key] = $val`). So a nested collection in a `POST` body must be keyed by the
+  child **route** in camelCase — not the table, not the model, not the FE's preferred name. Two
+  consequences: (a) **renaming a `Core.Records.route` silently renames the payload key of every
+  writer**, and nothing in the database enforces or warns about it; (b) a key that matches nothing
+  falls through to `$unknownFields` (`V2.php:5251`). Worked example: the toga25-supply Create
+  Transfer Order modal posts header + lines in one request as `transferOrderItems` — see
+  [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
+  > ⚠ **Do not assume the `$unknownFields` error protects you.** It is a *loud* rejection on this
+  > branch, but a wrong-shaped nested collection has been measured returning **201 with the data
+  > silently dropped** on other paths — see
+  > [nested-relationship writes](nested-relationship-writes.md). Match the route exactly and
+  > **assert child row counts**; never take a 2xx as proof the children landed.
 - **Adding an `InherentRecordChildren` row is a breaking-shape change, not a feature flag.** It
   alters the default response for **every** existing caller of that route — including 1.0 importers
   and NetSuite sync — so the blast radius has to be surveyed first. The transfer-order build
@@ -364,6 +379,13 @@ ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — wh
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-02 — Recorded that the inherent-child key rule **also governs the WRITE path**, so the
+  child **route** is the payload contract for a nested collection in a `POST` body: `V2.php:3248`
+  builds `$lookupInherentChildByFieldName` (route kebab→camel) and the CREATE branch reuses that
+  same lookup at `V2.php:5241` (`$childrenToCreate`), with unmatched keys collected into
+  `$unknownFields` at `:5251`. So renaming a `Core.Records.route` silently renames every writer's
+  payload key, with nothing in the database to warn about it. Verified against the engine while
+  making the Create Transfer Order modal post header + lines in a single request. (apeterson)
 - 2026-09-02 — Recorded that a **bridge** collection needs its own `InherentRecordChildren` row and
   that the **header** bridge is a different record from the item bridge: a transfer order's PO number
   reads through `312 → 325 purchase-orders-transfer-orders`, **not** `329

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

@@ -1096,19 +1096,49 @@ hits `Duplicate entry '251' for key 'messages.PRIMARY'`. The resolution that kee
 `Core/2026-09-02a - TalosAssistantSurfaceSeed.sql` +
 `Client_Nychh/2026-09-02a - TalosAssistantEnable.sql` put the Talos AI assistant behind the
 surface layer. The surface is `talos-assistant`, **type `DRAWER`**, **not record-bound**, with
-`appId` **inherited from the `navigation` sibling by slug** (never a literal). Five elements,
-**all seeded `isVisible = 0`** — grant-only:
+`appId` **inherited from the `navigation` sibling by slug** (never a literal). **TWO elements**,
+**both seeded `isVisible = 0`** — grant-only:
 
-| Role | Count | Purpose |
-|---|---|---|
-| `config.role = 'featureEnabled'`, `config.key = 'feature'` | 1 | **MASTER SWITCH.** Its `isVisible` turns the launcher, the panel and the whole AI stream on or off. |
-| `config.role = 'suggestion'` | 4 | one chip each (`pendingApproval`, `blockedApprovals`, `pendingFulfillment`, `statusCounts`): label → `labelMessageId`, the question actually sent → **`config.prompt`**, icon → `iconToken` + `iconWeightToken='solid'`, order → `sortOrder`. |
+| Element | Purpose |
+|---|---|
+| `config.role = 'featureEnabled'`, `config.key = 'feature'` | **MASTER SWITCH.** Its `isVisible` turns the launcher, the panel and the whole AI stream on or off. Stays a **plain boolean grant** — see why below. |
+| `config.role = 'suggestion'`, `config.key = 'suggestions'` | **THE WHOLE CHIP ROW, in ONE element.** `config.items` is an **ordered JSON array** of `{label, prompt, icon}` (`icon` = a literal FontAwesome name). Its own `isVisible` switches the entire row. |
 
 It replaced `DEFAULT_SUGGESTIONS` — four hardcoded **TOGa Supply** questions that lived inside
 `toga-blox`, a library five apps consume, so any host mounting the panel inherited Supply's
 prompts. FE side:
 [Talos integration](../../toga25-supply/features/talos-integration.md).
 
+### ⚠ SUPERSEDED — the chips were briefly ONE ELEMENT PER CHIP. They are not.
+
+The first cut of this seed wrote **five** elements: the marker plus **four `config.role='suggestion'`
+elements, one per chip** (`labelMessageId` for the label, `config.prompt` for the question,
+`iconToken`/`iconWeightToken` for the icon, `sortOrder` for the order). **That shape is gone** —
+replaced before anything ran past local. If you find a doc, a branch or a local DB in that shape, it
+is the old design. There is **no `config.prompt`**, no per-chip `labelMessageId`, and **no per-chip
+`sortOrder`** any more; order is array order.
+
+**Why one element wins.** Per-chip elements let a tenant only switch **on** questions Core had
+already seeded, so changing a tenant's *wording* needed a new **Core** migration for every phrasing.
+These are the tenant's own business questions — Core must not gatekeep the wording. With one
+element a tenant **authors its own set** in a single `CONFIG` override, and adding or reordering a
+chip is **one row instead of a Core deploy**.
+
+**Two costs, accepted deliberately — do not rediscover them:**
+
+1. **Chip labels are NOT translatable.** They are raw strings in `config`, not `Messages` keys, so
+   `MessageTranslations` cannot reach them. (Partly moot: API-auth JWTs carry no language, so client
+   translations never apply on those sessions anyway.)
+2. **Only whole SETS are scopable, not individual chips — and a multi-role user resolves
+   arbitrarily.** Two role-scoped `CONFIG` rows resolve by
+   `ORDER BY (roleId IS NULL) DESC, (personaId IS NULL) DESC, id ASC`, so for a user holding **both**
+   roles the **higher id simply wins**. There is no merge and no defined precedence between two peer
+   roles.
+
+That second cost is exactly **why the `featureEnabled` marker was NOT folded into the config**: a
+plain boolean grant keeps the grant-only model (and its clean shadowing rules) for the thing that
+actually gates access.
+
 ### 🚨 A feature switch is a MARKER ELEMENT — never `Surfaces.isVisible`
 
 The override cascade is keyed by **`surfaceElementId`** and is **never applied to a `Surfaces`
@@ -1116,7 +1146,7 @@ row's own `isVisible`** (`_loadOverrides`, `Model/Core/Surface.php` ~L733–748)
 surface row silently does nothing.** So a whole-feature switch has to be a hidden **marker
 element** on the surface, exactly like the `sectionVisibility` and `approvalsEnabled` markers.
 
-### The prompt lives in `config.prompt`, NOT an `Actions` row
+### The prompts live in `config.items[]`, NOT an `Actions` row
 
 `RUN_TALOS` **is** a member of the `Actions.type` ENUM, but **nothing in `dbchanges2` has ever
 seeded an `Actions` row** and there is **no FE action-registry entry** for it. `config` is emitted
@@ -1125,6 +1155,44 @@ wiring**. Same trade `Core/2026-08-12a` made choosing `config.path` over `Action
 the same discriminator as the BUTTON_BAR rule above: **seed an `Action` only when the behaviour
 lives in the registry.**
 
+### 🚨 A `CONFIG` override REPLACES `config` wholesale — this is the load-bearing rule of the whole design
+
+Verified in `_underscore` **`Model/Core/Surface.php:839`**: the decoded JSON is **assigned over**
+`$config` —
+
+```php
+$config = (is_array($value) || is_object($value)) ? $value : $config;
+```
+
+— **there is no `array_merge`.** Consequences, in order of how much time they cost:
+
+- **A tenant override MUST restate `"role":"suggestion"` alongside its `items`.** Send only `items`
+  and `config.role` is **wiped**, the frontend stops recognising the element, and **the chips
+  silently disappear** — no error in the API, the console, or the bundle. Nothing anywhere says
+  why.
+- **A top-level JSON array passes that check**, which is precisely why sending a bare
+  `[{...},{...}]` is the tempting wrong move. It is accepted, stored, resolved — and roleless.
+- Verify a chip override by asserting the **role survived**, not just that the row exists:
+  `JSON_UNQUOTE(JSON_EXTRACT(o.c_longValue,'$.role'))` must be non-NULL.
+
+**Put the JSON in `c_longValue`, never `value`.** `value` is `varchar(255)` and any real chip set
+overflows it. The resolver falls back to `c_longValue` when `value` is `NULL` or `''`
+(`Surface.php:907`). `_castOverrideValue` `json_decode`s `CONFIG` / `VISIBILITY_RULE` /
+`ENABLED_RULE`, and on bad JSON it **`error_log`s and returns null** — so a typo degrades to "the
+override was never there", again silently.
+
+### Teardown belongs IN the file, and the ORDER is not optional
+
+Both files carry a commented `TEARDOWN` block, because this shape changed **after** the files had
+already been run on local. Correct order:
+
+1. `DELETE` the `Client_Nychh.SurfaceOverrides` rows **first**.
+2. Then the Core `SurfaceElements` rows.
+3. Then the `Surfaces` row.
+
+Reverse it and the grants point at element ids that no longer exist. The `talos.feature.name`
+`Message` is **deliberately left behind** — harmless, and re-used on a re-run.
+
 ### ⚠ Second authoring pattern: AUTO_INCREMENT + `NOT EXISTS`, for a PURELY ADDITIVE seed
 
 The reserved-literal-id house style above (2026-08-24) remains the default. **These two files
@@ -1197,35 +1265,88 @@ user — including devteam — gets Talos. That matches how NYCHH already grants
 After a seed that consumes ids, post **"next `<Table>.id` = N"** for teammates. The number to
 publish is the **highest `MAX(id)+1` across EVERY environment**, not just local.
 
+#### `Core.Records` / `Core.RecordFields` — the two HAND-MAINTAINED id tables: ASK, don't derive
+
+These two are **not** like `Surfaces`/`SurfaceElements`/`Messages`. Platform-wide they are the
+**only** tables whose ids are **team-assigned by hand**, which is precisely what makes them safe to
+inline as literals in a `Client_*` file across the Core/Client cluster split. Three rules, in order:
+
+1. **Ask the developer for the next free id.** The team maintains the running number and posts it
+   after every id-consuming migration. That is the primary source — not a query, not the repo.
+2. **Never `AUTO_INCREMENT` a `Records` / `RecordFields` insert.** A generated id differs per
+   environment and instantly breaks every literal that points at it.
+3. **Never infer the next id from `dbchanges2`** — **the repo lags production.** Rows get
+   hand-applied ahead of (or instead of) a migration file, so the highest id in the repo is routinely
+   *below* the real ceiling. Verify against **production** before running.
+
+Consumed on **2026-09-01** by the transfer-order contact/notes work — verified against production
+first (`MAX(Records.id)` = **358**; `RecordFields` **2561–2563** free), then used: Records
+**357**/**358** and RecordFields **2550–2560** + **2561–2563**. **Handoff published: next
+`Records.id` = 359, next `RecordFields.id` = 2564.** ⚠ Re-verify against production immediately
+before your own run — that handoff is a snapshot, and the migrations that consumed it were still
+uncommitted at the time. See
+[Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
+
 ## Change history
+- 2026-09-02 — Wrote down the **`Core.Records` / `Core.RecordFields` id protocol**, the counterpart to
+  this doc's reserved-block discipline: they are the only two hand-maintained-id tables platform-wide,
+  so **ask the developer for the next free id**, never `AUTO_INCREMENT` them, and **never infer the
+  next id from `dbchanges2` — the repo lags production** (rows are hand-applied ahead of files).
+  Consumed 2026-09-01 by the transfer-order contact/notes work after verifying against production
+  (`MAX(Records.id)` = 358): Records 357/358 and RecordFields 2550–2563. Handoff published: next
+  `Records.id` = 359, next `RecordFields.id` = 2564. (apeterson)
+
 - 2026-09-02 — Added the **Talos feature-gate seed pair** (`Core/2026-09-02a -
   TalosAssistantSurfaceSeed.sql`: surface `talos-assistant`, type **DRAWER**, not record-bound,
-  `appId` inherited from the `navigation` sibling by slug, 5 elements all `isVisible = 0`;
-  `Client_Nychh/2026-09-02a - TalosAssistantEnable.sql`: 5 client-wide grants). **DECIDED** four
-  things worth reusing: (1) a whole-feature switch must be a hidden **marker element**, because the
-  override cascade is keyed by `surfaceElementId` and is **never** applied to a `Surfaces` row's own
-  `isVisible` (`_loadOverrides`, `Surface.php` ~L733–748) — overriding the surface row silently does
-  nothing; (2) the chip prompt lives in **`config.prompt`**, not an `Actions` row — `RUN_TALOS` is in
-  the ENUM but no `Actions` row has ever been seeded and there is no FE registry entry, while
-  `config` is emitted verbatim, so it needs no new wiring; (3) a **purely additive, id-agnostic**
-  seed may use **`AUTO_INCREMENT` + `NOT EXISTS`** instead of reserved literal ids — the
-  discriminator is whether the file re-parents rows or a `Client_*` file must inline a Core id, and
-  the analogue is the original `navigation` seed; (4) **OFF is correct, not just cautious**, for a
-  feature that sends a tenant's live data to an external AI. **FIXED prod-readiness** (developer
-  caught it): Core and `Client_*` are on **separate clusters** in prod, so the client file's
-  `JOIN Core.SurfaceElements` cannot run there — restructured into **Section A** (single-cluster
-  join, local/beta only), **Section B** (read-only `SELECT` on the Core cluster printing ids + a
-  paste-able `VALUES` body), **Section C** (literal-id guarded `INSERT` on the client cluster), with
-  rollback/verify in both forms. **De-qualified the Core file** (`Core.Messages` → `Messages`) because
-  api2 can rename the Core schema via `[database] core_dbname`, while the per-client file **keeps**
-  its `Client_Nychh.` qualification so a wrong-cluster run fails loudly rather than granting another
-  tenant the feature. DISCOVERED that **`SurfaceOverrides`' unique key protects a client-wide grant
-  not at all** — MySQL treats NULLs in a unique key as distinct, and a client-wide grant is
-  `personaId`/`roleId`/`languageId` all NULL, so the `NOT EXISTS` guard is the *only* thing making a
-  re-run idempotent. Verified against the real DDL: `iconToken` nullable, `NEUTRAL`/`BUTTON`/`TEXT`/
-  `LEFT` valid, `Surfaces.type DRAWER` exists, `Surfaces` UNIQUE KEY is `(slug, appId)`. Local run
-  produced `SurfaceElements` **216–220** (`navigation` = surface 39, appId 1); **beta and prod NOT
-  yet run**. (apeterson)
+  `appId` inherited from the `navigation` sibling by slug; `Client_Nychh/2026-09-02a -
+  TalosAssistantEnable.sql`). **REBUILT mid-session and this entry records the FINAL shape:** Core
+  seeds **TWO** elements, both `isVisible = 0` — the `config.role='featureEnabled'` marker, and
+  **ONE** `config.role='suggestion'` / `config.key='suggestions'` element whose `config.items` is an
+  ordered JSON array of `{label, prompt, icon}`. The first cut wrote **five** elements (one per
+  chip, prompt in `config.prompt`, order in `sortOrder`); **that shape is superseded** — per-chip
+  elements let a tenant only switch on wording **Core** had already seeded, so every rephrasing
+  needed a Core migration for questions that are the tenant's own business. NYCHH now writes **three**
+  rows: two `IS_VISIBLE='1'` grants (`feature`, `suggestions`) plus **one `CONFIG` override
+  authoring its own three questions**. Two costs accepted: chip labels are raw config strings, **not
+  `Messages` keys**, so `MessageTranslations` can never translate them (partly moot — API-auth JWTs
+  carry no language); and only whole **sets** are scopable, so a **multi-role user resolves
+  arbitrarily** (`ORDER BY (roleId IS NULL) DESC, (personaId IS NULL) DESC, id ASC` — higher id
+  wins, no merge). That is exactly why the `featureEnabled` marker was **kept a plain boolean grant**
+  and not folded into the config. **DECIDED/DISCOVERED, reusable:** (1) a whole-feature switch must
+  be a hidden **marker element**, because the override cascade is keyed by `surfaceElementId` and is
+  **never** applied to a `Surfaces` row's own `isVisible` (`_loadOverrides`, `Surface.php`
+  ~L733–748) — overriding the surface row silently does nothing; (2) 🚨 a **`CONFIG` override
+  REPLACES `config` wholesale, it does not merge** — verified at `Surface.php:839`
+  (`$config = (is_array($value) || is_object($value)) ? $value : $config;`, no `array_merge`), so a
+  tenant override **must restate `"role":"suggestion"`** beside its `items` or the chips **silently
+  disappear**; a bare top-level array passes that check, which is why it is the tempting wrong move;
+  the JSON goes in **`c_longValue`, never `value`** (varchar(255) overflow — resolver falls back at
+  `Surface.php:907`), and `_castOverrideValue` `error_log`s + returns null on bad JSON; (3) the chip
+  prompts live in **`config.items[]`**, not an `Actions` row — `RUN_TALOS` is in the ENUM but no
+  `Actions` row has ever been seeded and there is no FE registry entry, while `config` is emitted
+  verbatim; (4) a **purely additive, id-agnostic** seed may use **`AUTO_INCREMENT` + `NOT EXISTS`**
+  instead of reserved literal ids — the discriminator is whether the file re-parents rows or a
+  `Client_*` file must inline a Core id, and the analogue is the original `navigation` seed; (5)
+  **OFF is correct, not just cautious**, for a feature that sends a tenant's live data to an external
+  AI; (6) both files now carry a commented **TEARDOWN** whose order is load-bearing — client
+  `SurfaceOverrides` first, then Core `SurfaceElements`, then `Surfaces` (the `talos.feature.name`
+  `Message` is left behind on purpose). **FIXED prod-readiness** (developer caught it): Core and
+  `Client_*` are on **separate clusters** in prod, so the client file's `JOIN Core.SurfaceElements`
+  cannot run there — restructured into **Section A** (single-cluster join, local/beta only),
+  **Section B** (read-only `SELECT` on the Core cluster printing ids + a paste-able `VALUES` body),
+  **Section C** (literal-id guarded `INSERT` on the client cluster), with rollback/verify in both
+  forms. **De-qualified the Core file** (`Core.Messages` → `Messages`) because api2 can rename the
+  Core schema via `[database] core_dbname`, while the per-client file **keeps** its `Client_Nychh.`
+  qualification so a wrong-cluster run fails loudly rather than granting another tenant the feature.
+  DISCOVERED that **`SurfaceOverrides`' unique key protects a client-wide grant not at all** — MySQL
+  treats NULLs in a unique key as distinct, and a client-wide grant is `personaId`/`roleId`/
+  `languageId` all NULL, so the `NOT EXISTS` guard is the *only* thing making a re-run idempotent.
+  Verified against the real DDL: `iconToken` nullable, `NEUTRAL`/`BUTTON`/`TEXT`/`LEFT` valid,
+  `Surfaces.type DRAWER` exists, `Surfaces` UNIQUE KEY is `(slug, appId)`. Run state: **local only**
+  (`navigation` = surface 39, appId 1). The first attempt consumed `SurfaceElements` **216–220** under
+  the old per-element shape; those were torn down and re-created under the two-element shape, so local
+  ids advanced again — **element ids are `AUTO_INCREMENT` and therefore per-environment**, which is
+  why prod reads them off Core in Section B. **Beta and prod NOT yet run.** (apeterson)
 - 2026-08-31 — Added the **denial-details** seed pair (`Core/2026-08-31a -
   SalesOrderDenialDetailsSurfaceSeed.sql` — Surface **47**, elements **170–176**, Messages
   **227–232**, plus a `readOnlyRule` marker on surface 41; and `Client_Compass/2026-08-31a -

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/advanced-select.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/AdvancedSelect/AdvancedSelect.tsx
@@ -62,6 +62,14 @@ Common (`AdvancedSelectBaseProps<T>`): `data: T[]`, `getOptionValue/getOptionLab
 
 - **`renderOption` prop is declared but unused** — option rendering is hardcoded (primary +
   secondary label, check/checkbox, avatar). Treat custom rendering as not yet supported.
+- **⚠ GAP: there is NO footer / pinned-action slot.** A select that needs a persistent action in the
+  panel — the common "+ Add contact" when the option list is empty or wrong — cannot be built with
+  `AdvancedSelect` today. **And the obvious workaround does not work:** a sentinel option pushed into
+  `data` is **filtered out by the built-in search**, i.e. it disappears exactly when the user has
+  typed something and most needs it. Adding a real footer slot (rendered outside the virtualizer and
+  outside the search filter) is the fix; until then this pushes consumers to app-local selects.
+  Worked example: toga25-supply's app-local `PanelSelect` in the Create Transfer Order modal —
+  [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 - Single-select with a `secondaryLabel` and menu closed shows a styled two-line value; the
   native input collapses to width 0 (`.inputCollapsed`).
 - Selected-float-to-top is **not** configurable.
@@ -70,4 +78,9 @@ Common (`AdvancedSelectBaseProps<T>`): `data: T[]`, `getOptionValue/getOptionLab
 - No built-in required validation or full ARIA listbox/option roles (aria-labels on buttons only).
 
 ## Change history
+- 2026-09-02 — Recorded a real **gap**: `AdvancedSelect` has **no footer / pinned-action slot**, and
+  a sentinel option placed in `data` is filtered out by the component's own search — so a select that
+  needs a persistent "+ Add …" action cannot use it. This is why toga25-supply built an app-local
+  `PanelSelect` for the Create Transfer Order modal instead of consuming blox. Suggested fix: a
+  footer slot rendered outside the virtualizer and outside the search filter. (apeterson)
 - 2026-06-23 — Documented AdvancedSelect: virtualization, client/server search with abort, infinite scroll, keyboard nav, single/multi modes, and the unused `renderOption` caveat (apeterson).

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