toga-ai 1.0.506 → 1.0.507

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

@@ -5,3 +5,4 @@
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
 | [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | _underscore/Model/Client/Measure.php, _underscore/Model/Client/TrackingNumber.php, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts, toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |
+| [Onboarding a client to the supply2 frontend (host-scoping)](workflows/client-host-scoping.md) | How a new tenant becomes a "client" in the `toga2-supply` frontend. | toga2-supply/src/stores/useHostNameStore.ts, toga2-supply/src/hooks/useHostName.tsx, toga2-supply/src/hooks/usePageDetails.tsx, toga2-supply/src/hooks/usePageListDetails.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/src/utils/handleClientAuthentication.ts, toga2-supply/src/App.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/api/toga.ts |

package/knowledge/2.0/apps/toga2-supply/workflows/client-host-scoping.md

@@ -0,0 +1,83 @@
+---
+title: Onboarding a client to the supply2 frontend (host-scoping)
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-08-04
+owners: [apeterson]
+files:
+  - toga2-supply/src/stores/useHostNameStore.ts
+  - toga2-supply/src/hooks/useHostName.tsx
+  - toga2-supply/src/hooks/usePageDetails.tsx
+  - toga2-supply/src/hooks/usePageListDetails.tsx
+  - toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx
+  - toga2-supply/src/utils/handleClientAuthentication.ts
+  - toga2-supply/src/App.tsx
+  - toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts
+  - toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx
+  - toga2-supply/src/api/toga.ts
+related:
+  - ../architecture.md
+  - ../../../clients/elite/features/supply2-scope.md
+---
+
+## Summary
+
+How a new tenant becomes a "client" in the `toga2-supply` frontend. There is **no client
+registry, enum, or per-client folder** in this repo. A "client" is simply the **subdomain
+hostname** (`window.location.hostname` → e.g. `ELITE`), read through `useHostNameStore` /
+`useHostName`. Onboarding a client means deciding, per page, what shows and how it behaves —
+via backend ACL/pageMeta (the correct path) or, where necessary, a hardcoded host conditional
+(the escape hatch). This doc is the reusable playbook and records the sharp edges (chiefly the
+NYCHH inventory fragility) that any host-scoping change must not break.
+
+## The two gating mechanisms
+
+1. **Backend ACL / pageMeta (preferred).** `usePageDetails` / `usePageListDetails` read
+   `acl["<slug>"][...]` from the API. Columns, page availability, and permissions are
+   data-driven per role/client — no frontend change needed to grant or hide a page.
+2. **Hardcoded `hostName === "X"` conditionals (escape hatch).** Used in `SlideMenu.tsx`
+   (nav visibility / deep-links) and `handleClientAuthentication.ts`. This is how NYCHH,
+   EndeavorHealth, and BankOfAmerica are wired. Prefer ACL; reach for a host conditional only
+   when the behavior cannot be expressed in pageMeta.
+
+Routing in `App.tsx` is **centralized and unconditional** — pages are gated by nav + ACL,
+never by the router. Do not add per-client routes.
+
+## Onboarding checklist
+
+1. Confirm the client's subdomain resolves the tenant (hostname → client → `Client_<slug>` DB).
+2. Grant each in-scope page via backend ACL/pageMeta for the client's roles (slugs like
+   `sales-orders`, `sales-orders-listing`, inventory statics, etc.).
+3. Add nav entries in `SlideMenu.tsx` (host-scoped if the page is client-specific).
+4. For any page view-model that maps behavior by host (e.g. Orders `fieldMapping`,
+   Inventory group-by statics), add an **explicit entry for the new host** — do not rely on a
+   fallback (see gotchas).
+5. Verify no shared global static was reordered or mutated for existing hosts.
+
+## Gotchas / guardrails (do not break existing hosts)
+
+- **NYCHH inventory is the most fragile surface in supply2.** Its nav deep-links hardcode the
+  group uuid `94f1e621-6eb4-bece-7f67-302ed49bce88` ("Items By Customer POs", `isDefault`).
+  That option's branch sets `additionalData {slug:"customerId", uuid:"1"}`, which triggers an
+  **NYCHH-only** `_total ne 0` filter in `api/toga.ts` (`slug=="customerId" &&
+  hostName[0]=="NYCHH"`). Nothing here may change when host-scoping shared inventory statics.
+- **Group-by options are a global static** (`DUMMYGROUPOPTIONS.ts`) with no host branching
+  today. When you host-scope it, **return a fully separate array per host** — do NOT filter a
+  combined array. Invariant: **exactly one `isDefault` per host's visible array.**
+- **Selection is uuid-driven and non-null-asserted.** Selection resolves from the URL param
+  `<tableSlug>:group=<uuid>` with fallback `groupOptions.find(o=>o.isDefault) || groupOptions[0]`;
+  `InventoryPage.tsx` non-null-asserts the uuid find and **throws** if the uuid is missing for a
+  host. Every host must have a valid default.
+- **Shared localStorage is order-dependent and persists across host switches** in one browser
+  (`"urlKeys"` in `PrimaryTable.tsx`, and `"selectedGrouping"`). A new client's group option
+  must use a **distinct `urlKeys.key`** and must **never reorder** existing ones.
+- **View-model host maps must not depend on a fallback.** Orders' `useOrdersPageViewModel.ts`
+  uses `fieldMapping[hostName] || fieldMapping.compass`, but the fallback key is a nonexistent
+  lowercase `compass`, so an unrecognized host **throws**. Always add an explicit host entry.
+
+## Change history
+- 2026-08-04 — Documented the supply2 client host-scoping onboarding pattern, the ACL-vs-hardcoded gating split, and the NYCHH inventory fragility guardrails (planning session for the Elite client) (apeterson)

package/knowledge/INDEX.md

@@ -22,7 +22,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 21 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 5 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
-- **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
+- **toga2-supply** (TOGa Supply) — 5 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 7 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)

package/knowledge/clients/elite/INDEX.md

@@ -2,4 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Elite — supply2 frontend scope (planned)](features/supply2-scope.md) | 2.0 | **Planned** scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx |
 | [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, library/app/api/toga2.php |

package/knowledge/clients/elite/features/supply2-scope.md

@@ -0,0 +1,61 @@
+---
+title: Elite — supply2 frontend scope (planned)
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: elite
+type: client-feature
+status: draft
+updated: 2026-08-04
+owners: [apeterson]
+files:
+  - toga2-supply/ELITE-CLIENT-TASK-NOTES.md
+  - toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts
+  - toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts
+  - toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx
+  - toga2-supply/src/pages/Orders/OrdersPage.tsx
+  - toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts
+  - toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts
+  - toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx
+  - toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx
+related:
+  - ../../2.0/apps/toga2-supply/workflows/client-host-scoping.md
+  - ../profile.md
+---
+
+## Summary
+
+**Planned** scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). This is
+a scoping/handoff plan — **no code was written**; the source-of-truth plan is
+`toga2-supply/ELITE-CLIENT-TASK-NOTES.md` at the repo root. Elite's supply2 surface is two
+pages: **Sales Orders** (table + details modal, **no approvals**) and **Inventory** (a single
+"Units By Items" group-by view, nested expand, no modal). Follow the shared
+[host-scoping onboarding playbook](../../2.0/apps/toga2-supply/workflows/client-host-scoping.md)
+and its guardrails when implementing.
+
+## Part 1 — Inventory
+
+- One host-scoped group-by view only: **"Units By Items"**, no group-by modal.
+- Elite introduces the **first host-scoping** of the global `DUMMYGROUPOPTIONS.ts` static —
+  return a **separate array** for `ELITE` (do not filter the shared array); exactly one
+  `isDefault`; use a **distinct `urlKeys.key`**; never reorder NYCHH's existing options.
+- Lock to the single view via `INVENTORYPAGEFIELDS.ts` `isGroupByModalVisible: false`
+  (host-scoped).
+- No modal is already the default (`InventoryPage.tsx` `hasModalTable=false`,
+  `rowsHaveModalOnClick=false`). **Nested rows non-clickable is automatic** when
+  `isNestedTable: true` (the `onRowClick` no-op in `PrimaryTableContent.tsx`).
+
+## Part 2 — Sales Orders
+
+- Table columns are backend pageMeta-driven for slug `sales-orders`; ACL fetched under slug
+  `sales-orders-listing`.
+- **Details modal needs no code:** `renderModalContent.tsx` DEFAULT routes unknown hosts to
+  `OrderDetailsModal` only (no `ApprovalsModal`); `useOrderDetailsViewModel.ts` falls back to
+  `DEFAULTFIELDS.json`.
+- **Required FE change:** add an explicit `ELITE` entry to `useOrdersPageViewModel.ts`
+  `fieldMapping`. The fallback `fieldMapping[hostName] || fieldMapping.compass` references a
+  nonexistent lowercase `compass` key, so an unrecognized host **throws**. Elite's FIELDS must
+  set `approvalsButton.isEnabled=false` and omit `approvalActionOptions` to exclude approvals.
+
+## Change history
+- 2026-08-04 — Captured the planned Elite supply2 scope (Inventory single-view + Sales Orders without approvals) from the ELITE-CLIENT-TASK-NOTES.md scoping session; no code written yet (apeterson)

package/knowledge/clients/elite/profile.md

@@ -4,18 +4,20 @@ framework: "2.0"
 apps:
   - worker2
   - library
+  - toga2-supply
 project: Worker
 client: elite
 type: profile
 status: active
-updated: 2026-06-10
-owners: [snaredla]
+updated: 2026-08-04
+owners: [snaredla, apeterson]
 files:
   - worker2/Worker/Elite.php
   - library/app/api/toga2.php
 related:
   - 2.0/apps/worker2/features/elite-freshservice-sync.md
   - 1.0/apps/library/features/elite-freshservice-sync.md
+  - features/supply2-scope.md
 ---
 
 ## Summary

package/package.json

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