toga-ai 1.0.467 → 1.0.469

package/knowledge/1.0/apps/library/INDEX.md

@@ -9,7 +9,7 @@
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
-| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
+| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |

package/knowledge/1.0/apps/library/features/netsuite-item-isfulfillable-sync.md

@@ -6,15 +6,17 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-28
 owners: [bala]
 files:
   - library/app/netsuite.php
   - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php
 related:
   - toga2-api-client-and-bridge.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../worker/workflows/isfulfillable-multi-client-backfill.md
   - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
 ---
 
@@ -26,24 +28,43 @@ item** in the 2.0 platform. The client-facing copy is reached separately by the
 which walks the supply chain up from the source item. Only the source item is stamped here.
 
 ## Key files / entry points
-- `library/app/netsuite.php` — `App_NetSuite::getItemIsFulfillable($itemInternalId): bool|null`.
-  A SOAP `ItemSearchBasic` by internal id; returns the boolean (or `null` when unknown). Mirrors
-  the existing `getItemIsSerialized` exactly — the only prior item flag the sync read.
-- `library/app/api/toga2.php` — `getCreateItem` (~line 4364). During item create/update the sync
-  now reads `$isFulfillableItem = App_NetSuite::getItemIsFulfillable($nsItemInternalId)` and, when
-  **non-null**, stamps `$payload['isFulfillable']` on the create/update PUT|POST to api2. The
-  NetSuite internal id is resolved from the order line or from the part number
-  (`getItemInternalIdFromPartNumber` / `getItemGroupInternalIdFromPartNumber`). Stores
-  `c_netsuiteInternalItemId` on the item.
-- `worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php` — one-time backfill (see below).
+- `library/app/netsuite.php`
+  - `App_NetSuite::getItemIsFulfillable($itemInternalId): bool|null` — a SOAP `ItemSearchBasic` by
+    internal id; returns the boolean (or `null` when unknown). Mirrors `getItemIsSerialized`.
+  - `App_NetSuite::getItemSerializedAndFulfillable($itemInternalId)` — **combined lookup** returning
+    **both** flags from **one** `ItemSearchBasic` (serialized via `instanceof SerializedInventoryItem`,
+    fulfillable via the record's `isFulfillable`). `getCreateItem` now calls this once instead of the
+    two separate SOAP searches (`getItemIsSerialized` + `getItemIsFulfillable`) — halves the per-line
+    NetSuite round-trips now that the sync reads fulfillability for every line (see refresh below).
+- `library/app/api/toga2.php` — three item-creation paths now stamp `isFulfillable`:
+  - `getCreateItem` (~line 4364) — reads both flags via `getItemSerializedAndFulfillable` and, when
+    fulfillable is **non-null**, stamps `$payload['isFulfillable']` on the create/update PUT|POST. It
+    now also **refreshes the flag on EXISTING items** when NetSuite's value differs from the stored
+    value (not only on create), mirroring how the serialized flag works. Because the PUT is
+    diff-only, a re-sync with an unchanged value is a no-op. NetSuite internal id is resolved from the
+    order line or part number (`getItemInternalIdFromPartNumber` / `getItemGroupInternalIdFromPartNumber`);
+    stores `c_netsuiteInternalItemId`.
+  - `syncItemFulfillmentFromNetsuite` (~line 3562) and `syncInventoryAdjustmentFromNetsuite`
+    (~line 3882) — the two **other** direct `/items` creation paths now also stamp `isFulfillable` on
+    create. Previously only `getCreateItem` did, so items first created via these flows stayed **NULL**.
+- `worker/crons/toga2/netsuite/common_sync_togasupply.php` — `isFulfillable` was added to the bulk
+  `/items` GET field list so the existing-item refresh has the stored value to compare NetSuite's
+  against (without it, the refresh has nothing to diff).
+- `worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php` — one-time Compass backfill (see below).
+  The later **multi-client** catch-up lives in its own worker workflow doc
+  ([isFulfillable multi-client backfill](../../worker/workflows/isfulfillable-multi-client-backfill.md)).
 
 ## How it works
 1. Item sync resolves the NetSuite internal id for the item (order line, else part-number lookup).
-2. `getItemIsFulfillable` SOAP-searches the item and returns the flag.
-3. If non-null, `getCreateItem` adds `isFulfillable` to the item PUT/POST payload to api2. api2's
-   Items interceptor then propagates it up-chain (Phase 2).
-4. Going forward the **daily sync** handles new items automatically; existing items are caught up
-   by the one-time backfill.
+2. `getItemSerializedAndFulfillable` SOAP-searches the item **once** and returns both the serialized
+   and fulfillable flags.
+3. If fulfillable is non-null, `getCreateItem` adds `isFulfillable` to the item PUT/POST payload to
+   api2 — on **create**, and on **update** whenever the stored value differs from NetSuite's (the
+   existing-item refresh). api2's Items interceptor then propagates it up-chain (Phase 2). The two
+   other creation paths (`syncItemFulfillmentFromNetsuite`, `syncInventoryAdjustmentFromNetsuite`)
+   also stamp it on create.
+4. Going forward the **daily sync** handles new items and keeps existing items current (the refresh);
+   items that predate the feature are caught up by the one-time backfills.
 
 ### One-time backfill (July 5+ orders)
 `backfill_isfulfillable_jul5.php` catches up Agilant items on SalesOrders since **2026-07-05**:
@@ -85,6 +106,14 @@ nearly everything resolves to `fulfillable = 1`.**
   in `Client_Compass.Apis` (name `Agilant`) — never reproduce the secret value.
 
 ## Change history
+- 2026-07-28 — Code-review hardening: (1) `getCreateItem` now **refreshes `isFulfillable` on
+  existing items** when NetSuite's value differs (not create-only), mirroring the serialized flag;
+  diff-only PUT keeps re-syncs no-op. (2) The two other `/items` creation paths
+  (`syncItemFulfillmentFromNetsuite`, `syncInventoryAdjustmentFromNetsuite`) now also stamp the flag
+  on create — they previously left it NULL. (3) Added `isFulfillable` to the worker sync's bulk
+  `/items` GET field list so the refresh has a stored value to diff. (4) New combined
+  `App_NetSuite::getItemSerializedAndFulfillable` returns both flags from one `ItemSearchBasic`, so
+  `getCreateItem` no longer makes two SOAP searches per line. (bala)
 - 2026-07-20 — Added `App_NetSuite::getItemIsFulfillable` (SOAP `ItemSearchBasic`, mirrors
   `getItemIsSerialized`) and wired `getCreateItem` to stamp `isFulfillable` on the item PUT/POST to
   api2 when non-null (internal id from order line or part-number lookup; stores
@@ -100,3 +129,5 @@ nearly everything resolves to `fulfillable = 1`.**
 - [NetSuite → TOGa Supply Per-Client Sync](../../worker/features/netsuite-togasupply-per-client-sync.md)
   — the sync engine this item flag rides in.
 - [Phase 2 — isFulfillable propagation up the SO↔PO chain (2.0)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md).
+- [isFulfillable multi-client backfill (worker)](../../worker/workflows/isfulfillable-multi-client-backfill.md)
+  — the cross-client catch-up cron and its client-DB / catalog-matching gotchas.

package/knowledge/1.0/apps/worker/INDEX.md

@@ -10,4 +10,5 @@
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
+| [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/workflows/isfulfillable-multi-client-backfill.md

@@ -0,0 +1,90 @@
+---
+title: isFulfillable Multi-Client Backfill (all togasupply clients)
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-07-28
+owners: [bala]
+files:
+  - worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php
+  - library/app/api/toga2.php
+related:
+  - ../features/netsuite-togasupply-per-client-sync.md
+  - ../../library/features/netsuite-item-isfulfillable-sync.md
+  - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
+  - ../../../clients/compass-usa/profile.md
+---
+
+## Summary
+One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17
+togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health, ERAU, GroWrk, NYC Health +
+Hospitals, Masonite, Miami-Dade, NCCI, Prudential, Quad, SBA, SHRSS, S&P Global, Trividia Health,
+and Compass). It is the multi-client successor to the Compass-only `backfill_isfulfillable_jul5.php`
+(see the [Phase 1 library doc](../../library/features/netsuite-item-isfulfillable-sync.md)). Like that
+one, it re-PUTs each Agilant **source** item to api2 `/items` so the **api2 interceptor does the
+recursive up-chain propagation** — it never writes the DB directly and never walks the chain itself.
+
+## Steps (how the cron runs)
+1. **Scope each client's Agilant-catalog items directly from that client's DB** — NOT via api2 —
+   keyed by `c_netsuiteInternalItemId`. Direct DB is required because that field is not an api2 GET
+   field (see gotchas). The Agilant catalog is matched by **`Catalogs.name = 'Agilant'`**, not by id.
+2. **Read `isFulfillable` from NetSuite by internal id** via SuiteQL `WHERE id IN (...)`, **cached
+   across clients** so a shared internal id is fetched once for the whole run.
+3. **PUT each source item to api2 `/items`** (`App_Api_Toga2::send`). The Items interceptor then
+   propagates the value up the SO↔PO chain onto every client-facing item (Phase 2).
+4. **Per-client scoping rule:**
+   - **Compass** — limited to orders since a cutoff (~**2026-06-20**); it was already partly
+     backfilled and only orders after that had correct chain linkage to propagate up to the client
+     items.
+   - **Every other client** — takes **ALL** its Agilant items (never previously backfilled).
+5. **Resilience:** clients whose DB read fails are **skipped and reported**, not fatal. Supports
+   `DRY_RUN`, `DB_HOST_PREFERENCE` (`localhost` / `writer.client` / `sandbox-dev`), and
+   `API_ENDPOINT_OVERRIDE` (the **9th arg** of `App_Api_Toga2::send`) so the run can target prod or a
+   beta/sandbox endpoint.
+
+## Gotchas / known issues
+- **Agilant catalog is matched by NAME, not id.** `Catalogs.name = 'Agilant'` is stable across every
+  client, but the `catalogId` **differs per client** — **Quad = 2, all other clients = 1** (verified
+  across all 17 client DBs). Hardcoding `catalogId = 2` would silently hit only Quad and miss the
+  other 16. Always resolve the catalog by name.
+- **`c_netsuiteInternalItemId` is NOT an api2 GET field** — there is no `Core.RecordField` for it, so
+  it can only be read by direct DB query. That is why the backfill scopes items via direct DB reads
+  rather than an api2 `/items` GET.
+- **Client DB names don't always follow the client identifier.** Compass's identifier is
+  `Compass_Usa` but its database is **`Client_Compass`**. All client DBs live on **one cluster**
+  (prod `prod-client`), so a single host/user/pass with a swapped **database name** reaches them all.
+- **⚠ Environment must be fully deployed, or the backfill can't propagate.** PUTting `isFulfillable`
+  to `api.beta.togahub.com` returns **EV-9 "no write permission"** — the field exists but the write
+  ACL was never deployed there (only `dev-sandbox` had field + interceptor + ACL). The Core
+  RecordField, the `ApiPayloadInterceptors` rows, **and** the client column + write ACL must all be
+  present on the **same** environment, and the run must scope from that same cluster. Deploy order:
+  dbchanges (field/ACL/interceptors) before running the backfill. See the
+  [Phase 2 deploy gotchas](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md).
+- **🔐 Credentials.** The cron reuses the per-client api uuids/secrets already embedded in the
+  `sync_togasupply_*` crons; the api secrets live in each `Client_<client>.Apis` (name `Agilant`) —
+  never reproduce a secret value in code or docs.
+
+## Run status
+- 2026-07-28 — Ran across all NetSuite/togasupply clients. Compass scoped to orders after
+  ~2026-06-20 (only those had correct chain linkage to propagate up to the client items); every other
+  client backfilled from all its Agilant items.
+
+## Change history
+- 2026-07-28 — Built and ran the multi-client `backfill_isfulfillable_all_clients.php`: direct
+  client-DB scoping of Agilant-catalog items (matched by `Catalogs.name`, not id) keyed by
+  `c_netsuiteInternalItemId`, NetSuite reads by internal id (cached across clients), re-PUT to api2 so
+  the interceptor recurses. Per-client scope (Compass ~post-2026-06-20, all others full), DRY_RUN /
+  DB_HOST_PREFERENCE / API_ENDPOINT_OVERRIDE knobs, failed-DB clients skipped + reported. Recorded the
+  catalog-by-name (Quad catalogId=2), `c_netsuiteInternalItemId`-not-a-GET-field, Compass DB-name, and
+  beta EV-9 deploy-gap gotchas. (bala)
+
+## Related docs
+- [isFulfillable from NetSuite during item sync (Phase 1, library)](../../library/features/netsuite-item-isfulfillable-sync.md)
+  — where the value is sourced and the earlier Compass-only backfill.
+- [isFulfillable propagation up the SO↔PO chain (Phase 2, _underscore)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md)
+  — the api2 interceptor this backfill relies on to do the recursion.
+- [NetSuite → TOGa Supply Per-Client Sync](../features/netsuite-togasupply-per-client-sync.md)
+  — the steady-state sync whose credentials/config this backfill reuses.

package/knowledge/2.0/apps/_underscore/features/fulfillable-item-propagation.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-28
 owners: [bala]
 files:
   - _underscore/Model/Client/Item.php
@@ -50,7 +50,14 @@ same bridge topology, walked for a different payload (a scalar flag rather than
    one-time backfill) send that field, so day-to-day item edits skip the walk entirely.
 2. **Load the source item** by uuid → `id` + `isFulfillable`. If the value is **NULL**, return
    (nothing authoritative to propagate).
-3. **Walk the chain UP** with a `WITH RECURSIVE ChainSalesOrderItems` CTE:
+   - **Writer-routed (read-your-writes).** Both this source read **and** the chain-walk CTE below
+     call `->setisReadHostEnabled(false)` so they execute on the **writer**, not a read replica.
+     `_Query` routes SELECTs to a read replica by default (`Query.php` ~line 273) — a separate
+     connection that cannot see this request's still-open write transaction and can lag replication,
+     so a replica read could return the *pre-write* value (or NULL for a brand-new item) and
+     propagate the wrong value or skip. The UPDATE was already writer-routed; now read + update share
+     the one request transaction.
+3. **Walk the chain UP** with a `WITH RECURSIVE ChainSalesOrderItems` CTE (also writer-routed, see above):
    - **Anchor:** `SalesOrderItems WHERE itemId = <sourceItemId>`.
    - **Recursive step:** join `PurchaseOrderItems_SalesOrderItems` (PSO) then
      `SalesOrderItems_PurchaseOrderItems` (SPO) to climb one tier
@@ -93,6 +100,20 @@ uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfilla
 - Engine itself is shared `_Model_Client_Item` logic; any client with the schema present gets it.
 
 ## Gotchas / known issues
+- **⚠ Propagation reads MUST be writer-routed.** `_Query` SELECTs default to a read replica
+  (`Query.php` ~line 273), a separate connection that can't see the current request's open write
+  transaction and may lag replication. The interceptor runs inside the write request, so a
+  replica-routed read here can see the **pre-write** value (or NULL on a just-created item) and
+  propagate wrongly or skip. Both SELECTs in `propagateFulfillableAcrossChain` therefore set
+  `setisReadHostEnabled(false)`. Any future read added to an interceptor that must see the same
+  request's writes needs the same treatment.
+- **⚠ Beta deploy gap — EV-9 "no write permission" (write ACL not deployed).** PUTting
+  `isFulfillable` to `api.beta.togahub.com` returns **EV-9**: the field *exists* there but its write
+  ACL was never deployed (only `dev-sandbox` had the full field + interceptor + ACL from earlier
+  work). The three pieces — Core RecordField, `ApiPayloadInterceptors` rows, **and** the client
+  column + write ACL — must all be present on the **same** environment (and a backfill run must scope
+  from that same cluster) or the write is rejected and nothing propagates. Reinforces the deploy-order
+  dependency: dbchanges (field + ACL + interceptors) before the code/backfill that writes the field.
 - **⚠ Interceptors are DB-driven.** The `postPost`/`postPut` PHP does nothing without the
   `ApiPayloadInterceptors` rows in the **target env's Core DB**. Missing rows → the hook never
   fires **and** api2 EV-8's the unknown `isFulfillable` field, **403-ing the whole request** (not
@@ -108,6 +129,12 @@ uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfilla
   vs. using `itemtype` to hide services — is **pending product confirmation**.
 
 ## Change history
+- 2026-07-28 — Fixed a **read-replica routing** bug: `propagateFulfillableAcrossChain`'s source-item
+  read and the recursive chain-walk CTE now `setisReadHostEnabled(false)` so they run on the writer
+  and see the request's own open write transaction (read-your-writes) — a replica read could return
+  the pre-write value or NULL and propagate wrongly/skip. Recorded the **beta EV-9 write-ACL deploy
+  gap** (field present but write ACL undeployed on `api.beta.togahub.com`; all three deploy pieces
+  must land on the same env). (bala)
 - 2026-07-20 — Built the isFulfillable up-chain propagation engine:
   `propagateFulfillableAcrossChain` + the payload-gated `postPost`/`postPut` interceptor on Items
   (recursive SOI↔POI CTE, diff-only `UPDATE`), plus the Compass `parent::` fix so the price-override

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa View Frontend (toga2-view) Architecture](architecture.md) | `toga2-view` is the **React/TypeScript single-page frontend** for the TOGa 2.0 platform — the customer-facing web app (home warranty / tech-support portals). | toga2-view/src/main.tsx, toga2-view/src/App.tsx, toga2-view/src/routes.tsx, toga2-view/src/api/axiosInstance.ts, toga2-view/src/api/apiFunctions.ts, toga2-view/src/utils/queryHelpers.ts, toga2-view/src/contexts/AuthContext.tsx, toga2-view/src/contexts/useUserStore.ts, toga2-view/src/hooks/useAuthenticationFlow.ts, toga2-view/vite.config.ts, toga2-view/package.json |
+| [Get Support — Subscription Details & Cancel Subscription Gating](features/get-support-cancel-subscription.md) | The Get Support page (`/get-support?itemUuid=…`) shows a **subscription details card** (plan · price · renewal date) for the service the user clicked, and — **o | toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts, toga2-view/src/pages/GetSupport/view/GetSupportPage.tsx, toga2-view/src/pages/GetSupport/viewModels/DUMMYFIELDS/SUPPORTDUMMYFIELDS.json, toga2-view/src/constants/featureFlags.ts, toga2-view/src/hooks/useBundleServices.ts |
 | [Mobile Nav Header](features/mobile-nav-header.md) | The `MobileNavToggle` component renders the fixed 72 px header (hamburger + Rate logo) and the slide-in drawer nav. | toga2-view/src/components/MobileNav/MobileNav.tsx, toga2-view/public/assets/Rate_Logo.svg |
 | [/v2 Query-String Builder (assembleOptions / where coercion)](features/query-string-builder.md) | `src/utils/queryHelpers.ts` converts a structured JS options object (`fields`, `where`, `join`/`ojoin`, `sort`, …) into the `api2` `/v2` query string. | toga2-view/src/utils/queryHelpers.ts, toga2-view/src/utils/queryHelpers.test.ts |
 | [Service Card Component](features/service-card.md) | The `ServiceCard` component renders a single service subscription (tech support or home warranty) on both the Home and Services pages. | toga2-view/src/components/ServiceCard/ServiceCard.tsx, toga2-view/src/pages/Services/view/ServicesPage.tsx, toga2-view/src/pages/Home/view/HomePage.tsx, toga2-view/src/constants/bundleConstants.ts, toga2-view/src/pages/Services/viewModels/DUMMYFIELDS/SERVICESDUMMYFIELDS.json |

package/knowledge/2.0/apps/toga2-view/features/get-support-cancel-subscription.md

@@ -0,0 +1,145 @@
+---
+title: "Get Support — Subscription Details & Cancel Subscription Gating"
+framework: "2.0"
+repo: toga2-view
+project: TOGa View Frontend
+client: shared
+type: feature
+status: active
+updated: 2026-07-28
+owners: ["tcox"]
+files:
+  - toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts
+  - toga2-view/src/pages/GetSupport/view/GetSupportPage.tsx
+  - toga2-view/src/pages/GetSupport/viewModels/DUMMYFIELDS/SUPPORTDUMMYFIELDS.json
+  - toga2-view/src/constants/featureFlags.ts
+  - toga2-view/src/hooks/useBundleServices.ts
+related:
+  - ../architecture.md
+  - ../../../../clients/rate/features/service-card-entitlements.md
+  - ../../../../clients/rate/profile.md
+---
+
+## Summary
+
+The Get Support page (`/get-support?itemUuid=…`) shows a **subscription details card**
+(plan · price · renewal date) for the service the user clicked, and — **only for tech-support
+services** — a **Cancel Subscription** button plus a confirmation modal. Whole Home (WH) warranty
+services and unclassified services get the subscription details card **without** any cancel path.
+
+Two things about this flow are easy to get wrong and are the reason it is documented:
+
+- The cancel affordance exists **only on this page** — `ServiceCard` has none.
+- **There is no backend cancellation endpoint yet.** The viewModel's `cancelSubscription()` is a
+  stub that always rejects, so confirming surfaces an error instead of faking success.
+
+## Key files / entry points
+
+- `pages/GetSupport/viewModels/getSupportPageViewModel.ts` — resolves `activeService`, builds the
+  `subscription` object, exposes `canCancelSubscription` and the `cancelSubscription()` stub
+- `pages/GetSupport/view/GetSupportPage.tsx` — the **only** place a cancel affordance is rendered;
+  computes `showCancelUi` and owns the confirm-modal state (`showCancelModal`, `cancelError`)
+- `constants/featureFlags.ts` — `CANCEL_SUBSCRIPTION_ENABLED` (currently `true`); flipping it to
+  `false` hides the whole cancel path in one place
+- `viewModels/DUMMYFIELDS/SUPPORTDUMMYFIELDS.json` — copy: `renewsPrefix`, `cancelNote`
+  ("You can cancel anytime. Coverage continues until the end of your current period."),
+  `confirm.*` (including `confirm.errorMessage`)
+- `hooks/useBundleServices.ts` — `detectServiceType()`, the classification the gate reuses
+
+## How it works
+
+1. **`activeService` resolution.** The viewModel picks the bundle service whose `uuid` matches the
+   URL's `itemUuid`, falls back to the first service with `isActive`, else `null`:
+   ```ts
+   const activeService =
+       bundleServices?.find((service) => service.uuid === itemUuid) ??
+       bundleServices?.find((service) => service.isActive) ??
+       null;
+   ```
+   The subscription card **and** the cancel gate both read this same `activeService`, so older links
+   without a resolvable `itemUuid` behave consistently across both.
+
+2. **Subscription details.** `subscription` = `{ plan, price, renewalDate, entitlementUuid }` from
+   `activeService`, else `null`. The card renders whenever `subscription` exists — **including for
+   warranty services**. Gating cancel does not hide the plan/price/renewal information.
+
+3. **The gate (positive, not negative).**
+   ```ts
+   const canCancelSubscription = activeService?.serviceType === "tech";
+   ```
+   `'warranty'` **and** `'other'` therefore both hide it — an unclassified service fails closed.
+   `serviceType` comes from `detectServiceType(bundleName || itemTitle)` in `useBundleServices`
+   (title-substring classification: contains "warranty"/"whole home" and not "tech" → `'warranty'`;
+   contains "tech"/"support" → `'tech'`; else `'other'`). This is the same signal that switches
+   `ServiceCard`'s second data row between **Price** (tech) and **Address** (warranty), so the cancel
+   gate and the service cards agree by construction.
+
+4. **The view gates three things with one boolean.**
+   ```ts
+   const showCancelUi = CANCEL_SUBSCRIPTION_ENABLED && canCancelSubscription;
+   ```
+   - the Cancel Subscription button
+   - the confirm modal (`showCancelUi && showCancelModal`)
+   - the `cancelNote` sentence appended to the `subscriptionDetails` string
+
+   The note is gated deliberately: leaving *"You can cancel anytime…"* on a card with no cancel
+   button is self-contradictory copy.
+
+5. **Confirm flow.** `handleConfirmCancel()` awaits `cancelSubscription()`; it closes the modal
+   **only** on a genuine resolve, and on rejection keeps the modal open and renders
+   `subscriptionFields.confirm.errorMessage`. Since the stub always throws, today's real-world
+   outcome is always the error state — intentional, so nothing reports a cancellation that did not
+   happen.
+
+## Decision — gate on `serviceType`, not on `isRateWarranty`
+
+The page already carries a separate warranty signal: `isRateWarranty = bundleUuid ===
+HOME_WARRANTY_BUNDLE_UUID`, used to route the **TICKETS** support method to the claims-style
+create-ticket link. It was deliberately **not** reused for the cancel gate:
+
+- `serviceType` is a *product classification*, so any service classified `'tech'` gets cancel —
+  it does not need a bundle uuid allowlist maintained per product.
+- It keeps this page consistent with the service cards, which already branch on `serviceType`.
+- A bundle-uuid check would silently fail open for any new warranty bundle uuid.
+
+**Why WH is excluded at all:** Whole Home warranty contracts (the AIG-backed warranty product) are
+not self-service cancellable from the portal; only tech-support subscriptions are.
+
+## Gotchas / known issues
+
+- **The cancel UI lives only on `GetSupportPage.tsx`.** `ServiceCard` has no cancel affordance —
+  do not go looking for one in `components/`, and do not add a second entry point without
+  reproducing the same `showCancelUi` gate.
+- **No backend endpoint exists.** `cancelSubscription()` throws
+  `"Subscription cancellation is not available yet."` by design (reject, never resolve). Swap the
+  body for the real API call when the endpoint ships; do not "fix" it by resolving.
+- **`detectServiceType` now has a second consumer with a policy consequence.** Widening its
+  `'tech'` keywords does not just change a card row any more — it **exposes the cancel button** for
+  whatever newly matches. Check both call sites before touching the classifier.
+- **The gate fails closed on `'other'`.** If a legitimately cancellable service stops matching
+  "tech"/"support" in its bundle/item title, its cancel button silently disappears. The title is the
+  only input.
+- **`cancelNote` is not standalone copy** — it is concatenated into `subscriptionDetails` and gated
+  by `showCancelUi`. Any new surface rendering that string must gate it the same way.
+- **`CANCEL_SUBSCRIPTION_ENABLED = false` hides button + modal + note but keeps the subscription
+  details card** — that is the intended kill-switch behavior.
+- **Never close the confirm modal on failure.** Closing it reads to the user as a successful
+  cancellation.
+
+## Client variations
+
+Rate is the consumer of this page today. Its product mix — Whole Home Warranty (AIG-backed) plus
+tech support — is what makes the gate load-bearing: both products appear as active services for the
+same user, so the page must distinguish them per service rather than per account. See
+[Rate profile](../../../../clients/rate/profile.md) and
+[Service Card Entitlement Display](../../../../clients/rate/features/service-card-entitlements.md).
+
+## Change history
+
+- 2026-07-28 — Cancel Subscription UI gated by service type: viewModel exposes
+  `canCancelSubscription` (`activeService?.serviceType === "tech"`), and the view's `showCancelUi`
+  now gates the button, the confirm modal, and the `cancelNote` sentence. WH warranty and
+  unclassified services keep the subscription details card with no cancel path. Also first capture of
+  the pre-existing flow: cancel exists only on `GetSupportPage`, is flagged by
+  `CANCEL_SUBSCRIPTION_ENABLED`, and `cancelSubscription()` is a stub that always rejects until the
+  backend endpoint ships. (tcox)

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 14 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 16 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 17 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 10 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
@@ -23,7 +23,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **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)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
-- **toga2-view** (TOGa View Frontend) — 6 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
+- **toga2-view** (TOGa View Frontend) — 7 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **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)

package/knowledge/clients/rate/features/service-card-entitlements.md

@@ -6,7 +6,7 @@ project: TOGa View Frontend
 client: rate
 type: client-feature
 status: active
-updated: 2026-07-27
+updated: 2026-07-28
 owners: ["bala", "tcox", "mhammontree"]
 files:
   - src/components/ServiceCard/ServiceCard.tsx
@@ -24,6 +24,7 @@ files:
 related:
   - clients/rate/profile.md
   - whole-home-warranty-purchase-guard.md
+  - 2.0/apps/toga2-view/features/get-support-cancel-subscription.md
 ---
 
 ## Summary
@@ -101,6 +102,11 @@ This feature is Rate-specific. The warranty card showing Address instead of Pric
 by Rate's product mix (Whole Home Warranty + Tech Support). Other clients with different
 product types would need `detectServiceType` extended or overridden.
 
+**`detectServiceType` is no longer display-only.** As of 2026-07-28 it also gates the
+**Cancel Subscription** UI on the Get Support page (`serviceType === 'tech'` — WH warranty and
+unclassified services get no cancel path). See
+[Get Support — Subscription Details & Cancel Subscription Gating](../../../2.0/apps/toga2-view/features/get-support-cancel-subscription.md).
+
 ## Gotchas / known issues
 
 - **`ojoin` is required for address** — using INNER JOIN (`join`) drops every entitlement
@@ -115,6 +121,10 @@ product types would need `detectServiceType` extended or overridden.
   `AddSubscriptionSheet`) replaces the old "Get Started" inactive bundle cards.
 - **`useBundleServices` is shared** — both `useHomePageViewModel` and `useServicePageViewModel`
   call it. Changes to the hook affect both pages.
+- **Widening `detectServiceType`'s `'tech'` keywords now changes entitlement *permissions*, not just
+  a card row.** The Get Support page gates its Cancel Subscription button on
+  `serviceType === 'tech'`, so anything newly classified as tech becomes self-service cancellable.
+  Review both consumers (`ServiceCard` row 2 and the cancel gate) before editing the classifier.
 - **Show the entitlement's OWN pin only — never the contact's shared address.** The removed
   `contact.primaryContactAddress` fallback made every unpinned card display the same (latest)
   address because that field is one shared, purchase-overwritten value per contact. An unpinned
@@ -137,6 +147,9 @@ product types would need `detectServiceType` extended or overridden.
 
 ## Change history
 
+- 2026-07-28 — `detectServiceType` gained a second, non-display consumer: the Get Support page gates
+  its Cancel Subscription UI on `serviceType === 'tech'`, so the classifier now decides which
+  entitlements are self-service cancellable. (tcox)
 - 2026-07-27 — TRUE-79533: recorded that `fetchAddressesByIds`
   (`GET /v2/addresses?fields=id,line1,...`) returned **403 `EZ-2`** because the **`Addresses.id`
   field** had no read ACL grant in `Client_Rate` — the numeric `id` is ACL-gated like any field. Fixed

package/package.json

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