toga-ai 1.0.175 → 1.0.177

package/CLAUDE.md

@@ -227,3 +227,74 @@ toga-harness
 ```
 
 See `package.json` for full details.
+
+## TOGA Technology Claude Harness
+
+Installed from: npm bundle v1.0.174
+
+---
+
+### Session Workflow (STRICT — follow every session)
+
+**Start of every session — run this first, no exceptions:**
+```
+/kickoff
+```
+This loads the team knowledge base, framework context, and active client config into
+Claude's context. Without it, Claude has no knowledge of TOGA patterns, the codebase
+history, or decisions made by other devs. Do not skip it.
+
+**End of every session — run this before closing:**
+```
+/capture
+```
+This saves what you learned, fixed, or decided to the shared knowledge base and
+auto-pushes it to the team git repo. Your teammates get it on their next install.
+If you close without running /capture, the knowledge is lost.
+
+**Long session checkpoint (run before switching tasks or closing mid-work):**
+```
+/session-save
+```
+
+**Resuming previous work:**
+```
+/session-resume latest
+```
+
+---
+
+### Skills & agents
+
+Your Claude Code session already lists every available `/skill` and specialist agent on each
+launch — this file intentionally does **not** duplicate that catalog (a static copy only drifts
+out of date). The rules that matter:
+
+- **`/kickoff` first, `/capture` last** — every session (see above).
+- Specialist agents (php-reviewer, sql-reviewer, framework-pattern-checker, planner,
+  knowledge-writer, session-capture, cto, cso, devops, harness-optimizer) fire **automatically**
+  on the matching file or operation. You can also invoke one explicitly — e.g. "use the
+  php-reviewer agent on this file."
+
+---
+
+### Knowledge Base
+
+Team knowledge lives in `.claude/knowledge/`. It is seeded from the npm bundle
+and grows every time any developer runs `/capture`.
+
+- Search it: `node .claude/knowledge.js search --q="payments"`
+- Validate it: `node .claude/knowledge.js validate`
+- Re-index it: `node .claude/knowledge.js index`
+
+Every time you edit a file inside `.claude/knowledge/`, the post-edit-validate
+hook runs automatically and warns you of any frontmatter or schema errors.
+
+---
+
+### Updating
+
+Pull latest skills, agents, and knowledge from the team repo:
+```
+npx toga-ai
+```

package/agents/sql-reviewer.md

@@ -1,53 +1,122 @@
 ---
 name: sql-reviewer
-description: TOGA SQL reviewer — uses ecc:database-reviewer for deep query analysis (injection, N+1, schema, indexes), enhanced with TOGA framework DB layer patterns (App_Db vs _Db abstraction, queue payload size constraints).
+description: TOGA SQL/schema reviewer — uses ecc:database-reviewer for deep query analysis (injection, N+1, indexes), enhanced with the ACTUAL TOGA framework DB conventions for both frameworks (1.0 App_Database/App_Model on mysqli vs 2.0 _Database/_Model), enforcing the knowledge/{1.0,2.0}/standards SQL rules exactly — naming, table design, collation, field types, and escaping discipline.
 model: sonnet
 tools: Read, Grep, Glob, Bash, Agent
 ---
 
-# TOGA SQL Reviewer
+# TOGA SQL / Schema Reviewer
 
-Deep SQL quality and security reviewer combining ECC's database expertise with TOGA framework DB layer knowledge.
+Deep SQL quality and security reviewer combining ECC's database expertise with the TOGA
+framework DB conventions. **This agent enforces the team's published standards verbatim** —
+not a generic ORM model. The two frameworks have materially different DB layers and schema
+rules; getting the framework wrong produces false positives and missed violations, so
+**identify the framework first** and apply only that framework's rules.
 
-## Step 1 — Identify framework DB layer
+Authoritative sources (read the relevant one when a call is borderline — do not guess):
+- 1.0: `knowledge/1.0/standards/backend-php.md`, `knowledge/1.0/standards/framework-rules.md`
+- 2.0: `knowledge/2.0/standards/backend-php.md`, `knowledge/2.0/standards/framework-rules.md`
 
-Determine which abstraction layer is in use:
+## Step 1 — Identify the framework and its DB layer
 
-**Framework 1.0 (App_):** `App_Db::query()`, `App_Db::select()`, `App_Db::insert()`, `App_Db::update()`
-**Framework 2.0 (_underscore):** `_Db::select()`, `_Db::insert()`, `_Db::update()`, `_Db::delete()`
+Determine framework from the class prefix / repo (look it up in `registry.json` if unsure):
 
-Flag any raw `mysqli_*` or deprecated `mysql_*` calls as CRITICAL regardless of framework.
+**Framework 1.0 — `App_` (repos: `library`, `worker`)**
+- Raw queries: `App_Database::query($sql, $linkRegistryString)` — a **static wrapper over mysqli**, with result caching. NOT PDO, NOT prepared statements.
+- Reads: `App_Database::fetchRow()`, `fetchOne()`, `numRows()`. Writes: `affectedRows()`, `getInsertId()`.
+- Cached lookups: `App_Database::lookupField()`, `lookupRecord()` (the latter uses `SELECT *` internally **by design** — do not flag it).
+- Escaping: `App_Database::sqlEscape()` (safe interpolation) and `App_Database::sqlProtect()` (lossy strip-filter for free-form search only). In `browser/` action files, `getVarEscaped('field')` wraps `sqlEscape()`.
+- ORM: `App_Model` subclasses under `app/model/`, columns declared as `FIELDTYPE_*` constants.
 
-## Step 2 — Delegate to ECC database-reviewer
+**Framework 2.0 — `_underscore` (repos: `_underscore`, `worker2`, `api2`)**
+- Escaping: `_Database::escape()` (safe interpolation) and `_Database::protect()` (lossy strip-filter for free-form search only).
+- Built-in query-result cache enabled by default; `_Database::useQueryCache(false)` for guaranteed-fresh reads after a write.
+- ORM: `_Model` subclasses, columns declared as `FIELD_*` constants; load via `$model->load()`.
+- Background work goes through `_Worker::runTask()` / the queue — never inline.
 
-Spawn the `ecc:database-reviewer` agent with this TOGA context:
+> **Do not invent an API.** There is no `App_Db`/`_Db` class and no `::select()/::insert()/::update()/::delete()` query-builder in either standard. If you see real code using a helper not documented here, read the standards doc before judging it.
+
+**Always CRITICAL, any framework:** raw `mysql_*` calls (removed in PHP 7), and any user input concatenated/interpolated into a SQL string without `sqlEscape()` / `_Database::escape()` (or the model layer).
+
+## Step 2 — Delegate deep analysis to ECC database-reviewer
+
+Spawn the `ecc:database-reviewer` agent with the framework-correct context:
 
 ```
-TOGA CONTEXT:
-Framework DB layer: <App_Db | _Db> — custom wrappers, not Eloquent/Laravel.
+TOGA CONTEXT — framework <1.0 | 2.0>:
+DB layer is a custom mysqli wrapper (<App_Database | _Database>), NOT Eloquent/Laravel and NOT PDO/prepared statements. Escaping discipline at the call site is the injection control.
 Pay special attention to:
-- String concatenation or interpolation into _Db::query() or App_Db::query() calls
-- _Db::select() / App_Db::select() calls without a WHERE condition on mutable tables
-- Any loop containing a _Db:: or App_Db:: call (N+1 pattern)
-- Missing LIMIT on SELECT from order/item/fulfillment tables (can be millions of rows)
+- User input interpolated into a hand-written SQL string WITHOUT <App_Database::sqlEscape() | _Database::escape()> → injection (CRITICAL)
+- Use of <sqlProtect() | _Database::protect()> on values meant to be stored intact (it strips % \ / * " ' and " or") → data corruption
+- SELECT * appearing in feature code (allowed only in the framework's own lookupRecord helper)
+- Any <App_Database:: | _Database::> call inside a loop where a loop variable feeds the WHERE → N+1
+- Missing LIMIT on SELECT from large tables (orders/items/fulfillment can be millions of rows)
+- Missing index support for the WHERE/JOIN columns
 ```
 
-## Step 3 — TOGA-specific SQL checks
+Maker ≠ checker: do not let the agent that wrote the SQL review it.
+
+## Step 3 — TOGA standards enforcement (apply ONLY the in-scope framework)
+
+### 3a. SQL injection & escaping (both frameworks)
+- Raw user input in a query string with no escaping and no model layer → **CRITICAL**.
+- `sqlProtect()` / `_Database::protect()` used to "escape" a value that is then stored → **WARNING** (lossy; corrupts data). It is only for sanitizing free-form search input.
+- Prefer the model layer (`App_Model` / `_Model`) over hand-written SQL — note it as **INFO** when hand-written SQL could have used the model.
+
+### 3b. SQL formatting (both frameworks — shared rules)
+- All SQL keywords UPPERCASE (`SELECT`, `FROM`, `INNER JOIN`, `WHERE`, `AND`, `ORDER BY`, `LIMIT`, …).
+- Tabs for indentation; each clause on its own line; a line break after each comma in the SELECT list.
+- SQL embedded in PHP: opening/closing quotes on their own lines, query indented.
+- `INNER JOIN`s before outer joins; prefer `LEFT OUTER JOIN` over `RIGHT OUTER JOIN`; each JOIN on its own line.
+- Mixing `AND` and `OR` **requires parentheses**; `AND`/`OR` start a new line; spaces around operators.
+- Subqueries parenthesized, on a new line, indented.
+- Prefer `#` over `--` for SQL comments. → formatting issues are **INFO/WARNING**, not CRITICAL.
+
+### 3c. SQL naming (both frameworks — shared, strictly enforced)
+- Databases PascalCase/formal name; **tables PascalCase**; **fields camelCase**.
+- Foreign keys: referenced table → singular → append `Id`, camelCase (`PurchaseOrders` → `purchaseOrderId`). Flag `PurchaseOrdersId`, `purchase_order_id`, etc.
+- Human-readable field must be `name` — never `label`, `type`, `displayName`, `niceName`, `companyName`.
+- Bridge tables: parent first, underscore-joined, plurals aligned with real table names (`Locations_LocationAttributes`).
+- Boolean/flag fields begin with `is` (`isVisible`) and are `UNSIGNED TINYINT`.
+- PK/FK columns must be **UNSIGNED** integers.
 
-After ECC's findings, add these TOGA-specific patterns:
-- `_Db::update()` or `App_Db::update()` without a condition array → CRITICAL (table wipe)
-- `_Db::delete()` without WHERE → CRITICAL
-- SQS/queue job payloads containing full DB row data → WARNING (use ID only, fetch in worker)
-- Queries inside `foreach` loops where loop variable appears in WHERE → CRITICAL N+1
+### 3d. Table design — **DIVERGES by framework** (most common false-positive source)
+
+| Rule | 1.0 (`App_` / legacy) | 2.0 (`_underscore`) |
+|---|---|---|
+| Primary key | `id` UNSIGNED AUTO_INCREMENT, first column | same |
+| Second column | **NO `uuid` column** — do not add one | **`uuid` mandatory**, second column, from `_String::generateUuid()` (never MySQL `UUID()`) |
+| Custom fields | **NO `c_` prefix block** | client custom fields prefixed `c_`, camelCase after, at end of table |
+| Collation | **`latin1_swedish_ci`** — match the tables you JOIN against; do NOT introduce `utf8mb4` into a legacy schema | **`utf8mb4` / `utf8mb4_0900_ai_ci`** required |
+| Engine | InnoDB | InnoDB |
+| Table/field comments | rarely present; encouraged but not enforced | **required**, short & descriptive; `id`/`uuid`/FK comments have mandated formats; don't begin with "The" |
+| Datetime field prefix | legacy uses `dt` prefix (`dtCreated`, `dtUpdated`) | no `dt` prefix |
+| Field-type constants | `FIELDTYPE_*` (e.g. `FIELDTYPE_PRIMARYKEY`) | `FIELD_*` (e.g. `FIELD_PRIMARYKEY`) |
+
+→ **Flag a `uuid` column, `c_` field, or `utf8mb4` collation added to a 1.0 table** as a standards violation. **Flag a missing `uuid`, missing comments, or `latin1` collation in a 2.0 table** as a violation. Applying the wrong framework's table rules is itself the error to avoid.
+
+2.0 varchar sizing: max 255 then switch to TEXT; allocate in binary intervals (1, 2, 4, 8, 16, 32, 64, 128, 255).
+
+### 3e. Destructive-operation safety (both frameworks)
+- Hand-written `UPDATE`/`DELETE` with no `WHERE`, or a model bulk operation with no condition → **CRITICAL** (table wipe).
+- SELECT from a large table with no `LIMIT` where pagination is expected → **WARNING**.
+
+### 3f. 2.0-only checks
+- Long-running/background DB work inline in a request instead of dispatched via `_Worker::runTask()` → **WARNING**.
+- Reliance on stale cached reads immediately after a write without `_Database::useQueryCache(false)` → **WARNING**.
 
 ## Output format
 
 ```
-## SQL Review — <filename>
-Framework: <1.0 | 2.0> | DB layer: <App_Db | _Db>
+## SQL / Schema Review — <filename>
+Framework: <1.0 | 2.0> | DB layer: <App_Database / App_Model | _Database / _Model>
 
-| File:Line | Severity | Issue | Fix |
-|-----------|----------|-------|-----|
+| File:Line | Severity | Standard | Issue | Fix |
+|-----------|----------|----------|-------|-----|
 
 **Summary:** X critical, Y warnings, Z info
+Verdict: <SAFE TO MERGE | FIX REQUIRED | BLOCK>
 ```
+
+`Standard` cites the rule (e.g. "1.0 §SQL Injection Prevention", "2.0 §UUIDs", "shared §Naming/FK").
+Report only what you can ground in the standards above or the source files — no speculative findings.

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

@@ -2,3 +2,4 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [Bundle Confirmation — Cart Preservation When Adding Add-On Services](features/bundleconfirmation-cart-preservation.md) | Fix: adding any add-on service (Data Transfer, Promotional Bundle, New PC Services, etc.) was silently removing the 1-year tech support SKU from the cart. | toga/app/togarefresh2026/servicerequests/bundleconfirmation.php |

package/knowledge/1.0/apps/toga/features/bundleconfirmation-cart-preservation.md

@@ -0,0 +1,68 @@
+---
+title: Bundle Confirmation — Cart Preservation When Adding Add-On Services
+framework: "1.0"
+repo: toga
+project: TOGa
+client: office-depot
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - toga/app/togarefresh2026/servicerequests/bundleconfirmation.php
+related:
+  - ../../../clients/office-depot/features/togarefresh2026-linkbuilder-routing.md
+---
+
+## Summary
+Fix: adding any add-on service (Data Transfer, Promotional Bundle, New PC Services, etc.)
+was silently removing the 1-year tech support SKU from the cart. The `?services=` block in
+`bundleconfirmation.php` now only strips tech support when the service being added IS itself
+a tech support plan.
+
+## Key files / entry points
+- `toga/app/togarefresh2026/servicerequests/bundleconfirmation.php` — the `$_GET['services']`
+  block (lines ~118–150) is the only place this logic lives.
+
+## How it works
+Two callers pass `?services=` to `bundleconfirmation.php`:
+
+| Caller | Service IDs passed | Expected behavior |
+|---|---|---|
+| `techsupport.php` (lines 88, 120, 152) | 194, 195, 101900 (tech support plans) | Remove old tech support, add new, set session vars |
+| `additionalservices.php` (lines 277, 288) | Add-on IDs (categories 174, 175, 178, 179) | Append to cart only — never touch existing items |
+
+The fixed block:
+```php
+if (in_array($serviceID, $techSupportServiceIds)) {
+    // Replacing tech support — remove the old plan before adding the new selection
+    $_SESSION['cartProducts'] = array_values(array_filter(...));
+    $_SESSION['techSupportServiceId'] = $serviceID;
+    $_SESSION['selectedJobJacket'] = 2;
+}
+if (!in_array($serviceID, $_SESSION['cartProducts'])) {
+    $_SESSION['cartProducts'][] = $serviceID;
+}
+```
+
+## Data model
+Session vars touched:
+- `$_SESSION['cartProducts']` — array of service IDs in the quote
+- `$_SESSION['techSupportServiceId']` — ID of the selected tech support plan
+- `$_SESSION['selectedJobJacket']` — job jacket type (2 = tech support flow)
+
+## Gotchas / known issues
+- The old code also called `unset($_SESSION['techSupportServiceId'])` for every add-on.
+  This was also a bug — it would flip `$isTechSupportFlow` (line ~296) to false mid-session
+  even when tech support was still in the cart. The fix leaves the var alone for add-ons.
+- Four total `cartProducts` removal points exist in the 2026 service request flow. The other
+  three are all safe: McAfee replacement (`bundleconfirmation.php:103`, removes only the
+  prior McAfee ID), and two empty-value cleanups (lines ~641 and `mcafeeupdates.php:453`).
+- `$techSupportServiceIds = [194, 195, 101900]` — if a new tech support SKU is introduced,
+  this array must be updated or the new plan will be treated as an add-on (won't replace old).
+
+## Related docs
+- `clients/office-depot/features/togarefresh2026-linkbuilder-routing.md`
+
+## Change history
+- 2026-06-23 — Bug fix: add-on services no longer strip tech support from cart. (snaredla)

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

@@ -13,3 +13,4 @@
 | [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 |
+| [WJE Freshservice Sync (worker2)](features/wje-freshservice-sync.md) | WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose tickets, contacts, assets, groups, categories, and canned res | worker2/Worker/Wje.php, _underscore/Component/Api/Wje/Wje.php, _underscore/Model/Wje/Ticket.php, _underscore/Model/Wje/TicketNote.php, _underscore/Model/Wje/Contact.php, _underscore/Model/Wje/Unit.php, _underscore/Model/Wje/TicketTeam.php, _underscore/Model/Wje/TicketCategory.php, _underscore/Model/Wje/AssetType.php, _underscore/Model/Wje/PredefinedReply.php, library/app/api/wje.php, worker/crons/toga2/wje/import_supporting_records.php, worker/crons/toga2/wje/sync_togasupply_wje.php, worker/crons/notifications/reports/wje/wje_common.php, library/app/systemmonitor/wje.php, dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql |

package/knowledge/2.0/apps/worker2/features/wje-freshservice-sync.md

@@ -0,0 +1,143 @@
+---
+title: WJE Freshservice Sync (worker2)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: wje
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: ["snaredla"]
+files:
+  - worker2/Worker/Wje.php
+  - _underscore/Component/Api/Wje/Wje.php
+  - _underscore/Model/Wje/Ticket.php
+  - _underscore/Model/Wje/TicketNote.php
+  - _underscore/Model/Wje/Contact.php
+  - _underscore/Model/Wje/Unit.php
+  - _underscore/Model/Wje/TicketTeam.php
+  - _underscore/Model/Wje/TicketCategory.php
+  - _underscore/Model/Wje/AssetType.php
+  - _underscore/Model/Wje/PredefinedReply.php
+  - library/app/api/wje.php
+  - worker/crons/toga2/wje/import_supporting_records.php
+  - worker/crons/toga2/wje/sync_togasupply_wje.php
+  - worker/crons/notifications/reports/wje/wje_common.php
+  - library/app/systemmonitor/wje.php
+  - dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql
+related:
+  - clients/wje/profile.md
+  - 2.0/apps/worker2/features/elite-freshservice-sync.md
+  - 1.0/apps/library/features/toga2-api-client-and-bridge.md
+  - 2.0/apps/worker2/features/startech-webhook-handler.md
+---
+
+## Summary
+
+WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose
+tickets, contacts, assets, groups, categories, and canned responses are synced into TOGA. Unlike
+Startech (multi-client, resolved dynamically by `company_id`), **WJE is a single hardcoded client** —
+its IDs and credentials are baked into the integration files.
+
+Data reaches TOGA two ways: a **real-time Freshservice webhook** handled by `_Worker_Wje::Webhook`, and
+a **daily batch import** of supporting records. A separate 2-minute cron bridges Toga2 ↔ TOGaDesk (see
+`clients/wje/profile.md`).
+
+## Key files / entry points
+
+- **Webhook handler:** `worker2/Worker/Wje.php` — `abstract _Worker_Wje`, entry `Webhook($payload, $headers)`.
+  Reached via `webhook.togahub.com/wje` → WebhookIngestion Lambda → `Core.WorkerJobs` action `Wje/Webhook`
+  → SQS → EB worker.
+- **API clients (two parallel, same creds):** `_Component_Api_Wje` (`_underscore/Component/Api/Wje/Wje.php`,
+  used by worker2/2.0) and `App_Api_Wje extends App_Api` (`library/app/api/wje.php`, used by 1.0 crons).
+  Both hit `https://wje.freshservice.com` with basic auth; `send($method, $route, $payload)`, 90s timeout,
+  1s sleep between calls. **Production only — no test/stage Freshservice instance.**
+- **Crons (worker 1.0):** `crons/toga2/wje/import_supporting_records.php` (daily import),
+  `crons/toga2/wje/sync_togasupply_wje.php` (2-min Togadesk bridge),
+  `crons/notifications/reports/wje/{wje_monthly_report,wje_quarterly_report,wje_common}.php`.
+- **Models:** `_underscore/Model/Wje/*` (8 classes, see Data model).
+- **Monitoring:** `library/app/systemmonitor/wje.php` (`App_SystemMonitor_WJE`).
+
+## How it works
+
+### Real-time webhook (`_Worker_Wje::Webhook`)
+1. Payload arrives JSON-wrapped under `freshdesk_webhook` (it is Freshservice despite the name):
+   `$wjeRecord = (object)((object)json_decode($payload, true))->freshdesk_webhook;`
+2. Branches on shape: **ticket** webhook if `property_exists($wjeRecord, 'ticket_id')`; **asset** webhook
+   if `property_exists($wjeRecord, 'asset_display_id')`.
+3. **Ticket path:** upserts associated assets (`associated_asset_ids`), the requester contact
+   (`requester_id`), and the agent contact (`agent_id`). Sleeps a few seconds to dodge duplicate-ticket
+   races, then **re-fetches the full ticket** from WJE `/tickets/{id_numeric}` (the webhook body omits
+   `group_id` and category detail). Resolves the category/subcategory/item hierarchy by **name** against
+   TOGA `TicketCategories`. Upserts the ticket (by `c_wjeTicketId`) and syncs conversation notes from
+   `/tickets/{id}/conversations` (by `c_wjeConversationId`).
+4. **Asset path:** upserts the unit by asset tag `ASSET-{display_id}`, matches the contact by email when
+   `c_wjeUserId` is unavailable, and updates serial/tag/type/contact custom fields.
+
+### Daily import (`import_supporting_records.php`)
+Canned responses → `PredefinedReplies` (`c_wjeCannedResponseId`); requesters → `Contacts` (`c_wjeUserId`);
+assets → `Units` (`c_wjeAssetId`, tag `ASSET-{id}`); groups → `TicketTeams` (`c_wjeGroupId`);
+`ticket_form_fields` (field `13000126389`) → `TicketCategories` (`c_wjeCategoryId`, 3-level hierarchy).
+
+### Reports & monitoring
+`wje_common.php::generateWJEReport(...)` builds Excel metrics (SLA, first-response, resolution, reopens)
+via PhpSpreadsheet for client 153 / dept 269; monthly cron emails `serviceops@togatech.com` +
+`mhicks@togatech.com`. `App_SystemMonitor_WJE` checks every 5 min (300s window, 30-min reminders) and
+alerts `devteam@togatech.com` on Freshservice/webhook responses > 300, reading both Logs 1.0 (`API`) and
+Logs 2.0 (`Api` in `db_prod_logs_wje`).
+
+## Data model
+
+Models in `_underscore/Model/Wje/` extend the base `_Model_Client_*` and add WJE linkage fields
+(all `self::FIELD_CHAR`):
+
+| Model | Custom field(s) |
+|-------|-----------------|
+| `_Model_Wje_Ticket` | `c_wjeTicketId`, `c_wjeAgentId` |
+| `_Model_Wje_TicketNote` | `c_wjeConversationId` (unique in DB) |
+| `_Model_Wje_Contact` | `c_wjeUserId` |
+| `_Model_Wje_Unit` | `c_wjeAssetId` |
+| `_Model_Wje_TicketTeam` | `c_wjeGroupId` |
+| `_Model_Wje_TicketCategory` | `c_wjeCategoryId` |
+| `_Model_Wje_AssetType` | `c_wjeAssetTypeId` |
+| `_Model_Wje_PredefinedReply` | `c_wjeCannedResponseId` |
+
+Schema in `dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql` (+ `2024-10-23.sql`, `2024-10-25.sql`):
+API record, the `c_wje*` CustomRecordFields, TicketStages (Open=2, Pending=3, Resolved=4, Closed=5),
+asset type "Laptop", urgencies (Low/Normal/High/Critical), system params
+`TOGADESK_LAST_TICKET_INTEGRATION_DATETIME` / `TOGA_LAST_TICKET_INTEGRATION_DATETIME`.
+
+Hardcoded IDs: `CLIENT_UUID_WJE=c2f5180f-…`, `API_UUID_WJE=4750650f-…` (and `API_SECRET_WJE`) in
+`worker2/Worker/Wje.php`; TOGaDesk client `153`, dept `269` (internal `290`); default group
+`13000155420` / agent `13000771757`; category form field `13000126389`.
+
+## Client variations
+
+WJE-specific: single hardcoded tenant (no `company_id` resolution); requires a group on every ticket and
+falls back to the default group/agent when none is assigned. Sister Freshservice client **Elite** uses a
+parallel but separate `_Worker_Elite` handler — see related doc.
+
+## Gotchas / known issues
+
+- **W1** Payload is wrapped under `freshdesk_webhook`, not top-level. Decode with `json_decode($p, true)` then cast.
+- **W2** Webhook body is thin — `ticket_category`/`group_id` often null; the handler re-fetches `/tickets/{id_numeric}`. Don't trust the webhook body for category/group.
+- **W3** Two id forms: `ticket_id` (string "INC-46687", stored in `c_wjeTicketId`) vs `id_numeric` (46687, used in API calls). Mixing them → 404s / missed matches.
+- **W4** Webhook resolves category by **name** against TOGA `TicketCategories`; the **daily import** is what populates `c_wjeCategoryId`. A WJE rename before the import runs breaks name matching — check the import cron first.
+- **W5** Units keyed by asset tag `ASSET-{display_id}`, linked via `c_wjeAssetId`; asset webhook falls back to email matching when `c_wjeUserId` is absent.
+- **W6** Asset import catches per-asset errors and continues; if WJE revokes `/assets` API access it silently skips assets — check logs.
+- **W7** `c_wjeUserId` is the source of truth for contact identity; email is only opportunistically added.
+- **W8** `_Component_Api_Wje` is production-only — local testing hits production WJE; be careful with writes.
+- **W9** Credentials are duplicated in `_Component_Api_Wje` and `App_Api_Wje` — rotate **both**.
+- **W10** Lazy-transaction rule: write back `c_wje*` identifiers via direct model `->save()`, not an internal API round trip inside an open transaction (cf. Startech G4).
+- **W11** `json_decode($s, true)` + top-level `(object)` cast leaves nested fields as arrays — cast each level you traverse.
+- **W12** TicketStages use Freshservice status codes (Open=2 … Closed=5); status sync depends on those matching live Freshservice statuses.
+
+> Secrets (`API_SECRET_WJE`, the Freshservice password) are hardcoded in source — read them from the file
+> when needed; never copy the values into docs or commits.
+
+## Related docs
+
+- `clients/wje/profile.md` — WJE client profile + the 2-min Togadesk bridge sync.
+- `2.0/apps/worker2/features/elite-freshservice-sync.md` — sister Freshservice client.
+- `2.0/apps/worker2/features/startech-webhook-handler.md` — the multi-client webhook pattern WJE predates.
+- `1.0/apps/library/features/toga2-api-client-and-bridge.md` — `App_Api_Toga2::syncWithTogadesk`.

package/knowledge/INDEX.md

@@ -11,12 +11,12 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
-- **toga** (TOGa) — 1 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
+- **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 11 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 12 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 5 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 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/wje/INDEX.md

@@ -2,4 +2,4 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Wiss, Janney, Elstner Associates, Inc.](profile.md) | 2.0 | Wiss, Janney, Elstner Associates, Inc. | worker/crons/toga2/wje/sync_togasupply_wje.php |
+| [Wiss, Janney, Elstner Associates, Inc.](profile.md) | 2.0 | Wiss, Janney, Elstner Associates, Inc. | worker/crons/toga2/wje/sync_togasupply_wje.php, worker2/Worker/Wje.php, worker/crons/toga2/wje/import_supporting_records.php |

package/knowledge/clients/wje/profile.md

@@ -12,19 +12,33 @@ updated: 2026-06-23
 owners: [jcardinal]
 files:
   - worker/crons/toga2/wje/sync_togasupply_wje.php
+  - worker2/Worker/Wje.php
+  - worker/crons/toga2/wje/import_supporting_records.php
 related:
   - ../../1.0/apps/library/features/toga2-api-client-and-bridge.md
+  - ../../2.0/apps/worker2/features/wje-freshservice-sync.md
 ---
 
 ## Summary
 
-Wiss, Janney, Elstner Associates, Inc. (WJE) is a TOGa Desk client integrated through the
-**1.0↔2.0 TOGaDesk bridge** (`App_Api_Toga2::syncWithTogadesk`). The cron
-`worker/crons/toga2/wje/sync_togasupply_wje.php` runs every 2 minutes and enables the **full**
-set of bridge sub-syncs (tickets both directions, ticket-notes, contacts→people, items/units→
-assets, predefined-replies, ticket-teams→groups, ticket-categories) for TOGaDesk client id 153,
-department 269 (plus internal-tickets department 290). WJE requires a group on every ticket and
-falls back to a default group/agent when none is assigned.
+Wiss, Janney, Elstner Associates, Inc. (WJE — "WJE IT") is a **Freshservice**-based help-desk
+client (`wje.freshservice.com`). It is a **single hardcoded tenant** (no dynamic `company_id`
+resolution). Data moves between WJE and TOGA on three paths:
 
-See the bridge feature doc for the mechanism. No NetSuite TOGa Supply importer runs for WJE
-(it is a help-desk integration, not a supply/procurement client).
+1. **Real-time Freshservice webhook** → `_Worker_Wje::Webhook` (worker2) — creates/updates tickets,
+   contacts, assets, groups, categories, and conversation notes, keyed by `c_wje*` custom fields.
+2. **Daily batch import** (`worker/crons/toga2/wje/import_supporting_records.php`) — imports canned
+   responses, requesters, assets, groups, and the 3-level category hierarchy.
+3. **2-minute TOGaDesk bridge** (`App_Api_Toga2::syncWithTogadesk`) — the cron
+   `worker/crons/toga2/wje/sync_togasupply_wje.php` enables the **full** set of bridge sub-syncs
+   (tickets both directions, ticket-notes, contacts→people, items/units→assets, predefined-replies,
+   ticket-teams→groups, ticket-categories) for TOGaDesk client id 153, department 269 (plus
+   internal-tickets department 290).
+
+WJE requires a group on every ticket and falls back to a default group/agent (`13000155420` /
+`13000771757`) when none is assigned. No NetSuite TOGa Supply importer runs for WJE (it is a
+help-desk integration, not a supply/procurement client).
+
+See **`2.0/apps/worker2/features/wje-freshservice-sync.md`** for the full integration (webhook
+handler, import cron, `c_wje*` models, API clients, schema, reports, monitoring, and gotchas), and
+the bridge feature doc for the `syncWithTogadesk` mechanism.

package/package.json

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