toga-ai 1.0.491 → 1.0.492

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

@@ -8,9 +8,10 @@
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only triage/curation screen for the 2.0 Issue/Event error-reporting pipeline, built as a 1.0 Tools MVC page reading the **shared Core Logs DB** through | tools/mvc/errors/get.php, tools/mvc/errors/post.php, tools/_/app/nav.php, tools/config.production.ini |
-| [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |
+| [Legacy Email Notifier (tools /email-migration/notify)](features/legacy-email-notifier.md) | An SSO-gated admin tool at **`/email-migration/notify`** (nav group **Email Migration** > **Legacy Notifier**, personas `['TOGa Technology','Development Team']` | tools/mvc/email-migration/notify/get.php, tools/mvc/email-migration/notify/post.php, tools/_/app/nav.php |
+| [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php, library/app/error.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |
 | [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | > **PER-AI-MODEL, DATA-DRIVEN SCOPING (2026-07-29).** The KB-documents and Vocabulary admin > UIs were refactored from a single hard-coded **"development-team"* | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/get.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/pg.php, tools/_/app/model/true/aimodels.php, tools/_/app/model/true/vectorindexes.php, tools/_/app/model/true/aimodels_vectorindexes.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf, tools/.platform/hooks/prebuild/01-install-php-pgsql.sh, tools/.platform/hooks/postdeploy/01-restart-php.sh |
 | [Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus a client-side estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/mvc/talos/onboarding/get.php, tools/mvc/talos/onboarding/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/benchmarks/get.php, tools/mvc/talos/factors/get.php, tools/mvc/talos/factors/post.php, tools/assets/css/style.css |
-| [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json |
+| [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json, tools/ebs/setup_export_cache_folders.php, tools/_/app/frameworkindex.php |

package/knowledge/1.0/apps/tools/features/legacy-email-notifier.md

@@ -0,0 +1,112 @@
+---
+title: Legacy Email Notifier (tools /email-migration/notify)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-08-03
+owners: [bala]
+files:
+  - tools/mvc/email-migration/notify/get.php
+  - tools/mvc/email-migration/notify/post.php
+  - tools/_/app/nav.php
+related:
+  - ./mvc-data-access-patterns.md
+  - ../workflows/deploy-to-elastic-beanstalk-al2023.md
+  - ../architecture.md
+---
+
+## Summary
+
+An SSO-gated admin tool at **`/email-migration/notify`** (nav group **Email Migration** >
+**Legacy Notifier**, personas `['TOGa Technology','Development Team']`) that drives the
+company-wide retirement of the legacy email domains. An admin uploads the weekly Microsoft 365
+message-trace `.xlsx` exports; the tool emails each current employee a digest of messages still
+being sent to their **old** addresses last week, asking senders to switch to `@togatech.com`.
+
+Legacy domains it targets: `@goagilant.com`, `@asisystem.com`, `@agilantsolutions.com`.
+The one client DB it reads is `Client_True.Users` (the internal Agilant/True org tenant) via the
+`db_true` connection, **read-only**.
+
+## How it works
+
+1. **Upload + merge.** Accepts **multiple** `.xlsx` files (up to 10) and merges all rows into one
+   set. Parsing uses the library-vendored **PhpSpreadsheet** (see the deprecation gotcha below).
+2. **Legacy filter.** Keeps only rows whose `RecipientAddress` ends in a legacy domain; everything
+   else is dropped.
+3. **Recipient resolution (product decision — nothing is ever skipped).** A local-part map is
+   loaded once from `Client_True` over `db_true`:
+
+   ```sql
+   SELECT
+       LOWER(SUBSTRING_INDEX(email, '@', 1)) AS lp,
+       email,
+       displayName
+   FROM Users
+   WHERE email LIKE '%@togatech.com'
+   ```
+
+   `isActive` is deliberately **not** filtered — local-parts are unique. Each legacy recipient's
+   local-part is matched to that map (**user-match**). If it is **not** found, the tool **always**
+   domain-swaps to `localPart@togatech.com` — no row is skipped, by explicit product decision.
+4. **Digest grouping.** Groups into **one digest per person per legacy domain** (a person who
+   received legacy mail on two old domains gets two digests).
+5. **Chunked browser-driven send.** An AJAX loop sends **25 recipients per batch** with a progress
+   bar, per-step vertical connectors, and a **Cancel** that clears files/preview/in-progress send.
+
+### Data facts (verified in prod `Client_True.Users`)
+
+- `@togatech.com` is the migrated domain: **1960** users, **1039** active.
+- Functional mailboxes / distribution lists (e.g. `serviceops`, `ariba`, `rumcsupport`) have **no**
+  user record, so they resolve **only** via domain-swap. That swapped address may hard-bounce if no
+  such `@togatech.com` mailbox exists — an **accepted tradeoff** of the never-skip rule.
+
+## Gotcha — cross-instance job cache must live in S3, not local disk
+
+Prod `tools` runs **multiple Elastic Beanstalk instances behind a load balancer**. The parsed job
+is written at Preview and read at Send; if it is cached to local disk, Preview lands on instance A
+and the Send AJAX is load-balanced to instance B, which returns **"That job has expired."**
+
+`/var/www/cache` (created per-instance and `chmod 777` by
+`ebs/setup_export_cache_folders.php`) is **local disk, not an s3fs/shared mount**, so it cannot
+hold cross-request state. Fix: store the parsed job JSON in **S3** (reusing
+`App_Talos_S3::client()`; key prefix `email-migration-jobs/<jobId>.json`), read it in the
+send-batch step, and delete it on completion. Local dev has no vendored AWS SDK
+(`tools/vendor` absent) and is single-instance, so it **falls back to a local file**; **prod
+refuses the local fallback and fails loudly** ("Cross-instance job storage is unavailable").
+Sessions work across instances only because they use a shared store — that is why login worked but
+the local file cache did not. (See the deploy workflow for the multi-instance / local-cache facts.)
+
+## Gotcha — `App_Email::send()` is unusable in the tools runtime; send via SES SMTP directly
+
+Every send failed (`sent:0`, all "Send failed") because `App_Email::send()` also does a `Defaults`
+lookup (Vision / `db_main`), a `Logs.Emails` write (`db_logs`), and an `EmailSuppressionList`
+check (Common / `db_common`) — that 1.0 email-stack DB wiring is **not** present in the tools app,
+so it threw for every recipient.
+
+Fix: send with **PHPMailer directly** using `App_Email`'s SES SMTP **constants**
+(`SMTP_HOSTNAME` / `SMTP_PORT` / `SMTP_SECURE` / `SMTP_USERNAME` / `SMTP_PASSWORD` — the same
+proven SES SMTP creds, `us-west-2`) and **no DB calls**; From `no-reply@togatech.com` / "TOGa IT".
+**Operational prerequisite:** the `togatech.com` sender identity/domain must be **verified in that
+us-west-2 SES account** or delivery is rejected. Any future tools-app feature that needs to send
+email hits the same wall — bypass `App_Email::send()` and go straight to SES.
+
+## Gotcha — PhpSpreadsheet 1.6.0 deprecations abort the request
+
+The vendored PhpSpreadsheet is **1.6.0** (library composer constraint `^1.6`, which supports only
+PHP 5.6/7.0) and emits `E_DEPRECATED` all over on PHP 8.x. A single deprecation during the xlsx
+parse aborts the request, because the 1.0 error handler promotes any PHP notice/deprecation to a
+thrown exception **and** (when Sentry is absent) echoes "Sentry is not installed…" into the
+response, corrupting the JSON. Fix: install a **scoped `set_error_handler`** at the top of the
+endpoint that swallows non-fatal diagnostics (returns `true`) for the duration of the action; real
+fatals and thrown exceptions still reach the `catch`. The framework mechanism is documented in
+[mvc-data-access-patterns](./mvc-data-access-patterns.md).
+
+## Change history
+- 2026-08-03 — Built the Legacy Email Notifier: multi-file xlsx merge via vendored PhpSpreadsheet,
+  legacy-domain filter, `Client_True.Users` local-part resolution with always-domain-swap
+  (never-skip), one digest per person per legacy domain, and chunked (25/batch) browser-driven
+  send. Recorded the S3 cross-instance job cache, SES-direct send (App_Email unusable in tools),
+  and the PhpSpreadsheet-deprecation scoped error-handler fixes (bala)

package/knowledge/1.0/apps/tools/features/mvc-data-access-patterns.md

@@ -6,11 +6,12 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: [jcardinal]
+updated: 2026-08-03
+owners: [jcardinal, bala]
 files:
   - tools/_/app/nav.php
   - tools/mvc/get.php
+  - library/app/error.php
 related:
   - ./persona-gated-navigation.md
   - ./saml-sso-auth.md
@@ -86,10 +87,32 @@ if (!headers_sent()) { http_response_code(401); }   // matches App_MVC::routeTo'
 path hit this too — see [saml-sso-auth](./saml-sso-auth.md). The clean long-term fix is to handle
 status-setting routes **before any output** and `exit`.
 
+## Gotcha — the error handler promotes ANY PHP notice/deprecation to a thrown exception (and corrupts JSON)
+`App_Error::handleError` (`library/app/error.php`) **ignores the `error_reporting` mask** and
+promotes **any** PHP notice/warning/deprecation to a thrown `ErrorException`. When Sentry is not
+installed it **also echoes** "Sentry is not installed…" into the response — which **corrupts a JSON
+response body**. So a single `E_DEPRECATED` (e.g. an old vendored package like PhpSpreadsheet 1.6.0
+running on PHP 8.x) aborts the whole request and, on an AJAX endpoint, breaks the JSON the browser
+is parsing. This is the same escalation behind the preloader-flush 500 above.
+
+Fix for a page/endpoint that legitimately triggers non-fatal diagnostics: install a **scoped**
+`set_error_handler` at the top of the action that **returns `true`** to swallow non-fatal notices
+for the duration of the action; real fatals and thrown exceptions still reach your `catch`. Scope
+it tightly — do not disable diagnostics app-wide.
+
+```php
+set_error_handler(fn(): bool => true); // swallow non-fatal notices/deprecations for this action only
+```
+
 ## Autoloader
 `App_Foo_Bar` → `app/foo/bar.php`, **all lowercase** (per the library CLAUDE.md). E.g.
 `App_Talos_Estimator` → `_/app/talos/estimator.php`.
 
 ## Change history
+- 2026-08-03 — Added the error-handler escalation gotcha: `App_Error::handleError` promotes ANY PHP
+  notice/deprecation to a thrown `ErrorException` (ignoring `error_reporting`) and, without Sentry,
+  echoes "Sentry is not installed…" into the response — corrupting JSON on AJAX endpoints; workaround
+  is a scoped `set_error_handler` returning true. Surfaced building the Legacy Email Notifier (xlsx
+  parse via PhpSpreadsheet 1.6.0 on PHP 8.x). (bala)
 - 2026-06-30 — Added the preloader-flush gotcha: pages run after `App_Page::flushCapture()` flushes the output buffer, so `http_response_code`/`header`/`session_regenerate_id` from inside a page fatal on headers-already-sent (escalates to a 500) — guard with `!headers_sent()`. Surfaced by the SSO failure-path 500 fix. (jcardinal)
 - 2026-06-29 — Documented tools MVC routing (GET→get.php / POST→post.php; writes via mvc/<route>/post.php, not the legacy actionHandler path), Origin/Referer CSRF (no token field), `App_Database` query/row/txn API + `sqlEscape()` name, the by-reference row-helper warning gotcha, the persona-narrowing gotcha, and the lowercase autoloader mapping. Discovered building the Talos Pricing UI. (jcardinal)

package/knowledge/1.0/apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: workflow
 status: active
-updated: 2026-06-26
-owners: [jcardinal]
+updated: 2026-08-03
+owners: [jcardinal, bala]
 files:
   - tools/.ebextensions/004_http_to_https.config
   - tools/.ebextensions/006_mount-s3fs.config
@@ -17,6 +17,8 @@ files:
   - tools/.ebextensions/020_setup_git_libraries.config
   - tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config
   - tools/ebs/git.json
+  - tools/ebs/setup_export_cache_folders.php
+  - tools/_/app/frameworkindex.php
 related:
   - ../architecture.md
 ---
@@ -100,6 +102,64 @@ roles, so `AWS_SECRET_KEY` / `AWS_ACCESS_KEY_ID` are not injected into `$_SERVER
 s3fs credential write fails cleanly. Use `ignoreErrors` only on genuinely non-fatal infra
 setup — the git clone (`020`) deliberately does **not** use it (see gotchas).
 
+## Prod is multi-instance — never store cross-request state on local disk
+
+Prod `tools` runs **multiple EB instances behind a load balancer** (see
+`050_register_instance_to_shared_application_load_balancer.config`). Any state written on one
+request may be read on another instance on the next request. Consequences:
+
+- **`/var/www/cache` is per-instance LOCAL disk, not shared.** It is created and `chmod 777`ed
+  per instance by `ebs/setup_export_cache_folders.php`; it is **not** an s3fs/shared mount, so it
+  cannot hold state that a later request must read. Symptom seen: a Preview→Send flow that cached
+  the parsed job to `/var/www/cache` failed with "That job has expired" because Preview hit
+  instance A and the Send AJAX was load-balanced to instance B.
+- **Cross-instance state must go to S3** (e.g. via `App_Talos_S3::client()`), or another shared
+  store. **Sessions already survive across instances** because they use a shared store (redis) —
+  that is why login works while a local file cache does not.
+- Fail **loudly** in prod if the shared store is unavailable rather than silently falling back to
+  local disk (a local fallback is fine for single-instance local dev only).
+
+## No composer install step on deploy
+
+The deploy clones `agilantsolutions/library` and `resources` via
+`020_setup_git_libraries.config` but has **no explicit `composer install` step**. `tools/vendor`
+(AWS SDK, Sentry) therefore exists **only if** the EB PHP platform auto-runs composer. Do not
+assume a composer package is present at runtime — any code path needing one must `require_once` the
+autoloader itself and degrade gracefully when `tools/vendor` is absent (this is why S3-backed
+cross-instance storage has a local-disk fallback path for dev, where the AWS SDK is not vendored).
+
+## Config selection & DB wiring
+
+- **Which config file loads is chosen by the `ENVIRONMENT` env var, NOT the hostname.**
+  `App_Config::getConfigFilename` resolves `config.<ENVIRONMENT>.ini`.
+- Config maps DB key **`db_<x>` → `[database_<x>]`** section; `App_Registry::get()` connects
+  **lazily** on first use. `Client_True` is **`db_true`** (`reader1.client.database.togahub.com`).
+- Prod php.ini caps `upload_max_filesize=25M` / `post_max_size=30M` (`009_setup_phpini.config`) —
+  multi-file uploads (e.g. the Legacy Email Notifier's xlsx trace exports) must stay under this.
+
+## Local development
+
+- **Run locally with the `ENVIRONMENT` var pointing at your local config:**
+
+  ```sh
+  ENVIRONMENT=<name> php -d include_path=".;C:/WWW/library" -S localhost:8000 router.php
+  ```
+
+  This selects `config.<name>.ini` and puts `library/` on the include path. Local dev is
+  single-instance and has **no vendored AWS SDK** (`tools/vendor` absent), so S3-backed features
+  fall back to local disk here.
+- **The Vision copyright watchdog in the shared `resources/library.js` redirects local dev.**
+  `App_FrameworkIndex::render()` loads `resources/library.js`, whose obfuscated block
+  (`resources/library.js:848` → `jc()`/`jcr()`) pings the hardcoded **production** endpoint
+  `https://vision.asisystem.com/vision/cr.php` ~12–35s after load. `cr.php` checks the browsing
+  host against the `CopyrightHosts` table (`db_log`) and, for a host that is neither listed nor a
+  `*.agilantsolutions.com` origin (e.g. `localhost`), redirects to `vision/unauthorized.html`
+  ("Unauthorized Access!"). This breaks local dev of **any** tools/1.0 page. Workarounds: browse
+  under a `*.agilantsolutions.com` hosts alias (cr.php short-circuits those), **or** neutralize
+  `window.jc`/`window.jcr`. A **dev-only** skip was added to `App_FrameworkIndex_Tools::render()`
+  (`tools/_/app/frameworkindex.php`), gated on `App_Registry::inDevMode()` (a no-op in prod), that
+  overwrites those globals so local dev is not redirected.
+
 ## Gotchas (durable AL2023 / EB rules)
 
 - **php-fpm on AL2023 defaults to `clear_env=yes`, so `getenv()` cannot see EB environment
@@ -136,6 +196,12 @@ setup — the git clone (`020`) deliberately does **not** use it (see gotchas).
   returns `200` fast. Reusable for any TOGA app behind Elastic Beanstalk.
 
 ## Change history
+- 2026-08-03 — Recorded that prod Tools is multi-instance behind an ALB, so `/var/www/cache` is
+  per-instance local disk (not shared) and cross-request state must go to S3 — the root cause of a
+  Preview→Send "job expired"; noted the no-composer-install deploy, `ENVIRONMENT`-based config
+  selection + `db_<x>`→`[database_<x>]`/`db_true` wiring, and added a Local development section (run
+  command + the Vision `cr.php` copyright-watchdog redirect and its dev-only frameworkindex skip).
+  Discovered building the Legacy Email Notifier (bala)
 - 2026-07-24 — Added the php-fpm `clear_env=yes` gotcha (read EB env properties from
   `getenv()`/`$_SERVER`/`$_ENV`) and raised `application.ini` upload/post limits to 25M/30M for
   multi-MB design-demo exports (jcardinal)

package/knowledge/INDEX.md

@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 12 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 13 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/clients/compass-usa/INDEX.md

@@ -12,5 +12,5 @@
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
-| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |
+| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

package/knowledge/clients/compass-usa/workflows/odp-order-pipeline-to-netsuite.md

@@ -6,12 +6,13 @@ project: Worker
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-07-01
-owners: ["rgirish"]
+updated: 2026-08-03
+owners: ["rgirish", "bala"]
 files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
   - worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php
   - worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php
+  - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
   - worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php
   - library/app/client/compass.php
 related:
@@ -69,6 +70,45 @@ ODP SalesOrder (customerId = 1)
    - **computer-kit orders** (Bundles 187–196) wait for a **2nd PO** before syncing.
    - a **30-minute delay** after the first ODP PO is created.
 
+## Cron 5 NetSuite SO creation — failure modes & the two ODP error emails
+
+Two different Compass ODP error emails exist, from **two different pipeline stages**. They look
+alike but are distinct — check the subject to know which cron/stage failed:
+
+- **`Office Depot PO Import error: <ODP PO number>`** — sent by cron **3a**
+  (`workflow/3a_import_office_depot_purchase_orders.php`, EDI 850 → PO import into Toga 2.0) via
+  its `sendErrorNotification()`. It writes the raw EDI x12 to a temp file and **attaches it**
+  (`App_Email_Agilant->addAttachment`).
+- **`Compass Office Depot SO failed in NetSuite: <SO> / <CompassPO>`** — sent by cron **5**
+  (ODP PO → NetSuite SO creation). (Reworded 2026-08-03; was
+  `Office Depot Import error: <Compass SO> / <Compass PO>`, historically with no attachment.)
+
+**Cron 5 has exactly two error sources**, both pushed onto `$errMessage[]`:
+1. **`Item not found in NetSuite: <partNumber>`** — the SKU resolved to no NetSuite internal id.
+2. **NetSuite `add()` rejection** — NetSuite refused the SalesOrder (see the Ext Price root cause
+   below, the common case).
+
+### Root cause of the recurring "Please enter a value for Ext Price" rejection
+In cron 5's item loop, `$soItem->rate` (NetSuite's "Ext Price") is set **only** when the SKU
+resolves as a NetSuite **item group** via `App_NetSuite::getItemGroupInternalIdFromPartNumber()`.
+For a **plain item** resolved via `App_NetSuite::getItemInternalIdFromPartNumber()`, no rate is
+ever set, so NetSuite's `add()` rejects the whole order with USER_ERROR **"Please enter a value
+for Ext Price."** The order then stays stuck: cron 5 only picks ODP SalesOrders with
+`c_dtTransmittedToNetsuite IS NULL` and **re-attempts (and re-emails) every hour** until a success
+stamps `c_dtTransmittedToNetsuite` + `c_netsuiteInternalSalesOrderId`. So a repeating hourly
+"SO failed in NetSuite" email for the same order is this loop, not a new failure each time.
+
+### Error-email rework (2026-08-03, cron 5)
+- New helper **`buildNetsuiteErrorMessage(AddResponse $response)`** walks
+  `writeResponse->status->statusDetail[]` and returns `NetSuite rejected the order - <CODE>:
+  <message>` (multiple details joined by `; `) — replacing the old whole-`AddResponse` `print_r`
+  dump.
+- The email body now appends the **no-rate item part numbers** (collected in `$itemsWithoutRate`
+  whenever `$soItem->rate` is unset) after the error line — these are the Ext Price culprits.
+- An attachment **`NetSuiteError_<SO>.txt`** (written to `sys_get_temp_dir()`) carries the Compass
+  SO/PO, the Office Depot PO, and the full NetSuite request (SalesOrder) + response dump, attached
+  via `App_Email_Agilant->addAttachment()` (the same mechanism cron 3a uses).
+
 ## Constants & identities (`library/app/client/compass.php`)
 - `App_Client_Compass::VENDOR_ID__OFFICE_DEPOT = 1` — `Vendors.id = 1` = "OFFICE DEPOT".
 - `App_Client_Compass::CUSTOMER_ID__OFFICE_DEPOT = 1` — `Customers.id = 1` = "Office Depot".
@@ -101,6 +141,12 @@ wrong record makes every order look "stuck." Use the **join**, never a number ma
   transmission feature.)
 
 ## Change history
+- 2026-08-03 — Documented cron 5's "Please enter a value for Ext Price" root cause (`rate` set
+  only for NetSuite item groups, never plain items → NetSuite `add()` USER_ERROR, order re-emails
+  hourly while stuck), the two distinct ODP error emails (3a PO-import vs 5 SO-creation) and cron
+  5's two error sources, plus the cron-5 error-email rework (`buildNetsuiteErrorMessage`
+  `statusDetail` parsing, no-rate part numbers appended, reworded subject, `NetSuiteError_<SO>.txt`
+  request/response attachment). (bala)
 - 2026-07-01 — Documented the numbered ODP→NetSuite worker-cron pipeline (crons 1/2/edi-1/5),
   the AS2 850 S3 hand-off (`agilant-as2` / `OfficeDepot/`), the customerId=1-vs-2 NetSuite
   writeback rule + cron-5 exclusion filters, and the "order not in NetSuite" diagnostic method

package/package.json

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