toga-ai 1.0.1089 → 1.0.1091

package/knowledge/2.0/apps/toga-blox/features/api-client.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-20
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/reactQuery/queryHelpers.ts
@@ -63,6 +63,7 @@ blox axios/React-Query client — envelope, auth (Bearer + refresh), option seri
 - `TableViewField.slug` (URL-safe) ≠ `tableViewField` (DB column path); `getDataTableData` maps slug → DB field.
 - Only **401** auto-retries; other network errors need React Query `retry`.
 - 401 refresh needs a `refreshToken` in localStorage, else it logs out (hard redirect to `/`).
+- Refresh covers **only** calls through the registered axios instance. A raw `fetch` to another host (e.g. Talos/Aegra) keeps a stale token and fails after expiry — call `refreshAccessToken` yourself, as toga25-supply's `talosFetch` does ([talos-integration](../../toga25-supply/features/talos-integration.md)). `refreshAccessToken` logs the refresh bearer on failure — [defect 10](blox-authoring-defects.md).
 - `transactionId` is injected automatically (request tracing); `depth=-1` returns hydrated nesting.
 - **⚠ `fetchPublicToken()` (`POST /auth/public`) is ORIGIN-GATED** — api2 resolves the browser's `Origin` header against `Core.Domains` to establish `appId`/`clientId` before minting, and rejects an unregistered origin with **EN-6 "domain not permitted"**. Every **host variant needs its own `Core.Domains` row**: verified 2026-08-13 that `https://togatech.com` and `http://localhost` (any port — the port is stripped) are allowed while **`https://www.togatech.com` is rejected**. Symptom on a public marketing page is *silent* — no token, so every anonymous fetch fails and the section renders its empty state. Fix is a `Core.Domains` row, not frontend code. See [encrypted user-uuid auth handoff](../../api2/features/encrypted-user-uuid-auth-handoff.md) for the same gating on the SSO handoff route.
 - **⚠ `assembleOptionsWhere` (`reactQuery/queryHelpers.ts`) expects every `where.and`/`where.or` entry to be a STRUCTURED OBJECT** (`{field:{op:value}}`). A **raw API-syntax string** clause — e.g. a metadata `apiWhereClause` like `(IFNULL(Items.assetTypeId,0):ne:3)` that `getDataTableData` pushes into `apiOptions.where.and` — is iterated with `for (const field in entry)`, which on a string walks **character indices**, emitting garbage `index:0:char` conditions (`0:0:(`, `1:0:I`, …). api2 v2 then rejects the request with **`Invalid operator '0'` → EO-1 500**. Symptom: opening a modal/table whose `tableViewMeta` carries an `apiWhereClause` (seen in the Compass USA Item Fulfillment modal) 500s. Fix (in place since 2026-08-17): the serializer now passes any `typeof === "string"` entry through **verbatim**, stripping one outer paren pair so the group re-wrap doesn't double-wrap. Any raw pre-formatted where clause was 100% broken before this. If you add a new raw-string clause path, route it through this string branch — do **not** feed a raw clause into an object-expecting serializer.
@@ -88,3 +89,7 @@ blox axios/React-Query client — envelope, auth (Bearer + refresh), option seri
 
 - [architecture](../architecture.md) — library overview and the data-layer summary.
 - [Table component](table.md) — consumer of the table-data fetchers.
+
+## Change history
+
+- 2026-10-20 — Gotcha: axios-only refresh; raw `fetch` callers must refresh themselves (TRUE-82954) (tcox).

package/knowledge/2.0/apps/toga-blox/features/blox-authoring-defects.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-10-05
+updated: 2026-10-20
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/components/BaseButton
@@ -53,6 +53,11 @@ Nothing here is scheduled — a backlog with evidence attached, so a fix can be
 - **Consumer symptom.** On any **SSO client**, `/` is precisely the route that triggers the IdP redirect — so signing out bounces the user straight back into SSO and the local `/login` becomes **unreachable**. Worse, an app cannot fully patch around it from one place: the Logout button goes through the app's own auth context while an expired token goes through blox's 401 interceptor, so a workaround must cover **both** paths. `toga25-supply` built that workaround and then reverted it, so the loop is live there today.
 - **Fix direction.** Make the destination **caller-supplied** (a `redirectTo` option, defaulting to today's `"/"`), or have `performLogout` not navigate and let the caller's `onLogout` own it.
 
+**10. `refreshAccessToken` — logs the whole `AxiosError`, refresh token included** (found 2026-10-20, TRUE-82954)
+- **Mechanism.** On failure it `console.error`s the full `AxiosError`, whose `config.headers` hold `Authorization: Bearer <refreshToken>`.
+- **Consumer symptom.** None visible. The refresh token lands in the browser console and, in apps with Sentry, can ride along in a console breadcrumb — a credential leak the app cannot stop (frontend §12: never log a token).
+- **Fix direction.** Log only `error.response?.status` and a short message. Non-breaking.
+
 ### Styling defects
 
 **4. `BaseButton` — `primary` and `primaryAction` are NOT interchangeable variants**
@@ -105,6 +110,7 @@ Long-standing, previously recorded only as consumer-side advice:
 - **A fix here is a fleet-wide change.** blox is unbundled and consumed by ~40 call sites; anything touching auth or `localStorage` keys changes live session behavior on the next channel head a consumer picks up — and `toga2-commerce` picks up the channel head **automatically at build time**, with no PR. Sequence auth fixes deliberately.
 
 ## Change history
+- 2026-10-20 — added auth defect 10 (`refreshAccessToken` logs the refresh-token bearer) (tcox)
 - 2026-10-05 — added tooling defects 7–9 (Storybook addons in `dependencies`, unstyled local-only Storybook, broken Docker scripts) (tcox)
 
 ## Related

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

@@ -4,6 +4,7 @@
 |-----|---------|
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | Whole-repo map of the toga2-commerce React storefront (bootstrap, routing, MVVM pages, state, API, multi-tenant resolution); open when working anywhere in this |
 | [Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)](features/bundle-item-visibility-and-selectability.md) | Which kit components a shopper can see/select is decided entirely in the browser, enforced nowhere on the server; open when touching bundle rendering, kit check |
+| [Cart addItem line merge — re-adding an item refreshes its price, except in edit-order mode](features/cart-add-item-line-merge.md) | What `useCartStoreZu.addItem` does when the item is already a cart line: a draft cart takes the new price, edit-order mode keeps the saved order price; open for |
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart bundles (kits) become SalesOrderItems on submit/edit, and the bundleUuid identity contract every consumer must obey; open before touching cart-bundle s |
 | [Cart Notification Emails — auto-add/remove lifecycle + duplicate prevention](features/cart-notification-emails.md) | Cart Notifications section: CC-email duplicate prevention + auto-add/remove of order-for-user & delegate-manager emails; open when touching notification emails |
 | [Cart Order For user — Add New User duplicate guard + approving-manager rule](features/cart-order-for-user-and-approving-manager.md) | Cart "Order For" user section: the Add New User duplicate check (username OR email), who the Order For list can find, and the config-driven rule that blocks che |

package/knowledge/2.0/apps/toga2-commerce/features/cart-add-item-line-merge.md

@@ -0,0 +1,86 @@
+---
+title: Cart addItem line merge — re-adding an item refreshes its price, except in edit-order mode
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-10-19
+owners: ["tcox"]
+files:
+  - toga2-commerce/src/stores/useCartStoreZu.ts
+  - toga2-commerce/src/stores/useCartStoreZu.test.ts
+  - toga2-commerce/src/stores/useEditOrderZu.ts
+  - toga2-commerce/src/pages/ItemsView/ItemViewPage.tsx
+  - toga2-commerce/src/api/syncSalesOrderFromApiToLocalStorage.ts
+  - toga2-commerce/src/pages/Cart/view/cartTable/CartTableBundleItem.tsx
+related:
+  - ./catalog-cache-freshness.md
+  - ./inactive-item-purchase-gating.md
+  - ./cart-bundle-submission-and-identity.md
+  - ./cart-order-total-computation.md
+  - ../workflows/unit-testing-vitest.md
+  - ../workflows/local-development-hosts.md
+---
+
+What `useCartStoreZu.addItem` does when the item is already a cart line: a draft cart takes the new price, edit-order mode keeps the saved order price; open for any "cart shows the old price" or "editing an order changed its price" bug.
+
+## Summary
+
+> **Status 2026-10-19 — branch-dependent.** The rules below are on `TRUE-82729` (`c2b756a8`, pending merge, not on `_production`). Ship it **with or after** `TRUE-82427` — see [Merge order](#merge-order).
+
+A line is matched by `Item.uuid`. On a match:
+
+| Mode | `price` / `lease` / `Item` | `uuid` (sales order item link) | quantity |
+|---|---|---|---|
+| Draft cart | taken from the new item | kept | summed |
+| Edit-order (`useEditOrderZu.getState().inEditMode`) | **kept** (saved order values) | kept | summed |
+
+New items added while editing use the current price. The line `price` (`ItemForZuCart.price`) is what totals (`useCartViewModel.ts` reduce) and the sales order sync (`syncSalesOrderItemsFromLocalStorageCartToApi.ts` L42) use.
+
+## How it works
+
+### Decision — edit-order mode never reprices a placed order
+
+Decided 2026-10-19 (tcox). Repricing an order the customer already placed is bad business practice. Edit mode starts at `/cart?uuid=<salesOrderUuid>` (`useCartViewModel.ts` ~L87-110 calls `setInEditMode(true)`).
+
+**Check `inEditMode`, never the line `uuid`.** A normal draft cart is a quote sales order loaded at login by `syncSalesOrderWithLocalStorageCart` (`AuthLayout`), so its lines carry sales order item uuids too.
+
+### Who calls `addItem` with an existing line
+
+- **Item page** (`ItemViewPage.tsx` `handleAddItemToCart`) — the main re-add path. After add it resets quantity to 1 only; price/lease/uuid stay.
+- **Split from kit** (`CartTableBundleItem.tsx` ~L74) — sends `bundleItem.item._unitPrice`, the item's own catalog price (the kit price is `bundleItem._unitPrice`). Split is enabled only for COMPASS / COMPASSCANADA admins.
+- **Home `ItemsSection` and Filter** — call `addItem` only when the item is not in the cart (they show +/- otherwise), so they never reach the merge branch.
+- **Cart "+" (`incrementItem`)** — never changes price.
+
+A currency change in MySettings clears the cart, so a merge never mixes currencies.
+
+### Merge order
+
+On `_production` the item page still serves a price cached up to 24h (see [catalog cache freshness](./catalog-cache-freshness.md#where-the-staleness-lives)), so a re-add would copy that old cached price onto the line. `TRUE-82427` removes that cache. The branches touch different lines; no conflict expected.
+
+### How to test (no DB change)
+
+1. Add an item to the cart.
+2. In the browser console, edit `localStorage["zu-cart"]`: parse it, set `c.state.items[0].price = 1`, write it back. Reload.
+3. Re-add the same item from the item page. The line must jump back to the real price.
+4. Edit mode: open `/cart?uuid=<test order uuid>`, fake the price the same way, re-add. The price must stay.
+
+Passed 2026-10-19. Unit tests: `src/stores/useCartStoreZu.test.ts` (4 tests incl. edit mode) — see [unit testing](../workflows/unit-testing-vitest.md).
+
+## Gotchas
+
+- **⚠ Fixing the re-add price exposed a price-0 bug on the item page.** `handleAddItemToCart` used to reset `itemForCart` to price 0 / lease 0 / uuid `""`; the sync effect does not re-run, so a second click sent price 0. The old merge hid it by keeping the line's price. Fixed on `TRUE-82729`: reset quantity only.
+- **⚠ The old merge bug was old, not a regression** — present since at least 2025-10 (`8c3ad44c`). It surfaced in QA after `TRUE-82427` made the item page send the refetched price (CodeRabbit, PR #376). `TRUE-81382` never touches the cart store.
+- The inactive-item guard also lives in `addItem` — see [inactive-item purchase gating](./inactive-item-purchase-gating.md#3-the-store-is-the-choke-point-not-the-buttons).
+
+## Change history
+- 2026-10-19 — Created. Re-add takes the new price/lease/Item (keeps line uuid, sums quantity); edit-order mode keeps the saved price (decision); item page no longer resets price to 0 after add; first cart store unit tests. TRUE-82729 (`c2b756a8`, pending merge). (tcox)
+
+## Related
+
+- [catalog-cache-freshness](./catalog-cache-freshness.md)
+- [inactive-item-purchase-gating](./inactive-item-purchase-gating.md)
+- [cart-bundle-submission-and-identity](./cart-bundle-submission-and-identity.md)
+- [cart-order-total-computation](./cart-order-total-computation.md)

package/knowledge/2.0/apps/toga2-commerce/features/catalog-cache-freshness.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-10-13
+updated: 2026-10-19
 owners: ["bala", "apeterson", "tcox"]
 files:
   - toga2-commerce/src/lib/queryClient.ts
@@ -31,6 +31,7 @@ files:
   - toga2-commerce/src/pages/BundleView/hooks/applyBundleFormatting.ts
   - toga2-commerce/src/pages/GetSupport/GetSupportPage.tsx
 related:
+  - ./cart-add-item-line-merge.md
   - ./inactive-item-purchase-gating.md
   - ./force-logout-on-deployment.md
   - ./sso-redirect-and-session-gating.md
@@ -90,7 +91,7 @@ A change reaches the shopper on: navigating to the page (mount), refresh / fresh
 
 Limits to state to the business:
 
-1. **Prices already in the cart do not update** — the cart is Zustand + `localStorage`, not React Query.
+1. **Prices already in the cart do not update** — the cart is Zustand + `localStorage`, not React Query. Re-adding the item refreshes its line price on `TRUE-82729` (not in edit-order mode) — see [cart addItem line merge](./cart-add-item-line-merge.md).
 2. **Alt-tabbing to another application is not a focus event** — see [frontend standard §4](../../../standards/frontend.md).
 3. **On a cold load the old value paints first** from `localStorage["commerce"]`, then swaps.
 
@@ -109,8 +110,7 @@ Limits to state to the business:
 
 - No loop: `selectedItem` is view-model state, and React Query structural sharing keeps its reference when data is unchanged.
 - Never add `itemToAddToCart` as a dependency — it is rebuilt every render.
-- **Open:** after Add to Cart, `handleAddItemToCart` resets `itemForCart` to price `0` / uuid `""` until `selectedItem` or currency changes; a second click in that window can add the item at price 0. Fix direction: rebuild price/lease from `itemToAddToCart` inside the reset.
-- **Open:** `addItem` in `src/stores/useCartStoreZu.ts` keeps the existing cart line's fields when the same item uuid is added again and only increments quantity, so re-adding after a price change keeps the old price on the whole line (CodeRabbit, PR #376). Fix direction: refresh the item fields in the existing-uuid branch. Out of scope for `TRUE-82427` (cart is Zustand, a stated limit).
+- The re-add-keeps-old-price and second-click-price-0 bugs are fixed on `TRUE-82729` (pending merge) — see [cart addItem line merge](./cart-add-item-line-merge.md).
 
 ### Opting a single query out — `staleTime: 0` + `gcTime: 0` is not enough
 
@@ -183,6 +183,7 @@ Pinned 2026-09-03 on `TRUE-81610`.
 - **`AuthLayout` never remounts**, so `refetchOnMount` fires once per session for queries it owns.
 
 ## Change history
+- 2026-10-19 — The two open item-page Add to Cart bullets closed by `TRUE-82729`; moved to [cart addItem line merge](./cart-add-item-line-merge.md). (tcox)
 - 2026-10-13 — `TRUE-82427` (`93f12265`, pending merge): per-query `staleTime` / `refetchOnWindowFocus: false` overrides removed, focus refetch on app-wide, guard's explicit opt-in removed, Home refetch fix, item-detail Add to Cart uses refetched price (and rebuilds on currency id change), Home refetch reapplies the submitted search (CodeRabbit fixes `61e4ffd9`, `e5eca52f`), 81382 merge resolution corrected; four other refetch-ignoring pages logged as open. Countries + 5-min login queries left out of scope. 30s heavy-query shape superseded. (tcox)
 - 2026-10-08 — Bundle queries uncached + excluded from persistence (TRUE-81382); branch map of the two persistence filters; buster live on `_production`. (tcox)
 - 2026-10-01 — Global default already `staleTime: 0`; per-query 24h overrides inventoried; ticket scope agreed. (apeterson)

package/knowledge/2.0/apps/toga2-commerce/workflows/local-development-hosts.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: workflow
 status: active
-updated: 2026-10-08
+updated: 2026-10-19
 owners: [apeterson, tcox]
 files:
   - toga2-commerce/vite.config.ts
@@ -32,8 +32,9 @@ The tenant is resolved from `window.location.hostname`, and api2 checks the requ
 
 - **⚠ `npm run sandbox-client` dies with `getaddrinfo ENOTFOUND`** until `client.sandbox.togacommerce` has its own hosts entry.
 - **⚠ A missing hosts entry looks like an auth bug.** The symptom is an instant redirect to `/login`, not a network error.
-- **⚠ `npm run dev` talks to beta, not sandbox-client.** `.env.development` sets `VITE_API = https://api.beta.togahub.com/v2`. A DB error seen locally (e.g. 1054 `Unknown column 'isOpen'` on `SalesOrderItems`, 2026-10-08) is beta's schema — check the request host before reading another environment's DB or `Logs_<Tenant>.Api`.
+- **⚠ `npm run dev` and the tenant scripts (`npm run compass`, …) talk to beta, not sandbox-client.** `.env.development` sets `VITE_API = https://api.beta.togahub.com/v2`. A DB error seen locally (e.g. 1054 `Unknown column 'isOpen'` on `SalesOrderItems`, 2026-10-08) is beta's schema — check the request host before reading another environment's DB or `Logs_<Tenant>.Api`.
 
 ## Change history
+- 2026-10-19 — Tenant dev scripts (`npm run compass`) also hit beta. (tcox)
 - 2026-10-08 — Added: local dev API target is beta. (tcox)
 - 2026-09-25 — Documented after tracing "cannot sign in locally" to the Origin/`Core.Domains` check. (apeterson)

package/knowledge/2.0/apps/toga2-commerce/workflows/unit-testing-vitest.md

@@ -6,16 +6,18 @@ project: TOGa Commerce
 client: shared
 type: workflow
 status: active
-updated: 2026-09-22
-owners: [apeterson]
+updated: 2026-10-19
+owners: [apeterson, tcox]
 files:
   - toga2-commerce/vitest.config.ts
   - toga2-commerce/package.json
   - toga2-commerce/src/lib/session.test.ts
   - toga2-commerce/src/api/refreshAuthTokens.test.ts
+  - toga2-commerce/src/stores/useCartStoreZu.test.ts
 related:
   - ./cypress-testing.md
   - ../features/sso-redirect-and-session-gating.md
+  - ../features/cart-add-item-line-merge.md
 ---
 
 How to run and write unit tests in commerce (vitest + jsdom), and how to verify a change actually compiles without tripping the build-mode trap.
@@ -23,16 +25,18 @@ How to run and write unit tests in commerce (vitest + jsdom), and how to verify
 ## Steps
 
 1. Run the suite: `npm test` (watch: `npm test:watch`). Config is `vitest.config.ts`, environment `jsdom`.
-2. Name the file next to its subject: `src/lib/session.test.ts`, `src/api/refreshAuthTokens.test.ts`.
+2. Name the file next to its subject: `src/lib/session.test.ts`, `src/api/refreshAuthTokens.test.ts`, `src/stores/useCartStoreZu.test.ts` (Zustand store). Test names are snake_case `test_…`.
 3. **Prove the test fails on the pre-fix code first.** Reverting `hasSession` turned 5 red; removing the single-flight and identity guards turned 3 red. A regression test that was never seen red proves nothing.
 4. Test a race with a **held-open promise you resolve by hand**, never real timing — that is what makes the refresh tests deterministic.
 5. Verify a build compiles with `npx vite build --mode development` (cheap), then read the trap below before trusting any `DEV`-gated path.
 
 ## Gotchas
 
+- **⚠ `npm run test` fails with `vitest: command not found` on a stale `node_modules`.** vitest/jsdom are in `devDependencies` but not installed until you run `npm install`.
 - **⚠ `import.meta.env.DEV` comes from `NODE_ENV`, not `--mode`.** `vite build` pins `NODE_ENV=production`, so a `DEV`-gated code path is **unreachable in every deployed mode** — including `--mode development`. Never gate behaviour a deployed build needs on `DEV`.
 - **⚠ Commerce's production build script is plain `vite build` with no `--mode`,** so `MODE` is `"production"`. Anything keyed on `MODE` (e.g. the SSO `Environments.slug` lookup) resolves to `PRODUCTION` there.
 - Commerce had **no** unit harness before 2026-09-22 — Cypress only ([cypress-testing](./cypress-testing.md)). Put browser/route behaviour in Cypress; put pure logic and races in vitest.
 
 ## Change history
+- 2026-10-19 — First cart store test (`useCartStoreZu.test.ts`, 4 tests); stale `node_modules` gotcha. TRUE-82729. (tcox)
 - 2026-09-22 — Created. vitest + jsdom added to commerce with 19 tests over `hasSession` and the token refresh. TRUE-81991 (`e546db3d`). (apeterson)

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

@@ -5,7 +5,7 @@
 | [TOGa Blox 2.5 — Architecture](architecture.md) | Shared React+TS SOURCE library for the new platform apps (new platform apps first; replaces toga-blox for all apps over time); read the ADR for full detail, not |
 | [Contact primary email/phone save (updateContactChannels) — table calls only](features/contact-channels-save.md) | How a contact edit form saves the contact's primary email and phone without nested writes; use it (do not rebuild it) in any app that edits a contact's email/ph |
 | [Money formatting (useSessionCurrency / formatMoney / useFormatMoney)](features/money-formatting.md) | The one money formatter for every platform app (session currency + session language via Intl); open before showing any money amount or adding a money column. |
-| [Old blox (toga-blox) straight port inside toga25-blox](features/old-blox-port.md) | Old `@agilant/toga-blox` code copied unchanged into toga25-blox (blox-v1 layer); open before touching any old component, its checks/config, or merging Storybook |
+| [Old blox (toga-blox) port into toga25-blox — rewrite, pixel-identical](features/old-blox-port.md) | Old `@agilant/toga-blox` code in toga25-blox: interim straight copy being rewritten piece by piece, same names/props/look; open before touching any old componen |
 | [Shell GlobalSearch, NotificationBell, NotificationsInbox (@toga/blox/shell)](features/shell-search-and-notifications.md) | Shared app-shell header search + notifications for every platform app; open when wiring search or the bell into an app, or changing search timing/keys. |
 | [GitHub Actions → AWS role via OIDC (trust policy + sub claim)](workflows/github-actions-aws-oidc-role.md) | How a GitHub Actions job assumes an AWS IAM role with OIDC, and the `sub` claim trap; open before creating or debugging any GitHub-to-AWS role ("Not authorized |
 | [Moving an old app from @agilant/toga-blox onto toga25-blox](workflows/moving-an-old-app-onto-toga25-blox.md) | Planned steps to switch an old app off the `@agilant/toga-blox` npm package onto toga25-blox source with zero import edits; open before moving any old app. |

package/knowledge/2.0/apps/toga25-blox/architecture.md

@@ -22,7 +22,7 @@ Shared React+TS SOURCE library for the new platform apps (new platform apps firs
 **Critical rules:**
 - **Reuse order:** an existing `toga25-blox` piece → a piece already built in another
   new-platform app (promote it to blox) → only then build new. Never duplicate.
-- **Moving an old app: rewrite onto toga25-blox pieces — never port old blox code wholesale.** Old blox has 3 table engines and 3 select stacks; copying them carries that over.
+- **Moving an old app: rewrite onto toga25-blox pieces — never port old blox code wholesale.** Old blox has 3 table engines and 3 select stacks; copying them carries that over. The rewrite must be invisible to old apps: same export names, props and pixel-identical look (tcox, 2026-10-13) — see [old-blox-port](features/old-blox-port.md).
 - **Import boundary:** apps may import only `@toga/blox/<entry>` (the public entry barrel) —
   lint blocks deeper paths. Blox never imports app code.
 - **Layer order (nothing imports upward):** `lib` < `core` < `tenancy` < `theme` < `surface`

package/knowledge/2.0/apps/toga25-blox/features/old-blox-port.md

@@ -1,12 +1,12 @@
 ---
-title: Old blox (toga-blox) straight port inside toga25-blox
+title: Old blox (toga-blox) port into toga25-blox — rewrite, pixel-identical
 framework: "2.0"
 repo: toga25-blox
 project: TOGa Blox 2.5
 client: shared
 type: feature
 status: active
-updated: 2026-10-08
+updated: 2026-10-13
 owners: [tcox]
 files:
   - toga25-blox/src/index.ts
@@ -21,18 +21,23 @@ related:
   - ../workflows/moving-an-old-app-onto-toga25-blox.md
   - ../../toga-blox/architecture.md
 ---
-Old `@agilant/toga-blox` code copied unchanged into toga25-blox (blox-v1 layer); open before touching any old component, its checks/config, or merging Storybook onto it.
+Old `@agilant/toga-blox` code in toga25-blox: interim straight copy being rewritten piece by piece, same names/props/look; open before touching any old component, its checks/config, or merging Storybook onto it.
 
 ## Summary
 
-Old blox moves to toga25-blox as a **straight port, not a rewrite** (tcox, 2026-10-07). Only the delivery changes (git source, no npm); the code and its public names do not. Apps must keep compiling with zero import edits.
+**Corrected 2026-10-13 (tcox):** old blox is **REWRITTEN** into toga25-blox (Jeff's ADR "do not port wholesale" is intended), but the rewrite must be **invisible to old apps**. The straight copy committed on TRUE-81994 (`5901e1c`) is only the interim base and safety net; each piece is replaced by its rewrite behind the same name, and the copy is gone when the last piece is done.
 
 **Rules:**
-- Copy old code unchanged. Never rename exports, props, signatures, or return types — old apps across the org import them. New names are additive only.
-- No `legacy/` folder. Old code keeps its old layout.
-- Do not fix old bugs during the port; fix them later as separate, additive changes.
+- Rewrite every ported piece (including ones no app uses yet — they must be ready for later).
+- Keep the public surface identical: export names, prop names (incl. `*Classes` string props), defaults, signatures, return types. Old apps must compile and behave the same with zero import edits.
+- Keep the rendered look **pixel-identical** where old apps use it — no one should notice. Prove it with screenshot comparison against old blox before swapping a piece in.
+- No Tailwind inside rewritten pieces: CSS modules + tokens, with values matching what apps render today.
+- Names that also exist in new blox (e.g. `Badge`, `ToasterProvider`, `MultiSelect`, `useTableData`): extend the new piece additively so old usage keeps working.
+- Bugs found while rewriting are fixed (e.g. old `Header` two hamburgers).
+- No `legacy/` folder. Move apps one at a time, light users first: commerce → view → toga25-supply → togatech, BDR, talos. toga2-hub is retired and does not move; toga2-supply is mostly retired (one client may still use it) and stays on npm old blox until retired; toga2-view (2.0, no 2.5 version) is still in use and moves.
+- Target for "identical" = what each app shows today on its pinned old-blox version, proved per app. Decision record: ADR `docs/decisions/0002-old-blox-compatible-rewrite.md` in toga25-blox (needs Jeff's sign-off).
 
-A first attempt that rewrote Tooltip/Tabs/Avatar/InlineAlert in new-blox style with renamed props was thrown away for breaking these rules.
+A 2026-10-07 attempt that rewrote Tooltip/Tabs/Avatar/InlineAlert with **renamed props** was thrown away — renaming is what broke the rule, not rewriting.
 
 ## How it works
 

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -19,7 +19,7 @@
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 decides on every navigation whether to bounce an anonymous visitor to their client's SSO IdP vs the local `/login` (useAuthenticationFlow); open for SSO |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The FE consumer of the platform-wide Surface layer (DB-driven UI config via `GET /v2/surfaces/meta`) — hooks, registries, adapter seams, migration recipe, and t |
 | [TableView CSV export (generic, all pages)](features/tableview-csv-export.md) | Reusable export of any blox TableView to CSV (every page, not just the loaded rows); open before adding an Export button to a toga25-supply table. |
-| [Talos Integration in TOGa Supply](features/talos-integration.md) | TOGa Supply embeds a surface-gated blox Talos panel using the current Supply user's bearer; open for assistant discovery, streaming, frontend lifecycle gaps or |
+| [Talos Integration in TOGa Supply](features/talos-integration.md) | TOGa Supply embeds a surface-gated blox Talos panel using the current Supply user's bearer (refreshed by `talosFetch`); open for assistant discovery, streaming, |
 | [Toolbar button chrome (ToolbarButton) — and why blox BaseButton can't be resized from the theme](features/toolbar-button-chrome.md) | toga25-supply's own ToolbarButton chrome (pill/chip, both pinned 27px) for page-toolbar buttons, because blox `BaseButton` sizes are un-themeable literals; open |
 | [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders vertical — list + record modal + Create modal, built surface-first from nothing (NYCHH-only today); the cleanest worked example of the curre |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How toga25-supply deploys to all its Amplify environments from one shared `amplify.yml` — branch `_<mode>` → Vite `--mode`; open when adding an environment or d |

package/knowledge/2.0/apps/toga25-supply/features/talos-integration.md

@@ -6,10 +6,13 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-10-08
-owners: [apeterson, akhokhani]
+updated: 2026-10-20
+owners: [apeterson, akhokhani, tcox]
 files:
   - toga25-supply/src/api/talos.ts
+  - toga25-supply/src/api/talosAuth.ts
+  - toga25-supply/src/api/talosConfig.ts
+  - toga25-supply/src/api/apiBaseUrl.ts
   - toga25-supply/src/hooks/useTalosSession.ts
   - toga25-supply/src/hooks/useTalosThreads.ts
   - toga25-supply/src/hooks/useTalosSurface.ts
@@ -19,18 +22,21 @@ files:
   - toga25-supply/.env.production
 related:
   - ../../toga-blox/features/talos-assistant.md
+  - ../../toga-blox/features/api-client.md
   - ../../dbchanges2/features/surface-layer-schema.md
+  - ../../../../standalone/apps/talos-backend/features/client-integration-contract.md
+  - ../../../../standalone/apps/talos-backend/features/auth-and-access-control.md
   - ../../../../standalone/apps/talos-backend/workflows/toga-supply-client-onboarding.md
   - ../../../../standalone/apps/talos/features/chat-frontend.md
   - ../../../../clients/nychh/features/talos-assistant-enablement.md
   - ../../../../clients/compass-usa/features/talos-supply-assistant.md
 ---
 
-TOGa Supply embeds a surface-gated blox Talos panel using the current Supply user's bearer; open for assistant discovery, streaming, frontend lifecycle gaps or tenant enablement.
+TOGa Supply embeds a surface-gated blox Talos panel using the current Supply user's bearer (refreshed by `talosFetch`); open for assistant discovery, streaming, token refresh/401s, where Talos can be tested, frontend lifecycle gaps or tenant enablement.
 
 ## Summary
 
-`AppLayout` hosts the launcher and controlled panel; one Supply-owned `TalosStreamProvider` wraps LangGraph SDK `useStream`. Blox is UI only. The shared `talos-assistant` Surface is seeded off and granted per tenant; a provisioned backend assistant does not establish that a customer's panel is enabled.
+`AppLayout` hosts the launcher and controlled panel; one Supply-owned `TalosStreamProvider` wraps LangGraph SDK `useStream`. Blox is UI only. Every Talos request goes through app-local `talosFetch`, which refreshes the api2 bearer (the blox axios interceptor covers api2 calls only). The shared `talos-assistant` Surface is seeded off and granted per tenant; a provisioned backend assistant does not establish that a customer's panel is enabled.
 
 ## How it works
 
@@ -38,12 +44,24 @@ TOGa Supply embeds a surface-gated blox Talos panel using the current Supply use
 
 Use the locally saved `origin/_production` source, not a stale working clone. The October 7 survey inspected Supply commit `bb35181`: React 18.3, Vite 7, LangGraph SDK `^1.10.0` and blox `1.1.4-production.196`. `.env.production` is tracked and sets `VITE_TALOS_API=https://api.togaiq.com`; non-production env files target `https://api.beta.togaiq.com`. There is a production backend.
 
-`src/api/talos.ts` is the only env read chokepoint. Browser requests go directly to Aegra using the current Supply access token and real browser Origin; there is no token exchange or Next proxy. Aegra's TogaHub auth resolves the exact JWT client slug into the Talos control plane; `/v2/users/me` supplies persona-linked AI-model slug grants. The platform MCP receives that same user's bearer and trusted frontend routing context; api2 remains the business-record/field authorization authority.
+Env reads (TRUE-82954): `src/api/talosConfig.ts` is the only `VITE_TALOS_API` read (plus `isTalosOrigin`); `src/api/apiBaseUrl.ts` is the only `VITE_API` read (`api.ts` imports it). Both sit outside the blox barrel, so non-axios code and Vitest can use them — the barrel pulls `dist/global.css` and fails Vitest with `Unknown file extension ".css"`.
+
+Browser requests go directly to Aegra with the current Supply access token and real browser Origin; there is no token exchange or Next proxy. Aegra's TogaHub auth resolves the exact JWT client slug into the Talos control plane; `/v2/users/me` supplies persona-linked AI-model slug grants. The platform MCP receives that same user's bearer and trusted frontend routing context; api2 remains the business-record/field authorization authority.
 
 `useTalosSession` requires `isAuthenticated`, not merely a token (logged-out public tokens exist). Assistant query keys use user UUID, never the token: React Query cache is persisted locally. Query state produces disabled/connecting/ready/error; keep it a non-Suspense query so reconnect does not unmount the composer.
 
 `GET /assistants?limit=100&offset=0` discovers the client assistant. Prefer `metadata.customer_facing===true`, otherwise use the list, choose first, and warn on multiple candidates. Never pin an assistant ID in env. GET carries no body or unnecessary JSON Content-Type. HTTP status logs distinguish rejected identity/tenant/entitlement from absent configuration.
 
+### Bearer and refresh (`talosFetch`)
+
+`src/api/talosAuth.ts` (TRUE-82954, branch `TRUE-82954`, not merged to `_production` as of 2026-10-20). Used by the REST helpers in `talos.ts` (they take no token parameter) and by `useStream` through module-scope `callerOptions: { fetch: talosFetch }`. Keep that object at module scope: an inline options/`defaultHeaders` object rebuilds the SDK Client every render, and a mount-time header never refreshes.
+
+1. Read the token from localStorage on every request, and only when the `user` key exists (otherwise it is the blox public token).
+2. Token within 60 s of JWT `exp` → refresh first with blox `refreshAccessToken(apiBaseURL)` (deep import `@agilant/toga-blox/dist/api/auth.js`), single-flight. No refresh when `apiBaseURL` is empty.
+3. 401 → refresh and resend **once**, only if the sent token was expiring or the body `message === "Token expired"`, and only for string/empty bodies. Safe because Aegra auth runs before any route, so a 401 created no run or message. Other 401s and every 403 are returned as is.
+4. Refresh fails → blox `performLogout()` (same as the axios interceptor; `api.ts` passes no `onLogout`). Dead token and failed refresh → logout without sending.
+5. Not signed in, or URL not on the Talos origin → return a synthetic 401 `Response`, never throw: the SDK AsyncCaller retries thrown errors 4x but never retries 401/403. The bearer is only sent to the Talos origin.
+
 ### Surface and provider lifecycle
 
 `useTalosSurface` finds a `featureEnabled` element in the `talos-assistant` bundle; missing/loading/failed/no-marker means disabled. Its `suggestion` element owns the whole ordered chip row. `config.items` has label/prompt/icon; prompt falls back to label. Invalid items are skipped, while a visible empty row is permitted.
@@ -54,10 +72,16 @@ The inspected implementation shows final-answer outcomes and suppresses final-an
 
 ### Backend contract versus inspected gaps
 
-The intended embedded-chat contract requires explicit server cancellation, persisted `/transcript` reload, run-ID rejoin with replay cursor, meaningful terminal-state handling, feedback and refreshed bearer retry. In the inspected production provider, Stop calls only `stream.stop()`; the dedicated cancellation helper is not wired. The saved Compass handoff also identified missing persisted transcript reload and run-ID rejoin. Treat these as release gaps, not finished behavior.
+The intended embedded-chat contract ([client integration contract](../../../../standalone/apps/talos-backend/features/client-integration-contract.md)) requires explicit server cancellation, persisted `/transcript` reload, run-ID rejoin with replay cursor, meaningful terminal-state handling, feedback and refreshed bearer retry. Bearer refresh/retry is built (above). Still open: Stop calls only `stream.stop()` — the dedicated cancellation helper is not wired; the saved Compass handoff also found missing persisted transcript reload and run-ID rejoin. Treat these as release gaps, not finished behavior.
 
 The backend assistant is `toga-supply` on `deep_agent`, with user-bearer `toga-platform` tools and tenant-specific persona/BLP. Compass and NYCHH backend deployments existed in the dated survey; neither tenant's current production Surface grants were read from Core/Client DB during that survey. See their client pages for exact evidence.
 
+### Where Talos can be tested (verified 2026-10-20)
+
+- **Local dev** (`npm run nychh`, mode `development`): `.env.development` / `.env.development.local` set no `VITE_TALOS_API`, so the panel shows "unavailable".
+- **sandbox-client** (`https://nychh.client.sandbox.togasupply.com`, Amplify branch `_sandbox-client`, `.env.sandbox-client`): `VITE_TALOS_API=https://api.beta.togaiq.com`, but tokens come from `api.client.sandbox.togahub.com`. Beta Talos validates through `TOGAHUB_API_URL=https://api.beta.togahub.com/v2/users/me` (talos-backend `.env.beta`), which rejects them: `GET /assistants` → 401 `"Token expired"` with 43 min left on the token. Panel: "Talos is unavailable right now." Beta health (200) and CORS are fine. Pre-existing env problem, not fixed.
+- So a real browser test needs a Talos whose `TOGAHUB_API_URL` is the same api2 that issued the Supply build's tokens. Until then, Talos auth changes are verified by unit tests only (`talosAuth.test.ts`, `talos.test.ts`, `TalosStreamProvider.test.tsx`).
+
 ### Hosting evidence
 
 As of 2026-10-07, production Supply used Amplify app `d3v9s1i7kge4ll` and its CloudFront distribution. `*.beta.togasupply.com` used a different Amplify app/repo, `toga2-supply`, not this production 2.5 source. Confirm hostname→build mapping before reproducing a version-specific failure.
@@ -66,7 +90,10 @@ As of 2026-10-07, production Supply used Amplify app `d3v9s1i7kge4ll` and its Cl
 
 - Surface visibility, active `/users/me` slug grant, control-plane tenant, assistant capability assignments and MCP data ACL are independent gates. Do not repair a denied user with an admin/service token.
 - A backend assistant with successful historical runs is not proof of a production panel launch. Read the actual Surface bundle as the intended user.
+- Aegra `"Token expired"` does not prove expiry: it is returned for **any** TogaHub `/users/me` 401, including a token from a different api2 environment (see sandbox-client above). Check the token's `exp` and `iss` before debugging refresh. Error bodies are `{error, message, details}`, not FastAPI `{detail}` ([auth](../../../../standalone/apps/talos-backend/features/auth-and-access-control.md)).
+- Do not call Talos with plain `fetch` or a token captured at render/mount — it goes stale after the api2 token expires and chat fails. Use `talosFetch`.
 - SDK Stop closes browser streaming; it is not a verified server-run cancellation in the inspected implementation.
+- The SDK retries 5xx/network errors on `POST /runs/stream` (could duplicate a run) — open follow-up, see the [client integration contract](../../../../standalone/apps/talos-backend/features/client-integration-contract.md) gotchas.
 - The mapper hides tools/HITL. Keep this customer-facing read-only assistant within its declared boundary; richer decision UI requires deliberate contract work.
 - Stable query keys must not include credentials. Caches and logs can persist long after a token changes.
 - Code comments calling Aegra “TOGa IQ” are legacy naming. Talos is the backend agent platform; TOGa IQ is the separate management UI.
@@ -74,7 +101,10 @@ As of 2026-10-07, production Supply used Amplify app `d3v9s1i7kge4ll` and its Cl
 ## Related
 
 - [talos assistant](../../toga-blox/features/talos-assistant.md)
+- [blox api client](../../toga-blox/features/api-client.md)
 - [surface layer schema](../../dbchanges2/features/surface-layer-schema.md)
+- [client integration contract](../../../../standalone/apps/talos-backend/features/client-integration-contract.md)
+- [auth and access control](../../../../standalone/apps/talos-backend/features/auth-and-access-control.md)
 - [toga supply client onboarding](../../../../standalone/apps/talos-backend/workflows/toga-supply-client-onboarding.md)
 - [chat frontend](../../../../standalone/apps/talos/features/chat-frontend.md)
 - [talos assistant enablement](../../../../clients/nychh/features/talos-assistant-enablement.md)
@@ -82,4 +112,5 @@ As of 2026-10-07, production Supply used Amplify app `d3v9s1i7kge4ll` and its Cl
 
 ## Change history
 
+- 2026-10-20 — Added `talosFetch` bearer refresh + one-time 401 resend; env reads moved to `talosConfig.ts` / `apiBaseUrl.ts`; recorded why Talos cannot be tested locally or on sandbox-client (TRUE-82954) (tcox).
 - 2026-10-08 — Reconciled local source and dated 2026-10-07 research into the canonical KB (akhokhani).

package/knowledge/2.0/apps/toga25-supply/workflows/amplify-deployment.md

@@ -6,11 +6,11 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-10-01
+updated: 2026-10-20
 owners: [jcardinal, apeterson, tcox]
 files:
   - toga25-supply/amplify.yml
-  - toga25-supply/src/api/api.ts
+  - toga25-supply/src/api/apiBaseUrl.ts
   - toga25-supply/src/hooks/useAuthenticationFlow.ts
   - toga25-supply/vite.config.ts
   - toga25-supply/package.json
@@ -79,7 +79,7 @@ this settled TRUE-82138 in one step on 2026-09-29 (bundle carried all three stri
 
 **Why the exact `--mode` matters at runtime.** `import.meta.env.MODE` (the `--mode` value) is baked into the bundle and read at **runtime** by the auth flow: `useAuthenticationFlow.ts` sends it as the `environment` value to the `/domains` API endpoint. A generic `vite build` (mode `production`) therefore ships the wrong **environment identity**, not just the wrong URL. Each deployed environment must be built with its exact `--mode` string. Environments differ only by `VITE_API` base URL (per `.env.<mode>`). Per-**client** behavior is separate and resolves at **runtime by hostname** (`useHostnameStore` / `clientSlug`), not at build time — a multi-client shared build, so no client-specific branches.
 
-**API base-URL resolution (`api.ts`).** axios `baseURL` resolves as:
+**API base-URL resolution (`src/api/apiBaseUrl.ts`; was in `api.ts` before TRUE-82954).** The api2 base URL (axios `baseURL`, also used by `talosFetch` for token refresh) resolves as:
 
 ```
 import.meta.env["VITE_API_" + hostname.split(".")[0].toUpperCase()] || import.meta.env.VITE_API
@@ -123,6 +123,7 @@ Worse, **`.env.development` is git-TRACKED**, so developers keep flipping it to
 - **The audit that catches the blox defects — reusable for any blox consumer.** Enumerate the shared lib's `peerDependencies` from `node_modules/<pkg>/package.json`, then check each one for a **real directory** (not a symlink passthrough) in the *app's* `node_modules`. Do this whenever a repo has ever been developed against a linked local checkout.
 
 ## Change history
+- 2026-10-20 — `VITE_API` read moved from `api.ts` to `src/api/apiBaseUrl.ts` (TRUE-82954) (tcox).
 - 2026-10-01 — Added the "prove the change reached the environment" bundle-fetch check (curl the
   `/assets/index-<hash>.js`, grep for a unique string, read `last-modified`), and recorded the
   `amplify.yml` deletion recurrence on `_sandbox-client` (commit `37f7aeb`, 2026-09-29) carried in by a

package/knowledge/2.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-10-18
+updated: 2026-10-20
 owners: [jcardinal, apeterson, tcox]
 files: []
 related:
@@ -424,8 +424,11 @@ memory.
   `searchForWorkspaceRoot(process.cwd())`, never a hardcoded `path.resolve(__dirname)`, or you
   silently narrow what the dev server will serve. Mechanics:
   [local-link-into-a-consumer-app](../apps/toga-blox/workflows/local-link-into-a-consumer-app.md) §2c.
-- **MUST: one env-read chokepoint.** Read `VITE_API` in exactly **one** module (see §17). Verified:
-  both apps read it (plus a per-host override) only in `src/api/api.ts`.
+- **MUST: one env-read chokepoint per variable.** Read each `VITE_*` URL in exactly **one** small
+  module that does not import the blox barrel (see §17), so non-axios code and Vitest can import it
+  (the barrel pulls `dist/global.css` → `Unknown file extension ".css"`). desk: `VITE_API` in
+  `src/api/api.ts`. supply (TRUE-82954): `VITE_API` in `src/api/apiBaseUrl.ts` (imported by `api.ts`),
+  `VITE_TALOS_API` in `src/api/talosConfig.ts`.
 - **SHOULD: ESLint flat config**, verified identical in both apps:
 
   ```js
@@ -543,6 +546,8 @@ const instance = createAxiosInstance({ baseURL, onLogout });
 setAxiosInstance(instance);
 ```
 
+(supply, TRUE-82954: `baseURL` is imported from `./apiBaseUrl` instead of computed inline — same expression, see §11.)
+
 blox's API helpers **throw "No axios instance registered"** if any data hook or component runs
 first. The order is: create → set → *then* mount. (See `../apps/toga-blox/features/api-client.md`.)
 
@@ -593,7 +598,7 @@ per-environment blox channel, `--legacy-peer-deps`, Node/heap — is owned by
 
 The one code-side convention worth stating: both apps read **`VITE_API`** — plus an optional
 per-host **`VITE_API_<FIRST-HOSTNAME-SEGMENT>`** override — in **exactly one module**
-(`src/api/api.ts`, §14).
+(desk: `src/api/api.ts`; supply: `src/api/apiBaseUrl.ts`, imported by `api.ts` — §11, §14).
 
 ## 18. Client-side multi-tenant isolation — **MUST** *(cto-added)*
 

package/knowledge/INDEX.md

@@ -22,7 +22,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 111 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 91 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 92 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 27 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/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)
@@ -30,7 +30,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **apiproxy** (API Proxy) — 1 doc(s) → [2.0/apps/apiproxy/INDEX.md](2.0/apps/apiproxy/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 32 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 33 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 26 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga25-iq** (TOGa IQ) — 1 doc(s) → [2.0/apps/toga25-iq/INDEX.md](2.0/apps/toga25-iq/INDEX.md)
 - **toga25-desk** (TOGa Desk 2.5) — 1 doc(s) → [2.0/apps/toga25-desk/INDEX.md](2.0/apps/toga25-desk/INDEX.md)

package/knowledge/clients/compass-canada/INDEX.md

@@ -8,6 +8,7 @@
 | [Compass Canada — Item-Fulfillment TableViews (dead-Core-id 500, rebuilt onto the USA shape)](features/item-fulfillment-tableviews.md) | 2.0 | Why Compass Canada's item-fulfillment TableViews 500'd on dead Core ids and how they were rebuilt onto the USA shape; open when a Canada TableView 500s on /meta |
 | [Compass Canada: PO-to-vendor transmission monitor (Monitor/Compass/CompassCanadaPurchaseOrderTransmissionsToVendors)](features/oneuptime-po-transmissions-to-vendors-monitor.md) | 2.0 | worker2 OneUptime push monitor for Compass Canada POs the 1.0 cron has not yet sent to the vendor (Grand & Toy), plus how the Canada PO transmit cron differs fr |
 | [Compass Canada — order fulfillment status (standard base rule, no Canada override)](features/order-fulfillment-status-per-line.md) | 2.0 | Canada-specific facts for the shared Compass order fulfillment status (standard base rule since TRUE-79669); open before touching Canada order status or Canada |
+| [Compass Canada Persona Model (sector-granted vs hand-assigned)](features/persona-model.md) | 2.0 | Where each `Client_CompassCanada` persona comes from: PEOPLE cron (only "All"), sector `Locations_Personas`, or hand-assigned with nothing keeping it in step. |
 | [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |
 | [Copying a Compass USA user into the Canada tenant (cross-tenant hand-add)](workflows/copying-a-us-user-into-the-canada-tenant.md) | 2.0 | Giving a Compass **USA** person a login on the Canada TechHub portal: the guarded insert chain, the uuid role/persona mapping, and the worker2 guard that stops |
 | [Grand & Toy ASN Backfill (cXML replay + CSV-to-JSON)](workflows/grand-and-toy-asn-backfill.md) | 2.0 | How to recover Compass Canada shipments whose ASN never landed (cXML replay, CSV-to-JSON, or SQL line backfill); open when replaying a G&T outage or repairing a |

package/knowledge/clients/compass-canada/features/persona-model.md

@@ -0,0 +1,58 @@
+---
+title: Compass Canada Persona Model (sector-granted vs hand-assigned)
+framework: "2.0"
+project: _Underscore
+client: compass-canada
+type: client-feature
+status: active
+updated: 2026-10-20
+owners: [bala]
+files:
+  - worker2/Worker/Client/Compass/PeopleFile.php
+  - "dbchanges2/Client_CompassCanada/2025-12-19 - Personas.sql"
+  - "dbchanges2/Client_CompassCanada/2026-01-16 - insert_locations_personas.sql"
+  - worker/crons/toga2/compasscanada/Imports2.0/create_persona.php
+related:
+  - ../profile.md
+  - ../../compass-usa/features/persona-model-and-levy-gating.md
+  - ../../../2.0/apps/_underscore/features/effective-persona-resolution.md
+  - ../workflows/copying-a-us-user-into-the-canada-tenant.md
+---
+Where each `Client_CompassCanada` persona comes from: PEOPLE cron (only "All"), sector `Locations_Personas`, or hand-assigned with nothing keeping it in step. Open before answering "who sees what" in Canada or adding a Canada persona.
+
+## Summary
+
+Prod `Client_CompassCanada` (verified 2026-10-20): **34 personas**, **5,484** active users. Canada has
+**no** Levy, Non-Levy or Corporate/Field logic; those are Compass USA only
+([US persona model](../../compass-usa/features/persona-model-and-levy-gating.md)). Persona ids mean
+different things per tenant (CA 24 = "ESFM - CGC", not Levy). Personas were created by
+`dbchanges2/Client_CompassCanada/2025-12-19 - Personas.sql` and the 1.0
+`worker/crons/toga2/compasscanada/Imports2.0/create_persona.php`.
+
+## How it works (three sources)
+
+| Source | Personas | Kept in step by |
+|---|---|---|
+| PEOPLE cron (`PeopleFile.php`, CA branch) | **All (1)** | Nightly cron |
+| `Locations_Personas` on sector nodes | Sector personas **2-26** and **30** | Location data. Sector nodes use two-digit `c_erpEntityId` codes (e.g. `05` Canteen, `11` Quebec, `17` / `24` Compass One) |
+| Hand-assigned in `Users_Personas` | Managers/VIPs (33), MacBooks (32), Admin Canada (31), Provisioning (29), CDL & Compass Network (28), WasteNot (27), Executive Assistance (34) | **Nothing.** No job adds or removes them |
+
+The effective set is the usual UNION (direct + own location + 5-hop sector), see
+[Effective persona resolution](../../../2.0/apps/_underscore/features/effective-persona-resolution.md).
+
+## Gotchas
+
+- **11 sector personas grant no kits at all:** 3, 4, 5, 6, 9, 10, 11, 12, 13, 23, 26. Users under those
+  sectors see only what "All" and any hand-assigned persona give them.
+- **Managers/VIPs (33) drifts from reality.** 984 users hold it (19 kits), but only **858 of 1,146**
+  users who manage someone have it. It is hand-assigned, so new managers never get it.
+- **Admin Canada (31)** carries the full catalogue (33 kits); its category gap is in the
+  [profile](../profile.md).
+- **The CA branch of `PeopleFile` only adds/removes "All"** (Levy rule kept verbatim, never fires in
+  Canada). The US-only VIP (35) and persona-30 branches are not tenant-gated; see the latent gaps in
+  the [US persona model](../../compass-usa/features/persona-model-and-levy-gating.md#persona-assignment-by-tenant).
+- `PeopleFile.php` has a literal SFTP credential in its class constants. Never paste its constants.
+
+## Change history
+- 2026-10-20 — Created from a read-only prod check (TRUE-82956): 34 personas / 5,484 users, the three
+  persona sources, 11 sector personas with no kits, Managers/VIPs (33) coverage gap. (bala)

package/knowledge/clients/compass-canada/profile.md

@@ -19,7 +19,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-10-18
+updated: 2026-10-20
 owners: [jcardinal, bala, tcox, apeterson, ajean, mhammontree, rgirish]
 files: []
 related:
@@ -28,6 +28,7 @@ related:
   - features/grand-and-toy-asn-import.md
   - workflows/grand-and-toy-asn-backfill.md
   - workflows/copying-a-us-user-into-the-canada-tenant.md
+  - features/persona-model.md
   - ../../2.0/apps/api2/features/cxml-shipnotice-gateway.md
   - ../compass-usa/features/approval-decision-flow.md
   - ../compass-usa/features/stranded-approval-reassignment.md
@@ -222,13 +223,9 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
 - **Storefront French localization** (labels, submenus, orders-for-others, Get Support illustration) is
   driven by the COMPASSCANADA FIELDS JSON; the registry language key is **`fr-CA`** (not `fr`). See
   [Client Fields](../../2.0/apps/toga2-commerce/features/client-fields.md).
-- **Canada has no Levy sector — and its PEOPLE-cron persona logic is deliberately unchanged.** The
-  2026-08-06 Compass USA persona refactor split the US logic in
-  `worker2/Worker/Client/Compass/PeopleFile.php` by tenant; the **CA branch is preserved verbatim**
-  (Levy users lose persona 1, non-Levy users gain it; there is no Non-Levy persona). Verified
-  unreachable by the Levy path: `Client_CompassCanada` has **zero** locations with
-  `c_erpEntityId = 'K00000'` and **zero** users with either hardcoded Levy personnel number. See
-  [Persona Model & Levy-Sector Gating](../compass-usa/features/persona-model-and-levy-gating.md).
+- **Personas: 34, from three sources** (PEOPLE cron only manages "All"; sector personas via
+  `Locations_Personas`; the rest hand-assigned with nothing keeping them in step). No Levy, Non-Levy
+  or Corporate/Field logic in Canada. See [Canada Persona Model](features/persona-model.md).
 - **Known production defect — My Account renders a blank Persona field.** Canada is the only tenant
   with `languageSwitcher.isEnabled = true`, and its "no saved language" login branch (taken by ~98%
   of logins — only **69 of 4,655** active users have a stored language) was the one `setUser` call in

package/knowledge/clients/compass-usa/INDEX.md

@@ -5,7 +5,7 @@
 | [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass sales-order approval-decision / notification flow — approval+CC email lists, manager reassignment, settings-driven manager (VIP) auto-approve, EN/FR loc |
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | Compass USA ASN posting auto-creates the ItemFulfillment on the upstream SalesOrder and propagates tracking at every granularity; open when working ASN→IF creat |
 | [Compass Contact Email Resolution & Crossed `primaryContactEmailAddressId` Pointers](features/contact-email-resolution.md) | 2.0 | Any Compass code reading a contact's email must assert the email row belongs to that contact (~14% of pointers are crossed); open before reading Compass contact |
-| [Corporate vs Field laptop personas — the sector-52 split (designed, NOT built)](features/corporate-vs-field-laptop-personas.md) | 2.0 | Agreed design for splitting the Compass catalogue into a Corporate laptop and a field "laptop kit": attach Corporate at sector `J00000` via `Locations_Personas` |
+| [Corporate vs Field laptop personas (Levy/Compass x Corporate/Field, PEOPLE cron)](features/corporate-vs-field-laptop-personas.md) | 2.0 | LIVE since 2026-10-13 (TRUE-82667): `PeopleFile` gives every US user a Corporate or Field laptop persona (Levy and Compass halves) by cost center / sector `J000 |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" is a Unit-level Location keyed by `c_erpSystemEntityId` (NOT a `CostCenters` row), numeric-only since 2026-07-06; open for cost-center d |
 | [Compass isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md) | 2.0 | Why Compass storefront Qty-Fulfilled cells stay dead — `Items.isFulfillable` NULLs are structurally unreachable, some set values are wrong, and the type-derived |
 | [Compass Item Catalogs (Compass vs Agilant) & the Duplicate Items the NetSuite Sync Creates](features/item-catalogs-and-duplicate-items.md) | 1.0 | `Client_Compass.Items` is split across catalogs (Compass vs Agilant) and the NetSuite sync creates duplicate rows for one product; open first whenever a Compass |

package/knowledge/clients/compass-usa/features/corporate-vs-field-laptop-personas.md

@@ -1,90 +1,94 @@
 ---
-title: Corporate vs Field laptop personas — the sector-52 split (designed, NOT built)
+title: Corporate vs Field laptop personas (Levy/Compass x Corporate/Field, PEOPLE cron)
 framework: "2.0"
-project: _Underscore
+repo: worker2
+project: Worker
 client: compass-usa
 type: client-feature
-status: deferred
-updated: 2026-10-05
+status: active
+updated: 2026-10-20
 owners: [bala]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
+  - "dbchanges2/Client_Compass/2026-10-12a - PersonaCorporateField.sql"
 related:
   - ./persona-model-and-levy-gating.md
   - ./location-hierarchy-and-sectors.md
+  - ./cost-centers.md
   - ../workflows/persona-refactor-migration.md
+  - ../workflows/granting-persona-bundle-access.md
   - ../../../2.0/apps/_underscore/features/effective-persona-resolution.md
   - ../profile.md
 ---
-Agreed design for splitting the Compass catalogue into a Corporate laptop and a field "laptop kit": attach Corporate at sector `J00000` via `Locations_Personas`, assign Field in `PeopleFile`. Designed 2026-10-05, no code written. Open before building the field kit.
+LIVE since 2026-10-13 (TRUE-82667): `PeopleFile` gives every US user a Corporate or Field laptop persona (Levy and Compass halves) by cost center / sector `J00000`. Open before touching laptop kits, the corporate cost-center lists, or the four segment personas.
 
 ## Summary
 
-Compass confirmed the new **field laptop kit REPLACES the standard laptop** for non-corporate users;
-only admins see both. So the split is by **corporate vs not**, and corporate is a hierarchy question,
-not a flag — see [Location Hierarchy & Sectors](./location-hierarchy-and-sectors.md).
+Compass split the standard laptop into a **Corporate** kit and a cheaper **Field** kit. Field is the
+default; Corporate is decided by cost center (and, for Compass, by sector `J00000`). Four personas
+carry the kits, all assigned **directly in `Users_Personas`** by the nightly PEOPLE cron
+(`worker2/Worker/Client/Compass/PeopleFile.php`, commit `759a05c`, in `_production`). The one-time
+backfill was `dbchanges2/Client_Compass/2026-10-12a - PersonaCorporateField.sql`.
 
-Nothing is built. This doc records the agreed shape so the next session does not re-derive it.
+The earlier design (one `Locations_Personas` row on sector location 52) was **not** built.
 
-## How it works (the agreed design)
+## The four personas (prod `Client_Compass`, verified 2026-10-20)
 
-1. **Corporate persona.** Move the standard laptop bundle(s) out of **Non-Levy (persona 40)** into a
-   new **Corporate** persona, and attach it with a **single `Locations_Personas` row on sector
-   `J00000` (`Locations.id = 52`)**. Effective-persona resolution unions `Users_Personas`, the user's own
-   `Locations_Personas`, and their **sector's** (the 5-level walk), so every cost center under
-   `J00000` inherits it — including ones Compass adds on a later daily import.
-2. **Field persona.** It **cannot** use `Locations_Personas`: "everyone except sector 52" is not a
-   single location. Assign it in `worker2/Worker/Client/Compass/PeopleFile.php` as the default in
-   `Users_Personas`, skipped for anyone under `J00000` — mirroring the existing Levy branch.
-3. **Rejected alternative:** one `Locations_Personas` row per *other* sector (79 of them). It
-   silently misses any new sector Compass adds, which is the exact failure the feed is designed to
-   avoid.
-4. **No `isActive` filter is needed.** No inactive cost center under `J00000` has a single active
-   user, so attaching at the sector only ever reaches real people.
+| Persona | id | number | Kit | Active users |
+|---|---|---|---|---|
+| Levy Corporate | 41 | 43 | 189 LEVY - HP ZBOOK 8 | 244 |
+| Levy Field | 42 | 44 | 248 LEVY - Field Standard Laptop | 5,159 |
+| Compass Corporate | 43 | 45 | 187 Compass Standard HP ZBOOK 8 | 5,028 |
+| Compass Field | 44 | 46 | 247 Compass Field Standard Laptop | 65,447 |
 
-## Where the laptop bundles live (prod `Client_Compass`, verified 2026-10-05)
+- Kit **189 moved off Levy Purchaser (24)** and **187 off Non-Levy (40)**. Only those two moved.
+- Kit **249 NON COMPASS - Field Standard Laptop** sits on persona 5 (HTT and MITS team) and 12 (MITS
+  Team). MITS Team holds every kit, so it also has 247 and 248.
+- Ids and numbers differ (the migration header lists numbers 43-46). `PeopleFile` resolves all four
+  **by name** (`PERSONA_NAME_US_LEVY_CORPORATE` etc.). See the id/number table in
+  [Persona Model](./persona-model-and-levy-gating.md#the-persona-set-us).
 
-The standard laptop bundles sit in **persona 40 "Non-Levy"** (number 42) — not in persona 1, which is
-**Base** and carries only the 9 kits Levy also holds. See
-[Persona Refactor](../workflows/persona-refactor-migration.md) for the three-way split.
+## How it works
 
-| Bundle | Name | Note |
-|---|---|---|
-| 187 | Compass Standard HP ZBOOK 8 Laptop (Preferred) | |
-| 188 | Compass Hybrid HP Ebook 8 Flip (Travel) | `isActive = 0` |
-| 192 | HP PRO MINI 400 G9 | |
-| 195 | Compass Developer HP ZBOOK POWER | |
+`findSegmentPersonaIdsForUser()` runs for every US user on each PEOPLE run (existing and new users):
 
-**All four are attached to persona 12 "MITS Team" as well**, so the split must move/handle **both**
-personas — doing it on Non-Levy alone leaves MITS Team seeing the old laptop.
+1. **Levy half** when the user's effective persona set holds Levy Purchaser (24):
+   cost center in `LEVY_CORPORATE_COST_CENTERS` (33 values from Compass) -> Levy Corporate, else Levy Field.
+2. **Compass half** when the user should hold Non-Levy: location under sector `J00000` (Corporate
+   Indirect OH, `isLocationUnderSector()` walk, US only) **or** cost center in
+   `COMPASS_CORPORATE_COST_CENTERS` (10 values: 4018, 22772, 26963, 28184, 31335, 45781, 47258,
+   54188, 62230, 62937) -> Compass Corporate, else Compass Field.
+3. Cost center = `Users.c_erpEntityId` from the file. A user who moves cost center **swaps halves on
+   the next run** (insert the wanted one, delete the other three).
+4. A Levy user who also holds Non-Levy (Levy VIPs) gets **one of each** half.
+5. **Null-name guard:** until all four personas exist in that environment, nothing is added or
+   removed. That is what made "deploy worker2 first" safe.
 
-There is still **no `Locations_Personas` row for location 52**, so nothing inherits at that sector
-today. The table is already used this way for other sectors (e.g. Levy sector 55 → persona 24).
-
-**Open question — unanswered by the client:** which of **187 / 192 / 195** count as "the standard
-laptops" that stay corporate-only. Settle that before writing the migration.
+The effective set comes from `buildEffectivePersonaIds()`: direct `Users_Personas` + own-location +
+5-hop sector `Locations_Personas` (`findSectorLocationId()`) + Base, using **this run's** VIP/CDL
+flags (a user who just lost VIP drops it). Derived personas (Non-Levy and the four halves) are
+**removed** from that set, so a wrong grant cannot justify itself.
 
 ## Gotchas
 
-- **Never hardcode a persona id.** Resolve by name, exactly as `PeopleFile` does for `Non-Levy` —
-  ids differ per environment. See [Persona Model & Levy-Sector Gating](./persona-model-and-levy-gating.md).
-- **A persona grant is three tables** (`Personas_Bundles`, `Personas_Items`, `Personas_Assortments`),
-  not just bundles — see [granting a bundle](../workflows/granting-persona-bundle-access.md).
-- **The DB does not restrict what a persona sees** — the storefront front end is the only gate. A new
-  persona alone changes nothing until `toga2-commerce` filters on it.
-
-## Related
-- [Persona Model & Levy-Sector Gating](./persona-model-and-levy-gating.md)
-- [Location Hierarchy & Sectors](./location-hierarchy-and-sectors.md)
-- [Persona Refactor migration](../workflows/persona-refactor-migration.md)
-- [Effective persona resolution](../../../2.0/apps/_underscore/features/effective-persona-resolution.md)
+- **The rule lives in two places. Change one, change both:** `PeopleFile.php` and the
+  `2026-10-12a - PersonaCorporateField.sql` migration header/phases. The cron re-applies its copy
+  nightly, so drift silently undoes a manual fix.
+- **The cost-center lists are hardcoded and temporary.** Compass says a PEOPLE-file flag will replace
+  them. Until then a new corporate cost center needs a code change, not a DB row.
+- **Levy Corporate is by cost center only.** Levy's home office is the **district** `K9902`, not a
+  sector, so there is no sector walk for Levy. See [Location Hierarchy](./location-hierarchy-and-sectors.md).
+- **Never hand-add a half in `Users_Personas` or `Locations_Personas`.** The next run deletes a direct
+  row that does not match the rule. A location row still grants the half at read time, but the cron
+  never removes it, so those users end up holding both halves.
+- **The DB does not restrict what a persona sees**; the `toga2-commerce` storefront is the gate. A
+  grant is three tables. See [granting a bundle](../workflows/granting-persona-bundle-access.md).
+- `PeopleFile.php` has a literal SFTP credential in its class constants. Never paste its constants.
 
 ## Change history
-- 2026-10-05 — Created. Recorded the agreed corporate/field split (Corporate attached at sector
-  `J00000` via one `Locations_Personas` row; Field assigned in `PeopleFile` and skipped under
-  `J00000`; the 79-row per-sector alternative rejected) and the prod bundle locations verified the
-  same day: laptops 187 / 188 / 192 / 195 live in **Non-Levy (40)** and are also on **MITS Team
-  (12)**, and location 52 still has no `Locations_Personas` row. An earlier draft of this doc quoted
-  a **2026-09-15** persona read (persona 1 = "All", 23 bundles) as if it were current and called it a
-  conflict with the refactor doc — it was simply taken two days before the refactor went live on
-  2026-09-17. Removed; the refactor docs are correct. Nothing built. (bala)
+- 2026-10-20 — Rewritten from "designed, not built" to the shipped rule (TRUE-82667, worker2
+  `759a05c`, dbchanges2 `2026-10-12a`): four by-name personas assigned in `Users_Personas`, cost-center
+  lists + `J00000` walk, Field default, null-name guard, derived personas excluded from the effective
+  set. Prod counts verified 2026-10-20. The `Locations_Personas`-on-location-52 design was dropped. (bala)
+- 2026-10-05 — Created as a deferred design (Corporate at sector `J00000` via `Locations_Personas`,
+  Field in `PeopleFile`); laptop kits verified on Non-Levy (40) and MITS Team (12). (bala)

package/knowledge/clients/compass-usa/features/location-hierarchy-and-sectors.md

@@ -118,7 +118,7 @@ All of them are flagged Active and all have **zero users**. Drop them before any
 ## Related
 - [Cost Centers — Unit Locations, numeric-only policy](./cost-centers.md)
 - [Persona Model & Levy-Sector Gating](./persona-model-and-levy-gating.md)
-- [Corporate vs field laptop personas (deferred)](./corporate-vs-field-laptop-personas.md)
+- [Corporate vs field laptop personas (live, uses the `J00000` walk)](./corporate-vs-field-laptop-personas.md)
 - [Effective persona resolution](../../../2.0/apps/_underscore/features/effective-persona-resolution.md)
 
 ## Change history

package/knowledge/clients/compass-usa/features/persona-model-and-levy-gating.md

@@ -6,7 +6,7 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-10-09
+updated: 2026-10-20
 owners: [bala, ajean, mhammontree]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
@@ -43,22 +43,29 @@ below.
 
 ## The persona set (US)
 
-**The refactor is LIVE in prod since 2026-09-11** (three-way split, verified 2026-09-17 — see
-[Persona Refactor](../workflows/persona-refactor-migration.md)). Persona 1 is now named **Base**.
-
-| Persona | id | Meaning |
-|---|---|---|
-| Base (was "All") | **1** | The **9** kits Levy and non-Levy both hold (81, 82, 84, 85, 105, 115, 120, 165, 166), plus the 71 items / 11 categories Levy also holds. **Every US user holds it.** |
-| Levy Purchaser | **24** | Levy's own **5** kits: 189, 193, 213, 231, 242. |
-| Non-Levy | **resolved by name** — **id 40, number 42 in prod** | The other 14 persona-1 kits / 123 items / 3 categories. Granted to non-Levy users only. |
-| VIP | 35 | VIP add-on. Carries the manager auto-approve limit (`PersonaGlobalSettings` setting 18 = `'5000'`) — see [Approval-Decision Flow](approval-decision-flow.md). |
-| CDL (MacBook / Surface) | 30 | `@compassdigital.io` + VIP users. |
-
-**Never hardcode the Non-Levy id, and never assume it matches the number.** In prod it is **id 40**
-with **number 42** — the number is derived (`MAX(number)+1` under 100) because number 40 already
-belongs to "MyDining- KDS" (id 38). Earlier drafts variously claimed id 38 and id/number 40; both are
-wrong for prod. Every environment gets a different id, which is exactly what name-resolution protects
-against.
+Three-way refactor live since 2026-09-11 ([Persona Refactor](../workflows/persona-refactor-migration.md));
+Corporate/Field split live since 2026-10-13. Prod `Client_Compass` 2026-10-20: **43 personas** (id 33
+does not exist), **75,724** active users.
+
+| Persona | id | number | Meaning |
+|---|---|---|---|
+| Base (was "All") | **1** | | The **9** kits Levy and non-Levy both hold (81, 82, 84, 85, 105, 115, 120, 165, 166), plus the 71 items / 11 categories Levy also holds. **Every US user holds it.** |
+| Levy Purchaser | **24** | 27 | Levy's own **4** kits: 193, 213, 231, 242 (189 moved to Levy Corporate). |
+| Non-Levy | **by name** — 40 | 42 | The other persona-1 kits / 123 items / 3 categories, minus 187 (moved to Compass Corporate). |
+| Levy / Compass Corporate / Field | **by name** — 41-44 | 43-46 | One laptop kit each. See [Corporate vs Field](./corporate-vs-field-laptop-personas.md). |
+| VIP Role | 35 | 38 | VIP add-on. Carries the manager auto-approve limit (`PersonaGlobalSettings` setting 18 = `'5000'`) — see [Approval-Decision Flow](approval-decision-flow.md). |
+| Macbook and Surface (CDL) | 30 | 33 | `@compassdigital.io` + VIP users. |
+| CDL Eats Technology | 32 | 35 | |
+
+**Never hardcode a derived persona id, and never assume id = number.** Number is assigned as
+`MAX(number)+1` under 100, so ids and numbers drift apart (number 40 is "MyDining- KDS", id 38).
+Every environment gets different ids, which is what name-resolution protects against. `PeopleFile`
+still uses literal id constants for 1 / 24 / 30 / 35.
+
+**Location-granted personas can be wider than the name suggests.** Crothall Purchasing Team (**21**)
+is attached by `Locations_Personas` to the whole Crothall sector `B00000` (location **57**), same as
+Crothall Sector persona 6, so all **7,250** Crothall users see Virtual Manager kits **118 / 148**.
+Open question for Compass (2026-10-20) whether that is intended.
 
 `PeopleFile` resolves it at runtime:
 
@@ -116,10 +123,14 @@ users get it from their *own* location.
 **US** (`$tenantKey === 'US'`):
 - Always ensure **Base (1)** — never delete it. Base is printers, which every US user should see,
   Levy included.
-- **Non-Levy**, only when `$nonLevyPersonaId !== null`:
-  - `isLevy && hasNonLevy` → stage delete
-  - `!isLevy && !hasNonLevy` → stage insert
-- New users: always insert Base; insert Non-Levy only when `!isLevy` and the persona exists.
+- Build the **effective** set (`buildEffectivePersonaIds()`): direct + own-location + 5-hop sector
+  `Locations_Personas` + Base, using this run's VIP/CDL flags, with derived personas (Non-Levy and
+  the four Corporate/Field halves) removed so a wrong grant cannot justify itself.
+- **Non-Levy**, only when `$nonLevyPersonaId !== null`: `shouldUserHaveNonLevy()` is true unless the
+  effective set is exactly Base + Levy. Insert or delete to match.
+- **Corporate/Field half** (`findSegmentPersonaIdsForUser()`), only when all four exist — see
+  [Corporate vs Field](./corporate-vs-field-laptop-personas.md).
+- New users get the same three steps (Base, Non-Levy, half) with an empty direct set.
 
 > **⚠ This rule is DUPLICATED in the migration — change one, change both.** `PeopleFile.php` and
 > Phase 6 of `dbchanges2/Client_Compass/2026-09-11 - PersonaRefactor.sql` both skip users whose whole
@@ -184,6 +195,7 @@ Both are **latent, not live, and not yet fixed** — each needs its own ticket.
   constants from this file into tickets, docs, or chat transcripts.
 
 ## Change history
+- 2026-10-20 — Persona table refreshed from prod (TRUE-82956): ids vs numbers (24/27, 30/33, 32/35, 35/38, 40/42), Levy Purchaser down to 4 kits and Non-Levy minus 187 after the Corporate/Field split (TRUE-82667, live), assignment steps now include the effective set and the Corporate/Field half, Crothall Purchasing Team (21) sector-wide grant flagged as an open question. (bala)
 - 2026-10-09 — Persona 35 now carries the manager auto-approve limit (setting 18); PeopleFile keeps it in exact sync with `c_isVip` (prod 2269/2269), so do not decouple the two (TRUE-82608). (bala)
 - 2026-10-05 — Linked the deferred
   [corporate vs field laptop split](./corporate-vs-field-laptop-personas.md) (Corporate attached at

package/knowledge/clients/nychh/features/talos-assistant-enablement.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: nychh
 type: client-feature
 status: active
-updated: 2026-10-08
-owners: [apeterson, akhokhani]
+updated: 2026-10-20
+owners: [apeterson, akhokhani, tcox]
 files:
   - dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql
   - dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql
@@ -60,6 +60,8 @@ The older September 2 record verified only local override teardown/re-run and re
 
 For launch, inspect the actual production bundle as a non-admin intended user, verify `/users/me` grants active `toga-supply`, discover the assistant and run the shared streaming/isolation suite. Verify stop cancellation, transcript reload and run rejoin separately; code source and successful historical backend calls are insufficient.
 
+Do not use `https://nychh.client.sandbox.togasupply.com` or local dev to test Talos today: sandbox-client tokens are rejected by beta Talos (401 "Token expired") and local dev has no `VITE_TALOS_API` (verified 2026-10-20). Details: [Supply integration § Where Talos can be tested](../../../2.0/apps/toga25-supply/features/talos-integration.md).
+
 ## Gotchas
 
 - NYCHH stored assistant `persona_prompt` and persona `system_prompt` diverged (16,362 versus 17,848 characters in the survey). Compass had newer BLP/instructions and an embedding; do not assume publishing one client updates the other.
@@ -78,4 +80,5 @@ For launch, inspect the actual production bundle as a non-admin intended user, v
 
 ## Change history
 
+- 2026-10-20 — Noted Talos cannot be tested on sandbox-client or local dev (TRUE-82954) (tcox).
 - 2026-10-08 — Reconciled local source and dated 2026-10-07 research into the canonical KB (akhokhani).

package/knowledge/standalone/apps/talos-backend/features/auth-and-access-control.md

@@ -6,8 +6,8 @@ project: TOGa Talos
 client: shared
 type: feature
 status: active
-updated: 2026-10-08
-owners: [akhokhani]
+updated: 2026-10-20
+owners: [akhokhani, tcox]
 files:
   - talos-backend/libs/aegra-api/src/aegra_api/core/auth_deps.py
   - talos-backend/libs/aegra-api/src/aegra_api/core/auth_middleware.py
@@ -101,6 +101,7 @@ The shared authorization Redis holds TogaHub entitlements, cancellation and limi
 - Org IDs are exact and case-sensitive (`True`, `Towfoundation`, `Compass_Usa`, `Nychh`). Fix a wrong registration in the control plane; never add fuzzy matching.
 - A user who loses a TogaHub persona grant gets 403 even on their old threads.
 - `audience.client` for NYCHH is "NYC Health + Hospitals"; it resolves only because the control-plane `slug` matches it exactly.
+- 401 "Token expired" means **any** TogaHub `/users/me` 401 (`togahub_auth.py`), not only a real expiry. A token issued by a different api2 environment than `TOGAHUB_API_URL` gets it too: beta Talos (`https://api.beta.togahub.com/v2/users/me`) rejects tokens from `api.client.sandbox.togahub.com` this way, with time left on the token (verified 2026-10-20). Check the JWT `iss` against `TOGAHUB_API_URL` before chasing refresh.
 - `aud` in the JWT is not used as an audience check by Talos; the TOGa Platform MCP does enforce audience = forwarded origin ([toga-platform-mcp](toga-platform-mcp.md)).
 - Changing `AUTH_TYPE` to `noop` anywhere reachable from the internet exposes every tenant.
 - The tenant registry caches canonical org IDs; after control-plane edits restart or bust the cache (`tenant_registry.bust_cache`).
@@ -110,5 +111,6 @@ The shared authorization Redis holds TogaHub entitlements, cancellation and limi
 
 ## Change history
 
+- 2026-10-20 — Gotcha: "Token expired" covers any TogaHub 401, incl. a token from another api2 environment (TRUE-82954) (tcox).
 - 2026-10-08 — Corrected custom-auth production support to match startup validation (akhokhani).
 - 2026-10-07 — created from `_beta` code: TogaHub flow (org from `audience.client` canonicalized by org_id or slug), API-key grants, scheduled principal, slug-gated ACL, permission table (akhokhani)

package/knowledge/standalone/apps/talos-backend/features/client-integration-contract.md

@@ -6,8 +6,8 @@ project: TOGa Talos
 client: shared
 type: feature
 status: active
-updated: 2026-10-08
-owners: [akhokhani, apeterson]
+updated: 2026-10-20
+owners: [akhokhani, apeterson, tcox]
 files:
   - talos-backend/aegra.json
   - talos-backend/libs/aegra-api/src/aegra_api/main.py
@@ -48,6 +48,11 @@ Talos speaks the **LangGraph Agent Protocol**, so use the LangGraph SDK (`@langc
 - Browser: `Authorization: Bearer <api2 JWT>` (the token the app already holds; any TogaHub client mapped to a provisioned Talos org works). The browser's real `Origin`/`Referer` are forwarded to TogaHub `/v2/users/me`; they must be absolute and agree.
 - Service: `X-API-Key: aegra_<tenant>_<secret>` with scope `agent:run`, `allowed_model_slugs` and `allowed_graph_ids` — allowed only on `POST /threads` and `POST /threads/{id}/runs/stream`. For one-shot server calls prefer `/api/ai/agent` or `/api/ai/generate` ([ai-service-endpoints](ai-service-endpoints.md)).
 - Details and error strings: [auth-and-access-control](auth-and-access-control.md).
+- Browser token refresh is the client's job: read the bearer per request, refresh it near `exp`, and on a 401 `"Token expired"` refresh and resend **once**. A resend is safe — auth runs before any route, so a 401 created no thread, run or message. Reference: Supply `talosFetch` ([talos-integration](../../../../2.0/apps/toga25-supply/features/talos-integration.md)).
+
+### Error body
+
+Every `HTTPException` is returned as `{error, message, details}` (`main.py:agent_protocol_exception_handler`), not FastAPI's `{detail}`. Match on `message` (for example `"Token expired"`).
 
 ### CORS
 
@@ -102,10 +107,12 @@ Upload `POST /files/upload` (multipart; 50 MB in prod), download `GET /files/{id
 - `@langchain/langgraph-sdk` ≥ 1.10 declares `@langchain/core` as a required peer; missing it fails Vite dependency optimization with `Could not resolve "@langchain/core/messages"`.
 - `stream_resumable` sent by some clients is not a server field; resumability comes from `on_disconnect: "continue"` plus `Last-Event-ID` rejoin.
 - Older notes saying CORS headers appear only on the preflight are obsolete (verified 2026-10-07).
+- The LangGraph SDK `AsyncCaller` retries **thrown** errors, 5xx and network failures up to 4x, but never 401/403. So a custom `fetch` should return a 401 `Response` (not throw) for "not signed in". Risk, not yet handled: a retried 5xx on `POST /threads/{id}/runs/stream` can create a second run if the server already created the first — open follow-up (TRUE-82954).
 
 ## Related
 - [aegra-api](aegra-api.md) · [auth-and-access-control](auth-and-access-control.md) · [chat-frontend](../../talos/features/chat-frontend.md) · [toga25-supply talos-integration](../../../../2.0/apps/toga25-supply/features/talos-integration.md) · [toga-blox talos-assistant](../../../../2.0/apps/toga-blox/features/talos-assistant.md)
 
 ## Change history
+- 2026-10-20 — added error body shape `{error, message, details}`, client token-refresh/one-resend rule and SDK retry behavior (TRUE-82954) (tcox)
 - 2026-10-08 — corrected cross-framework/client links after standalone migration and clarified partial parallel resumes versus complete per-interrupt action decisions (akhokhani)
 - 2026-10-07 — created: single home for the caller contract (moved from aegra-api, toga25-supply and chat-frontend docs); CORS re-verified live (akhokhani)

package/package.json

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