toga-ai 1.0.216 → 1.0.217

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

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [_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 |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
+| [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [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/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.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 |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |

package/knowledge/2.0/apps/_underscore/features/assortment-name-translation.md

@@ -0,0 +1,86 @@
+---
+title: Assortment Name Translation (AssortmentTranslations sidecar)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: ["bala"]
+files:
+  - _underscore/Model/Client/AssortmentTranslation.php
+  - dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql
+  - dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql
+  - dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql
+related:
+  - ../../api2/features/language-translation-layer.md
+  - ./acl-permission-chain.md
+---
+
+## Summary
+
+Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language
+**sidecar** table `AssortmentTranslations`, reusing the platform's existing translation mechanism.
+English stays in `Assortments.name`; the sidecar holds only non-English overlays. Because the
+translation layer is fully metadata-driven (see
+[Language Translation Layer](../../api2/features/language-translation-layer.md)), wiring this up
+required **no api2 code change** — only a new table, model, Core record registration, ACL grant,
+and a single field link. Compass Canada's French (fr-CA) assortment names are seeded as the first
+consumer.
+
+## Key files / entry points
+
+- `_underscore/Model/Client/AssortmentTranslation.php` — the sidecar model (`_Model_Client_AssortmentTranslation`).
+- `dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql` — the sidecar table (every client DB).
+- `dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql` — Core record + fields + the field link.
+- `dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql` — Base-role ACL grant (every client DB).
+
+## How it works
+
+The mechanism itself is the data-driven translation layer documented in
+[Language Translation Layer](../../api2/features/language-translation-layer.md) — this feature only
+**registers a new translatable field** into it:
+
+1. **Sidecar table.** `Client.AssortmentTranslations` holds non-English overlays for assortment names.
+   English remains in `Assortments.name`; a null/absent sidecar row falls back to English.
+2. **Model.** `_Model_Client_AssortmentTranslation` is the ORM model for the sidecar.
+3. **Core record registration.** `Core.Records` registers route `assortment-translations` →
+   model `\_Model_Client_AssortmentTranslation` (record id **332**, `aclDatabase = 'CLIENT'`), with
+   `Core.RecordFields` rows for `id`, `uuid`, `assortmentId`, `languageId`, and `name`.
+4. **The field link (what makes it translate automatically).** The translatable `Assortments.name`
+   RecordField gets its `Core.RecordFields.translationRecordFieldId` set to the sidecar's `name`
+   RecordField. The api2 V2 layer reads `translationRecordFieldId` for every field and automatically
+   returns the sidecar value for the caller's resolved language (falling back to English when absent) —
+   so assortment names now translate **without any api2 code change**.
+5. **ACL.** A full ACL chain grants the **Base** role read/write on the new record. Because the
+   record's `aclDatabase = 'CLIENT'`, the grant lives in each client DB — see
+   [ACL Permission Chain](./acl-permission-chain.md).
+
+## Data model
+
+- `Client.AssortmentTranslations` — `id, uuid, dtCreated, dtUpdated, assortmentId (FK Assortments),
+  languageId (FK Languages), name`; `UNIQUE(assortmentId, languageId)`. English stays in `Assortments`;
+  sidecar holds only non-English overlays (null → English fallback).
+- `Core.Records` **332** = `assortment-translations` (`aclDatabase = 'CLIENT'`); `Core.RecordFields`
+  for id/uuid/assortmentId/languageId/name.
+- `Assortments.name` RecordField → `translationRecordFieldId` points at the sidecar `name` RecordField.
+
+## Client variations
+
+- **Compass Canada** seeds fr-CA assortment names (16 rows) into `AssortmentTranslations`. The French
+  text was extracted from the existing bilingual `Assortments.name` values (stored as `"English/French"`),
+  and a companion migration cleans `Assortments.name` back to English-only so the base value is pure
+  English and the French overlay lives only in the sidecar. See the Compass Canada profile.
+
+## Change history
+
+- 2026-06-26 — Initial build: `AssortmentTranslations` sidecar table + `_Model_Client_AssortmentTranslation`
+  model + `Core.Records` 332 registration + `translationRecordFieldId` link on `Assortments.name` + Base-role
+  ACL chain. Reuses the existing metadata-driven translation layer, so no api2 code change was needed.
+  Compass Canada French (fr-CA) assortment names seeded, with `Assortments.name` cleaned to English-only. (bala)
+
+## Related docs
+
+- [Language Translation Layer](../../api2/features/language-translation-layer.md)
+- [ACL Permission Chain](./acl-permission-chain.md)

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 16 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 17 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 17 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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

@@ -44,5 +44,9 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
 ## Notes
 - Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
   facing emails are sent in EN or FR accordingly.
+- Assortment (product-grouping) names are served in fr-CA via the `AssortmentTranslations` sidecar
+  (16 rows seeded). French was extracted from the old bilingual `"English/French"` `Assortments.name`
+  values, which were then cleaned to English-only. See
+  [Assortment Name Translation](../../2.0/apps/_underscore/features/assortment-name-translation.md).
 - The 2026-06-08 ASN → ItemFulfillment work was for **Compass USA**, not Compass Canada.
 - Related: [Compass USA](../compass-usa/profile.md).

package/package.json

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