toga-ai 1.0.746 → 1.0.747

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/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/toga25-supply/INDEX.md

@@ -14,7 +14,7 @@
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host, live Aegra streaming, LangGraph→blox mapper)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/api/talos.ts, toga25-supply/src/hooks/useTalosSession.ts, toga25-supply/src/hooks/useTalosThreads.ts, toga25-supply/src/hooks/useTalosThreads.test.ts, toga25-supply/src/hooks/useTalosSurface.ts, toga25-supply/src/hooks/useTalosSurface.test.ts, toga25-supply/src/App.tsx, toga25-supply/db-migrations/PLAYBOOK.md, dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, toga25-supply/src/providers/TalosStreamProvider.tsx, toga25-supply/src/utils/talosMessages.ts, toga25-supply/src/utils/talosMessages.test.ts, toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
-| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.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 |
+| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/PanelSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/ContactSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/SelectTargetLocationModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferItemPickerTable.tsx, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderNote.php, _underscore/Model/Client/TransferOrderNoteType.php, dbchanges2/Client/2026-09-01b - TransferOrderNotesTables.sql, dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql, dbchanges2/Core/2026-09-01c - TransferOrderNotesRecords.sql, dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql, toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.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 |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/.env.development |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |
 | [Porting a page (or query) from toga2-supply to toga25-supply](workflows/porting-a-page-from-toga2-supply.md) | `toga25-supply` re-implements pages that already exist in `toga2-supply`. | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/components/ui/Tables/hooks/useExportableData.tsx |

package/knowledge/2.0/apps/toga25-supply/features/talos-integration.md

@@ -29,6 +29,7 @@ files:
   - toga25-supply/src/assets/talos-owl.png
 related:
   - ../../toga-blox/features/talos-assistant.md
+  - ../../toga-blox/features/table-record-modal.md
   - ./surface-frontend.md
   - ../../dbchanges2/features/surface-layer-schema.md
   - ../../../clients/nychh/features/talos-assistant-enablement.md
@@ -139,15 +140,21 @@ navigation side effects (`onOpenRecord` → `/sales-orders?sales-orders=<id>`, `
 ### `useTalosSurface()` — the DB feature gate (2026-09-02)
 
 Reads the Core surface `talos-assistant` (type `DRAWER`, not record-bound) and returns
-**whether Talos is on for this tenant** plus the suggestion chips. Two element roles in the
-bundle:
+**whether Talos is on for this tenant** plus the suggestion chips. **TWO elements** in the bundle:
 
-| `config.role` | Meaning |
+| Element | Meaning |
 |---|---|
-| `featureEnabled` (one element, `config.key = 'feature'`) | **master switch** — its `isVisible` turns the launcher, the panel and the Aegra stream on or off |
-| `suggestion` (four elements) | one chip each: `labelMessageId` → label, **`config.prompt`** → the question actually sent, `iconToken`/`iconWeightToken` → icon, `sortOrder` → order |
-
-Chip keys: `pendingApproval`, `blockedApprovals`, `pendingFulfillment`, `statusCounts`.
+| `config.role = 'featureEnabled'`, `config.key = 'feature'` | **master switch** — its `isVisible` turns the launcher, the panel and the Aegra stream on or off |
+| `config.role = 'suggestion'`, `config.key = 'suggestions'` | **the whole chip row in ONE element.** `config.items` is an ordered array of `{label, prompt, icon}` (`icon` = a literal FontAwesome name). Its `isVisible` switches the entire row. |
+
+**⚠ SUPERSEDED: chips were briefly ONE ELEMENT PER CHIP** — four `config.role='suggestion'`
+elements with `labelMessageId` / `config.prompt` / `iconToken` / `sortOrder` and keys
+`pendingApproval`, `blockedApprovals`, `pendingFulfillment`, `statusCounts`. **That shape is gone.**
+There is no `config.prompt` and no per-chip `sortOrder`; **order is array order.** Reason: per-chip
+elements meant a tenant could only switch on wording **Core** had already seeded, so rephrasing a
+tenant's own business question needed a Core migration. One element lets a tenant author its own set
+in a single `CONFIG` override. Costs (labels not translatable; whole sets scope, not chips):
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
 
 **The FE FAILS CLOSED — deliberately, not defensively.** Missing bundle, failed fetch, absent
 marker element, or *still loading* all resolve to **disabled**. Talos answers questions from a
@@ -157,6 +164,19 @@ read as "on".
 `TalosStreamProvider` gained an **`enabled`** prop off the back of this: a tenant without Talos
 never even calls `GET /assistants`.
 
+#### `readItems` is TOLERANT on purpose — one bad item costs one chip
+
+`config.items` is a **hand-edited JSON column that differs per tenant**, so `readItems` **skips a
+malformed item instead of throwing**. One bad entry in a tenant's `CONFIG` override must cost them
+**one chip** — not every chip, and not a render crash. **14 tests** cover: `null`, a bare string, a
+number, a missing `label`, a whitespace-only `label`, a non-string `icon`, `items` absent, `items`
+not an array, and **array order being the authored order**.
+
+🚨 **The gate the FE cannot defend against:** a tenant `CONFIG` override that omits
+`"role":"suggestion"` **wipes** it (a `CONFIG` override replaces `config` wholesale — verified at
+`_underscore Model/Core/Surface.php:839`, no merge). The element then no longer matches, the chips
+**silently disappear**, and there is no error anywhere. That is a seeding rule, not a parser fix.
+
 Seeding side, the marker-element choice, and the prod-cluster procedure:
 [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
 
@@ -242,6 +262,20 @@ turns in `message`, which renders an **empty bubble**. Caught only by writing th
 
 Anyone writing to `TalosMessageModel` by hand will hit this.
 
+## Gotcha — the launcher greys out under a modal via a ROOT ATTRIBUTE, and keyboard access is still open
+
+blox `TableRecordModal` sets **`data-blox-modal-open` on `document.documentElement`** while open, and
+blox dims the launcher under `:root[data-blox-modal-open]`. It applies to **every** `TableRecordModal`
+in supply automatically — do not add a per-page dim. Why an attribute and not a prop: the launcher
+renders in the **header**, outside the modal's subtree, so no shared React state reaches it (same
+boundary-crossing trick as `--talos-dock-width`). Mechanism + the counter it needs:
+[TableRecordModal](../../toga-blox/features/table-record-modal.md).
+
+🚨 **Known gap, unfixed:** the launcher is still **keyboard-reachable** behind a modal.
+`pointer-events: none` stops the mouse only. Supply's header receives `inert` for the **side nav**
+but **not** for modals — closing this is a **supply** change that affects every header control, so it
+was flagged rather than patched.
+
 ## Gotcha — reserve dock width on the OUTER wrapper, not just `<main>`
 
 The docked panel is `position: fixed`, full-height on the right. The blox `Header` is in **normal
@@ -313,8 +347,13 @@ user resend. Decide deliberately rather than discovering it in QA.
 - 2026-09-02 — **Talos is now SURFACE-GATED, and OFF for every client by default** (this
   **corrects** the old "enabled for ALL clients, no per-client gating"): new `useTalosSurface()`
   reads the Core `talos-assistant` surface for a `config.role='featureEnabled'` **marker element**
-  (master switch) plus four `config.role='suggestion'` chips whose text lives in `config.prompt` —
-  replacing blox's hardcoded `DEFAULT_SUGGESTIONS`. The FE **fails closed**: missing bundle, failed
+  (master switch) plus **ONE** `config.role='suggestion'` element whose `config.items` is an ordered
+  array of `{label, prompt, icon}` — replacing blox's hardcoded `DEFAULT_SUGGESTIONS`. (**Superseded
+  mid-session:** the first cut was one element **per chip** with `config.prompt`/`sortOrder`; per-chip
+  elements meant only **Core** could author a tenant's wording, so one element + a tenant `CONFIG`
+  override replaced it. `readItems` is deliberately tolerant — a malformed item is **skipped**, not
+  thrown, so one bad entry in a hand-edited tenant config costs one chip, not the row; 14 tests.)
+  The FE **fails closed**: missing bundle, failed
   fetch, absent marker, or still-loading all resolve to disabled, and `TalosStreamProvider` gained
   an `enabled` prop so an ungranted tenant never calls `/assistants`. **NYCHH is the only granted
   tenant.** **BUILT the history drawer + new chat** (`useTalosThreads` maps Aegra threads → blox
@@ -330,7 +369,10 @@ user resend. Decide deliberately rather than discovering it in QA.
   `isError` on a failed **background** refetch while keeping the data, so one bad 4s poll flipped a
   good list into error; new pure `threadsStatusFrom` returns `"error"` only when there is nothing to
   show. Excluded the **`talos`** query namespace from the `localStorage`-persisted cache (chat
-  titles + assistant ids are session data). (apeterson)
+  titles + assistant ids are session data). **FIXED the launcher not greying out under a record
+  modal** — blox now marks `data-blox-modal-open` on the root element and dims the launcher; the
+  cause was **not** z-index. **Known gap flagged, not fixed:** the launcher stays **keyboard**-
+  reachable behind a modal, and closing that is a supply header (`inert`) change. (apeterson)
 - 2026-09-01 — **BUILT the live streaming integration.** Added `src/api/talos.ts` (env chokepoint +
   runtime `GET /assistants` lookup — `assistantId` is **per-tenant**, never pinned in env),
   `useTalosSession` (gates on `isAuthenticated`, not on a token, because blox leaves a **public**

package/knowledge/2.0/apps/toga25-supply/features/transfer-orders-page.md

@@ -9,6 +9,18 @@ status: active
 updated: 2026-09-02
 owners: [apeterson, bala]
 files:
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/PanelSelect.tsx
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/ContactSelect.tsx
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/SelectTargetLocationModal.tsx
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferItemPickerTable.tsx
+  - _underscore/Model/Client/TransferOrder.php
+  - _underscore/Model/Client/TransferOrderNote.php
+  - _underscore/Model/Client/TransferOrderNoteType.php
+  - dbchanges2/Client/2026-09-01b - TransferOrderNotesTables.sql
+  - dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql
+  - dbchanges2/Core/2026-09-01c - TransferOrderNotesRecords.sql
+  - dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql
   - toga25-supply/src/pages/TransferOrders/TransferOrders.tsx
   - toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts
   - toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx
@@ -50,6 +62,11 @@ related:
   - ../../../../clients/nychh/profile.md
   - ../../../../clients/nychh/features/transfer-order-inventory-quantities.md
   - ../../worker2/features/netsuite-transferorder-outbound-push.md
+  - ../../api2/features/nested-relationship-writes.md
+  - ../../_underscore/features/note-record-authorship.md
+  - ../../toga-blox/features/advanced-select.md
+  - ../../toga-blox/features/primary-table-templates.md
+  - ../../../standards/frontend.md
 ---
 
 ## Summary
@@ -62,12 +79,13 @@ reserved-id seed → per-tenant TableView → per-tenant nav opt-in → surface-
 **It was fully greenfield.** An audit of production, beta, sandbox-client **and all 36 client
 databases** on 2026-08-28 found **no transfer-order TableView anywhere**. Nothing was extended.
 
-A **Create Transfer Order** modal was started the same day and **reworked on 2026-09-01** against
-the live Claude Design export. Its data layer is wired (two of the three blocking data-model
-*questions* dissolved — availability comes from per-PO-line `_qty*`, and Locations are flat) and the
-order is scoped by a **purchase-order lock**, not by source location. 🚨 **But the picker still
-shows nothing for NYCHH**: every PO line reports availability 0 because of an upstream data gap,
-which is an open integration decision — see the blocker below.
+A **Create Transfer Order** modal was started the same day, **reworked on 2026-09-01** against the
+live Claude Design export, and **completed end to end on 2026-09-01/02** (front end + framework model
++ Core metadata + client schema). It now writes the whole transfer — header **and** every line — in a
+**single POST** with the lines nested under `transferOrderItems`, and the order is scoped by a
+**purchase-order lock**, not by source location. 🚨 **The picker still shows nothing for NYCHH**:
+every PO line reports availability 0 because of an upstream data gap, which is an open integration
+decision — see the blocker below (a dev-only env flag exists to test around it locally).
 
 The vertical is **platform-shared with NYCHH as the first (and today only) tenant**: the Core
 surfaces and the stage theme tokens are neutral/shared, and only the TableView and the navigation
@@ -85,6 +103,10 @@ tenant.
 | `Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql` | one tenant | reproduces the **untracked** record/field ACL prod already has for records 312/313 |
 | `Client/2026-08-28b - TransferOrderItemsTimestamps.sql` | all tenants (template) | `TransferOrderItems.dtCreated`/`dtUpdated` (+ indexes), guarded `qtyCommitted` |
 | `Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql` | Core | the `transfer-orders-list-actions` BUTTON_BAR + `common.columns.modal.*` Messages |
+| `Client/2026-09-01b - TransferOrderNotesTables.sql` | all tenants (template) | `TransferOrderNotes` + `TransferOrderNoteTypes` — **ship empty and are currently UNUSED** (see the Notes decision) |
+| `Core/2026-09-01c - TransferOrderNotesRecords.sql` | Core | Records **357**/**358**, RecordFields **2550–2560**, `InherentRecordChildren` 312→357 — **also unused, and 357/358 have NO NYCHH ACL grant** |
+| `Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql` | all tenants (template) | `TransferOrders.contactId` (FK Contacts), `createdByUserId` (FK Users), `description varchar(255)` |
+| `Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql` | Core | RecordFields **2561** `contactId` / **2562** `createdByUserId` / **2563** `description` on record 312, + `AclFieldPermissions` for roles **1** and **3** |
 
 All of them were audited against the cluster-isolation HARD RULE: **no `Core.*` reference in any
 `Client_*` file** (the only such strings are inside comments), no `UUID()`, all table references
@@ -217,14 +239,18 @@ literal is repointed** — nothing in the database enforces it.
 `useFetchSurfaceMetaGroup` pulls **all four record surfaces in one call**, and the view renders
 entirely from them: labels, column set, ordering, visibility. There is no hardcoded field list.
 
-**Two record requests, not one.** `TransferOrders` (record 312) has **no `InherentRecordChildren`
-row** (sales-orders/14 has seven), so `transferOrderItems` does *not* come back nested inside the
-record fetch the way `salesOrderItems` does. The modal reads the lines from the nested route
+**Two record requests, not one.** The modal reads the lines from the nested route
 `GET /v2/transfer-orders/{uuid}/transfer-order-items`, with the child route read from the items
-surface's `config.childRoute` so the FE never hardcodes it. Adding the `InherentRecordChildren` row
-was **deliberately declined** — it changes the default response shape for *every* existing
-`/transfer-orders` caller including the 1.0 NetSuite importer, and that blast radius was out of
-scope to verify. See [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).
+surface's `config.childRoute` so the FE never hardcodes it.
+
+> ⚠ **The reason for the second request is GONE — the read path was not revisited.** This build
+> declined to add the `InherentRecordChildren` row (it changes the default response shape for
+> *every* existing `/transfer-orders` caller, including the 1.0 NetSuite importer). **That decision
+> was reversed later:** `Core.InherentRecordChildren` row **152** now declares
+> `transfer-orders` (312) → `transfer-order-items` (313), so `/transfer-orders` **does** inline
+> `transferOrderItems` today. The modal still makes two calls; collapsing it to one is available but
+> unclaimed work. See
+> [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).
 
 **The record fetch raises `calcDepth` to 2.** `_Model_Client_Location` exposes
 `_addressLine1/_addressLine2/_addressCity/_addressState/_addressZip` as `FIELD_SQL` calculated
@@ -356,9 +382,163 @@ Related data-shape facts found the same day:
   an inline **Add Contact** path (`AddContactModal.tsx` + `useCreateLocationContact`).
 - **The populated join table is `Contacts_Locations`** (route `/contact-locations`, **Record 76**) —
   **not** `Locations_Contacts`. Binding the reversed name finds nothing.
-- **`TransferOrders` has NO notes/description column.** The notes field's persistence is an **open
-  decision**: either `TransferOrders.description varchar(255)` (mirroring `SalesOrders`) or a
-  `TransferOrderNotes` child table (mirroring `SalesOrderNotes`). Nothing is written yet.
+- ~~**`TransferOrders` has NO notes/description column**~~ — **closed 2026-09-01: `description
+  varchar(255)`.** Both candidates were actually built; see
+  [the Notes decision](#the-notes-box-writes-transferordersdescription--the-transferordernotes-tables-are-built-and-unused).
+
+### The whole transfer is ONE POST — lines nested under `transferOrderItems`
+
+`hooks/useCreateTransferOrder.ts`. Header **and** every line go out in a **single
+`POST /transfer-orders`**, with the lines nested under the key **`transferOrderItems`**. This is
+possible because `Core.InherentRecordChildren` row **152** now makes `transfer-order-items` (313) an
+inherent child of `transfer-orders` (312).
+
+**Why one request, not three.** An earlier draft posted the header and then each line separately and
+could leave a **half-written transfer** behind on a mid-sequence failure. One API request is one
+API transaction — the front controller commits the umbrella connection on `isSuccess` and rolls the
+data back on failure — so the nested POST is all-or-nothing **without** a scripted endpoint.
+
+> **DECIDED: no scripted API endpoint for transfer create.** Weighed with Jeff and dropped. The
+> inherent-child single POST already gives the atomicity a scripted endpoint would have been written
+> for, so the extra surface is not worth it.
+
+**The nested write key is the child ROUTE in camelCase — verified in the engine, not guessed.**
+`V2.php:3248` builds the lookup by converting each inherent child's `route` from kebab to camel, and
+`V2.php:5241` uses that **same** lookup on the CREATE path (`$childrenToCreate[$key] = $val`). So
+**renaming the Core route renames the payload key for every writer**, with nothing in the database
+to warn you. Engine detail and the read-side twin:
+[v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).
+
+This closes both **required POST changes** recorded on 2026-09-02: `number` is no longer sent (so
+`FIELD_AUTOINCREMENT` mints the `TA100000` sequence) and the lines ride nested in the same request
+(so `_Model_Client_TransferOrder::postPost` sees them when it reads the order back for the NetSuite
+push) — see
+[Toga TransferOrder → NetSuite Push](../../worker2/features/netsuite-transferorder-outbound-push.md).
+
+**FKs go out as nested `{ uuid }` objects under the field name WITHOUT the `Id` suffix** —
+`contact: { uuid }`, `createdByUser: { uuid }`. Each is omitted entirely when absent rather than sent
+as `null`: a location can have no contact, and an SSO session can lack a user uuid.
+
+### `TransferOrders.contactId` / `createdByUserId` / `description` — new schema, model and metadata
+
+`Client/2026-09-01c` adds the three columns, `_underscore/Model/Client/TransferOrder.php` declares
+them, and `Core/2026-09-01d` adds RecordFields **2561** (`contactId`), **2562** (`createdByUserId`),
+**2563** (`description`) on record 312 plus `AclFieldPermissions` for roles **1** and **3**. This is
+what replaced the Target Contact element's placeholder `valueKey` with a real binding.
+
+> ⚠ **`createdByUserId` is CLIENT-SUPPLIED and therefore only as trustworthy as the client.** The FE
+> reads the signed-in user's uuid from the **`user` localStorage key** and posts it. Nothing stamps
+> it server-side from the JWT. This matches the existing SalesOrders precedent, which is the only
+> reason it was done this way — **still open with Jeff** whether the platform should stamp it from
+> the token instead.
+
+### The Notes box writes `TransferOrders.description` — the `TransferOrderNotes` tables are built and UNUSED
+
+`view/TransferNotesField.tsx` + `hooks/useCreateTransferOrder.ts`. **DECIDED:** a transfer carries
+**one free-text description**, not a thread of typed notes from different authors, so the modal's
+Notes box writes `TransferOrders.description` (`varchar(255)`). The front end hard-caps the textarea
+at `DESCRIPTION_MAX_LENGTH = 255` so the tail is never silently truncated on save.
+
+🚨 **Consequence: `TransferOrderNotes` / `TransferOrderNoteTypes` and their Core metadata are now
+dead weight.** They were built earlier the same session (mirroring `PurchaseOrderNote` /
+`PurchaseOrderNoteType` exactly) and are **already migrated**, but **nothing reads or writes them**:
+
+- `Client/2026-09-01b` creates both tables — they **ship empty**.
+- `Core/2026-09-01c` seeds Records **357** (`transfer-order-notes`) / **358**
+  (`transfer-order-note-types`), RecordFields **2550–2560**, and `InherentRecordChildren` 312→357.
+- `_underscore/Model/Client/TransferOrderNote.php` + `TransferOrderNoteType.php`.
+- ⚠ **Records 357/358 have NO NYCHH ACL grant**, so even a deliberate caller gets `EZ-1` today.
+
+**Whether to drop them is an open question for Jeff** (see the open-items list). Leaving them is
+harmless but they are a trap for the next reader: the tables exist, so "notes are supported" looks
+true from the schema alone.
+
+Wider platform finding from building them:
+[note-record authorship is not recorded anywhere](../../_underscore/features/note-record-authorship.md).
+
+### Target Location picker + target-contact scoping
+
+`view/SelectTargetLocationModal.tsx`, `hooks/useTargetLocationOptions.ts`,
+`hooks/useLocationContacts.ts`, `hooks/useCreateLocationContact.ts`.
+
+- **Flat-list picker with debounced search.** The breadcrumb path is assembled from
+  `parentLocation.uuid` **with a cycle guard** — a self- or mutually-parented row would otherwise
+  loop forever.
+- **Target Contact options come from `Contacts` through the `Contacts_Locations` junction**, scoped
+  to the selected location.
+- **`Locations` deliberately does NOT get a contact FK.** The junction is the right place, and it is
+  genuinely **many-to-many** (a location can have several contacts). That kills the tempting
+  `UNIQUE(locationId, type)` idea outright — **only `isPrimary` is a viable "the one contact"
+  marker**, and how it is scoped/enforced is still open with Jeff.
+- **With NYCHH's data the common case is an EMPTY list** (2 of 31 locations have any contact at
+  all), so "+ Add contact" is usually the only clickable thing in the panel. Design accordingly —
+  an empty contact select here is normal, not a fetch bug.
+
+### `PanelSelect` — ONE app-local select control for the whole modal
+
+`view/PanelSelect.tsx`, consumed by `view/ContactSelect.tsx` and `CreateTransferOrderModal.tsx`.
+
+The Claude Design mockup draws **Target Contact and the purchase-order filter with the same
+control** (`window.FormSelect`), so they are **one component** here rather than two lookalikes:
+38px trigger, search box inside the panel, green check on the chosen row, optional pinned footer
+action, optional clear (×). `ContactSelect` is now a thin mapping over it. The PO filter is 200px,
+carries **"All POs" as a ROW in the list** (not a clear button), and goes disabled with a lock
+tooltip while lines are selected.
+
+**Built app-local on purpose, per [front-end standard §21](../../../standards/frontend.md)** —
+promote to blox only after a second consumer. blox's `AdvancedSelect` could not serve it today:
+it has `renderOption` but **no footer slot**, and a sentinel option pushed into `data` would be
+**filtered out by the very search that makes you want a pinned action**. Recorded as a blox gap on
+[AdvancedSelect](../../toga-blox/features/advanced-select.md).
+
+### "Show more" on the picker's item cell — copied from the primary table, rules and all
+
+`view/TransferItemPickerTable.tsx`. The rules come from blox `PrimaryTableBodyCell` (mechanism:
+[primary-table-templates](../../toga-blox/features/primary-table-templates.md)):
+
+1. The toggle is offered **only when the text is genuinely clipped**, measured **on hover** — not on
+   every render.
+2. The collapsed toggle's visibility is **CSS `group-hover`, NEVER React state.** A `mouseleave` is
+   not guaranteed to fire, so a JS-driven toggle can get **stuck on screen over an unhovered cell**.
+3. Expanded switches the cell to a column so the value wraps **above** a "Show less" toggle and the
+   row grows (body cells align top for this).
+4. The toggle **`stopPropagation`s** so it never checks the row it sits in.
+
+Colors come from the `--expandableCell-color-*` tokens. Cells cap at **300px** so truncation can
+trigger at all inside an auto-layout table; the items table maxes at **355px** (the design's figure).
+
+### Blank Item column — NYCHH leaves `Items.title` empty
+
+`hooks/usePurchaseOrderItemRows.ts`. The label chain is
+`item.title || item.description || "(untitled item)"`, and `vendorItem.item.description` was added to
+the requested `fields`.
+
+**Deliberately NOT falling back to a part number** — Part Number already has its own column, so that
+would duplicate a cell instead of naming the item. **The real fix is populating `Items.title`.**
+
+### ⚠ `VITE_TRANSFER_IGNORE_AVAILABILITY` — LOCAL TESTING ONLY, never in a deployed environment
+
+`hooks/usePurchaseOrderItemRows.ts` line ~91. With `VITE_TRANSFER_IGNORE_AVAILABILITY=true` the
+picker falls back to the PO line's own `quantity` instead of `_qtyAvailable`, so the create flow can
+be exercised while the `_qty*` blocker above is unresolved.
+
+> 🚨 **This disables the guard that stops a transfer requesting more than can be dispatched.** It
+> must **never** be set in any deployed environment — dev/local only.
+
+### Where the ground truth for this UI lives
+
+**Claude Design project `84fed1b2-b1ab-4243-9354-5d04f861bca0`:**
+
+| Thing | File in that project |
+|---|---|
+| the transfer modal mockup | `demo/transfer-modal.jsx` |
+| the shared select it uses (`window.FormSelect`) | `src/form-select.jsx` |
+| the PO-filter wrapper (200px, doubles as the lock) | `FilterLockSelect` |
+| written ground truth | `ground-truth-transfer-orders.md`, `ground-truth-transfer-orders-v2.md` |
+
+**Read the mockup source, not a screenshot.** The 2026-09-01 rework happened precisely because the
+first pass had been built from an image and diverged (one shared select vs. two, "All POs" as a row
+vs. a clear button).
 
 ### Line-item fetch is off behind a FLAG, not commented out
 
@@ -380,8 +560,10 @@ Money (Unit Value / Total / Total Value) and Target Contact are **dropped for v1
 `SurfaceElements` with `isVisible = 0`**, so enabling any of them later is a one-row client override
 rather than another Core migration.
 
-⚠ `TransferOrders` carries **no contact FK at all** today, so the Target Contact element's
-`valueKey` is a **placeholder** that needs a real binding before any client turns it on.
+~~⚠ `TransferOrders` carries **no contact FK at all** today, so the Target Contact element's
+`valueKey` is a **placeholder**~~ — **closed 2026-09-01.** `TransferOrders.contactId` (FK
+`Contacts`) exists and RecordField **2561** is granted to roles 1 and 3, so the element has a real
+binding and enabling it is now genuinely a one-row client override.
 
 The items table's **PO column is order-level**: `TransferOrderItems` has no line-level PO, so the
 column binds the parent order's `purchaseOrder.number` and repeats on every row. For NYCHH it
@@ -413,15 +595,33 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
 - **Open dependency:** `Client/2026-08-28a` writes to `ThemeTokens`, a table created by
   `Client/2026-06-25a - SurfaceClientTables.sql`. Any prod tenant that never received `2026-06-25a`
   will error, and the full 36-tenant list was **not** audited.
-- **🚨 Two REQUIRED changes to the Create Transfer Order POST (2026-09-02), both for the new
-  NetSuite push.** The push is triggered from `_Model_Client_TransferOrder::postPost` — see
-  [Toga TransferOrder → NetSuite Push](../../worker2/features/netsuite-transferorder-outbound-push.md):
-  1. **Drop `"number"` from the POST body.** The modal currently sends e.g.
-     `"number": "286906"`, and `FIELD_AUTOINCREMENT` only generates the new `TA100000` sequence when
-     `number` arrives **NULL** — a supplied value silently wins, with no error.
-  2. **Send `transferOrderItems` NESTED in the same POST.** `postPost` reads the order back
-     in-request; if the lines are posted in separate calls afterwards it sees **zero lines** and the
-     push aborts (and the trigger would have to move).
+- ~~**🚨 Two REQUIRED changes to the Create Transfer Order POST (2026-09-02)**~~ — **both done
+  2026-09-01/02.** `number` is no longer sent (so `FIELD_AUTOINCREMENT` mints the `TA100000`
+  sequence) and `transferOrderItems` rides **nested in the same POST** (so
+  `_Model_Client_TransferOrder::postPost` sees the lines when it reads the order back for the
+  NetSuite push). See
+  [the single-POST section](#the-whole-transfer-is-one-post--lines-nested-under-transferorderitems).
+- **Nothing was committed in ANY application repo for the 2026-09-01/02 work.** All of it — the
+  toga25-supply modal, `_underscore/Model/Client/TransferOrder*.php`, and the four new `dbchanges2`
+  files — sits **uncommitted in the working tree on branch `features-talos-transferorders`**. Treat
+  the migration ids as **reserved but unshipped** until that lands.
+
+### 🚩 Open items handed to Jeff (questions, NOT decisions)
+
+None of these is settled; do not read a resolution into the code that exists.
+
+1. **`TransferOrders.number` has no minter — rows get NULL.** The front end deliberately does
+   **not** mint `MAX(number)+1`, because two concurrent creates would race. (`FIELD_AUTOINCREMENT`
+   mints `TA100000` only where that model change is deployed — see the push doc.)
+2. **`transferOrderStageId` is not set on create.** Nobody knows which `TransferOrderStages` row
+   NYCHH treats as the opening stage.
+3. **`createdByUserId`: client-supplied vs. JWT-stamped server-side.** Today it is client-supplied
+   from `localStorage`, matching SalesOrders.
+4. **`Contacts_Locations.isPrimary`: per-location or per-type, and how is it enforced?** The junction
+   is many-to-many, so a unique index on `(locationId, type)` is wrong.
+5. **The `_qty*` = 0 blocker** (see above) — integration/data-owner decision.
+6. **Whether to drop the now-unused `TransferOrderNotes` tables + Core metadata** (records 357/358,
+   RecordFields 2550–2560, `InherentRecordChildren` 312→357).
 - ~~No `transfer-orders-list-actions` BUTTON_BAR surface~~ — **closed** by `Core/2026-08-28b`
   (Surface 52, elements 187–189); the header is now `SurfaceActionBar`-driven like Sales Orders.
 - **Test data lives in the session scratchpad, never in dbchanges2** (24 seed orders + an unseed
@@ -480,6 +680,23 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
   literal `name`.
 - **`calcDepth` defaults to 1**, so a calculated field on a record one FK hop out returns NULL with
   no error. Raise it explicitly when the payload crosses an FK.
+- **⚠ Request FK fields as DOTTED PATHS, never as the bare column name.** The convention in this
+  repo is `vendorItem.item.title` / `parentLocation.uuid` — a bare `parentLocationId` in `fields`
+  **silently returns nothing**. FKs then **write** as nested `{ uuid }` objects under the name
+  *without* the `Id` suffix (`contact: { uuid }`). Both halves were got wrong once this session.
+- **⚠ The nested WRITE key for an inherent child is the child ROUTE in camelCase.** Renaming a Core
+  route renames every writer's payload key, with no database-level warning
+  (`V2.php:3248` builds the lookup, `:5241` consumes it).
+- **⚠ A collapsed "Show more" toggle must be hidden by CSS `group-hover`, not React state** — a
+  `mouseleave` is not guaranteed to fire, so a state-driven toggle gets stuck on screen over a cell
+  nobody is hovering.
+- **⚠ `VITE_TRANSFER_IGNORE_AVAILABILITY` disables the over-transfer guard** — local only, never in
+  a deployed environment.
+- **`TransferOrderNotes` exists but is dead.** The tables + Core metadata are migrated and empty;
+  notes persist as `TransferOrders.description`. Schema alone will mislead you here.
+- **A note row's author is not recorded anywhere on the platform** — every `*Notes` model declares a
+  `contactId` that no code writes. See
+  [note-record authorship](../../_underscore/features/note-record-authorship.md).
 - **`_Model_Client_Item` has no `name` field** — the item title/description live in `partNumber`,
   `title`, `description`, `longDescription` (`Item.php:39-45`). Binding `name` yields nothing.
 - **`Client_Nychh` `AclFieldPermissions` on the Location address fields (Core RecordFields 70–74)
@@ -489,6 +706,37 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
   earlier migration without names, so a name-based lookup on them finds nothing.
 
 ## Change history
+- 2026-09-02 — **Finished the Create Transfer Order modal end to end** (front end + framework model +
+  Core metadata + client schema) and **closed both required POST changes**: the transfer now writes
+  header and every line in **ONE `POST /transfer-orders`** with the lines nested under
+  `transferOrderItems`, made possible by `InherentRecordChildren` row **152** (312→313). Verified in
+  the engine that the nested **write** key is the child **route** in camelCase — `V2.php:3248` builds
+  the kebab→camel lookup and `V2.php:5241` reuses it on the CREATE path — so renaming a Core route
+  renames every writer's payload key. **DECIDED: no scripted API endpoint** (the single POST is one
+  API transaction, so it is atomic already). **DECIDED: the Notes box writes
+  `TransferOrders.description` (varchar 255, FE hard-capped)**, which leaves the
+  `TransferOrderNotes`/`TransferOrderNoteTypes` tables + Core records 357/358 + RecordFields
+  2550–2560 **built, migrated, empty and UNUSED** (and 357/358 have no NYCHH ACL grant) — whether to
+  drop them is open. Added `TransferOrders.contactId` / `createdByUserId` / `description` with
+  RecordFields **2561–2563** and role 1/3 field ACL, which gives the previously-placeholder Target
+  Contact element a real binding; ⚠ `createdByUserId` is **client-supplied** from the `user`
+  localStorage key, not JWT-stamped. Built the Target Location picker (flat list, debounced search,
+  `parentLocation.uuid` breadcrumb with a cycle guard) and scoped Target Contact through the
+  many-to-many **`Contacts_Locations`** junction — so `Locations` gets no contact FK and only
+  `isPrimary` is a viable "the one contact" marker. Built **one app-local `PanelSelect`** for both
+  Target Contact and the PO filter (per front-end standard §21; blox `AdvancedSelect` has no footer
+  slot and would let its own search filter out a sentinel row), and copied blox's four "Show more"
+  rules into the picker's item cell. Fixed the blank Item column with
+  `title || description || "(untitled item)"` (NYCHH leaves `Items.title` empty; deliberately no
+  part-number fallback, which would duplicate an existing column). Added the **local-only**
+  `VITE_TRANSFER_IGNORE_AVAILABILITY` escape hatch — 🚨 it disables the over-transfer guard and must
+  never be deployed. Recorded that the FE convention for FK fields is **dotted paths**
+  (`vendorItem.item.title`), that the UI ground truth is Claude Design project
+  `84fed1b2-b1ab-4243-9354-5d04f861bca0` (`demo/transfer-modal.jsx`, `src/form-select.jsx`,
+  `FilterLockSelect`), and six **open questions for Jeff** (no `number` minter, unset
+  `transferOrderStageId`, `createdByUserId` ownership, `isPrimary` scoping, the `_qty*` blocker, and
+  the dead notes tables). Nothing was committed in any application repo — all of it sits on
+  `features-talos-transferorders`. (apeterson)
 - 2026-09-02 — Recorded two **required** changes to the Create Transfer Order POST, both driven by
   the new [TransferOrder → NetSuite push](../../worker2/features/netsuite-transferorder-outbound-push.md):
   **drop `"number"`** (the new `TA100000` `FIELD_AUTOINCREMENT` sequence only generates when `number`

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 78 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 79 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 59 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 15 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/nychh/features/transfer-order-inventory-quantities.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Nychh/Item.php
@@ -251,6 +251,34 @@ Until one of those lands, treat any NYCHH transfer-order availability figure as
 not as a bug to debug. Tracking the adjustment↔fulfillment link:
 [NYCHH inventory-adjustment → item-fulfillment linking](./netsuite-inventory-adjustment-fulfillment-link.md).
 
+#### Second reference row, and two more eliminations (2026-09-02)
+
+Re-hit on a **different** line and re-investigated from scratch, which is worth recording so the
+next person does not pay for it a third time. Reference row:
+`PurchaseOrderItems` uuid **`715ef031-003d-6742-871d-0d20de2fa40f`** (PO **80622**, line **21**).
+
+| Source | `quantity` | `_qtyReceived` | `_qtyFulfilled` | `_qtyOnHand` | `_qtyAvailable` |
+|---|---|---|---|---|---|
+| V2 API response | **3270** (correct) | 0 | 0 | 0 | 0 |
+| hand-run SQL on `Client_Nychh` | 3270 | **3270** | 0 | — | — |
+
+`quantity` coming back correct on the very same object is the tell that this is **not** a fetch,
+route, database or deploy problem. Two further eliminations from this pass:
+
+- **The values arrive as a literal `0`, not as `null` and not absent.** That rules out
+  `AclFieldPermissions` **and** an insufficient `calcDepth` in one step — both of those produce a
+  missing/`null` field, never a `0`. (Consistent with the rule now on
+  [v2-rest-query-contract](../../../2.0/apps/api2/features/v2-rest-query-contract.md): a calculated
+  field returning `0` is almost never an ACL problem.)
+- **No physical shadowing columns on `PurchaseOrderItems`.** A stored column of the same name would
+  win over the `FIELD_SQL` expression; the blank client template creates only **7** columns on that
+  table, so there is nothing to shadow.
+
+**The receipts genuinely exist** (3270 received on this line), so the numbers are recoverable — which
+is exactly the shape of option **(b)** above. Left **UNRESOLVED and handed to Jeff**; it needs the
+same integration/data-owner decision, and the evidence above narrows it to the override's stock-in
+source rather than anything in the request path.
+
 ### The role-3 grant migration is NOT the fix for the empty picker
 
 `dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql` grants **role 3 (API)**
@@ -385,6 +413,17 @@ pattern (default a NOT NULL non-writable column in the model, never send it) is
   session — and a *passing* drift check on the base `Model/Client/` file is what made it feel safe.
 
 ## Change history
+- 2026-09-02 — **Re-hit the `_qty*` = 0 blocker on a second line and narrowed it two steps further.**
+  Reference row `PurchaseOrderItems` uuid `715ef031-003d-6742-871d-0d20de2fa40f` (PO 80622, line 21):
+  the V2 API returns `quantity: 3270` **correctly** while `_qtyReceived`/`_qtyOnHand`/`_qtyAvailable`/
+  `_qtyFulfilled` all come back **0**, and hand-run SQL on `Client_Nychh` gives received **3270** —
+  the receipts DO exist. Newly eliminated: (a) the values arrive as a **literal `0`, not null and not
+  absent**, which rules out `AclFieldPermissions` *and* an insufficient `calcDepth` in one step, since
+  both of those produce a missing/null field; (b) there are **no physical shadowing columns** on
+  `PurchaseOrderItems` (the blank client template creates only 7). That leaves the deployed override's
+  inventory-adjustment stock-in source as the cause — i.e. the same open blocker, now with evidence
+  pointing at resolution option (b). Still **unresolved; handed to Jeff.** (apeterson)
+
 - 2026-09-01 — **Diagnosed the "API returns 0, hand-run SQL returns 40" report, and it turned into a
   data blocker rather than a bug.** The API ran `_Model_Nychh_PurchaseOrderItem`'s
   inventory-adjustment `_qtyReceived` while the hand-run check used the **base** item-receipt

package/package.json

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