toga-ai 1.0.881 → 1.0.883

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/api2/features/tableview-field-metadata.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-23
 owners: [apeterson, bala]
 files:
   - _underscore/Model/Client/TableView.php
@@ -18,13 +18,15 @@ files:
   - dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql
   - dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
-  - dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql
+  - dbchanges2/Core/2026-09-23a - BundleRecordFieldTypes.sql
+  - dbchanges2/Client_Compass/2026-09-23a - BundlesTableViewFieldFlags.sql
 related:
   - tableview-apiwhereclause-row-filtering.md
   - ../../_underscore/features/page-meta-context-field-settings.md
   - ../../_underscore/features/acl-permission-chain.md
   - ../../toga25-supply/features/meta-driven-table-data.md
   - ../../_underscore/features/tableview-joins.md
+  - v2-rest-query-contract.md
 ---
 
 How a 2.0 table view's columns/order/sort are defined by DB metadata (`TableViews`/`TableViewFields`/`TableViewJoins`), the per-client type override, hidden projected columns, and the safe reorder/rebuild patterns; open before writing any TableView migration.
@@ -45,6 +47,12 @@ The columns of a 2.0 table view are defined by DB metadata, not code. Per-client
 
 **A column's `type` / `precision` are NOT per-view — they come from `Core.RecordFields`.** A field's rendered **type and precision are canonical**, read from the shared `Core.RecordFields.type` / `Core.RecordFields.precision` — there is **no per-view type/precision override** on `TableViewFields`. Changing `Core.RecordFields.type`/`precision` therefore changes the column's type/format **everywhere that field appears, for every client**. Intended canonical behavior — if you only want the change in one view, this mechanism cannot do it. (Reference: `Core.RecordFields` id 369 = `ItemFulfillmentItems.quantity` set to `type=NUMBER`, `precision=0`, which normalizes that column across all fulfillment views/clients.)
 
+**`Core.RecordFields.type` controls DISPLAY and FILTER only — it does NOT change sorting.** `_Model_Client_TableView::meta()` emits `'type' => $recordField->type` straight off `Core.RecordFields` (`_underscore/Model/Client/TableView.php` ~L355). The type decides which **cell component** renders and which **filter widget** appears — nothing more. Sorting is done by the database on the real column, so a **text** column typed `NUMBER` still sorts alphabetically (`10` before `9`). Verified across sales-orders, items, vendor-items and bundles (2026-09-23). To get numeric ordering you must change the column or the `ORDER BY`, not the metadata — see [V2 REST query contract](v2-rest-query-contract.md).
+
+**🚨 Typing a text column `NUMBER` BLANKS every non-numeric row.** `NumberCell` runs `Number(value)`; `Number("kit 207")` is `NaN` and renders empty. `Client_Compass` has 3 bundles whose `number` is literally `kit 205` / `kit 206` / `kit 207`, so setting `Bundles.number` to `NUMBER` emptied those cells. **Only type a column `NUMBER` after confirming every tenant's values actually convert** (`WHERE col REGEXP '^[0-9]+$' = 0`). `BOOLEAN` has the opposite story and is usually right: a JS boolean renders as nothing in a plain text cell, so a genuinely blank flag column (`Bundles.isActive`) is fixed by typing it `BOOLEAN`. Reference: `dbchanges2/Core/2026-09-23a - BundleRecordFieldTypes.sql`.
+
+**Flag columns are NULLable — a migration guarded with `isFilterable = 0` updates NOTHING.** `isSortable`/`isFilterable`/`isCopyable`/`isGroupable` are left **NULL** by a seed that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`index`/`slug` (which is what the 2026-04-07 bundles view did), and `NULL = 0` is unknown in SQL. Guard with `COALESCE(col, 0) = 0` — full write-up in [re-runnable additive migrations](../../dbchanges2/features/rerunnable-additive-inserts.md).
+
 **Per-client type override — point the column at a same-named `CustomRecordFields` row.** "No per-view override" is about `TableViewFields` having no `type` column of its own. It does **not** mean a client is stuck with the Core type: a column does not have to point at a Core `RecordField` at all. `TableViewFields.customRecordFieldId` is the alternative to `recordFieldId`, so **one client can retype a column without touching Core**:
 1. Insert a `Client_<X>.CustomRecordFields` row with the **same `field` name** as the Core `RecordField` (e.g. `_unitPrice`) and the wanted `type` (e.g. `STRING`).
 2. Repoint that client's `TableViewFields` row at `customRecordFieldId` instead of `recordFieldId`.
@@ -120,6 +128,9 @@ So the visible failure is a broken SQL query while the actual defect is one miss
 - **Don't assume `Core.RecordFields`/`Core.Records` ids are stable across environments** — look them up by `field` name + record.
 - **Make column migrations idempotent** (`NOT EXISTS` guard) — they run per client DB.
 - **`isVisible=0` still costs a fetch** — the field is selected into the projection; only the render is suppressed.
+- **`type` drives rendering + filtering, NOT sort order** — a text column typed `NUMBER` still sorts alphabetically.
+- **`NUMBER` on a column with non-numeric values renders those cells BLANK** (`Number("kit 207")` → NaN). Check every tenant's data first.
+- **Flag columns are NULLable** — guard flag migrations with `COALESCE(col, 0) = 0`, never `col = 0`, or the UPDATE matches 0 rows and looks like caching.
 - **`type`/`precision` are canonical (Core-wide), not per-view.** Editing `Core.RecordFields` changes every view/client that shows the field; there is no per-view type override. `isCopyable`, `isSortable`, `isFilterable`, `isGroupable`, `isVisible` are the per-view knobs (on `TableViewFields`).
 - **`TableView::meta()` contains a hand-written `SELECT` that names `TableViewFields` columns explicitly.** So a new column on that table is required by **two** mechanisms — the model property *and* that query — and a grep for the property alone under-reports what a missing column breaks.
 - **`isGroupable` has no migration** — omit it from new TableView migrations (fails on prod/beta) until the fan-out migration lands. Composite unique keys read as unconstrained in `information_schema.COLUMNS`; use `information_schema.STATISTICS` / `SHOW INDEX`.
@@ -131,3 +142,6 @@ So the visible failure is a broken SQL query while the actual defect is one miss
 - [ACL permission chain](../../_underscore/features/acl-permission-chain.md)
 - [Meta-driven table data](../../toga25-supply/features/meta-driven-table-data.md)
 - [TableView joins](../../_underscore/features/tableview-joins.md)
+
+## Change history
+- 2026-09-23 — Recorded that `Core.RecordFields.type` drives display/filter only and never sorting; that `NUMBER` on a text column blanks non-numeric rows (Compass `kit 205-207` bundles) while `BOOLEAN` fixes genuinely blank flag columns; and that the flag columns are NULLable so a `= 0` migration guard matches nothing. (apeterson)

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-18
+updated: 2026-09-23
 owners: [tcox, bala, apeterson, jcardinal, rgirish]
 files:
   - api2/Component/Api/V2/V2.php
@@ -18,6 +18,7 @@ related:
   - nested-fk-acl-embedding.md
   - ../../_underscore/features/calculated-sql-fields.md
   - ../../toga25-supply/features/transfer-orders-page.md
+  - tableview-field-metadata.md
 ---
 
 ## Summary
@@ -63,6 +64,33 @@ controller.
   the join is genuinely 1:1, or the duplicates agree. Worked example:
   [category tile sort order](../../toga2-commerce/features/category-tile-sort-order.md).
 
+### How `sort` becomes `ORDER BY` — and why "descending sort is broken" is usually just NULLs
+
+`ORDER BY` is a **plain string concatenation** of the resolved column and `ASC`/`DESC` — no cast, no
+`NULLS FIRST/LAST` handling, no per-field hook (`V2.php` plain-column branch ~L3782-3784,
+calculated-field branch ~L3771-3773).
+
+Two things follow.
+
+**1. Empty/NULL columns fill page 1 of an ascending sort.** MySQL puts NULLs **first** on `ASC` and
+**last** on `DESC`. A column with many empties — e.g. the Compass sales-orders MITS PO number (slug
+`purchaseOrderNumber`, backed by the calculated `_purchaseOrders`) — therefore shows a page of
+dashes when sorted ascending. That is correct SQL, **not a bug**; triage it as data coverage. A
+"blanks always last" behaviour would be `ORDER BY (col IS NULL), col`, and should be a **per-field
+opt-in**, never blanket.
+
+**2. The same expression is the keyset (seek) pagination cursor.** `$seekSortColumn` is reused in the
+seek `WHERE` (~L4042) and the uuid tiebreaker (~L4123). So **any change to the `ORDER BY` expression
+must be mirrored in the seek `WHERE` and in `getSeekFieldType()`** — otherwise page 1 looks right and
+page 2 onward silently returns the wrong rows, with no error.
+
+**Text columns sort as text — that is the column, not the engine.** Every genuinely numeric column
+sorts correctly (`_qtyItems`, `_totalPurchase`, `_unitPrice`, `_unitCost`, `sortOrder`). Metadata
+cannot fix it: `Core.RecordFields.type` affects rendering/filtering only
+([TableView field metadata](tableview-field-metadata.md)). **Decision (2026-09-23, TRUE-82137): do
+not add a shared-engine cast** for a one-column problem — it risks the keyset pagination contract
+above and loses the index. Fix the column type in the schema, or cast per-field, deliberately.
+
 ### ⚠ `depth` is not free — the default 3 re-reads child rows and races concurrent deletes
 
 **`depth` defaults to 3 on every request, writes included.** Serialization (`getFullModelData()` in
@@ -557,6 +585,11 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-23 — Documented how `sort` becomes `ORDER BY` (plain concatenation, no cast or NULL
+  handling), that the same expression doubles as the keyset-pagination cursor so any change must be
+  mirrored in the seek `WHERE`/`getSeekFieldType()`, and that "descending sort is broken" reports are
+  usually normal MySQL NULL ordering. Decided against an engine-level numeric cast for Bundles
+  (TRUE-82137). (apeterson)
 - 2026-09-18 — Recorded that swapping an OR-chain of `contains` for a single `in` on a
   calculated field only shortens the SQL text and does not speed it up: the Compass approvals list
   (`_status:in:...`) still takes 14.66 s with the `in` clause live (TRUE-81379). (apeterson)

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-09-22
+updated: 2026-09-23
 owners: [bala, kyalamarthi, apeterson, ajean, jcardinal, rgirish]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -16,6 +16,7 @@ files:
   - dbchanges2/_modules/netsuite/2026-09-11c - ItemClassRecordPermission.sql
   - dbchanges2/Client_Compass/2026-09-18a - BackfillUpstreamItemFulfillmentTracking.sql
   - dbchanges2/Client_Compass/2026-09-21a - BackfillUpstreamItemFulfillmentUnits.sql
+  - dbchanges2/Client_Compass/2026-09-23a - BundlesTableViewFieldFlags.sql
 related:
   - ../architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
@@ -413,8 +414,35 @@ Both are local-only evidence: pair them with the
 [local-vs-prod config parity check](../workflows/local-vs-prod-mysql-config-parity.md) before
 concluding a migration is production-safe.
 
+### ⚠ A `col = 0` guard on a NULLable flag matches NOTHING — use `COALESCE(col, 0) = 0`
+
+The house pattern for a "turn these flags on" migration guards the UPDATE so a re-run is a no-op:
+
+```sql
+-- WRONG — silently updates 0 rows when the flags are NULL
+UPDATE TableViewFields SET isFilterable = 1, isCopyable = 1
+WHERE tableViewId = @tv AND (isFilterable = 0 OR isCopyable = 0);
+
+-- CORRECT
+WHERE tableViewId = @tv AND (COALESCE(isFilterable, 0) = 0 OR COALESCE(isCopyable, 0) = 0);
+```
+
+In SQL `NULL = 0` is **unknown**, not true, so the guard excludes exactly the rows that most need
+the update. MySQL reports success with `0 rows affected` and the UI is unchanged — which reads as a
+caching problem, not a migration bug. Hit live on 2026-09-23 on the Compass bundles TableView, whose
+flags were left NULL by the original seed.
+
+**Applies to every NULLable flag column**, and the flags on `TableViewFields`
+(`isSortable`/`isFilterable`/`isCopyable`/`isGroupable`) are NULLable and are routinely left NULL by
+an INSERT that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`index`/`slug`.
+
+> **Known outstanding hole:** the precedent files `2026-08-26 - EnableTableViewFieldFilters.sql`
+> (NYCHH, Quad, Compass USA, Compass Canada) all use the bare `= 0` guard, so any row that was NULL
+> rather than 0 was never updated by them. Not yet audited.
+
 ## Gotchas
 
+- **⚠ `col = 0` never matches a NULL** — guard flag-enabling UPDATEs with `COALESCE(col, 0) = 0`, or the migration reports success and changes nothing.
 - **⚠ An unguarded ACL grant migration duplicates silently — `AclRecordPermissions` has no unique key
   that stops it (found in prod 2026-09-15).** `_modules/netsuite/2026-09-11c - ItemClassRecordPermission.sql`
   is a plain `INSERT … VALUES` for `(recordId 105, roleId 3)` with **no `NOT EXISTS` guard**. Every
@@ -477,6 +505,7 @@ concluding a migration is production-safe.
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-23 — Added the NULL-unsafe flag-guard trap (`col = 0` matches no NULL row; use `COALESCE(col, 0) = 0`), found when a bundles TableViewFields migration updated 0 rows; flagged the 2026-08-26 `EnableTableViewFieldFilters` files as carrying the same hole. (apeterson)
 - 2026-09-22 — Added multi-tier chain backfill rules from the Compass tracking/serial backfills: re-run the same file until the verify count is 0 (each pass moves data up one tier; both files needed 3 passes); `GROUP BY` the target key pair instead of `SELECT DISTINCT` when many downstream rows roll up to one upstream row (bundles tripped a bridge UNIQUE 6-to-1); measure the safe/ambiguous/no-match split before writing bulk DML and skip the ambiguous rows (4,900 broken links = 1,982 safe + 0 ambiguous + 2,918 no-match). Sharpened the unique-key rule with measured composite keys across the four item-fulfillment tables — `ItemFulfillmentItemUnits` has none and already carries 254 duplicates. (rgirish)
 - 2026-09-21 — Added three lessons from the platform-wide `Users.contactId` NOT NULL backfill: a guarded
   `NOT NULL` ALTER (`sql_mode ''` silently coerces leftover NULLs to `0`, so gate on a residual count —

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

@@ -8,6 +8,7 @@
 | [API client (axios wrapper, auth, table-data fetchers)](features/api-client.md) | blox axios/React-Query client — envelope, auth (Bearer + refresh), option serialization, CRUD, table-data fetchers; open for init, query shapes, and the many si |
 | [BaseInput (react-hook-form field factory)](features/base-input.md) | react-hook-form field factory rendering an input per `inputType`; open for its config surfaces, the input-type switch, validation rules, and the `<FormProvider> |
 | [blox authoring defect backlog (fix IN blox, not around it)](features/blox-authoring-defects.md) | Backlog of defects to fix INSIDE `@agilant/toga-blox` (the counterpart to frontend §22's app-side workarounds); open when editing blox itself or deciding whethe |
+| [EnvironmentBadge & endpoint classifier](features/environment-badge.md) | The on-screen badge that names which API a build is talking to, and the URL classifier behind it; open before changing its hide rule, adding an environment, or |
 | [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | The production wired-up table (server/client templates, measure-and-freeze sizing, virtualization, sticky columns); open for props, column-sizing/sticky mechani |
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | Generic presentational record-detail modal shell (position/animation/lifecycle only); open for its props, the `data-blox-modal-open` root marker, and the no-por |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | TanStack-v8 Table building block (column building, cell types, filters/sorts, data hooks, theming); open for cell resolution, the filter components, hooks, and |

package/knowledge/2.0/apps/toga-blox/features/environment-badge.md

@@ -0,0 +1,70 @@
+---
+title: EnvironmentBadge & endpoint classifier
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-09-23
+owners: [apeterson]
+files:
+  - toga-blox/src/components/EnvironmentBadge/EnvironmentBadge.tsx
+  - toga-blox/src/components/EnvironmentBadge/EnvironmentBadge.css
+  - toga-blox/src/utils/getEndpointFromEnvironment.ts
+related:
+  - ../architecture.md
+  - ../../../standards/frontend-deploy.md
+  - ../../../standards/frontend.md
+---
+
+The on-screen badge that names which API a build is talking to, and the URL classifier behind it; open before changing its hide rule, adding an environment, or debugging a build that shows no badge.
+
+## Summary
+
+`EnvironmentBadge` is a dev/QA warning indicator shipped by blox and mounted by the apps (see `toga2-view` `App.tsx`, commerce `AuthLayout.tsx`). It labels the resolved API endpoint so nobody mistakes a non-production site for production — or worse, a non-production site that is wired to the **production** API.
+
+It is the client-side detector for a broken deploy rule: `frontend-deploy.md` says never build with `npm run build` (no `--mode`), because Vite then defaults to mode `production` and loads `.env.production`. When that happens the site points at the production API. The badge exists to make that visible.
+
+**Hiding is this component's worst failure mode.** Treat "show a wrong-ish label" as always better than "show nothing".
+
+## How it works
+
+### Hide rule (three conditions, all required)
+
+The badge hides only when **all** of:
+
+1. build mode is `production` (`import.meta.env.MODE`),
+2. the classified endpoint is `production`, and
+3. `isNonProductionHost(window.location.hostname)` is false.
+
+The hostname overrides the build. Before 2026-09-23 only conditions 1 and 2 existed, so the exact incident the badge is for — a sandbox site built without `--mode`, defaulting to mode `production` and `.env.production` — matched both and rendered nothing. Now a sandbox URL talking to the prod API shows a red `Endpoint: Production`.
+
+### `isNonProductionHost(hostname)` (exported)
+
+Returns true when the hostname contains any marker in `NON_PRODUCTION_HOST_MARKERS`, case-insensitive: `.client.sandbox`, `.dev.sandbox`, `.beta`, `.gamma`.
+
+### `getEndPointFromEnvironment()` — explicit match, never a fallback
+
+Classifies `VITE_API` into `production` | `local` | `unknown` (plus the existing named environments):
+
+- `production` — only an explicit match on `/^(https?:\/\/)?api\d?\.togahub\.com(:\d+)?(\/|$)/i` (api, api1, api2, api3).
+- `local` — a **dotless** host (the XAMPP vhost `http://api/v2`); a dotless host can never be a public production host.
+- `unknown` — any other fully-qualified host.
+
+**The general rule this encodes: never let the "hide the warning" value be the fallback.** Match it explicitly and label the leftovers. Previously `production` was returned for any unrecognised base URL, so an unrecognised `VITE_API` went completely unlabelled.
+
+### Styling
+
+`EnvironmentBadge.css` classes are `env-<endpoint>`. `.env-unknown` is styled **red like production**, so an unclassified backend reads as a warning, not a normal environment.
+
+## Gotchas
+
+- **The marker list is exhaustive, not a heuristic.** A differently shaped non-prod host (e.g. `staging.togasupply.com`) still hides. Adding an environment means adding its marker to `NON_PRODUCTION_HOST_MARKERS`.
+- **A CSS class typo silently unstyles the badge.** `.env-localost` (missing `h`) shipped for a long time; the localhost badge rendered as plain text and nobody noticed. Class names must match the endpoint strings the classifier returns — add both together.
+- **Testing `import.meta.env`:** use `vi.stubEnv("MODE", …)` / `vi.stubEnv("VITE_API", …)`. To set the hostname without navigating jsdom, redefine `window.location` with `Object.defineProperty`.
+- **Consumers import it in ways that matter.** A barrel `import { EnvironmentBadge } from "@agilant/toga-blox"` drags in unrelated peers at build time; older published versions exported it as **default only**. See [toga2-commerce Amplify build & deploy](../../toga2-commerce/workflows/amplify-build-and-deploy.md).
+- Do not remove the badge from an app to "clean up" — it is a deliberate QA tool.
+
+## Change history
+- 2026-09-23 — Hostname now overrides the hide rule (`isNonProductionHost`); endpoint classifier matches `production` explicitly and adds `local`/`unknown`; fixed `.env-localost` typo, added `.env-local`/`.env-unknown`; 24 tests added (apeterson)

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

@@ -6,13 +6,14 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-23
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
   - toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx
   - toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts
   - toga25-supply/src/hooks/useTablePageMeta.ts
+  - 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
@@ -90,6 +91,23 @@ The view model then returns `salesOrdersTableMeta` (after column-visibility adju
 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).
 
+### 🚨 Never hardcode a table meta in a view model — it fakes the flags too
+
+The Bundles page (fixed 2026-09-23, TRUE-82137) carried a **hardcoded `meta` object** as its table
+meta, called `useFetchPageMeta` with the **wrong page slug** (`"inventory"`, copied from the
+Inventory page), and called `useTablePageMeta` but **threw the fetched result away**, keeping only
+`isLoadingFilterOptions`. Two failures, and the second is the dangerous one:
+
+1. No labels reached the table, so headers rendered raw camelCase slugs (`number`, `isActive`, …) —
+   the visible "lowercase headers" bug.
+2. The fake meta declared `isSortable`/`isFilterable`/`isCopyable` **`true` on every column**, which
+   **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.
+
 ### What's in the table meta (the columns)
 
 `useFetchTablePageMeta` returns `{ table, nestedTable }`. The `table` object is the `TableViewMeta` (alias of `DataTableMetaProp`) and carries:
@@ -137,5 +155,9 @@ App-side glue (NOT in toga-blox):
 - **Don't shrink the fetch meta for column hiding.** `getDataTableData` builds its API field list from `meta.fields`; adjust `isVisible` only on the *display* meta (see column-visibility).
 - **Infinite scroll needs a height-constrained scroll container** (`max-height` + `overflow-y: auto`); inline-expanded nested tables where the page scrolls won't load more. Pagination is unaffected.
 - **`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.
 - **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-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/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
 
@@ -34,7 +34,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 26 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 21 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
-- **toga-blox** (TOGa Blox) — 14 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
+- **toga-blox** (TOGa Blox) — 15 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 
 ## standalone 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.881",
+  "version": "1.0.883",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",