toga-ai 1.0.665 → 1.0.666

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

@@ -7,6 +7,7 @@
 | [AdvancedSelect (virtualized single/multi select)](features/advanced-select.md) | `AdvancedSelect<T>` is a **fully controlled, virtualized** single/multi select built from scratch (not react-select) on **`@tanstack/react-virtual`**, for large | toga-blox/src/components/AdvancedSelect/AdvancedSelect.tsx, toga-blox/src/components/AdvancedSelect/AdvancedSelect.types.ts, toga-blox/src/components/AdvancedSelect/AdvancedSelect.module.css |
 | [API client (axios wrapper, auth, table-data fetchers)](features/api-client.md) | `src/api/` is a thin **axios** wrapper that standardizes the **2.0 API envelope**, manages auth (Bearer + refresh), serializes complex query options, and provid | toga-blox/src/reactQuery/queryHelpers.ts, toga-blox/src/api/index.ts, toga-blox/src/api/axiosInstance.ts, toga-blox/src/api/apiFunctions.ts, toga-blox/src/api/auth.ts, toga-blox/src/api/genericApi.ts, toga-blox/src/api/types.ts, toga-blox/src/api/tableData |
 | [BaseInput (react-hook-form field factory)](features/base-input.md) | `BaseInput` is a **form-field factory** driven by react-hook-form. | toga-blox/src/components/BaseInput/BaseInput.tsx, toga-blox/src/components/BaseInput/BaseInput.types.ts, toga-blox/src/components/BaseInput/BaseInput.module.css, toga-blox/src/components/BaseInput/components |
+| [blox authoring defect backlog (fix IN blox, not around it)](features/blox-authoring-defects.md) | The standing list of **defects to fix inside `@agilant/toga-blox`**. | toga-blox/src/api/auth.ts, toga-blox/src/api/axiosInstance.ts, toga-blox/src/reactQuery/queryHelpers.ts, toga-blox/src/components/BaseInput, toga-blox/tsconfig.json, toga-blox/package.json |
 | [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | `src/templates/PrimaryTable/` is the **production, wired-up table** built on the [Table component](table.md). | toga-blox/src/components/Table/themeConfig/toga.module.css, toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx, toga-blox/src/templates/PrimaryTable/types.ts |
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |

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

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: architecture
 status: active
-updated: 2026-06-23
+updated: 2026-08-27
 owners: [apeterson]
 files:
   - toga-blox/package.json
@@ -20,6 +20,7 @@ related:
   - features/base-input.md
   - features/advanced-select.md
   - features/api-client.md
+  - features/blox-authoring-defects.md
 ---
 
 ## Summary

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-08-17
+updated: 2026-08-27
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/reactQuery/queryHelpers.ts
@@ -118,8 +118,48 @@ Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `Da
   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.
+- **⚠ AUTHORING DEFECT — `handleClientAuthentication(uuid)` collides by name with app-local SSO
+  helpers and is not interchangeable with them.** blox's version `POST`s
+  `/auth/encrypted-user-uuid` with an **empty payload** (`{client:"",user:""}`), writes
+  access/refresh tokens to `localStorage`, and returns a `/users` payload. `toga2-supply` has a
+  local util of the **same name** that resolves a client's SSO URL — a completely different
+  function. `toga25-supply` called blox's by mistake and SSO silently never fired for ~any data,
+  because the returned object has no `singleSignOnServiceUrl` property (masked by an `as any`).
+  See [toga25-supply SSO redirect & session gating](../../toga25-supply/features/sso-redirect-and-session-gating.md).
+- **⚠ AUTHORING DEFECT — `fetchPublicToken()` PERSISTS the public token to `localStorage`**
+  (`accessToken` + `refreshToken`), so a logged-**out** visitor is indistinguishable from a
+  logged-in one if you gate on `accessToken`. The correct discriminator is `localStorage`'s
+  **`user`** key — which this module's own request interceptor already uses
+  (`userString ? accessToken : fetchPublicToken(baseURL)`). Corollary: `localStorage` repopulating
+  seconds after logout is a **fresh public token**, not a surviving session, and no app-side code
+  can stop it while this behavior stands.
+- **⚠ AUTHORING DEFECT — `performLogout` hardcodes `window.location.href = "/"`.** On a
+  single-sign-on client, `/` is exactly the route that triggers the IdP redirect, so logging out
+  bounces the user straight back into SSO and `/login` becomes unreachable. Apps can pass
+  `onLogout` to `createAxiosInstance` **and** stop calling `performLogout` from their own logout
+  action — **both**, since the Logout button and the 401-interceptor path are separate — but the
+  real fix is blox-authoring work.
+- **`GET /domains` requires a Bearer token.** The request interceptor transparently supplies a
+  *public* one when there is no `user` in `localStorage`, which is why a logged-out domain lookup
+  works in-app but **401s from a raw `curl`**. Reproduce out-of-app by minting a public token first.
+- **Verifying a domain is registered without DB access:** `POST /auth/public` with an explicit
+  `Origin` header. `Origin: https://compass.togasupply.com` → **201** with an audience of
+  `{client: "Compass Group", app: "TOGa Supply"}`; no `Origin` at all → **401 EN-6**.
+- **OPEN QUESTION (unresolved 2026-08-27): `EV-14` from a filtered `/domains` lookup.** `EV-14` is a
+  **404 "expected exactly one record"**. A public-token `/domains` lookup returned it for every
+  environment slug tried (`PRODUCTION`, `PROD`, `LIVE`). It was **not** determined whether the
+  app's own in-browser request differs (different token scope, different filter). Treat as an open
+  thread, not a settled finding.
 
 ## Change history
+- 2026-08-27 — Recorded three blox **authoring defects** surfaced while debugging toga25-supply SSO:
+  (1) `handleClientAuthentication` collides by name with app-local SSO helpers and returns a
+  `/users` payload with no `singleSignOnServiceUrl`; (2) `fetchPublicToken` persists the public
+  token to `localStorage`, making logged-out visitors look authenticated unless you gate on the
+  `user` key; (3) `performLogout`'s hardcoded `"/"` redirect traps SSO clients in a logout→IdP loop
+  and makes `/login` unreachable. Also documented that `/domains` needs a Bearer token (public one
+  auto-supplied in-app, hence raw-curl 401s), the `Origin`-header trick for confirming a domain is
+  registered, and left the public-token `/domains` **EV-14** result as an open question. (apeterson)
 - 2026-08-17 — Fixed `assembleOptionsWhere` spreading a raw-string `apiWhereClause` character-by-
   character into invalid `index:0:char` conditions (api2 `Invalid operator '0'` / EO-1 500 opening
   the Compass USA Item Fulfillment modal). String entries now pass through verbatim (single outer

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

@@ -0,0 +1,129 @@
+---
+title: blox authoring defect backlog (fix IN blox, not around it)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-08-27
+owners: [apeterson]
+files:
+  - toga-blox/src/api/auth.ts
+  - toga-blox/src/api/axiosInstance.ts
+  - toga-blox/src/reactQuery/queryHelpers.ts
+  - toga-blox/src/components/BaseInput
+  - toga-blox/tsconfig.json
+  - toga-blox/package.json
+related:
+  - ../architecture.md
+  - api-client.md
+  - base-input.md
+  - advanced-select.md
+  - ../../../standards/frontend.md
+  - ../../toga25-supply/features/sso-redirect-and-session-gating.md
+---
+
+## What it is
+
+The standing list of **defects to fix inside `@agilant/toga-blox`**. This is the counterpart to
+[frontend standard §22](../../../standards/frontend.md), which tells a *consuming app* how to work
+**around** the same defects. §22 is defensive advice for app authors; **this doc is the work list
+for whoever edits blox itself**, and it is where §22's long-standing "a future `blox-authoring.md`"
+pointer resolves.
+
+Nothing here is scheduled. Treat it as a backlog with evidence attached, so a fix can be picked up
+without re-deriving the mechanism. **When one of these is fixed and published, update §22 in the
+same pass** — otherwise consuming apps keep carrying dead workarounds.
+
+## How it works (how to use this list)
+
+Each entry carries three things deliberately: the **mechanism** (what the code actually does), the
+**consumer-facing symptom** (how it presents in an app, which is usually nothing like the
+mechanism), and a **fix direction** (a suggestion, not a decision). Every one of these is a
+**breaking-ish change for ~40 consumers**, so a fix needs a deprecation path or a coordinated bump
+— see the [publish pipeline](../workflows/dynamic-publish-pipeline.md).
+
+## Auth-layer defects (found 2026-08-27, toga25-supply SSO debugging)
+
+### 1. `handleClientAuthentication` — misleading name, untyped return
+
+- **Mechanism.** Despite the name, it is not a client-authentication *flow driver*: it is an
+  **encrypted-uuid token exchange**. It `POST`s `/auth/encrypted-user-uuid` with an empty payload
+  (`{client:"",user:""}`), writes access/refresh tokens to `localStorage`, and returns a `/users`
+  payload. Its return type is not modeled, so consumers reach into it untyped.
+- **Consumer symptom.** `toga2-supply` has an app-local util of the **exact same name** that
+  resolves a client's SSO URL. `toga25-supply` called blox's by mistake; the returned object has no
+  `singleSignOnServiceUrl` property, so the SSO redirect evaluated to `null` under **any** data and
+  silently fell through to `/login` forever. An `as any` cast is what let it compile and ship.
+- **Fix direction.** **Rename it to describe what it does** (e.g. an `exchangeEncryptedUserUuid`
+  shape) so it cannot collide with app-level SSO helpers, and **declare a return type** so a shape
+  mismatch is a compile error at the call site instead of a silent `undefined`.
+
+### 2. `fetchPublicToken` — persists the public token to `localStorage`
+
+- **Mechanism.** It writes both `accessToken` and `refreshToken` to `localStorage` for
+  **logged-out** requests, using the same keys a real session uses.
+- **Consumer symptom.** A public token becomes **indistinguishable from a user session** for any
+  consumer that gates on `accessToken` — which is the obvious thing to gate on. Bugs present as
+  intermittent and environment-dependent (clean storage behaves one way, a browser that has already
+  touched the API behaves another). It also makes `localStorage` repopulate seconds after logout,
+  which reads as "logout is broken" when it is a fresh public token. The only current discriminator
+  is the `user` key — which blox's own request interceptor already relies on
+  (`userString ? accessToken : fetchPublicToken(baseURL)`), so the library is internally aware of a
+  distinction it does not expose.
+- **Fix direction.** **Hold the public token in memory** (module scope) rather than persisting it,
+  so `localStorage` means "a real session exists" and nothing else. If persistence is genuinely
+  needed for reloads, use a **separate key** (`publicAccessToken`) so the two can never be confused.
+
+### 3. `performLogout` — hardcoded `window.location.href = "/"`
+
+- **Mechanism.** The logout destination is a literal `"/"`, not configurable by the caller.
+- **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 `"/"` for compatibility), or have `performLogout` simply not navigate and let the caller's
+  `onLogout` own it.
+
+## Already-known authoring items (carried over from §22)
+
+These are long-standing and were previously recorded only as consumer-side advice:
+
+- **Empty `where` serializes to a literal `()`** in `reactQuery/queryHelpers.ts` — apps must avoid
+  emitting an empty filter object. Fix direction: omit the clause entirely when it has no entries.
+- **`dist/main.css` is not compiled** — it still contains raw `@tailwind` directives, so importing
+  it does nothing useful. Fix direction: either build it properly or stop shipping it, because its
+  presence invites consumers to import it.
+- **Two select stacks** (`react-select` + the custom `AdvancedSelect`) and **two table stacks**
+  (`react-table` v7 + `@tanstack/react-table` v8) coexist. This is real dependency weight pushed
+  onto every consumer, and the v7 stack is what forces apps to declare `react-table` /
+  `react-table-sticky` / `react-multi-select-component` peers. Fix direction: converge on one of
+  each and retire the legacy stack.
+- **`BaseInput` has a ~85-prop className-string styling contract** and **no custom-validator
+  passthrough** — the latter is why every consuming app rebuilds an app-side validator layer. Fix
+  directions: drive styling from host tokens rather than per-prop strings, and accept a validator
+  passthrough.
+- **`strict: false` in blox's own tsconfig.** The library ships looser types than the apps that
+  consume it, which is how untyped returns like defect 1 survive review. Fix direction: enable
+  strict incrementally.
+- **React-18-only peers.** Blocks every consumer from React 19; unscheduled and consumer-wide.
+
+## Gotchas
+
+- **Do not "fix" these in an app.** Working around them in a consumer is §22's job and is
+  legitimate; changing app code to *imitate* the defect is not.
+- **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 that
+  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-08-27 — Created the doc §22 had been pointing at since 2026-08-18. Seeded with the three auth
+  defects found while debugging toga25-supply SSO (`handleClientAuthentication`'s misleading name +
+  untyped return, `fetchPublicToken` persisting the public token to `localStorage`,
+  `performLogout`'s hardcoded `"/"`), each with mechanism / consumer symptom / fix direction, plus
+  the previously consumer-side-only items carried over from §22. (apeterson)

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

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: [jcardinal, apeterson]
 files:
   - toga-blox/.github/workflows/publish.yml
@@ -167,8 +167,39 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
 - **Secret hygiene done right.** `publish.yml` writes a transient `.npmrc` at build time from
   GitHub secrets (`${NODE_AUTH_TOKEN}` / FontAwesome token) — it never commits tokens. This is
   the pattern the consuming apps should follow (see the commerce workflow's secret-hygiene note).
+- **⚠ Sibling to the `.scss`-only gotcha, DIFFERENT mechanism: a stylesheet whose import path
+  ESCAPES `dist/` is never in the tarball.** After the `feature-new-table` → `_production` merge,
+  `global.css` sat at the **repo root** with `import "../global.css"` in `src/index.ts`. `tsc`
+  emits that specifier **verbatim**, so `dist/index.js` pointed *outside* `dist/`, and
+  `"files": ["dist","README.md"]` meant the stylesheet was never packed. Every consumer failed with
+  `Could not resolve "../global.css"`. Shipped broken as **1.0.323-production.137** and
+  **1.1.1-production.138**. Fix: move it to `src/global.css` with `import "./global.css"` so
+  `copyfiles` ships it into `dist/` — which is exactly what `_sandbox-client` had always published
+  (identical blob, different location). **This was a merge-resolution failure, not new code** —
+  when landing a long-lived branch, diff the *published tarballs* of the two channels, not just the
+  source. Same failure family as the `.scss` gotcha above (JS importing an unshipped stylesheet),
+  but caused by the path + the `files` allowlist rather than the copy glob.
+- **There is no base version that publishes as itself.** CI always does **patch + 1** on the base,
+  so a base of `1.1.0` can never publish as `1.1.0` — it publishes `1.1.1-production.<run>`. The
+  developer controls only the base; plan release numbering around that.
+- **Keep the production base ahead of, or level with, sandbox.** `_production`'s base had drifted
+  **12 patches behind** `_sandbox-client`, so the production channel was publishing *numerically
+  lower* versions than sandbox. The base was bumped `1.0.322` → **1.1.0** to mark the
+  `feature-new-table` release and stop that inversion; CI published `1.1.1-production.139`.
+- **Pushing to a `_*` branch IS the publish — there is no separate step to run afterwards.** The
+  merge push itself triggered a publish (`1.0.323-production.137`) about a minute after the merge
+  landed. Consequence: a merge that is not release-ready still ships. Get the tree right *before*
+  you push to a release branch.
 
 ## Change history
+- 2026-08-27 — Released blox **1.1.0** on `_production` (published `1.1.1-production.139`) and fixed
+  a shipped-broken tarball: the `feature-new-table` → `_production` merge left `global.css` at the
+  repo root with `import "../global.css"`, so the emitted `dist/index.js` referenced a path outside
+  `dist/` that `"files": ["dist"]` never packed — breaking every consumer on
+  `1.0.323-production.137` / `1.1.1-production.138`. Moved to `src/global.css` + `./global.css`.
+  Also recorded that CI's patch+1 means no base ever publishes as itself, that the prod base had
+  fallen 12 patches behind sandbox (hence the `1.1.0` bump), and that pushing a `_*` branch **is**
+  the publish. (apeterson)
 - 2026-08-26 — Deployed `1.0.334-sandbox-client.136` (`feature-new-table` → `_sandbox-client`, 6
   files, no conflicts) and recorded three workflow gotchas from it: (1) a feature branch that never
   touches the `version` line merges without a version conflict, which is why the bump lands on

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

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: workflow
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: ["jcardinal", "apeterson"]
 files:
   - toga2-commerce/amplify.yml
@@ -129,8 +129,28 @@ full cross-repo publish-then-build model. **The channel must exist before the ap
   environment variables and write a **transient `.npmrc` at build time** from
   `$FONTAWESOME_NPM_AUTH_TOKEN` — exactly what blox's `publish.yml` already does. Never document the
   token values.
+- **⚠ The `package.json` blox pin governs LOCAL DEV ONLY — the deployed build always takes the
+  channel head.** `amplify.yml` runs `npm install "@agilant/toga-blox@$MODE"`, which **overwrites**
+  whatever version `package.json` pins. So a production deploy silently picks up a newly published
+  blox release **with no PR and no pin change at all** — and conversely, "bump the pin" accomplishes
+  much less here than it does in `toga25-supply`, which installs blox as a normal pinned dependency.
+  Reason about commerce's deployed blox version from the **dist-tag**, not the manifest.
+- **A caret on a PRERELEASE is inert, not floating.** `^1.0.322-sandbox-client.117` resolves to
+  **exactly** `1.0.322-sandbox-client.117`: npm only matches prereleases sharing the same
+  `major.minor.patch`. Verified with `semver.maxSatisfying`. It is still a
+  [frontend standard](../../../standards/frontend.md) §13(a) violation and confusing, but it is
+  **not** a drift risk — don't chase it as one.
+- **Commerce's dependency health is better than supply's**, verified 2026-08-27: all 19 blox peers
+  satisfied (none missing) and `resolve.dedupe` is committed on `TRUE-80707`.
 
 ## Change history
+- 2026-08-27 — Replaced the caret sandbox blox pin `^1.0.322-sandbox-client.117` with the exact
+  production-channel `1.1.1-production.139` per frontend standard §13(a), verified with the same
+  chain Amplify runs (`tsc -b` + `vite build --mode production`, green). **Working-tree only /
+  uncommitted on `TRUE-80707`.** Recorded two findings: `amplify.yml`'s
+  `npm install "@agilant/toga-blox@$MODE"` **overwrites** the manifest pin, so the pin governs local
+  dev only and a prod deploy takes the channel head with no PR; and a caret on a prerelease is
+  **inert**, resolving to that exact version rather than floating. (apeterson)
 
 - 2026-08-26 — Dependency-resolution findings from a local commerce build: root-caused an
   `ERESOLVE` to the **missing `legacy-peer-deps=true` in commerce's tracked `.npmrc`** (supply had

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

@@ -10,6 +10,7 @@
 | [Force Logout on Deployment (useDeploymentGuard)](features/force-logout-on-deployment.md) | On large deployments the backend bumps the Core parameter `META_LAST_REFRESH_DATETIME`. | toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/App.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts |
+| [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |

package/knowledge/2.0/apps/toga25-supply/features/sso-redirect-and-session-gating.md

@@ -0,0 +1,100 @@
+---
+title: SSO redirect & public-vs-user session gating (useAuthenticationFlow)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-08-27
+owners: [apeterson]
+files:
+  - toga25-supply/src/hooks/useAuthenticationFlow.ts
+  - toga25-supply/src/routes.tsx
+  - toga25-supply/src/contexts/AuthContext.tsx
+  - toga25-supply/src/api/api.ts
+related:
+  - ../../toga-blox/features/api-client.md
+  - ../../api2/features/encrypted-user-uuid-auth-handoff.md
+  - ../../../standards/frontend.md
+---
+
+## Summary
+
+How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to
+their client's SSO IdP instead of the local `/login` form. `useAuthenticationFlow` resolves the
+client from the current domain, asks api2 for that client's `singleSignOnServiceUrl`, and
+redirects there if one exists. This mirrors `toga2-supply`, which invokes the equivalent flow from
+`App.tsx` on every navigation.
+
+Confirmed working in production for Compass USA / Compass Canada as of 2026-08-27.
+
+## How it works
+
+1. **The hook must be mounted inside the router.** It uses `useNavigate` / `useLocation`, so it is
+   mounted as an `AuthenticationFlowRoot` **route element** that wraps *both* the `PrivateRoute`
+   branch and `/login` in `routes.tsx`. Mounting it above the router, or not at all, silently
+   disables SSO.
+2. **Resolve the SSO URL from the scripted API, not from a login helper.** The correct call is
+   `GET /client-authentications/singleSignOnServiceUrl` with `{ uuid, domainUuid }`, reading
+   `data.clientAuthentications.singleSignOnServiceUrl`. A typed `SsoUrlResponse` interface holds
+   that shape so a mismatch is a compile error.
+3. **Redirect or fall through.** A non-null URL → `window.location` to the IdP; null → local
+   `/login`.
+4. **Gate on a real user session, not on a token.** The "is this visitor already signed in?" check
+   reads `localStorage.getItem("user")` — **not** `accessToken` (see gotchas).
+
+## Gotchas
+
+- **⚠ blox exports a `handleClientAuthentication(uuid)` that is NOT `toga2-supply`'s util of the
+  same name.** This is a **name collision between a shared-lib export and an app-local helper**,
+  and it was the root cause of SSO never firing here. blox's version `POST`s
+  `/auth/encrypted-user-uuid` with an **empty payload** (`{client:"",user:""}`), writes
+  access/refresh tokens to `localStorage`, and returns a `/users` payload that has **no
+  `singleSignOnServiceUrl` property at all**. The old code did
+  `(ssoData as any)?.singleSignOnServiceUrl ?? null`, so the result was **always null under any
+  data** and always fell through to `/login`. The `as any` cast is precisely what let this ship —
+  when consuming a shared-lib function whose name matches a local one, type the response and
+  verify the endpoint it actually calls.
+- **⚠ A token in `localStorage` does not mean a user is signed in.** blox's `fetchPublicToken`
+  writes `accessToken` **and** `refreshToken` for *logged-out* requests. Gating on
+  `localStorage.getItem("accessToken")` (which both `hasTokenInStorage` in the hook and
+  `AuthContext`'s initial `isAuthenticated` did) makes any visitor who has already touched the API
+  look authenticated, so SSO is **skipped**. Symptom is maddeningly intermittent: clean storage →
+  SSO fires; any prior request → no SSO. **`localStorage.getItem("user")` is the correct
+  discriminator** — only a real session writes `"user"`, and blox's own axios request interceptor
+  already uses exactly that distinction (`userString ? accessToken : fetchPublicToken(baseURL)`).
+  *(Status: fix written but **uncommitted** as of 2026-08-27.)*
+- **Tokens reappearing right after logout are not a surviving session.** They are a **fresh public
+  token** minted by `fetchPublicToken` on the next request. No app-side logout code can prevent
+  this while blox persists public tokens to `localStorage`.
+- **⚠ Known live defect: `/login` is currently unreachable on an SSO client.** blox's
+  `performLogout` hardcodes `window.location.href = "/"`, and `/` is exactly what triggers the SSO
+  redirect — so signing out bounces straight back to the IdP. A fix landing on `/login` from both
+  paths (`AuthContext.logout` no longer calling `performLogout`, **plus** an `onLogout` passed
+  through `api.ts` so blox's 401-interceptor path matches — **both** are required, since the Logout
+  button goes through `AuthContext` and an expired token goes through the interceptor) was made in
+  `e886afb` and then **reverted at the developer's request** in `09f8dd5` (a revert, not a history
+  rewrite, because `e886afb` was already pushed and merged). The revert was **not pushed** as of
+  2026-08-27. The underlying defect is blox's hardcoded `"/"`, and the app-side workaround was
+  rejected — so this is **blox-authoring work**.
+- **A `?local=1` sessionStorage opt-out is unnecessary — don't rebuild it.** It was built and
+  discarded: once you submit the login form you hold a real token, so SSO stops firing on its own.
+
+### Diagnosing whether a hook is even running: grep the deployed bundle
+
+Search the built bundle for the endpoint **string literals** the code should contain. Before the
+fix: `client-authentications` 0 occurrences, `encrypted-user-uuid` 1. After: inverted. Because an
+unmounted hook is tree-shaken out entirely, the absence of its literals also proves it is never
+mounted — a cheap way to confirm a deploy actually carries the change.
+
+## Change history
+- 2026-08-27 — Fixed SSO never redirecting: mounted the previously-callerless
+  `useAuthenticationFlow` as an in-router `AuthenticationFlowRoot`, and replaced the call to blox's
+  same-named `handleClientAuthentication` (empty-payload `/auth/encrypted-user-uuid`, no
+  `singleSignOnServiceUrl` in its response) with the scripted
+  `GET /client-authentications/singleSignOnServiceUrl`, typed via `SsoUrlResponse` instead of
+  `as any`. Committed, pushed, confirmed working. Also recorded (fix **uncommitted**) that public
+  tokens are indistinguishable from user tokens when gating on `accessToken` — gate on `"user"` —
+  and that the logout→`/`→SSO loop, briefly fixed in `e886afb`, was **reverted** (`09f8dd5`,
+  unpushed) so `/login` is currently unreachable on Compass. (apeterson)

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

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-07-17
-owners: [jcardinal]
+updated: 2026-08-27
+owners: [jcardinal, apeterson]
 files:
   - toga25-supply/amplify.yml
   - toga25-supply/src/api/api.ts
@@ -111,8 +111,32 @@ and are the single source of truth for environment API endpoints.
   build is required. The `.env.<mode>` files are the single source of truth.
 - **`npm run build` ships production everywhere** — always build with an explicit
   `--mode "$VITE_MODE"`; the per-mode `package.json` scripts are dev servers, not builds.
+- **⚠ A symlinked shared-lib checkout MASKS both a missing dependency declaration and missing peer
+  deps.** Verified 2026-08-27: `_production` did **not** list `@agilant/toga-blox` in
+  `package.json` at all and had **no lock entry**, despite ~200 imports across `src/`. It only
+  resolved locally because `node_modules/@agilant/toga-blox` was a **symlink to the local checkout**
+  (`toga-blox-npm`), so resolution fell through to the linked package's own `node_modules`. The
+  Amplify `preBuild` runs **`npm ci`**, which would have failed outright. Installing blox properly
+  from the registry then surfaced **four** peers the symlink had been hiding — because
+  `legacy-peer-deps=true` means npm does **not** auto-install peers, and blox's barrel import pulls
+  in components the app never renders:
+  `@fortawesome/free-solid-svg-icons@^6.7.2` (blox `Input.tsx` / `faCircleInfo`),
+  `react-multi-select-component@^4.3.4`, `react-table@^7.8.0`, `react-table-sticky@^1.1.3`
+  (the legacy v7 table stack). All three `react-table` v7 packages were **already** declared at
+  identical versions on `_sandbox-client` — `_production` was the outlier. Fixed in `92644c8`
+  (pushed), verified with a clean vite build (1761 modules).
+- **The audit that catches the above — 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-08-27 — Fixed `_production` never declaring `@agilant/toga-blox` (no dependency entry, no
+  lock entry, ~200 imports) — it resolved only via a local **symlink**, and `npm ci` in `preBuild`
+  would have failed. Added blox plus the four peers the symlink had masked
+  (`@fortawesome/free-solid-svg-icons`, `react-multi-select-component`, `react-table`,
+  `react-table-sticky`), which `_sandbox-client` already carried. Committed `92644c8`, pushed.
+  Recorded the reusable peer-audit procedure. (apeterson)
 - 2026-07-17 — Documented the single shared `amplify.yml` multi-environment deploy: `_<mode>`
   branch → `--mode` derivation, fail-loud guardrails, runtime `import.meta.env.MODE` identity,
   and the critical never-set-`VITE_API`-in-the-Amplify-console gotcha (console vars override

package/knowledge/2.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: [jcardinal, apeterson]
 files: []
 related:
@@ -422,6 +422,15 @@ on the back end. A consuming app **MUST** meet every requirement below.
 Verified 2026-08-26: `toga2-commerce` violates this with `"^1.0.322-sandbox-client.117"`. Also audit
 for **pin drift** between branches (commerce's `TRUE-80707` was 11 versions behind `_sandbox-client`).
 
+**Nuance (verified 2026-08-27): a caret on a PRERELEASE is inert, not floating.** npm only matches
+prereleases sharing the same `major.minor.patch`, so `^1.0.322-sandbox-client.117` resolves to
+**exactly** `1.0.322-sandbox-client.117` (confirmed with `semver.maxSatisfying`). It is still a
+violation — it misleads every reader about intent — but do **not** justify it as a drift risk. The
+real floating risk lives elsewhere: `toga2-commerce`'s `amplify.yml` runs
+`npm install "@agilant/toga-blox@$MODE"`, which **overwrites the manifest pin at build time**, so
+commerce's deployed build always takes the channel head and its pin governs local dev only.
+Commerce's caret is now the exact `1.1.1-production.139` (working-tree only on `TRUE-80707`).
+
 **(b) Declare blox's peer deps that do not hoist into your app.** blox lists them as peers, so npm
 will not necessarily install them for you: verified 2026-08-18 they include `react-hook-form`,
 `@tanstack/react-query`, `@tanstack/react-table`, `framer-motion`, and `axios` (pinned exactly by
@@ -597,9 +606,24 @@ Work **around** these shared-lib defects; do **not** imitate them in app code:
 - A **~85-prop className-string styling contract on `BaseInput`** — verbose by design; drive it from
   tokens, not per-instance strings.
 - **`strict: false` in blox's own tsconfig**, and **React-18-only** peers.
-
-**Fixing these is blox-authoring work, tracked separately** (a future `blox-authoring.md`), **not
-app work.** In a consuming app, guard against them and move on.
+- **⚠ `handleClientAuthentication(uuid)` collides by name with app-local SSO helpers.** blox's
+  version POSTs `/auth/encrypted-user-uuid` with an empty payload and returns a `/users` payload
+  with **no `singleSignOnServiceUrl`** — `toga2-supply` has an unrelated util of the same name.
+  Cost `toga25-supply` a silently-dead SSO redirect, masked by an `as any`. **Type shared-lib
+  responses; never `as any` a cross-package result.**
+- **⚠ `fetchPublicToken` persists the public token to `localStorage`**, so gating auth on
+  `accessToken` makes logged-out visitors look signed in (intermittent-looking bugs: clean storage
+  works, a warm one doesn't). Gate on the **`user`** key — blox's own interceptor already does.
+- **⚠ `performLogout` hardcodes `window.location.href = "/"`.** On an SSO client `/`
+  re-triggers the IdP, so logout loops and `/login` is unreachable. An app-side override needs
+  **both** the logout action and `createAxiosInstance({ onLogout })` (the 401 path is separate) —
+  but that workaround was rejected in supply, so this one is blocking real behavior until fixed in
+  blox.
+
+**Fixing these is blox-authoring work, tracked separately — see
+[blox authoring defect backlog](../apps/toga-blox/features/blox-authoring-defects.md), which
+carries the mechanism, consumer symptom and fix direction for each.** This is **not** app work. In a
+consuming app, guard against them and move on.
 
 ---
 
@@ -640,6 +664,13 @@ app work.** In a consuming app, guard against them and move on.
 
 ## Change history
 
+- 2026-08-27 — §13(a): corrected the caret rationale — a caret on a **prerelease is inert**, not
+  floating; the real floating risk is `toga2-commerce`'s `amplify.yml` overwriting the manifest pin
+  at build time. §22: added three blox auth gotchas found debugging toga25-supply SSO
+  (`handleClientAuthentication` name collision, `fetchPublicToken` persisting the public token to
+  `localStorage`, `performLogout`'s hardcoded `"/"`), and resolved the dangling
+  "a future `blox-authoring.md`" pointer to the new
+  [blox authoring defect backlog](../apps/toga-blox/features/blox-authoring-defects.md). (apeterson)
 - 2026-08-26 — Recorded commerce's missing `resolve.dedupe` (+ the blox-symlink second-React
   hazard), its caret blox pin and cross-branch pin drift, the barrel-import missing-peer trigger,
   and the removal of blox's phantom `react-router-dom` peer. The blox half is now merged and

package/knowledge/INDEX.md

@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **_underscore** (_Underscore) _(framework core)_ — 69 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 57 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 11 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 12 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) — 4 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
@@ -30,8 +30,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 12 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
-- **toga-blox** (TOGa Blox) — 12 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 13 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga-blox** (TOGa Blox) — 13 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 
 ## standalone framework

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

@@ -21,6 +21,7 @@
 | [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is **inserted as a brand-new `Users` row** by the PEOPLE importer i | _underscore/Model/Compass/ApprovalDecision.php, worker2/Worker/Client/Compass/ApprovalReassignment.php, worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
+| [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. | dbchanges2/Client_Compass/2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql |
 | [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
 | [Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)](workflows/odp-edi-import-recovery.md) | 1.0 | How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron **3a** created the ODP SalesOrder header, the follow-up item | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json |

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

@@ -18,7 +18,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
@@ -28,6 +28,7 @@ related:
   - workflows/persona-refactor-migration.md
   - workflows/persona-population-env-comparison.md
   - workflows/granting-persona-bundle-access.md
+  - workflows/granting-navigation-access.md
   - features/mits-sales-order-transmission-alerting.md
   - features/asn-to-item-fulfillment.md
   - features/order-fulfillment-status-per-line.md

package/knowledge/clients/compass-usa/workflows/granting-navigation-access.md

@@ -0,0 +1,158 @@
+---
+title: Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-08-27
+owners: [apeterson]
+files:
+  - dbchanges2/Client_Compass/2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql
+related:
+  - ./granting-persona-bundle-access.md
+  - ../profile.md
+  - ../../../2.0/apps/_underscore/features/surface-resolver.md
+  - ../../../2.0/apps/dbchanges2/features/surface-layer-schema.md
+  - ../../../2.0/apps/toga25-supply/features/surface-frontend.md
+  - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+---
+
+## Summary
+
+"Give user X the same menu items user Y has" is the **navigation analog** of the recurring
+[bundle/persona grant](./granting-persona-bundle-access.md) request. On Compass it is *not* an ACL
+question at all — the `navigation` TAB_STRIP surface is gated **purely** by role-scoped
+`Client_Compass.SurfaceOverrides` rows. Nothing about `AclActionPermissions` participates.
+
+The trap is scope. The two users' role sets will differ by several roles, but usually only **one** of
+those roles carries navigation overrides. Granting the whole role diff hands over far more than
+navigation.
+
+All facts below were verified read-only against live `Client_Compass` on **2026-08-27**.
+
+## How Compass navigation is actually gated
+
+Two facts, both verified, that together mean the surface-override table is the *only* lever:
+
+1. **Every one of the six nav elements is seeded Core-base `isVisible = 0`.** Nothing is visible by
+   default; every visible menu item exists because some role turned it on.
+2. **Every one of them has `aclActionId = NULL`.** The element-level ACL gate inside
+   `resolve()` (`_Model_Client_AclActionPermission` → `aclActionId`, see
+   [Surface Resolver](../../../2.0/apps/_underscore/features/surface-resolver.md)) is therefore a
+   **no-op for navigation**. Do not go looking for a missing `AclActionPermissions` row; there was
+   never one to find.
+
+So visibility = exactly one thing: a `Client_Compass.SurfaceOverrides` row with
+`attribute = 'IS_VISIBLE'`, `value = 1`, scoped to a `roleId` the user holds.
+
+### `Core.SurfaceElements` ids for surface slug `navigation`
+
+| Element id | `config.path` | Nav item | `sortOrder` |
+|---|---|---|---|
+| 109 | `sales-orders` | Sales Orders | 10 |
+| 110 | `inventory` | Inventory | 20 |
+| 111 | `items` | Items | 30 |
+| 112 | `vendor-items` | Vendor Items | 40 |
+| 113 | `bundles` | Bundles | 50 |
+| 114 | `service-requests` | Service Requests | 60 |
+
+> **⚠ These ids sit OUTSIDE the team-reserved blocks.** The reserved-id table in
+> [Surface Resolver](../../../2.0/apps/_underscore/features/surface-resolver.md) and
+> [surface-layer-schema](../../../2.0/apps/dbchanges2/features/surface-layer-schema.md) lists
+> `Core.Surfaces` **41–43** / `Core.SurfaceElements` **125–146**. The `navigation` surface predates
+> those blocks and lives at elements **109–114**. Read the reserved blocks as "the decision-surface
+> reseed", not as an inventory of all surface ids.
+
+### The Compass override map (all `IS_VISIBLE`, `value = 1`, `personaId` NULL, `languageId` NULL)
+
+| Element | Roles granting visibility |
+|---|---|
+| 109 Sales Orders | **4** (Admin), **8** (Manager), **9** (Agilant - Administrators) |
+| 111 Items | **9** only |
+| 112 Vendor Items | **9** only |
+| 113 Bundles | **9** only |
+| 110 Inventory | **none — no override row for any role** |
+| 114 Service Requests | **none — no override row for any role** |
+
+## The diagnostic recipe ("same navigation as user Y")
+
+1. **Diff the two users' `Users_Roles` rows.** Here 289067 held roles 1, 4, 7, 12; the reference user
+   127046 held 1, 4, 5, 7, 9, 12, 15, 16 — a **four-role** gap (5, 9, 15, 16).
+2. **Intersect that diff against the roles that actually appear in the nav override map.** Only role
+   **9** did. Roles 5, 15 and 16 carry **no** nav overrides and were irrelevant to the request. A
+   four-role gap collapsed to a one-role decision. **Never grant the whole role diff.**
+3. **Identify whose bundle you are looking at by counting visible elements.** If a developer pastes a
+   surface bundle without saying which user it came from, match the visible set against the override
+   map. A bundle showing **4** visible items (sales-orders / items / vendor-items / bundles) is role
+   9's exact signature, so it belonged to 127046 — not to 289067, who holds only role 4 of the
+   nav-granting roles and therefore sees **Sales Orders alone**. Settling attribution first avoids
+   diagnosing the wrong user.
+4. **Pick the lever** (below), write the migration, hand it to the developer to run.
+
+### Two levers, and the tradeoff
+
+| Lever | Blast radius | Use when |
+|---|---|---|
+| **(a) Grant the missing role** — one additive `Users_Roles` row | affects only this user, but confers **all** of that role's record-CRUD, field and action grants, not just nav | the user genuinely *is* that persona |
+| **(b) Add role-scoped `SurfaceOverrides` rows** for a role the user already holds | surgical on nav, but widens nav for **every holder** of that role | the role is narrow and the nav change is intended tenant-wide |
+
+Lever (b) against a broad role such as 4 (Admin) is a **tenant-wide behavior change** dressed up as a
+per-user fix. For user 289067 the developer confirmed an internal Agilant user, so **(a)** was
+correct: grant `Agilant - Administrators` additively.
+
+## The migration
+
+`dbchanges2/Client_Compass/2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql` — additive
+`Users_Roles` insert for user 289067; roles 1, 4, 7, 12 are left intact.
+
+Three house-style points it demonstrates:
+
+- **Resolve the role by name subselect, not a hardcoded id.** `Roles.id` differs per client DB, so the
+  file matches `WHERE r.name = 'Agilant - Administrators'`. The subselect stays entirely inside
+  `Client_Compass`, so the file names only tables in its own database and is cluster-safe.
+- **Wrap the idempotency guard in a derived table.** The guard reads the INSERT's own target table,
+  which trips MySQL error 1093 (and, unwrapped, can see its own new row mid-statement):
+
+  ```sql
+  AND r.id NOT IN (
+      SELECT roleId FROM (
+          SELECT DISTINCT roleId FROM Users_Roles WHERE userId = 289067
+      ) AS existing
+  )
+  ```
+
+  Same dodge documented in
+  [Re-runnable additive INSERTs](../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md).
+- **Pre-generate the v4 UUID as a literal** — never `UUID()`.
+
+## Gotchas
+
+- **⚠ Inventory (110) and Service Requests (114) are unreachable for the ENTIRE Compass tenant.** No
+  role — not even Agilant - Administrators — has an `IS_VISIBLE` override for them, and Core base is
+  `0`. Copying "the same nav as the admin user" will *not* surface them. This was found, not fixed, on
+  2026-08-27 and needs its own ticket.
+- **Role permissions resolve as a union**, so an additive `Users_Roles` row never takes access away —
+  see [ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md). The flip
+  side is that it also grants everything else the role carries.
+- **Verifying the change requires a LOGOUT, not a reload.** Surface meta is cached
+  `staleTime`/`gcTime` `Infinity` **and persisted to `localStorage`** under
+  `supply-chain-query-cache`, so a hard reload restores the stale bundle and proves nothing. There is
+  no server-side surface cache. Full detail in
+  [Surface Frontend](../../../2.0/apps/toga25-supply/features/surface-frontend.md).
+- **`aclActionId` is NULL on all six nav elements** — resist the instinct to reach for
+  `AclActionPermissions` when a menu item is missing. It is always a `SurfaceOverrides` row.
+
+## Change history
+- 2026-08-27 — Initial: documented that Compass `navigation` is gated **solely** by role-scoped
+  `SurfaceOverrides IS_VISIBLE` rows (all six elements are Core-base `isVisible = 0` with
+  `aclActionId = NULL`, so the element ACL gate is a no-op); recorded the element-id → role map
+  (109/111/112/113; role 9 is the only role granting Items/Vendor Items/Bundles) and that
+  `SurfaceElements` **109–114** sit **outside** the reserved 125–146 block. Added the diff-then-
+  intersect diagnostic recipe (a four-role gap for user 289067 collapsed to role 9 alone), the
+  visible-element-count trick for attributing a pasted bundle, and the role-grant vs. SurfaceOverride
+  tradeoff. Flagged that **Inventory and Service Requests are visible to no Compass role at all**.
+  Migration `2026-08-27a - GrantAgilantAdministratorsRoleToInternalUser.sql` written on branch
+  `TRUE-81325` — not committed, not executed. (apeterson)

package/knowledge/clients/compass-usa/workflows/granting-persona-bundle-access.md

@@ -11,6 +11,7 @@ owners: [bala]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
 related:
+  - ./granting-navigation-access.md
   - ../features/persona-model-and-levy-gating.md
   - ./persona-refactor-migration.md
   - ./persona-population-env-comparison.md

package/package.json

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