toga-ai 1.0.41 → 1.0.43

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

@@ -5,3 +5,4 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
+| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql |

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -0,0 +1,123 @@
+---
+title: Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php
+  - _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php
+  - _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Prudential/AdvanceShippingNotice.php
+  - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - _underscore/Trait/Netsuite/ItemFulfillment.php
+  - api2/Component/Api/Cxml/Cxml.php
+  - dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql
+  - dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql
+related:
+  - recursive-item-fulfillments.md
+---
+
+## Summary
+
+Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`,
+`returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables across the ASN,
+Item Fulfillment (IF), and Item Receipt (IR) hierarchies. This migration moves all tracking
+into dedicated **`*_TrackingNumbers` bridge tables** (one consistent pattern per hierarchy
+level), so a record can carry multiple tracking numbers and the model is uniform. It also:
+
+- renames the ASN **`AdvanceShippingNoticeUnits`** table → **`AdvanceShippingNoticeItemUnits`**
+  (and its bridge + FK column `advanceShippingNoticeUnitId` → `advanceShippingNoticeItemUnitId`),
+- consolidates **`ItemFulfillmentPackages`** (header-level tracking) into
+  **`ItemFulfillments_TrackingNumbers`** and **drops the packages table**,
+- makes tracking a model concept submitted/read **as an inherent child of the parent record**
+  (not a scalar field).
+
+## The bridge pattern
+
+Each hierarchy level gets a bridge keyed to its parent plus `trackingNumberId`
+(+ `returnTrackingNumberId` on ASN and IF bridges; IR has no returns):
+
+| Level | Bridge table | Core Record id | Route (inherent-child key) |
+|---|---|---|---|
+| ASN | AdvanceShippingNotices_TrackingNumbers | 218 | advance-shipping-notice-tracking-numbers |
+| ASN item | AdvanceShippingNoticeItems_TrackingNumbers | 217 | advance-shipping-notice-item-tracking-numbers |
+| ASN unit | AdvanceShippingNoticeItemUnits_TrackingNumbers | 216 (renamed) | advance-shipping-notice-item-unit-tracking-numbers |
+| IF | ItemFulfillments_TrackingNumbers | 317 (new) | item-fulfillment-tracking-numbers |
+| IF item | ItemFulfillmentItems_TrackingNumbers | 318 (new) | item-fulfillment-item-tracking-numbers |
+| IF item unit | ItemFulfillmentItemUnits_TrackingNumbers | 319 (new) | item-fulfillment-item-unit-tracking-numbers |
+| IR | ItemReceipts_TrackingNumbers | 320 (new) | item-receipt-tracking-numbers |
+| IR item | ItemReceiptItems_TrackingNumbers | 321 (new) | item-receipt-item-tracking-numbers |
+| IR item unit | ItemReceiptItemUnits_TrackingNumbers | 322 (new) | item-receipt-item-unit-tracking-numbers |
+
+All bridges are registered as **`InherentRecordChildren`** of their parent record, so the
+engine derives the payload key from the bridge route (kebab→camel) — e.g. an ASN unit's
+tracking is submitted as `advanceShippingNoticeItemUnitTrackingNumbers: [{ trackingNumber: {...},
+returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTrackingNumbers`.
+
+## Key files / entry points
+
+- **Bridge models** — `Model/Client/<Parent>/TrackingNumber.php` (e.g. `ItemFulfillmentItemUnits/TrackingNumber.php`).
+  The renamed ASN unit model is `Model/Client/AdvanceShippingNoticeItemUnit.php`; the old
+  `AdvanceShippingNoticeUnit.php` + `AdvanceShippingNoticeUnits/TrackingNumber.php` were deleted.
+- **Recursive feature** — `Model/Client/ItemFulfillment.php`: `reconcileUpstreamUnits` and
+  `reconcileUpstreamPackages` now read/write the bridges (POST `/item-fulfillment-item-unit-tracking-numbers`
+  and `/item-fulfillment-tracking-numbers`); unit deletes cascade to the inherent-child bridge rows.
+  The FedEx/shipping-label methods read header tracking from `ItemFulfillments_TrackingNumbers`.
+- **Prudential interceptor** — `Model/Prudential/AdvanceShippingNotice.php::prePost` (see the
+  Prudential client doc).
+- **cXML inbound** — `api2/Component/Api/Cxml/Cxml.php` emits the new key + bridge-child tracking.
+- **DB** — `dbchanges2/Core/...` (records/fields/ACL/inherent-children, record-41 teardown),
+  `dbchanges2/Client/...` (renames, bridges, migrations, ACL) split into an additions file and a
+  companion `..._DROPS.sql` for the column/table drops to run after confirmation.
+
+## Data model
+
+- New bridges: `id, uuid, <parentFk>, trackingNumberId (NULL), [returnTrackingNumberId (NULL)]`,
+  `InnoDB / utf8mb4_unicode_ci`, `UNIQUE(uuid)`, `UNIQUE(<parentFk>, trackingNumberId)`, FKs to
+  the parent + `TrackingNumbers`.
+- Dropped (in the DROPS file): `AdvanceShippingNoticeItemUnits.trackingNumberId/returnTrackingNumberId`,
+  `ItemFulfillmentItemUnits.trackingNumberId`, `ItemReceiptItems.trackingNumberId`,
+  `ItemReceiptItemUnits.trackingNumberId`, and the entire `ItemFulfillmentPackages` table.
+- Core: Records 61 (unit) + 216 (unit bridge) renamed; new Records 317–322 + RecordFields 2171–2200;
+  `returnTrackingNumberId` RecordFields added to 216/217/218; dropped RecordFields 334/652/1431/1576/1577;
+  record 41 (item-fulfillment-packages) fully removed. Label settings (`DefaultRecordFieldSettings`)
+  and `Records.labelRecordFieldId` are **repointed** from dropped fields to the new bridge fields.
+
+## Client variations
+
+- **Compass (Client_Compass / compass-usa):** ASN→IF auto-creation (`Model/Compass/AdvanceShippingNotice.php`)
+  posts unit tracking + header tracking via the bridge routes; `Model/Compass/SalesOrder.php::_trackingNumbers`
+  reads through the bridges. The `item-fulfillments-for-sales-order-items` TableView was rebuilt
+  (see the compass-usa client doc).
+- **Prudential (Client_Prudential):** Dell posts the legacy `advanceShippingNoticeUnits` key with flat
+  tracking — a PRE/POST interceptor rewrites it (see the prudential client doc).
+- **NetSuite-integrated clients:** `Trait/Netsuite/ItemFulfillment.php` now reads
+  `itemFulfillmentTrackingNumbers` and posts `/item-fulfillment-tracking-numbers`. The 1.0 library
+  `App_Api_Toga2` (`library/app/api/toga2.php`) got the same change for the worker tier.
+
+## Gotchas / known issues
+
+- **Tracking is now an inherent child, not a scalar.** Any producer that sent a flat `trackingNumber`
+  on a unit must nest it under the unit's `*TrackingNumbers` child array, or it is silently dropped.
+- **Migration FK pitfalls (all handled in the SQL):** deleting `RecordFields` hits `DefaultRecordFieldSettings`
+  FKs (repoint first); deleting `AclRecordPermissions` hits the `AclLogicGroups`→`AclLogicGroupExpressions`
+  chain (record-41 teardown wraps it in `SET FOREIGN_KEY_CHECKS=0`); deleting `TableViewFields` hits
+  `TableViews.sortPrimaryTableViewFieldId` (null it first, re-point after); self-referencing `INSERT … NOT EXISTS`
+  on the target table errors 1093 (use a derived table); and orphaned/dangling `trackingNumberId` values
+  fail the bridge FK 1452 (join `TrackingNumbers` so orphans become NULL / are skipped).
+- **UUIDs in SQL:** generated with `RANDOM_BYTES()` (MySQL 8) — never MySQL `UUID()` (per 2.0 standard).
+- **Dropped FK constraint names vary per client** — drop them dynamically via `INFORMATION_SCHEMA` + PREPARE.
+- **Deploy coupling:** renames are NOT backward compatible — apply the DB migration and deploy
+  `_underscore` + `api2` + `worker` + `library` together. Run the additions/migrations DB file first;
+  run the companion `..._DROPS.sql` (and the Core deletes) only after the bridges + app are confirmed.
+
+## Related docs
+- Recursive Item Fulfillment feature (the upstream-sync engine this migration reworked).
+- compass-usa: ASN→Item Fulfillment, and the Item Fulfillment tracking TableView.
+- prudential: Dell ASN units interceptor.

package/knowledge/INDEX.md

@@ -9,7 +9,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 3 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_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) — 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)
@@ -17,8 +17,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## Clients
 
-- **compass-canada** → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
-- **compass-usa** → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
-- **elite** → [clients/elite/INDEX.md](clients/elite/INDEX.md)
-- **nycdoe** → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
+- **Compass Canada** (`compass-canada`) → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
+- **Compass USA** (`compass-usa`) → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
+- **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
+- **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
+- **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 

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

@@ -1,4 +1,4 @@
-# Client: compass-canada
+# Client: Compass Canada `compass-canada`
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|

package/knowledge/clients/compass-canada/profile.md

@@ -1,5 +1,6 @@
 ---
 title: Compass Canada
+name: "Compass Canada"
 framework: "2.0"
 project: _Underscore
 client: compass-canada

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

@@ -1,6 +1,7 @@
-# Client: compass-usa
+# Client: Compass USA `compass-usa`
 
 | 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: 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/item-fulfillment-tracking-tableview.md

@@ -0,0 +1,46 @@
+---
+title: "Compass: Item Fulfillments for Sales Order Items TableView (tracking via bridge)"
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql
+related:
+  - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+
+The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in
+Client_Compass) was rebuilt as part of the tracking-number bridge migration. It was rooted at
+**Units** with INNER joins (so non-serialized items with no unit never appeared) and sourced the
+outbound tracking number from the now-dropped `ItemFulfillmentItemUnits.trackingNumberId`.
+
+## How it works (new definition)
+
+- **Base record re-rooted** to `ItemFulfillmentItems` (record 29).
+- Joins: INNER `SalesOrderItems`; **OUTER** `ItemFulfillmentItemUnits` (so items without a
+  serialized unit still return); OUTER `Units`; OUTER the new `ItemFulfillmentItemUnits_TrackingNumbers`
+  bridge (record 319) → OUTER `TrackingNumbers` → OUTER `ShippingCarriers`.
+- Columns, in order: **Sales Order Line Number, Quantity Fulfilled (new — `ItemFulfillmentItems.quantity`),
+  Outbound Tracking #, Carrier, Serial #, Asset Tag.**
+- Default sort (`TableViews.sortPrimaryTableViewFieldId`) re-pointed to the line-number field.
+
+## Gotchas / known issues
+
+- Tracking is sourced through the bridge join (`ItemFulfillmentItemUnits_TrackingNumbers.trackingNumberId`),
+  NOT the dropped column. The bridge record/fields (319 / 2183 itemFulfillmentItemUnitId / 2184
+  trackingNumberId) come from the Core migration and must exist before this file runs.
+- `TableViews.sortPrimaryTableViewFieldId` is a FK to `TableViewFields`; it must be set NULL before the
+  old fields are deleted, then re-pointed (via a multi-table UPDATE, not a self-subquery, to avoid 1093).
+- `TableViewFields` must be deleted before `TableViewJoins` (`tableViewJoinId` FK).
+
+## Client variations
+This is Compass-only. The underlying bridge model is shared (see the _underscore feature doc).
+
+## Related docs
+- 2.0 _underscore: Tracking-Number Bridge Migration.

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

@@ -1,5 +1,6 @@
 ---
 title: Compass USA
+name: "Compass USA"
 framework: "2.0"
 project: _Underscore
 client: compass-usa

package/knowledge/clients/elite/INDEX.md

@@ -1,4 +1,4 @@
-# Client: elite
+# Client: Elite `elite`
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|

package/knowledge/clients/elite/profile.md

@@ -1,5 +1,6 @@
 ---
 title: Elite Client Profile
+name: "Elite"
 framework: "2.0"
 project: Worker
 client: elite

package/knowledge/clients/nycdoe/INDEX.md

@@ -1,4 +1,4 @@
-# Client: nycdoe
+# Client: New York City Department of Education `nycdoe`
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|

package/knowledge/clients/nycdoe/profile.md

@@ -1,5 +1,6 @@
 ---
 title: NYC DOE (New York City Department of Education)
+name: "New York City Department of Education"
 framework: "1.0"
 project: Worker
 client: nycdoe

package/knowledge/clients/prudential/INDEX.md

@@ -0,0 +1,6 @@
+# Client: Prudential Financial `prudential`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
+| [Prudential](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |

package/knowledge/clients/prudential/features/dell-asn-units-interceptor.md

@@ -0,0 +1,51 @@
+---
+title: "Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)"
+framework: "2.0"
+project: _Underscore
+client: prudential
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Prudential/AdvanceShippingNotice.php
+  - dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql
+related:
+  - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+
+After the tracking-number bridge migration, the ASN unit route was renamed
+(`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inherent-child
+key became `advanceShippingNoticeItemUnits`, and unit tracking now lives in the bridge child
+`advanceShippingNoticeItemUnitTrackingNumbers` (the scalar `trackingNumber`/`returnTrackingNumber`
+fields on the unit were dropped). **Dell will not change their payload**, so a Prudential-only
+interceptor translates it on the way in.
+
+## How it works
+
+- **`Model/Prudential/AdvanceShippingNotice.php::prePost(&$api, &$payload)`** — for each
+  `$payload->advanceShippingNoticeItems[]`: renames the legacy `advanceShippingNoticeUnits` key to
+  `advanceShippingNoticeItemUnits`, and lifts each unit's flat `trackingNumber` / `returnTrackingNumber`
+  into a single `advanceShippingNoticeItemUnitTrackingNumbers` bridge-child row, removing the flat fields.
+- **Registration** — `Client_Prudential.ApiPayloadInterceptors` row: `recordId = 55`
+  (advance-shipping-notices), `prePostProcessing = 'PRE'`, `httpMethod = 'POST'`, `apiId = 2` (Dell),
+  `isActive = 1`. The engine resolves `_Model_Client_AdvanceShippingNotice` → `_Model_Prudential_AdvanceShippingNotice`
+  by client identifier; **both** the DB interceptor row AND the model method are required for it to fire.
+
+## Inbound payload (Dell, unchanged)
+```
+advanceShippingNoticeItems: [ { quantity, advanceShippingNoticeUnits: [
+    { trackingNumber:{number}, returnTrackingNumber:{number}, unit:{serialNumber} } ] } ]
+```
+The interceptor rewrites each item to `advanceShippingNoticeItemUnits` with the tracking moved into
+`advanceShippingNoticeItemUnitTrackingNumbers`.
+
+## Gotchas
+- Scoped to `apiId = 2` so other (internal) Prudential callers — which already send the new shape —
+  are not double-transformed.
+- DB change lives in `dbchanges2/Client_Prudential/`.
+
+## Related docs
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/knowledge/clients/prudential/profile.md

@@ -0,0 +1,35 @@
+---
+title: Prudential
+name: "Prudential Financial"
+framework: "2.0"
+project: _Underscore
+client: prudential
+type: profile
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files: []
+related:
+  - features/dell-asn-units-interceptor.md
+---
+
+## Summary
+Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell
+API (`Client_Prudential.Apis.id = 2`). Dell posts Advance Shipping Notices (with tracking and
+return-tracking per unit) into the 2.0 platform (DB `Client_Prudential`); the 1.0 worker tier
+(`crons/toga2/prudential/`) handles NetSuite sync, ServiceNow (RITM) close/ship updates, and
+order-status transmissions.
+
+## Integrations
+- **Inbound:** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Outbound (worker crons):** `transmissions_to_netsuite.php`, `transmit_ordershipped_updates_prudential.php`,
+  `transmit_closecomplete_updates_prudential.php`, `transmit_order_delivered_updates_from_fedex_toga2.php`,
+  `update_tracking_number_from_netsuite_to_toga.php`, `manually_insert_ASN.php`.
+
+## Gotchas
+- Dell will not change their payload shape — see the Dell ASN units interceptor feature doc for the
+  PRE/POST translation that keeps their feed working after the tracking-number bridge migration.
+
+## Related docs
+- Dell ASN units interceptor.
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/knowledge.js

@@ -252,12 +252,16 @@ function cmdIndex() {
 
     // per-client INDEX.md
     const clientsDir = path.join(ROOT, 'clients');
+    const clientFormalNames = {}; // slug -> formal name (from profile.md `name:`)
     if (fs.existsSync(clientsDir)) {
         for (const client of fs.readdirSync(clientsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)) {
             const clientDir = path.join(clientsDir, client);
             const clientDocs = docs.filter(d => d.file.startsWith(clientDir + path.sep));
+            const profileDoc = clientDocs.find(d => path.basename(d.file) === 'profile.md');
+            const formalName = (profileDoc && profileDoc.data.name) || client;
+            clientFormalNames[client] = formalName;
             const lines = [
-                `# Client: ${client}`,
+                `# Client: ${formalName} \`${client}\``,
                 '',
                 '| Doc | Framework | Summary | Files |',
                 '|-----|-----------|---------|-------|',
@@ -284,7 +288,7 @@ function cmdIndex() {
         ? fs.readdirSync(clientsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) : [];
     master.push('## Clients', '');
     if (clientNames.length === 0) master.push('_No client knowledge captured yet._', '');
-    else { for (const c of clientNames) master.push(`- **${c}** → [clients/${c}/INDEX.md](clients/${c}/INDEX.md)`); master.push(''); }
+    else { for (const c of clientNames) master.push(`- **${clientFormalNames[c] || c}** (\`${c}\`) → [clients/${c}/INDEX.md](clients/${c}/INDEX.md)`); master.push(''); }
     writeIndex(path.join(ROOT, 'INDEX.md'), master);
 
     console.log('index rebuilt: ' + docs.length + ' doc(s) across ' + registry.length + ' registered repo(s).');
@@ -340,6 +344,7 @@ function cmdValidate() {
         const isClientDoc = d.rel.startsWith('clients/');
         if (isClientDoc) {
             if (!d.data.client || d.data.client === 'shared') { fail(`${d.rel}: client doc must set a real "client"`); ok = false; }
+            if (path.basename(d.rel) === 'profile.md' && !d.data.name) { fail(`${d.rel}: client profile must set a formal "name" (e.g. name: "Compass USA")`); ok = false; }
         } else {
             // framework/apps doc: framework + repo must match the path
             const parts = d.rel.split('/'); // <fw>/apps/<repo>/...  OR <fw>/standards/...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "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/skills/capture/SKILL.md

@@ -146,6 +146,8 @@ For every doc, set/refresh frontmatter: `framework`, `repo`, `project`, `client`
 `type`, `status`, `updated` (today's date), `owners`, `files`, `related`.
 Set `owners` to `["<AUTHOR_USERNAME>"]` from Step 1b — **never leave it empty**; when a doc
 already has owners, add `AUTHOR_USERNAME` if missing rather than replacing.
+For a client `profile.md`, set the dedicated `name:` field to the client's **formal name**
+(distinct from `title`, the doc title) — `validate` requires it; see New-client onboarding.
 Add `related:` cross-links. Append new repos to `<TEAM_REPO>/knowledge/registry.json`.
 
 ## Step 6 — Validate, index, mirror back (mandatory)
@@ -355,6 +357,38 @@ Ask **all** — assume nothing (a heuristic may seed a default to confirm):
 
 Append the entry to `registry.json`, then continue. `validate` will confirm consistency.
 
+## New-client onboarding (client has no `knowledge/clients/<slug>/` folder yet)
+
+When this session's work is for a client with no `clients/<slug>/` folder, before writing
+any client docs:
+
+1. **Slug** — confirm the folder slug (lowercase, hyphenated, e.g. `compass-usa`). The slug
+   is used only for the folder name.
+2. **Formal name** — **ASK the developer for the client's formal name** (e.g. "Compass USA",
+   "New York City Department of Education"). **Never invent it from the slug.**
+3. Create `clients/<slug>/profile.md` with the formal name in the dedicated `name:` field
+   (distinct from `title`). `validate` **requires** `name:` on every client profile — a
+   profile missing it fails the build.
+
+```markdown
+---
+title: <Client> Profile
+name: "<Formal Client Name>"   # formal name; the slug is only the folder
+framework: "<1.0|2.0>"
+project: <Project>
+client: <slug>
+type: profile
+status: active
+updated: <YYYY-MM-DD>
+owners: ["<AUTHOR_USERNAME>"]
+files: []
+related: []
+---
+
+## Summary
+Who the client is and what their integration does.
+```
+
 ---
 
 ### After Capture

package/skills/kickoff/SKILL.md

@@ -117,8 +117,10 @@ Ask these in one message. **Present the repos/projects you already know** (read
    choice;** a session often spans more than one repo/project, so always let the developer
    pick several. If they pick a repo not listed, run **New-repo onboarding** (below) for
    each new repo before continuing.
-4. **Client** — which client is this for, or "shared / internal"? **List EVERY folder under
-   `knowledge/clients/`** plus "shared / internal" and "a new client" — do not show only a
+4. **Client** — which client is this for, or "shared / internal"? **List EVERY client by its
+   formal name** — read the `name:` field from each `knowledge/clients/<slug>/profile.md`
+   and show the **formal name, not the slug** (fall back to a title-cased slug only if
+   `name:` is missing). Include "shared / internal" and "a new client". Do not show only a
    subset.
 5. **What are you building or changing?** (a sentence — used to pick relevant feature docs.)
 
@@ -142,9 +144,10 @@ and naturally supports multi-select.
   N. a new repo not listed
 
 **Which client?** (one, or "shared / internal")
-  1. compass-canada
-  2. compass-usa
-  ... every folder under knowledge/clients/ ...
+  1. Compass Canada
+  2. Compass USA
+  3. Elite
+  ... every client's FORMAL name (from clients/<slug>/profile.md `name:`), not the slug ...
   S. shared / internal
   X. a new client
 ```