toga-ai 1.0.161 → 1.0.163

package/knowledge/1.0/apps/library/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
+| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | `App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal used across all TOGa service request views. | library/app/model/toga/diagnostic.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem |

package/knowledge/1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md

@@ -0,0 +1,49 @@
+---
+title: Diagnostic Dialog — View Recommended Services Routing
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - library/app/model/toga/diagnostic.php
+related:
+  - ../../../clients/office-depot/features/togarefresh2026-linkbuilder-routing.md
+---
+
+## Summary
+`App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal
+used across all TOGa service request views. It includes a "View Recommended Services"
+button whose URL depends on whether the store is a TOGaRefresh 2026 store and whether
+the diagnostic passed or failed.
+
+## How it works
+1. Checks `$_SESSION['isTogaRefresh2023']` or `$_SESSION['isTogaRefresh2026']` to
+   determine if this is a refresh store.
+2. For refresh stores, casts `$serviceRequestId` to `(int)` then queries `Diagnostics`
+   for the latest `pass` value for the service request.
+3. Routes:
+   - **Diagnostic pass** (`pass >= 1`) → `?content=togarefresh2026_servicerequests_techsupport&serviceRequestId=...`
+   - **Diagnostic fail / no diagnostic** (`pass < 1`) → `?content=togarefresh2026_servicerequests_serviceselection&jobJacketId=1&showServices=195,101899&serviceRequestId=...`
+4. For non-refresh stores, falls back to `App_Model_ServiceRequest::linkBuilder()`.
+
+## Data model
+- Table: `Diagnostics` (db_toga)
+- Field read: `pass` (TINYINT boolean — 1 = passed, 0 = failed)
+- Query: latest record by `id DESC LIMIT 1` for the given `serviceRequestId`
+
+## Gotchas / known issues
+- `$serviceRequestId` is cast to `(int)` before SQL interpolation — do not remove this cast (SQL injection prevention).
+- If no diagnostic record exists, `$diagnosticPass` defaults to `0` (fail path) — shows service selection with `showServices=195,101899`.
+- The same pass/fail routing logic exists in `toga/app/togarefresh2026/servicerequests/view.php` (lines 2358–2381) — keep both in sync.
+- `isTogaRefresh2023` is kept alongside `isTogaRefresh2026` for backward compatibility — do not remove it.
+- `$_SESSION['isTogaRefresh2026']` is set in `toga/_/app/frameworkindex.php` and `toga/app/home/action.php` at login time.
+
+## Related docs
+- `clients/office-depot/features/togarefresh2026-linkbuilder-routing.md`
+
+## Change history
+- 2026-06-23 — Initial doc. Diagnostic modal now routes pass→techsupport, fail→serviceselection with showServices=195,101899. (snaredla)

package/knowledge/1.0/apps/toga/INDEX.md

@@ -0,0 +1,4 @@
+# toga (TOGa) — 1.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|

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

@@ -0,0 +1,9 @@
+# toga25-supply (TOGa 2.5 Supply) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
+| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md |
+| [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/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
+| [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
+| [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |

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

@@ -0,0 +1,115 @@
+---
+title: TOGa 2.5 Supply — Architecture
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: architecture
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga25-supply/src/main.tsx
+  - toga25-supply/src/App.tsx
+  - toga25-supply/src/routes.tsx
+  - toga25-supply/src/fieldsConfig/index.ts
+  - toga25-supply/src/fieldsConfig/useClientFields.ts
+  - toga25-supply/src/layout/
+  - toga25-supply/src/pages/
+  - toga25-supply/src/hooks/useTableCellInteractions.ts
+related:
+  - features/client-configurable-fields.md
+  - features/meta-driven-table-data.md
+  - features/column-visibility.md
+  - features/record-modals-and-nested-tables.md
+---
+
+## Summary
+
+`toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply
+application — an iteration and improvement of `toga2-supply`. It is a Vite + React 18 SPA
+(react-router-dom 7, TanStack Query 5, react-hook-form 7) that talks to the 2.0 backend API
+(`_underscore`). It does **not** depend on `toga2-supply`; its components, table templates, and
+data hooks come from the shared in-house library **`@agilant/toga-blox`** (repo `toga-blox-npm`,
+currently consumed at `1.0.318-beta.37`).
+
+The app is **multi-client and meta-driven by design**. The same build serves many clients
+(Compass USA/Canada, NYC Health & Hospitals, Quad, Prudential, GroWrk, and others — there are
+per-client build scripts such as `nychh`, `compass`, `compasscanada`, `growrk`, `prudential`,
+`spglobal`, `bankofamerica`, `wmchealth`, `quad`). Almost nothing is hardcoded per client:
+table columns/labels come from server **table meta**, and client/role-specific UI config
+(filter buttons, group-by options, column pickers, layout toggles) is resolved at runtime
+through `src/fieldsConfig` + `useClientFields()`. Pages are thin; the real logic lives in
+per-page **view models** (`use*ViewModel` hooks) and reusable **layout** components that wrap
+toga-blox table/modal templates.
+
+**Critical rules:**
+- **Don't hardcode per-client behavior in components or view models** — resolve it through
+  `useClientFields()` / `src/fieldsConfig`, keyed by `clientSlug` (from `useHostnameStore`) ×
+  `role`. Every config must have a `DEFAULT` fallback or a client/role with no entry won't render.
+- **A table's pagination-vs-infinite-scroll mode is decided solely by `isPaginationEnabled` from
+  the table meta**, consumed via the single `useTableData` hook — never pick a data hook or
+  hardcode the mode per page.
+- **`@agilant/toga-blox` is symlinked from the local `toga-blox-npm` repo and the app consumes its
+  `dist/`** — after editing toga-blox source you MUST rebuild (`cd toga-blox-npm && npm run build`)
+  or the change won't reach runtime. Patching only `src` is a silent no-op.
+- **Source files in this repo use TAB indentation** — match exactly or string-replace edits fail.
+
+## Tech stack & entry points
+
+- **Build/dev:** Vite. `src/main.tsx` → `src/App.tsx`; routes in `src/routes.tsx`. Per-client
+  dev/build scripts in `package.json` (`dev`, `build`, plus `nychh`, `compass`, `growrk`, etc.).
+- **Data:** TanStack Query 5 (`@tanstack/react-query`). The canonical table query key prefix is
+  `["table-data", slug, …]`; a blanket `invalidateQueries({ queryKey: ["table-data"] })` refetches
+  any table after a mutation.
+- **Forms:** react-hook-form 7 (`FormProvider` + `BaseInput`), used by the create/edit record modals.
+- **Routing:** react-router-dom 7. URL search params are the primary state store for tables
+  (sorting, filters, pagination, active-row uuid, column visibility, nested-table swap keys).
+- **UI library:** `@agilant/toga-blox` provides `PrimaryTable*Layout`, `TableRecordModal`,
+  `BaseInput`, `BaseButton`, `DetailSection`, the `useTableData` hook, FontAwesome helpers, etc.
+
+## Directory layout (`src/`)
+
+- `pages/<Entity>/` — page component (thin) + `viewModel/` (the `use*PageViewModel` hook) +
+  per-page `FIELDS/<CLIENT>/*.json` client config + `hooks/` + `dummyData/` (column-width JSON).
+- `layout/<Thing>Layout/` — reusable table/modal layout wrappers around toga-blox templates,
+  each with its own `use*ViewModel`. Key ones: `SalesOrdersTableLayout`,
+  `SalesOrderRecordModalLayout`, `SalesOrderItemsTableLayout`, `ItemFulfillmentModal`,
+  `ItemRecordModalLayout`, `GenericNestedTables`, `RecordApprovalModalLayout`.
+- `fieldsConfig/` — `index.ts` (the `ClientFields` bundle + `FIELDS[clientSlug][role]` map) and
+  `useClientFields.ts` (resolves active client/role, falls back to `DEFAULT_CLIENT_FIELDS`).
+- `globalFieldsConfig/`, `hooks/`, `stores/` (e.g. `useHostnameStore`), `contexts/`, `utils/`,
+  `types/`, `api/`, `styles/`, `themeConfig.json`.
+
+## Architectural pillars (see feature docs)
+
+1. **Client/role-driven config** — runtime UI config without rebuilds. See
+   [client-configurable-fields](features/client-configurable-fields.md).
+2. **Meta-driven table data** — one `useTableData` hook; meta's `isPaginationEnabled` picks the
+   fetch strategy. See [meta-driven-table-data](features/meta-driven-table-data.md).
+3. **URL-driven column visibility** — shareable show/hide-columns, client-gated button. See
+   [column-visibility](features/column-visibility.md).
+4. **Layered modals over tables** — record modals, nested client/server tables, cell-click
+   modals, and the `GenericNestedTables` config-driven renderer. See
+   [record-modals-and-nested-tables](features/record-modals-and-nested-tables.md).
+
+## 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.
+
+## Conventions & gotchas
+
+- **Tabs, not spaces** for indentation in this repo's source.
+- **`BaseButton` is a default import:** `import BaseButton from "@agilant/toga-blox/dist/components/BaseButton/BaseButton.js"`.
+- **Per-consumer React Query cache scope:** when two components fetch the same record with
+  different field configs, share a `scope` discriminator in the query key so they don't clobber
+  each other's cached data (e.g. record modal vs. approval modal — `scope="record-modal"` vs
+  `scope="approval-modal"`). Including `additionalData` in the query key is mandatory for
+  WHERE-filtered modal tables, or React Query serves a stale unfiltered first render.
+- **Typecheck with `npx tsc --noEmit` / `npx tsc -b`** after changes; adding a required key to
+  `ClientFields` surfaces every bundle missing it.

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -0,0 +1,88 @@
+---
+title: Client-Configurable Fields (useClientFields / fieldsConfig)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga25-supply/src/fieldsConfig/index.ts
+  - toga25-supply/src/fieldsConfig/useClientFields.ts
+  - toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/
+  - toga25-supply/src/pages/Inventory/viewModel/FIELDS/
+  - toga25-supply/src/pages/Inventory/README.md
+related:
+  - ../architecture.md
+  - column-visibility.md
+---
+
+## What it is
+
+The mechanism for config that **varies by client** (or client × role) — field overrides,
+filter buttons, group-by options, column pickers, layout toggles — without hardcoding it in
+the view model or rebuilding per client. All such config resolves through `src/fieldsConfig`
+and the `useClientFields()` hook.
+
+## How it works
+
+1. **Per-client JSON lives next to the consuming page**, under `FIELDS/<CLIENT>/`
+   (e.g. `src/pages/SalesOrders/viewModel/FIELDS/COMPASS/salesOrdersPageFields.json`). There is
+   **always a `DEFAULT/`** folder every client falls back to. `<CLIENT>` must match the hostname
+   `clientSlug` (uppercase — `COMPASS`, `NYCHH`, …).
+2. **`src/fieldsConfig/index.ts`** imports those JSON files and wires them into the
+   `ClientFields` bundle — a normalized `FIELDS[clientSlug][role]` map merged over `DEFAULT`.
+3. **`useClientFields()`** resolves the active `clientSlug` (from `useHostnameStore`) + `role`
+   (from `resolveRole`), looks up the bundle, falls back to `DEFAULT_CLIENT_FIELDS`, and caches
+   the result in React Query. It **always returns a defined bundle** (DEFAULT while loading/missing),
+   so reading `clientFields.yourKey` is safe without optional chaining — but guard array access.
+4. **The view model reads its slice:**
+   ```ts
+   const { fields: clientFields } = useClientFields();
+   const tenantFields = clientFields.salesOrdersPageFields; // your key
+   ```
+
+### By client × role vs. by client only
+
+- **Client × role** (e.g. `salesOrdersPageFields` — ADMIN vs MANAGER see different filter buttons):
+  the JSON is keyed by role at the top level (`{ "ADMIN": {...}, "MANAGER": {...} }`); use a
+  `pick*`/`merge*` helper to merge `DEFAULT[role]` with the client's `[role]`.
+- **Client only** (e.g. `inventoryGroupings` — every role sees the same group-by options): the JSON
+  is flat, and you **inject** it across every role bundle for that client rather than hand-writing
+  it into each. Author the map literal as `FIELDS_BASE` (typed `Omit<ClientFields, "yourKey">`),
+  then build `FIELDS` by mapping each `[clientSlug][role]` entry and grafting
+  `yourKey: BY_CLIENT[clientSlug] ?? DEFAULT_*`. Avoids editing all ~13 role bundles.
+  `DEFAULT_CLIENT_FIELDS` must also carry the new key (ultimate fallback).
+
+### Hydration (non-serializable bits)
+
+Keep JSON **serializable** — strings, enums, arrays. No JSX, no functions, no Tailwind classes.
+Anything non-serializable is referenced by an **enum key** and resolved in the view model via a
+registry that maps enum → real value (e.g. `MODAL_RENDERERS: Record<ModalKey, renderModal>`).
+This is the one place app-owned JSX is grafted back onto client-authored config. Clients never
+author JSX.
+
+## Adding a new client-configurable field
+
+1. Author the serializable JSON under `FIELDS/DEFAULT/<thing>.json` + a folder per overriding client.
+2. Declare the types next to the JSON (`FIELDS/index.ts`) and export the shape.
+3. Wire into `fieldsConfig/index.ts`: add the key to `ClientFields`, import each client's JSON,
+   add the value to **every** bundle + `DEFAULT_CLIENT_FIELDS` (or use the injection pattern).
+4. Consume in the view model via `useClientFields()`.
+5. Hydrate enum→value in the view model if the config references components/render callbacks.
+6. `npx tsc -b` — a new required `ClientFields` key surfaces every bundle missing it.
+
+## Gotchas
+
+- **Always provide `DEFAULT`.** Resolution order: `FIELDS[client]?.[role]` → `FIELDS[client]?.DEFAULT`
+  → `DEFAULT_CLIENT_FIELDS`. A client/role with no entry must still render.
+- **New client *file* = no code change** (just import/wiring). **New render style/modal type
+  (new enum value) = code change** in the hydration registry — that's the intended boundary
+  between client config and app rendering.
+- Worked examples: `salesOrdersPageFields` (client × role) and `inventoryGroupings` (client-only +
+  hydration; full write-up in `src/pages/Inventory/README.md`).
+
+## Change history
+- 2026-06-23 — Documented from the `add-client-fields` skill during initial knowledge seed. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/column-visibility.md

@@ -0,0 +1,98 @@
+---
+title: Column Visibility (URL-driven show/hide columns)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga25-supply/src/components/ColumnVisibilityModal/
+  - toga25-supply/src/pages/SalesOrders/SalesOrders.tsx
+  - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
+  - toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx
+related:
+  - ../architecture.md
+  - client-configurable-fields.md
+  - meta-driven-table-data.md
+---
+
+## What it is
+
+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 selection in the URL as a
+shareable link. The button's presence/label/icon — and the modal's entire copy — are driven per
+client × role via the FIELDS config. Built for pages using `PrimaryTableServerLayout` (the Sales
+Orders pattern). Reference: `ColumnVisibilityModal` + Sales Orders page/view model/data hook.
+
+## How the table renders columns (key facts)
+
+- The table meta (`TableViewMeta` / `DataTableMetaProp`) carries `fields: TableViewField[]`; each
+  field has a unique `slug` and an `isVisible`. `buildTanstackColumns` (toga-blox) **filters by
+  `isVisible`** before building columns, so the tanstack column `id` is the field `slug`. Hiding =
+  `isVisible: false` or removing the field — identical column set.
+- `getDataTableData` builds the API field list **from `meta.fields`**. So the meta used for
+  *fetching* must keep all fields; only the meta passed to the *table* should be visibility-adjusted.
+  **Keep two metas separate: fetch = full, display = adjusted.**
+
+## URL-state semantics
+
+Single param `cols` = comma-separated **visible** column slugs.
+- **Absent** → fall back to each field's default `isVisible`.
+- **Present (even empty)** → only the listed slugs are visible. Distinguish absent from empty with
+  `searchParams.has("cols")`, NOT truthiness (so "hide all" works):
+
+```ts
+const visibleSlugSet = searchParams.has("cols")
+  ? new Set((searchParams.get("cols") ?? "").split(",").filter(Boolean))
+  : null;
+const isFieldVisible = (f) => visibleSlugSet ? visibleSlugSet.has(f.slug) : f.isVisible;
+```
+
+## Steps
+
+1. **Reuse the modal.** `ColumnVisibilityModal` is generic and holds **zero hardcoded copy** —
+   props `{ isOpen, columns: { slug, label, visible }[], labels, icon, onApply(visibleSlugs),
+   onReset?, onClose }`. `labels` = `{ title, showAll, hideAll, reset, cancel, apply, close }`;
+   `icon` = `{ name, variant }`. It keeps pending state internally, commits only on Apply.
+2. **View model — derive visibility from URL.** Add `visibleSlugSet`/`isFieldVisible`,
+   `columnOptions` (`fields.map(f => ({ slug, label: f.label ?? f.slug, visible: isFieldVisible(f) }))`),
+   `displayTableMeta` (`{ ...meta, fields: fields.map(f => ({ ...f, isVisible: isFieldVisible(f) })) }` —
+   return THIS as the table meta; data hook keeps full meta), `columnVisibilityKey` (visible slugs
+   joined; remount key), and `applyColumnVisibility(slugs)`/`resetColumnVisibility()`.
+3. **Data hook — exclude `cols` from the query key.** Where the slug key is stripped from
+   `tableSearchParams`, also `filtered.delete("cols")` — else every toggle refetches.
+4. **Page — button + modal + remount key.** Local `isColumnsModalOpen` state; render the button
+   from client config; pass `columnsButton.modal.labels`/`.icon` to the modal; put
+   `key={columnVisibilityKey}` on the table layout (required — see gotcha).
+5. **Make button + all modal copy client-configurable** (mirrors `filterButtons`; see
+   [client-configurable-fields](client-configurable-fields.md)). Add a `columnsButton` block to each
+   role in `FIELDS/<CLIENT>/<page>Fields.json` (and to `DEFAULT` first). Resolve it off `tenantFields`
+   in the view model into `{ icon, labels }` with **per-key fallbacks living in the resolution layer**,
+   never in the component.
+6. **Verify:** `npx tsc --noEmit`, validate each JSON parses, click live (toggle, Apply, copy URL,
+   reload → state persists).
+
+## Gotchas
+
+- **No hardcoded copy in the component** — every user-facing string (incl. Close `aria-label`) is a
+  required `labels` prop from client FIELDS; fallbacks live in the view model's resolution, not the
+  component, not default prop values. Only structural glyphs (checkbox tick, close `xmark`) stay.
+- **Remount key is REQUIRED.** toga-blox's `PrimaryTableRow` memoizes
+  `useMemo(() => row.getVisibleCells(), [row])`; TanStack caches `row` by data, so a columns-only
+  change doesn't change `row` → stale cells. Symptom: **toggling off removes the header but leaves the
+  body column.** `key={columnVisibilityKey}` forces a fresh table instance — the only fix without
+  editing `node_modules`. Real upstream fix: repair that memo in toga-blox.
+- **Don't shrink the fetch meta** — adjust `isVisible` only on the table meta; `getDataTableData`
+  builds its field list from `meta.fields`.
+- **`cols` must be stripped from the data query** or every toggle refetches.
+- **`has("cols")` vs truthiness** — empty `cols` is a real "hide all" state, not "absent".
+- **Checkbox can't be a nested `<button>`** — the row is the clickable `<button>`; the checkbox is a
+  visual `<span aria-hidden>`. A button-in-button is invalid HTML and silently breaks clicks.
+- **Shareable-link trade-off** — an explicit `cols` set captures an exact view; columns added to the
+  meta later won't appear for an old link until Reset (intended).
+
+## Change history
+- 2026-06-23 — Documented from the `add-column-visibility` skill during initial knowledge seed. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/meta-driven-table-data.md

@@ -0,0 +1,176 @@
+---
+title: Meta-Driven Page & Table Setup
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
+  - toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts
+  - toga25-supply/src/hooks/useTablePageMeta.ts
+  - toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts
+  - toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts
+  - toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts
+  - toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts
+related:
+  - ../architecture.md
+  - column-visibility.md
+  - record-modals-and-nested-tables.md
+---
+
+## What it is
+
+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 settings), then fetches the *table
+data* — each step keyed by a slug, each hook supplied by `@agilant/toga-blox`. A developer wires a
+new page by composing these hooks in a view model; they never hand-build columns or choose a
+fetch strategy. `useSalesOrdersViewModel`
+(`src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx`) is the canonical example.
+
+## The flow (Sales Orders)
+
+```
+useSalesOrdersViewModel
+  │
+  │ 1. PAGE META  ── page slug "sales-orders-listing", app "supply"
+  ├─▶ useFetchPageMeta("sales-orders-listing", { app: "supply", enabled: true })   [toga-blox]
+  │       → pageMeta: PageMeta { settings: { sections, fields }, acl }
+  │         (field-label/section overrides + ACL for this page)
+  │
+  │ 2. TABLE SLUG  ── from the route, not from pageMeta
+  ├─▶ useSalesOrdersTableState() → useServerTableUrlState(slug, …)                 [app]
+  │       slug = location.pathname.replace("/", "")   // e.g. "salesorders"
+  │       also owns sorting / filters / page / recordsPerPage / activeRowUuid (URL state)
+  │
+  │ 3. TABLE META  ── table slug → columns + table settings
+  ├─▶ useTablePageMeta({ slug: tableState.slug })                                  [app wrapper]
+  │       └─ useFetchTablePageMeta({ slug })                                       [toga-blox]
+  │            → { table: TableViewMeta, nestedTable }, isLoadingFilterOptions, …
+  │              table.fields[]  = every column (TableViewField[])
+  │              table.{ slug, route, joins, sort, recordsPerPage,
+  │                      isPaginationEnabled, isInfiniteScrollingEnabled, apiWhereClause }
+  │
+  │ 4. MERGE LABELS  ── graft page-meta labels onto table fields
+  ├─▶ useAssignTableFieldLabels(fetchedTableViewMeta, pageMeta)                    [toga-blox]
+  │       → salesOrdersTableMeta: TableViewMeta | null
+  │
+  │ 5. TABLE DATA  ── same table slug → rows
+  └─▶ useTableData({ slug: tableState.slug, tableViewMeta: salesOrdersTableMeta,
+                     isPaginationEnabled: !!salesOrdersTableMeta?.isPaginationEnabled,
+                     sorting, columnFilters, page, recordsPerPage,
+                     searchParams, additionalData })                              [toga-blox]
+          → { records, isLoadingTableDataLoading, isFetching,
+              paginationMeta, fetchNextPage, hasNextPage }
+```
+
+The view model then returns `salesOrdersTableMeta` (after column-visibility adjustment — see
+[column-visibility](column-visibility.md)), `displayRecords`, the pagination/infinite wiring, and
+`tableSettings = { isPaginationEnabled }` for the `*TableLayout` to forward to
+`PrimaryTableServerLayout`.
+
+### Two slugs, two metas — keep them straight
+
+- **Page slug** (`"sales-orders-listing"`) is a literal passed to `useFetchPageMeta` and identifies
+  the *page* (its label overrides, sections, ACL). It does **not** identify the table.
+- **Table slug** (`tableState.slug`) identifies the *table* and is used for **both** the table-meta
+  fetch (step 3) and the table-data fetch (step 5) — they must match so the columns and the rows
+  describe the same table. In Sales Orders this slug is derived from the route pathname via
+  `useServerTableUrlState`, not read out of `pageMeta`.
+- `useAssignTableFieldLabels` is the bridge: it overlays the page meta's per-field labels
+  (`pageMeta.settings.fields[table][field].label`) onto the table meta's fields, so page-scoped
+  copy wins without re-fetching.
+
+## What's in the table meta (the columns)
+
+`useFetchTablePageMeta` returns `{ table, nestedTable }`. The `table` object is the `TableViewMeta`
+(alias of `DataTableMetaProp`) and carries:
+
+- `fields: TableViewField[]` — **every column**. Each field: `slug` (unique id / tanstack column
+  id), `label`, `isVisible`, `index`, `type` (`STRING | NUMBER | DATE | DATETIME | SELECT |
+  MULTISELECT | IMAGE | HYPERLINK | STATUS | CURRENCY | AVATAR | LINK | URGENCY | CLIENT |
+  STATUS_BADGE | BOOLEAN | null`), `isEditable`, `isSortable`, `isFilterable`, `isCopyable`,
+  `isExpandableCell`, `width`, `sticky` (`left|right|null`), `precision`, `casing`, `recordRoute`,
+  `hyperlinkField`, `imageUrlField`, `filterOptions`, `settings: { table, field, contextTable,
+  contextField }`, `selectIdentifierField`, `selectNameField`.
+- Table-level: `slug`, `route`, `table`, `joins[]`, `sort[]`, `recordsPerPage`, `apiWhereClause`,
+  `isPaginationEnabled`, `isInfiniteScrollingEnabled`.
+- `nestedTable` — a second `TableViewMeta | null` for nested/expand rows.
+
+`buildTanstackColumns` (toga-blox) builds columns from `fields`, filtering by `isVisible` (the
+tanstack column `id` is the field `slug`).
+
+## Pagination vs. infinite scroll is meta-driven too
+
+`useTableData` runs **both** a paginated `useQuery` and an infinite `useInfiniteQuery`, gating each
+with `enabled` on `isPaginationEnabled` so only the active one fetches, and returns one normalized
+shape (`records`, `paginationMeta` *or* `fetchNextPage`/`hasNextPage`). The view model passes only
+`isPaginationEnabled` (from the table meta); `PrimaryTable*Layout` derives
+`isInfiniteScrollingEnabled = !isPaginationEnabled`. So a table's mode comes from its meta, never a
+per-page hook choice. Other baked-in behavior: unified `["table-data", slug, …]` query key (a
+blanket `invalidateQueries({ queryKey: ["table-data"] })` refetches either mode); display params
+(`<slug>` active-row uuid, `cols`) stripped from the key/API call; generic record extraction (first
+array in `response.data`).
+
+## From toga-blox `dist` (reference)
+
+Everything in the pipeline except the route-derived table slug comes from `@agilant/toga-blox`. The
+app imports the built `dist/` — edits to toga-blox source require a rebuild (`cd toga-blox-npm &&
+npm run build`) before they reach runtime.
+
+| Export | `dist` path | Signature / role |
+|---|---|---|
+| `useFetchPageMeta` | `dist/hooks/useFetchPageMeta` | `(slug, { app, enabled?, onError? }) → { pageMeta: PageMeta \| null, labels, isLoading, isError, refetch }`. `PageMeta = { settings: { sections: MetaSections, fields: Record<string,any> }, acl }`. Page-level labels/sections/ACL. |
+| `useFetchTablePageMeta` | `dist/hooks/useFetchTablePageMeta` | `({ slug }) → { tableViewMeta: { table, nestedTable }, isLoadingFilterOptions, isLoadingTableDataLoading, isFetching }`. The columns + table settings. |
+| `useAssignTableFieldLabels` | `dist/hooks/useAssignTableFieldLabels` | `(fetchedTableViewMeta: { table? } \| null, pageMeta: { settings?: { fields? } } \| null) → TableViewMeta \| null`. Merges page-meta field labels onto table fields. |
+| `useTableData` | `dist/components/Table/hooks/useTableData` | `(UseTableDataOptions) → { records, isLoadingTableDataLoading, isFetching, paginationMeta, fetchNextPage, hasNextPage }`. Bimodal data fetch (see above). |
+| `TableViewMeta` (type) | `dist/components/Table/types` → `= DataTableMetaProp` | The `table`/`nestedTable` shape; `TableSkin = "supply" \| "desk" \| "supply-nested" \| "supply-modal-table"`. |
+| `TableViewField` (type) | `dist/api/index` | Per-column shape (see "What's in the table meta"). |
+
+App-side glue (NOT in toga-blox):
+- `useTablePageMeta` (`src/hooks/useTablePageMeta.ts`) — thin wrapper over `useFetchTablePageMeta`
+  that re-types `table`/`nestedTable` as `TableViewMeta | null` and re-exposes the rest unchanged.
+- `useSalesOrdersTableState` → `useServerTableUrlState` (`src/hooks/`) — derives the **table slug**
+  from the route pathname and owns URL-backed sorting/filters/pagination/active-row state.
+
+## Wiring a new page (recipe)
+
+1. `useFetchPageMeta("<page-slug>", { app: "supply", enabled: true })` → `pageMeta`.
+2. A table-state hook (`use<Page>TableState` → `useServerTableUrlState(slug, …)`) to get the table
+   `slug` + URL state (`sorting`, `columnFilters`, `page`, `recordsPerPage`, `searchParams`).
+3. `useTablePageMeta({ slug })` → `tableViewMeta` (columns + settings).
+4. `useAssignTableFieldLabels(tableViewMeta, pageMeta)` → the merged meta you hand to the table.
+5. `useTableData({ slug, tableViewMeta: merged, isPaginationEnabled: !!merged?.isPaginationEnabled,
+   sorting, columnFilters, page, recordsPerPage, searchParams, additionalData })` → rows.
+6. `tableSettings = useMemo(() => ({ isPaginationEnabled: merged?.isPaginationEnabled }), [merged])`.
+7. Return both pagination wiring (`paginationMeta`, `handlePageChange`, `handleRecordsPerPageChange`)
+   **and** infinite wiring (`fetchNextPage`, `hasNextPage`); forward all from the `*TableLayout` to
+   `PrimaryTableServerLayout`.
+
+## Gotchas
+
+- **Page slug ≠ table slug.** The page slug is a literal for `useFetchPageMeta`; the table slug
+  (route-derived here) drives table meta *and* table data — those two must use the **same** slug.
+- **Server meta currently returns `isPaginationEnabled: true` for every slug**, so all tables
+  paginate today. A table that should infinite-scroll needs the backend to return `false` for that
+  slug — the frontend no longer hardcodes it. (This is why VendorItems, historically infinite, now
+  paginates.)
+- **Don't shrink the fetch meta for column hiding.** `getDataTableData` builds its API field list
+  from `meta.fields`; adjust `isVisible` only on the *display* meta (see column-visibility).
+- **Infinite scroll needs a height-constrained scroll container** (`max-height` + `overflow-y: auto`);
+  inline-expanded nested tables where the page scrolls won't load more. Pagination is unaffected.
+- **`additionalData` must be in the query key** (it is, inside `useTableData`) — required for
+  WHERE-filtered modal tables or React Query serves a stale unfiltered first render.
+- **toga-blox edits need a rebuild** — the app consumes `dist/`; editing only `src` is a silent no-op.
+
+## Change history
+- 2026-06-23 — Refocused on the full page→table→data meta pipeline (page meta via `useFetchPageMeta`,
+  table meta via `useTablePageMeta`/`useFetchTablePageMeta`, label merge via
+  `useAssignTableFieldLabels`, data via `useTableData`), grounded in `useSalesOrdersViewModel`; added
+  a toga-blox `dist` reference table. (apeterson)
+- 2026-06-09→06-10 — Migration that established the bimodal `useTableData`: added it to toga-blox;
+  made `PrimaryTable*Layout` derive `isInfiniteScrollingEnabled`; migrated Items/SalesOrders/VendorItems
+  view models + `GenericNestedTables` + `ItemFulfillmentModal`; deleted per-page data hooks. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -0,0 +1,147 @@
+---
+title: Record Modals & Nested Tables
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - 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/
+  - toga25-supply/src/hooks/useTableCellInteractions.ts
+related:
+  - ../architecture.md
+  - meta-driven-table-data.md
+---
+
+## What it is
+
+The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and
+`PrimaryTable*Layout`. Covers: row-click record modals, nested client/server tables inside a
+modal, cell-click modals, modal-contained server tables, the config-driven `GenericNestedTables`
+renderer, and form-driven create/edit record modals. The canonical examples live in
+`src/layout/*` (Sales Orders + Item). These six patterns are the load-bearing UI architecture for
+this app.
+
+## Pattern 1 — Row click opens a record modal (URL-driven)
+
+Page renders a `*TableLayout` and passes a `renderModal` prop. The table layout owns all state via
+`use*ViewModel` → `useServerTableUrlState`. Clicking a row sets `activeRowUuid` in the URL;
+`PrimaryTableServerLayout` calls `renderModal({ uuid, onClose })`, which renders the record modal
+wrapped in `TableRecordModal position="bottom"`.
+
+- `renderModal` is `({ uuid, onClose }) => ReactNode | null` — return `null` when `uuid` is falsy.
+- `onClose` clears the URL state (`handleModalClose`).
+- The record modal layout calls its own view model to fetch data for that uuid.
+- **Action-column modals** (e.g. approval) use a separate `useState<Record|null>` in the page,
+  rendered as a second `TableRecordModal position="center"` — not URL-driven.
+
+## Pattern 2 — Record modal contains a nested client-side table
+
+The record modal view renders e.g. `SalesOrderItemsTableLayout` with `displayRecords` from the
+parent view model. The nested table uses `PrimaryTableClientLayout` (data already in memory),
+`tableSkin="supply-modal-table"`, and its **own** slug + `useSearchParams` + `useServerTableUrlState`
+so URL-state namespacing doesn't collide with the outer table. Column widths come from
+`src/pages/<Entity>/dummyData/*.json`; `headerSpan` adds a spanning header above grouped columns.
+
+## Pattern 3 — Cell click within a nested table opens another modal
+
+Driven by the reusable hook `useTableCellInteractions` (`src/hooks/useTableCellInteractions.ts`),
+which owns all click/hover/style logic. Each table's view model only defines the registries:
+
+```ts
+const { activeModal, closeModal, handleTableClick, handleTableMouseOver,
+        handleTableMouseOut, applyClickableStyles } = useTableCellInteractions({
+  fields, cellClickRegistry, headerClickRegistry /* optional */, contextUuid /* optional */ });
+```
+
+- `cellClickRegistry[key]` (key matches the field's `onClick` in the table meta JSON):
+  `{ canOpen?(row), getModalSpec(row) => ({ key, uuid, row }) }`. `canOpen` is the single source
+  of "is this cell clickable?" — used by the click handler, hover styles, and cursor styles.
+- `headerClickRegistry[key]` (key matches the field's `headerOnClick`):
+  `{ getModalSpec(contextUuid) => ({ key, uuid, row }) }`.
+- Table meta JSON marks a field: `{ "name": "qtyFulfilled", "onClick": "openFulfilledModal",
+  "headerOnClick": "openAllFulfillments" }` — both independent.
+
+Layout setup: wrap the table in a div with `onClick={(e) => handleTableClick(e, displayRecords)}`
++ mouseover/out; re-apply styles on DOM changes via a `MutationObserver` calling
+`applyClickableStyles` (virtual scroll re-renders rows); render each modal as a sibling switching
+on `activeModal.key`. **Adding a clickable column = 3 edits:** meta JSON `onClick`, one
+`cellClickRegistry` entry, one `{activeModal?.key === "myKey" && <Modal/>}` block.
+
+## Pattern 4 — Modal containing a server-side table
+
+For modal tables needing server data, use `PrimaryTableServerLayout` inside `TableRecordModal
+position="bottom"`. The modal view model calls `useFetchTablePageMeta` + `useTablePageData`
+(or `useTableData`) with an `additionalData` WHERE filter, e.g. `{ slug: "SalesOrderItems.uuid",
+uuid: "<row-uuid>" }`. **`additionalData` MUST be in the query key** (in toga-blox) or React Query
+caches the unfiltered first render (uuid null) and never refetches. Guard with `isOpen={!!uuid}`;
+when uuid is null, `additionalData` returns `{}`. Typically `isPaginationEnabled: false` +
+`isInfiniteScrollingEnabled: true` (but see [meta-driven-table-data](meta-driven-table-data.md)).
+
+## Pattern 5 — `GenericNestedTables` (config-driven multi-level / swap tables)
+
+A config-driven renderer: declare an array of `TableLevel` objects instead of hand-wiring each
+level. Each level fetches its own meta + data and renders a `GenericTableLayout` (wraps
+`PrimaryTableServerLayout`). Reference: `src/pages/Inventory/`.
+
+`TableLevel` carries `fetchSlug`, `metaVariant`, `tableSkin`/`swapTableSkin`, `actionColumns`,
+`renderModal` (Pattern 1), `rowInteraction` (`"expand"` default | `"swap"`), `urlParamKey`
+(required for swap, unique per level), `getAdditionalData(parentUuid)`,
+`getSwapAdditionalData(selfUuid)`.
+
+- **`"expand"`** — clicking a row inline-expands the next level beneath it (filtered via
+  `getAdditionalData(parentUuid)`).
+- **`"swap"`** — clicking writes `urlParamKey=<rowUuid>`; the renderer makes that level the new
+  active root, filtered by `getSwapAdditionalData(selfUuid)` (using `swapTableSkin`).
+
+`additionalData` is produced per-level by callbacks (the WHERE-filter shape from Pattern 4). Each
+level runs its own `useServerTableUrlState` and strips its own slug key, isolating URL state.
+A page-level `pageMeta` (from `useFetchPageMeta`) flows down for field-label overrides. The page
+view model builds `TableLevel[]` arrays, picks the active one via a URL param, and passes `levels`
+to `GenericNestedTables` with `key={activeGrouping.key}` to force remount and avoid stale state.
+
+## Pattern 6 — Create/edit record modal (form-driven)
+
+Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLayout/`). Form-driven
+(react-hook-form + `FormProvider`), fields rendered through a section/field config + `DetailSection`
++ `BaseInput`, inside `TableRecordModal position="bottom" variant="expandable"`.
+
+```
+<Entity>RecordCreateModalLayout        ← owns form hook, mounts TableRecordModal
+  └─ <Entity>RecordCreate              ← FormProvider + form, renders sections
+       ├─ use<Entity>CreateForm        ← rhf state + apiPost submit
+       └─ use<Entity>RecordEditViewModel ← fetches advancedSelect options
+```
+
+- Form hook: `useForm({ defaultValues, mode: "onChange", reValidateMode: "onChange" })`; `onSubmit`
+  builds a payload (map relation objects to `.uuid`), `apiPost("/<entities>", payload)`, then
+  `queryClient.invalidateQueries({ queryKey: ["table-data"] })`, reset, `onCreated?.()`. Edit
+  variant: `form.reset(record)` in a `useEffect`, `apiPut`, expose `isEditing`/`onEnableEdit`/`onCancelEdit`.
+- Field types: `text`, `textArea`, `toggle`, `advancedSelect`, `advancedMultiSelect`; mark required
+  with `isRequired` + `showRequiredIndicator`; feed select options via `optionsByFieldUuid` keyed by
+  field `uuid`. The edit view model that supplies options is **reused** by both create and edit.
+- Page holds `isCreateOpen` state + a "New <Entity>" `BaseButton`, renders the layout with `isOpen`/`onClose`.
+
+## Gotchas
+
+- **Files use TABS** — match exactly or edits won't apply.
+- **`BaseButton` is a default import:** `@agilant/toga-blox/dist/components/BaseButton/BaseButton.js`.
+- **Submit payload diverges from form shape** — send relation `.uuid`, not the `{uuid,name}` object;
+  confirm field names against the real POST/PUT contract.
+- **Nested tables need their own slug + URL-state isolation** or sibling tables clobber each other.
+- **`additionalData` in the query key is mandatory** for WHERE-filtered modal tables (Pattern 4).
+- **Per-consumer cache `scope`** — two consumers fetching the same record with different field
+  configs must use a `scope` discriminator in the query key or they overwrite each other's cache
+  (record modal vs. approval modal: the approval modal omitting item-image fields blanked the
+  record modal's images until scoping isolated the entries).
+
+## Change history
+- 2026-06-23 — Documented from CLAUDE.md Modal Patterns 1–5 + the `create-record-modal` skill during
+  initial knowledge seed. (apeterson)

package/knowledge/INDEX.md

@@ -4,13 +4,14 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 6 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 7 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 10 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **toga** (TOGa) — 1 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 
 ## 2.0 framework
 
@@ -26,6 +27,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) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 
 ## standalone framework
 

package/knowledge/clients/office-depot/INDEX.md

@@ -3,4 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [ODP Tech Support Agent (Office Depot variant)](features/odp-tech-support.md) | 2.0 | ODP-specific customization of the shared TOGa Voice agent. | voice-to-voice/clients/odp/agent.py, voice-to-voice/clients/odp/agents/tech_support.py, voice-to-voice/clients/odp/prompts.py, voice-to-voice/clients/odp/config.yaml, voice-to-voice/clients/odp/.env.example |
+| [TOGaRefresh 2026 — linkBuilderRefresh URL Routing (ODP)](features/togarefresh2026-linkbuilder-routing.md) | 1.0 | In the TOGaRefresh 2026 UI, any button that navigates to the service builder must use `App_Model_ServiceRequest::linkBuilderRefresh()` (→ `togarefresh2026_servi | toga/app/togarefresh2026/servicerequests/review.php, toga/app/togarefresh2026/customers/view.php, library/app/model/toga/diagnostic.php |
 | [Office Depot](profile.md) | 2.0 | Office Depot is the first deployed tenant of the **TOGa Voice** (`voice-to-voice`) platform. |  |

package/knowledge/clients/office-depot/features/togarefresh2026-linkbuilder-routing.md

@@ -0,0 +1,49 @@
+---
+title: TOGaRefresh 2026 — linkBuilderRefresh URL Routing (ODP)
+framework: "1.0"
+repo: toga
+project: TOGa
+client: office-depot
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - toga/app/togarefresh2026/servicerequests/review.php
+  - toga/app/togarefresh2026/customers/view.php
+  - library/app/model/toga/diagnostic.php
+related:
+  - ../profile.md
+  - ../../../1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md
+---
+
+## Summary
+In the TOGaRefresh 2026 UI, any button that navigates to the service builder must use
+`App_Model_ServiceRequest::linkBuilderRefresh()` (→ `togarefresh2026_servicerequests_serviceselection`)
+instead of the legacy `linkBuilder()` (→ `servicerequests_builder`).
+
+## Key files / entry points
+- `App_Model_ServiceRequest::BUILDER` = `'servicerequests_builder'` (legacy)
+- `App_Model_ServiceRequest::BUILDERREFRESH` = `'togarefresh2026_servicerequests_serviceselection&jobJacketId=1'`
+- Both constants defined in `library/app/model/servicerequest.php` lines 11–12.
+
+## How it works
+Files updated to use `linkBuilderRefresh`:
+
+| File | Location | Context |
+|------|----------|---------|
+| `togarefresh2026/servicerequests/review.php` | line 217 | Quote submission POST URL for non-EXISTING job jackets |
+| `togarefresh2026/customers/view.php` | line 64 | "Create Work Order For This Customer" button |
+| `library/app/model/toga/diagnostic.php` | `initializeDiagnosticDialog()` | Device modal button — routes by diagnostic pass/fail (see library doc) |
+
+## Gotchas / known issues
+- The old `servicerequests/view.php` (legacy non-refresh view) intentionally keeps `linkBuilder()` — 2026 stores do not route through it.
+- Do not change `App_Model_ServiceRequest::BUILDER` — legacy stores still depend on it.
+- The diagnostic modal routing is pass/fail conditional — see `1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md` for full details.
+- `toga` app repo was not in registry.json before this session — it has been added (framework 1.0, role app, dependsOn library).
+
+## Related docs
+- `1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md`
+
+## Change history
+- 2026-06-23 — Initial doc. All 2026 builder buttons now use linkBuilderRefresh; diagnostic modal uses pass/fail routing. toga added to registry.json. (snaredla)

package/knowledge/registry.json

@@ -159,5 +159,21 @@
     "framework": "2.0",
     "role": "app",
     "dependsOn": ["api2"]
+  },
+  {
+    "repo": "toga",
+    "project": "TOGa",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "toga25-supply",
+    "project": "TOGa 2.5 Supply",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
   }
-]
+]

package/package.json

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