toga-ai 1.0.332 → 1.0.334

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/INDEX.md

@@ -9,6 +9,7 @@
 | [ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming](features/clickup-github-autolink.md) | How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch / PR-title naming convention that triggers it. |  |
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [ClickUp Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |
+| [ClickUp Subtask Activity → Parent Opportunity/Epic Comments](features/clickup-subtask-activity.md) | Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity** or **Epic** it rolls up to, so a deal/project owner sees activity whe | worker2/Worker/Clickup/Subtask.php, worker2/Worker/Clickup.php, dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql |
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |

package/knowledge/2.0/apps/worker2/features/clickup-project-routing.md

@@ -15,6 +15,7 @@ related:
   - ../architecture.md
   - ./creating-worker-actions.md
   - ./clickup-connectivity-watchdog.md
+  - ./clickup-subtask-activity.md
 ---
 
 ## Summary
@@ -78,8 +79,11 @@ ids are discovered. Configure via the `DiscoverTaskTypes()` / `DiscoverIds()` ac
 2. Each handler fetches task details via `_Worker_Clickup::getTaskDetails()` (a per-invocation
    `static` cache shared across all handlers in one job), then guards on **space id** and
    **top-level** (`parent` empty). The three routing handlers identify Epics/tasks
-   **structurally** (space + top-level). Custom **Task Types are now configured**, and the
-   newer `enforceHubPlacement` guard keys on `custom_item_id` to recognize Epics/Opportunities.
+   **structurally** (space + top-level). The `enforceHubPlacement` guard was written to key on
+   `custom_item_id`, but the Task-Types ClickApp is **not reliably enabled** on the hub spaces
+   and `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID` remain `null` — so that guard is
+   effectively **inert** in practice; structural (space + top-level) identification is what
+   actually runs (see Gotchas, and `./clickup-subtask-activity.md`).
 3. Custom fields are read by name via `extractCustomFields()` (one pass, last-non-null-wins,
    trimmed) → mapped to a target list id → reconciled by `applyMultiListPlacement()`:
    POST the target if absent, DELETE every other in-scope list (DELETE failures are caught
@@ -160,6 +164,7 @@ Read-only / setup actions, invoked via `curl -X POST https://worker.togahub.com/
 `RESULT: PASS`), `RegisterOpportunityWebhook` and `RegisterHubGuardWebhooks` (one-time setup).
 
 ## Change history
+- 2026-07-14 — Correction: `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID` are still `null` and the Task-Types ClickApp is not reliably enabled on the hub spaces, so `enforceHubPlacement`'s custom-Task-Type keying is inert; structural (space + top-level) identification is what actually runs. Cross-linked the new subtask-activity feature (same hub spaces/pipeline). (ajean)
 - 2026-06-23 — Added the hub-placement guard (`enforceHubPlacement` on `taskCreated`/`taskMoved`): re-anchors misplaced Epics/Opportunities to their hub by custom Task Type + home space, backfills Business Unit/Project Category, and notifies. Added `DiscoverTaskTypes`, `RegisterHubGuardWebhooks`, `TestHubGuardMappings`. Corrected the earlier "Task Types not enabled" note. (ajean)
 - 2026-06-09 — Documented ClickUp secondary multi-list routing (hybrid native-automation + worker design, three space handlers, self-trigger guard). (jcardinal)
 

package/knowledge/2.0/apps/worker2/features/clickup-subtask-activity.md

@@ -0,0 +1,117 @@
+---
+title: ClickUp Subtask Activity → Parent Opportunity/Epic Comments
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: draft
+updated: 2026-07-14
+owners: [ajean]
+files:
+  - worker2/Worker/Clickup/Subtask.php
+  - worker2/Worker/Clickup.php
+  - dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql
+related:
+  - ./clickup-project-routing.md
+  - ../architecture.md
+---
+
+## Summary
+
+Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity**
+or **Epic** it rolls up to, so a deal/project owner sees activity where they actually look.
+On a `clickup` webhook for a subtask (a task with a non-empty `parent`) of event
+`taskStatusUpdated` or `taskCommentPosted`, the worker walks the parent chain to the
+top-level ancestor and, if that ancestor is an Opportunity (Opportunity/RFP Hub space
+`90113928591`) or an Epic (Project Hub space `90113939341`), posts **one** comment on the
+ancestor. Implemented in `_Worker_Clickup_Subtask` (extends `_Worker_Clickup`), fanned out
+from a pre-switch block in `_Worker_Clickup::Webhook()`.
+
+> **Status: not yet deployed / not live-verified.** PRs open: worker2 #110, dbchanges2 #427.
+> The dbchanges2 migration must run **before or with** the worker deploy (the worker reserves
+> a ledger row before every post).
+
+## Key files / entry points
+
+- `worker2/Worker/Clickup/Subtask.php` — `_Worker_Clickup_Subtask` (NEW), all subtask
+  fan-out / ancestor-walk / dedup / post logic.
+- `worker2/Worker/Clickup.php` — a **pre-switch fan-out block** in `_Worker_Clickup::Webhook()`
+  detects a subtask event and dispatches `_Worker::runTask('Clickup/Subtask/Process',
+  ['taskId', 'event', 'data' => history_items])`. The block is wrapped in a best-effort
+  `try/catch (Throwable)` and **deliberately does not `return`** — it falls through to the
+  existing `taskStatusUpdated` / `taskCommentPosted` switch, so sprint / work-type handling is
+  unaffected.
+- `dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql` (NEW) — creates the
+  `ClickUpSubtaskActivity` dedup ledger table in the **Team** DB.
+
+## How it works
+
+1. Webhook arrives → `_Worker_Clickup::Webhook()`. The pre-switch block short-circuits **early
+   on the subtask's own space** before any parent walk (a subtask lives in the same space as its
+   ancestor, so a non-hub space is discarded before spending API calls).
+2. `Clickup/Subtask/Process` walks up the `parent` chain to the top-level (no-parent) ancestor
+   and confirms it is an Opportunity or Epic **structurally** — by home space id + top-level —
+   mirroring `handleEpicUpdate` / `handleOpportunityUpdate`. **Not** by custom Task Type: the
+   Task-Types ClickApp is not reliably enabled on the hub spaces (see Gotchas).
+3. Triggers:
+   - **Status** — post when the subtask status moves into `in progress`, `roadblocked`, or
+     `on hold` (matched by **lowercase status name**, consistent with existing status
+     comparisons in `Worker/Clickup.php`), OR into any completed status (matched by **status
+     TYPE** in `done`/`closed` via the inherited `COMPLETE_STATUS_TYPES`).
+   - **Comment** — any user comment posted on the subtask is mirrored to the ancestor as
+     `"💬 <author> commented on subtask …"`.
+4. Every post carries a trailing `(automated)` marker. Comments that already carry that marker
+   are **never** mirrored (loop guard).
+5. Posts use `_Component_Api_Clickup::send('POST', '/task/{id}/comment',
+   ['comment_text' => …, 'notify_all' => false])`; task lookups reuse
+   `_Worker_Clickup::getTaskDetails()` (in-process static cache);
+   `_Worker_Clickup_Project::RATE_LIMIT_DELAY_US` paces the parent walk.
+
+### Dedup ledger (the authoritative guard)
+
+Before posting, the worker **reserves a ledger row** (`INSERT` into `ClickUpSubtaskActivity`)
+so the `UNIQUE(subtaskId, activityKey)` constraint — not a check-then-act window — is the
+authoritative dedup guard against re-delivered webhooks. If the comment POST fails, the row is
+**released** (`DELETE`) so a retry can re-attempt. The `activityKey` is:
+- `status:<name>` for a watched named status,
+- `status:completed` for a completion,
+- `comment:<clickupCommentId>` for a mirrored comment — falling back to the history-item id,
+  then a per-event date, then `md5(text)`, so identical comment texts stay distinct.
+
+Ledger access follows the `ClickUpHealthState` pattern from `_Worker_Clickup_Health`: raw
+`_Query` on `_underscore::DB_TEAM` with `_Database::escape()`.
+
+## Data model
+
+`ClickUpSubtaskActivity` in the **Team** DB (dbchanges2 migration `2026-07-14a`):
+`id`, `uuid`, `subtaskId VARCHAR(32)`, `activityKey VARCHAR(255)`, `dtPosted`, with
+`UNIQUE(subtaskId, activityKey)`. All other state lives in ClickUp.
+
+## Client variations
+
+None — internal automation for Agilant's ClickUp workspace, uniform across clients.
+
+## Gotchas / known issues
+
+- **Ancestor identification is STRUCTURAL, not by Task Type.** The Task-Types ClickApp is not
+  reliably enabled on the hub spaces, and `_Worker_Clickup_Project`'s `TASK_TYPE_EPIC_ID` /
+  `TASK_TYPE_OPPORTUNITY_ID` remain `null` (inert). Identify Opportunities/Epics by home space
+  id + top-level, exactly like the routing handlers — do not rely on `custom_item_id` here.
+- **Completion matches by status TYPE (`done`/`closed`), not name** — it survives label
+  changes. The other watched statuses match by lowercase **name** (`in progress`,
+  `roadblocked`, `on hold`).
+- **Loop guard is the `(automated)` marker** — every automated post carries it, and any comment
+  carrying it is skipped on mirror. Removing/altering the marker text re-opens the mirror loop.
+- **Fan-out never returns** — it falls through to the existing switch on purpose; keep it that
+  way or existing sprint/work-type handling breaks.
+- **Migration ordering** — deploy the dbchanges2 `2026-07-14a` migration before/with the worker;
+  the worker reserves a ledger row on every post and will error without the table.
+
+## Change history
+- 2026-07-14 — Created (draft, not yet deployed): subtask status/completion/comment mirroring to the parent Opportunity/Epic via `_Worker_Clickup_Subtask`, guarded by the `ClickUpSubtaskActivity` UNIQUE-key dedup ledger. PRs worker2 #110 / dbchanges2 #427. (ajean)
+
+## Related docs
+
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md) — same hub spaces, same webhook pipeline, same structural identification.
+- [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS worker contract.

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

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 31 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 28 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 29 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 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)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/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.332",
+  "version": "1.0.334",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",