toga-ai 1.0.882 → 1.0.884

package/knowledge/1.0/apps/tools/INDEX.md

@@ -9,6 +9,7 @@
 | [Compass User & Persona Admin (tools /compass/users, /compass/personas)](features/compass-user-persona-admin.md) | Two pages in the Tools `developers` nav folder that let staff do, in a browser, the Compass requests that used to mean "email a developer, who writes a `dbchang |
 | [Design Demo Admin](features/design-demo-admin.md) | SSO-gated Tools admin at `/design` that publishes self-contained "Claude Design" HTML exports as versioned demos into the `forward` repo over the GitHub REST AP |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | Tools "Developers" folder — the Generate UUID and Generate Password tools (reference example of the one-tool-per-`mvc/<route>/get.php` pattern); open for the ge |
+| [/emails Email Queue Review (Tools → 2.0 Logs_<Client>.Email)](features/email-queue-review.md) | Staff page to browse any 2.0 client's `Logs_<Client>.Email` queue and release/reject `HELD` review-hold emails. |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only 1.0 Tools triage/curation screen (`/errors`) for the 2.0 Issue/Event error pipeline, reading the shared Core Logs DB via `db_toga2logs`; curates, |
 | [GitHub Audit (monthly code-churn report)](features/github-audit.md) | Internal monthly code-churn report at `/developers/github-audit` (lines added/removed across every `agilantsolutions` repo for one month); open for the two-phas |
 | [Legacy Email Notifier (tools /email-migration/notify)](features/legacy-email-notifier.md) | SSO-gated admin tool at `/email-migration/notify` that emails employees a digest of mail still hitting their legacy domains (asks senders to switch to `@togatec |

package/knowledge/1.0/apps/tools/architecture.md

@@ -79,9 +79,17 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
 
 ## Gotchas
 
+- **Bare `<header>` violated again (2026-09-23, /emails)** — use a `<div>` with a page class; see Critical rules.
+- **The app-wide input rule outranks class selectors.** `style.css` ~line 769 styles inputs with five chained `:not()`; that specificity beats a page's class selector. A page restyling its inputs must repeat the same `:not()` chain under its page scope.
+- **`.app-content` caps width at 960px** unless the page root has `.tool--wide`.
+- **`.btn-secondary` and `.btn-secondary-outline` are RED (danger).** There is no neutral button class; do not use them for non-destructive actions.
+- **CSRF is not a token.** `App_Page::validateCrossSiteRequestForgery` checks Origin/Referer only; POST handlers rely on it.
 - **⚠ `tools` runs PHP 8, not 7.2 — check the vhost, not the framework label.** Despite being a 1.0 `App_` app, its vhost lives in the PHP 8 Apache (`DocumentRoot "C:/WWW/tools"`), and `App_Compass::tenantKey(mixed $key)` uses the `mixed` type hint (PHP 8.0+). The trap: `mixed` **passes** `php -l` on 7.2 (parsed as a class name) and only fatals at runtime — "Argument 1 passed to f() must be an instance of mixed, string given". So linting `tools` on 7.2 fails in the dangerous direction: it accepts code that would die.
 - **Plaintext secrets were publicly web-readable (fixed 2026-07-24; rotation still owed).** `config.*.ini` (incl. `config.prod.ini`) holds plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The front controller routed through `index.php` on a `RewriteCond !-f` rule **only**, which is not access control — a direct `GET /config.production.ini` served the file **verbatim**. Fixed 2026-07-24 by adding `<FilesMatch>` `Require all denied` blocks (sensitive extensions incl. `.ini`, and any `config.*`) — see the [1.0 back-end security standard](../../standards/backend-php.md). **Action still owed:** rotate every secret in `config.production.ini` — the file was reachable, so treat all of it as compromised. (Location only — no values recorded here.)
 - **Hardcoded GitHub Personal Access Token committed in plaintext (rotation owed).** `.ebextensions/020_setup_git_libraries.config` contains a GitHub PAT in plaintext, committed to the repo and therefore exposed in git history. **Action owed:** rotate the token and move it to an EB environment property (read via `getenv()`/`$_SERVER`/`$_ENV` per the deploy workflow's clear_env gotcha); a rotation does not un-expose git history. (Location only — no value recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.
 - **~~Unproxied third-party polling from the browser~~ (resolved 2026-08-18).** The monitor column used to pull ~250 KB from OneUptime cross-origin every poll (per open tab) and hardcode the status-page ID in the HTML. It is now served by a same-origin server-side proxy `/v2/monitors/status/` (`App_Clickup_Monitors`) that fetches, reduces to ~1 KB and caches ~5s (APCu), with the status-page ID in config — one upstream fetch shared across all tabs, no cross-origin dependency. See `features/oneuptime-monitor-status-panel.md`. **Framework gotcha found building it (prod incident CV-2):** never call `curl_close()` in App_ code — it is deprecated in PHP 8.5 and the strict error handler promotes that `E_DEPRECATED` to a fatal (500). It is a no-op since PHP 8.0; drop it (or `unset($ch)`).
 - **Framework-level Sentry error reporting is an open gap.** Prod printed "Sentry is not installed" because `sentry/sentry` was missing from `composer.json` (added `^4.10`; sibling apps use `^4.10`/`^4.19`). But even with Sentry in `vendor/`, the 1.0 framework does **not** auto-require `vendor/autoload.php` (the `App_Talos_S3` pattern `require_once`s it explicitly), so framework-level Sentry reporting for Tools still does not load. Any code path that needs a composer package must `require_once` the autoloader itself.
+
+## Change history
+- 2026-09-23 — Added gotchas from the /emails build: input :not chain, 960px cap/.tool--wide, red btn-secondary, Origin/Referer CSRF. (jcardinal)

package/knowledge/1.0/apps/tools/features/email-queue-review.md

@@ -0,0 +1,54 @@
+---
+title: /emails Email Queue Review (Tools → 2.0 Logs_<Client>.Email)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-09-23
+owners: ["jcardinal"]
+files:
+  - tools/_/app/emails.php
+  - tools/mvc/emails/get.php
+  - tools/mvc/emails/post.php
+  - tools/_/app/nav.php
+  - tools/assets/css/style.css
+related:
+  - ../architecture.md
+  - ../../../../2.0/apps/_underscore/features/email-send-pipeline.md
+  - ../../../../2.0/apps/_underscore/features/email-template-sending.md
+---
+
+## Summary
+
+Staff page to browse any 2.0 client's `Logs_<Client>.Email` queue and release/reject `HELD`
+review-hold emails. Nav: Developers group, Development Team persona only.
+
+## Key files / entry points
+
+- `tools/_/app/emails.php` — `App_Emails`: client list, queue queries, actions.
+- `tools/mvc/emails/get.php` / `post.php` — page + actions.
+- `tools/assets/css/style.css` — `.tool--emails` block.
+
+## How it works
+
+1. Client list from Core (`db_toga2core`). Queue queries go over `db_toga2logs` against one
+   `Logs_<Client>` db named from `Core.Clients.logDatabaseId`, checked against
+   `^Logs_[A-Za-z0-9]+$`. Never joins Core with Logs.
+2. Status tabs with counts, search, pagination, split-pane list/detail.
+3. Actions:
+   - **Approve** — guarded `UPDATE ... WHERE status='HELD'`, requires `affectedRows === 1`; sets
+     `PENDING`, `dtReviewed`, `reviewedBy` = staff email.
+   - **Reject** — `HELD` → `CANCELLED`, same guard.
+   - **Send copy** — new `PENDING` row + attachments via `INSERT ... SELECT`, PHP v4 uuid per row.
+4. Deep link `/emails?client=&emailId=` is the target of `[_underscore] email_review_url`.
+
+## Gotchas / known issues
+
+- Preview is an `<iframe sandbox="" srcdoc>` — the **only** XSS barrier for stored email HTML.
+  Never add `allow-scripts`.
+- CSRF is `App_Page` Origin/Referer check, not a token (see architecture).
+
+## Change history
+- 2026-09-23 — Created: browse queue, Approve/Reject held emails, Send copy. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
-owners: ["bala", "tcox", "dfranks", "apeterson"]
+updated: 2026-09-23
+owners: ["bala", "tcox", "dfranks", "apeterson", "jcardinal"]
 files:
   - _underscore/Email.php
   - _underscore/String.php
@@ -39,6 +39,9 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
   unless both `setClientIdentifier(...)` and a From address (`fromEmailAddress`) are set. The
   `Logs_[Client]` databases live on a separate cluster (`production-logs-*`), so `send()` points
   `DB_CLIENT_LOGS` at the correct `Logs_[Client]` schema before inserting.
+- Setters (2026-09-23): `setIsHeld(true)` writes the row as `HELD` instead of `PENDING`;
+  `setEmailTemplateId()` / `setReviewOfEmailId()` fill the matching columns. `send()` returns the
+  **int `Logs_<Client>.Email` id**.
 - `worker2/Worker/Infrastructure/Email/Send.php` — `Run()` fetches up to 100 `PENDING` rows for
   the client, and `sendEmail()` transmits each via SES SMTP. Constants: `STATUS_PENDING`,
   `STATUS_SENT`, `STATUS_FAILED`, `MAX_RETRIES`.
@@ -54,6 +57,17 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
 4. On success the row flips to `SENT`; on failure `retryCount` is incremented and the row is
    retried on subsequent runs until `MAX_RETRIES` (3), after which it is marked `FAILED`.
 
+### Statuses + review columns (2026-09-23)
+
+`status` enum = `PENDING` / `SENT` / `FAILED` / `HELD` / `CANCELLED`. The Send cron reads only
+`PENDING`, so `HELD` and `CANCELLED` rows are never sent (worker2 unchanged). Columns:
+`emailTemplateId` (after `dtCreated`), `reviewOfEmailId` (self FK, `ON DELETE SET NULL` — links a
+review copy to the held original), `dtReviewed` (after `dtSent`), `reviewedBy` (after
+`failureReason`). Migration: `dbchanges2/Logs_Client/2026-09-23a - EmailReview.sql` — must run
+**before** the `_underscore` deploy or every `send()` fails. Who writes `HELD`: see
+[email-template-sending.md](email-template-sending.md) *Review hold*; who releases it: Tools
+[/emails](../../../../1.0/apps/tools/features/email-queue-review.md).
+
 ### `send()` resolves the log database itself — from the clientIdentifier
 
 `send()` does not take a database name. It resolves `Logs_<Client>` by joining
@@ -76,10 +90,8 @@ derive one from the other).
 
 ## Gotchas / known issues
 
-- **It is a POLL, not an enqueue — and the docblock lies.** The comment at `_underscore/Email.php`
-  ~line 320 says `send()` "enqueues a Worker 2 job". **There is no enqueue anywhere in the file.**
-  `send()` only INSERTs a `PENDING` row (`Logs_<Client>.Email`, `status` enum
-  `PENDING`/`SENT`/`FAILED`), and `worker2/Worker/Infrastructure/Email/Send.php` loops the clients
+- **It is a POLL, not an enqueue.** (The old docblock claiming `send()` "enqueues a Worker 2 job"
+  was corrected 2026-09-23.) `send()` only INSERTs a `PENDING` (or `HELD`) row, and `worker2/Worker/Infrastructure/Email/Send.php` loops the clients
   and `SELECT`s `PENDING` rows. Two consequences: nothing is queued anywhere but the database, and
   **a `PENDING` row written from a local machine is never delivered**, because the worker polls the
   sandbox/prod clusters, not your laptop. Local "the email never arrived" is expected — verify by
@@ -190,6 +202,9 @@ derive one from the other).
     for a hotfix.
 
 ## Change history
+- 2026-09-23 — Review hold: `HELD`/`CANCELLED` statuses, `emailTemplateId`/`reviewOfEmailId`/
+  `dtReviewed`/`reviewedBy` columns, `setIsHeld`/`setEmailTemplateId`/`setReviewOfEmailId`;
+  `send()` now returns the log id; stale "enqueues" docblock fixed. (jcardinal)
 - 2026-09-17 — Three gotchas from building the NYCHH transfer-order emails, no code change: the
   `Logs_<Client>.Email` `body` column holds the **finished HTML**, so a new email is verified by
   reading the row rather than an inbox; **`send_debug_emails_to` redirects at QUEUE time only** (the

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-23
 owners: ["jcardinal", "bala", "mhammontree", "apeterson"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
@@ -65,6 +65,29 @@ sends via `_Email`. The only client-specific input the send actually needs is th
 4. Replace `{key}` placeholders in subject and body from the `$args` variadic map
    (`replaceTemplateVariables`), then `send()`.
 
+### Review hold (`EmailTemplates.isReviewRequired`, 2026-09-23)
+
+The **template** decides (not `_Email`; direct `_Email` callers are never held). When
+`isReviewRequired = 1`, `dispatch()` calls `_Email::send()` twice:
+1. The real email, real recipients, `setIsHeld(true)` → row status `HELD` (Send cron skips it).
+2. A `PENDING` copy, subject prefixed `[REVIEW] `, sent **only** to the template's `toCcBcc =
+   REVIEW` addresses. Body gets a yellow banner inserted after `<body>` listing the real
+   To/CC/BCC + held id, plus an approve link if `[_underscore] email_review_url` is set (Tools
+   `/emails?client=&emailId=`). Linked via `reviewOfEmailId`.
+
+Release/reject happens in Tools [/emails](../../../../1.0/apps/tools/features/email-queue-review.md).
+Rules:
+- **Fail loud:** review on + no `REVIEW` rows → throws `Email template <uuid> requires review but
+  has no REVIEW addresses configured`; nothing is queued. Unknown `toCcBcc` → throws.
+- `REVIEW` addresses are never merged into real To/CC/BCC.
+- Out of scope by decision: no expiry of held rows, no body/PII hiding, no time-sensitive guard.
+- Rejected design: an approve button inside the email (mail scanners pre-fetch links). Runner-up:
+  single held row, preview only in Tools.
+
+Migrations: `Core/2026-09-23e - EmailTemplateReviewRecordField.sql` (RecordFields 2632 on
+Records 202), `Client/2026-09-23a - EmailTemplateReview.sql`, `Logs_Client/2026-09-23a -
+EmailReview.sql`. Deploy: SQL (Logs_Client first) → `_underscore` → tools.
+
 Both `sendEmail()` and `send()` are thin wrappers that forward to `dispatch()`, so the API
 and non-API paths run identical code — no behavioral drift between them.
 
@@ -76,10 +99,10 @@ gets a real error instead of a `true`/`false` it would otherwise ignore.
 
 ## Data model
 
-- `EmailTemplates` (client DB): `uuid`, `isActive`, `sendFromEmailAddress`, `sendFromName`,
+- `EmailTemplates` (client DB): `uuid`, `isActive`, `isReviewRequired`, `sendFromEmailAddress`, `sendFromName`,
   `priority`, `subject`, `body`.
 - `EmailTemplateOutgoingEmailAddress` (client DB): `emailTemplateId`, `emailAddress`,
-  `toCcBcc` (`TO`/`CC`/`BCC`).
+  `toCcBcc` (`TO`/`CC`/`BCC`/`REVIEW`).
 
 ## Client variations
 
@@ -207,6 +230,8 @@ worker method) in-process instead.
 
 ## Change history
 
+- 2026-09-23 — Added the review hold (`isReviewRequired` + `REVIEW` addresses → `HELD` real email +
+  `[REVIEW]` copy); fail-loud on missing REVIEW rows / unknown `toCcBcc`. (jcardinal)
 - 2026-09-17 — Added two caller-side gotchas found building the NYCHH transfer-order emails:
   `replaceTemplateVariables()` does **no escaping** (plain `str_replace`, and the Send worker forces
   HTML mode), so a stored value containing `<` arrives as live markup and every scalar must be

package/knowledge/2.0/apps/_underscore/features/page-meta-context-field-settings.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: [tcox, bala, jcardinal]
+updated: 2026-09-24
+owners: [tcox, bala, jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Page.php
   - _underscore/Model/Client/TableView.php
@@ -62,6 +62,18 @@ For a **joined** column, a `ClientRecordFieldSettings` row with a null `contextR
 
 **Check which page slug the frontend ACTUALLY requests.** Every label and ACL lookup is filtered on the page's `Core.PageRecords`, so the records must be attached to **the page the frontend asks for** — not always the page you built. Elite's `service-requests` view is requested as **`meta?page=sales-orders-listing`** (Elite reuses that page), so records 99 (Tickets) and 36 (ServiceRequestTypes) had to be attached to `sales-orders-listing`, **not** only to the new `service-requests-listing` page. Attaching them to the new page alone changed nothing. **Read the Network tab first** — mis-diagnosed twice before the actual request URL settled it. A missing header is a *page-attachment* question, and only the real request identifies the page.
 
+**The Core default label chain (verified against production Core, 2026-09-24).** For a base (non-custom, context-free) field the whole chain is Core-only:
+
+```
+Pages --< PageRecords >-- Records --< RecordFields
+                                          |
+                    DefaultRecordFieldSettings (settingId = 'label-singular')
+```
+
+`Core.Settings` id **5** = `label-singular`; `Core.Apps` id **1** = `supply`. Client/Persona/User/Language `RecordFieldSettings` only *override* this; the Core default already labels the field for **every** tenant. So seeding headers for a new page is **one `dbchanges2` `Core/` file** — no per-tenant fan-out and no cross-cluster split. (Worked example: `Core/2026-09-24a - BundlesListingPageMeta.sql`.)
+
+**`Sections` are a different path — and listing pages have none.** `Sections` / `SectionRecordFields` / `ClientSectionRecordFieldSettings` do not feed table column labels. In prod and sandbox **every** `*-listing` page has **0** `Sections` rows; only `*-view` pages (`items-view`, `sales-orders-view`) have any. "This page has no Sections" is normal and is never the reason a header is missing.
+
 **The `Core.PageRecords` gate.** `Page.php` assembles `settings.fields` from an **INNER JOIN** on `Core.RecordFields` (~L652) gated by **`Core.PageRecords`**: only fields of records *attached to the page* are emitted. A correct settings row does nothing until **both** the labelled field's record **and** the context record are attached to the page. Sequencing:
 1. **The `isset()` guard in `Page.php` (below) goes first.** Until it ships, adding context rows is actively dangerous — a context row fatals **every** page that contains the labelled field's record but not the context record.
 2. Then the `Core.PageRecords` attachments.
@@ -77,6 +89,7 @@ For a **joined** column, a `ClientRecordFieldSettings` row with a null `contextR
 
 ## Gotchas
 
+- **Missing headers: check `PageRecords` + `DefaultRecordFieldSettings`, never `Sections`.** Listing pages have zero Sections by design.
 - **A page-meta 500 is not necessarily about that page.** Trace it to the offending `ClientRecordFieldSettings` row via the array key in the message (it is a `Core.RecordFields` id), not via the slug you requested.
 - **Error-handler strictness is a deploy-time behavior change.** Warnings survivable for years become 500s the moment the strict handler ships; expect a cluster of "new" failures in old code after such a deploy.
 - Do not "fix" this by deleting the client's settings row — that removes a real client customization. The guard belongs in the framework.
@@ -87,3 +100,6 @@ For a **joined** column, a `ClientRecordFieldSettings` row with a null `contextR
 - [TableView field/column metadata](../../api2/features/tableview-field-metadata.md)
 - [Error reporting (Issue/Event)](error-reporting-issue-event.md)
 - [Elite supply2 TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md)
+
+## Change history
+- 2026-09-24 — Documented the Core-only label chain (`Pages`→`PageRecords`→`RecordFields`→`DefaultRecordFieldSettings` `label-singular`, setting id 5) and that `Sections` are a separate path listing pages never have. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/meta-driven-table-data.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-23
+updated: 2026-09-24
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
@@ -16,7 +16,8 @@ files:
   - toga25-supply/src/pages/Bundles/viewModel/useBundlesPageViewModel.tsx
   - toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts
   - toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts
-  - toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts
+  - toga-blox-npm/dist/components/Table/hooks/useAssignTableFieldLabels.js
+  - _underscore/Model/Core/Page.php
   - toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts
 related:
   - ../architecture.md
@@ -79,17 +80,39 @@ The view model then returns `salesOrdersTableMeta` (after column-visibility adju
 - **Table slug** (`tableState.slug`) identifies the *table* and is used for **both** the table-meta fetch (step 3) and the table-data fetch (step 5) — they must match so the columns and the rows describe the same table. In Sales Orders this slug is derived from the route pathname via `useServerTableUrlState`, not read out of `pageMeta`.
 - `useAssignTableFieldLabels` is the bridge: it overlays the page meta's per-field labels (`pageMeta.settings.fields[table][field].label`) onto the table meta's fields, so page-scoped copy wins without re-fetching.
 
-### 🚨 There is NO label in the table meta — a page with no page-meta record shows raw slugs
+### 🚨 There is NO label in the table meta — labels come from Core page meta
 
-`_Model_Client_TableView::meta()` emits, per field: `slug`, `settings{table, field, contextTable, contextField}`, `tableViewField`, `type`, `precision` and the `is*` flags — **and no `label`.** Every column header in this app is therefore supplied by the *page* meta and grafted on in step 4.
+`_Model_Client_TableView::meta()` emits, per field: `slug`, `settings{table, field, contextTable, contextField}`, `tableViewField`, `type`, `precision` and the `is*` flags — **and no `label`.** `Core.TableViewFields` has no label column at all. Every column header in this app is therefore supplied by the *page* meta and grafted on in step 4.
 
-`useAssignTableFieldLabels` bails at **`if (!pageFields) return table`** when `pageMeta` is null. So **any list screen built without a legacy `<slug>-listing` page-meta record renders raw camelCase slugs** — and not only in the grid: the **Columns-visibility modal** reads the same merged meta, so the two stay consistently wrong. This is a general platform trap for every new page, not a per-screen bug. (`toga2-supply`'s equivalent fallback and the joined-column context rules are in [page-meta-context-field-settings](../../_underscore/features/page-meta-context-field-settings.md).)
+**The label chain (verified against production Core, 2026-09-24):**
+
+```
+Pages --< PageRecords >-- Records --< RecordFields
+                                          |
+                    DefaultRecordFieldSettings (settingId = 'label-singular')
+```
+
+- `_Model_Core_Page::meta()` (`_underscore/Model/Core/Page.php`, the "fields settings" block ~L640-745) scopes which `RecordFields` a page exposes through **`PageRecords`** — the join table, **not** `Sections`.
+- The label value is `Core.DefaultRecordFieldSettings` where `settingId` = the `label-singular` setting (`Core.Settings` id **5**; `Core.Apps` id **1** = `supply`). Per-tenant overrides layer on top via `Client/Persona/User/LanguageRecordFieldSettings` in the client DB, but the **Core default carries the label for every tenant**.
+- **So seeding labels is a Core-only change** — one `dbchanges2` `Core/` file, no per-tenant fan-out, no cross-cluster split.
+- `Sections` / `SectionRecordFields` / `ClientSectionRecordFieldSettings` are a **separate** settings path with nothing to do with table column labels.
+
+**Trap — "the page has no Sections" is a dead end.** In prod (and sandbox) **every** `*-listing` page has **0 rows in `Sections`**; only the `*-view` pages (`items-view`, `sales-orders-view`) have any (5 each). Missing Sections is normal for a listing page and is never why labels are missing. Time was lost chasing this on 2026-09-24.
+
+**Two failure shapes in `useAssignTableFieldLabels` that look identical on screen** (`toga-blox-npm/dist/components/Table/hooks/useAssignTableFieldLabels.js`):
+
+| Cause | Code path | Result |
+|---|---|---|
+| `pageMeta` is null (no page-meta record) | `if (!pageFields) return table` | fields carry **no `label` key at all** |
+| `pageMeta` present but the page slug is wrong / field unmatched | `const label = labelSingular \|\| fieldSlug` | label is stamped as the **raw slug** |
+
+Pointing a page at the **wrong** page-meta slug is therefore not harmless — the merge runs, matches nothing, and writes slugs in as labels. Both render as camelCase headers, so the symptom does not tell you which one you have; check the `pageMeta` response.
 
 **Interim workaround (Transfer Orders, 2026-08-28):** a slug humanizer applied to the **merged** meta — `sourceLocation` → "Source Location" — deliberately after the merge so headers and the Columns modal cannot drift. It cannot recover a label the slug does not contain: the design's "TO Number" is unreachable from slug `number`.
 
-**The real fix is a label source**, one of:
-1. a legacy `<slug>-listing` **page-meta record** (matches every existing page), or
-2. extending the **list surface** with per-column `FIELD` elements carrying a `labelMessageId` — which additionally makes headers translatable through `MessageTranslations`, something the page-meta route cannot do. See [surface-frontend](./surface-frontend.md).
+**Preferred fix for a new list page (decided 2026-09-24): seed the Core page meta.** One `dbchanges2` `Core/` migration with a `<slug>-listing` `Pages` row + `PageRecords` link + `DefaultRecordFieldSettings` `label-singular` rows. This was previously mis-estimated as expensive (assumed per-tenant `SectionRecordFields` fan-out across ~30 client DBs plus a cross-cluster split) — **it is not; it is Core-only, one file.** Prefer it over the `humanizeSlug` fallback, which stays valid only where the slug already reads correctly. A third option, extending the **list surface** with per-column `FIELD` elements carrying a `labelMessageId`, additionally makes headers translatable through `MessageTranslations` — something the page-meta route cannot do. See [surface-frontend](./surface-frontend.md).
+
+Worked example (Bundles, TRUE-82137, 2026-09-24) — `dbchanges2` `Core/2026-09-24a - BundlesListingPageMeta.sql`: `Pages(bundles-listing, appId 1)`, `PageRecords` → `Records` id 43 (bundles), and 5 `DefaultRecordFieldSettings` `label-singular` rows (`number` 265 → Number, `name` 248 → Name, `description` 1446 → Description, `isActive` 1356 → Active, `sortOrder` 1314 → Sort Order). The `Records` and `RecordFields` ids already existed in prod, so no team-reserved ids were needed.
 
 ### 🚨 Never hardcode a table meta in a view model — it fakes the flags too
 
@@ -104,9 +127,14 @@ Inventory page), and called `useTablePageMeta` but **threw the fetched result aw
    **masked** the fact that the real served meta had them all off (the flags were NULL in
    `TableViewFields`). The page looked configured while the database said otherwise.
 
-Use the fetched server meta plus a `humanizeSlug` label fallback — the pattern in
-`useTransferOrdersPageViewModel`. A hardcoded meta is never a workaround for missing data; it hides
-the data problem.
+Use the fetched server meta. A hardcoded meta is never a workaround for missing data; it hides the
+data problem.
+
+The label half was closed on **2026-09-24**, and it takes **two changes that must land together**:
+`useBundlesPageViewModel.tsx:40` `"inventory"` → `"bundles-listing"` (commit `87b4442`), **and** the
+Core seed `dbchanges2 Core/2026-09-24a - BundlesListingPageMeta.sql` (commit `89d88d7`). Shipping the
+slug alone leaves the page with no page-meta record; shipping the seed alone leaves it fetching
+`inventory`.
 
 ### What's in the table meta (the columns)
 
@@ -157,7 +185,10 @@ App-side glue (NOT in toga-blox):
 - **`additionalData` must be in the query key** (it is, inside `useTableData`) — required for WHERE-filtered modal tables or React Query serves a stale unfiltered first render.
 - **Never hardcode a table meta object in a view model.** It silently fakes `isSortable`/`isFilterable`/`isCopyable` and hides a real `TableViewFields` gap; always render the fetched meta.
 - **toga-blox edits need a rebuild** — the app consumes `dist/`; editing only `src` is a silent no-op.
+- **Listing pages have zero `Sections` rows by design** — never diagnose missing headers by looking at `Sections`.
+- **A wrong page-meta slug is worse than none** — the merge stamps raw slugs in as labels; it looks the same on screen as having no page meta.
 - **A new page with no page-meta record has no column labels at all** — the table meta carries no `label` and the merge hook no-ops on a null `pageMeta`, so headers *and* the Columns modal render raw camelCase slugs. Plan the label source before building the screen (see above).
 
 ## Change history
+- 2026-09-24 — Corrected the column-label source: labels come from `Core.DefaultRecordFieldSettings` (`label-singular`) scoped by `Pages`→`PageRecords`→`RecordFields`, **not** from `Sections`; listing pages legitimately have zero Sections. Recorded the two `useAssignTableFieldLabels` failure shapes (null pageMeta vs. wrong slug → raw slug stamped as label), corrected the cost of seeding page meta to Core-only/one-file, and closed the Bundles label gap (slug fix + `Core/2026-09-24a`, TRUE-82137). (apeterson)
 - 2026-09-23 — Added the hardcoded-table-meta anti-pattern found on the Bundles page: it produced raw slug headers and, worse, faked `isSortable`/`isFilterable`/`isCopyable` as true, masking NULL flags in `TableViewFields` (TRUE-82137). (apeterson)

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-23
+updated: 2026-09-24
 owners: [apeterson, bala, "jcardinal"]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
@@ -191,7 +191,7 @@ One `SurfaceOverrides` row, `IS_VISIBLE = '1'`, **client-wide** (`personaId`/`ro
 
 `src/pages/TransferOrders/`, wired into `ROUTE_REGISTRY` in `src/routes.tsx` as `transfer-orders`.
 - **The TableView slug comes from the surface** (`listSurfaceMeta.surface.tableViewSlug`, falling back to a local constant), so re-pointing the page at a different view is a data change. The page never derives its identity from the route.
-- **Column labels are humanized from the slug.** There is no `transfer-orders-listing` page-meta record, so blox's label merge contributes nothing and headers would render raw camelCase. The humanizer is applied to the **merged** meta so headers and the Columns-visibility modal cannot drift. It cannot produce the design's "TO Number" from slug `number` — see [meta-driven-table-data](./meta-driven-table-data.md) for the real fix.
+- **Column labels are humanized from the slug.** There is no `transfer-orders-listing` page-meta record, so blox's label merge contributes nothing and headers would render raw camelCase. The humanizer is applied to the **merged** meta so headers and the Columns-visibility modal cannot drift. It cannot produce the design's "TO Number" from slug `number`. Seeding a `transfer-orders-listing` page-meta record is the fix, and it is cheap (Core-only, one `dbchanges2` file) — see [meta-driven-table-data](./meta-driven-table-data.md).
 
 ### The record modal — two fetches, one modal element
 

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **test** (Test) — 16 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **store** (Store) — 3 doc(s) → [1.0/apps/store/INDEX.md](1.0/apps/store/INDEX.md)
-- **tools** (Tools) — 21 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 22 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/clients/nychh/features/transfer-order-notification-emails.md

@@ -7,7 +7,7 @@ client: nychh
 type: client-feature
 status: active
 updated: 2026-09-23
-owners: ["bala", "rgirish"]
+owners: ["bala", "rgirish", "jcardinal"]
 files:
   - worker2/Worker/Client/Nychh/TransferOrderEmails.php
   - _underscore/Model/Nychh/TransferOrder.php
@@ -231,6 +231,12 @@ Cost of the split, stated so nobody is surprised later:
 
 ## Gotchas / known issues
 
+- **Submitted uses the review hold** (template "Transfer Order - Submitted", `Client_Nychh`
+  `EmailTemplates` id 3, `isReviewRequired = 1`) — first prod user; see
+  [email-template-sending.md](../../../2.0/apps/_underscore/features/email-template-sending.md).
+  Turning it on **without** a `REVIEW` address row fails `Client/Nychh/TransferOrderEmails/SendSubmitted`
+  (prod Logs.Issue Y6) — expected fail-loud. Fix: add the `REVIEW` row, retry the job.
+
 - **⚠ There is NO `try`/`catch` anywhere in this feature, by design.**
   `sendTransferOrderEmail()` returns `void` and **throws `_Exception`** when
   `_Model_Client_EmailTemplate::send()` returns `false` (which happens only when the template row is
@@ -260,6 +266,7 @@ loaded out of the dbchanges2 file so an unresolved `{placeholder}` fails a test.
 unescaped values and both detail-box defects were all found there, not in production.
 
 ## Change history
+- 2026-09-23 — Submitted template put on review hold; missing REVIEW row → job failure note. (jcardinal)
 
 - 2026-09-23 — **The greeting now addresses whoever raised the order, not the site contact.**
   `readTransferOrderForEmail()` selects `CreatedByUsers.firstName AS submittedByFirstName`, and

package/package.json

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