toga-ai 1.0.760 → 1.0.762

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -202,6 +202,43 @@ Prudential-EDI, S&P Global**.
 - **Lesson:** any `sync*FromNetsuite()` that takes the record `&$byReference` and refetches must have
   its fetch-by-id shim carry **every** field the caller reads afterward — `lastModifiedDate` first.
 
+### ⚠ …but the by-reference shim wrote the cursor on the WRONG CLOCK → ITEM_RECEIPTS + ITEM_FULFILLMENTS re-matched forever (found + fixed 2026-09-03, NYCHH prod)
+
+A follow-on to the by-reference fix directly above. Once the two shims carried a `lastModifiedDate`
+again, the sections still could **not advance** — the value was in the **wrong timezone**, so
+`lastmodifieddate > cursor` re-matched the **same record every run** (an infinite loop, no crash).
+
+- **Root cause — two clocks.** The prior fix set `fetchItemFulfillmentById` / `fetchItemReceiptById`'s
+  `->lastModifiedDate` from the **REST record GET**, which returns **UTC** (e.g. `2024-08-06T14:45:00Z`).
+  `common_sync_togasupply.php` then `date()`-formats it in the script timezone **America/Chicago** →
+  `2024-08-06 09:45:00`, and stores that as the cursor. But the LIST fetch's `WHERE`
+  (`App_Api_Netsuite_Rest::listItem*`) compares `lastmodifieddate` via SuiteQL
+  `TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS')`, which is the **NetSuite account timezone =
+  Eastern** → `2024-08-06 10:45:16`. So the cursor was written **~1 hour behind** the clock the fetch
+  reads → `lastmodifieddate > cursor` was always still true for the record just processed → it was
+  re-fetched and re-processed forever and the watermark never moved.
+- **Proven on NYCHH prod** (item receipt internalId `4953915`): REST GET `lastModifiedDate`
+  `2024-08-06T14:45:00Z` (UTC) · SuiteQL `2024-08-06 10:45:16` (Eastern) · stored cursor
+  `2024-08-06 09:45:00` (Chicago). ITEM_RECEIPTS was jammed on it; because that heavy receipt (nested
+  PO→SO reconcile) runs **before** fulfillments and starved the run, ITEM_FULFILLMENTS' window kept
+  collapsing to 6s and never grew to clear the empty gap to its first real record (2025-01-06; 1,294
+  NYCHH fulfillments waited after 2025-01-01).
+- **INVENTORY_ADJUSTMENTS was NOT stuck** — `fetchInventoryAdjustmentById` already reads
+  `lastmodifieddate` from SuiteQL `TO_CHAR` (the right clock), so it advanced normally. **That is the
+  correct pattern**; the other two shims did not follow it.
+- **Fix (library only, `php -l` clean, fail-loud preserved):** in `library/app/api/netsuite/rest.php`,
+  `fetchItemFulfillmentById` (~L2093) and `fetchItemReceiptById` (~L2254) now set
+  `$shim->lastModifiedDate` from a SuiteQL
+  `SELECT TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS') AS lastmodifieddate FROM transaction WHERE id = $id`
+  (Eastern) — matching `fetchInventoryAdjustmentById` — **instead of** the REST header's UTC
+  `$header->lastModifiedDate`. No shim reads the REST/UTC `lastModifiedDate` anymore. No worker change,
+  no SQL. After deploy the two sections resume and backfill on their own (idempotent).
+- **Lesson:** the per-record cursor value MUST be written in the **same timezone the fetch `WHERE`
+  compares against** — SuiteQL account time (Eastern), never the REST record GET's UTC
+  `lastModifiedDate`. A cursor even an hour behind the fetch clock re-matches the same record forever.
+  This is the same SuiteQL-vs-REST clock trap as the date-only-format bug above — see the
+  [SuiteQL/REST shim doc](../../library/features/netsuite-suiteql-rest-shim.md).
+
 ### ⚠ Per-record isolation is SECTION-SPECIFIC — and SALES_ORDERS has NONE (corrected 2026-08-17)
 
 Whether a bad record is "stepped over" or freezes the section depends entirely on whether **that
@@ -1175,6 +1212,15 @@ the code deploy).
 
 ## Change history
 
+- 2026-09-03 — **By-reference shim wrote the cursor on the WRONG CLOCK → ITEM_RECEIPTS + ITEM_FULFILLMENTS
+  re-matched the same record forever (fixed, `library` only).** Follow-on to the same-day by-reference
+  fix below: the shims set `lastModifiedDate` from the REST GET (UTC), `date()`-formatted in
+  America/Chicago, but the LIST `WHERE` compares SuiteQL `TO_CHAR(lastmodifieddate)` in the NetSuite
+  account tz (Eastern), so the cursor sat ~1h behind the fetch clock and `lastmodifieddate > cursor`
+  always re-matched — infinite loop, no crash. `fetchItemFulfillmentById`/`fetchItemReceiptById`
+  (`rest.php` ~L2093/~L2254) now read `lastmodifieddate` from SuiteQL `TO_CHAR` (Eastern), matching
+  `fetchInventoryAdjustmentById` (already correct). Proven on NYCHH prod (item receipt 4953915). No
+  worker/SQL change; sections self-backfill after deploy. (jcardinal)
 - 2026-09-03 — **By-reference refetch dropped `lastModifiedDate` → ITEM_FULFILLMENTS + INVENTORY_ADJUSTMENTS
   froze (fixed, `library` only).** GroWrk's ITEM_FULFILLMENTS was re-throwing every 5 min since the
   2026-09-02 per-record cursor deploy (`Undefined property: stdClass::$lastModifiedDate` at

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

@@ -14,5 +14,5 @@
 | [Talos AI-Assistant Component (launcher + docked/drawer chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a chat panel (`TalosPanel`) tha | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/Talos/TalosPanel.test.tsx, toga-blox/src/components/index.ts, toga-blox/src/components/Talos/README.md, toga-blox/src/components/TableRecordModal/TableRecordModal.tsx |
 | [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |
-| [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml |
-| [Local-linking an unpublished blox into a consumer app (incl. a React 19 / Next host)](workflows/local-link-into-a-consumer-app.md) | How to develop a **blox component that is not published yet** against a real consuming app, on Windows, including the hard case: a **React 19 / Next.js (Turbopa | toga-blox/package.json, toga-blox/postcss.config.cjs, toga25-supply/vite.config.ts |
+| [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml, toga25-supply/vite.config.ts, toga25-supply/package-lock.json |
+| [Local-linking an unpublished blox into a consumer app (incl. a React 19 / Next host)](workflows/local-link-into-a-consumer-app.md) | How to develop a **blox component that is not published yet** against a real consuming app, on Windows, including the hard case: a **React 19 / Next.js (Turbopa | toga-blox/package.json, toga-blox/postcss.config.cjs, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/tsconfig.node.json |

package/knowledge/2.0/apps/toga-blox/workflows/landing-a-large-feature-branch.md

@@ -6,13 +6,16 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-26
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - toga-blox/package.json
   - toga-blox/.github/workflows/publish.yml
+  - toga25-supply/vite.config.ts
+  - toga25-supply/package-lock.json
 related:
   - ./dynamic-publish-pipeline.md
+  - ./local-link-into-a-consumer-app.md
   - ../architecture.md
 ---
 
@@ -23,6 +26,9 @@ commits) into `_production` in `toga-blox-npm`. The decision recorded here is **
 `_production` into the feature branch — do not rebase.** Use this doc before starting any
 big-branch integration; the recon step is the transferable part.
 
+Steps 4–5 cover the routine case too: merging the **same** `_production` commit into **several**
+feature branches at once (proven on `toga25-supply`, 2026-09-03).
+
 ## How it works
 
 ### 1. Measure the divergence first
@@ -56,6 +62,42 @@ This shows the exact conflicting files without touching the working tree, which
 2. Resolve the (small, known) conflict set **once**.
 3. Open a normal PR: feature → `_production`.
 
+### 4. Regenerate `package-lock.json` — never hand-merge it
+
+```bash
+npm install --package-lock-only
+```
+
+It rebuilds the lockfile from the **merged `package.json`** and does **not** touch
+`node_modules` — which matters in this repo family because it therefore cannot destroy a blox
+symlink (see [local-link](./local-link-into-a-consumer-app.md) §1a). `toga25-supply/.npmrc`
+already sets `legacy-peer-deps=true`, so no flag is needed. Confirm afterwards that the
+regenerated lock matches the pin in `package.json`.
+
+### 5. Copying one resolution across several branches — diff BOTH sides first
+
+When the same `_production` commit is merged into several feature branches, the conflict often
+*looks* identical and the resolution can be copied:
+
+```bash
+git show <already-resolved-branch>:<file> > <file>   # then verify byte-identical
+```
+
+**But check first — "the same conflict" is frequently not the same.** Before copying, diff both
+conflict sides against the branch you are copying from:
+
+```bash
+git show :2:<file>   # ours  (the feature branch)
+git show :3:<file>   # theirs (_production)
+```
+
+Concrete case (toga25-supply, 2026-09-03, all three branches merging `_production` `4c99ced`,
+blox pin `1.1.2-production.144`): `TRUE-81379` and `TRUE-81217` had identical sides and copied
+cleanly. `TRUE-79020-v2` had **drifted** — its side was space-indented (52 space lines against
+the repo's tabs-only standard) and was missing the react-query alias, the `isBloxLinked`
+branching, and the whole `server.fs.allow` block, while already carrying two `dedupe` members the
+others lacked. A blind copy would have silently reverted work.
+
 ### Why not rebase
 
 Rebasing 281 commits onto `_production` replays every commit, forces the **same conflicts to
@@ -70,10 +112,23 @@ conflict set exactly once and preserves the pushed history.
   at `1.0.314`, so the merge publishes the *branch's* number. See
   [dynamic-publish-pipeline](./dynamic-publish-pipeline.md) for how CI derives the published
   version from that base.
+- **⚠ git can auto-merge a DUPLICATE import with no conflict marker.** One side had
+  `import fs from "fs"`, the other `import fs from "node:fs"`. Git saw two independent additions,
+  merged **both**, and flagged nothing. The result is a duplicate identifier that breaks the
+  build. **After resolving any conflict, scan the whole file for duplicate imports** — "no
+  conflict markers left" does not mean "the file is correct."
 - **Do not read a behind-count as staleness** in this repo — much of it is release plumbing
   generated on the release branch and never merged back (see the publish-pipeline doc).
 
 ## Change history
+- 2026-09-03 — Broadened past the huge-branch case to cover merging one `_production` commit into
+  **several** feature branches. Added step 4 (`npm install --package-lock-only` regenerates the
+  lockfile from the merged `package.json` without touching `node_modules`, so it cannot break a
+  blox symlink) and step 5 (**diff `git show :2:`/`:3:` before copying a resolution between
+  branches** — of three toga25-supply branches merging the same commit, one had drifted to space
+  indentation and was missing three config blocks). Added the gotcha that git **auto-merged a
+  duplicate `import fs`** — `fs` vs `node:fs` — with **no conflict marker**, breaking the build.
+  (apeterson)
 - 2026-08-26 — Created. Recorded the merge-not-rebase decision for landing `feature-new-table`
   (281 ahead / 8 behind, 530 files) into `_production`, and the
   `rev-list --left-right --count` → `merge-tree` recon pair that narrowed the conflict surface

package/knowledge/2.0/apps/toga-blox/workflows/local-link-into-a-consumer-app.md

@@ -6,12 +6,14 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-09-02
+updated: 2026-09-03
 owners: [tcox, apeterson]
 files:
   - toga-blox/package.json
   - toga-blox/postcss.config.cjs
   - toga25-supply/vite.config.ts
+  - toga25-supply/package.json
+  - toga25-supply/tsconfig.node.json
 related:
   - ./dynamic-publish-pipeline.md
   - ../features/talos-assistant.md
@@ -73,6 +75,15 @@ rm -rf node_modules/.vite
   (see §2c).
 - Same rule after editing blox source: `npm run build` in `toga-blox-npm`, **then** clear
   `node_modules/.vite` in the consumer.
+- **`npm ci` does it too, and switching branches forces it.** Each feature branch pins its own
+  blox version, so a branch switch means an install, which silently replaces the link. There is
+  no config fix — re-linking is a required manual step in the branch-switch routine. Shortest
+  re-link from the consumer root: `npm install --no-save ../toga-blox-npm`.
+- **The one npm command that CANNOT break the link: `npm install --package-lock-only`.** It
+  regenerates `package-lock.json` from the merged `package.json` **without touching
+  `node_modules`**. That is also the only correct way to resolve a lockfile merge conflict —
+  never hand-merge one. (`toga25-supply/.npmrc` sets `legacy-peer-deps=true`, so no flag is
+  needed.) Verified 2026-09-03 on toga25-supply at blox `1.1.2-production.144`.
 
 ### 2. Collapse to ONE React (the React 19 case)
 
@@ -127,6 +138,30 @@ dedupe: [
   `@tanstack/react-query`, `@tanstack/react-query-persist-client`, `@tanstack/react-table`,
   `react-hook-form`. `react-hook-form` was nested under blox as well — the same latent bug for
   `BaseInput` / `useFormContext`, just not throwing yet.
+- **Closed out 2026-09-03: `react-hook-form` was the next one to bite, in `toga25-supply`.** It
+  was in **neither** `dedupe` **nor** `resolve.alias`, while **24 files** under
+  `toga25-supply/src` import it and blox's `BaseInput` calls `useFormContext()` — `<FormProvider>`
+  fills one copy, `BaseInput` reads the other. blox's own `node_modules` ships
+  `react-hook-form@7.82.0` (alongside `react`/`react-dom` 18.3.1, `@tanstack/react-query`
+  5.101.4, `@tanstack/react-table` 8.21.3, `framer-motion`, `react-select`, `react-day-picker`,
+  and the react-query persist/devtools packages). Same version on both sides does **not** save
+  you — two folders means two module instances. `toga25-desk` already deduped it; supply had the
+  gap. Supply's list is now:
+
+  ```ts
+  dedupe: [
+    "react", "react-dom",
+    "@tanstack/react-table",
+    "@tanstack/react-query",
+    "@tanstack/react-query-persist-client",
+    "@tanstack/react-query-devtools",
+    "react-hook-form",
+  ]
+  ```
+
+  **Check it after every install:** `npm ls react react-dom @tanstack/react-query
+  @tanstack/react-table react-hook-form` must show exactly one copy of each (verified after
+  `npm ci`, 2026-09-03).
 - **`optimizeDeps.include` is why the throw appears to come from inside blox.** With blox in
   `optimizeDeps.include`, esbuild pre-bundles blox **together with its nested copy**, so the error
   surfaces from `@agilant_toga-blox.js` rather than from app code, and the `?v=<hash>` in the error
@@ -183,6 +218,42 @@ const isLinked = fs.lstatSync(bloxDir).isSymbolicLink();
 - **Result: a blox rebuild now just triggers HMR.** No `rm -rf node_modules/.vite`, no browser cache
   fight. For the **linked** case this **supersedes** §2b's "editing `dedupe` is not enough — clear
   `.vite` and hard-reload"; that step remains true for a published install.
+- **Switching branches between a linked and a published blox also self-heals — verified in Vite
+  source 2026-09-03.** Vite 7.3.6's `getConfigHash()` hashes `resolve` **and**
+  `optimizeDeps.include`/`exclude` (read at
+  `node_modules/vite/dist/node/chunks/config.js:32429`). Because the config branches those exact
+  values on `isBloxLinked`, moving between a symlinked and a published blox changes the hash and
+  Vite re-runs optimizeDeps by itself — **no `rm -rf node_modules/.vite` needed on a branch
+  switch.** This was asserted in a code comment before; it is now checked against Vite's source.
+  It does **not** cover a blox *rebuild*: the hash never sees a linked package's `dist`, which is
+  why the linked branch keeps blox out of the pre-bundle entirely.
+
+**The settled `vite.config.ts` shape (toga25-supply, 2026-09-03 — now identical on the three
+in-flight branches `TRUE-81379`, `TRUE-81217`, `TRUE-79020-v2`):**
+
+```ts
+const bloxDir       = path.resolve(__dirname, "node_modules/@agilant/toga-blox");
+const isBloxLinked  = fs.existsSync(bloxDir) && fs.lstatSync(bloxDir).isSymbolicLink();
+```
+
+- **Auto-detect, never a developer-flipped flag.** A hand-set boolean is always wrong on someone
+  else's machine. Keep the `existsSync` guard first — `lstatSync` throws when blox is not installed.
+- **`optimizeDeps` has exactly two branches.** LINKED → `exclude: [BLOX]` + `include:
+  BLOX_EXTERNALS`. PUBLISHED → `include: [BLOX]`.
+- **`server.fs.allow` — use `searchForWorkspaceRoot(process.cwd())`, NOT `path.resolve(__dirname)`:**
+
+  ```ts
+  server: { fs: { allow: [searchForWorkspaceRoot(process.cwd()), ...(bloxRealPath ? [bloxRealPath] : [])] } }
+  ```
+
+  Setting `allow` **replaces** Vite's default list rather than extending it, so hardcoding the
+  project root silently narrows what the dev server will serve. This form also needs no
+  `isBloxLinked` branch — it is a no-op on a normal install.
+- **The explicit `resolve.alias` for `@tanstack/react-query` was kept on top of `dedupe`** —
+  `_production` had deleted it, the original author's comment says dedupe alone did not beat the
+  symlink. It is a no-op on a published install, so keeping it costs nothing. ⚠ **Still unverified
+  in an actual symlinked run — open question.** If you reproduce it either way, record the answer
+  here.
 
 **Trade-off: `BLOX_EXTERNALS` is a hand-maintained list** (the grep that regenerates it sits in a
 comment beside it). If blox adds a dependency and the list is not updated, the symptom is **"does not
@@ -253,11 +324,29 @@ edit; clearing `node_modules/.vite` matters because Vite's pre-bundle cache hold
   believing a deploy will work.
 - **Linked ≠ shippable.** A consumer on a link **cannot deploy**. The component has to merge and
   publish, and the consumer has to move to the npm version, before anything ships.
+- **Type-check `vite.config.ts` with `-p tsconfig.node.json`.** The config file is covered by
+  `tsconfig.node.json`, not `tsconfig.app.json`, so the usual
+  `npx tsc --noEmit -p tsconfig.app.json` never looks at it. After editing the Vite config run
+  `npx tsc --noEmit -p tsconfig.node.json` as well.
 - **Import subpaths to keep the bundle small.** blox's `exports` allows `./dist/*`, so
   `@agilant/toga-blox/dist/components/<X>/index.js` pulls just that component; the package barrel
   drags every component's CSS into the consumer bundle.
 
 ## Change history
+- 2026-09-03 — Recorded the **settled `vite.config.ts` shape** now shared by supply's three
+  in-flight branches, and closed two open threads. (1) `react-hook-form` was in **neither**
+  `dedupe` nor `alias` in `toga25-supply` while 24 `src` files import it and blox's `BaseInput`
+  calls `useFormContext()` — added, and supply's full 7-member `dedupe` list is written down.
+  (2) Verified in Vite source (`chunks/config.js:32429`) that `getConfigHash()` hashes `resolve`
+  **and** `optimizeDeps.include`/`exclude`, so branching them on `isBloxLinked` makes a
+  linked↔published branch switch invalidate the dep cache **by itself** — no
+  `rm -rf node_modules/.vite`. Also: `server.fs.allow` must use
+  `searchForWorkspaceRoot(process.cwd())` because `allow` **replaces** Vite's default rather than
+  extending it; `npm ci` un-links blox just like `npm install`, and
+  `npm install --package-lock-only` is the one command that cannot (so it is also how you resolve
+  a lockfile conflict); and `vite.config.ts` is type-checked with `-p tsconfig.node.json`, not the
+  app config. The kept `@tanstack/react-query` alias remains **unverified** under a real symlink.
+  (apeterson)
 - 2026-09-02 — Expanded step 4: the consumer's `tsc` resolves blox **types from source** through the
   symlink while Vite loads the package from **`dist/`**, so a clean `tsc --noEmit` does **not** prove
   the browser has your change. Every blox edit needs `npm run build` in blox **plus**

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: architecture
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - toga25-supply/src/main.tsx
@@ -98,11 +98,25 @@ toga-blox table/modal templates.
 ## toga-blox relationship
 
 `@agilant/toga-blox` is the shared frontend component/template/utility library (repo
-`toga-blox-npm`). It is **not published to npm for this app's purposes** — the app is currently
-its primary consumer and resolves it via a symlinked `node_modules/@agilant/toga-blox` →
-`toga-blox-npm`. Because the app imports the built `dist/` (JS + `.d.ts`), any change to toga-blox
-**source** requires a rebuild before it is visible at runtime; in urgent cases the `dist/` files
-(and their `.d.ts`) have been patched directly. The `/update-blox` skill covers version bumps.
+`toga-blox-npm`). The app consumes it in **one of two states, and you must check which you are in**
+before trusting anything else in this section:
+
+- **Published (the normal state, incl. every CI/Amplify build).** `package.json` pins an exact
+  version — `1.1.2-production.144` as of 2026-09-03. A blox source change reaches the app only via
+  publish + pin bump. The `/update-blox` skill covers the bump.
+- **Symlinked (a local dev loop only).** `node_modules/@agilant/toga-blox` points at the
+  `toga-blox-npm` checkout. The app imports the built `dist/`, so **every** blox source edit needs
+  `npm run build` in blox first.
+
+`vite.config.ts` **auto-detects** which state it is in
+(`fs.existsSync(bloxDir) && fs.lstatSync(bloxDir).isSymbolicLink()`) and flips `optimizeDeps`
+accordingly — there is no flag to set by hand.
+
+**⚠ Any `npm install` or `npm ci` silently replaces the symlink with the published package.**
+Switching branches changes the blox pin, which forces an install, which un-links it. There is no
+config fix; re-link with `npm install --no-save ../toga-blox-npm`. The symptom of missing this is a
+misleading "does not provide an export named X". Full procedure and the `dedupe`/`alias` one-copy
+rules: [local-link-into-a-consumer-app](../toga-blox/workflows/local-link-into-a-consumer-app.md).
 
 ## Conventions & gotchas
 

package/knowledge/2.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [jcardinal, apeterson]
 files: []
 related:
@@ -132,6 +132,13 @@ npx tsc --noEmit -p tsconfig.app.json    # ✅
 npx tsc --noEmit                         # ❌ silent no-op
 ```
 
+**MUST: `vite.config.ts` is checked by `tsconfig.node.json`, not the app config.** The app-config
+run never looks at it, so a broken Vite config type-checks green. After editing it, also run:
+
+```bash
+npx tsc --noEmit -p tsconfig.node.json
+```
+
 Documented independently in two repos on this tsconfig shape — `toga25-supply` (verified
 2026-09-01) and `toga2-view` ([architecture](../apps/toga2-view/architecture.md)) — so assume it
 for any app sharing the shape, but **verify per repo before asserting it**. Note also that a repo
@@ -359,15 +366,28 @@ memory.
   because they follow that app's shared-lib surface — verified 2026-08-18:
 
   ```ts
-  // toga25-supply/vite.config.ts
-  dedupe: ["react", "react-dom", "@tanstack/react-table"]
+  // toga25-supply/vite.config.ts — verified 2026-09-03
+  dedupe: [
+    "react", "react-dom",
+    "@tanstack/react-table",
+    "@tanstack/react-query",
+    "@tanstack/react-query-persist-client",
+    "@tanstack/react-query-devtools",
+    "react-hook-form",
+  ]
   // toga25-desk/vite.config.ts
   dedupe: ["react", "react-dom", "react-hook-form"]
   ```
 
-  Supply dedupes the table lib (it consumes blox's table context); desk dedupes react-hook-form (it
-  consumes blox's `BaseInput`, which reads `useFormContext()`). See §13(c) for why a second copy
-  silently breaks blox's hooks.
+  Supply's earlier three-member list (`react`, `react-dom`, `@tanstack/react-table`) is
+  **superseded** — it was incomplete, and each missing member has since caused or nearly caused a
+  live defect. Verified 2026-09-03: `toga-blox-npm/node_modules/` ships its own
+  `react-hook-form@7.82.0`, and supply had it in **neither** `dedupe` **nor** `resolve.alias`
+  while 24 `src` files import it and blox's `BaseInput` calls `useFormContext()` — a
+  `<FormProvider>` filling one copy and `BaseInput` reading the other. **Same version on both
+  sides does not save you**; two folders means two module instances. Desk already deduped it.
+  Apply the principle, then audit the actual list per app: dedupe every peer the shared lib
+  provides context or hooks for. See §13(c).
 
   Verified 2026-08-26: `toga2-commerce` had **no** `dedupe` at all and now declares
   `["react","react-dom","react-hook-form","react-router-dom","framer-motion","@tanstack/react-query","@tanstack/react-table"]`
@@ -375,6 +395,15 @@ memory.
   ships its own `react@18.3.1`/`react-dom@18.3.1`, so consuming blox through a **local symlink**
   resolves React to blox's own copy. Dedupe is what makes the symlink workflow safe — it is not
   optional polish.
+- **SHOULD: branch `optimizeDeps` on whether the shared lib is symlinked, and let Vite's config
+  hash do the cache-busting.** Verified in Vite 7.3.6 source 2026-09-03
+  (`node_modules/vite/dist/node/chunks/config.js:32429`): `getConfigHash()` hashes `resolve` **and**
+  `optimizeDeps.include`/`exclude`. So a config whose `optimizeDeps` differs between a linked and a
+  published blox re-optimizes **by itself** on a branch switch — no `rm -rf node_modules/.vite`.
+  Also: `server.fs.allow` **replaces** Vite's default allow-list, it does not extend it — use
+  `searchForWorkspaceRoot(process.cwd())`, never a hardcoded `path.resolve(__dirname)`, or you
+  silently narrow what the dev server will serve. Mechanics:
+  [local-link-into-a-consumer-app](../apps/toga-blox/workflows/local-link-into-a-consumer-app.md) §2c.
 - **MUST: one env-read chokepoint.** Read `VITE_API` in exactly **one** module (see §17). Verified:
   both apps read it (plus a per-host override) only in `src/api/api.ts`.
 - **SHOULD: ESLint flat config**, verified identical in both apps:
@@ -680,6 +709,13 @@ consuming app, guard against them and move on.
 
 ## Change history
 
+- 2026-09-03 — §11: replaced supply's stale three-member `dedupe` list with the verified
+  seven-member one and added `react-hook-form` (it was in neither `dedupe` nor `alias` while 24
+  `src` files import it and blox's `BaseInput` calls `useFormContext()`). Added a SHOULD for
+  branching `optimizeDeps` on the symlink — Vite's `getConfigHash()` hashes `resolve` +
+  `optimizeDeps.include`/`exclude` (verified in source), so a branch switch self-invalidates the
+  dep cache — plus the trap that `server.fs.allow` **replaces** Vite's default list. §2: added a
+  MUST to type-check `vite.config.ts` with `-p tsconfig.node.json`. (apeterson)
 - 2026-09-01 — §2: added a MUST to **type-check with `-p tsconfig.app.json` (or `tsc -b`), never
   bare `npx tsc --noEmit`** — the root `tsconfig.json` is references-only (`files: []`), so a bare
   root run compiles nothing and always exits 0, a false green in any pre-commit/CI check. Verified

package/package.json

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