toga-ai 1.0.136 → 1.0.138

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

@@ -4,5 +4,6 @@
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
 | [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 |
 | [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 |

package/knowledge/1.0/apps/library/features/email-templates.md

@@ -0,0 +1,115 @@
+---
+title: Branded HTML Email Templates (App_Email_Template)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["mhammontree"]
+files:
+  - library/app/email/template.php
+  - library/app/email/agilant.php
+related:
+  - ../architecture.md
+---
+
+## Summary
+
+`App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in
+the 1.0 (`App_`) framework. Brand-specific subclasses under `app/email/` (e.g.
+`App_Email_Agilant`, `App_Email_Dukefarms`, `App_Email_Hartreepartners`) set a handful of
+brand properties in their constructor; the base `renderHtml()` assembles the full email
+(header bar + body + footer bar). Because it lives in `library` **core**, any change here ships
+to **every 1.0 app that sends these emails** (worker crons, togadesk, etc.) — verify across
+apps, not just one.
+
+`App_Email_Agilant` is the **default TOGA Technology brand** despite its legacy class name —
+it sends as `TOGA Technology <noreply@togatech.com>`.
+
+## Key files / entry points
+
+- `app/email/template.php` — `App_Email_Template extends App_Email`. Owns the brand properties
+  and `renderHtml()` (the whole email markup) and `send()`.
+- `app/email/agilant.php` — `App_Email_Agilant extends App_Email_Template`. The TOGA-branded
+  defaults. Other brand subclasses follow the same shape.
+
+## How it works
+
+A subclass sets brand properties in its constructor; `send()` calls `renderHtml()` (when
+`sendWithTemplate` is on) to build the body, then defers to `App_Email::send()`.
+
+Properties consumed by `renderHtml()`:
+
+- `companyName` — used as the footer logo `alt`.
+- `primaryColorHex`, `gradientColorA`, `gradientColorB` — header/footer colors.
+- `logoImageUrl` — the **footer** logo image (rendered at 35×35 in the footer gradient bar).
+  If empty, no footer bar renders.
+- `logoLinkToUrl` — href wrapping the footer logo.
+- `includeHeader` — toggles the header bar.
+- `heroImageUrl`, `heroHeight` — optional hero (set via `App_Email_Template`; see DEV-2094).
+
+`renderHtml()` builds three rows in a 600px table:
+1. **Header bar** — a gradient `<td>` whose CSS `background-image` layers the brand line-art
+   (`TOGA-TECHNOLOGY-Header-Logo-Vector.png`) over a `linear-gradient`, with the email
+   **subject** centered in white as the heading.
+2. **Body** — `getBody()` inside a white content cell.
+3. **Footer bar** — a gradient `<td>` containing only the `logoImageUrl` (linked to
+   `logoLinkToUrl`).
+
+## Data model
+
+None — pure presentation. Brand values are hardcoded in each subclass constructor.
+
+## Client variations
+
+One subclass per brand under `app/email/`. They differ only in the brand properties above
+(colors, logo URLs, sender). Some client emails (e.g. `toga.php`, `officedepot.php`) instead
+pull a per-client logo from the client's `logoDocumentId` rather than a static URL.
+
+## Brand assets (TOGA Technology rebrand)
+
+- Header line-art (full-bleed background pattern, blue on transparent):
+  `https://common-host.s3.us-west-2.amazonaws.com/logos/TOGA-TECHNOLOGY-Header-Logo-Vector.png`
+- Footer symbol (white-on-transparent, 35×36 — shows on the dark gradient footer bar):
+  `https://common-host.s3.us-west-2.amazonaws.com/logos/TOGA-TECHNOLOGY-Logo-Symbol.png`
+
+Note the host is `s3.us-west-2` (dot), not the older `s3-us-west-2` (hyphen) used by the
+retired Agilant assets.
+
+## Gotchas / known issues
+
+- **New Outlook double-renders a cell that has BOTH a `background="…"` HTML attribute and a CSS
+  `background-image`.** It paints the attribute image (native size, top-left) *and* the CSS
+  `cover` image (offset) — producing a duplicated, shifted header bar with the title spilling
+  out. Fix: drive backgrounds from **CSS only** on the cell (and VML for classic Outlook if you
+  need the gradient there). Do not set the legacy `background=` attribute alongside CSS.
+- **No VML fallback in the current header/footer** — classic desktop Outlook (the Word engine)
+  can't render CSS gradients/background-images, so it falls back to the solid `bgcolor`
+  (`#2B47AD`) + white text (no gradient, no line-art). Acceptable, just flatter. Add a VML
+  `v:rect`/`v:fill` block if the gradient/line-art must appear in classic Outlook.
+- **Footer logo must be light/white on transparent** — it sits on the dark blue gradient bar.
+  A dark logo disappears.
+- **`footerText` and `socialMediaImageUrlsToLinks` are vestigial.** The properties still exist
+  on `App_Email_Template`, but the simplified `renderHtml()` (TRUE-79240) no longer renders
+  them — the footer is **logo-only**. Setting them has no effect; older subclasses may still
+  assign them harmlessly.
+- **Verifying a fix:** these emails are sent by deployed code, so an email already in someone's
+  inbox reflects the code that was live when it was sent. Confirm a template change with a
+  **fresh send after deploy**, viewed across new Outlook / classic Outlook / Gmail / Apple Mail
+  — not against a pre-deploy message.
+
+## Change history
+
+- 2026-06-18 — Header double-render fix: removed the redundant `background="…vector.png"`
+  attribute from the header cell (new Outlook was painting it twice, offset from the CSS
+  background). CSS-only backgrounds now. (mhammontree)
+- 2026-06-18 — TRUE-79240: rebranded `App_Email_Agilant` footer to TOGA — `logoImageUrl` →
+  `TOGA-TECHNOLOGY-Logo-Symbol.png`, `logoLinkToUrl` → `https://togatech.com`; removed the
+  Agilant footer address text and social-media icons (footer is logo-only per Figma).
+  (mhammontree)
+
+## Related docs
+
+- [Library Architecture](../architecture.md)

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

@@ -8,5 +8,5 @@
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [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, worker/crons/toga2/forecast2/import_open_orders.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, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.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 |

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-open-orders-sync.md

@@ -6,12 +6,16 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-17
+updated: 2026-06-18
 owners: ["dfranks"]
 files:
   - 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
   - worker/crons/toga2/forecast2/import_open_orders.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
@@ -77,6 +81,25 @@ None — uniform (platform-wide Forecast2 sync).
 
 ## Gotchas / known issues
 
+- **Async-recalc race → a transiently-empty REST read PURGES a genuinely-open order (silent data loss).**
+  The open-status gate is not the only way rows get deleted: on an **open** order, if the REST GET
+  momentarily returns **zero importable open lines**, `syncOpenLines` runs its reconcile-delete with an
+  empty kept-set and wipes every existing row — there is no separate "removeAll", but the effect is the
+  same. This fires when NetSuite's own **asynchronous `-System-` line recompute** (e.g. the open
+  gross-profit pass, `CUSTCOL_OPEN_GP`) is still in flight at the instant the webhook's REST GET runs —
+  the record reads back open but with its open lines not yet materialized. The webhook is often *triggered
+  by that very recompute*, so the GET races it. **Confirmed live 2026-06-18 on SO 7151688** (tranId
+  279345): 4 edit webhooks at 14:02:35–48 CDT all succeeded with **0 rows**, while NetSuite's `-System-`
+  open-GP recompute wrote the line values at the same 14:02:30–45 window (NS Eastern = worker Central +1h).
+  A manual re-sync 22 min later imported all 4 lines correctly. Nothing self-heals it — there is no retry,
+  and the batch cron is being decommissioned. **Fix direction (not yet implemented):** never let "open
+  status + zero importable lines" trigger a destructive delete — re-fetch after a short delay, or treat it
+  as retryable (`throw` → `isSuccess=0` → re-runs) — and only let a **confidently-closed** status
+  (Billed / Closed / Cancelled) purge. Diagnose with `check_so_history.php` (systemnote status timeline)
+  + `check_so_status.php` (current REST status) + `probe_so_rest_lines.php` (REST `item.items` as the
+  handler sees them). NB: `App_ApiTransaction::execute(false)` returns a raw JSON **string** for a record
+  GET — `json_decode` it directly; double-encoding it (`json_decode(json_encode($resp))`) silently yields
+  an empty object and a false "empty record" reading.
 - **REST shape ≠ SOAP shape.** The cron reads the SOAP-shim shape; this handler reads the REST record
   (`status->refName`, line `quantityBilled`, `class->refName`, `entity->id`, `salesRep->id`,
   `shippingCost`). Verified against live orders via `test/@dave/probe_salesorder_rest_shape.php`.
@@ -131,6 +154,15 @@ and are a candidate to extract into a shared `_Component_Forecast_Db` before the
 
 ## Change history
 
+- 2026-06-18 — **Verified live in production** after the SalesOrder enqueuer left Testing. 14 orders
+  reconciled against NetSuite SuiteQL (`probe_open_order_lines.php`); 13 at $0.00 delta. Found one
+  miss — SO 7151688 (open, ~$20.31, 0 rows) — traced to the **async-recalc race** above (see new
+  gotcha): the order was approved (Pending Approval → Pending Fulfillment) *before* the enqueuer was
+  released (so the approval itself never enqueued — one-time cutover artifact), then NetSuite's
+  `-System-` open-GP recompute fired the edit webhooks and the handler's REST GET raced that recompute,
+  reading zero open lines → reconcile-delete. A manual re-sync corrected it. Added diagnostics
+  `check_so_status.php`, `check_so_history.php`, `probe_so_rest_lines.php`. No code change yet — fix
+  direction recorded in the gotcha. (dfranks)
 - 2026-06-17 — **Fixed dropped zero-revenue/open-cost lines.** REST omits `rate` for $0 lines, and the
   `if (!is_numeric($rate)) continue;` guard was skipping them — but the cron inserts these (profit =
   −qtyOpen × unitCost; 575 such rows in prod). Now defaults missing/non-numeric rate to 0 so the both-zero

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)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 5 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)

package/package.json

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