toga-ai 1.0.910 → 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/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.910",
+  "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",