toga-ai 1.0.159 → 1.0.161

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

@@ -7,3 +7,4 @@
 | [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 |
 | [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 |
 | [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 |
+| [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php |

package/knowledge/1.0/apps/library/features/startech-pcmaticb2b-sync.md

@@ -0,0 +1,68 @@
+---
+title: Startech PC Matic B2B Sync (library)
+framework: "1.0"
+repo: library
+project: Library
+client: pcmaticb2b
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - library/app/api/toga2.php
+related:
+  - clients/pcmaticb2b/features/startech-ticket-sync.md
+  - clients/pcmaticb2b/profile.md
+---
+
+## Summary
+
+`library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. All tickets sync in both directions regardless of `c_escalateToStartech` value — the Startech exclusion is enforced by `_Trait_Startech_Ticket`, not here.
+
+## Key Function
+
+`App_Api_Toga2::syncToga2TicketIntoTogadesk1Ticket()` (~line 5095)
+
+PC Matic B2B path detected via:
+```php
+$isPcmaticb2bUuid = (self::$togaClientUuid == App_Api_Toga2::CLIENT_UUID_PCMATICB2B);
+```
+
+## Ticket Type Map: TOGA 2.0 to TOGaDesk
+
+```php
+$ticketTypeMap = [
+    TOGA2_TICKET_TYPE_CODE__SUPPORT      => TOGADESK_TICKET_TYPE__INCIDENT,
+    TOGA2_TICKET_TYPE_CODE__API          => TOGADESK_TICKET_TYPE__API,
+    TOGA2_TICKET_TYPE_CODE__PCS          => TOGADESK_TICKET_TYPE__PCS,
+    TOGA2_TICKET_TYPE_CODE__TOGADESK_PCS => TOGADESK_TICKET_TYPE__TOGADESK_PCS,
+];
+```
+
+## Ticket Type Map: TOGaDesk to TOGA 2.0
+
+Applied at two callsites (~lines 6845 and 7417):
+
+```php
+if ($togadeskTicketTypeCustomFieldValue === TOGADESK_TICKET_TYPE__API) {
+    $toga2TicketTypeCode = TOGA2_TICKET_TYPE_CODE__API;
+} elseif ($togadeskTicketTypeCustomFieldValue === TOGADESK_TICKET_TYPE__PCS
+       || $togadeskTicketTypeCustomFieldValue === TOGADESK_TICKET_TYPE__TOGADESK_PCS) {
+    $toga2TicketTypeCode = TOGA2_TICKET_TYPE_CODE__PCS;
+} else {
+    $toga2TicketTypeCode = TOGA2_TICKET_TYPE_CODE__SUPPORT;
+}
+$payload['ticketType'] = ['code' => $toga2TicketTypeCode];
+```
+
+Both `PCS Ticket` and `TOGaDesk-PCS` map to `PCS` in TOGA 2.0.
+
+## Gotchas
+
+- **Do not add a NULL early-return guard in this function.** NULL `c_escalateToStartech` means the ticket was created in TOGaDesk — it must still sync to TOGA 2.0. The Startech gate lives in `_Trait_Startech_Ticket::postPost`, not here.
+- **`SUPPORT REQUEST` with a space** — `TOGA2_TICKET_TYPE_CODE__SUPPORT = 'SUPPORT REQUEST'`. Using `'SUPPORT'` silently breaks type matching.
+- **`$isPcmaticb2bUuid` flag** is used for PC Matic B2B-specific branching throughout `syncToga2TicketIntoTogadesk1Ticket()`.
+
+## Change history
+
+- 2026-06-23: Initial doc — ticket type maps (both directions), NULL sync behavior, TOGADESK_PCS type added

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

@@ -9,4 +9,5 @@
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |

package/knowledge/2.0/apps/worker2/features/startech-webhook-handler.md

@@ -0,0 +1,58 @@
+---
+title: Startech Webhook Handler (worker2)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: pcmaticb2b
+type: feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - worker2/Worker/Startech.php
+related:
+  - clients/pcmaticb2b/features/startech-ticket-sync.md
+  - clients/pcmaticb2b/profile.md
+---
+
+## Summary
+
+Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. Sets `c_escalateToStartech = 0` on all webhook-originated tickets so the sync system recognizes them as Startech-sourced without re-posting them back to Startech.
+
+## Key File
+
+`worker2/Worker/Startech.php` — `_Worker_Startech::Webhook()`
+
+## How It Works
+
+1. Startech POSTs a webhook event to the TOGA 2.0 worker endpoint
+2. `Webhook()` extracts `ticket_id` from the payload as `$startechTicketId`
+3. Searches TOGA 2.0 for an existing ticket with `c_startechTicketId = $startechTicketId`
+4. If not found: `POST /tickets` (create); if found: `PUT /tickets/{uuid}` (update)
+5. Builds payload with ticket fields + `c_escalateToStartech: 0`
+6. `_Trait_Startech_Ticket::postPost` gate: `!($payload->c_escalateToStartech ?? null)` evaluates `!0 = true` — skips re-posting to Startech since ticket already exists there
+
+## Payload Fields
+
+```php
+$payload = [
+    'c_startechTicketId'   => $startechTicketId,
+    'c_escalateToStartech' => 0,
+    'number'               => (string) $startechTicketId,
+    'ticketType'           => ['c_startechTicketTypeId' => $startechPayload->ticket_type],
+    'urgency'              => ['c_startechPriorityId'   => $startechPayload->ticket_priority],
+    'shortDescription'     => $startechPayload->subject,
+    'longDescription'      => $startechPayload->description,
+];
+```
+
+Conditional additions: `ticketStage` (from `ticket_status`), `contact` (from `creator`).
+
+## Gotchas
+
+- `c_escalateToStartech: 0` must be in the payload. If omitted, the interceptor still skips Startech (null is also falsy), but the field stays NULL in TOGA 2.0 — making webhook tickets indistinguishable from TOGaDesk-created ones.
+- `ticketType` is resolved via `c_startechTicketTypeId` on `TicketTypes` — not a hardcoded string. Startech type IDs: SR=6, PCS=54, API=201.
+
+## Change history
+
+- 2026-06-23: Initial doc — webhook handler, c_escalateToStartech=0 payload field, POST vs PUT logic

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 5 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 6 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 10 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 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)
@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 10 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 9 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
@@ -42,6 +42,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **NYC Health & Hospitals** (`nychh`) → [clients/nychh/INDEX.md](clients/nychh/INDEX.md)
 - **Office Depot** (`office-depot`) → [clients/office-depot/INDEX.md](clients/office-depot/INDEX.md)
+- **PC Matic B2B Client Profile** (`pcmaticb2b`) → [clients/pcmaticb2b/INDEX.md](clients/pcmaticb2b/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 - **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)

package/knowledge/clients/pcmaticb2b/INDEX.md

@@ -0,0 +1,6 @@
+# Client: PC Matic B2B Client Profile `pcmaticb2b`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [PC Matic B2B — Startech Ticket Sync](features/startech-ticket-sync.md) | 1.0 | Bidirectional ticket sync between TOGaDesk 1.0 (client 177), TOGA 2.0 (client 21), and Startech (Easeedesk). | worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php, library/app/api/toga2.php, togadesk/desk/includes/controllers/quickactions.php, togadesk/desk/template/pages/tickets/manage.php, togadesk/desk/includes/functions.php, worker2/Worker/Startech.php, _underscore/Trait/Startech/Ticket.php, dbchanges2/Client_Pcmaticb2b/2026-06-22-pcmaticb2b-enhancements.sql |
+| [PC Matic B2B Client Profile](profile.md) | 1.0 | PC Matic B2B is a client using TOGaDesk 1.0 for ticket management, with TOGA 2.0 as the data layer and Startech (Easeedesk) as an external ticketing system for | worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php, togadesk/desk/includes/functions.php |

package/knowledge/clients/pcmaticb2b/features/startech-ticket-sync.md

@@ -0,0 +1,159 @@
+---
+title: PC Matic B2B — Startech Ticket Sync
+framework: "1.0"
+project: TOGa
+client: pcmaticb2b
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php
+  - library/app/api/toga2.php
+  - togadesk/desk/includes/controllers/quickactions.php
+  - togadesk/desk/template/pages/tickets/manage.php
+  - togadesk/desk/includes/functions.php
+  - worker2/Worker/Startech.php
+  - _underscore/Trait/Startech/Ticket.php
+  - dbchanges2/Client_Pcmaticb2b/2026-06-22-pcmaticb2b-enhancements.sql
+related:
+  - clients/pcmaticb2b/profile.md
+  - 2.0/apps/worker2/features/startech-webhook-handler.md
+  - 1.0/apps/library/features/startech-pcmaticb2b-sync.md
+---
+
+## Summary
+
+Bidirectional ticket sync between TOGaDesk 1.0 (client 177), TOGA 2.0 (client 21), and Startech (Easeedesk). The goal is full data parity between 1.0 and 2.0 (long-term 1.0 retirement path), while Startech only receives tickets that originated there or were explicitly escalated by an analyst.
+
+## c_escalateToStartech Field
+
+The `Client_Pcmaticb2b.Tickets.c_escalateToStartech` TINYINT(1) field controls sync behavior:
+
+| Value | Meaning | Syncs 1.0↔2.0 | Posts to Startech |
+|-------|---------|----------------|-------------------|
+| `NULL` | Created in TOGaDesk manually | Yes | No |
+| `0` | Originated from Startech (webhook-created) | Yes | No (already there) |
+| `1` | Escalated via "Escalate to Startech" button | Yes | Yes |
+
+Column: `TINYINT(1) UNSIGNED NULL DEFAULT NULL`
+
+## Ticket Type Map
+
+### TOGA 2.0 to TOGaDesk 1.0
+
+| TOGA 2.0 Code | TOGaDesk Name | TOGaDesk Dept |
+|---------------|---------------|---------------|
+| `SUPPORT REQUEST` | Startech Incident | 336 |
+| `PCS` | PCS Ticket | 337 |
+| `API` | API Ticket | 338 |
+| `TOGADESK_PCS` | TOGaDesk-PCS | 337 |
+
+### TOGaDesk 1.0 to TOGA 2.0
+
+| TOGaDesk Name | TOGA 2.0 Code |
+|---------------|---------------|
+| `API Ticket` | `API` |
+| `PCS Ticket` | `PCS` |
+| `TOGaDesk-PCS` | `PCS` |
+| anything else | `SUPPORT REQUEST` |
+
+`TOGADESK_PCS` maps to `PCS` in TOGA 2.0 — it is the pre-escalation placeholder type for manually created tickets destined for PCS.
+
+## Startech Ticket Type IDs (c_startechTicketTypeId)
+
+| Code | Startech ID |
+|------|-------------|
+| `SUPPORT REQUEST` | 6 |
+| `PCS` | 54 |
+| `API` | 201 |
+
+The `ticketType` on Startech-originated tickets is resolved dynamically via `c_startechTicketTypeId` on `TicketTypes` — not hardcoded.
+
+## Sync Direction 1: Startech to TOGA 2.0 (Webhook)
+
+`worker2/Worker/Startech.php` — `_Worker_Startech::Webhook()`
+
+1. Startech POSTs a webhook event on ticket create/update
+2. Worker looks up TOGA 2.0 ticket by `c_startechTicketId`
+3. Creates (POST) or updates (PUT) the ticket in TOGA 2.0
+4. Payload includes `c_escalateToStartech: 0` — marks it as Startech-originated
+5. `_Trait_Startech_Ticket::postPost` gate evaluates `!0 = true` — skips re-posting to Startech (already there)
+
+## Sync Direction 2: TOGA 2.0 to TOGaDesk 1.0 (CRON)
+
+`library/app/api/toga2.php` — `App_Api_Toga2::syncToga2TicketIntoTogadesk1Ticket()`
+
+CRON calls `syncWithToga()` every 2 minutes. All PC Matic B2B tickets sync regardless of `c_escalateToStartech` value — NULL, 0, and 1 all sync to TOGaDesk. Ticket type is mapped using the TOGA 2.0 to TOGaDesk map above.
+
+## Sync Direction 3: TOGaDesk 1.0 to TOGA 2.0 (CRON)
+
+`library/app/api/toga2.php` — called by `syncWithTogadesk()` in the same CRON
+
+Pushes TOGaDesk ticket changes back to TOGA 2.0. Ticket type mapped using the TOGaDesk to TOGA 2.0 map above.
+
+## Sync Direction 4: TOGA 2.0 to Startech (Interceptors)
+
+`_underscore/Trait/Startech/Ticket.php`
+
+- `postPost`: fires on new TOGA 2.0 ticket creation. Gate: `if (!($payload->c_escalateToStartech ?? null)) { return; }` — only proceeds when value is `1`. NULL and `0` both evaluate to falsy and skip.
+- `postPut`: fires on update. Creates in Startech when `c_escalateToStartech` flips to `1` and no `c_startechTicketId` yet.
+
+## Escalate to Startech Button
+
+Shown on the TOGaDesk manage ticket page only for client 177. Handler: `quickactions.php` case `"escalateToStartech"`.
+
+Flow:
+1. Confirm dialog: "Escalate this ticket to Startech? The ticket type will be changed to PCS."
+2. Loads ticket, gets TOGA 2.0 UUID from `referenceId`
+3. GETs PCS ticket type UUID from TOGA 2.0 (`code = 'PCS'`)
+4. PUTs `/tickets/{uuid}` with `c_escalateToStartech: 1` + `ticketType: {uuid: $pcsTypeUuid}`
+5. Sets TOGaDesk `departmentid = 337` (PCS dept) and saves
+6. `postPut` interceptor fires and creates the Startech ticket
+7. History comment added, page redirects
+
+## DB Migration
+
+`dbchanges2/Client_Pcmaticb2b/2026-06-22-pcmaticb2b-enhancements.sql`
+
+- `Contacts.c_togaCustomerId` — TOGaDesk 1.0 customer ID cross-reference
+- `Tickets.c_escalateToStartech` — sync state flag (see above)
+- `TicketTypes.c_togadeskTicketDepartmentId` — maps TOGA 2.0 ticket type to TOGaDesk dept
+- Department UPDATE: SR=336, PCS=337, API=338
+- INSERT `TOGADESK_PCS` ticket type (code=`TOGADESK_PCS`, dept=337)
+- All new fields registered in `CustomRecordFields` + `AclCustomFieldPermissions`
+
+## Constants
+
+### togadesk/desk/includes/functions.php
+```php
+const CLIENT_PCMATICB2B = 177;
+const CLIENT_DEPARTMENT_PCMATICB2B_PCS = 337;
+```
+
+### sync_togadesk_startech_pcmaticb2b.php
+```php
+const TOGADESK_PCMATICB2B_CLIENT_ID = 177;
+const TOGADESK_PCMATICB2B_STARTECH_DEPARTMENT_ID = 326;
+const TOGA_PCMATICB2B_CLIENT_ID = 21;
+const TOGA2_TICKET_TYPE_CODE__SUPPORT      = 'SUPPORT REQUEST';
+const TOGA2_TICKET_TYPE_CODE__PCS          = 'PCS';
+const TOGA2_TICKET_TYPE_CODE__API          = 'API';
+const TOGA2_TICKET_TYPE_CODE__TOGADESK_PCS = 'TOGADESK_PCS';
+const TOGADESK_TICKET_TYPE__INCIDENT       = 'Startech Incident';
+const TOGADESK_TICKET_TYPE__PCS            = 'PCS Ticket';
+const TOGADESK_TICKET_TYPE__API            = 'API Ticket';
+const TOGADESK_TICKET_TYPE__TOGADESK_PCS   = 'TOGaDesk-PCS';
+```
+
+## Gotchas / Known Issues
+
+- **`SUPPORT REQUEST` not `SUPPORT`** — the DB value has a space. Using `'SUPPORT'` breaks type matching silently.
+- **TOGADESK_PCS maps to PCS in TOGA 2.0** — both `PCS Ticket` and `TOGaDesk-PCS` TOGaDesk types map to the `PCS` code in TOGA 2.0. Intentional.
+- **NULL tickets sync 1.0 and 2.0** — Startech exclusion for NULL is enforced by `_Trait_Startech_Ticket`, not the CRON. Do not add a NULL early-return guard in `syncToga2TicketIntoTogadesk1Ticket()`.
+- **Webhook must set c_escalateToStartech=0** — without this, the `postPost` gate evaluates `!null = true` and would skip Startech for webhook-originated tickets on any subsequent PUT.
+- **ticketType uses c_startechTicketTypeId dynamically** — stored on `TicketTypes`, not hardcoded in the worker.
+
+## Change history
+
+- 2026-06-23: Initial doc — full bidirectional sync, c_escalateToStartech semantics, ticket type maps, escalate button, DB migration, constants, gotchas

package/knowledge/clients/pcmaticb2b/profile.md

@@ -0,0 +1,58 @@
+---
+title: PC Matic B2B Client Profile
+framework: "1.0"
+project: TOGa
+client: pcmaticb2b
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php
+  - togadesk/desk/includes/functions.php
+related:
+  - clients/pcmaticb2b/features/startech-ticket-sync.md
+---
+
+## Summary
+
+PC Matic B2B is a client using TOGaDesk 1.0 for ticket management, with TOGA 2.0 as the data layer and Startech (Easeedesk) as an external ticketing system for escalated/inbound tickets. All three systems sync bidirectionally.
+
+## Key IDs
+
+| Identifier | Value |
+|------------|-------|
+| TOGaDesk 1.0 client ID | 177 |
+| TOGA 2.0 client ID | 21 |
+| TOGA 2.0 client UUID constant | `App_Api_Toga2::CLIENT_UUID_PCMATICB2B` |
+| TOGA 2.0 API UUID constant | `App_Api_Toga2::API_UUID_PCMATICB2B` |
+| TOGA 2.0 API secret constant | `App_Api_Toga2::API_SECRET_PCMATICB2ID` |
+| Startech department in TOGaDesk | 326 |
+
+## Departments (TOGaDesk 1.0)
+
+| Constant | ID | Ticket Type |
+|----------|----|-------------|
+| `TOGADESK_PCMATICB2B_DEPARTMENT_ID__SUPPORT_REQUEST` | 336 | Support Request |
+| `TOGADESK_PCMATICB2B_DEPARTMENT_ID__PCS` | 337 | PCS / TOGaDesk-PCS |
+| `TOGADESK_PCMATICB2B_DEPARTMENT_ID__API` | 338 | API |
+
+## Ticket Type IDs in Startech (Easeedesk)
+
+| TOGA 2.0 Code | Startech Type ID |
+|---------------|-----------------|
+| `SUPPORT REQUEST` | 6 |
+| `PCS` | 54 |
+| `API` | 201 |
+
+## CRON Entry Point
+
+`worker/crons/toga2/startech/sync_togadesk_startech_pcmaticb2b.php` — runs every 2 minutes.
+
+Calls:
+1. `App_Api_Toga2::syncWithToga()` — pulls TOGA 2.0 tickets into TOGaDesk
+2. `App_Api_Toga2::syncWithTogadesk()` — pushes TOGaDesk tickets to TOGA 2.0
+
+## Change history
+
+- 2026-06-23: Initial profile — client IDs, departments, Startech ticket type IDs, CRON entry point

package/knowledge/clients/tow-foundation/INDEX.md

@@ -2,5 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Credit Card Receipt Processing](features/receipt-processing.md) | 2.0 | Automated processing of credit card receipts uploaded to SharePoint. | worker2/Worker/Client/TowFoundation.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php, worker2/Worker/Client/TowFoundation/TowFoundationVendors.php |
+| [Credit Card Receipt Processing](features/receipt-processing.md) | 2.0 | Automated processing of credit card receipts uploaded to SharePoint. | worker2/Worker/Client/TowFoundation.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php, worker2/Worker/Client/TowFoundation/TowFoundationVendors.php, worker2/Worker/Client/TowFoundation/TowFoundationCategories.php |
 | [Tow Foundation](profile.md) | 2.0 | Tow Foundation is a nonprofit client. |  |

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -5,12 +5,13 @@ project: Worker
 client: tow-foundation
 type: client-feature
 status: active
-updated: 2026-06-18
+updated: 2026-06-23
 owners: ["rgirish"]
 files:
   - worker2/Worker/Client/TowFoundation.php
   - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
   - worker2/Worker/Client/TowFoundation/TowFoundationVendors.php
+  - worker2/Worker/Client/TowFoundation/TowFoundationCategories.php
 related:
   - clients/tow-foundation/profile.md
 ---
@@ -86,7 +87,7 @@ Amex billing cycle runs 3rd-to-3rd. `computeRefNo()` returns the cycle-end date
 `TowFoundationVendors.php` holds 2,994 vendor names exported verbatim from Tow Foundation's
 QuickBooks vendor list (June 2026). `matchQbVendor()` runs three passes against this list:
 1. Exact match (case-insensitive)
-2. Substring match — QB name contains extracted name or vice versa (min 4 chars); picks shortest match on multiple hits
+2. Substring match — QB name contains extracted name or vice versa; minimum 3 chars. For needles shorter than 4 chars, a **whole-word boundary check** is used (regex `(?<![a-z])<needle>(?![a-z])`) to prevent short acronyms like `"UPS"` from matching inside `"USPS"`. Picks shortest QB name on multiple hits.
 3. `similar_text()` similarity ≥ 80% — picks highest scorer
 
 Returns the exact QB vendor string or `''` if no confident match. The AI only extracts
@@ -95,11 +96,35 @@ Returns the exact QB vendor string or `''` if no confident match. The AI only ex
 To update the vendor list: re-export from QuickBooks → run the extraction script →
 replace `TowFoundationVendors.php`. The matching logic is in `matchQbVendor()` and needs no changes.
 
-### AI category values
-The AI is prompted to return **specific expense types** — e.g. `"Dining"`, `"Travel"`,
-`"Accommodation"`, `"Transportation"`, `"Office Supplies"`, `"Entertainment"`,
-`"Professional Services"`, `"Subscriptions"`. It must not use broad accounting labels
-like `"Administrative Expenses"`.
+### AI category values and QB mapping
+The AI is prompted to return **specific expense types**. These are then mapped to the exact
+QB account string via `mapCategory()`, which loads `TowFoundationCategories.php` and does
+a case-insensitive lookup. Unmapped values are passed through as-is and logged as warnings.
+
+| AI category value | QB account string |
+|---|---|
+| `Dining` | `6640 Dining & Entertainment` |
+| `Entertainment` | `6640 Dining & Entertainment` |
+| `Travel` | `6609 Travel, conferences, meetings` |
+| `Transportation` | `6610 Travel expense` |
+| `Accommodation` / `Lodging` | `6620 Lodging` |
+| `Office Supplies` | `6751 Office supplies` |
+| `Professional Services` | `6400 Professional Fees & Consultants` |
+| `Subscriptions` | `67271 Subscriptions` |
+| `Technology` | `6710 Technology Systems Expense` |
+| `Software` | `6714 Software License Expense` |
+| `Printing` | `6722 Printing expense` |
+| `Postage` | `6721 Postage` |
+| `Membership` | `6730 Membership Dues` |
+| `Insurance` | `6740 Insurance` |
+| `Telephone` | `6755 Telephone & internet expense` |
+| `Photography` | `67241 Photography` |
+| `Board` | `6650 Board Expenses and Board Development` |
+| `Professional Development` | `6735 Staff Professional Development` |
+
+To update the mapping: edit `TowFoundationCategories.php` — keys are case-insensitive,
+values must be the exact QB account string. The AI prompt in `extractReceiptData()` lists
+the valid category names; keep them in sync with the map keys.
 
 ### Per-person constants
 `CLASS_MAP` and `PAYMENT_ACCOUNT_MAP` in `ProcessReceipts.php` map each cardholder's name
@@ -158,9 +183,13 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 - **`billingCycle` filter is suffix-match, not exact** — always pass just the date portion (`"06-03-2026"`), not the full folder name. Passing the full name (`"Amex ending in 06-03-2026"`) also works but would miss Mastercard folders.
 - **Ole Mole not in QB vendor list** — as of June 2026 this vendor is not in Tow Foundation's QuickBooks, so `qb_vendor` will be blank for Ole Mole charges until they add it to QB and the vendor list is refreshed.
 - **Duplicate detection is within-run only** — if the same receipt was processed in a prior run and archived, it won't be caught. The dedup only covers receipts present in the current run's `$pendingRenames`.
+- **Unmapped AI categories pass through** — if the AI returns a category string not in `TowFoundationCategories.php`, `mapCategory()` logs a warning and writes the raw AI string to the Excel. Check error logs after a run if the Category column looks odd; add the new value to the map file to fix it.
+- **Short vendor acronyms (< 4 chars) require whole-word match** — the substring pass uses a word-boundary regex for needles under 4 chars to avoid false positives (e.g. `"UPS"` inside `"USPS"`). If a short vendor name is not matching, check that the QB vendor list entry starts or ends with the acronym as a whole word.
+- **Archive restore script** — a one-shot CLI script `/tmp/tow_restore_archives.php` was written 2026-06-23 to move archived files back to their billing-cycle folders for reprocessing. It is not committed; re-create from the session transcript if needed. It uses the production credentials from `Config/production.ini`.
 
 ## Change history
 
+- 2026-06-23 — `TowFoundationCategories.php` added: AI category values now mapped to exact QB account strings via `mapCategory()`; `"Transportation"` → `"6610 Travel expense"` etc. (19 mappings). QB vendor substring match minimum lowered from 4 to 3 chars with whole-word boundary guard for short needles — fixes `"CVS"` → `"CVS Pharmacy"`, `"MTA"` → `"MTA Metro card"`, prevents `"UPS"` → `"USPS"` false positive. (rgirish)
 - 2026-06-18 — QB vendor matching via local fuzzy match against `TowFoundationVendors.php` (2,994 vendors); AI category prompt updated to return specific types (Dining, Travel, etc.); duplicate receipt detection added (person+date+vendor+amount dedup); `billingCycle` filter parameter added (suffix-match — card-type agnostic); person folder ` CC receipts` suffix stripped so CLASS_MAP/PAYMENT_ACCOUNT_MAP resolve correctly (rgirish)
 - 2026-06-12 — QB Excel upload moved to root-level `3. QB Excel/`; Archive/exception folders flattened (no person subfolder); unsupported mime types (`application/octet-stream`) now throw ReceiptProcessingException instead of being silently skipped (rgirish)
 - 2026-06-11 — Added CC (Magdalena), BCC (devteam@togatech.com), per-cardholder Archive subfolders, Excel upload to "3. QB Excel" SharePoint folder, two-pass rename with alphabetical duplicate suffix, rename format changed to `YYYY.MM.DD Full Name_Vendor_Amount` (rgirish)

package/package.json

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