toga-ai 1.0.654 → 1.0.655

package/knowledge/2.0/apps/_underscore/features/apirequest-json-content-type.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
-owners: ["jcardinal"]
+updated: 2026-08-26
+owners: ["jcardinal", "ajean"]
 files:
   - _underscore/ApiRequest.php
 related:
@@ -74,7 +74,33 @@ case-insensitive scan of already-set headers, so a caller-supplied `Content-Type
   save) lives **inside `execute()`** and would affect every framework caller, so it is deferred
   pending architecture review. Do **not** work around it per-caller.
 
+- **Hand-rolled `Logs.Api` inserts must set `isAuthRequest`, `instanceId` and `hostname` — they are
+  NOT NULL with no defaults.** `_ApiRequest`'s own logging sets all three (`ApiRequest.php:260-264`),
+  so a helper that writes its own log row while only setting `direction`/`source`/`method`/`route`
+  throws `Column 'X' cannot be null` on **every** insert. Because such helpers are usually a
+  *wrapper* around the real call, the throw propagates out of the wrapped call and, under a
+  `catch(Throwable)`, turns the whole feature into a **silent no-op that still reports success**.
+  Two worker2 handlers shipped with exactly this bug and one went unnoticed for months — see
+  [netsuite-opportunity-sync](../../worker2/features/netsuite-opportunity-sync.md#gotchas--known-issues).
+  Prefer letting `_ApiRequest` log rather than writing `Logs.Api` by hand.
+- **⚠ Auto-logging persists the `Authorization` header in PLAINTEXT.** `ApiRequest.php:267` writes
+  the full request headers to `Logs.Api.requestHeaders`, so any component that sends a bearer
+  token/API key and does not `setLogging(false)` is depositing that credential into the logs DB on
+  every call. Known live instance: `_underscore/Component/Api/Clickup/Clickup.php` (which also
+  **hardcodes** its token in committed source — flagged for a rotate-and-move-to-config ticket; 11
+  worker2 files use it). When adding a new component, decide deliberately: log and accept the header
+  exposure, strip/redact the auth header before the call is logged, or `setLogging(false)`.
+- **`Logs.Api` is 1.4M+ rows and `source` is NOT indexed.** Any diagnostic query must be bounded by
+  `dtStamp` (indexed) or it times out — `WHERE source = '…'` alone will not return.
+
 ## Change history
+- 2026-08-26 — Documented the **manual-insert column contract** (`isAuthRequest`, `instanceId`,
+  `hostname` are NOT NULL with no defaults, and `_ApiRequest` sets them at `ApiRequest.php:260-264`),
+  after a hand-rolled `logged()` helper in two worker2 handlers threw on every insert and silently
+  no-op'd an entire feature behind a `catch(Throwable)`. Also recorded that auto-logging persists the
+  **`Authorization` header in plaintext** into `Logs.Api.requestHeaders` (`ApiRequest.php:267`) — the
+  reason `_Component_Api_Clickup`'s hardcoded token needs rotation — and that `Logs.Api.source` is
+  unindexed at 1.4M+ rows, so queries must be bounded by `dtStamp`. (ajean)
 - 2026-08-05 — Documented (no code change) that the `direction = 'OUT'` api-log row is
   **committed immediately** inside `execute()` (`transactionCommit(DB_CLIENT_LOGS)`), so it
   survives a later rollback and `Logs_<Client>.Api` is definitive evidence of whether an outbound

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

@@ -11,4 +11,5 @@
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |
 | [Talos AI-Assistant Component (launcher + slide-out chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a slide-out chat panel (`TalosP | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/index.ts |
+| [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |

package/knowledge/2.0/apps/toga-blox/features/toaster.md

@@ -0,0 +1,100 @@
+---
+title: Toaster — host-token styling contract
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-08-26
+owners: [apeterson]
+files:
+  - toga-blox/src/components/Toaster/Toaster.module.css
+  - toga-blox/src/components/Toaster/Toaster.tsx
+  - toga-blox/src/components/Toaster/ToasterContext.tsx
+  - toga2-commerce/src/styles/index.css
+  - toga2-commerce/src/components/Toasters/ToasterList.tsx
+related:
+  - ../architecture.md
+  - ../../../standards/frontend.md
+  - ../../toga2-commerce/architecture.md
+---
+
+## Summary
+
+The blox `Toaster` is a CSS-Module component whose every visual property reads a
+`--toaster-*` custom property supplied by the **host app**. It is the clearest working example of
+the blox styling contract described in `frontend.md` §13(e) — and of that contract's failure mode:
+a host that defines **zero** tokens gets a component that renders **unstyled**, because every
+declaration is invalid-at-computed-value-time and dropped.
+
+As of 2026-08-26 the component ships **default values via `var(--token, fallback)`**, so it renders
+fully styled with no host configuration, while any host-defined `--toaster-*` token still wins.
+*(All Toaster changes below are working-tree on blox `feature-new-table` and commerce `TRUE-80707` —
+not yet merged or published; verify against the installed version before relying on them.)*
+
+## How it works
+
+### Token layer with fallbacks (the pattern to copy)
+
+Every declaration in `Toaster.module.css` is written `var(--toaster-x, <literal default>)`. This was
+chosen over adding a `:root` token block inside blox because:
+
+- blox ships **no** `:root` token block anywhere (§13e), and
+- `dist/main.css` is **uncompiled** and must not be imported by consumers (§13f),
+
+so a `:root` block would need a stylesheet import that no consumer makes. Fallbacks need nothing
+imported. **This is the generalisable rule for any blox component that reads host tokens: ship
+`var(--token, fallback)`, never a bare `var(--token)`.**
+
+### Do NOT declare a property on an element that also receives a host override class
+
+`.prefixIcon` and `.closeBtn` deliberately declare **no `color`**. The host's `iconColor` /
+`closeIconColor` classes land on those same elements at **equal specificity**, so a `color`
+declared in the module would be resolved by **stylesheet source order** and could silently beat the
+host's class (supply's mint/crimson icons losing to a grey default). They inherit from `.base`
+instead, which any host class reliably overrides. In-code comments record this so it is not
+"helpfully" re-added.
+
+### Host wiring — the variant-remap mechanism
+
+The supported way for a host to express toast variants is to define the `--toaster-*` layer once,
+then have each variant class **remap only the `--toaster-default-*` tokens** that blox's `.base`
+already reads. Do **not** style toasts with utility classes on a wrapper — Tailwind utilities and
+blox's `.base` land at equal specificity and compete unpredictably.
+
+```css
+:root { --toaster-padding: 1.25rem; /* … full token set … */ }
+.commerceToaster--error { --toaster-default-bg: …; --toaster-default-text: …; }
+```
+
+`toga25-supply` defines the full set (~33 tokens) in `src/themeConfig.json`; `toga2-commerce` now
+defines it in `src/styles/index.css` with `.commerceToaster--{success,error,restricted,default}`
+variant classes consumed by `ToasterList.tsx`. Commerce's result was verified by `tsc -b` / `vite
+build` and by inspecting the emitted CSS for the tokens and all four variant classes — **not
+visually in a browser**.
+
+## Gotchas
+
+- **A missing `var()` wrapper fails silently.** Two declarations read `min-width: (--toaster-min-width)`
+  / `max-width: (--toaster-max-width)` — no `var()`, so the parser dropped both. `toga25-supply`
+  masked this by re-declaring `min-width` on `.supplyToaster`; commerce had nothing to mask it, which
+  is how it surfaced. A host override can hide a blox CSS bug indefinitely.
+- **`border-width` + `border-color` with no `border-style` renders no border at all.** `.base`
+  previously set the first two only; `border-style` (plus `border-radius`, `font-family`,
+  `font-size`, `margin-block`) has been added.
+- **Order placement in commerce does not raise a success toast** — do not use it to test toast
+  styling. See `../../toga2-commerce/features/order-submit-sync-sequencing.md`.
+- Commerce's `restricted` (orange) variant is commerce-only; supply has no equivalent. Commerce's
+  palette has no `crimson-600`, so supply's error icon color maps to `crimson-500`.
+
+## Change history
+
+- 2026-08-26 — Toaster now ships **default styling** via `var(--token, fallback)` on every custom
+  property (renders styled with zero host config; host tokens still win) and gained the missing
+  `border-style`/`border-radius`/`font-family`/`font-size`/`margin-block` on `.base`. Fixed two
+  declarations missing their `var()` wrapper (`min-width`/`max-width`), which supply had been
+  masking. Recorded the deliberate **no `color` on `.prefixIcon`/`.closeBtn`** decision (equal
+  specificity with the host's `iconColor`/`closeIconColor` classes). `toga2-commerce` rewired to
+  supply's variant-remap mechanism and given the full `--toaster-*` token layer, replacing the
+  competing Tailwind-utility styling. (apeterson)

package/knowledge/2.0/apps/toga-blox/workflows/dynamic-publish-pipeline.md

@@ -93,6 +93,27 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   copy on the pushed branch, a new `_<mode>` channel will **not** publish unless the branch you push
   carries the wildcard-trigger version. When standing up a new channel, merge from a branch that has
   the dynamic `publish.yml` (or update it first).
+- **Do NOT judge a blox branch's staleness by its behind-count.** `feature-new-table` reports
+  **"0 ahead / 47 behind"** `_sandbox-client` and `git merge-base --is-ancestor` says it is fully
+  contained — which reads as "stale, already merged, wrong base". **It is not.** Those 47 commits are
+  almost entirely `Merge branch 'feature-new-table' into _sandbox-client` and
+  `chore: bump version to 1.0.3xx` — **release plumbing generated ON `_sandbox-client` by the publish
+  flow and never merged back**. The actual source difference is **2 files** (`src/global.css`,
+  `src/index.ts`); the rest of the 334-file diff is `.claude/knowledge/` docs and `publish.yml`.
+  `feature-new-table` is the **active development branch** (tip 2026-08-24, `feat: prefer
+  server-supplied filter options in table meta`) and is the correct base. Verified 2026-08-26.
+  Corollary: the `publish.yml` divergence noted above is a **non-issue for publishing**, because
+  Actions runs the workflow on the **pushed** branch (`_sandbox-client`), which carries the dynamic
+  `_*` trigger.
+- **A declared peer can be phantom — check before working around it.** Verified 2026-08-26:
+  `react-router-dom` appeared in blox's `peerDependencies` but only three files referenced it, two of
+  them tests; the single production reference was a **dead `import { Link }`** on line 1 of
+  `src/components/old/BaseButton/BaseButton.tsx` (the component renders an injected `linkComponent`
+  prop instead). The peer declaration and the dead import were removed *(working-tree on
+  `feature-new-table` — not yet merged or published)*; `react-router-dom` stays a
+  **devDependency** (`^6.30.1`) for the tests' `MemoryRouter`. Verified clean build, zero
+  `react-router-dom` references in `dist/`, and vitest identical to baseline. This peer was the
+  stated reason consumers pass `--legacy-peer-deps` against a router-7 app.
 - **FontAwesome v7 `style`-prop TS2322** (fixed 2026-07-21 in `getFontAwesomeIcon.tsx`, and a
   reusable pattern for any consumer). FA v7 types the `FontAwesomeIcon` `style` prop as
   `CSSProperties & CSSVariables`, where `CSSVariables` requires a `--fa-*` custom-property index
@@ -122,6 +143,12 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   the pattern the consuming apps should follow (see the commerce workflow's secret-hygiene note).
 
 ## Change history
+- 2026-08-26 — Corrected the branch-topology misreading: `feature-new-table`'s "0 ahead / 47 behind"
+  is release plumbing generated on `_sandbox-client`, not staleness — it remains the active dev
+  branch and correct base (real source delta: 2 files). Noted the `publish.yml` divergence is a
+  non-issue because Actions runs the pushed branch's copy. Removed the **phantom
+  `react-router-dom` peer** (its only production reference was a dead `Link` import in
+  `old/BaseButton`); it is now a devDependency for tests only. Working-tree, uncommitted. (apeterson)
 - 2026-08-04 — Recorded the prod/beta `.scss`-only build gotcha: the `_production`/`_beta`
   `build` copies only `src/**/*.scss`, so a component shipped with a plain `.css` + matching
   `import "./X.css"` publishes JS referencing a stylesheet absent from the tarball, breaking

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -16,6 +16,6 @@
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | Submitting an order from the cart fires **two independent sync routines** — one for the sales-order header (`syncSalesOrderData`) and one for the line items (`s | toga2-commerce/src/pages/OrderDetails/hooks/useSubmitOrder.ts, toga2-commerce/src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts, toga2-commerce/src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | On the toga2-commerce **Cart** page, a shipping option's **cost** can be waived by config using the same `PrimaryItemShippingRule` vocabulary that drives expedi | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/CartPage.tsx |
-| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |
+| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.npmrc, toga2-commerce/vite.config.ts, toga2-commerce/.github/workflows/sync-stage-environments.yml |
 | [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | The Cypress **e2e** convention set for `toga2-commerce`, and the first **active** e2e coverage for the **Cart** page (`cartV2.cy.ts`, slice 1 — 12 tests, verifi | toga2-commerce/cypress/e2e/cartPage/cartV2.cy.ts, toga2-commerce/cypress/fixtures/cart/fetchSingleUserAdmin.json, toga2-commerce/cypress/fixtures/cart/fetchLocations.json, toga2-commerce/cypress/fixtures/cart/fetchUserShippingMethods.json, toga2-commerce/cypress/support/commands.ts, toga2-commerce/cypress/support/e2e.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartFormSection.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartContentsTable.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartTableItem.tsx, toga2-commerce/src/components/Inputs/AdvancedInput.tsx, toga2-commerce/src/components/BaseButton/BaseButton.tsx |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | When a Chromium browser (Chrome / Edge) shows **`ERR_HTTP2_PROTOCOL_ERROR`** loading a `*.togacommerce.com` tenant for **one client/network but works for the TO |  |

package/knowledge/2.0/apps/toga2-commerce/features/order-submit-sync-sequencing.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
-owners: ["bala"]
+updated: 2026-08-26
+owners: ["bala", "apeterson"]
 files:
   - toga2-commerce/src/pages/OrderDetails/hooks/useSubmitOrder.ts
   - toga2-commerce/src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts
@@ -134,9 +134,22 @@ Three changes, in `toga2-commerce`:
 - **⚠ Omitting a line from the rebuilt cart DELETES it from a placed order.** `processItems` with
   `getDeleteItems = true` derives the delete set by difference, so "don't re-add this one" and
   "destroy this one" are the same instruction on this path.
+- **There is NO success toaster on order placement — by design, not a bug.** `useSubmitOrder` calls
+  `addToaster` **only in its `catch` block** (`status: 'error'`). Both success paths navigate away
+  before anything could render: cart → `createNewSalesOrderSubmit()` →
+  `navigate("/order-details?uuid=…&type=orderPlaced")` (no `addToaster` anywhere in it); edit-order →
+  `window.location.href = getSupplyRedirectLink(orderUuid)`. **Consequence for debugging: placing an
+  order is not a valid way to test toaster styling.** Use a path that stays mounted — add/edit
+  shipping address (Cart or Account), Account → My Settings, or Cart → add new user; for the error
+  variant, force a submit failure to hit the catch block. See
+  [blox Toaster](../../toga-blox/features/toaster.md).
 
 ## Change history
 
+- 2026-08-26 — Recorded that order placement raises **no success toaster by design** (`addToaster`
+  is only in the `catch`; both success paths navigate away), and listed the mounted-path
+  alternatives for testing toaster styling. (apeterson)
+
 - 2026-08-14 — Recorded **how order lines are actually written**, learned while adding a
   server-side order guard: the header sync `delete`s `salesOrderItems` from the edit `PUT` (line
   20), and lines are written **one request at a time** — new lines via the nested

package/knowledge/2.0/apps/toga2-commerce/workflows/amplify-build-and-deploy.md

@@ -6,16 +6,19 @@ project: TOGa Commerce
 client: shared
 type: workflow
 status: active
-updated: 2026-07-21
-owners: ["jcardinal"]
+updated: 2026-08-26
+owners: ["jcardinal", "apeterson"]
 files:
   - toga2-commerce/amplify.yml
   - toga2-commerce/.gitattributes
   - toga2-commerce/package.json
+  - toga2-commerce/.npmrc
+  - toga2-commerce/vite.config.ts
   - toga2-commerce/.github/workflows/sync-stage-environments.yml
 related:
   - ../../toga2-supply/workflows/amplify-build-and-deploy.md
   - ../../toga-blox/workflows/dynamic-publish-pipeline.md
+  - ../../../standards/frontend.md
 ---
 
 ## Summary
@@ -69,6 +72,10 @@ full cross-repo publish-then-build model. **The channel must exist before the ap
 
 ## Edge cases & escalation
 
+> The 2026-08-26 commerce-side fixes below (`.npmrc` flag, added peers, `resolve.dedupe`, the
+> `--toaster-*` token layer, the `ToasterList` rewiring) are **working-tree on branch `TRUE-80707`** —
+> uncommitted, unmerged, and not in any deployed build.
+
 - **All the toga2-supply gotchas apply** (console build spec overriding repo `amplify.yml`;
   CRLF breaking block-scalar parsing; Vite silently falling back to `.env`/beta when a mode's env
   file is missing). See the related doc.
@@ -77,14 +84,44 @@ full cross-repo publish-then-build model. **The channel must exist before the ap
   only triggers on branches listed in `on.push.branches` and only tags branches with an explicit
   `elif` case — creating the branch alone does nothing; the workflow file must be present on that
   branch (GitHub Actions runs the workflow version on the pushed branch).
-- **`--legacy-peer-deps` is required** because blox declares `react-router-dom@^6` as a peer while
+- **`--legacy-peer-deps` is required** because blox declared `react-router-dom@^6` as a peer while
   commerce uses `react-router-dom@7` (npm 7+ `ERESOLVE` otherwise). All non-prod build scripts use it.
+  (That peer was **phantom** and was removed from blox on 2026-08-26 — see the blox publish-pipeline
+  doc — but the flag stays until a build without it is proven.)
+- **When one app installs a shared lib and a sibling app does not, compare `.npmrc` BEFORE touching
+  peer ranges.** A local `npm i` in commerce failed `ERESOLVE` on blox's router peer while
+  `toga25-supply` installed cleanly against the **same** blox version and the **same** router major.
+  The difference was not the peer range: supply carries `legacy-peer-deps=true` in its committed
+  `.npmrc` and commerce did not. Fix was adding `legacy-peer-deps=true` to commerce's `.npmrc` — a
+  tracked file, so it also reaches the Amplify build (the amplify.yml flag alone does not cover a
+  developer's local install).
 - **`--legacy-peer-deps` disables npm's peer auto-install**, so any blox peer that is NOT in
   commerce's own `dependencies` and NOT in blox's `dependencies` must be added explicitly, or Vite/
   Rollup fails with `failed to resolve import "<pkg>"`. Concretely, commerce had to add the table
-  peers: `@tanstack/react-table@^8`, `react-table@^7.8.0`, `react-table-sticky@^1.1.3`. Check
-  `npm view @agilant/toga-blox@<tag> peerDependencies` against commerce deps when a resolve error
-  appears.
+  peers: `@tanstack/react-table@^8`, `react-table@^7.8.0`, `react-table-sticky@^1.1.3`, and on
+  2026-08-26 `@fortawesome/free-solid-svg-icons@^6.7.2` + `react-multi-select-component@^4.3.4`.
+  Check `npm view @agilant/toga-blox@<tag> peerDependencies` against commerce deps when a resolve
+  error appears.
+- **A BARREL import is what drags in peers you never use.** The failure text was
+  `Rollup failed to resolve import "@fortawesome/free-solid-svg-icons" from
+  node_modules/@agilant/toga-blox/dist/components/Input/Input.js`, triggered by
+  `AuthLayout.tsx` doing `import { EnvironmentBadge } from "@agilant/toga-blox"` — the package
+  index pulls `Input` and `MultiSelect` along with it. A deep import would not have surfaced it, so
+  expect the missing-peer set to be blox's **whole** surface, not the components you reference.
+- **`resolve.dedupe` was missing from commerce's `vite.config.ts`** (a `frontend.md` §11 MUST), which
+  made consuming blox via a local symlink hazardous: `toga-blox-npm/node_modules/` contains its own
+  `react@18.3.1`/`react-dom@18.3.1`, and because blox ships **unbundled**, imports resolve against
+  the nearest `node_modules` — under a symlink that is blox's own, giving a second React copy. This
+  is precisely why supply's symlink workflow works (it has always deduped
+  `react`/`react-dom`/`@tanstack/react-table`) and commerce's did not. Commerce now dedupes
+  `react`, `react-dom`, `react-hook-form`, `react-router-dom`, `framer-motion`,
+  `@tanstack/react-query`, `@tanstack/react-table`.
+- **`package.json` pins blox with a CARET** (`"@agilant/toga-blox": "^1.0.322-sandbox-client.117"`),
+  violating `frontend.md` §13(a) — some published versions ship an empty `dist`, and a caret can
+  float you onto one. Pin exact. Related: the `TRUE-80707` branch pin is **11 versions behind** the
+  `_sandbox-client` branch pin (`1.0.333-sandbox-client.134`); reconcile before merging.
+- **Secret hygiene re-confirmed unremediated 2026-08-26** — the live tokens are still in the tracked
+  `.npmrc` in **both** `toga2-commerce` and `toga25-supply`. See the remediation below.
 - **Secret hygiene (open remediation):** `toga2-commerce/.npmrc` is **git-tracked** — it is listed
   in `.gitignore` but was committed before that, so git still tracks it, and it holds a live
   FontAwesome registry token and a live npm auth token in plaintext. Remediation: (1) **rotate both
@@ -95,6 +132,13 @@ full cross-repo publish-then-build model. **The channel must exist before the ap
 
 ## Change history
 
+- 2026-08-26 — Dependency-resolution findings from a local commerce build: root-caused an
+  `ERESOLVE` to the **missing `legacy-peer-deps=true` in commerce's tracked `.npmrc`** (supply had
+  it) rather than blox's peer range; recorded the barrel-import trigger for missing peers (added
+  `@fortawesome/free-solid-svg-icons`, `react-multi-select-component`); added the previously absent
+  `resolve.dedupe` to `vite.config.ts` and explained why supply can symlink blox safely and commerce
+  could not; flagged the caret blox pin and the 11-version pin drift on `TRUE-80707`; re-confirmed
+  the committed `.npmrc` tokens are still unremediated. All working-tree, uncommitted. (apeterson)
 - 2026-07-21 — Reworked `amplify.yml` to a **fully dynamic inline build** (no per-branch `case`, no
   `npm run <script>`): derive mode from `$AWS_BRANCH`, dynamic `npm install
   "@agilant/toga-blox@$MODE"`, `npx tsc -b` (composite), `npx vite build --mode "$MODE"`. Re-export

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

@@ -26,6 +26,7 @@
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
 | [NetSuite Integrations Monitor (Monitor/Operations/NetsuiteIntegrations)](features/netsuite-integrations-monitor.md) | `_Worker_Monitor_Operations::NetsuiteIntegrations()` is a cross-client health check that detects **stuck NetSuite ↔ 2.0 integrations**. | worker2/Worker/Monitor/Operations.php, dbchanges2/Core/2026-08-10a - Netsuite Integrations Monitor.sql, _underscore/Database.php, _underscore/Query.php |
+| [ClickUp Opportunity Client vs End-Customer Labels (Stakeholders / End Customer)](features/netsuite-opportunity-client-labels.md) | The NetSuite→ClickUp opportunity task carries **two** customer labels, not one (TRUE-81010, PR #142): - **Stakeholders** = the **client** — the consolidated par | worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/OpportunityStakeholderDigest.php, worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php |
 | [NetSuite ↔ ClickUp / TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Clickup.php, worker2/Worker/Clickup/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, _underscore/Model/Forecast/Opportunity.php, test/@dave/approach/TRUE-80044.md, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, worker2/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Location.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_amq_invoice_resync_salesorder.js, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [Toga → NetSuite Sales-Order Push (multi-client, mapping-driven worker)](features/netsuite-salesorder-outbound-push.md) | The **outbound** half of `worker2/Worker/Netsuite/SalesOrder.php` (everything from the `OUTBOUND PUSH (REST)` banner down) pushes a Toga sales order **into** Ne | worker2/Worker/Netsuite/SalesOrder.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-13
-owners: [jcardinal, dfranks, mhammontree, tcox, bala]
+updated: 2026-08-26
+owners: [jcardinal, dfranks, mhammontree, tcox, bala, ajean]
 files:
   - worker2/Worker/
   - worker2/Controller/Index.php
@@ -309,10 +309,25 @@ Rules: rename **both sides in one PR and one deploy**; grep every repo for the o
   host. **Production's `[databaseClient]` additionally exposes a `readhost`** (a reader endpoint);
   use it for **bulk reads** rather than the primary. Credential *values* live only in the ini files —
   never copy them anywhere else.
+- **A new action does not run on a schedule until a `Core.CronJobs` row exists.** The schedule
+  registry is **data, not code** — shipping the PHP file changes nothing on its own. Ship the code
+  deploy and the `dbchanges2` cron-row migration together (see "Adding a new cron job" above).
+- **For a code path gated behind a RARE condition, build a dry-run entry point and fire it
+  deliberately — do not wait for the path to fire naturally.** A dry run enqueued against production
+  found a fatal bug in ~2 seconds that two weeks of green telemetry had not: the path was reached
+  only when a NetSuite opportunity webhook carried a presales lead (83% return
+  `skipped (no presales lead)`; ~36 tasks in 14 days), so natural traffic would have hidden the
+  failure indefinitely. The dry run must exercise the **same helpers** as the real path — a separate
+  test harness that reimplements them proves nothing. See
+  [netsuite-opportunity-sync](./netsuite-opportunity-sync.md#gotchas--known-issues) for what it caught.
 - See [architecture.md](../architecture.md) for the always-HTTP-200 rule and the
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-08-26 — Added two operational gotchas: a new action **does not run on a schedule until its
+  `Core.CronJobs` row exists** (schedule is data, not code), and the practice of building a
+  **dry-run entry point for a rare-gated path** rather than waiting for it to fire — one found a
+  fatal `Logs.Api` insert bug in seconds after two weeks of green telemetry missed it. (ajean)
 - 2026-08-13 — Added a **database-side test for "the tier stopped consuming"**, which resolves the
   absent-`WorkerJobs`-row ambiguity without SQS metrics: compare created vs. completed
   `Core.WorkerJobs` for the day — on dev-sandbox 2026-08-12, **1,548 created / 1,547 never

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-client-labels.md

@@ -0,0 +1,138 @@
+---
+title: ClickUp Opportunity Client vs End-Customer Labels (Stakeholders / End Customer)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-08-26
+owners: ["ajean"]
+files:
+  - worker2/Worker/Netsuite/Opportunity.php
+  - worker2/Worker/Netsuite/OpportunityStakeholderDigest.php
+  - worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php
+related:
+  - ./netsuite-opportunity-sync.md
+  - ./creating-worker-actions.md
+  - ./notification-email.md
+---
+
+## Summary
+
+The NetSuite→ClickUp opportunity task carries **two** customer labels, not one (TRUE-81010, PR #142):
+
+- **Stakeholders** = the **client** — the consolidated parent company we contract with.
+- **End Customer** = the NetSuite opportunity `entity` — the specific (often sub-)customer the work
+  is for.
+
+Before this change the sync pushed `entity->refName` into **Stakeholders**, flattening the two
+levels of the NetSuite customer hierarchy into one field. Verified against production that `entity`
+is the **end customer**, and the client is the consolidated parent (NetSuite `custentity10`):
+`Forecast.Customers` row `"6096:6308 Compass Group"` hangs off `Forecast.ConsolidatedCustomers`
+`"Office Depot"` — Office Depot is who we bill, Compass Group is who receives.
+
+Two support actions ship with it: a **daily digest** of label options still to create in ClickUp,
+and a **seed-if-empty backfill** for the 761 tasks that already exist.
+
+## Key files / entry points
+
+- `worker2/Worker/Netsuite/Opportunity.php` — `deriveLabelNames()`, `splitCustomerRefName()`,
+  `buildCustomFields()`. The sync itself; see [netsuite-opportunity-sync](./netsuite-opportunity-sync.md).
+- `worker2/Worker/Netsuite/OpportunityStakeholderDigest.php` — action
+  `Netsuite/OpportunityStakeholderDigest/Daily` (`dryRun=false`, `to=null`).
+- `worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php` — action
+  `Netsuite/OpportunityStakeholderBackfill/Backfill` (`dryRun=true`, `taskId=null`, `exactOnly=true`).
+
+**ClickUp field ids** on list `901111987449` (Presales Qualification), both `labels` type with ~169
+options each: `Stakeholders` = `ec15edfd-5920-4c12-a1dc-94ede4a62438`,
+`End Customer` = `67bb359f-fa59-40e1-b94a-0076450bb7c0`.
+
+## How it works
+
+**Resolution is entirely local — no extra NetSuite call.** The opportunity payload carries only a
+flat `entity` ref, and `expandSubResources` does **not** dereference it to the consolidated parent.
+So the client is resolved through Forecast:
+
+```
+Opportunities.customerId → Customers.consolidatedCustomerId → ConsolidatedCustomers.name
+```
+
+`deriveLabelNames()` then applies three rules, each sized against production data:
+
+1. **No consolidated parent → the entity IS the client.** 186 of 759 task-bearing opportunities
+   (24.5%) have no parent. Stakeholders then receives exactly what it received before the change,
+   so the swap is not a regression for them.
+2. **Mirror when equal.** For 678 of 761 the parent is the same company as the entity
+   (`"4679 Staples, Inc."` → `"Staples, Inc."`). Both fields carry the same value rather than one
+   being left blank — which makes an **empty field an unambiguous signal that resolution FAILED**,
+   and nothing else.
+3. **Genuinely different parent** in only 83 of 573 parented opportunities (14.5%, 25 distinct
+   pairs) — the case the split exists for.
+
+Net effect measured on production: Stakeholders exact-match rose from **31.5% to 36.4%** (47.0%
+including fuzzy).
+
+### Daily digest (`OpportunityStakeholderDigest/Daily`)
+
+The originally-shipped per-opportunity "option missing" email does not survive real data — **402 of
+759** task-bearing opportunities fail to resolve a client label, and a second field roughly doubles
+that, i.e. hundreds of mails a day. It is replaced by **one spreadsheet each morning** to
+`pmteam@togatech.com` listing every label option still to add, sorted by opportunity count.
+
+**Stateless by design:** recomputed from live Forecast rows + live ClickUp options on every run. No
+table, no migration, no reconciliation state — a row simply disappears from tomorrow's digest once
+someone adds the option in ClickUp.
+
+### Seed-if-empty backfill (`OpportunityStakeholderBackfill/Backfill`)
+
+Existing tasks are never reached by the sync (see the claim gotcha below), so a separate backfill is
+the only way to populate them.
+
+- **Seed-if-empty, never overwrite.** A ClickUp `labels` write is **add-only and therefore
+  accumulates**: re-pointing an opportunity would leave the task carrying two clients with no signal
+  which is current. Seeding only empty fields also makes re-runs write nothing.
+- **`exactOnly` defaults TRUE.** On live data `"Lee County Sheriff's Office"` scores **86.8%**
+  against the option `"Polk County Sheriff Office"` — over the 85% fuzzy floor, wrong county, 12
+  opportunities affected, and nothing would have surfaced it. Fuzzy matching is opt-in only.
+- **Pacing is 700 ms per REQUEST, not per task** (~85/min against ClickUp's 100/min/token). A task
+  costs a variable 1–3 requests, so per-task pacing cannot bound the request rate.
+
+## Gotchas / known issues
+
+- **`splitCustomerRefName()` must handle composite sub-customer numbers.** The original pattern
+  `/^(\d+)\s+(.*)$/` (digits then whitespace) could not parse `"6096:6308 Compass Group"` — the colon
+  broke the match, the number stayed in the name, and normalization produced
+  `"60966308compassgroup"`, which can never match a ClickUp option. **15.4% of `Forecast.Customers`
+  use this composite form** (1,418 of 9,211) and they are precisely the hierarchical customers this
+  feature exists to distinguish. Now `/^(\d+(?::\d+)*)\s+(.*)$/` — still requiring the whitespace so
+  `"3M Company"` is not decapitated.
+- **Option ids ride on `$body`, not on extra positional arguments.** `buildCustomFields()` used to
+  take the Stakeholders option id as an optional 3rd argument, but `updateTask()` called it as
+  `buildCustomFields($body, $presalesUserId)` — two arguments — so that path could never set the
+  field even if `UPDATE_CLICKUP` were true. Passing option ids on `$body` (the pattern
+  `opportunityStageOrderIndex` already used) makes the divergence structurally impossible and keeps
+  the signature under the 4-positional-parameter limit.
+- **The empty field means "resolution failed" — that is the whole diagnostic.** Because of the
+  mirror-when-equal rule, a blank Stakeholders or End Customer is never "same as the other one";
+  it is always a missing ClickUp option or a failed lookup, and it will appear in the next digest.
+- **The digest emails INLINE, it does not attach.** See
+  [notification-email](./notification-email.md#gotchas--known-issues) — the EmailTemplate action has
+  no attachment parameter and `_Email::addAttachment()` takes a **file path**, which an enqueued job
+  running later may no longer find.
+- **CSV values beginning `=`, `+`, `-` or `@` are apostrophe-prefixed** against spreadsheet formula
+  injection before they go into the digest.
+
+## Change history
+- 2026-08-26 — **Built the client vs end-customer split (TRUE-81010, PR #142, merged).** Stakeholders
+  now receives the consolidated parent (the client, NS `custentity10`) and a new **End Customer**
+  field receives the opportunity `entity`; resolution is local via
+  `Opportunities.customerId → Customers.consolidatedCustomerId → ConsolidatedCustomers.name` with no
+  extra NetSuite call. Three mapping rules sized against production (no-parent → entity is the
+  client, 24.5%; mirror-when-equal, 678/761; genuinely-different parent, 83/573) lifted Stakeholders
+  exact-match 31.5% → 36.4%. Fixed `splitCustomerRefName()` to parse composite sub-customer numbers
+  (`6096:6308 …`, 15.4% of Forecast.Customers). Moved option ids onto `$body` to kill a
+  `buildCustomFields()` optional-argument divergence. Added the daily
+  `OpportunityStakeholderDigest` (one spreadsheet to pmteam@ replacing hundreds of per-miss mails;
+  stateless) and the `OpportunityStakeholderBackfill` (seed-if-empty, `exactOnly` default true,
+  700 ms per-request pacing). (ajean)

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-19
-owners: ["dfranks", "kyalamarthi"]
+updated: 2026-08-26
+owners: ["dfranks", "kyalamarthi", "ajean"]
 files:
   - worker2/Worker/Netsuite.php
   - worker2/Worker/Netsuite/Opportunity.php
@@ -29,6 +29,7 @@ files:
   - test/@dave/approach/TRUE-80044.md
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
+  - ./netsuite-opportunity-client-labels.md
   - ./netsuite-salesorder-open-orders-sync.md
   - ../architecture.md
 ---
@@ -152,6 +153,10 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   `Opportunity #` (`a5529cdc-…`) ← `tranId`; `Customer #` (`170dc118-…`) ← `entity->refName`
   (the customer **name**, deliberately — not the NetSuite customer number). Plus `Sales Rep`,
   `Presales Lead Email`, and `Presales Lead` (users field).
+  **Since 2026-08-26 the two customer *labels* fields are a separate subject** — `Stakeholders`
+  carries the **client** (the consolidated parent) and `End Customer` carries the opportunity
+  `entity`. See [ClickUp Opportunity Client vs End-Customer Labels](./netsuite-opportunity-client-labels.md);
+  do not re-derive that mapping here.
 - The ClickUp token comes from `[clickup] token` in the worker2 config (legacy webhook received
   it on the payload; the new contract drops it).
 - Every ClickUp `_ApiRequest` calls `setLogging(self::CLICKUP_API_LOGGING_ENABLED=false)`, so ClickUp
@@ -168,11 +173,11 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   removing that `setLogging(false)` is under review (handle the 20–50 KB payload volume the
   prod-appropriate way — retention/sampling/summary — not by defaulting logging off).
 
-## Atomic ClickUp-task claim (TRUE-80044 — decided approach, not yet built)
+## Atomic ClickUp-task claim (TRUE-80044 — BUILT, in production)
 
 Concurrent NetSuite opportunity webhooks (a real edit racing NetSuite's hourly `OPP` fallback) can both
 pass the non-atomic find-then-create in `maybeCreateClickupTask()` and create **duplicate** ClickUp
-tasks. The fix is a **race-safe DB claim** on the **existing `Forecast.Opportunities` table** — an added
+tasks. The fix — **now built and running in production** — is a **race-safe DB claim** on the **existing `Forecast.Opportunities` table** — an added
 `clickupTaskId` column — **not** a new dedicated table. (A prior plan proposed a new
 `NetsuiteOpportunityClickupTask` table in `Client_True`; reviewer Rohan Girish rejected that and mandated
 reusing `Forecast.Opportunities`.)
@@ -198,9 +203,24 @@ How the claim is race-safe:
 - **Edge case:** if `importOpportunity()` was skipped (no NS status → no Forecast row), there is nothing
   to claim; that rare path falls back to today's unguarded create.
 
-Requires a new `dbchanges2/Forecast/` ALTER adding the `clickupTaskId` column, and a
+Required a new `dbchanges2/Forecast/` ALTER adding the `clickupTaskId` column, and a
 `_underscore/Model/Forecast/Opportunity.php` field addition. Plan: `test/@dave/approach/TRUE-80044.md`.
 
+### Consequence: `updateTask()` is unreachable — `UPDATE_CLICKUP` alone does NOT revive it
+
+`maybeCreateClickupTask()` claims the row **before** it ever looks at ClickUp
+(`Opportunity.php:40`): `UPDATE Opportunities SET clickupTaskId='PENDING' WHERE … AND clickupTaskId
+IS NULL`. Once `clickupTaskId` holds a real id, **every later webhook for that opportunity returns
+`skipped (already claimed)` and exits** — it never reaches the find-then-update branch.
+
+So `updateTask()` is dead **twice over**: behind `UPDATE_CLICKUP = false` *and* behind the claim.
+Flipping the constant activates ~180 lines of code that have **never run in production** and still
+reaches **none** of the 761 existing tasks — only a separate backfill action reaches those (see
+[client vs end-customer labels](./netsuite-opportunity-client-labels.md#seed-if-empty-backfill-opportunitystakeholderbackfillbackfill)).
+`UPDATE_CLICKUP` stays `false`. **This is a trap for the next developer:** the constant's own comment
+says nothing about the claim interaction, so reading the constant alone gives you the wrong model of
+what enabling it would do.
+
 ## Data model
 
 Writes `Forecast.Opportunities` (header) + `Forecast.OpportunityItems` (children), faithful to
@@ -340,8 +360,8 @@ None — platform-wide Forecast sync.
   (create branch, new task `868k2rfj8`).
 - **ClickUp dedup keys on the `Opportunity #` field, not a DB column.** Historically we did NOT add
   a `clickupTaskId` column — the dedup lookup queried ClickUp itself by `Opportunity #` (= tranId).
-  **This is being replaced (TRUE-80044) by a race-safe DB-claim approach — see "Atomic ClickUp-task
-  claim" below.** Consequences of the field-lookup approach to know:
+  **This has been replaced (TRUE-80044) by the race-safe DB-claim approach — see "Atomic ClickUp-task
+  claim" above.** Consequences of the field-lookup approach to know:
   - **Legacy tasks had `Opportunity #` empty** (the old `webhook/` handler never set it), so they
     can't be matched until backfilled — see the backfill tool below. Without backfill, the first
     edit of a pre-existing opp creates a *second* task.
@@ -422,6 +442,33 @@ None — platform-wide Forecast sync.
   (doubled-prefix ids — see the doubled-id gotcha), which are **SuiteQL-queryable** for after-the-fact
   diagnosis even though the calling-script log rolls off.
 
+- **`logged()` could never insert a `Logs.Api` row — and it failed the whole feature SILENTLY.**
+  `Logs.Api` has NOT-NULL columns with **no defaults**. The `logged()` helper set
+  `direction`/`source`/`method`/`route` but never `isAuthRequest`, `instanceId` or `hostname`, so
+  **every** insert threw `Column 'X' cannot be null` and the exception propagated out of the wrapped
+  call. (`_ApiRequest`'s own auto-logging sets all three — `ApiRequest.php:260-264` — which is why
+  the omission is invisible when you compare against normal api-logged traffic.) The blast radius was
+  far wider than one failing cron: the NS→CU webhook path calls this inside
+  `try/catch(Throwable)`, so the whole TRUE-81010 label feature was a **permanent no-op that reported
+  success** — tasks created, both label fields empty, `(label lookup failed)` in the output, every
+  job green. **The identical omission existed in `_Worker_Clickup_Opportunity::logged()`**, where the
+  helper was ported from — fixed there too (PRs #150 + #151). Evidence it never once worked: since
+  1 July `Logs.Api` held exactly two `source` values — `NULL` (1,413,654 rows, the `_ApiRequest`
+  auto-log path) and `OPEN_ORDER_IMPORT` (87,476). **Zero** `clickup-opportunity` rows, i.e. the
+  CU→NS sync's outbound logging has been dead since it shipped and nobody noticed. See
+  [`_ApiRequest`](../../_underscore/features/apirequest-json-content-type.md#gotchas--known-issues)
+  for the full manual-insert column contract.
+- **When porting a helper, port its correctness too.** A faithful copy of broken code is still
+  broken, and a swallowed exception hides it indefinitely — that is exactly how one missing-column
+  bug ended up in two handlers and survived two weeks of green telemetry.
+- **Do NOT reach for `_Component_Api_Clickup` for new work.** A live ClickUp API token is
+  **hardcoded in committed source** at `_underscore/Component/Api/Clickup/Clickup.php:5`, and because
+  `send()` never disables `_ApiRequest`'s auto-logging, that `Authorization` header has been
+  persisted into `Logs.Api.requestHeaders` in **plaintext on every call** (`ApiRequest.php:267`).
+  11 worker2 files use the component. The TRUE-81010 work deliberately routed around it with an
+  inline `_ApiRequest`. **Needs its own ticket:** rotate the token and move it to config. (Never
+  paste the value anywhere, including here.)
+
 ## CU→NS direction (BUILT 2026-06-30, TRUE-79181): reverse sync
 
 The integration is now **bidirectional** for **field + stage**. ClickUp task edits flow back to the
@@ -502,6 +549,18 @@ deprecated** for production opportunity code.
   blocked on the Aaron stakeholder decision noted above.
 
 ## Change history
+- 2026-08-26 — **Fixed `logged()` (PRs #150 + #151) and confirmed the atomic claim makes
+  `updateTask()` unreachable.** `logged()` omitted the NOT-NULL `isAuthRequest`/`instanceId`/
+  `hostname` columns, so every `Logs.Api` insert threw and — inside the webhook path's
+  `catch(Throwable)` — turned the whole TRUE-81010 label feature into a silent no-op that reported
+  success; the same omission was fixed in `_Worker_Clickup_Opportunity::logged()`, whose outbound
+  logging had been dead since it shipped (zero `clickup-opportunity` rows in `Logs.Api`). Also
+  recorded that `maybeCreateClickupTask()` claims `clickupTaskId` **before** consulting ClickUp
+  (`Opportunity.php:40`), so `updateTask()` is dead twice over — flipping `UPDATE_CLICKUP` activates
+  never-run code and still reaches none of the 761 existing tasks. Flagged the hardcoded ClickUp
+  token in `_underscore/Component/Api/Clickup/Clickup.php` (plaintext `Authorization` persisted to
+  `Logs.Api.requestHeaders`) for a dedicated security ticket. The Stakeholders/End Customer label
+  mapping moved to its own doc. (ajean)
 - 2026-08-19 — Recorded a second, worse instance of the "`Released` ≠ active" enqueuer-deployment failure
   family: the AMQ enqueuer is deployed **per record type**, and **Customer** (`customdeploy9`, deployment
   internal id 9) was still at `status = TESTING` / `isdeployed = F` while the other 15 types were

package/knowledge/2.0/apps/worker2/features/notification-email.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: ["mhammontree", "jcardinal"]
+updated: 2026-08-26
+owners: ["mhammontree", "jcardinal", "ajean"]
 files:
   - worker2/Worker/Notification/Email.php
   - _underscore/Model/Client/EmailTemplate.php
@@ -140,10 +140,27 @@ working recipe — verified in classic + new Outlook:
 - **Missing wrapper row → unbranded send, logged.** If a client has no active wrapper row the alert
   still goes out (raw body) and an `error_log` line records the missing uuid. Branding is *not*
   guaranteed on this path by design (internal mail). Don't rely on it for client-facing email.
+- **There is no attachment path on the worker email actions — send the payload INLINE.**
+  `_Worker_Notification_EmailTemplate::Send` has **no attachment parameter**, and
+  `_Email::addAttachment()` takes a **file path**, which an enqueued job running minutes later on a
+  different instance may no longer be able to find. A generated report (e.g. a CSV digest) should be
+  rendered into the body via `_Worker_Notification_Email::Send` rather than attached. Proven by
+  `Worker/Netsuite/OpportunityStakeholderDigest.php` — see
+  [ClickUp opportunity client labels](./netsuite-opportunity-client-labels.md).
+- **Commit your own DB work BEFORE calling `Send()`.** `_Email` registers the client-log DB and
+  toggles the read host as a side effect of sending; doing that inside your still-open transaction
+  is asking for trouble. A worker that has been writing to, say, `DB_FORECAST` should
+  `_Database::transactionCommit(DB_FORECAST)` first, then send.
 - **`{subject}`/`{body}` substitution is `strtr`, not sequential `str_replace`.** All placeholders
   are replaced simultaneously, so a `{body}` literal inside the subject can't be re-expanded.
 
 ## Change history
+- 2026-08-26 — Documented (no code change) that **neither worker email action can attach a file** —
+  `EmailTemplate::Send` has no attachment parameter and `_Email::addAttachment()` takes a file path
+  an enqueued job may not still have — so generated reports go **inline in the body**; and that a
+  caller must **commit its own transaction before `Send()`**, because `_Email` registers the
+  client-log DB and toggles the read host mid-send. Surfaced building the daily opportunity
+  stakeholder digest. (ajean)
 - 2026-08-04 (**uncommitted/undeployed** at time of writing) — Added an optional trailing
   `?int $priority = null` to `Send()`, mapping to `_Email::setPriority()`
   (`X-Priority`/`Importance`/`X-MSMail-Priority`). Backward compatible because the dispatcher

package/knowledge/2.0/standards/frontend-deploy.md

@@ -5,8 +5,8 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-07-21
-owners: [jcardinal]
+updated: 2026-08-26
+owners: [jcardinal, apeterson]
 related:
   - ../apps/toga25-supply/workflows/amplify-deployment.md
   - ../apps/toga-blox/workflows/dynamic-publish-pipeline.md
@@ -50,7 +50,12 @@ strict 1:1). When an app does this:
   hardcoded per-branch list, so one `amplify.yml` serves every environment.
 - `--legacy-peer-deps` may be required when the app's and library's peer ranges diverge; when it
   is used, npm will not auto-install the library's peers, so any peer not already in the app's
-  dependencies must be added explicitly.
+  dependencies must be added explicitly. **Set it in the app's committed `.npmrc`
+  (`legacy-peer-deps=true`), not only as a CLI flag in `amplify.yml`** — otherwise a developer's
+  local `npm i` fails `ERESOLVE` while CI succeeds. When one app installs the shared lib cleanly and
+  a sibling does not at the same lib and peer versions, **diff the two `.npmrc` files before
+  touching any peer range** (verified 2026-08-26: `toga25-supply` had the flag, `toga2-commerce` did
+  not; commerce's `.npmrc` fix is working-tree on `TRUE-80707`, not yet merged).
 
 ## Build memory / heap
 

package/knowledge/2.0/standards/frontend.md

@@ -5,8 +5,8 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-18
-owners: [jcardinal]
+updated: 2026-08-26
+owners: [jcardinal, apeterson]
 files: []
 related:
   - ../apps/toga25-supply/architecture.md
@@ -352,6 +352,13 @@ memory.
   Supply dedupes the table lib (it consumes blox's table context); desk dedupes react-hook-form (it
   consumes blox's `BaseInput`, which reads `useFormContext()`). See §13(c) for why a second copy
   silently breaks blox's hooks.
+
+  Verified 2026-08-26: `toga2-commerce` had **no** `dedupe` at all and now declares
+  `["react","react-dom","react-hook-form","react-router-dom","framer-motion","@tanstack/react-query","@tanstack/react-table"]`
+  (working-tree on branch `TRUE-80707`, not yet merged). The concrete hazard: `toga-blox-npm/node_modules/`
+  ships its own `react@18.3.1`/`react-dom@18.3.1`, so consuming blox through a **local symlink**
+  resolves React to blox's own copy. Dedupe is what makes the symlink workflow safe — it is not
+  optional polish.
 - **MUST: one env-read chokepoint.** Read `VITE_API` in exactly **one** module (see §17). Verified:
   both apps read it (plus a per-host override) only in `src/api/api.ts`.
 - **SHOULD: ESLint flat config**, verified identical in both apps:
@@ -412,12 +419,18 @@ on the back end. A consuming app **MUST** meet every requirement below.
 **(a) Pin an exact published version — never a caret.** Some published versions ship an **empty
 `dist`** and break the build; a caret can float you onto one. Both apps pin exact versions
 (verified 2026-08-18: supply `1.0.330-sandbox-client.128`, desk `1.0.328-sandbox-client.125`).
+Verified 2026-08-26: `toga2-commerce` violates this with `"^1.0.322-sandbox-client.117"`. Also audit
+for **pin drift** between branches (commerce's `TRUE-80707` was 11 versions behind `_sandbox-client`).
 
 **(b) Declare blox's peer deps that do not hoist into your app.** blox lists them as peers, so npm
 will not necessarily install them for you: verified 2026-08-18 they include `react-hook-form`,
-`@tanstack/react-query`, `@tanstack/react-table`, `framer-motion`, `react-router-dom`, and `axios`
-(pinned exactly by blox at `1.8.4`). A missing peer surfaces as a runtime "undefined is not a
-component," not a build error.
+`@tanstack/react-query`, `@tanstack/react-table`, `framer-motion`, and `axios` (pinned exactly by
+blox at `1.8.4`). **`react-router-dom` was removed as a peer on 2026-08-26** — it was phantom (its
+only production reference was a dead `Link` import in `old/BaseButton`); *(change staged on blox
+`feature-new-table`, not yet merged/published — verify against the installed version before relying
+on it)*. A missing peer surfaces as a runtime "undefined is not a component," **or**, because a
+**barrel import pulls blox's whole index**, as a Rollup `failed to resolve import` for a component
+you never referenced.
 
 **(c) Dedupe `react` / `react-dom` (+ `react-hook-form` / `@tanstack/react-table`) to a single
 copy.** blox is shipped **unbundled** — its `build` is `tsc && copyfiles … && fix-esm-imports`
@@ -575,7 +588,11 @@ Work **around** these shared-lib defects; do **not** imitate them in app code:
 - **Two select stacks** coexist (`react-select` + a custom `AdvancedSelect`) and **two table
   stacks** (`react-table` v7 + `@tanstack/react-table` v8) — verified 2026-08-18 in blox's peer
   deps. Know which one a given component uses before you wire it.
-- Phantom/unused peer deps in blox's manifest.
+- **Phantom/unused peer deps in blox's manifest** — confirmed and one now removed:
+  `react-router-dom` (dead `Link` import in `old/BaseButton`; removal staged 2026-08-26 on
+  `feature-new-table`, not yet merged/published — it stays a devDependency for the tests'
+  `MemoryRouter`). Verify a declared peer is actually reachable in `src/` before adding it to your
+  app or reaching for `--legacy-peer-deps`.
 - Supply/commerce business logic has leaked into the shared lib.
 - **No custom-validator passthrough on `BaseInput`** — hence the app-side validator layer in §7.
 - A **~85-prop className-string styling contract on `BaseInput`** — verbose by design; drive it from
@@ -624,6 +641,11 @@ app work.** In a consuming app, guard against them and move on.
 
 ## Change history
 
+- 2026-08-26 — Recorded commerce's missing `resolve.dedupe` (+ the blox-symlink second-React
+  hazard), its caret blox pin and cross-branch pin drift, the barrel-import missing-peer trigger,
+  and the removal of blox's phantom `react-router-dom` peer. All the underlying code changes are
+  working-tree only (blox `feature-new-table`, commerce `TRUE-80707`) — unmerged and unpublished.
+  (apeterson)
 - 2026-08-18 — Initial front-end (React) coding standard: universal React/TS layer + TOGA 2.0
   platform-conventions layer, mined from @agilant/toga-blox, toga25-supply, and toga25-desk; per-rule
   convergence tagging; testing/a11y/error-reporting/React-19 flagged as open. (jcardinal)

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 67 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 56 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 57 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)_ — 9 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
@@ -31,7 +31,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) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 12 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
-- **toga-blox** (TOGa Blox) — 10 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
+- **toga-blox** (TOGa Blox) — 11 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/standalone/apps/claude/workflows/mcp-tool-usage.md

@@ -6,8 +6,8 @@ project: Claude Harness
 client: shared
 type: workflow
 status: active
-updated: 2026-08-06
-owners: ["jcardinal", "tcox"]
+updated: 2026-08-26
+owners: ["jcardinal", "tcox", "ajean"]
 files:
   - claude/.claude/skills/kickoff/SKILL.md
   - claude/.claude/skills/capture/SKILL.md
@@ -138,6 +138,18 @@ data is missing. Query **`dev-sandbox`** whenever someone says "beta". Any front
 onboarding SQL shows beta on a us-west-2 `client-cluster`; that has since been consolidated —
 trust `Core.DatabaseHosts`, not old migrations.)
 
+**⚠ The write-blocker is a naive string scan — it rejects `UPDATE`/`REPLACE` even inside a string
+literal.** `toga_query` refuses the whole statement if those words appear anywhere in it, so a
+perfectly read-only query like
+`… WHERE output LIKE '%skipped update%'` fails validation. Work around it by matching on a fragment
+that avoids the keyword (`LIKE '%skipped%'`), or by pulling the rows and filtering client-side —
+don't conclude the data isn't there.
+
+**Production sessions render in US/Central (UTC−5); most other timestamps you're comparing are
+UTC.** GitHub/API/webhook timestamps are UTC, so a naive `dtStamp` vs. commit-time comparison is off
+by five hours — enough to make a healthy worker fleet look dead. Anchor both sides to UTC (or
+`CONVERT_TZ`) before drawing a conclusion about "when did this last run".
+
 **`local` is not this MCP.** If someone means their own machine's database, use the `mysql` CLI
 via shell, not `toga-db`.
 
@@ -183,5 +195,10 @@ Schema names are **case-sensitive** — copy the exact value from `toga_list_sch
   and why. Database → what is actually true right now.
 
 ## Change history
+- 2026-08-26 — Added two `toga-db` query traps: the write-blocker is a **naive string scan** that
+  rejects any statement containing `UPDATE`/`REPLACE` **even inside a string literal** (so
+  `LIKE '%skipped update%'` fails validation on a read-only SELECT), and **production DB sessions
+  render in US/Central (UTC−5)** while GitHub/API/webhook timestamps are UTC — the mismatch made a
+  healthy worker fleet look dead. (ajean)
 - 2026-08-06 — Recorded that **"beta" resolves to the `dev-sandbox` cluster** for client databases (`Core.DatabaseHosts` env `beta` → the sandbox-dev host) while the MCP's `client-beta` environment exposes no schemas — query `dev-sandbox` when someone says beta. Cost real debugging time while onboarding Elite to the supply2 frontend (tcox)
 - 2026-07-30 — Created. Established that "ask/use Talos" means the Internal Knowledge Base MCP and not the `talos` repo; that Claude runs its own SELECTs unprompted while developers execute writes; and that both MCP connections are used proactively without being requested. Recorded the KB↔registry client-name divergence and the `Core.Clients` identifier traps (jcardinal)

package/package.json

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