toga-ai 1.0.944 → 1.0.945

package/knowledge/1.0/apps/library/features/email-test-mode-and-write-free-sends.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-05
 owners: ["bala"]
 files:
   - library/app/email.php
@@ -88,7 +88,8 @@ Call `App_Framework_Worker::initialize()` (or the app's equivalent) for config/r
 2. Read your sample data with a **single SELECT** — no models that `save()`, no api2 calls.
 3. Build the mail exactly as the real code does (same template class, same subject, same S3 fetches) so you test the real body, not a paraphrase.
 4. Set the three switches above.
-5. Print, before sending, which attachments resolved and their byte sizes — a missing PDF is otherwise invisible (see `email-queue-attachments.md`: PHPMailer 5 sends anyway).
+5. To read **prod** data from a local run: call `App_Registry::setOkToPerformOnReadCluster(true)` and force the prod DB links by name (e.g. `db_prod_<client>`, `db_prod_logs_<client>`), because client crons pick `db_dev_*` links under `inDevMode`. Stop before any `UPDATE` the real cron does after sending.
+6. Print, before sending, which attachments resolved and their byte sizes — a missing PDF is otherwise invisible (see `email-queue-attachments.md`: PHPMailer 5 sends anyway).
 
 Run it with the framework repos on the include path:
 ```

package/knowledge/clients/prudential/INDEX.md

@@ -7,7 +7,7 @@
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | How the device-sync cron links a Unit to its employee Contact, the "null null" duplicate-contact incident, and the dedup+backfill remediation; open before touch |
 | [Prudential: ItemClasses device-tier data is dead (and how that was proved)](features/itemclasses-device-tier-data.md) | 2.0 | Prudential `ItemClasses` device-tier data is dead/partly-wrong and was cleared 2026-09-11; also the reusable 4-source method for proving any field is dead. |
 | [Prudential: OneUptime order-pipeline backlog monitors (Monitor/Prudential/*)](features/oneuptime-order-pipeline-monitors.md) | 2.0 | Three worker2 OneUptime push monitors watching the Prudential/Dell order pipeline for stalls; open before touching Prudential monitors, their thresholds, or the |
-| [Prudential: order email PDF attachments (which guide goes on which email)](features/order-email-pdf-attachments.md) | 1.0 | Which S3 PDF guide attaches to which Prudential order email by service-request type/stage, and how to change an attachment safely; open before editing any Prude |
+| [Prudential: order email PDF attachments (which guide goes on which email)](features/order-email-pdf-attachments.md) | 1.0 | Which S3 PDF guide attaches to which Prudential order email by service-request type/stage, every hardcoded spot to change when a guide is swapped, and how to te |
 | [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The prePost interceptor that validates a Prudential service request's deliverToAddress per region (USA/India/Ireland) and rejects a blank customer uuid; open fo |
 | [Prudential: refused REQ alert (401/403 on POST /v2/service-requests)](features/service-request-auth-rejection-alert.md) | 1.0 | The 15-min cron that alerts on refused (401/403) inbound Prudential REQs, where each code is logged, and how to tell "we refused it" from "they never sent it"; |
 | [Prudential: Service Request bundle lookup scoped to the customer's catalog (wrong Dell India provision profile)](features/service-request-bundle-catalog-resolution.md) | 2.0 | Why India REQs link to USA bundles (bundle numbers repeat across catalogs) and the prePost fix that resolves the bundle uuid inside the customer's catalog; open |

package/knowledge/clients/prudential/features/order-email-pdf-attachments.md

@@ -6,19 +6,21 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-05
 owners: ["bala"]
 files:
   - worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php
   - worker/crons/toga2/prudential/transmissions_to_netsuite.php
   - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
   - worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php
+  - worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php
+  - store/common/prudential/home.php
 related:
   - transmit-ordershipped-email.md
   - ../profile.md
   - ../../../1.0/apps/library/features/email-test-mode-and-write-free-sends.md
 ---
-Which S3 PDF guide attaches to which Prudential order email by service-request type/stage, and how to change an attachment safely; open before editing any Prudential order-email attachment.
+Which S3 PDF guide attaches to which Prudential order email by service-request type/stage, every hardcoded spot to change when a guide is swapped, and how to test against prod safely; open before editing any Prudential order-email attachment or guide link.
 
 ## Summary
 Every customer-facing Prudential order email carries S3-hosted PDF guides, and **which** guide is attached is decided by the service request type. The rule was inconsistent between stages (same request type got different documents at order-created vs shipped vs delivered), and a new hire was being sent the *return* instructions instead of a setup guide. As of 2026-08-27 one rule applies at **every** stage:
@@ -42,7 +44,7 @@ Reported by the client (Gary Yerman) against the new-hire order-created email; t
 Load-bearing part is the **Return** column: no non-New type may go out without the return guide, and New must never carry it.
 
 ### Which cron sends which email
-All four are `active: 1` in `worker/schedules/cron.worker.sync.json`:
+Schedules in `worker/schedules/cron.worker.sync.json`. All `active: 1` except `transmissions_to_netsuite.php` (`active: 0` since 2026-07-17, see `transmit-ordershipped-email.md`):
 | Stage | Cron | Branches on |
 |---|---|---|
 | Order created | `generate_sales_and_purchase_orders_from_service_requests.php` | `serviceRequestTypeId` (`1`, `5`, `3`, `else`) |
@@ -53,14 +55,29 @@ All four are `active: 1` in `worker/schedules/cron.worker.sync.json`:
 **Two different crons send the shipped email** (`transmissions_to_netsuite.php` and `transmit_ordershipped_updates_prudential.php` — both also stamp `c_dtTransmittedOrderShippedUpdateToPrudential`). Any attachment change to the shipped email must be made in **both**, or they drift apart. The order-created cron switches on the numeric `serviceRequestTypeId`, while shipped and delivered crons switch on the type **name string** read from `serviceRequest.serviceRequestType.name` in the TOGa API response. Names match the enum exactly (`New`, `Reclaim`), so the string comparisons are safe — but the two styles mean a newly added request type lands in the `else` branch everywhere and is never matched by name.
 
 ### The PDF assets
-All three live under `https://external-client-files.s3.us-west-2.amazonaws.com/prudential/` and all returned HTTP 200 (verified 2026-08-27). Two are **renamed on attach**:
+All three live under `https://external-client-files.s3.us-west-2.amazonaws.com/prudential/`. Two are **renamed on attach**:
 | S3 object | Attached to the email as | Size |
 |---|---|---|
-| `EquipMe-Win11-v1.pdf` | `Getting_Started_Guide_Windows11.pdf` | 773,591 B |
+| `EquipMe-Win11-Sep_2026.pdf` (since 2026-10-05; replaced `EquipMe-Win11-v1.pdf`) | `Getting_Started_Guide_Windows11.pdf` | 2,735,276 B |
 | `2026_Aug_PrudentialMacSetupGuide_ZCC.pdf` | `PrudentialMacSetupGuide.pdf` | 7,543,154 B |
 | `Prudential_Instruction-2Page-V1.pdf` | (unchanged) | 100,224 B |
 
-The Mac guide dominates: a new-hire email is roughly **11 MB** once base64-encoded. Grepping for the attached-as filename will not find the S3 object — search the S3 basename.
+A new-hire email (Win11 + Mac) is roughly **14 MB** once base64-encoded. Grepping for the attached-as filename will not find the S3 object, search the S3 basename.
+
+**The attached name never changes, so it does not tell you the version.** The email shows `Getting_Started_Guide_Windows11.pdf` and the cron caches to `$cacheFolder/Getting_Started_Guide_Windows11.pdf` whatever URL was fetched. Check the byte size instead (Sep 2026 = 2,735,276; old v1 = 773,591). The old `EquipMe-Win11-v1.pdf` and the S3 object `Getting_Started_Guide_Windows11.pdf` are byte-identical (both the old guide).
+
+### Swapping the Windows 11 guide: every hardcoded spot
+There is **no setting or table** for the guide URL. It is a literal in each file below, and all must change together:
+| File | Where |
+|---|---|
+| `worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php` | `$pdfUrl2` in the order-created branches New (1), Refresh (3), and `else` (Breakfix/Swap/Label). Reclaim (5) attaches only `Prudential_Instruction-2Page-V1.pdf`. |
+| `worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php` | Shipped (Dell, vendorId 1): new-hire block, plus the shared block inside `if ($reqType != 'Reclaim')`. |
+| `worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php` | Delivered: same two places, same Reclaim guard. |
+| `worker/crons/toga2/prudential/transmissions_to_netsuite.php` | Shipped for Agilant-shipped POs (vendorId 2). Cron is `active: 0`, and prod has 0 vendor-2 POs with `c_dtEmailSentOrderShipped`, so it never fires today. Change it anyway. |
+| `worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php` | Beta copy of order-created. |
+| `store/common/prudential/home.php` (~L244-245) | Equip Me home page "Document" announcement: `$link` ("Click here") and `$win10Link` ("click here") both point at the guide. The Mac link (`$macLink`) is separate. |
+
+Last swap 2026-10-05 (to the Sep 2026 build guide): New, Refresh, Breakfix/Swap/Label emails and the Equip Me page; Reclaim stays excluded.
 
 ### The verbiage has to match what actually attached
 Every attach is guarded by `if ($pdfGuideX !== false)`, but until 2026-08-31 the `$attachmentText` paragraph that *describes* the attachments was unconditional. A failed S3 fetch produced an email whose copy pointed the recipient at guides not on the message — and it always said "guides" plural even when a single guide attached. The rule now, in every branch touched: **derive the sentence from the guards, not from the intent.**
@@ -94,23 +111,18 @@ Only the new-hire and Breakfix/Swap/Label order-created templates carry the (com
 2. Each PDF gets its **own** `if ($pdfX !== false)` guard around the `file_put_contents` + `addAttachment` pair — never a joint `&&`. One failed PDF must drop only itself; the email always sends.
 3. **Put the return-guide fetch *before* the `if ($reqType != 'Reclaim')` guard** in the shipped and delivered crons. Everything inside that guard is skipped for Reclaim — and Reclaim is precisely the type that most needs the return instructions. That guard is how Reclaim ended up receiving zero attachments.
 
-### Testing these emails without writing anything
-**There is no committed test harness — do not go looking for one.** Three throwaway scripts (`test_new_hire_email.php`, `test_prudential_order_emails.php`, `test_prudential_email_templates.php`) were written under `crons/toga2/prudential/` on 2026-08-31 to mail every stage/type combination with the real templates and real S3 PDFs. They were **never committed and are no longer in the working tree**. What is durable is the technique.
-
-A harness that mails a real, byte-identical copy while writing **nothing** to the database needs all of this:
-- `setQueueForSending(false)`, `sendEmailEvenIfOutboundEmailIsDisabled = true`, and `setIsLogEnabled(false)` on the `App_Email` object. All three — the first two keep it out of `Common.EmailsQueued`, the third keeps it out of `Logs.Email`. Full detail in [App_Email Side Effects & Test Mode](../../../1.0/apps/library/features/email-test-mode-and-write-free-sends.md).
-- `App_Framework_Worker::initialize()` **only**. Do **not** call `App_Framework::cronInitialization()` — it INSERTs a `CronJobExecutions` row. Set `set_time_limit()` and `date_default_timezone_set()` yourself instead.
-- One read-only SELECT for the sample data (below), rather than the cron's api2 fetches.
-- Print each PDF's resolved/missing state and byte size **before** sending; PHPMailer 5 will send the message anyway if an attachment is unreadable.
-
-**Run it on the worker server if anyone other than you needs to receive it.** Local and beta configs have `internal.test_mode = 1`, which discards the recipient list and sends only to `email.dev_email_to`. `config.worker.ini` on the worker server has `test_mode = 0`.
-
-Read-only query for a real sample request: one row per request type is enough. Join `ServiceRequests` to `Addresses` on `deliverToAddressId`, `States` on `Addresses.stateId`, `Contacts` on `requestedForContactId`, and **LEFT JOIN** `SalesOrders` on `SalesOrders.serviceRequestId` (left, because an unprocessed request has no SO yet). Select `ServiceRequests.c_reqNumber AS reqNumber`, `Contacts.firstName`, the address parts, `States.code`, and `SalesOrders.number` — the exact set the shipped/delivered templates interpolate. All six request types have live rows in prod `Client_Prudential` (verified 2026-08-31); **Swap has only 2 rows**, the rest have thousands, so filter narrowly for Swap or you will miss it.
+### Testing these emails against prod data without writing anything
+No committed harness. Build a throwaway `test_<x>_emails.php` next to the cron, use it, delete it. The generic recipe (the three `App_Email` switches, skip `cronInitialization()`, reading prod from a local run) is in [App_Email Side Effects & Test Mode](../../../1.0/apps/library/features/email-test-mode-and-write-free-sends.md). Prudential specifics:
+- Copy the cron's email block **verbatim** (template, subject, S3 fetches) and force `$emailAddresses = [$testEmailRecipient]`.
+- Force links `db_prod_prudential` / `db_prod_logs_prudential` (the crons pick `db_dev_*` under `inDevMode`).
+- Sample = the latest prod record per `serviceRequestTypeId` that was **already emailed** at that stage: `SalesOrders.c_dtEmailSent` (created), `PurchaseOrders.c_dtEmailSentOrderShipped` (shipped), `c_dtEmailSentOrderClosed` (delivered) `IS NOT NULL`. Swap has very few rows in prod, so filter narrowly.
+- Stop before the cron's `UPDATE` of those date columns.
+- Print each PDF's byte size before sending (that is how you tell guide versions apart, see above).
 
 ## Gotchas
 - **`transmit_closecomplete_updates_prudential.php` still over-promises (~line 447).** Its delivered email hardcodes "Guides for Windows 11 and MacBook devices are provided" with no reference to whether either PDF actually attached — the exact bug fixed everywhere else on 2026-08-31. Left alone deliberately to keep PR #1707's diff to files already being changed. **Worth a follow-up ticket.**
 - **`transmissions_to_netsuite.php` also sends *delivered* emails — with no attachments at all.** It carries its own "New hire equipment has been delivered" / "Your equipment has been delivered" blocks (~L1765 and ~L2149) that make **zero** `addAttachment()` calls, while `transmit_closecomplete_updates_prudential.php` sends the **same two subjects** with the guides attached. **Whether both fire for the same order was not established** — if they do, the recipient gets a duplicate delivered email, one attachment-less. Check this before changing either.
-- **`prudential_beta/` does not match prod.** `crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php` is `active: 1` on the same schedule but points at the beta DB and still references the retired `Prudential_Return_Instructions.pdf` (and the old `PrudentialMacSetupGuide.pdf`). **A beta test will not reproduce prod attachment behavior.** Left as-is deliberately; the developer is aware.
+- **`prudential_beta/` does not match prod.** `crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php` is `active: 1` on the same schedule but points at the beta DB and still references the retired `Prudential_Return_Instructions.pdf` (and the old `PrudentialMacSetupGuide.pdf`). **A beta test will not reproduce prod attachment behavior.** Only the Win11 guide URL is kept in sync with prod (2026-10-05); the rest is left as-is on purpose.
 - **Breakfix / Swap / Label get no Mac guide on the order-created email** (they do get it on shipped and delivered). Known, and left alone on purpose — not a bug to "fix" unasked.
 - The delivered cron (`transmit_closecomplete_updates_prudential.php`) already followed the rule and was deliberately **not** touched.
 

package/package.json

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