toga-ai 1.0.778 → 1.0.779

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [jcardinal, apeterson, bala]
 files:
   - _underscore/Model/Client/Language.php
@@ -155,6 +155,32 @@ boolean rows; the item-record modal (the first boolean consumer) exposed the gap
 `_underscore`, so it takes effect only once the framework branch is deployed (framework is pulled at
 deploy).
 
+### 🚨 A message key inside `config` JSON is NEVER resolved — copy must ride a `*MessageId` column
+
+`_buildBundle`/`_serializeElement` build `bundle.messages` by scanning **exactly six columns** on
+`SurfaceElements` — `labelMessageId`, `tooltipMessageId`, `placeholderMessageId`,
+`disabledTooltipMessageId`, `trueMessageId`, `falseMessageId` (`Surface.php` ~L600). **`config` is
+passed through untouched and is never scanned for message keys.** A key written into `config`
+therefore ships to the frontend with **no value behind it**, and the screen renders the raw key.
+
+This is a load-bearing constraint on how *any* surface-driven copy is modelled: **one string = one
+`SurfaceElement` message column.** There is no way to attach copy to a nested `config` blob.
+
+**Real case (2026-09-03).** The Columns modal rendered `common.columns.modal.apply` as its Apply
+button label. `Core/2026-08-28b` had put the seven `common.columns.modal.*` keys inside the
+`columnsButton` element's `config.modal` — data that looks right and can never resolve. The chosen
+fix was **not** to teach the resolver to scan `config` (that widens the message-resolution contract
+for every surface); it was to give the modal **its own MODAL Surface** so every string rides a real
+`*MessageId` on its own element and the existing collector resolves it with **zero `_underscore`
+change**. See
+[column-visibility](../../toga25-supply/features/column-visibility.md).
+
+**Diagnostic order.** When the FE shows a raw message key, first check whether the key rides a
+`*MessageId` column — *before* suspecting an unrun seed. The resolved bundle in the API response is
+the proof: if the element is present but `bundle.messages` has no entry for the key, the seed ran and
+the modelling is wrong. (This session's first diagnosis — "the seed hasn't run" — was wrong, and the
+pasted API response is what disproved it.)
+
 ## FIELD elements bound to a RecordField — see the dedicated doc
 
 A `renderType = FIELD` element with a non-null `recordFieldId` gets `Core.RecordFields` metadata and
@@ -755,6 +781,13 @@ full stop. See
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-09-03 — Recorded a **hard constraint on message resolution**: the resolver collects
+  `bundle.messages` from **only** the six `*MessageId` columns on `SurfaceElements`; a message key
+  placed inside `config` JSON is **never** resolved and renders raw on screen. Found when the Columns
+  modal displayed `common.columns.modal.apply`; `Core/2026-08-28b` had seeded those keys into
+  `config.modal`. Fixed in data, not in the framework — the modal became its own MODAL Surface
+  (Core 60) so each string rides a real `*MessageId`. Also recorded the diagnostic order: a raw key
+  means "check the modelling" before "check whether the seed ran". (apeterson)
 - 2026-09-01 — Split the new **FIELD ↔ RecordField binding** capability out into its own doc
   ([surface-field-recordfield-binding](surface-field-recordfield-binding.md)) rather than growing this
   one: for a `renderType=FIELD` element with a `recordFieldId`, `_buildBundle` now folds on

package/knowledge/2.0/apps/dbchanges2/workflows/targeting-the-right-database.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: [apeterson]
 files:
   - api2/Config/production.ini
@@ -65,6 +65,20 @@ setpw() {
 `MYSQL_PWD` keeps the password out of `ps` and history the same way a defaults file does — use it
 when the client rejects `--defaults-extra-file` (some builds do).
 
+**Check the password's line SHAPE without ever seeing the value.** Mask every character that is not
+a space, tab, `;`, or `"` — you learn whether the value is quote-wrapped and whether an inline `;`
+comment is in play, and the secret never reaches your screen or scrollback:
+
+```bash
+awk -v S=database '$0=="["S"]"{f=1;next} /^\[/{f=0} f && /^password/{
+  k=$0; sub(/=.*/,"=",k); v=$0; sub(/^[^=]*=/,"",v); gsub(/[^ \t;"]/,"x",v);
+  print "[" k v "]"; exit}' Config/production.ini
+```
+
+On `production.ini` `[database]` this printed `[password = "xxxxxxxx"]` (checked 2026-09-04): the
+double-quote wrap is real, and there is **no inline `;` comment** on password lines — so `setpw`
+above, which strips quotes only, is correct as written and needs no comment handling.
+
 **Keep the password out of your shell history and out of `ps`** by building a throwaway
 credentials file from the ini instead of passing `-p` on the command line:
 
@@ -93,10 +107,25 @@ Delete the file when you are done.
 
 ## Resetting a shared environment from production (dump → drop → reload)
 
-Used 2026-09-03 to bring sandbox-client's stale `Client_Nychh` TableViews back in line with prod.
-The developer runs every one of these; do not execute them for them.
-
-1. **Dump each source database**, one file each — prod `Core` from
+Used 2026-09-03 to bring sandbox-client's stale `Client_Nychh` TableViews back in line with prod,
+and again 2026-09-04 (`Core` + `Client_Nychh`). The developer runs every one of these; do not
+execute them for them.
+
+1. 🚨 **Inventory what the reset will DESTROY — before you drop anything.** A shared non-prod
+   environment is normally *ahead* of prod, because that is where changes get tried first, so a
+   prod→sandbox reload silently rolls that lead back. List every `dbchanges2` file dated after the
+   last prod release, plus anything parked in `git stash`, and decide which ones must be re-run.
+   Candidates from the 2026-09-04 sandbox-client reset, all *potentially* sandbox-only:
+   - `Core/` — 2026-09-01a, -01c, -01d, -02a, -02b, -03a, -03b, -03c, -03d
+   - `Client/` — 2026-09-01b, -01c, -02a
+   - `Client_Nychh/` — 2026-09-02a, -03a, -03b
+   - `dbchanges2` `stash@{0}` ("TO qty fulfilled core seed"), which is applied nowhere
+
+   **Verify every candidate against the environment — never assume the list.** After this reset
+   sandbox read `Core.Surfaces` = 54, which means some of those Core surface files were **already in
+   prod** and must not be re-run. The repo records intent, not deployed state — see
+   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
+2. **Dump each source database**, one file each — prod `Core` from
    `reader1.core.database.togahub.com`, prod tenant from `reader1.client.database.togahub.com`:
    ```
    mysqldump --single-transaction --quick --routines --triggers --events \
@@ -104,14 +133,17 @@ The developer runs every one of these; do not execute them for them.
    ```
    `--set-gtid-purged=OFF` because RDS has GTID on; `--no-tablespaces` because the `admin` user
    lacks `PROCESS` (otherwise **error 1227**).
-2. 🚨 **`tail -1` every dump file and confirm it ends with `-- Dump completed` BEFORE you drop
+3. 🚨 **`tail -1` every dump file and confirm it ends with `-- Dump completed` BEFORE you drop
    anything.** A truncated dump loads without complaining. DNS dropped mid-session on a host that
    had resolved seconds earlier (`ERROR 2005 Unknown MySQL server host`) — the dump just stops.
-3. **Prove which environment each connection actually reached.** Better than `@@hostname`: check the
+4. **Prove which environment each connection actually reached.** Better than `@@hostname`: check the
    resolved IP — production resolves into **`10.201.x`**, sandbox into **`10.200.x`**.
-4. **Drop + create the target schema, then pipe the dump in.**
-5. **Verify with a row count known to differ** (step 1 of the procedure above), against the schema
-   you intended to copy.
+5. **Drop + create the target schema, then pipe the dump in.**
+6. **Verify with a row count known to differ** (step 1 of *before you trust ANY tenant dump*,
+   above), against the schema you intended to copy.
+7. **Re-run the step-1 migrations that prod did not already have, in `Core/` → `Client/` fan-out →
+   `Client_<Tenant>/` order.** Client files reference Core record ids, and the client work needs the
+   columns the `Client/` fan-out adds — any other order fails or half-applies.
 
 ### ⚠ Which `mysql` / `mysqldump` binary you are running is load-bearing
 
@@ -120,10 +152,23 @@ The developer runs every one of these; do not execute them for them.
   `xamppfiles/bin/mysqldump` is **MariaDB 10.4** (rejects the flag);
   `xamppfiles/mysql/bin/mysqldump` is **MySQL 8.0.44** (correct). Run `mysqldump --version` before
   you trust it.
-- **A shell alias can hijack a remote connection.** XAMPP's `mysql` alias hardcodes
-  `-uroot -pmysql --socket=…`, so a command you wrote for a remote host silently talks to localhost.
-  Call the client by **full path** for anything remote — and remember an exact match with your local
-  DB is evidence of a bad restore, not a good one (see the gotcha below).
+- 🚨 **A shell alias hijacks a remote connection — and the error names the wrong problem.** On an
+  XAMPP machine `~/.zshrc:31` defines
+  `alias mysql='/Applications/XAMPP/xamppfiles/mysql/bin/mysql -u root -p<pw> --socket=…'`. A later
+  `-u admin` on the command line wins for the **user**, but the alias's `-p<pw>` **overrides
+  `MYSQL_PWD`** — so every `mysql -h <remote-host> -u admin …` dies with
+  `ERROR 1045 (28000): Access denied for user 'admin'@'<your ip>' (using password: YES)`, *against
+  the correct remote host*. That reads as a rotated credential, a missing grant, a VPN problem, or
+  the double-quote trap above, and it is none of them. (The same alias can also silently talk to
+  localhost when its `--socket` wins — two symptoms, one cause.)
+  - **The tell: `mysqldump` to the SAME host with the SAME `MYSQL_PWD` succeeds while `mysql`
+    1045s.** Only `mysql` is aliased, not `mysqldump`. "Dump works, `mysql` denied" identifies the
+    alias immediately — check that before you go near the password extractor or the ini quoting.
+  - **Fix:** call the binary by full path
+    (`MYSQL=/Applications/XAMPP/xamppfiles/mysql/bin/mysql`). `\mysql` or `command mysql` also skip
+    alias expansion.
+  - An exact match with your local DB is evidence of a bad restore, not of a good one (see the
+    gotcha below).
 
 ## Gotchas
 
@@ -137,6 +182,12 @@ The developer runs every one of these; do not execute them for them.
   makes the dump a point-in-time snapshot, so a live table keeps moving after it: `Units` read 8,627
   on prod and 8,618 on the restored sandbox. Do not chase that; only a *category* difference
   (missing tables, order-of-magnitude counts) means the restore was wrong.
+  - **The reference counts written down here go stale too.** After the 2026-09-04 reset,
+    sandbox-client read `Core.Surfaces` = **54** and `Client_Nychh.TransferOrders` = **1,932**,
+    against the prod figures previously recorded here — 53 (2026-09-03) and 1,927 (2026-08-31).
+    Prod itself moved on. Restored counts landing slightly **above** an older recorded prod number
+    is the expected pattern, not evidence of a bad restore. Re-read the count from the source at
+    reset time instead of comparing to a number in this doc.
 - 🚨 **The `dbchanges2` folder name IS the target database — pipe each folder to its own DB.**
   `Core/` → `Core`, `Client_<Name>/` → that one tenant, `Client/` → **every** tenant. Files reference
   tables **unqualified** by design (the cluster-isolation rule), so running a `Core/` file against a
@@ -157,6 +208,17 @@ The developer runs every one of these; do not execute them for them.
   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
 
 ## Change history
+- 2026-09-04 — Second sandbox-client reset (`Core` + `Client_Nychh`) from prod; the procedure held,
+  three gaps closed. Added a mandatory **step 1 — inventory what the reset will destroy** (a shared
+  non-prod environment is normally ahead of prod, so the reload rolls that lead back), with the
+  2026-09-04 candidate file list and the unapplied stash, plus a **step 7** to re-run them in
+  `Core/` → `Client/` → `Client_<Tenant>/` order. Sharpened the shell-alias bullet: the real symptom
+  is **`ERROR 1045` against the CORRECT remote host** (the alias's `-p<pw>` beats `MYSQL_PWD`), not a
+  silent localhost connection — and the tell is that `mysqldump` works while `mysql` is denied,
+  because only `mysql` is aliased. Added a value-safe way to inspect an ini password's line shape
+  (confirms the double-quote wrap and that there is no inline `;` comment, so `setpw` needs no
+  change). Refreshed the expected-drift numbers and noted that recorded reference counts age.
+  (apeterson)
 - 2026-09-03 — Added the **reset-a-shared-environment-from-production** procedure (the `mysqldump`
   flag set, `--set-gtid-purged=OFF` for RDS GTID, `--no-tablespaces` for the missing `PROCESS`
   grant, the mandatory `tail -1` "`-- Dump completed`" check because a truncated dump loads

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

@@ -8,7 +8,7 @@
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. | toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/api/CartApi.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
-| [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP | toga2-commerce/src/App.tsx, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |
+| [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP | toga2-commerce/src/App.tsx, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/api/axiosInstance.ts, toga2-commerce/src/hooks/useAuthenticationFlow.ts, toga2-commerce/src/components/NavIcons/NavIconList.tsx, toga2-commerce/src/pages/BundleView/hooks/useBundleQueryData.ts, toga2-commerce/src/pages/Home/viewModel/useHomeViewModel.ts, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |
 | [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one | src/pages/Filter/api/FilterApi.ts, src/pages/Filter/viewModel/useFilterViewModel.ts, api2/Component/Api/V2/V2.php, toga2-supply/src/pages/Items/api/itemsApi.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/contexts/helpers/getLoginSettings.ts, src/pages/Account/viewModel/useAccountViewModel.ts, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json, src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HEADERFIELDS.json, src/components/AuthLayout/AuthLayout.tsx |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |

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

@@ -6,15 +6,21 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
-owners: ["bala"]
+updated: 2026-09-03
+owners: ["bala", "apeterson"]
 files:
   - toga2-commerce/src/App.tsx
   - toga2-commerce/src/contexts/AuthContext.tsx
+  - toga2-commerce/src/api/axiosInstance.ts
+  - toga2-commerce/src/hooks/useAuthenticationFlow.ts
+  - toga2-commerce/src/components/NavIcons/NavIconList.tsx
+  - toga2-commerce/src/pages/BundleView/hooks/useBundleQueryData.ts
+  - toga2-commerce/src/pages/Home/viewModel/useHomeViewModel.ts
   - toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts
 related:
   - ./inactive-item-purchase-gating.md
   - ../architecture.md
+  - ../../toga25-supply/features/persisted-query-cache.md
   - ../../toga25-supply/features/force-logout-on-deployment.md
 ---
 
@@ -30,26 +36,37 @@ switched back on, it stays hidden.
 Any query whose answer **gates an action** (can this be bought? is this still available?) must be
 opted out of *both* mechanisms. Opting out of one is not enough.
 
+**Three long-running production complaints all trace back to this file set**, and were pinned to
+`file:line` on 2026-09-03 (read-only, branch `TRUE-81610`): "users don't see updated data",
+"clearing their cache doesn't work", and "users get stuck on a broken login page after a forced
+logout". They are **four separate causes**, listed below. Nothing has been fixed yet.
+
 ## How it works
 
 ### The default: cached and persisted
 
-`src/App.tsx` creates the client with `staleTime: 1000 * 60 * 60 * 24` and a
-`createSyncStoragePersister` on `localStorage` key `"commerce"`. Everything inherits that unless it
-overrides it — including the `["clientFields", …]` query that carries the per-tenant `FIELDS`
-content, which is why copy/config deploys also look stale for returning users (see the
-[architecture gotchas](../architecture.md#gotchas)).
+`src/App.tsx:26-31` creates the client with `staleTime: 1000 * 60 * 60 * 24` and a
+`createSyncStoragePersister` on `localStorage` key `"commerce"` (`src/App.tsx:34-37`). Everything
+inherits that unless it overrides it — including the `["clientFields", …]` query that carries the
+per-tenant `FIELDS` content, which is why copy/config deploys also look stale for returning users
+(see the [architecture gotchas](../architecture.md#gotchas)).
+
+For comparison, **TOGa 2.5 Supply's default is `staleTime: 0`** *because* its cache is persisted.
+Same library, same persister, opposite default. See
+[supply's persisted query cache](../../toga25-supply/features/persisted-query-cache.md).
 
-### The platform's cache-bust: `META_LAST_REFRESH_DATETIME`
+### The platform's cache-bust: the Core parameters blob
 
-The **only** mechanism that clears the persisted cache for everyone is the Core parameter
-**`META_LAST_REFRESH_DATETIME`** (`Core.Parameters` id 32). `src/contexts/AuthContext.tsx` polls it
-with `staleTime: 0` **on every route change and on window focus**; when the value differs from the
-one captured at login it calls `logout()` and forces a full reload, which clears the saved cache.
+`src/contexts/AuthContext.tsx:192-252` runs a `["fetchCoreParameters"]` query with `staleTime: 0`
+and `refetchOnWindowFocus: true`, plus a refetch on every route change. On the first fetch after
+login it stores the whole response as a baseline; on any later fetch it **string-compares the
+entire core-parameters JSON** against that baseline and, on **any** difference, calls `logout()` and
+`window.location.href = "/"`.
 
-> **⚠ Bumping that parameter logs out EVERY user on that environment.** It is a deployment-grade
-> lever, not a way to refresh one catalogue change. The sibling implementation in TOGa 2.5 Supply
-> is documented in
+> **⚠ It is not keyed on `META_LAST_REFRESH_DATETIME` alone — it compares the whole blob.** Any
+> Core parameter change on that environment logs out **every** user. It is a deployment-grade
+> lever, not a way to refresh one catalogue change. The narrower, notice-first sibling in TOGa 2.5
+> Supply is documented in
 > [force logout on deployment](../../toga25-supply/features/force-logout-on-deployment.md).
 
 ### Opting a single query out — `staleTime: 0` + `gcTime: 0` is NOT sufficient on its own
@@ -68,6 +85,13 @@ const shouldDehydrateQuery = (query) => {
 // … persistOptions: { dehydrateOptions: { shouldDehydrateQuery } }
 ```
 
+> **⚠ CORRECTION (verified 2026-09-03): this exclusion is NOT in production.** `shouldDehydrateQuery`
+> exists only on `origin/_beta` and `origin/#sprint84`. `origin/_production`, `origin/_sandbox`,
+> `origin/_dev` and `TRUE-81610` all pass `persistOptions: { persister: localStoragePersister }`
+> with **no `dehydrateOptions` at all** — so **nothing is excluded from persistence in production**,
+> and the inactive-item purchase gate it was built for is not actually protected there. Confirm the
+> branch before relying on this section.
+
 **Why the exclusion is required:** `gcTime: 0` only evicts a query once it becomes **inactive**. An
 **active** query — exactly the state the item page is in while the user is looking at it — is still
 dehydrated and written to `localStorage`, and is rehydrated on the next load. So `gcTime: 0` alone
@@ -80,6 +104,104 @@ every other query, so this is an allowlist-shaped opt-out with no app-wide side
 decision; making every listing uncached would trade a real performance characteristic for no
 correctness gain.
 
+## The four stacked causes behind the production complaints
+
+Verified 2026-09-03 on branch `TRUE-81610`. Read-only; none of these are fixed.
+
+### 1. App-wide 24h `staleTime` + persisted cache with nothing excluded → daily stale data
+
+`src/App.tsx:26-31` (24h default) plus a persisted cache and no `dehydrateOptions` means
+**yesterday's queries are served today with no network call**. This is the "users not seeing
+updated data" report, and it happens **daily** — not only after a deploy.
+
+The same 24h value is **also hardcoded per-hook**, so changing only the default is not enough:
+
+- `src/pages/BundleView/hooks/useBundleQueryData.ts:26,40`
+- `src/pages/Home/viewModel/useHomeViewModel.ts:150,173,197`
+
+### 2. Cache clears are not gated on restoration → they are silently undone
+
+`PersistQueryClientProvider` renders children **while still restoring**
+(`react-query-persist-client/build/modern/PersistQueryClientProvider.js`: `isRestoring` starts
+`true`, `persistQueryClientRestore` resolves later). A `queryClient.clear()` +
+`localStorage.removeItem("commerce")` that runs before restore finishes is **undone** — the pending
+restore hydrates the old cache on top, and the persist subscription writes it back.
+
+All three clearing sites are unguarded:
+
+| Site | What it clears |
+|---|---|
+| `src/contexts/AuthContext.tsx:180-183` | logout |
+| `src/components/NavIcons/NavIconList.tsx:162-170` | view-as / persona switch (language-specific data) |
+| `src/api/axiosInstance.ts:46` | 401 forced logout |
+
+**This is the "it's not successfully clearing their caches" report.** Supply already solved it with
+an `awaitRestoration()` promise built from `useIsRestoring()`
+(`toga25-supply/src/contexts/AuthContext.tsx:56-77`) and gates every clear behind it.
+
+### 3. Two auth gates read two different localStorage keys → stuck on a broken login page
+
+- The axios request interceptor gates on **`user`** (`src/api/axiosInstance.ts:112-118`). With no
+  `user` it calls `fetchPublicToken()`, which POSTs `/auth/public` and **writes the public token
+  back as `accessToken`** (`src/api/axiosInstance.ts:53-64`).
+- But `src/hooks/useAuthenticationFlow.ts:213-217` gates on **`accessToken`** and returns early if
+  it exists.
+
+So after a forced logout: the first API call writes a *public* `accessToken`, the auth flow sees a
+token, skips **both** the SSO redirect and `/login`, and the user is logged out while the app
+believes they are not.
+
+Supply gates on `user` — with an explicit comment at
+`toga25-supply/src/contexts/AuthContext.tsx:47-51`. This is the app-side twin of the blox
+`fetchPublicToken` gotcha already recorded in `2.0/standards/frontend.md` §22.
+
+### 4. The forced logout is too aggressive, and login never clears the cache
+
+`src/contexts/AuthContext.tsx:192-252`:
+
+- On **any** core-parameter change it calls `logout()` + `window.location.href = "/"` with **no
+  notice** to the user. On an SSO client `/` re-triggers the IdP.
+- It **monkey-patches `window.history.pushState` and `replaceState`** (`:216-226`) to refetch on
+  every navigation. react-router uses those same methods.
+
+Separately, commerce's `login()` (`:100-148`) **never clears the cache**, so signing in as a
+different user inherits the prior user's data for up to 24h. Supply clears on login.
+
+## Decision — `gcTime` is the speed knob, `staleTime` is the correctness knob
+
+Decided 2026-09-03. The 24h `staleTime` was reached for to make heavy item/bundle pages feel fast.
+**It is the wrong knob, and it buys zero perceived speed here.**
+
+- React Query **paints cached data instantly regardless of `staleTime`**. `staleTime` only controls
+  whether it *also* refetches in the background. `gcTime` controls how long the cached copy is kept
+  at all.
+- Commerce gates **every** loading state on `isLoading`, never `isFetching`
+  (`useBundleQueryData.ts:22,35`; `useHomeViewModel.ts:136,157,177`). `isLoading` is `false`
+  whenever cached data exists. So **lowering `staleTime` shows no extra spinner** — the 24h value
+  only suppresses the refetch.
+- **`gcTime` is set nowhere in commerce**, so it is the 5-minute default. Navigating away from Home
+  for 6+ minutes and back drops the query from memory and **does** show a real spinner today,
+  despite the 24h `staleTime`. The persisted cache only helps a full reload, not in-session
+  navigation. **Fixing `gcTime` is the actual speed win.**
+
+**Agreed shape for heavy queries:**
+
+```ts
+staleTime: 30_000,            // stops a refetch storm on Home → bundle → Home clicks;
+                              // never survives a session or a deploy
+gcTime: 1000 * 60 * 60,       // the real perceived-speed knob
+refetchOnWindowFocus: false,
+```
+
+Keep the **app default at `0`**, like supply.
+
+**Caveat still open:** if a payload drives a **price or a stock count**, that query must gate its
+spinner on **`isFetching`**, not `isLoading` — a wrong price shown for one second is a real
+problem, unlike a stale item list. Which commerce queries those are is **not yet answered**.
+
+**Rejected:** keeping the 24h `staleTime` "for speed" (verified it buys none), and `staleTime: 0`
+on the heavy hooks (too many repeats of a large payload).
+
 ## Gotchas / known issues
 
 - **⚠ Never verify a catalogue or FIELDS change on a warm browser.** Clear
@@ -87,18 +209,42 @@ correctness gain.
   rehydrated cache.
 - **⚠ `gcTime: 0` does not stop persistence.** Active queries are still dehydrated. Exclude the key
   via `dehydrateOptions.shouldDehydrateQuery` as well.
-- **⚠ `META_LAST_REFRESH_DATETIME` is not a targeted invalidation** — it force-logs-out every user
-  on the environment. Use per-query opt-out or `queryClient.invalidateQueries` for anything
-  narrower.
-- **A `persistOptions.buster` keyed on the build version** would fix stale FIELDS at deploy time but
-  invalidates every persisted query app-wide — still an **open team decision, not implemented**
-  (carried over from the architecture doc).
+- **⚠ Nothing is excluded from persistence on `_production`** — the `shouldDehydrateQuery`
+  allowlist lives only on `_beta`/`#sprint84`. Check the branch.
+- **⚠ The core-parameters watcher is not a targeted invalidation** — any Core parameter change
+  force-logs-out every user on the environment. Use per-query opt-out or
+  `queryClient.invalidateQueries` for anything narrower.
+- **⚠ A `queryClient.clear()` that is not awaited behind cache restoration is undone.** All three
+  of commerce's clear sites have this bug.
+- **⚠ Gate auth on `user`, never `accessToken`** — `fetchPublicToken` writes a public token into
+  `accessToken`.
+- **A `persistOptions.buster` keyed on the build version** would fix stale data at deploy time.
+  Commerce has a committed `amplify.yml`, so injecting `AWS_COMMIT_ID` as a build id is
+  straightforward here (`package.json` `version` is `0.0.0` and `vite.config.ts` has no `define`
+  block, so the id must be created first). Mechanics and the scope limit — a buster runs inside the
+  app and can never fix a browser-cached JS bundle — are written up in
+  [supply's persisted query cache](../../toga25-supply/features/persisted-query-cache.md#the-buster-gap).
+  Still **not implemented**.
 - **`AuthLayout` never remounts**, so `refetchOnMount` fires once per session for queries it owns —
   a route-change refresh has to be wired explicitly. That interacts with everything above: a query
   can be both stale *and* never refetched during a session.
 
 ## Change history
 
+- 2026-09-03 — Read-only diagnosis (branch `TRUE-81610`). **Corrected** this doc: the
+  `shouldDehydrateQuery` opt-out it described exists only on `origin/_beta` / `origin/#sprint84` —
+  `_production`, `_sandbox`, `_dev` have **no `dehydrateOptions`**, so nothing is excluded from
+  persistence in production. Also corrected the cache-bust: `AuthContext` string-compares the
+  **whole core-parameters blob**, not just `META_LAST_REFRESH_DATETIME`, so any Core parameter
+  change logs out every user. Added the four stacked causes behind the standing production
+  complaints (app-wide 24h `staleTime` also hardcoded in `useBundleQueryData`/`useHomeViewModel`;
+  all three cache clears unguarded against the `PersistQueryClientProvider` restore race; the
+  `user`-vs-`accessToken` gate split that leaves a user logged out while the app thinks otherwise;
+  the notice-less forced logout that monkey-patches `history.pushState`, plus `login()` never
+  clearing the cache). Recorded the decision that **`gcTime` is the speed knob and `staleTime` is
+  the correctness knob** — commerce gates every spinner on `isLoading`, so the 24h `staleTime` buys
+  no perceived speed, while `gcTime` is at its 5-minute default and *is* the real cause of slow
+  in-session navigation. No code changed. (apeterson)
 - 2026-08-14 — Created while building the
   [inactive-item purchase gate](./inactive-item-purchase-gating.md). Recorded that the 24h
   persisted cache masks catalogue state **in both directions** (a switched-off item kept rendering

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

@@ -9,12 +9,13 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql |
 | [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/TransferOrders/viewModel/useTransferOrdersPageViewModel.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 |
+| [Persisted React Query cache (localStorage `supply-chain-query-cache`)](features/persisted-query-cache.md) | `localStorage["supply-chain-query-cache"]` is **not a hand-written cache**. | toga25-supply/src/App.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/hooks/useCurrentUser.ts, toga25-supply/src/hooks/useStatusTypeValues.ts, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/vite.config.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/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, 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, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css |
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. | toga25-supply/src/routes.tsx, toga25-supply/src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts, api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [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/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.test.ts, toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, 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/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Bundles/viewModel/useBundlesPageViewModel.tsx, toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx, 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, live Aegra streaming, LangGraph→blox mapper)](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/api/talos.ts, toga25-supply/src/hooks/useTalosSession.ts, toga25-supply/src/hooks/useTalosThreads.ts, toga25-supply/src/hooks/useTalosThreads.test.ts, toga25-supply/src/hooks/useTalosSurface.ts, toga25-supply/src/hooks/useTalosSurface.test.ts, toga25-supply/src/App.tsx, toga25-supply/db-migrations/PLAYBOOK.md, dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, toga25-supply/src/providers/TalosStreamProvider.tsx, toga25-supply/src/utils/talosMessages.ts, toga25-supply/src/utils/talosMessages.test.ts, 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 |
-| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/PanelSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/ContactSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/SelectTargetLocationModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferItemPickerTable.tsx, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderNote.php, _underscore/Model/Client/TransferOrderNoteType.php, dbchanges2/Client/2026-09-01b - TransferOrderNotesTables.sql, dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql, dbchanges2/Core/2026-09-01c - TransferOrderNotesRecords.sql, dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql, toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, toga25-supply/src/pages/TransferOrders/TransferOrder.module.css, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
+| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/PanelSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/ContactSelect.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/SelectTargetLocationModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferItemPickerTable.tsx, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderNote.php, _underscore/Model/Client/TransferOrderNoteType.php, dbchanges2/Client/2026-09-01b - TransferOrderNotesTables.sql, dbchanges2/Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql, dbchanges2/Core/2026-09-01c - TransferOrderNotesRecords.sql, dbchanges2/Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql, toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, toga25-supply/src/pages/TransferOrders/TransferOrder.module.css, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Core/2026-09-03a - TransferOrderStatusBadgeRecordFields.sql, dbchanges2/Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql, dbchanges2/Core/2026-09-03b - InventoryCreateTransferOrderAction.sql, dbchanges2/Client_Nychh/2026-09-03b - InventoryCreateTransferOrderShow.sql, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx, _underscore/Model/Client/TransferOrderItem.php |
 | [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, toga25-supply/.env.development |
 | [Cypress Testing Harness (multi-tenant, fully stubbed)](workflows/cypress-testing.md) | The Cypress harness for `toga25-supply`: an **e2e** project and a **component** project, plus a stub layer that answers **every** `/v2` call so no test touches | toga25-supply/cypress.config.ts, toga25-supply/cypress/README.md, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/tenants.ts, toga25-supply/cypress/support/api/stubApi.ts, toga25-supply/cypress/support/api/envelope.ts, toga25-supply/cypress/support/api/users.ts, toga25-supply/cypress/support/api/surfaces.ts, toga25-supply/cypress/support/api/session.ts, toga25-supply/cypress/e2e/login.cy.ts, toga25-supply/cypress/e2e/emptyNavigation.cy.ts, toga25-supply/cypress/component/harness.cy.tsx, toga25-supply/cypress/fixtures/tenants/COMPASS/surfaces/navigation.json, toga25-supply/cypress/fixtures/tenants/COMPASSCANADA/surfaces/navigation.json, toga25-supply/cypress/fixtures/tenants/NYCHH/surfaces/navigation.json, toga25-supply/cypress/fixtures/tenants/QUAD/surfaces/navigation.json, toga25-supply/scripts/cypress.mjs, toga25-supply/tsconfig.node.json, toga25-supply/package.json |
 | [Porting a page (or query) from toga2-supply to toga25-supply](workflows/porting-a-page-from-toga2-supply.md) | `toga25-supply` re-implements pages that already exist in `toga2-supply`. | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/components/ui/Tables/hooks/useExportableData.tsx |

package/knowledge/2.0/apps/toga25-supply/features/persisted-query-cache.md

@@ -0,0 +1,211 @@
+---
+title: Persisted React Query cache (localStorage `supply-chain-query-cache`)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-09-03
+owners: ["apeterson"]
+files:
+  - toga25-supply/src/App.tsx
+  - toga25-supply/src/contexts/AuthContext.tsx
+  - toga25-supply/src/hooks/useDeploymentGuard.tsx
+  - toga25-supply/src/fieldsConfig/useClientFields.ts
+  - toga25-supply/src/surface/useFetchSurfaceMeta.ts
+  - toga25-supply/src/hooks/useCurrentUser.ts
+  - toga25-supply/src/hooks/useStatusTypeValues.ts
+  - toga25-supply/src/surface/useStatusColors.ts
+  - toga25-supply/vite.config.ts
+related:
+  - ./force-logout-on-deployment.md
+  - ./surface-frontend.md
+  - ./transfer-orders-page.md
+  - ../architecture.md
+  - ../../toga2-commerce/features/catalog-cache-freshness.md
+---
+
+## Summary
+
+`localStorage["supply-chain-query-cache"]` is **not a hand-written cache**. It is the **whole
+React Query cache**, dehydrated to localStorage by `PersistQueryClientProvider`. Every successful
+query in the app lands there and survives reloads *and* sessions.
+
+Two consequences drive most of the "it didn't deploy" / "I'm seeing yesterday's data" reports:
+
+1. The app default is **`staleTime: 0`** precisely because the cache is persisted. Any hook that
+   sets its own non-zero `staleTime` can serve **a previous session's answer and never fetch**.
+2. Nothing in the app invalidates the blob on deploy. There is **no `buster`**. Deploys are
+   covered separately, and only indirectly, by `DeploymentGuard` forcing a logout.
+
+Scattered warnings about this exist in several docs. This is the owning doc: mechanics, what is
+persisted, every reset path, and the `buster` gap.
+
+## How it works
+
+### Wiring
+
+```ts
+// src/App.tsx:27-30
+const localStoragePersister = createSyncStoragePersister({
+	storage: window.localStorage,
+	key: "supply-chain-query-cache",
+});
+```
+
+`PersistQueryClientProvider` (`src/App.tsx:33`) wraps the app. The `QueryClient` default is
+`staleTime: 0` (`src/App.tsx:18`).
+
+### What is persisted — everything except three namespaces
+
+`shouldDehydrateQuery` (`src/App.tsx:63-70`) keeps TanStack's default (persist successful queries)
+**minus** three query-key namespaces:
+
+| Excluded namespace | Why |
+|---|---|
+| `talos` | chat titles / assistant ids are per-session user data; must not sit on disk |
+| `surface-meta` | the surface bundle carries **permission and feature-gate** state |
+| `surface-meta-group` | same bundle, grouped endpoint |
+
+The surface exclusion is the important one. `useFetchSurfaceMeta` runs at `staleTime: Infinity`, so
+a *persisted* copy would never refetch — a permission **grant**, or worse a **revoke**, would not
+reach a browser that already had one until the persister's 24h `maxAge` expired. Excluding it costs
+one request per page load; the in-memory cache still covers every route change.
+`staleTime: Infinity` is safe there **only because** it is excluded from persisting.
+
+### Query key → API map
+
+| Query key | Request |
+|---|---|
+| `["table-data", slug, …]` | `getDataTableData` (blox) |
+| `["table-meta", slug]` | `GET /table-views/meta` (blox `components/Table/hooks/useFetchTablePageMeta.js:8`) |
+| `["status-colors", route]` | `GET /{route}?fields=slug,colorHex&sort=sortOrder` |
+| `["currentUser"]` | `GET /users` |
+| `["clientFields", slug, role]` | client `FIELDS` config |
+| `["status-type-values", routes]` | status enum values |
+| `["deploymentVersion"]` | `GET /core-parameters` |
+
+### The 24h `maxAge` is ONE timestamp for the whole blob
+
+The persister's default `maxAge` is 24h — confirmed at
+`node_modules/@tanstack/query-persist-client-core/build/modern/persist.js:10`. It is compared
+against a single `persistedClient.timestamp`, **not per query**. So the cache is either fully
+hydrated or **fully dropped** at restore. There is no partial expiry.
+
+### Reset paths — the only things that clear it
+
+1. **Login** — `src/contexts/AuthContext.tsx:113-114` (`await awaitRestoration()` then
+   `queryClient.clear()`), so signing in as a different user cannot inherit the prior user's data.
+2. **Logout** — `src/contexts/AuthContext.tsx:141-146` (same gate, plus `localStorage.clear()`).
+3. **A list page's Refresh button** — `queryClient.clear()` + `resetQueries(["table-data"])` on
+   SalesOrders, TransferOrders, ServiceRequests, Items, VendorItems, Bundles, Inventory.
+4. **The 24h `maxAge`** expiring at restore.
+
+That is all. A deploy is **not** on the list.
+
+### The restoration race, and `awaitRestoration()`
+
+`PersistQueryClientProvider` renders children **while still restoring** (`isRestoring` starts
+`true`; `persistQueryClientRestore` resolves later). A `queryClient.clear()` that runs before
+restore finishes is **silently undone** — the pending restore hydrates the old cache on top, and
+the persist subscription writes it straight back.
+
+Supply solves this at `src/contexts/AuthContext.tsx:56-77`: it turns `useIsRestoring()` into an
+awaitable promise and gates **every** clearing path behind it.
+
+```ts
+const isRestoring = useIsRestoring();
+// …resolve a promise once isRestoring flips false…
+const awaitRestoration = (): Promise<void> =>
+	restorationCompleteRef.current ?? Promise.resolve();
+
+// then, in login() and logout():
+await awaitRestoration();
+queryClient.clear();
+```
+
+**Any new cache-clearing code path must await this first.** TOGa Commerce does not, and its cache
+clears are undone — see
+[catalog cache freshness](../../toga2-commerce/features/catalog-cache-freshness.md).
+
+### Deploys are covered by DeploymentGuard, not by the cache
+
+`src/hooks/useDeploymentGuard.tsx` polls the Core parameter `META_LAST_REFRESH_DATETIME`
+(`GET /core-parameters`, `staleTime: 0`) every 5 minutes and on window focus. On a change it shows
+a toast for 2.5s (`LOGOUT_NOTICE_DELAY_MS`) and then signs the user out — which clears the cache
+via path 2 above. Details in
+[force logout on deployment](./force-logout-on-deployment.md).
+
+## The `buster` gap
+
+A `persistOptions.buster` is the standard way to drop a persisted cache on deploy. Mechanics
+(verified at `query-persist-client-core/build/modern/persist.js:20-24`):
+
+- `buster` is **one string, compared once at restore, before hydrate**.
+- If it differs from the stored one, the whole persisted cache is **deleted** (`removeClient()`)
+  instead of hydrated.
+- It must be **stable within a build and change per build**. A `Date.now()` buster would wipe the
+  cache on every page load.
+
+**Blocker: this repo has no build id.** `package.json` `version` is `0.0.0` (never bumped),
+`vite.config.ts` has **no `define` block**, and there is **no `amplify.yml`** — supply's Amplify
+build is console-configured. Amplify does set `AWS_COMMIT_ID` in the build environment, so the
+build id has to be created first:
+
+```ts
+// vite.config.ts
+define: { __BUILD_ID__: JSON.stringify(process.env.AWS_COMMIT_ID ?? "dev") }
+// src/vite-env.d.ts
+declare const __BUILD_ID__: string;
+// src/App.tsx
+persistOptions: { persister: localStoragePersister, buster: __BUILD_ID__, /* … */ }
+```
+
+Type-check **both** `-p tsconfig.app.json` and `-p tsconfig.node.json` — `vite.config.ts` is only
+covered by the node config.
+
+**Scope limit — a buster cannot fix a stale JS bundle.** It runs *inside* the app, so if the
+browser never downloaded the new app, the buster never runs. Diagnostic to tell the two caches
+apart:
+
+| Symptom | Cause | Does a buster help? |
+|---|---|---|
+| Hard refresh (Cmd+Shift+R) fixes it | bundle / CDN cache headers | No — irrelevant |
+| Only logging out fixes it | persisted query data | Yes |
+
+**Rejected alternative:** versioning the storage key (`…-v2`). It works, but leaves the old blob in
+localStorage forever; `buster` calls `removeClient()` and cleans up.
+
+## Gotchas / known issues
+
+- **⚠ A non-zero `staleTime` on a persisted query serves yesterday's data and never fetches.** Data
+  hooks in this app use `staleTime: 0`. Hooks that currently break this rule **and are persisted**:
+  `useClientFields`, `useCurrentUser`, `useStatusTypeValues`, `useStatusColors`,
+  `useSalesOrderUuidForServiceRequest` (all `Infinity`), and the three VendorItem form hooks
+  (`5 * 60_000`). Each can serve a previous session's answer.
+- `useTalosSession` and `useTalosThreads` also set a non-zero `staleTime`, but their keys start with
+  `talos`, so they are **not** persisted — in-memory only, safe.
+- **⚠ Never verify a config, surface, or ACL change on a warm browser.** Log out, or delete the
+  `supply-chain-query-cache` key in devtools. Most "it didn't deploy" reports are a rehydrated
+  cache.
+- **⚠ `gcTime: 0` does not stop persistence.** It only evicts a query once it becomes *inactive*;
+  an active query is still dehydrated. To keep something off disk, exclude its namespace in
+  `shouldDehydrateQuery`.
+- **⚠ Any new `queryClient.clear()` must `await awaitRestoration()` first**, or the restore race
+  undoes it.
+- The `maxAge` is one timestamp for the entire blob — you cannot expire a single query through it.
+
+## Change history
+
+- 2026-09-03 — Created. Consolidated the persisted-cache mechanics that were scattered across the
+  architecture doc and the surface/transfer-orders/talos features into one owning doc: the
+  three excluded namespaces and *why* surface-meta is excluded (permission/feature-gate state +
+  `staleTime: Infinity`), the query-key→API map, the four reset paths, that the 24h `maxAge` is a
+  **single timestamp for the whole blob** (all-or-nothing at restore), the `awaitRestoration()`
+  gate for the `PersistQueryClientProvider` restore race, and the full list of hooks that still set
+  a non-zero `staleTime` while being persisted. Also recorded the `buster` mechanics
+  (one string, compared before hydrate, deletes the whole cache on mismatch) and the blocker —
+  no build id exists in the repo (`version 0.0.0`, no `define`, no `amplify.yml`) — plus the fact
+  that a buster can never fix a browser-cached JS bundle. Read-only investigation; no code changed.
+  (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/transfer-orders-page.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
@@ -50,6 +50,15 @@ files:
   - dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql
   - dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql
   - dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql
+  - dbchanges2/Core/2026-09-03a - TransferOrderStatusBadgeRecordFields.sql
+  - dbchanges2/Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql
+  - dbchanges2/Core/2026-09-03b - InventoryCreateTransferOrderAction.sql
+  - dbchanges2/Client_Nychh/2026-09-03b - InventoryCreateTransferOrderShow.sql
+  - toga25-supply/src/surface/useStatusColors.ts
+  - toga25-supply/src/pages/Inventory/Inventory.tsx
+  - toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx
+  - toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx
+  - _underscore/Model/Client/TransferOrderItem.php
 related:
   - ./surface-frontend.md
   - ./meta-driven-table-data.md
@@ -109,6 +118,10 @@ tenant.
 | `Core/2026-09-01c - TransferOrderNotesRecords.sql` | Core | Records **357**/**358**, RecordFields **2550–2560**, `InherentRecordChildren` 312→357 — **also unused, and 357/358 have NO NYCHH ACL grant** |
 | `Client/2026-09-01c - TransferOrderContactCreatedByAndDescription.sql` | all tenants (template) | `TransferOrders.contactId` (FK Contacts), `createdByUserId` (FK Users), `description varchar(255)` |
 | `Core/2026-09-01d - TransferOrderContactCreatedByAndDescriptionRecordFields.sql` | Core | RecordFields **2561** `contactId` / **2562** `createdByUserId` / **2563** `description` on record 312, + `AclFieldPermissions` for roles **1** and **3** |
+| `Core/2026-09-03a - TransferOrderStatusBadgeRecordFields.sql` | Core | flips the stage RecordField to `type = 'STATUS'` + points `Records.statusRecordId` at the stage record — the badge chain |
+| `Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql` | one tenant | the ACL grants the badge's vocabulary fetch needs (incl. the **`uuid`** RecordField — see the gotcha) |
+| `Core/2026-09-03b - InventoryCreateTransferOrderAction.sql` | Core | the Inventory header **Create Transfer Order** action button, seeded `isVisible = 0` |
+| `Client_Nychh/2026-09-03b - InventoryCreateTransferOrderShow.sql` | one tenant | the `SurfaceOverrides` row that reveals it |
 
 All of them were audited against the cluster-isolation HARD RULE: **no `Core.*` reference in any
 `Client_*` file** (the only such strings are inside comments), no `UUID()`, all table references

package/knowledge/INDEX.md

@@ -31,7 +31,7 @@ _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) — 21 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 18 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 19 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 14 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)
 

package/knowledge/clients/nychh/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
@@ -58,6 +58,13 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   run the NetSuite→TOGa Supply sync and the asset-tag verification/backfill diagnostics.
 
 ## Key features (this client)
+- 🚨 **sandbox-client (`Core` + `Client_Nychh`) was reset from PRODUCTION again on 2026-09-04** —
+  the second reset in two days (the first, 2026-09-03, was over the stale `purchase-orders`
+  TableView). Every "verified on <date>" sandbox-client claim in this profile dated **before
+  2026-09-04 now describes whatever prod had**, not what is there. The 2026-09-01 → 2026-09-03
+  `dbchanges2` migrations may also need re-running on sandbox-client. Re-read the environment before
+  trusting any sandbox state below; procedure and the re-run order are in
+  [Targeting the right database](../../2.0/apps/dbchanges2/workflows/targeting-the-right-database.md).
 - **Transfer orders now push OUT to NetSuite as $0 sales orders (2026-09-02, built not yet run).**
   NYCHH is the first and only client on that path; it is switched on purely by its
   `transfer-orders` (record 312) `POST`/`POST` interceptor row. Destination location = NetSuite

package/package.json

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