toga-ai 1.0.331 → 1.0.333

package/knowledge/2.0/apps/ai-bdr/INDEX.md

@@ -3,8 +3,9 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [AI-BDR Architecture](architecture.md) | **AI-BDR** is TOGA's outbound AI sales-development representative. | ai-bdr/README.md, ai-bdr/requirements.txt, ai-bdr/.env.example, ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/vapi/templates/assistant.template.json, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py |
-| [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Status:** Draft 2 (needs one more review). | bdr/PLAN.md, bdr/mockup/app.jsx, bdr/mockup/screens.jsx, bdr/mockup/components.jsx |
+| [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Execution status (2026-07-14):** PLAN **Phases 0–5 are BUILT and QA'd** — the web > app engine, full mockup port, and real backend are done. | bdr/PLAN.md, bdr/mockup/app.jsx, bdr/mockup/screens.jsx, bdr/mockup/components.jsx |
 | [Call Orchestration — PHP Worker ↔ Vapi (the integration seam)](features/call-orchestration.md) | The **PHP worker** is the orchestrator; **Vapi** is the actor. | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/scripts/update_structured_output.py |
 | [Vapi Integration — Assistants, Tools, Structured Output](features/vapi-integration.md) | Everything inside Vapi: the three assistants, the three shared tools, the shared structured-output schema, the Liquid-templated system prompt, and the Python sc | ai-bdr/vapi/templates/assistant.template.json, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md |
-| [Web Funnel — Next.js UI + Config-Driven Campaign Content](features/web-funnel-content-model.md) | The **public-facing web funnel** is the new UI / lead-capture front door of the **same AI-BDR product** documented in `../architecture.md` — it is the front doo | bdr/src/content/schema.ts, bdr/src/content/hubspotProvider.ts, bdr/src/content/useCampaign.ts, bdr/src/content/default.ts, bdr/src/server/leadSink.ts, bdr/src/server/callbackService.ts, bdr/src/app/api/call-now/route.ts, bdr/src/app/api/call-later/route.ts |
+| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/lib/resolveCampaignId.ts, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/app/api, bdr/test, bdr/public, bdr/mockup/styles.css |
+| [Web Funnel — Next.js UI + Config-Driven Campaign Content](features/web-funnel-content-model.md) | > **Status note:** the content **contract** below (schema, provider seam, adapters) > is now BUILT and QA'd (PLAN Phases 0–5). | bdr/src/content/schema.ts, bdr/src/content/hubspotProvider.ts, bdr/src/content/useCampaign.ts, bdr/src/content/default.ts, bdr/src/lib/resolveCampaignId.ts, bdr/src/server/leadSink.ts, bdr/src/server/callbackService.ts, bdr/src/app/api/call-now/route.ts, bdr/src/app/api/call-later/route.ts, bdr/src/app/api/contact/route.ts |
 | [New-Campaign Onboarding (6-phase runbook)](workflows/new-campaign-onboarding.md) | The end-to-end procedure for launching a new outbound BDR campaign (industry, offer, target persona, geography). | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/calcom-new-campaign-event-guide.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py |

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

@@ -5,7 +5,7 @@
 | [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/ |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/_.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
-| [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
+| [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |

package/knowledge/2.0/apps/api2/features/language-translation-layer.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-14
 owners: ["jcardinal", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,10 +15,16 @@ files:
   - _underscore/Model/Core/RecordField.php
   - _underscore/Model/Core/DefaultGlobalSetting.php
   - _underscore/Model/Client/ItemTranslation.php
+  - _underscore/Model/Client/FeatureTranslation.php
+  - _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php
+  - _underscore/Model/Client/ItemFeatureTranslation.php
   - dbchanges2/Client/2026-06-23a - ItemTranslations.sql
   - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
+  - dbchanges2/Client/2026-07-13a - FeatureTranslations.sql
+  - dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql
   - dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql
   - dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql
+  - dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql
 related:
   - ./acl-permission-chain.md
   - ../../_underscore/features/model-magic-field-access.md
@@ -26,8 +32,9 @@ related:
 
 ## Summary
 
-Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple
-languages without forking the schema or breaking English consumers. English stays in the source
+Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text —
+`Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures.value`/`presentationValue`) in
+multiple languages without forking the schema or breaking English consumers. English stays in the source
 table; per-language overlays live in per-table **sidecar** tables (`ItemTranslations` first).
 The caller's language is resolved once at authentication, surfaced on every response's
 `audience.language`, and embedded in the JWT; reads/writes are redirected to the sidecar in the
@@ -126,8 +133,19 @@ endpoint for those.
 - `Core.RecordFields.translationRecordFieldId` — new nullable self-FK (after `recordId`).
 - `Core.Records` 331 = `item-translations` (`aclDatabase='CLIENT'`); `Core.RecordFields` 2233–2239
   (its fields), 2240 (the self-describing `translationRecordFieldId` field).
-- `item-translations` ACL chain lives in each client DB targeting the Base role — see
-  [acl-permission-chain.md](./acl-permission-chain.md).
+- **Feature-text sidecars** (same pattern as `ItemTranslations`, ship via `dbchanges2/Client/`):
+  - `Client.FeatureTranslations` — overlay for `Features.name`; `id, uuid, dtCreated, dtUpdated,
+    featureId (FK), languageId (FK), name`; `UNIQUE(featureId, languageId)`.
+  - `Client.ItemCategoryFeatureGroupTranslations` — overlay for `ItemCategoryFeatureGroups.name`;
+    `…, itemCategoryFeatureGroupId (FK), languageId, name`; `UNIQUE(fk, languageId)`.
+  - `Client.ItemFeatureTranslations` — overlay for `ItemFeatures.value` + `presentationValue`;
+    `…, itemFeatureId (FK), languageId, value, presentationValue`; `UNIQUE(fk, languageId)`.
+  - `Core.Records` 343 / 344 / 345 = the three above; `Core.RecordFields` 2442–2457. The
+    `translationRecordFieldId` column on the source fields (`features.name`,
+    `item-category-feature-groups.name`, `item-features.value`/`presentationValue`) is set by an
+    `UPDATE…JOIN` so `getTranslatedFieldValue()`/`shouldTranslate()` substitute the sidecar value on read.
+- `item-translations` (and the feature sidecars') ACL chain lives in each client DB targeting the
+  Base role — see [acl-permission-chain.md](./acl-permission-chain.md).
 
 ## Client variations
 
@@ -157,6 +175,22 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   `$this->response->status` to `200` **before** finalization. An `is_null` guard there suppresses the
   `201` + tokens and yields a broken `200`/`data:null` login. Branch on the explicit
   `$invalidLanguageSetting` flag instead.
+- **The all-fields (expand-everything) serializer branch must also translate.** `V2.php` has two
+  nested-child serialization paths: when the caller requests **specific** fields it already ran each
+  value through `getTranslatedFieldValue()`, but when the caller requested **no** specific fields
+  (empty `$varOptions`, i.e. "return everything I have access to") the code copied raw child values
+  straight into `$outData` and never translated — so any field returned via the all-fields expansion
+  stayed in base English even for a non-base-language user. Both branches must route through
+  `getTranslatedFieldValue($record, $field, $sourceModel, $defaultValue)` (preserving the
+  `renamedFields` alias). Symptom that found it: on the Compass Canada French storefront item-detail
+  page (loaded via `/bundles`), feature-spec **values** were French but the feature-group **headers**
+  (`itemCategoryFeatureGroup.name`, e.g. "Processeur"/"Mémoire") stayed English, because the group
+  object serialized through the all-fields branch. **Not a query-depth problem** — a commerce-side
+  `depth:6` theory was wrong and reverted; the fix returns French headers at the default `meta.depth 3`.
+- **Sidecar/source collation mismatch.** The translation sidecar tables use `utf8mb4_unicode_ci`
+  (matching `ItemTranslations`) while the source fields are `utf8mb4_0900_ai_ci`. Ad-hoc queries that
+  compare a sidecar string against a source string must add `COLLATE utf8mb4_bin` or MySQL throws a
+  collation-mismatch error.
 - Reading a possibly-absent magic field off a generic `_Model` needs `array_key_exists(...)` +
   `__get` — `isset()`/`?? null` always read false/null. See
   [_Model magic-field access](../../_underscore/features/model-magic-field-access.md); this was the
@@ -168,6 +202,14 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 
 ## Change history
 
+- 2026-07-13 — Extended the translation layer to item **feature** text: three new sidecar tables
+  (`FeatureTranslations`, `ItemCategoryFeatureGroupTranslations`, `ItemFeatureTranslations`; Records
+  343/344/345, RecordFields 2442–2457) with `translationRecordFieldId` wired to the source fields,
+  so feature names, group headers, and feature values translate on read exactly like Item text. Fixed
+  the all-fields (expand-everything) nested-child serializer branch in `V2.php` (~L5958) to route
+  through `getTranslatedFieldValue()` — previously it copied raw base-English child values (Compass
+  Canada French group headers stayed English while values were French); the `depth:6` theory was wrong
+  and reverted. Noted the sidecar/source collation-mismatch gotcha. (bala)
 - 2026-06-23 — Initial build: audience.language + JWT embedding, ItemTranslations sidecar + metadata +
   full ACL chain, and translation-aware read/write at the API layer. Also fixed a latent autoload bug
   by renaming `DefaultFlobalSetting.php` → `DefaultGlobalSetting.php`. (jcardinal)

package/knowledge/2.0/apps/worker2/features/etilize-item-translation-import.md

@@ -6,13 +6,15 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
+updated: 2026-07-14
 owners: [bala]
 files:
   - worker2/Worker/Etilize/ItemTranslations.php
 related:
   - ./creating-worker-actions.md
   - ./etilize-catalog-item-import.md
+  - ../../api2/features/language-translation-layer.md
+  - ../../../clients/compass-canada/features/french-item-feature-translations.md
 ---
 
 ## Summary
@@ -35,6 +37,28 @@ Routes are `Etilize/ItemTranslations/<Method>` (see
    — translates **all** items that have a `c_etilizeProductId`.
 2. `ImportItemsLanguageByPartNumbers(string $client, string $languageCode, array $partNumbers, ?string $languageName = null, ?string $catalog = null)`
    — translates only the given part numbers (uses a `partNumber IN (...)` filter).
+3. `BackfillEtilizeAttributeIds(...)` — populates `c_etilizeAttributeId` (on `Features`) and
+   `c_etilizeAttributeGroupId` (on `ItemCategoryFeatureGroups`) from Etilize `en_us`, so features and
+   groups can be matched to their Etilize attribute id. Must run **before** feature-translation import
+   so each French value lands on the right feature/group.
+
+## Feature-text translation (item features, not just Item title/desc)
+
+Beyond `ItemTranslations` (Item title/description/longDescription), `importItemLanguage` now also
+writes **feature** translations via `importItemFeatureTranslations` → `translateAttributeGroup` /
+`translateAttribute`, into the `FeatureTranslations`, `ItemCategoryFeatureGroupTranslations`, and
+`ItemFeatureTranslations` sidecar tables (see the shared
+[Language Translation Layer](../../api2/features/language-translation-layer.md) for the read-side
+metadata wiring). Matching is by Etilize **attribute id** (`c_etilizeAttributeId`) and **attribute
+group id** (`c_etilizeAttributeGroupId`), which is why the backfill action above must run first.
+
+- **Group translation is scoped per-item, not catalog-wide.** `findGroupIdsForItemByEtilizeAttributeGroupId`
+  joins through the item's own `ItemFeatures → ItemCategoryFeatures → groups` so only the groups that
+  item actually uses are translated. Doing it catalog-wide would write thousands of unrelated group rows.
+- Constants: `ETILIZE_LOCALE_ENGLISH = 'en_us'`, `ETILIZE_GENERAL_ATTRIBUTE_GROUP_ID = '35'`,
+  `FEATURE_VALUE_MAX_LENGTH = 254`.
+- `RefreshItemsFromEtilize` is idempotent — it reuses existing features/groups by name (and by
+  item+feature), so re-running does not duplicate.
 
 ## How it works
 
@@ -61,8 +85,21 @@ Items **not published in the requested locale are skipped**.
 - Only items with a `c_etilizeProductId` are translatable — items without an Etilize id
   are silently skipped.
 - English is intentionally never written here; it lives in the `Items` table.
+- **Use `_Query::getAffectedRows()`, not `rowsAffected()`.** There is no `rowsAffected()` method
+  (the CLAUDE.md doc was wrong); calling it throws "Call to undefined method".
+- **OOM on a full (~200-item) run.** `_Database` caches every SELECT in `$_queryCache`, so a large
+  batch grows unbounded. Call `_Database::useQueryCache(false)` and `gc_collect_cycles()` **per item**
+  inside the batch loops.
+- **`clampFeatureValue` must use `mb_strlen` / `mb_substr` with `'UTF-8'`**, never byte-based
+  `strlen`/`substr`, or a French accent gets cut mid-character (`FEATURE_VALUE_MAX_LENGTH = 254`).
 
 ## Change history
+- 2026-07-13 — Added `BackfillEtilizeAttributeIds` action and extended `importItemLanguage` to import
+  item **feature** translations (`importItemFeatureTranslations` → `translateAttributeGroup` /
+  `translateAttribute`) into the Feature/group/item-feature sidecar tables; groups scoped per-item via
+  `findGroupIdsForItemByEtilizeAttributeGroupId` to avoid catalog-wide writes. Durable gotchas:
+  `getAffectedRows()` (no `rowsAffected()`); disable `_Database` query cache + `gc_collect_cycles()`
+  per item to avoid OOM on full runs; `mb_`-based value clamp for accents. (bala)
 - 2026-06-26 — Documented `_Worker_Etilize_ItemTranslations`: per-language Etilize
   `getProduct` import into `ItemTranslations` (title=desc type 2, longDescription=type 1),
   locale derived from language code, COALESCE upsert that never overwrites with blanks,

package/knowledge/INDEX.md

@@ -27,7 +27,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **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) — 6 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
+- **ai-bdr** (AI-BDR) — 7 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 9 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 8 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)

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

@@ -2,5 +2,6 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [French (fr-CA) Item Feature Translations (Compass Canada)](features/french-item-feature-translations.md) | 2.0 | Renders item **feature** text on the Compass Canada French storefront — feature names, feature-group headers (e.g. | _underscore/Model/Compass/Canada/Feature.php, _underscore/Model/Compass/Canada/ItemCategoryFeatureGroup.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, worker2/Worker/Etilize/ItemTranslations.php, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql, dbchanges2/Client_CompassCanada/2026-07-13 - FeatureAttributeCustomFields.sql, dbchanges2/Client_CompassCanada/2026-07-13 - DedupeItemFeaturesAndGroups.sql, dbchanges2/Client_CompassCanada/2026-07-13 - SeedFrenchFeatureTranslations.sql |
 | [Grand & Toy ASN Import (Compass Canada)](features/grand-and-toy-asn-import.md) | 2.0 | Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. | worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/Canada/AdvanceShippingNotice.php, dbchanges2/Client_CompassCanada/ |
 | [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |  |

package/knowledge/clients/compass-canada/features/french-item-feature-translations.md

@@ -0,0 +1,96 @@
+---
+title: French (fr-CA) Item Feature Translations (Compass Canada)
+framework: "2.0"
+project: _Underscore
+client: compass-canada
+type: client-feature
+status: active
+updated: 2026-07-14
+owners: ["bala"]
+files:
+  - _underscore/Model/Compass/Canada/Feature.php
+  - _underscore/Model/Compass/Canada/ItemCategoryFeatureGroup.php
+  - _underscore/Model/Client/FeatureTranslation.php
+  - _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php
+  - _underscore/Model/Client/ItemFeatureTranslation.php
+  - worker2/Worker/Etilize/ItemTranslations.php
+  - dbchanges2/Client/2026-07-13a - FeatureTranslations.sql
+  - dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql
+  - dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql
+  - dbchanges2/Client_CompassCanada/2026-07-13 - FeatureAttributeCustomFields.sql
+  - dbchanges2/Client_CompassCanada/2026-07-13 - DedupeItemFeaturesAndGroups.sql
+  - dbchanges2/Client_CompassCanada/2026-07-13 - SeedFrenchFeatureTranslations.sql
+related:
+  - ../profile.md
+  - ../../../2.0/apps/api2/features/language-translation-layer.md
+  - ../../../2.0/apps/worker2/features/etilize-item-translation-import.md
+---
+
+## Summary
+Renders item **feature** text on the Compass Canada French storefront — feature names, feature-group
+headers (e.g. "Processeur", "Mémoire", "Chipset"), and feature values — in fr-CA. It layers the shared
+metadata-driven sidecar translation infrastructure ([Language Translation Layer](../../../2.0/apps/api2/features/language-translation-layer.md))
+on top of a French **import** from Etilize ([Etilize Item Translation Import](../../../2.0/apps/worker2/features/etilize-item-translation-import.md)),
+matched to the right feature/group by Etilize **attribute id**. fr-CA is `languageId 2`.
+
+This replaces the old approach where the `worker/crons/toga2/compasscanada/Imports2.0/Import_items.php`
+cron wrote French straight into the **base** fields and minted new group UUIDs every run — corrupting
+English and producing thousands of duplicate features/groups.
+
+## Compass-Canada-specific pieces
+- **Custom match fields** (Compass Canada only, shipped via `dbchanges2/Client_CompassCanada/`, models
+  under `_underscore/Model/Compass/Canada/`):
+  - `c_etilizeAttributeId` on `Feature` (`Model/Compass/Canada/Feature.php`)
+  - `c_etilizeAttributeGroupId` on `ItemCategoryFeatureGroup` (`Model/Compass/Canada/ItemCategoryFeatureGroup.php`)
+  These let the importer match an English feature/group to its Etilize attribute id so the correct
+  French value lands on the right feature. Populate them first with the worker2
+  `BackfillEtilizeAttributeIds` action.
+- **fr-CA = `languageId 2`** (see also profile: `UserGlobalSettings.settingId = 2`, `en` / `fr-CA`).
+- The shared sidecar tables (`FeatureTranslations`, `ItemCategoryFeatureGroupTranslations`,
+  `ItemFeatureTranslations`) and Core Records 343/344/345 + RecordFields 2442–2457 are documented in the
+  shared layer doc; only the custom fields and the seed/dedup data are Compass-Canada-specific.
+
+## Rollout order (dev/beta done, prod pending)
+1. Deploy the translation schema (sidecars + ACL + Core RecordFields) with the correct **env-specific**
+   Core Record/RecordField ids.
+2. **Dedup** existing features/groups (see below).
+3. `BackfillEtilizeAttributeIds` — populate the custom match fields from Etilize `en_us`.
+4. Import French translations (worker2 Etilize feature-translation import).
+5. Seed any remaining French feature translations.
+6. **Retire** the old `worker/crons/toga2/compasscanada/Imports2.0/Import_items.php` cron.
+
+Prod rollout is deferred until explicitly requested; the dev/beta build (beta DB) is complete.
+
+## Dedup of duplicate features/groups
+- **Root cause:** the old `Import_items.php` cron did unconditional POSTs and minted new group UUIDs on
+  every run → ~7700 duplicate features and ~2100 duplicate groups on dev; prod counts ~12665→4932
+  features and ~2390→263 groups.
+- **Migration technique (team practice):** the dedup migration must **not** use `CREATE TEMPORARY
+  TABLE` — use inline **derived-table subqueries**. MySQL 8 materializes them and avoids error 1093
+  (can't reopen the table being updated).
+- **Keep-which-row differs by env:** the **dev** variant prefers the already-translated duplicate —
+  `COALESCE(MIN(CASE WHEN translated THEN id END), MIN(id))`; the **prod** variant keeps the **lowest
+  id**.
+
+## Gotchas / known issues
+- **Sidecar/source collation mismatch.** Sidecar tables are `utf8mb4_unicode_ci` (matching
+  `ItemTranslations`); the source fields are `utf8mb4_0900_ai_ci`. Any ad-hoc query comparing across the
+  two needs `COLLATE utf8mb4_bin` or MySQL throws a collation-mismatch error.
+- **Etilize attribute ids of the form `34xxxxxx` are NOT corrupted** (false alarm resolved). A manual
+  XML showing `32xxxxxx` came from a different Etilize view; the worker's Etilize endpoint returns
+  `34xxxxxx` consistently for both backfill and import, so translations match. Do not "fix" them.
+- **A shared `c_etilizeProductId` across two part numbers can be a data error.** On dev, partNumber
+  `BT6L3UC#ABA` had the wrong shared `c_etilizeProductId 1083084905` (shared with `B4TM0UC#ABA`); prod's
+  correct value is `1086408433`. Fixed by a single `UPDATE` — this was a data error, not a code bug.
+
+## Change history
+- 2026-07-13 — Built the fr-CA item-feature translation path end-to-end on dev/beta: shared feature
+  sidecar tables + Core wiring, Compass-only `c_etilizeAttributeId` / `c_etilizeAttributeGroupId` custom
+  fields, worker2 backfill + feature-translation import, dedup of ~7700 dup features / ~2100 dup groups,
+  French seed. Corrected the `34xxxxxx` attribute-id false alarm and fixed the `BT6L3UC#ABA` shared
+  `c_etilizeProductId` data error. Prod rollout + retiring the old `Import_items.php` cron deferred. (bala)
+
+## Related docs
+- [Compass Canada profile](../profile.md)
+- [Language Translation Layer](../../../2.0/apps/api2/features/language-translation-layer.md)
+- [Etilize Item Translation Import](../../../2.0/apps/worker2/features/etilize-item-translation-import.md)

package/package.json

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