toga-ai 1.0.909 → 1.0.911

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: ["dfranks", "jcardinal", "kyalamarthi", "ajean"]
+updated: 2026-09-28
+owners: ["dfranks", "jcardinal", "kyalamarthi", "ajean", "rgirish"]
 files:
   - library/app/api/netsuite/rest.php
   - library/ssl/netsuite_ec_key.pem
@@ -110,7 +110,9 @@ Status codes (`transaction.status` letter):
 
 Header columns present (✓ confirmed in SuiteQL): `id`, `tranid`, `trandate`, `lastmodifieddate`, `type`, `status`, `entity`, `employee`, `leadsource`, `terms`, `memo`, `otherrefnum`, `foreigntotal`/`total` (both return the same value), `foreignamountunpaid` (AR balance — invoices only; NULL for SO/credit memo/cash sale), `duedate`, `shipmethod`, `opportunity`, `shippingaddress` (numeric id → join `transactionShippingAddress`), and custom fields (`CUSTBODY_END_CUSTOMER`, `CUSTBODY_STOCKING_ORDER`, …).
 
-Header fields NOT in SuiteQL (✗ — require a per-id REST GET): `shippingCost`, `taxTotal`, `subTotal`, `createdFrom` (also derivable from `previousTransactionLineLink`, but non-deterministically — see shim doc), `trackingNumbers`, `linkedTrackingNumbers`, and the **structured** `shippingAddress` object (SuiteQL gives only the id).
+Header fields NOT in SuiteQL (✗ — require a per-id REST GET): `shippingCost`, `taxTotal`, `subTotal`, `createdFrom` (also derivable from `previousTransactionLineLink`, but non-deterministically — see shim doc), and the **structured** `shippingAddress` object (SuiteQL gives only the id).
+
+Tracking numbers in SuiteQL (verified 2026-09-28): `transaction.trackingnumberlist` (on the IF) / `linkedtrackingnumberlist` (on the SO) return **`trackingnumber` record ids**, not the numbers — resolve with `SELECT id, trackingnumber FROM trackingnumber WHERE id IN (...)`. `trackingnumbermap` returned nothing. The REST per-id GET below also has them.
 
 ### `transactionline` table
 

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-23
+updated: 2026-09-28
 owners: [bala, kyalamarthi, apeterson, ajean, jcardinal, rgirish]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -182,6 +182,8 @@ the item-fulfillment bridges, which sit side by side and do **not** agree:
 | `ItemFulfillmentItems_TrackingNumbers` | yes — `(itemFulfillmentItemId, trackingNumberId)` |
 | `ItemFulfillmentItemUnits_TrackingNumbers` | yes — `(itemFulfillmentItemUnitId, trackingNumberId)` |
 | `ItemFulfillmentItemUnits` | **no** — and it already holds **254** duplicate `(itemFulfillmentItemId, unitId)` rows as a result |
+| `Users_Personas` | yes — `(userId, personaId)` (`userId_personaId_UNIQUE`, `Client/2026-09-22-BLANK_CLIENT_DATABASE.sql:11410`) |
+| `Users_Roles` | yes — `(userId, roleId)` |
 
 The last row is the whole point: the table with no unique key had already accumulated duplicates
 that nobody noticed, because nothing ever errored.
@@ -198,6 +200,13 @@ WHERE
 	ur.id IS NULL;
 ```
 
+**Not every table has a `dtCreated` to set.** The "always write `dtCreated = NOW()`" rule below
+applies only where the column exists. The user bridges do **not** have one —
+`_Model_Client_Users_Persona` (`_underscore/Model/Client/Users/Persona.php`) declares exactly
+`(id, uuid, userId, personaId)`, and `Users_Roles` is the same shape — so a hand-written INSERT names
+only the uuid and the two ids. Read the model (or the blank-client schema) before adding a timestamp
+column that does not exist.
+
 **A guarded insert that inserts zero rows is a success, not a wasted file** — see
 [Client-DB grant migrations are re-runnable NO-OPs](../../_underscore/features/acl-permission-chain.md).
 
@@ -505,6 +514,7 @@ an INSERT that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`inde
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-28 — `Users_Personas` / `Users_Roles` added to the composite-unique table (both unique on the id pair, so a guarded re-run is a clean no-op), plus the counterpoint to the dtCreated rule: these user bridges have no timestamp column at all. (apeterson)
 - 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

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

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-09-21
+updated: 2026-09-28
 owners: [apeterson, tcox, bala]
 files:
   - toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts
@@ -85,10 +85,10 @@ Per-column header controls, each a popover trigger with `data-active` / `data-op
 
 - **`HeaderFilterSearch`** — text filter, **multi-chip with per-chip mode**. Each confirmed search becomes its own `TextFilterTag = { value, mode }` (mode ∈ Includes / Starts with / Ends with / Exactly / Excludes). The mode dropdown sets the mode for the **next** chip added; existing chips keep the mode they were created with. All chips on a column are combined with **AND**. `onFilterChange` emits the full tags array (`{ tags }`); the component rehydrates every chip from props and renders each as "Mode: value". `isActive = tags.length > 0`. The mode dropdown is portalled to `document.body` with fixed positioning recomputed on scroll. The search icon (solid when active, regular otherwise) is hidden while the input is focused; both the trigger button and the icon span carry `data-active`. The clear button must not widen the input row (fixed-width menu). (Previously a column allowed only one term / one mode — a second search replaced the first and switching mode re-applied it to everything.)
 - **`HeaderFilterRange`** — numeric, modes exactly/moreThan/lessThan + a range toggle (min/max); emits `{ key, value }[]` (`eq`/`min`/`max`/`between`). Reads its persisted operator/values back from a `filterParams` prop (not `filterValue`, which collapses to the literal `"active"` when a range filter is set); `PrimaryTableHeaderCell` must pass `filterParams` through.
-- **`HeaderFilterMultiselect`** — checkbox list with "Select All"; emits comma-joined slugs.
+- **`HeaderFilterMultiselect`** — checkbox list with "Select All"; emits comma-joined slugs. **Its "Clear" must call the `onClear` prop, not just reset local state** — see the clear-contract gotcha below.
 - **`HeaderFilterDate`** — calendar picker, modes exactly/before/after + range; converts `MM/DD/YYYY` ↔ URL `YYYY-MM-DD`; calendar + mode dropdown both portalled.
 - **`HeaderFilterButton`** — generic trigger: shows a numbered badge when active with a `filterIndex`, otherwise the search icon (`data-active`).
-- **`SortIcon`** — asc/desc/reset menu with a multi-sort index badge; button visibility keys off current sort direction.
+- **`SortIcon`** — asc/desc/reset menu with a multi-sort index badge; button visibility keys off current sort direction. The badge **points down for `desc`** via a `.sortDropdownBadgeDesc` modifier that rotates the whole badge 180deg, with a nested rule counter-rotating `.sortDropdownBadgeIndex` so the sort-position digit still reads upright. **Rotate, never swap the icon** — FontAwesome Pro has no down-pointing `triangle`, and `caret`/`sort` have a different silhouette, so a swap changes the designed shape. The offset is held in one CSS variable both rules read (`--sortDropdownBadgeIndex-offset`) so retuning the base offset cannot drift the rotated copy. These rotations are deliberately **not** host tokens: a 180deg flip is geometry, not brand — same treatment as the un-tokenized `translateX(-50%)` centering on `.sortDropdownMenu` (a CSS comment records this so it is not "fixed" later). (Before 2026-09-28 the badge always rendered the solid `triangle` and ignored `isSorted`, so asc and desc looked identical.)
 
 ### Hooks (`hooks/`)
 
@@ -118,6 +118,10 @@ This exists because an unscoped `GET /{recordRoute}` returns *every* row of a lo
 
 ## Gotchas
 
+- **A filter popover's "Clear" must call `onClear()` — resetting local state only leaves the table filtered.** `HeaderFilterMultiselect.handleClear` did just `setSelectedOptions([])`, so the URL param (owned by the consuming app) and the applied filter survived: the popover showed nothing selected while the table stayed filtered. Fixed 2026-09-28 — it now calls `onClear()` and closes, **guarded by `if (filterValue)`**. The guard matters: `onClear` routes through `PrimaryTableHeaderCell` → `table.options.onColumnFiltersChange` → toga25-supply `useServerTableUrlState`, which resets to **page 1 on any filter change** — so an unguarded Clear with nothing applied would bounce the user off their page.
+- **⚠ OPEN — `HeaderFilterRange.handleClear` has the same bug** (~line 162): it resets `singleValue`/`minValue`/`maxValue` but never calls `onClear()` and never closes the popover. Same fix shape as the multi-select. Not fixed as of 2026-09-28.
+- **⚠ OPEN — `SortIcon` has no `aria-*` at all.** Sort direction and position are conveyed by shape only — no `aria-label`, no `aria-sort`. Pre-existing; needs its own ticket.
+- **A unit test cannot prove a CSS change — verify in blox's own Storybook.** JSDOM applies no real layout, so a Vitest test can only assert the modifier class is present; it can never show the triangle actually flipped or that the digit stayed upright. Add a co-located `*.stories.tsx` rendering the states side by side, run `npm run blox` (port 6006), and look at it.
 - **⚠ OPEN — the multi-select filter matches by SUBSTRING, not exactly.** `HeaderFilterMultiselect` comma-joins the picked slugs and `src/api/tableData/getDataTableData.ts` turns that into `where: { or: [ { field: { contains: value } }, … ] }`. Picking "Jon Smith" also matches "Jon Smithson" — it over-includes rows.
 - **⚠ OPEN — an option value containing a comma silently returns zero rows.** It splits into two bogus filter terms, with no error. Both bugs are pre-existing and affect **every** multi-select column including Order Status; both fix in one place — send a list / exact-equals operator instead of a comma-joined `contains`. Not fixed as of 2026-09-15.
 - **⚠ `useTableData` APPENDS `.uuid` to `additionalData.slug` — unless the slug is on a hardcoded allow-list.** The list is exactly `catalogId`, `customerId`, `Items.catalogId`, `SalesOrderItems.uuid`, `SalesOrders.uuid` (verified in `@agilant/toga-blox` **1.1.2-production.144**, the version toga25-supply pins). Consequences for anyone writing a filter slug into config or a `TableLevel` callback:
@@ -139,6 +143,9 @@ This exists because an unscoped `GET /{recordRoute}` returns *every* row of a lo
 - **Filter presentational components must seed their internal state from props.** Filter state survives the URL round-trip and is rehydrated into TanStack `columnFilters` by toga25-supply `useServerTableUrlState`, carried through `PrimaryTableHeaderCell`. But `HeaderFilterSearch`/`HeaderFilterRange` are remounted fresh each time a popover opens, so they must seed local state from props or reopening *shows the wrong state*. **Text (`HeaderFilterSearch`)** now persists as a single readable URL param `<slug>_<col>_filter` = comma-separated `mode:value` pairs (values URL-encoded so `:`/`,` inside a term can't corrupt the delimiters); `getDataTableData` parses it and pushes **one AND WHERE condition per chip** (mode→op: includes→contains, startsWith→starts, endsWith→ends, exactly→eq, excludes→excludes). The component rehydrates the full `tags` array from props. Old base64/legacy single-mode `_starts`/`_ends`/… URLs don't parse under the new scheme (graceful — just re-apply the filter). The browser may percent-encode `:`/`,` in the address bar but it round-trips. **Range (`HeaderFilterRange`)** still persists as key suffixes (`_min`/`_max`/`_eq`/`_between`); it reads mode + value(s) back from `filterParams` via a rehydration effect keyed on `JSON.stringify(filterParams)` (`eq`→Exactly, `min`→MoreThan, `max`→LessThan, `between`→range min/max).
 - **Table/surface meta is cached with `Infinity` staleTime/gcTime** (`useFetchTablePageMeta`), so after a DB metadata change (`TableViewFields`, `Core.RecordFields`) a **hard reload** is required to see it. And the app consumes toga-blox's built **`dist/`**, not `src/` — editing blox source requires `npm run build` before it takes effect at runtime.
 
+## Change history
+- 2026-09-28 — multi-select filter "Clear" now actually clears (calls `onClear`, page-1 guard); sort badge now points down for `desc` via CSS rotation (apeterson)
+
 ## Related
 
 - [Primary Table templates](primary-table-templates.md) — the wired table built on this.

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

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-09-21
+updated: 2026-09-28
 owners: [jcardinal, apeterson, tcox, rgirish]
 files:
   - toga-blox/.github/workflows/publish.yml
@@ -110,6 +110,9 @@ Dates: the **August 2026** npm change removed 2FA-bypass for *account and packag
   If any one fails, bump on the feature branch instead. Note the bump commit lands *only* on `_sandbox-client` and is never merged back, which is precisely what generates the "N behind" release plumbing.
 - **`gh` is not installed on every dev machine.** The skill's `gh run watch` monitoring step simply does not work there. Fall back to polling the registry: `npm view @agilant/toga-blox@sandbox-client version` (or `npm dist-tag ls @agilant/toga-blox`) until the new version appears — the registry is the authoritative confirmation anyway.
 - **A publish is only half the deploy — and the consumer must depend on the LITERAL dist-tag.** In `toga25-supply/package.json` the dependency is the bare tag string (`"@agilant/toga-blox": "sandbox-client"`), **not** a version range. `npm install @agilant/toga-blox@sandbox-client` rewrites it to a `^` range, which then stops following base bumps — re-set the literal tag, re-run `npm install`, commit `package-lock.json`. Verify what is installed with `node -p "require('./node_modules/@agilant/toga-blox/package.json').version"`. Exact pins drift: branch `TRUE-81379` was pinned to `1.1.3-production.166` while `node_modules` held `1.1.10-sandbox-client.163` — check this first when a fix "works locally but not after deploy". Likewise the feature branch keeps its old base version after a bump lands on `_sandbox-client`; that is expected.
+- **⚠ A CARET on a prerelease pin can NEVER upgrade — it reads as "my fix did not deploy", not as drift.** npm matches `^` on a prerelease only inside the **same** `major.minor.patch`, so `toga25-supply` `_sandbox-client` pinned at `"^1.1.4-sandbox-client.188"` could not pick up `1.1.10-sandbox-client.191` — the bump had to be explicit. This is the concrete failure mode behind the literal-tag rule above: silent never-upgrade, not slow drift. Confirmed 2026-09-28.
+- **`toga25-supply` `_sandbox-client` has NO `amplify.yml`** — it builds from the Amplify **console** build spec. If that spec runs `npm install "@agilant/toga-blox@$MODE"`, the deployed build takes the **channel head** and the `package.json` pin governs local dev only. Check the console spec before chasing a "stale deploy".
+- **Confirm a bump landed by grepping the INSTALLED `dist/`, not by trusting the install.** e.g. `grep -n "sortDropdownBadgeDesc" node_modules/@agilant/toga-blox/dist/components/Table/components/columnFiltersAndSorts/SortIcon.js`. Same technique proves a published channel actually carries a fix (2026-09-28: verified a bug was live in `1.1.4-production.184`'s dist, not just in src).
 - **⚠ Credentials have been found in the local git remote URL.** Verified 2026-08-26: the `origin` remote for the `toga-blox-npm` checkout had a **GitHub PAT embedded in plaintext in the URL** (visible to anything that runs `git remote get-url origin`, and to any tool that reads `.git/config`). Check for this and re-point the remote at SSH or a credential helper; treat any token found this way as compromised and rotate it. This is the local-config sibling of the committed-`.npmrc` violation already recorded in `../../../standards/frontend.md`.
 - **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 signature that plain `React.CSSProperties` lacks. Cast the passed style to `React.CSSProperties & Record<\`--${string}\`, string>` — the value type must be `string` (**not** `string | number`; `CSSVariables` requires `string`). Runtime and function signature are unchanged, so it is safe for the ~40 consumers.
 - **The `_production`/`_beta` build copies only `.scss` — a plain `.css` component stylesheet is silently dropped from the tarball.** On `_production` and `_beta` the `build` script is `tsc && copyfiles -u 1 "src/**/*.scss" dist`: `tsc` compiles a component's `import "./Foo.css"` into the emitted JS, but `copyfiles` never ships the `.css`, so the published package contains JS importing a file that isn't in the tarball. Consumers then fail their Vite/Rollup build with `Could not resolve "./Foo.css"` (seen with `EnvironmentBadge` in `@agilant/toga-blox@beta` 1.0.316-beta.108, breaking `toga2-commerce`). **Convention on the prod/beta build: author component stylesheets as `.scss`, never `.css`** (a flat `.css` file is valid SCSS as-is, so renaming is the zero-risk fix — no build-script change). Note the build description in `architecture.md` (copies `*.scss/*.css/*.module.css`) reflects the in-progress `feature-new-table` branch, **not** the current `_production`/`_beta` build; that feature branch is not to be merged to prod/beta just to pick up the wider copy glob.
@@ -120,6 +123,9 @@ Dates: the **August 2026** npm change removed 2FA-bypass for *account and packag
 - **Keep the production base ahead of, or level with, sandbox.** `_production`'s base had drifted **12 patches behind** `_sandbox-client`, so the production channel was publishing *numerically lower* versions than sandbox. The base was bumped `1.0.322` → **1.1.0** to mark the `feature-new-table` release and stop that inversion; CI published `1.1.1-production.139`.
 - **Pushing to a `_*` branch IS the publish — there is no separate step to run afterwards.** The merge push itself triggered a publish (`1.0.323-production.137`) about a minute after the merge landed. Consequence: a merge that is not release-ready still ships. Get the tree right *before* you push to a release branch.
 
+## Change history
+- 2026-09-28 — recorded the caret-on-prerelease never-upgrade trap, toga25-supply's missing `amplify.yml`, and dist-grep verification (apeterson)
+
 ## Related
 
 - [Landing a large feature branch](./landing-a-large-feature-branch.md) — the merge procedure that feeds a release branch.

package/knowledge/2.0/standards/secrets-and-build-credentials.md

@@ -0,0 +1,73 @@
+---
+title: Where Secrets Live (AWS Secrets Manager, Build Credentials)
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-09-28
+owners: [jcardinal]
+related:
+  - frontend-deploy.md
+  - ../apps/_underscore/features/cloud-secrets-manager.md
+  - ../apps/api2/architecture.md
+  - ../apps/toga25-blox/architecture.md
+---
+
+Every secret a machine (build, CI, app) reads lives in one place, AWS Secrets Manager in the production account; open before adding, reading, or rotating any credential.
+
+## Rule
+
+- One place: AWS Secrets Manager, **production account `654654170868`, `us-east-1`**. No secret values in config files, `.env`, source, CI YAML, or committed anywhere.
+- Secrets are **JSON**. Value key is `token` (or named keys when a secret holds several related values).
+- Never write a secret's actual value into a knowledge doc, commit, log, URL, or chat — location and name only.
+
+## Naming
+
+- Folder-style prefix by **who reads it**: `build/` = anything a build/CI job may read (Amplify, GitHub Actions).
+- Other existing prefixes: `toga/ssl/*` (SAML SP certs), `talos/<env>/*`, `sftp/<client>/*`.
+- Current `build/` secrets:
+  - `build/github-read` — fine-grained GitHub token on the shared deployment user `agilantgit`, resource owner org `agilantsolutions`, Contents read-only on `toga25-blox` / `toga25-desk` / `toga25-iq` / `toga2-template`, 1-year expiry — renew before it expires.
+  - `build/fontawesome` — FontAwesome Pro package token.
+
+## Env var name for local dev / CI
+
+Upper-case the secret name, `/` → `_`, append `_<KEY>` upper-cased.
+
+- `build/fontawesome` + key `token` → `BUILD_FONTAWESOME_TOKEN`. Read by the app's `.npmrc`. Each developer sets it once: `setx BUILD_FONTAWESOME_TOKEN "<token>"`, then open a new terminal.
+- `build/github-read` → `BUILD_GITHUB_READ_TOKEN`.
+
+## Cross-account access (prod-stored, non-prod reader)
+
+Secret is encrypted with KMS key `alias/toga-secrets` (key policy lets non-prod account `975050298201` decrypt only via Secrets Manager) plus a resource policy on the secret naming the reader roles. Readers must use the **full ARN**: `arn:aws:secretsmanager:us-east-1:654654170868:secret:<name>`. Same pattern as `toga/ssl/*` (read by non-prod `aws-elasticbeanstalk-ec2-role`).
+
+### Build readers today (non-prod `975050298201`)
+
+- `amplify-platform-build` — Amplify service role; inline policy `platform-build-secrets-read` grants `secretsmanager:GetSecretValue` on prod `secret:build/*` + `kms:Decrypt` on `toga-secrets` via Secrets Manager. Attached to Amplify app `toga25-desk` (`d311sdoq12ddne`).
+- `github-actions-toga25-blox` — GitHub OIDC provider (`token.actions.githubusercontent.com`), scoped to repo `agilantsolutions/toga25-blox` only, same policy shape. Used by `.github/workflows/apps-build.yml`.
+- **Open item:** production Amplify builds need their own `amplify-platform-build` role in the **prod** account (same-account read — no cross-account sharing needed there).
+
+## Adding a secret / a reader
+
+- **New build secret:** create under `build/`, encrypt with `alias/toga-secrets`, add the same resource policy (the two non-prod roles above). No IAM change needed — both roles already allow `build/*`.
+- **New non-prod reader role:** add its ARN to each shared secret's resource policy.
+
+## Rotation
+
+- Rotate at the source (GitHub, FontAwesome, etc.), update the value in Secrets Manager. Builds pick it up next run; developers update their local env var.
+- **Open item:** old FontAwesome + npmjs tokens are committed in `toga25-desk` / `toga25-iq` / `toga2-template` git history — rotate once every app reads `build/fontawesome`. Legacy apps `toga25-supply` / `toga2-commerce` still use the current (unrotated) token, so rotating now would break them first.
+- Any credential that has ever been committed must be treated as compromised and rotated — deleting the line does not remove it from history. See [worker2 committed secrets debt register](../apps/worker2/features/committed-secrets-and-config-debt.md) and [api2 architecture Security note](../apps/api2/architecture.md#security-note-committed-secrets) for the existing backlog this standard is meant to stop growing.
+
+## Never
+
+- Commit a token.
+- Put a token in a URL, log, or chat.
+- Give a build role access to all secrets — a build runs hundreds of npm packages; scope to `build/*` or narrower.
+
+## Related
+
+- [2.0 Frontend Deployment (Vite + AWS Amplify)](frontend-deploy.md)
+- [_Cloud Secrets Manager helper](../apps/_underscore/features/cloud-secrets-manager.md) — the app-side (PHP) reader; this standard covers the AWS-side layout and build/CI readers
+- [API (api2) Architecture — Security note](../apps/api2/architecture.md#security-note-committed-secrets)
+- [toga25-blox Architecture](../apps/toga25-blox/architecture.md)
+</content>

package/knowledge/INDEX.md

@@ -22,7 +22,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **_underscore** (_Underscore) _(framework core)_ — 90 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 80 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 21 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 22 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)
 - **saml** (SAML SSO Gateway) — 9 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **apiproxy** (API Proxy) — 1 doc(s) → [2.0/apps/apiproxy/INDEX.md](2.0/apps/apiproxy/INDEX.md)

package/knowledge/clients/adyen/INDEX.md

@@ -2,4 +2,4 @@
 
 | Doc | Framework | Summary |
 |-----|-----------|---------|
-| [Adyen](profile.md) | 2.0 | Adyen live TOGa Supply client (`Client_Adyen`) on the 1.0 NetSuite→TOGa Supply sync, status draft; open for the `isFulfillable` prod/beta column gap, the beta=c |
+| [Adyen](profile.md) | 2.0 | Adyen live TOGa Supply client (`Client_Adyen`) on the 1.0 NetSuite→TOGa Supply sync, status draft; open for the prod tracking-API test orders + SR↔NetSuite matc |

package/knowledge/clients/adyen/profile.md

@@ -11,21 +11,27 @@ project: Worker
 client: adyen
 type: profile
 status: draft
-updated: 2026-09-16
+updated: 2026-09-28
 owners: ["rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_adyen.php
   - library/app/api/toga2.php
   - _underscore/Model/Client/Item.php
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - _underscore/Trait/Netsuite/ItemFulfillment.php
+  - dbchanges2/Client_Adyen/2026-09-22a - AdyenApiTestSeed.sql
+  - dbchanges2/Client_Adyen/2026-09-28a - LinkTestOrdersToNetsuite.sql
+  - dbchanges2/Client_Adyen/2026-09-28b - RemoveUnmatchedTestOrders.sql
 related:
   - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../1.0/apps/library/features/netsuite-suiteql-api-reference.md
   - ../growrk/features/transfer-order-flow.md
   - ../../2.0/apps/_underscore/features/acl-permission-chain.md
   - ../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md
   - ../../2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md
 ---
 
-Adyen live TOGa Supply client (`Client_Adyen`) on the 1.0 NetSuite→TOGa Supply sync, status draft; open for the `isFulfillable` prod/beta column gap, the beta=client-sandbox env trap, and the ACL findings.
+Adyen live TOGa Supply client (`Client_Adyen`) on the 1.0 NetSuite→TOGa Supply sync, status draft; open for the prod tracking-API test orders + SR↔NetSuite matching, the `isFulfillable` column gap, the beta=client-sandbox env trap, and the ACL findings.
 
 ## Summary
 
@@ -36,6 +42,7 @@ Adyen live TOGa Supply client (`Client_Adyen`) on the 1.0 NetSuite→TOGa Supply
 
 - **NetSuite → TOGa Supply sync.** Per-client thin wrapper over the shared engine — full mechanics on [per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 - **Transfer orders ENABLED** (`IS_ENABLED_INTEGRATION_TRANSFER_ORDERS = true`). Adyen's NetSuite transfer orders arrive **as NetSuite sales orders**, classified by `TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` — `holdInvoice === true` **AND** `total === 0`, same rule as GroWrk (see [GroWrk transfer order flow](../growrk/features/transfer-order-flow.md)). Mode is now declared explicitly in Adyen's launcher; `App_Api_Toga2::isTransferOrder()` throws if it is missing, so **`library` and `worker` must deploy together** for Adyen.
+- **IDs:** `Core.Clients` id **48**; NetSuite customer **31054** ("4950 Adyen").
 - **`Client_Adyen`** is one of the client DBs with surface-layer / ACL drift noted on the [ACL permission chain](../../2.0/apps/_underscore/features/acl-permission-chain.md) and [surface-layer schema](../../2.0/apps/dbchanges2/features/surface-layer-schema.md) docs.
 
 ## Gotchas
@@ -48,6 +55,32 @@ Adyen live TOGa Supply client (`Client_Adyen`) on the 1.0 NetSuite→TOGa Supply
 - **⚠ Adyen's working beta calls hit `client-sandbox`, NOT `dev-sandbox`.** Calls go to `api.beta.togahub.com` with a JWT carrying `"env":"beta"`, which maps to the MCP environment **`client-sandbox`**. `Core.Domains` in client-sandbox shows `api.beta.togahub.com` with `env = 'beta'` and **`clientId = NULL`** — a shared API domain, so the tenant comes from the **JWT's client uuid**, not the hostname.
 - Comparing **dev-sandbox against prod** compares two environments the developer is not using — it produced **three consecutive wrong answers** in the 2026-09-08 session. Decode the token's `env` + `id.client.uuid` before any environment diff — recipe in [non-prod metadata drift, step 1](../../2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md#steps).
 
+### Prod tracking-API test orders — linked to real NetSuite (2026-09-28)
+
+Adyen tests the tracking API on **prod**. `2026-09-22a - AdyenApiTestSeed.sql` seeded dummy SalesOrders / ItemFulfillments / TrackingNumbers (fake `1ZADYEN…` numbers). Before the NetSuite sync runs they had to become real, or the sync would create **duplicate SOs**.
+
+- **`2026-09-28a - LinkTestOrdersToNetsuite.sql` (RAN on prod):** sets `SalesOrders.c_netsuiteInternalSalesOrderId` + `number` = NS `tranid` + `dateOrder`; `ItemFulfillments.c_netsuiteInternalItemFulfillmentId` + `number` + `dateItemFulfillment`; swaps fake tracking for real FedEx numbers, status `PENDING`. Verified: 22 SOs linked, 21 IFs + 42 tracking numbers real.
+- **`2026-09-28b - RemoveUnmatchedTestOrders.sql` (RAN on prod):** deletes the dummy SO/PO/IF chain for SOs with no NS match. ServiceRequests kept.
+- **Why this prevents duplicates:** the sync matches existing rows by `c_netsuiteInternalSalesOrderId` / `c_netsuiteInternalItemFulfillmentId` (`_underscore/Trait/Netsuite/SalesOrder.php`, `ItemFulfillment.php`). It will replace the dummy `SalesOrderItems` (itemId 6).
+- **⚠ Leftovers:** dummy POs `PO-SR%` and vendor `V-TEST-001` still exist for the linked SOs.
+
+**⚠ The Adyen NetSuite sync has never run.** `Parameters` cursors stuck at `2026-08-20 00:00:00|0`, the `Customers` row has no `c_netsuiteInternalCustomerId`, no `Locations`. Set these up before expecting sync data.
+
+**How to match an Adyen SR to its NetSuite SO — there is NO shared key.**
+
+- Adyen's reference number is `ServiceRequests.c_externalReferenceId` (e.g. 48753831); `SalesOrders.serviceRequestId` → `ServiceRequests.id`. NetSuite does not store it.
+- Match SR contact name + ship-to address against NS SO `otherrefnum` (holds the employee name) / shipping attention + addr1.
+- NS Adyen reclaim SOs: memo "Employee Leaving" / "Contractor Leaving", item `SVC-FS-OFFBOARD-ADN`, one IF each with **2 FedEx packages**. First number (87x/875/876) = outbound, 792x = return label — **this outbound/return split is an assumption, not confirmed.**
+- NS tracking-number lookup in SuiteQL: see [SuiteQL reference → `transaction` table](../../1.0/apps/library/features/netsuite-suiteql-api-reference.md).
+
+**Known data gaps (2026-09-28):**
+
+1. SR100024 duplicates SR100021 (same Adyen ref 48748808) — a lookup by that ref returns **2 SRs**.
+2. SR100026 → NS SO 290879, not fulfilled yet.
+3. SR100027–30 have no NS SO.
+4. NS SO 288261 has no SR in Toga.
+5. SR100000/01/02/25 are Adyen test SRs with no NS order.
+
 ### Open defect — `Client_Adyen.Items` missing `isFulfillable` (prod AND beta)
 
 - Root cause of the 2026-09-08 "works in sandbox, not in production" report; **NOT an ACL problem**. Adyen is the **only** tenant missing the column.
@@ -91,3 +124,4 @@ The `AclRecordPermissions` prod-vs-dev-sandbox route-name diff from that session
 - Formal/legal client name and account owner — recorded here simply as **Adyen**.
 - Which repos beyond the `apps:` list are genuinely in Adyen's scope.
 - Whether Adyen has client-specific models/features that deserve their own docs.
+- Confirm with Adyen/ops: which FedEx package is outbound vs return; whether SR100024 should be closed; who sets up the NetSuite sync (customer id, Locations, cursors).

package/knowledge/clients/quad/INDEX.md

@@ -7,4 +7,5 @@
 | [Quad: PO + ASN email importer (import_po_and_asn.php)](features/po-asn-email-import.md) | 1.0 | Quad's inbox-driven PO/ASN CSV importer and its 2026-08 failure classes; open when a Quad PO/ASN email jams the mailbox, fails EV-12, or you touch `import_po_an |
 | [Quad Graphics](profile.md) | 2.0 | Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`. |
 | [Quad Graphics — reversing the 30-item catalog fold (storefront-assortment recovery)](workflows/catalog-fold-reversal.md) | 2.0 | How the 2026-08-31 catalog-blind item merge damaged Quad's storefront and how the reversal was built; open when assessing/repairing catalog-fold damage on a two |
+| [Giving a Quad user every persona plus the `Global Admin` role](workflows/granting-all-personas-and-global-admin.md) | 2.0 | The two-table grant for "give internal user X everything on Quad" — every `Personas` row + `Global Admin` — and why it does **not** produce a combined catalogue |
 | [Giving Quad's internal TOGA staff extra toga25-supply nav (the `Agilant - Administrators` role pattern)](workflows/granting-internal-admin-navigation.md) | 2.0 | How to surface extra 2.5 Supply pages to internal TOGA staff on a tenant without showing them to the client's own users — Quad's first internal-admin role; open |

package/knowledge/clients/quad/profile.md

@@ -23,6 +23,7 @@ related:
   - ../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md
   - ./workflows/catalog-fold-reversal.md
   - ./workflows/granting-internal-admin-navigation.md
+  - ./workflows/granting-all-personas-and-global-admin.md
   - ./features/po-asn-email-import.md
   - ./features/enter-po-details-vendor-selection-ev12.md
   - ../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
@@ -63,7 +64,10 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
 - **Quad is the ONLY storefront tenant with the persona switcher**
   (`determineShouldShowPersonaSwitcher` returns true for QUAD alone). With it on, `getLoginSettings`
   sets `_personaIds` to a **single** persona (the saved default, else the first) — so a Quad user
-  never sees a combined view of their personas. `Client_Quad` also has **no persona 24 at all** (not
+  never sees a combined view of their personas. Granting a user **all** personas therefore only makes
+  them **selectable one at a time** in the switcher; it does not widen what they see at once
+  ([all personas + Global Admin](./workflows/granting-all-personas-and-global-admin.md)).
+  `Client_Quad` also has **no persona 24 at all** (not
   on a user, not on a location, the persona does not exist), so the Compass "persona 24" storefront
   hack never touched Quad. See
   [Storefront persona gating](../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md).

package/knowledge/clients/quad/workflows/granting-all-personas-and-global-admin.md

@@ -0,0 +1,86 @@
+---
+title: Giving a Quad user every persona plus the `Global Admin` role
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: quad
+type: workflow
+status: active
+updated: 2026-09-28
+owners: ["apeterson"]
+files:
+  - dbchanges2/Client_Quad/2026-09-28b - GrantAllPersonasToNSchenkel.sql
+related:
+  - ../profile.md
+  - ./granting-internal-admin-navigation.md
+  - ../../compass-usa/workflows/granting-persona-bundle-access.md
+  - ../../../2.0/apps/_underscore/features/effective-persona-resolution.md
+  - ../../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md
+  - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
+---
+
+The two-table grant for "give internal user X everything on Quad" — every `Personas` row + `Global Admin` — and why it does **not** produce a combined catalogue view on this tenant.
+
+## Summary
+
+A recurring request shape: *give internal user X everything on tenant Y*. On Quad it is **two
+guarded, re-runnable INSERTs**, both entirely inside `Client_Quad` (no `Core` join — separate prod
+clusters):
+
+1. **`Users_Personas`** — one row per `Client_Quad.Personas` row the user does not already hold
+   (`Users` resolved by `email`, `CROSS JOIN Personas`), uuid from the house inline `RANDOM_BYTES()`
+   v4 expression.
+2. **`Users_Roles`** — the tenant's `Global Admin` role.
+
+Both are additive: the user keeps every persona and role they already hold (roles resolve as a
+union — [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)).
+Nothing is removed, so this is not a reversible-by-re-run change; removing access is a separate,
+destructive job.
+
+## Steps
+
+1. **Guard `Users_Personas` on `(userId, personaId)`** — that *is* the real unique key
+   (`userId_personaId_UNIQUE`, verified against
+   `dbchanges2/Client/2026-09-22-BLANK_CLIENT_DATABASE.sql:11410`), so a guarded re-run is a true
+   no-op rather than a duplicate-key abort.
+2. **Resolve the role BY NAME, not by id** — `INNER JOIN Roles r ON r.name = 'Global Admin'`. On
+   Quad that is id **7** today, but ids drift per environment; the name keeps one file correct
+   everywhere.
+3. **Name only `uuid`, `userId`, `personaId` / `roleId`.** `Users_Personas` and `Users_Roles` carry
+   **no `dtCreated`** — see the gotcha below.
+4. **End with two verify SELECTs** — the user's persona list ordered by
+   `CAST(number AS UNSIGNED)` (`Personas.number` is a string column) and their role list.
+5. **Hand the file to the developer to run.** Verify in the app by logging out and back in.
+
+### The 2026-09-28 Quad migration
+`dbchanges2/Client_Quad/2026-09-28b - GrantAllPersonasToNSchenkel.sql` — branch `TRUE-82247`,
+**not committed and not yet run in any environment.** Grants `nschenkel@togatech.com` every
+`Client_Quad` persona plus `Global Admin`.
+
+Context: NSchenkel is one of the three `@togatech.com` Quad users deliberately left **off** the new
+`Agilant - Administrators` role created the same day
+([internal-admin navigation](./granting-internal-admin-navigation.md) — that role went to
+`devteam@togatech.com` only). This grant gives a different, wider reach: the tenant's own
+`Global Admin`, not the nav-only internal role.
+
+## Gotchas
+
+- **⚠ On Quad, "all personas" does NOT mean "sees everything at once".** Quad is the **only**
+  toga2-commerce tenant with the **persona switcher**
+  (`determineShouldShowPersonaSwitcher` returns true for `QUAD` alone), and with it on
+  `getLoginSettings` sets `_personaIds` to a **single** persona (the saved default, else the first).
+  So this grant makes every persona **selectable, one at a time** — it does not build the combined
+  catalogue view the same grant would give on Compass / Compass Canada. Expect the reporter to say
+  "the storefront did not change". See
+  [Storefront persona gating](../../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md).
+- **This touches only source 1 of the three effective-persona sources.** `Locations_Personas` on the
+  user's own location and on the 5-hop sector are untouched — so a "who has persona N" check still
+  has to resolve all three. See
+  [Effective persona resolution](../../../2.0/apps/_underscore/features/effective-persona-resolution.md).
+- **`Global Admin` is not an internal-only role on Quad.** Role 7 is held by 7 users, five of them
+  `@quad.com` — fine for granting *to* one internal user, never a place to hang an internal-only
+  override.
+
+## Change history
+- 2026-09-28 — Created; documents the `Users_Personas` + `Users_Roles` all-personas grant written for
+  NSchenkel (not yet run) and the Quad persona-switcher caveat (apeterson)

package/knowledge/clients/quad/workflows/granting-internal-admin-navigation.md

@@ -16,6 +16,7 @@ related:
   - ../../../2.0/apps/toga25-supply/features/side-navigation-and-default-route.md
   - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
   - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
+  - ./granting-all-personas-and-global-admin.md
 ---
 
 How to surface extra 2.5 Supply pages to internal TOGA staff on a tenant without showing them to the client's own users — Quad's first internal-admin role; open for "internal user can't see page X" on any tenant.
@@ -45,6 +46,8 @@ staff. That is a tenant-wide behavior change dressed up as a per-user fix.
 3. **Create a dedicated `Agilant - Administrators` role** in the client DB if the tenant has none,
    and assign only the internal users the developer names. Quad got **`devteam@togatech.com` only**;
    the other three `@togatech.com` Quad users (JWise, NSchenkel, rgreen) were deliberately left off.
+   NSchenkel was instead granted the tenant's own `Global Admin` role (a different, wider reach) —
+   [all personas + Global Admin](./granting-all-personas-and-global-admin.md).
 4. **Add role-scoped `SurfaceOverrides` rows** (`surfaceId` 39, the element ids, `IS_VISIBLE` = `'1'`,
    `personaId`/`languageId` NULL) for that new role. Nothing else — no `AclRecordPermissions`, no
    `AclFieldPermissions`, so the migration cannot widen data access.
@@ -77,5 +80,7 @@ Quad's starting state for contrast: **one** nav override total (element 109 `sal
   migration there.
 
 ## Change history
+- 2026-09-28 — NSchenkel (left off this role) granted `Global Admin` + all personas instead, in a
+  separate file; linked. (apeterson)
 - 2026-09-28 — Created; Quad's first `Agilant - Administrators` role + Items/Vendor Items nav
   overrides written (not yet run), scoped away from `Global Admin` role 7 (apeterson)

package/package.json

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