toga-ai 1.0.910 → 1.0.912

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

@@ -4,6 +4,7 @@
 |-----|---------|
 | [Library (1.0 Framework) Architecture](architecture.md) | The 1.0 `App_` framework core: bootstrap/autoloader, the `app/` (`App_`) + `browser/` (`Browser_`) class trees, and vendored packages; open for how any 1.0 app |
 | [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | The shared 1.0 address-validation gateway (`App_Api_OfficeDepot::validateAddress` → USPS fallback); open when standardizing/verifying a typed address before sav |
+| [API Request Logging & Retention (App_ApiTransaction → Logs.API / Logs_<Tenant>)](features/api-request-logging-and-retention.md) | Where every outbound API call is logged (1.0 `Logs.API` vs the 2.0 `Logs_<Tenant>` cluster), how the routing is chosen, and the 30-day retention trim; open befo |
 | [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | Where a new `App_` class goes — each `app/` folder's base class carries real inherited behavior; open before creating any class under `app/model|client|api`. |
 | [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | Reusable 1.0 SP-initiated SAML SSO via `saml.togahub.com` (`App_Sso::initiate`); the canonical doc to follow for any "add SSO to `<1.0 app>`" request. |
 | [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | 1.0 cron check-in/out lifecycle via `App_Framework::cronInitialization()`/`cronFinished()` → `Common.CronJobExecutions`; open to monitor a 1.0 cron or read its |

package/knowledge/1.0/apps/library/features/api-request-logging-and-retention.md

@@ -0,0 +1,89 @@
+---
+title: "API Request Logging & Retention (App_ApiTransaction → Logs.API / Logs_<Tenant>)"
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-09-29
+owners: ["mhammontree"]
+files:
+  - library/app/apitransaction.php
+  - library/app/model/logs/api.php
+  - library/app/model/toga2/logs/api.php
+  - worker/crons/maintenance/maintenance_daily.php
+related:
+  - error-capture-1-0.md
+  - ../architecture.md
+---
+
+Where every outbound API call is logged (1.0 `Logs.API` vs the 2.0 `Logs_<Tenant>` cluster), how the routing is chosen, and the 30-day retention trim; open before changing log routing, retention, or debugging past-window history.
+
+## Summary
+
+`App_ApiTransaction` writes one row per outbound API call. It has **two** storage paths — the legacy 1.0 `Logs`.`API` table and the 2.0 per-tenant `Logs_<Tenant>` cluster — and picks between them per run. Retention is enforced only on the 1.0 side, by a daily worker cron, at **30 days**.
+
+## How it works
+
+### Which log DB a call lands in
+`library/app/apitransaction.php:377`:
+```php
+if (App_Registry::varIsSet('toga2LogsDatabase')) { /* App_Model_Toga2_Logs_Api */ }
+else { /* App_Model_Logs_API  → legacy Logs.API */ }
+```
+- 2.0 routing is **opt-in per cron**. Only 10 crons set it, all Prudential, each hardcoding
+  `App_Registry::set('toga2LogsDatabase', 'Logs_Prudential')`.
+- Every other `crons/toga2/*` cron falls through to the 1.0 table — **this is why 2.0 client traffic
+  lands in the 1.0 `Logs.API`**.
+
+### Retention (1.0 only)
+`worker/crons/maintenance/maintenance_daily.php` trims the log tables nightly.
+- `$daysToKeep_APILog` = **30** (was 90; cut 2026-09-28, TRUE-82049, commit `89ef44f35`).
+- The `DELETE FROM Logs.API` is **chunked**: 25,000 rows per statement in a do/while loop with a
+  1s sleep, still bounded overall by `$maxLimitForDeletes`. Every *other* table this cron trims is
+  a single statement — `Logs.API` is the exception because it is ~12x the next biggest table
+  (`Vision_Log.Log`, 45.85 GB), and a single 5,000,000-row DELETE holds locks for minutes and lags
+  read replicas.
+- **The one-time backlog purge (~20M rows) is separate and not done** as of 2026-09-29.
+
+### Storage facts (measured 2026-09-28)
+- 1.0 `Logs`.`API`: **565.27 GB / 34,464,186 rows**, growing **~6.3 GB/day**. `dtStamp` is the
+  indexed date column; `sourceJob` names the writing cron.
+- Top writers by bytes (2-day sample): `sync_togasupply_compass_usa.php` 2.53 GB (128 KB/row),
+  `periodic_forecast_discrepancy_fix.php` 1.63 GB, `sync_togasupply_hh.php` 0.84 GB,
+  `sync_togasupply_elite.php` 0.53 GB, `compass/workflow/5_create_netsuite_sales_order.php`
+  1,581 KB/row, `infrastructure/system_monitors.php` 3,040 KB/row.
+- 2.0 logs cluster (`writer.logs.database.togahub.com`): **~1.67 TB** across 36 `Logs_<Tenant>`
+  DBs, oldest rows **2025-08-24** (~13 months — *not* the 90 days believed), and **no scheduled
+  DB events trimming it**. Largest: `Logs_Wje` 372.80 GB, `Logs_Elite` 228.99 GB,
+  `Logs_Compass` 185.88 GB, `Logs_Nychh` 129.71 GB, `Logs_Prudential` 125.32 GB.
+  `Logs_Northwell` is 43.59 GB from only 194,643 rows = 224 KB/row.
+
+### Decision
+**`Logs.API` is forensics-only; 30 days is enough** (Jeff, 2026-09-17). Debugging that needs
+older history is no longer possible — slow-burn bugs must be caught by **alerting**, not
+reconstructed after the fact.
+
+## Gotchas
+
+- **DELETE does not return space to disk on InnoDB.** After the backlog purge the file stays
+  ~565 GB with `DATA_FREE` growing. Reclaiming disk needs `OPTIMIZE TABLE` (~565 GB spare
+  required) or a copy-and-swap — a separate decision, not part of the retention change.
+- **Do NOT move 2.0 client logging to the 2.0 cluster without solving retention there first.**
+  It would shift ~7 GB/day onto a cluster that is already bigger and has **no working retention**.
+  Deliberately descoped from TRUE-82049. Nobody has found the 2.0 archiving script — it is not in
+  `worker2`, `api2`, or `_underscore`.
+- **`App_Model_Toga2_Logs_Api` has NO `save()` override.** The 1.0 `App_Model_Logs_API::save()`
+  deliberately wraps `parent::save()` in try/catch because a long-running cron can outlive its
+  `db_logs` connection (MySQL "server has gone away"), which once aborted whole imports mid-run.
+  Routing traffic to the 2.0 model without adding that guard reintroduces that failure.
+- **The 2.0 model has a `source` column the 2.0 branch never sets** — moving a cron to 2.0 logging
+  loses the writing-cron name (`sourceJob`'s equivalent).
+- **Cap payload size when adding new logging.** Team precedent: worker2's
+  `MAX_LOG_PAYLOAD_LENGTH = 8000` with a `...[truncated]` marker
+  (`Worker/Netsuite/Opportunity.php:148`, `Worker/Clickup/Opportunity.php:45`). Rows of
+  1,500–3,000 KB are what built the 565 GB table.
+
+## Change history
+- 2026-09-29 — Created: `Logs.API` retention cut 90→30 days and chunked DELETE (TRUE-82049); dual 1.0/2.0 routing and 2.0-cluster storage facts recorded. (mhammontree)

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/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

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 28 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 29 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 40 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/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/nycdoe/features/hold-status-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-09-25
+updated: 2026-09-29
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/send_ticket_updates.php
@@ -16,6 +16,7 @@ files:
   - library/app/model/common/nycdoeticket.php
   - dbchanges/Common/MH/2026-09-16.sql
   - library/app/api/nycdoev2.php
+  - worker/crons/sync/nycdoe/import_inc.php
   - togadesk/desk/includes/classes/class.repair.php
 related:
   - servicenow-integration.md
@@ -101,6 +102,60 @@ Current selection query:
 - The standalone assignment-group block was **deleted** — the main payload already diffs `assignment_group`, so it was a duplicate GET, a second code path, and the source of the lockout stamp.
 - Debug pin already in the file: the commented `#AND NYCDOETickets.ticketNumber = '...'` line scopes a pass to one ticket.
 
+### Assignment-group scoping — what counts as OUR ticket (rule, Mark 2026-09-28)
+**We only care about an INC or RITM while it is assigned to one of OUR ServiceNow assignment
+groups. If it is not, drop it and never re-check it. NEVER add another vendor's group to
+`Common.NYCDOETicketsDepartments`** to "make it sync" — a group that is not ours means DOE
+reassigned the incident away from ASI.
+
+**⚠ `Common.NYCDOETickets.isValidDepartmentName` means the OPPOSITE of its name.** `1` =
+**EXCLUDED from processing**; `0`/`NULL` = processed. Every write of `1` is on a skip path
+(invalid site code, unmapped assignment group, or SD QA — deliberately skipped at
+`process_tickets.php:392`), and all four DOE selections pick up only `= 0 OR IS NULL`. The
+companion column `departmentName` carries the human reason (`INVALID_SITE_CODE`,
+`Invalid Address Resolution`, or the actual ServiceNow group name). Reading the column name
+literally gives you the exact opposite of the truth. Writers: `process_tickets.php` (348, 392,
+1520), `import_asn.php:104`, `import_inc.php:85`, `send_ticket_updates.php:235`,
+`send_request_item_updates.php:56`. A pure rename across 13 sites would be safe, but must not be
+bundled with a behavior change.
+
+**The drop is self-healing — which is why no new column is needed.** `import_inc.php:82-86` loads
+the existing row by `referenceSysId` and unconditionally resets
+`dtProcessed = null; isValidDepartmentName = null; departmentName = null;` on every re-import
+(same in `import_asn.php:148`). While a ticket sits in a non-ASI group it never matches the
+importer filter, so it stays dropped at zero cost; if DOE reassigns it back to ASI its
+`sys_updated_on` moves, it re-imports, and the flag clears automatically. A purpose-built new
+column would NOT be reset by either import path and would make the drop irreversible — reusing
+`isValidDepartmentName` is the correct choice, not a compromise.
+
+**⚠ OPEN DEFECT (backfilled by hand, CODE FIX NOT DONE — needs its own ticket).**
+`send_ticket_updates.php` (~L375) treats an unmapped group as "someone forgot a mapping" and
+emails devteam@togatech.com hourly saying *"Add the group to that table to let them sync."* That
+advice is wrong. Measured cost: 15 tickets across 9 other-vendor groups (NOC Field, ATLAS Tier III
+Support, SD Nagarro Queens, OASIS L3 Support, NGSIS/GAM Support, Central User Support, Field Ops
+Queens, Field Ops Bronx, IET Support) re-GET every 6 minutes = **~3,600 wasted ServiceNow calls/day
+and ~236 emails since 2026-09-18**. Those 15 INCs were set by hand in production to
+`isValidDepartmentName = 1` with the real group in `departmentName`, and confirmed excluded.
+**Agreed approach for the fix ticket (CTO-reviewed) — an ordered predicate:**
+1. Group **is** in `NYCDOETicketsDepartments` → process normally (this is what keeps SD QA working).
+2. Group is not in the table but **starts with `ASI`** → keep the throttled email; this is the only
+   case the current advice is right for.
+3. Neither → **drop silently.**
+Do **not** close the repair orders — write one `repair_order_notes` line and send a one-time digest
+to DOE ops. `send_request_item_updates.php` needs the same treatment for RITMs.
+
+**⚠ Three competing definitions of "our DOE assignment groups" — they disagree.**
+- **(a) `Common.NYCDOETicketsDepartments`** — 14 rows: ASI Bronx, ASI Brooklyn, ASI Manhattan,
+  ASI Queens, ASI Staten Island, ASI General, ASI Calls, ASI Reconnect, ASI Research, ASI DOA,
+  ASI TM, SD QA (`isImportEnabled=0`), ASI Disposal, ASI PCS Delivery. **This one is correct.**
+- **(b) `download_tickets_incidents.php:80`** — a hardcoded 12-group ServiceNow query list that
+  includes "ASI Enhanced", which exists nowhere else. The file is referenced by **no**
+  `schedules/*.json` → **dead code; delete it in its own commit.**
+- **(c) `App_Api_NYCDOEV2::listIncItems()` (`library/app/api/nycdoev2.php:912`)** — the **live**
+  importer filter, a prefix match `assignment_groupSTARTSWITHASI^stateIN1,2,3,10`. This is what
+  `import_inc.php` actually uses.
+**Risk:** a future group named "ASI Something" imports under (c) then is dropped under (a).
+
 ### Batch loop, run caps & per-ticket isolation (TRUE-82129 current shape)
 Before this the cron ran the selection query **once per ticket under `LIMIT 1`** with a `sleep(1)` after every ticket — one ticket per 6-minute run, ~10 days for a full pass over the queue.
 - **One `LIMIT 250` (`BATCH_SIZE`) read into a PHP array, consumed with `array_shift`, refilled only when empty.** The query is `type=ALL`, ~35,021 rows, `Using temporary; Using filesort` (it drives off `managed_service_orders`, so `Common.NYCDOETickets.idx_dtLastChecked` is unusable at this join order). A filesort already sorts every surviving row before returning the top N, **so a bigger LIMIT costs nothing extra**.
@@ -138,6 +193,19 @@ There is **no sandbox for the SNOW integration**; verification happens in prod.
 2. INC2087375's `u_eta` moving from 2026-09-07 to 2026-09-17.
 3. `SELECT COUNT(*) FROM Common.NYCDOETickets WHERE dtLastChecked IS NOT NULL` climbing.
 
+**Answering "did the alert fire, and did the mail actually send?" — two tables, not an inbox.**
+An inbox check alone is misleading; the DB is decisive.
+- **Did the alert fire?** marker rows in `Core.AdvanceShippingNoticeQueue`, `dedupeKey`
+  `system|ticket_sync_patch_failure_alert` and `system|ticket_sync_invalid_group_alert`.
+- **Did the mail send?** `Logs.Emails` — columns `dtSent`, `isSuccess`, `error`, `subject`, `to`,
+  `sourceJob`. ⚠ the table is **`Emails`**, not `Email`, and the timestamp is **`dtSent`**, not
+  `dtStamp`.
+
+**TRUE-82027 verified healthy in production 2026-09-28:** `dtLastChecked` + `idx_dtLastChecked`
+present; ~2,784 active tickets cycling in under an hour at `RECHECK_INTERVAL_MINUTES=6`; PATCH
+volume ~44,000/day at 443,706 x HTTP 200 against only 6 non-200 over 10 days (3x 502, 1x 429);
+reproduction case INC2087375 back in rotation and syncing.
+
 ### RITM cron — deliberately unchanged by TRUE-81044
 `send_request_item_updates.php` already pushes native `state:"8"` (On Hold) and **never wrote** `u_status_task`, so TRUE-81044's ask was already satisfied there. It carries a defensive `HOLD_*` guard on the scheduled-update path so it can't push `state:"-14"` while held; its reverse-hold logic still **reads** `u_status_task == 'On Hold'`.
 > **OPEN QUESTION:** ServiceNow's communication was scoped to **Incident** state. We did **not** extend `hold_reason` / `u_eta` / `u_other_reason_on_hold` to the RITM payload without confirmation. Whether the RITM On Hold transition carries the same mandatory-set requirement is unconfirmed — ask before changing the RITM payload.
@@ -175,7 +243,7 @@ The SNOW round-trip note reconciliation (delete-and-reinsert in `process_tickets
   - **Query shape that works (TRUE-82332):** `endpoint LIKE '%nycd3%...'` and broad `requestPayload LIKE` scans time out (>300s) on the MCP. Use exact matches: PATCH `endpoint = 'https://supportadmin.schools.nyc/api/nycd3/data/tasks/INCxxxx'`; GET `endpoint = 'https://supportadmin.schools.nyc/api/nycd3/v2/data/tasks?domain=diit%2Calm&filter=sys_class_name%3Dincident%5Enumber%3DINCxxxx'`. For sweeps: `FORCE INDEX (dtStamp)`, windows ≤2 days, plus `sourceJob` / `method` filters. The state:3↔state:2 oscillation in TRUE-79922 was proven from this table (INC2074899, INC2185183 showed `state:3` then `state:2` pushed seconds apart in one run).
 - **`NYCDOETickets` (`App_Model_Common_NYCDOETicket`, `db_common` / legacy `Common`)** stores the inbound SNOW record in `rawData`, a **`FIELDTYPE_BLOBSTORAGE`** field (S3 bucket `asifiles`, key `prod/Common/NYCDOETickets/rawData/{id}`) — **NOT a queryable DB column.**
 - **⚠ `repair_orders.dtUpdated` is skewed — never build a selection query on it.** It is written exactly **240 minutes behind** the clock used by `repair_order_notes.notesdate` and `NYCDOETickets.dtSynced`. **Do NOT compensate with `+240 MINUTE`** — 240 is almost certainly UTC-vs-Eastern and becomes 300 at the DST change (2026-11-01), so a hardcoded offset breaks twice a year. TRUE-82027 sidestepped it by removing `dtUpdated` from the query. Mechanism + the second (720-minute) skew: [Field-Service Dispatch](../../../1.0/apps/togadesk/features/field-service-dispatch.md).
-- **⚠ `Logs.API` history is capped at 30 days from 2026-09-17** (Jeff, sprint review) and existing logs are being purged. This investigation depended on history far older than that (9,914 PATCHes back to 2026-08-20; a hold last pushed 22 days earlier; the 2,392-call storm). **Slow-burn bugs like this can no longer be traced backwards — they must be caught by alerting.** NYCDOE stays 1.0 so its logs stay in legacy `Logs.API`; Compass/Elite/WJE move their API logging to 2.0. Agreed: hold the purge until TRUE-82027 is verified in production.
+- **⚠ `Logs.API` history is capped at 30 days — SHIPPED 2026-09-28 (TRUE-82049).** This investigation depended on history far older than that (9,914 PATCHes back to 2026-08-20; a hold last pushed 22 days earlier; the 2,392-call storm). **Slow-burn bugs like this can no longer be traced backwards — they must be caught by alerting.** NYCDOE stays 1.0 so its logs stay in legacy `Logs.API`. Mechanics, storage facts and the not-yet-run backlog purge: [API Request Logging & Retention](../../../1.0/apps/library/features/api-request-logging-and-retention.md).
 - **Worker prod code cannot run on a Windows dev box.** The DB/S3 data layer fetches EC2 instance-metadata (IMDSv2) credentials and fails off-EC2. Investigate with the toga DB MCP and the `Logs.API` table instead of running the crons locally.
 
 ## Gotchas
@@ -202,6 +270,7 @@ The SNOW round-trip note reconciliation (delete-and-reinsert in `process_tickets
 - `qqStatus()` collapses all recognized hold sub-statuses to base `HOLD` in `repair_orders.status`; the specific hold **sub-reason persists only in `repair_order_notes.newstatus`**. Any status badge / report / filter reading `repair_orders.status` directly cannot distinguish the six hold variants after a recompute.
 
 ## Change history
+- 2026-09-29 — Assignment-group scoping rule + inverted `isValidDepartmentName` + the three competing group definitions; TRUE-82027 verified in prod (marker rows + `Logs.Emails` method). (mhammontree)
 - 2026-09-25 — TRUE-82332: hold-release no longer overwrites the close `state`; close re-sent when SN not closed; stuck-ticket re-queue recipe; `Logs.API` query shapes. (mhammontree)
 - 2026-09-18 — TRUE-82129: fixed the by-reference `fetchOne()` notice that killed every run; batch loop + run caps replaced LIMIT 1 + per-ticket sleep; alert emails de-PII'd and escaped; unmapped-group email now grouped per run. (mhammontree)
 - 2026-09-17 — TRUE-82027: outbound push runs once per order per pass; `dtLastChecked` split from `dtSynced`; failure alerting instead of a throw. (mhammontree)

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-09-25
+updated: 2026-09-29
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -62,7 +62,7 @@ The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents +
 | Table | Purpose |
 |---|---|
 | `NYCDOETickets` | Local ticket mirror (keyed `referenceSysId`; `type` = INCIDENT / RITM) |
-| `NYCDOETicketsDepartments` | Allowlist of valid assignment groups — others are not processed |
+| `NYCDOETicketsDepartments` | Allowlist of OUR assignment groups — others are dropped and never re-checked. ⚠ Two other places define this list differently, and `NYCDOETickets.isValidDepartmentName` is **inverted** (`1` = excluded): see [Hold-Status Sync](hold-status-sync.md) → *Assignment-group scoping* |
 | `NYCDOELocations` | Site-id → address mirror (backs ASN ship-to resolution) |
 | `AdvanceShippingNoticeQueue` | Stage-1 landing zone; **UNIQUE index `idx_dedupeKey`** |
 | `AdvanceShippingNotices` / `…Items` / `…Units` | ASN header (vendor+PO) → per-part items (`qtyOrder`) → individual units |
@@ -130,7 +130,7 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 
 ### Debugging & DB topology (DOE 1.0 sync)
 The 1.0 worker cannot run on a dev/Windows box; use the toga DB MCP + `Logs.API` instead of running prod code locally.
-- **⚠ `Logs.API` retention is 30 days from 2026-09-17** (Jeff, sprint review) and existing logs are being purged — so it is no longer a *historical* debugging avenue, only a recent-window one. Bugs that burn slowly (a hold not re-pushed for 22 days; 9,914 PATCHes traced back to 2026-08-20) can no longer be reconstructed after the fact and must be caught by **alerting** instead. NYCDOE stays 1.0, so its logs remain in legacy `Logs.API`; Compass/Elite/WJE move their API logging to 2.0.
+- **⚠ `Logs.API` retention is 30 days — SHIPPED 2026-09-28 (TRUE-82049)**; mechanics, storage facts and the not-yet-run backlog purge in [API Request Logging & Retention](../../../1.0/apps/library/features/api-request-logging-and-retention.md) — so it is no longer a *historical* debugging avenue, only a recent-window one. Bugs that burn slowly (a hold not re-pushed for 22 days; 9,914 PATCHes traced back to 2026-08-20) can no longer be reconstructed after the fact and must be caught by **alerting** instead. NYCDOE stays 1.0, so its logs remain in legacy `Logs.API`; Compass/Elite/WJE move their API logging to 2.0.
 - **`repair_orders.dtUpdated` and `.lastupdateddate` are both time-skewed in `TOGaDeskSupport`** — never select or diff on them, and never compensate with a fixed offset. Detail: [Field-Service Dispatch](../../../1.0/apps/togadesk/features/field-service-dispatch.md).
 - **`dbchanges` does not describe the real 1.0 schema** — some live columns were created outside the repo. Verify indexes/columns against the database, not the repo: [Authoring & Shipping a 1.0 dbchanges SQL File](../../../1.0/apps/dbchanges/workflows/authoring-and-shipping-sql-files.md).
 - **`db_core` alias → legacy (V1) environment, schema `Core`** — holds the FLAT tables `AdvanceShippingNotices` / `AdvanceShippingNoticeItems` / `AdvanceShippingNoticeUnits` (columns incl. `togadeskRepairOrderId`, `serialNumber`, `netSuiteInternalSalesOrderId`, `netSuiteInternalPurchaseOrderId`, `customerPurchaseOrder`). The 1.0 cron reads **legacy/Core**.
@@ -262,5 +262,6 @@ All **live** DOE business logic is 1.0. The only other 2.0 code is the in-progre
 - Local deep-dive (full WR260236464 case study with record IDs): `doe_service_now_integration.md` in Mark's WWW workspace root; also the `service-now-integration` skill (`asn-import-flow.md`)
 
 ## Change history
+- 2026-09-29 — Assignment-group scoping corrected (inverted `isValidDepartmentName`, three competing group lists) with detail in hold-status-sync; `Logs.API` 30-day retention shipped. (mhammontree)
 - 2026-09-25 — TRUE-82332: cross-link to the close-clobber fix; test-repo copy of the ServiceNow credential noted (mhammontree)
 - 2026-09-25 — Corrected "no 2.0 tenant" (TRUE-80519 2.0 ASN rewrite now exists); DOE-Open-Lenovo marked retired (mhammontree)

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.910",
+  "version": "1.0.912",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",