toga-ai 1.0.51 → 1.0.53

package/knowledge/2.0/apps/api2/INDEX.md

@@ -3,4 +3,3 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [Nested Field Foreign-Key Resolution (getChildOptionRecords)](bug/nested-field-foreign-key-resolution.md) | When a request supplies a `fields` option, the V2 JSON engine does NOT use the depth-bounded `getFullModelData()` serializer. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ItemCategoryFeature.php, _underscore/Model/Client/ItemFeature.php, _underscore/Model/Client/ItemCategoryFeatureGroup.php |

package/knowledge/INDEX.md

@@ -11,10 +11,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 4 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 5 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 2 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 
 ## Clients
 

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

@@ -2,6 +2,6 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php |
+| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql |
 | [Compass: Item Fulfillments for Sales Order Items TableView (tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in Client_Compass) was rebuilt as part of the tracking-number bridge migra | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -5,10 +5,12 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-08
+updated: 2026-06-11
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - api2/Component/Api/Cxml/Cxml.php
+  - dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -21,41 +23,81 @@ IFIUs for serialized units, and IF packages for tracking. ASNs arrive two ways:
 **cXML** (direct V2 API) and the worker email cron
 `3b_import_strategic_systems_advance_shipping_notices.php`.
 
+Tracking numbers are propagated across **every** ASN and IF granularity (see *Tracking number
+propagation* below), so a single ShipNotice tracking number lands at the header, item, and
+unit level on both sides — not just on one unit.
+
 ## Key files / entry points
+- `api2/Component/Api/Cxml/Cxml.php` — the cXML `ShipNoticeRequest` translator that builds
+  the `/advance-shipping-notices` POST payload.
 - `_underscore/Model/Compass/AdvanceShippingNotice.php` — `postPost(&$api, &$payload)`.
 - Fires only when the Compass ASN `ApiPayloadInterceptors` rows exist (interceptor is DB-driven).
+- `Model/Compass/Usa/` and `Model/Compass/Canada/` ASN classes are **empty subclasses** that
+  inherit `postPost` from `_Model_Compass_AdvanceShippingNotice` — edit the parent.
 
 ## How it works
 1. Read ASN → resolve PO → SO via `SalesOrders_PurchaseOrders`; skip if no SO.
 2. Select ASN items whose SOI still has unfulfilled qty (`SOI.quantity > SUM(IFI.quantity)`).
 3. Reuse the IF if one already exists with the SO number, else POST a new IF.
-4. Per ASN item: POST an IFI (qty = ASN item qty), then read its ASN units.
-5. Per ASN unit: if it has a Unit (serialized) → POST an IFIU; if it is tracking-only
-   (`unitId IS NULL`) → collect its tracking number for an IF package instead.
+4. Per ASN item: POST an IFI (qty = ASN item qty); then copy that ASN item's tracking numbers
+   (`AdvanceShippingNoticeItems_TrackingNumbers`) onto the IF item via
+   `POST /item-fulfillment-item-tracking-numbers` → `ItemFulfillmentItems_TrackingNumbers`.
+5. Per ASN unit: if it has a Unit (serialized) → POST an IFIU (carrying unit tracking); if it
+   is tracking-only (`unitId IS NULL`) → collect its tracking number for an IF package instead.
 6. Create one IF package per unique tracking number (header-level tracking merged with
    tracking-only ASN-unit tracking, deduped by tracking-number uuid).
 
+## Tracking number propagation
+The cXML translator maps each `ShipControl` block's tracking number to a line via its
+`LineNumber` Extrinsic (it iterates **all** ShipControls and **all** ShipNoticeItems, not just
+`[0]`), then attaches the number at every level. End state for a cXML ShipNotice:
+
+| Table | Populated by |
+|---|---|
+| `AdvanceShippingNotices_TrackingNumbers` | cXML payload (ASN header) |
+| `AdvanceShippingNoticeItems_TrackingNumbers` | cXML payload (matched line's item) |
+| `AdvanceShippingNoticeItemUnits_TrackingNumbers` | cXML payload (tracking-only unit) |
+| `ItemFulfillments_TrackingNumbers` | `postPost` IF package |
+| `ItemFulfillmentItems_TrackingNumbers` | `postPost` (copies ASN-item tracking) |
+| `ItemFulfillmentItemUnits_TrackingNumbers` | `postPost` — **only when serialized units exist** |
+
+Fix-forward only (decided 2026-06-11): applies to new ShipNotices; existing records are not
+backfilled.
+
 ## Data model
 - `AdvanceShippingNoticeUnits.unitId` is nullable (tracking-only units have NULL).
 - `ItemFulfillmentItemUnits.unitId` is **NOT NULL** — a tracking-only unit can never be an
-  IFIU; its tracking belongs on an `ItemFulfillmentPackage`.
-- Compass tracking lives in `ItemFulfillmentPackages` (header-level); IFIUs are only for
-  genuinely serialized units.
+  IFIU; its tracking belongs on an `ItemFulfillmentPackage` / `ItemFulfillments_TrackingNumbers`.
+  So for a tracking-only ShipNotice (no serialized units, the Office Depot norm) the IFIU
+  bridge legitimately stays empty — there are no IF item units to attach to.
+- Tracking bridge Records (Core): ASN = 216 (unit) / 217 (item) / 218 (header);
+  IF = 317 (header) / 318 (item) / 319 (unit). All six are registered inherent children of
+  their parents, so the nested payload keys are accepted with no metadata migration.
 
 ## Client variations
 Compass USA handler (`Model/Compass/`), extending `_Model_Client_AdvanceShippingNotice`.
-Compass Canada (`Model/Compass/Canada/`) is a separate sub-client.
+Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass cXML API
+(Core `ClientApiIdentities` identity `153531108`, clientId 2) holds roles 1 and 3.
 
 ## Gotchas / known issues
+- **Record 217 ACL gap (fixed 2026-06-11):** `AdvanceShippingNoticeItems_TrackingNumbers`
+  (Record 217) had **zero** `AclRecordPermissions` and its `advanceShippingNoticeItemId`
+  (RecordField 1440) / `trackingNumberId` (1441) fields had **zero** `AclFieldPermissions`,
+  so ASN-item-level tracking POSTs were rejected (`EZ-1`). `dbchanges2/Client_Compass/2026-06-11
+  - AsnItemTrackingNumberAcl.sql` grants role 3 CRUD + role 7 read at the record level and
+  roles 1/3/4 writable at the field level, mirroring sibling Record 216. **This SQL must be
+  executed against the Compass DB before the cXML change works end-to-end.**
 - **Tracking-only ASN units (the majority — ~56k of ~101k in prod):** before 2026-06-08 the
   IFIU query used `INNER JOIN Units`, silently dropping NULL-`unitId` rows, so cXML shipments
   produced an IF + IFI with **no IFIU and no package — tracking was lost**. Fixed: `LEFT
   OUTER JOIN Units` + route tracking-only units to IF packages. Historical records (e.g.
-  SO SA132502 / IF 66997) are **not backfilled** — fix-forward only; a one-time repair is
-  still an open decision.
+  SO SA132502 / IF 66997) are **not backfilled** — fix-forward only.
 - Interceptor is **DB-driven**: `postPost` does nothing without the Compass
   `ApiPayloadInterceptors` rows in that env.
 - The IF is named after the SO number; an already-existing IF with that number is reused.
+- **cXML SQL-injection hardening (2026-06-11):** the `ShipNoticeRequest` path interpolated the
+  cXML `Sender` Identity / SharedSecret and the OrderReference `orderID` (purchase order
+  number) straight into queries. These are now passed through `_Database::escape()`.
 - Separate latent bug in the 1.0 worker: the Strategic Systems cron's no-serials branch
   builds `$itemLevelTrackingNumbers` but never attaches it to the ASN payload.
 

package/knowledge/registry.json

@@ -5,6 +5,5 @@
   { "repo": "dbchanges2",  "project": "Database Changes", "framework": "2.0", "role": "core", "dependsOn": [] },
   { "repo": "library",     "project": "Library",     "framework": "1.0", "role": "core", "dependsOn": [] },
   { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "toga2-commerce", "project": "TOGa Commerce", "framework": "2.0", "role": "app", "dependsOn": ["api2"] }
+  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
 ]

package/package.json

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

package/knowledge/2.0/apps/api2/bug/nested-field-foreign-key-resolution.md

@@ -1,108 +0,0 @@
----
-title: Nested Field Foreign-Key Resolution (getChildOptionRecords)
-framework: "2.0"
-repo: api2
-project: API
-client: shared
-type: feature
-status: active
-updated: 2026-06-11
-owners: [bala]
-files:
-  - api2/Component/Api/V2/V2.php
-  - _underscore/Model/Client/ItemCategoryFeature.php
-  - _underscore/Model/Client/ItemFeature.php
-  - _underscore/Model/Client/ItemCategoryFeatureGroup.php
-related:
-  - 2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md
----
-
-## Summary
-
-When a request supplies a `fields` option, the V2 JSON engine does NOT use the
-depth-bounded `getFullModelData()` serializer. It uses a fields-driven serializer
-(`V2.php` ~line 3383) that splits each nested field path into:
-
-- **foreign-key sub-objects** (belongsTo) → resolved by `getChildOptionRecords()`
-- **inherent children** (one-to-many) → resolved by recursive `processRoutePairs()`
-
-There was a bug in `getChildOptionRecords()`: a foreign-key sub-object that sits on an
-**inherent child which is itself reached underneath another foreign-key parent** was
-fetched but never attached to the output, so it silently disappeared from the JSON.
-
-This surfaced as the `toga2-commerce` item-view "Specifications" headings showing
-`undefined` when an item was opened **through a bundle** (but not through a category).
-
-## Key files / entry points
-
-- `api2/Component/Api/V2/V2.php`
-  - `execute()` / `processRoutePairs()` — request lifecycle, depth setup (`DEFAULT_DEPTH = 3`).
-  - fields-driven serialization branch at ~line 3383 (`if (empty($selectFields))` else).
-  - `getChildOptionRecords()` (~line 5279) — resolves FK sub-objects and nested inherent children.
-
-## How it works
-
-For a request like `GET /items/{uuid}` with
-`...itemFeatures.itemCategoryFeatures.itemCategoryFeatureGroup.name`:
-
-- The item is the **top-level record**, so `itemFeatures` and `itemCategoryFeatures` are
-  handled as inherent children via the main `processRoutePairs` recursion, and
-  `itemCategoryFeatureGroup` (an FK on `ItemCategoryFeature`) resolves correctly. WORKS.
-
-For `GET /bundles/{uuid}` with
-`bundleItems.item.itemFeatures.itemCategoryFeatures.itemCategoryFeatureGroup.name`:
-
-- The top record is the bundle; `item` is an **FK** on `bundleItem`. Stepping through that FK
-  routes the whole `item` subtree into `getChildOptionRecords()`.
-- Inside it: `feature` is an FK → handled correctly (so `feature.measure.name` came back).
-  But `itemCategoryFeatures` is an **inherent child**, so it fell into the branch at
-  ~line 5779 ("requesting all available data for an inherent child"). That branch fetched
-  each row's FK (`itemCategoryFeatureGroup`) into `$res` (~line 5840) and **discarded it** —
-  only scalar columns (`uuid`, `limitDirection`) were attached. The group fell out.
-
-## The fix
-
-Attach the resolved FK result to the inherent child row (after the `getChildOptionRecords`
-call at ~line 5850):
-
-```php
-$outDataThisInherentChild[$inherentChildField] = $res;
-```
-
-## Data model
-
-Relationship chain (all `_Model_Client_*`, DB_CLIENT):
-
-- `ItemFeature` (`itemId`, `featureId`) — inherent child of `Item`.
-- `ItemCategoryFeature` (`itemFeatureId`, `itemCategoryFeatureGroupId`, `limitDirection`) —
-  inherent child of `ItemFeature`.
-- `ItemCategoryFeatureGroup` (`itemCategoryId`, `name`) — FK target that holds the heading.
-- `Feature` (`measureId`) -> `Measure` — the FK chain that always worked (different code arm).
-
-## Client variations
-
-None — this is a core engine fix affecting every client and every endpoint whose `fields`
-request has the shape "FK -> inherent child -> FK". The common top-level case
-(`/items`, `/sales-orders`, etc.) uses the other code path and is unaffected.
-
-## Gotchas / known issues
-
-- It is NOT a depth, ACL, or data problem. Verified against prod `Client_Compass`:
-  the group data exists (0 null `itemCategoryFeatureGroupId`), the
-  `item-category-feature-groups` record (126) has READ with `indirectRecordId = NULL`
-  (readable on any path), and no `minDepth` interceptor applies — both calls run at
-  `DEFAULT_DEPTH = 3`. `feature.measure.name` and `itemCategoryFeatureGroup.name` are at
-  identical nesting depth, so depth could never explain why one survived and the other did
-  not — the real cause is FK-vs-inherent-child handling.
-- Tell-tale sign of the buggy branch: it ignores the requested sub-fields and dumps all
-  permitted scalar columns, so the response contained a `uuid` that was never requested.
-- This branch still ignores `$varOptions` (over-returns columns) — the fix only makes FK
-  sub-objects consistent with the scalars. Acceptable and ACL-bounded, but slightly more
-  payload.
-- Leftover dead code: a second `getChildOptionRecords()` call at ~line 5887 also computes
-  `$res` and discards it (and references `$newPreviousIdentifiers`, only defined when an FK
-  field was seen). Left untouched to keep the fix minimal; worth removing separately.
-
-## Related docs
-
-- 2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md

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

@@ -1,6 +0,0 @@
-# toga2-commerce (TOGa Commerce) — 2.0 knowledge
-
-| Doc | Summary | Files |
-|-----|---------|-------|
-| [TOGa Commerce (toga2-commerce) Architecture](architecture.md) | TOGa Commerce (npm package `commerce2-react`) is the multi-tenant 2.0 storefront. | toga2-commerce/src/App.tsx, toga2-commerce/src/routes.tsx, toga2-commerce/src/api/axiosInstance.ts, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/themeConfig/ThemeContext.tsx, toga2-commerce/src/stores/index.ts |
-| [Item-View Bundle vs Direct Fetch](bug/item-view-bundle-vs-direct-fetch.md) | The item-view page (`/item-view`) fetches a single item two different ways depending on how the user reached it and what access they have: - **Direct** — `GET / | toga2-commerce/src/pages/ItemsView/api/ItemsApi.ts, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |

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

@@ -1,68 +0,0 @@
----
-title: TOGa Commerce (toga2-commerce) Architecture
-framework: "2.0"
-repo: toga2-commerce
-project: TOGa Commerce
-client: shared
-type: architecture
-status: active
-updated: 2026-06-11
-owners: [bala]
-files:
-  - toga2-commerce/src/App.tsx
-  - toga2-commerce/src/routes.tsx
-  - toga2-commerce/src/api/axiosInstance.ts
-  - toga2-commerce/src/contexts/AuthContext.tsx
-  - toga2-commerce/src/themeConfig/ThemeContext.tsx
-  - toga2-commerce/src/stores/index.ts
-related: []
----
-
-## Summary
-
-TOGa Commerce (npm package `commerce2-react`) is the multi-tenant 2.0 storefront. React 18 +
-Vite + TypeScript + Tailwind. Its backend is api2 (2.0 REST); shared UI comes from the
-`@agilant/toga-blox` component library. Multi-tenant by hostname — dev hosts include
-`compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`, `togacommerce`
-(see the `npm run` scripts in `package.json`).
-
-## Routing & shell
-
-- `src/routes.tsx` — `createBrowserRouter` (react-router-dom v7). `PrivateRoute` gates all
-  authed pages behind `useAuthenticationFlow`; authed pages are wrapped in `AuthLayout`.
-  Pages: Home, Filter, ItemsView (`/item-view`), BundleView, Cart, OrderDetails, Account,
-  GetSupport, Login, ResetPassword, Privacy/Terms.
-- `src/App.tsx` — provider stack: `PersistQueryClientProvider` (TanStack Query persisted to
-  `localStorage`, key `commerce`, 24h staleTime) -> `AuthProvider` -> `ThemeProvider` ->
-  `ToasterProvider` -> `RouterProvider`.
-
-## State management
-
-- **Server state:** TanStack Query, persisted to localStorage. Query defs in `src/queries/`.
-- **Client state:** Zustand stores in `src/stores/` — cart (`useCartStoreZu`), edit-order mode
-  (`useEditOrderZu`), bundle builder, user, fields, view-as impersonation, etc.
-- **Cart <-> API sync:** `src/api/` holds `syncSalesOrderFromApiToLocalStorage`,
-  `syncSalesOrderItemsFromLocalStorageCartToApi`, `syncSalesOrdersDataFromLocalStorageCartToApi`.
-  The cart lives in localStorage and syncs to api2 sales orders; "Edit Order" mode lets users
-  edit an existing sales order (App.tsx tracks a `synced` flag).
-
-## Cross-cutting
-
-- **Auth:** `src/contexts/AuthContext.tsx`, token-based, plus a "View As" user-impersonation
-  flow (`useReturnOriginalUserFromViewAsStore`).
-- **Theming:** `src/themeConfig/ThemeContext.tsx` + `themes.json`, per tenant.
-- **Dynamic fields:** `src/fieldsConfig/` and per-page `FIELDS/<CLIENT>/<LANG>/<ROLE>/*.json`
-  drive client-specific form/field sets.
-- **HTTP:** axios instance in `src/api/axiosInstance.ts`; Sentry for error reporting;
-  react-hook-form for forms.
-
-## Key decisions / gotchas
-
-- `dependsOn: ["api2"]` — runtime dependency on the api2 REST surface (not a PHP class
-  dependency). Field requests use the api2 `fields` option; deep nested field paths are
-  subject to api2's serializer behavior (see related api2 doc on FK resolution).
-
-## Related docs
-
-- 2.0/apps/api2/bug/nested-field-foreign-key-resolution.md
-- 2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md

package/knowledge/2.0/apps/toga2-commerce/bug/item-view-bundle-vs-direct-fetch.md

@@ -1,69 +0,0 @@
----
-title: Item-View Bundle vs Direct Fetch
-framework: "2.0"
-repo: toga2-commerce
-project: TOGa Commerce
-client: shared
-type: feature
-status: active
-updated: 2026-06-11
-owners: [bala]
-files:
-  - toga2-commerce/src/pages/ItemsView/api/ItemsApi.ts
-  - toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts
-related:
-  - 2.0/apps/api2/bug/nested-field-foreign-key-resolution.md
----
-
-## Summary
-
-The item-view page (`/item-view`) fetches a single item two different ways depending on how
-the user reached it and what access they have:
-
-- **Direct** — `GET /items/{uuid}` via `fetchItemDetails()`. Used for users with direct item
-  access. Fields come from the client/role `ITEMVIEWPAGEFIELDS.json` config.
-- **Via bundle** — `GET /bundles/{uuid}` via `fetchItemDetailsViaBundle()`, then the bundle's
-  `bundleItems` are filtered client-side to the requested item uuid. Used for **indirect-access**
-  users (they can read the item through the bundle ACL but not the item endpoint directly).
-  Triggered when the URL has `type=bundleItem` and a `bundleUuid` query param.
-
-## Key files / entry points
-
-- `src/pages/ItemsView/api/ItemsApi.ts`
-  - `fetchItemDetails()` — direct `/items/{uuid}` fetch (fields from config, optional persona where).
-  - `fetchItemDetailsViaBundle()` — `/bundles/{uuid}` fetch with `bundleItems.item.*` fields,
-    then client-side filter to the matching item (API does not support nested-uuid where clauses).
-- `src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts`
-  - Chooses the fetch by `viewTypeParam === "bundleItem" && bundleUuid`.
-  - Groups features for the Specifications section by
-    `itemCategoryFeatures[0].itemCategoryFeatureGroup?.name`. If that group object is missing,
-    the heading key becomes the string `undefined`.
-
-## How it works
-
-1. Read `uuid`, `type`, `bundleUuid` from the URL query string.
-2. If `type=bundleItem` and `bundleUuid` present → `fetchItemDetailsViaBundle`; else
-   `fetchItemDetails`.
-3. Normalize the response to `{ data: { items } }` and group `itemFeatures` by their
-   category-feature group name for display.
-
-## Client variations
-
-Multi-tenant by host (compass / compasscanada / quad / togacommerce). Field sets are
-per-client/per-language/per-role under
-`src/pages/ItemsView/viewModel/FIELDS/<CLIENT>/<LANG>/<ROLE>/ITEMVIEWPAGEFIELDS.json`.
-
-## Gotchas / known issues
-
-- The two fetch paths request the same leaf fields but at different nesting depths
-  (`bundle -> bundleItems -> item -> ...` adds two levels). This exposed an api2 serializer
-  bug where the `itemCategoryFeatureGroup` foreign key was dropped only on the bundle path,
-  making Specifications headings render as `undefined`. Root cause and fix are documented in
-  the api2 feature doc below — the frontend grouping logic itself is correct and identical
-  on both paths.
-- `fetchItemDetailsViaBundle` exists specifically for indirect-access users, so you cannot
-  simply switch it to `/items/{uuid}` — those users would hit an ACL denial.
-
-## Related docs
-
-- 2.0/apps/api2/bug/nested-field-foreign-key-resolution.md