toga-ai 1.0.334 → 1.0.336

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

@@ -6,6 +6,7 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |
+| [_ApiRequest ENCODE__JSON now sends Content-Type: application/json](features/apirequest-json-content-type.md) | `_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set a `Content-Type` header. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |

package/knowledge/2.0/apps/_underscore/features/apirequest-json-content-type.md

@@ -0,0 +1,39 @@
+---
+title: _ApiRequest ENCODE__JSON now sends Content-Type: application/json
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-14
+owners: ["jcardinal"]
+files:
+  - _underscore/ApiRequest.php
+related:
+  - ../../worker2/features/oneuptime-worker2-monitoring.md
+---
+
+## Summary
+`_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set
+a `Content-Type` header. cURL therefore defaulted to `application/x-www-form-urlencoded`, and
+receivers parsed the entire JSON string as a single form-field NAME — observed at OneUptime as
+`{"<json>":""}`. Every 2.0 `ENCODE__JSON` POST/PUT/PATCH caller was silently shipping
+form-urlencoded bodies.
+
+## How it works
+The `ENCODE__JSON` branch now adds `Content-Type: application/json`. It is guarded by a
+case-insensitive scan of already-set headers, so a caller-supplied `Content-Type` still wins
+(no override). All other encodings are unaffected.
+
+## Gotchas / known issues
+- This changes the wire format of ALL existing `ENCODE__JSON` callers (they were previously
+  sending form-urlencoded). This is a correction, but smoke-test heavy JSON callers post-deploy:
+  ClickUp, NetSuite, Vapi.
+
+## Change history
+- 2026-07-14 — Fixed `ENCODE__JSON` to send `Content-Type: application/json` (guarded so a
+  caller-set Content-Type wins). Root-caused via OneUptime receiving `{"<json>":""}`. Affects
+  all 2.0 ENCODE__JSON callers. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/_underscore/features/cloud-s3-helpers.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-13
+updated: 2026-07-14
 owners: ["jcardinal"]
 files:
   - _underscore/Cloud.php
@@ -22,7 +22,7 @@ workers or app code. Alongside the existing copy / get / delete methods it now h
 
 ## Key files / entry points
 
-- `_underscore/Cloud.php` — `_Cloud::getS3Objects($s3BucketName, $s3BucketPath = '')`.
+- `_underscore/Cloud.php` — `_Cloud::getS3Objects($s3BucketName, $s3BucketPath = '', ?string $awsRegion = null)`.
 
 ## How it works
 
@@ -33,10 +33,18 @@ workers or app code. Alongside the existing copy / get / delete methods it now h
 - `LastModified` — ISO-8601 string
 - `Size`
 
-The method is **purely additive** — no existing `_Cloud` method signature changed. Keeping
-S3 listing here (rather than instantiating `S3Client` in a worker) is the reason to prefer
+The method is **additive** — the optional 3rd param `?string $awsRegion = null` falls back
+to `_Config::cloud('aws_region')`, so existing 2-arg callers are unchanged. Keeping S3
+listing here (rather than instantiating `S3Client` in a worker) is the reason to prefer
 this helper over ad-hoc SDK calls.
 
+### Per-bucket region override
+
+The config-default region is **us-east-1**. Buckets in another region must pass
+`$awsRegion` explicitly or the SDK throws `AuthorizationHeaderMalformed`. Notably the
+**`agilant-as2`** bucket lives in **us-west-2** — the worker2 Office Depot S3 monitors pass
+`'us-west-2'`.
+
 First consumer: the worker2 Office Depot EDI backlog monitor — see
 [OneUptime push-metric monitors](../../worker2/features/oneuptime-worker2-monitoring.md).
 
@@ -48,7 +56,12 @@ None — shared core helper.
 
 - Callers get every matching key regardless of count; pagination is handled internally, so
   do not add your own `ContinuationToken` loop on top.
+- A bucket outside the config-default us-east-1 (e.g. `agilant-as2` in us-west-2) throws
+  `AuthorizationHeaderMalformed` unless you pass `$awsRegion`.
 
 ## Change history
+- 2026-07-14 — `getS3Objects()` gained an optional `?string $awsRegion = null` 3rd param
+  (falls back to `_Config::cloud('aws_region')`); needed because `agilant-as2` is in
+  us-west-2, not the config-default us-east-1. Additive — 2-arg callers unchanged. (jcardinal)
 - 2026-07-13 — Added `_Cloud::getS3Objects()` S3 LIST helper (paginated `listObjectsV2`,
   returns `{Key, LastModified, Size}`); additive, no existing signatures changed. (jcardinal)

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
-| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -13,7 +13,10 @@ files:
   - toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx
   - toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx
   - toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx
+  - toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx
+  - toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json
   - toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx
+  - toga2-supply/src/components/ui/BaseInput/BaseInput.tsx
   - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
   - toga2-supply/src/pages/EditShipment/types.ts
   - toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx
@@ -87,6 +90,75 @@ from the saved fulfillment; **Save UPDATES the existing records** instead of POS
 - `CardTable` was made reusable for this: optional `editIcon` + `isEditButtonDisabled` props
   (defaults preserve prior behavior; the shipments card is the only consumer today).
 
+## Update Info / Edit Shipment form (config-driven; Figma-alignment pass 2026-07)
+
+The New Shipment / Edit Shipment form is **config-driven**: fields come from
+`viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json`, are rendered by
+`view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx` through the shared
+`EditShipmentForm.tsx`, and the individual inputs are `components/ui/BaseInput/BaseInput.tsx`
+(text/currency) plus react-select (State/Country). To change field layout, labels,
+required-ness, or ordering, edit the **config JSON**, not the component.
+
+- **Create vs Edit are distinct entry points (decision — kept, not merged).** Select Items →
+  Next = create a **New Shipment**; the pending-shipments pencil = **edit** an existing draft.
+  They are deliberately NOT merged and there is no auto-load from Select Items, because a Sales
+  Order can have **multiple** shipments (partial fulfillment — Select Items shows
+  Ordered/Fulfilled/Committed per line), so "the saved shipment" is not singular and auto-loading
+  would be ambiguous. Page title now signals the mode: create = **"New Shipment"**, edit =
+  **"Edit Shipment"** (create previously mis-titled "Update Info").
+- **Fulfillment Location is READ-ONLY (decision — Eric, Exec Dir Services Ops, authoritative).**
+  Sourced from the Sales Order's location and shown display-only; the value must **not** change
+  in the tool — any change happens back at the SO. Implemented as `getAddress` fetching
+  `location.name`, `EditShipmentPage` adding `fulfillmentLocation` to the transformed address, and
+  `renderEditShipmentFormInput` rendering it via `BaseDisabledInput` on an `isReadOnly` flag. **Not
+  persisted to `IF.locationId`** for now — persisting would be a separate backend "set from SO"
+  change plus a NetSuite-mapping check.
+- **Reference 1 / Reference 2 fields are placeholders (rendered, values NOT wired yet).**
+  Definitions are settled: **Reference 1 = NetSuite Sales Order #, Reference 2 = NetSuite Purchase
+  Order #** (Eric, authoritative — supersedes Skyler's earlier "Ref 1 = vendor account #, Ref 2 =
+  company name"). Value sourcing/persistence/carrier-wiring is intentionally deferred; when wiring,
+  verify: SO# = the document **ORDER #** (e.g. `281144`) vs the internal id (`7221433`, stored as
+  `c_netsuiteInternalSalesOrderId`); the PO# lives in NetSuite and may not be in the 2.0 DB (the
+  SO's `customerPurchaseOrder` field — already reused as the carrier `referenceString` — vs a
+  separate linked NetSuite PO document).
+- **Phone # is REQUIRED by design (verified, kept per Eric):** config `isRequired:true` +
+  `showRequiredIndicator`, enforced by `validateFormOnSubmit`.
+- **Address block layout (Figma):** inline **left** labels (Addressee / Attention / Address 1 /
+  Address 2 / City / State / ZIP / Country) — previously `sr-only`. Residential checkbox moved
+  **below** Country with the checkbox to the **right** of the label.
+- **Carrier section = two vertical stacks (Figma, was 3 horizontal columns):** col6 = Carrier /
+  Shipment Method / Carrier Account # / Declared Cost; col7 = Reference 1 / Reference 2 / Phone # /
+  Fulfillment Location. Row container is `justify-between` so the columns fill to the right edge.
+- **Verbiage (David):** "This shipment contains a battery" → "Contains a battery"; "This shipment
+  needs a return label" → "Needs a return label".
+- **Return-label affordance:** the "Edit" link is inline to the right of the "Needs a return label"
+  label, and the return-location text ("TOGA Technology") below it is also clickable — both open the
+  Edit Return Label modal.
+- **Input UX helpers (`BaseInput`):** per-field clear "X" on address text inputs (opt-in
+  `hasClearButton` flag, via `useFormContext` `setValue`/`watch`; State/Country already have
+  react-select's clear); a **"Clear All"** link in the address header (`ClearAllAddressButton`
+  resets every address field via `useFormContext`); Declared Cost formats to 2 decimals on blur
+  (`onBlur` when `field.isCurrency`). Return modal (`ReturnShippingModal.tsx`): compact selects
+  vertically centered; Carrier Account # widened to `w-[172px]` to match Carrier.
+
+## Planned direction — "Fulfill & Ship" from an existing Item Fulfillment (future, Eric)
+
+A **third entry mode** is planned (distinct from Select-Items-create and the pencil-edit): a
+"Fulfill & Ship" button on an **existing NetSuite Item Fulfillment** punches out to the tool,
+sources item/serial info from that existing fulfillment, uses the tool for the **shipping-label
+portion only**, then pushes label/tracking data back into the Item Fulfillment. Most plumbing
+already exists from TRUE-79191: `getShipmentForEdit`/rehydrate + read-only items (source from the
+existing IF), `fulfillShipment` + `generateReturnLabel` (label), `saveShipmentToNetsuite`
+(push-back). New pieces needed: the punch-out entry carrying an IF id, and a **label-only mode**
+(skip the create step). This is a separate feature/ticket — recorded as planned direction, not done.
+
+## Sources — meeting notes / decision origins
+
+Fulfill & Ship meeting transcripts and notes live in the **Internal Knowledgebase MCP connector**
+(AWS Bedrock KBs, slug `development-team`, client `general`/`toga-technology`), searchable via
+`kb_search` — e.g. "2026-05-20 - Fulfill and Ship Dev Sync", "2026-02-27 - Fulfill & Ship Process
+Review". Use it when a decision's origin needs tracing.
+
 ## Reprint (backend-combined, 2026-07)
 
 Fulfilled-shipments view (`FulfilledShipmentsPage` → `ShipmentsCardTableForm` with
@@ -180,6 +252,19 @@ the call 403s and returns no label.
   everywhere (and `overflow-y-auto` on the `max-h-[530px]` card list in `ShipmentsCardTableForm`),
   and the fulfilled-page outer → `h-full overflow-auto`.
 
+- **"Attention" wrote to the wrong field (fixed 2026-07).** The Attention input was bound to
+  `valueKey "addressee"` — the same key as the Address name — so both wrote to `addressee` and the
+  form showed the same value twice (e.g. "Eric" in both). Rebound Attention to `"attention"`. When a
+  config-driven field mirrors another field's value, suspect a duplicated `valueKey`.
+- **The `/shipments` list is PER-SALES-ORDER (open product decision, Eric to decide).**
+  `getShipments` filters by `SalesOrders.c_netsuiteInternalSalesOrderId = <internalId>`, so
+  `/shipments` with no `internalId` shows the empty state — the tool is a per-SO **punch-out**
+  (entered from a NetSuite SO). The hamburger "Shipments" nav link (no SO context) is therefore
+  misleading. Options pending Eric's model decision (nothing changed yet): (A) keep per-SO and
+  remove/relabel the nav link; (B) add a global "All Pending Shipments" view — drop the SO filter
+  (client scoping is automatic from the JWT), but each row must then carry its own SO `internalId`
+  for the edit/fulfill links.
+
 ## Remaining work
 
 - ~~Reprint rewire~~ — done (backend `reprintLabelsApi` combine; see Reprint section).
@@ -194,7 +279,19 @@ the call 403s and returns no label.
   unit add/remove diffing against the API (the edit route already carries the fulfillment uuid);
   (b) the return modal's weight/dims/carrier fields are an **edit-trap** — see the gotcha below.
 - UPS 35-char hardening, location-scoped inventory lookup, carrier/method on the NS IF,
-  responsiveness per Figma, FedEx + UPS end-to-end verification before prod.
+  FedEx + UPS end-to-end verification before prod.
+- **Responsiveness (phase 2/3 — explicitly NOT in original scope per the 2026-02-27 Process Review
+  and 2026-05-20 Dev Sync).** David Mancol's Figma annotation **is** the spec: reduce the in-box
+  column count by 1 on narrower screens; flexible gaps that scale with screen size (min 2px, max
+  50px); may explore stacking. Owners: David Mancol (design) + Alexandra Peterson (phase 2/3). Not
+  yet implemented.
+- **Reference 1/2 value wiring** — fields render but values aren't sourced/persisted; see the form
+  section (SO# vs internal id, PO# in NetSuite) before wiring.
+- **Global-vs-per-SO Shipments list** — pending Eric's model decision; see the gotcha above.
+- **"Fulfill & Ship from an existing Item Fulfillment"** third entry mode — see Planned direction.
+
+This is the **first testable iteration** of the Figma-aligned form; a change-request list is
+expected once QA/users start.
 
 ## Deploy / provisioning requirements (per environment)
 
@@ -228,6 +325,18 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-14 — TRUE-79191 (Figma-alignment pass on the config-driven New/Edit Shipment form):
+  fixed the **Attention** field writing to `addressee` (rebound to `attention`); Figma layout
+  (inline left address labels, residential checkbox below Country, carrier section as two vertical
+  stacks with `justify-between`, David's verbiage trims); create-vs-edit titles clarified
+  ("New Shipment" vs "Edit Shipment"); added **Fulfillment Location** (read-only, sourced from the
+  SO — Eric); added **Reference 1/2** placeholder inputs (Ref1 = NetSuite SO#, Ref2 = NetSuite PO#,
+  values not wired yet — Eric); `BaseInput` per-field clear + "Clear All", Declared Cost 2-decimal
+  blur formatting; return-label "Edit" link inline + return-location text clickable. Recorded
+  decisions: create/edit entry points kept distinct (SO can have multiple shipments), Phone #
+  required, the `/shipments` list is per-SO (nav-link/global-view open item — Eric), the planned
+  **third entry mode** (Fulfill & Ship from an existing IF, label-only), David's responsiveness spec
+  (phase 2/3), and where the meeting transcripts live (`kb_search`). (mhammontree)
 - 2026-07-14 — TRUE-79191: added **edit-a-saved-pending-shipment-in-place** (pencil on `dtSubmitted==null` rows → `/edit-shipment`, `getShipmentForEdit`/`updateShipment` PUT existing records; item lines/serials read-only in v1; `CardTable` made reusable with `editIcon`/`isEditButtonDisabled`). Completed the Increment-3 **return-label** frontend (combined outbound+return PDF, return page captioned "Return Label" via a position-aligned `captions` CSV to `reprintLabelsApi`). Fixed the Declared Cost "$ -" column (field was never requested/mapped). Documented the return-modal edit-trap (only the return ADDRESS persists — weight/carrier/dims reuse outbound) and the per-env deploy/provisioning checklist + the "testing in prod = full prod release (real labels/NS IF)" decision. (mhammontree)
 - 2026-07-02 — Reprint rewired to the backend: `ShipmentsApi.ts` now calls `GET /v2/tracking-numbers/reprint` (`reprintLabelsApi`) for a combined base64 PDF built from the stored PNGs; removed the stale client-side `pdf-lib` merge. Return-label backend generation landed (`generateReturnLabel`, `returnTrackingNumberId` on the bridge). Ship-to address source resolved to `COALESCE(IF, SO)`. (mhammontree)
 - 2026-06-18 — PNG label-storage rework reflected on the frontend: labels now store as PNG and the PDF is built on the backend (`LabelPdf`), so the client-side `pdf-lib` reprint is stale and must be rewired to a backend generate endpoint. Fixed the Fulfilled Shipments responsiveness/clip bug (Reprint button unreachable at 100% zoom) — `overflow-scroll` → `overflow-auto` and gave `FulfilledShipmentsPage`'s outer its own scroll; documented the `/shipments` vs `/fulfilled-shipments` two-component trap and the `AuthLayout overflow-hidden` clip. (mhammontree)

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

@@ -21,7 +21,7 @@
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
-| [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, _underscore/Cloud.php |
+| [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.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 |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql |

package/knowledge/2.0/apps/worker2/features/oneuptime-worker2-monitoring.md

@@ -6,10 +6,12 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-13
+updated: 2026-07-14
 owners: ["jcardinal"]
 files:
   - worker2/Worker/Monitor/Compass.php
+  - worker2/Worker/Client/Compass.php
+  - worker2/composer.json
   - _underscore/Cloud.php
 related:
   - ./monitoring-framework.md
@@ -22,10 +24,10 @@ related:
 A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from
 the 1.0 `App_SystemMonitor_Compass` monitors. A worker2 cron action runs a self-contained
 check, decides pass/fail itself, and POSTs a JSON metric body to a OneUptime "Incoming
-Request" monitor — replacing the 1.0 tier's email alerts. First monitor:
-`_Worker_Monitor_Compass::OfficeDepotEdiImportQueue()`, which watches the Office Depot
-inbound EDI import backlog. Designed to be **client-agnostic** — a reusable template for
-future monitors and clients.
+Request" monitor — replacing the 1.0 tier's email alerts. The class is
+`abstract class _Worker_Monitor_Compass` and now carries a **suite of 9 monitors** covering
+the Compass USA / Office Depot integration (S3, DB, and mailbox checks). Designed to be
+**client-agnostic** — a reusable template for future monitors and clients.
 
 This is distinct from the DB-driven email-orchestrator
 [Monitoring Framework](./monitoring-framework.md) (`_Worker_Monitor` orchestrator +
@@ -37,92 +39,159 @@ that reports straight to OneUptime. Note the folder difference: these live under
 ## Key files / entry points
 
 - `worker2/Worker/Monitor/Compass.php` — `abstract class _Worker_Monitor_Compass`; each
-  monitor is a `public static` action method returning a summary string recorded in
-  `WorkerJobs` (standard worker2 action conventions). First method:
-  `OfficeDepotEdiImportQueue()`.
-- `_underscore/Cloud.php` — `_Cloud::getS3Objects()` list helper this monitor relies on
+  monitor is a `public static` action method dispatched via a `Core.CronJobs` action
+  `Monitor/Compass/<Method>` and returning a summary string recorded in `WorkerJobs`
+  (standard worker2 action conventions). `initialize()` registers the Compass client DB by
+  delegating to `_Worker_Client_Compass::initialize()` (not per-method).
+- `worker2/Worker/Client/Compass.php` — `_Worker_Client_Compass`; owns the Compass id
+  constants and the `DB_CLIENT_COMPASS` connection name the monitors query against.
+- `_underscore/Cloud.php` — `_Cloud::getS3Objects()` list helper the S3 monitors rely on
   (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
-## How it works
-
-Registered as a `Core.CronJobs` entry: schedule `*/5 6-20 * * *`, action
-`Monitor/Compass/OfficeDepotEdiImportQueue`. Each tick, `OfficeDepotEdiImportQueue()`:
+## The 9 monitors
+
+Each measures one Compass/Office Depot integration metric and pushes a decided alarm token.
+- **OfficeDepotEdiImportQueue** (S3) — counts files >10 min old in
+  `s3://agilant-as2/OfficeDepot/`, excluding `OUTBOX/`, `SENT/` and directory placeholders.
+- **CompassSalesOrderTransmission** (DB) — approved SOs (both approval stages) with
+  `c_dtTransmittedToCompass` NULL (not yet transmitted to MITS).
+- **CompassIncomingPurchaseOrders** (DB) — `SA%` SOs transmitted to MITS >4h ago (on/after
+  the 2026-04-30 cutoff) with no PO returned.
+- **CompassPurchaseOrderTransmissionsToVendors** (DB) — unsubmitted POs for monitored
+  vendors (Office Depot, Strategic Systems, Compass, Presidio) due today or earlier.
+- **EmailedAsnImport** (mailbox) — counts inbox messages in the emailed-ASN mailbox via
+  IMAP XOAUTH2 (see mailbox decision below).
+- **OfficeDepotPoAcknowledgements** (DB) — Office Depot POs with `dtAcknowledged` NULL
+  through the OD→Compass PO/SO chain.
+- **OfficeDepotNetsuiteIntegration** (DB) — OD SOs not in NetSuite
+  (`c_dtTransmittedToNetsuite` NULL) with a 30-min PO-grace subquery.
+- **OfficeDepotAsnExport** (DB) — OD orders whose ASN not sent (ItemFulfillments with
+  `c_dtEdi856Sent` NULL + a tracking number, on/after the 2025-02-04 cutover). Covers all
+  order types (SA/MR/MA) via ItemFulfillments/tracking-number logic. (The 1.0 monitor
+  TRUE-75101 in `library/app/systemmonitor/compass.php` was intentionally NOT ported — its
+  logic is superseded by this corrected definition.)
+- **OfficeDepotAs2Outbox** (S3) — counts ONLY top-level files in
+  `s3://agilant-as2/OfficeDepot/OUTBOX/` (skips subfolders + directory placeholders).
 
-1. Lists `s3://agilant-as2/OfficeDepot/` via `_Cloud::getS3Objects()`, then counts files
-   older than `AGED_FILE_MINUTES` (10), **excluding** the `OUTBOX/` and `SENT/` sub-prefixes
-   and directory-placeholder keys.
-2. Decides the alarm state itself and POSTs a JSON metric body to the OneUptime "Incoming
-   Request" monitor via `_ApiRequest` — with **logging disabled** and
-   **`throwExceptionsOnFailure` disabled**, so a failed ping never fails the worker job.
-3. On S3 failure it still POSTs `{"status":"error"}` so a blind/dead checker is
-   distinguishable from a real backlog.
+## How it works
 
-Body tokens (see the alarm contract below): `"alarm":"HIGH"` when the aged-file count is
-over threshold, else `"alarm":"OK"`; `"status":"error"` on S3 failure.
+Each monitor is a self-contained method: per-monitor config as `ALL_CAPS` local variables
+(PHP disallows `const` at function scope), plus a `$push` closure using `_ApiRequest` — all
+inside the method, so the class scales cleanly as monitors accumulate. The metric POST runs
+with **logging disabled** and **`throwExceptionsOnFailure` disabled**, so a failed ping
+never fails the worker job.
 
-### The token-based alarm contract (critical — OneUptime cannot compare numbers)
+### Payload contract & OneUptime criteria (critical — OneUptime cannot compare numbers)
 
 OneUptime **Incoming Request** monitors **cannot** do numeric threshold comparison on a
-pushed body. Verified in OneUptime source (`Common/Server/.../IncomingRequestCriteria.ts`):
-a `checkOn: "Request Body"` filter supports only `Contains` / `NotContains` **string**
-matching — it does **not** JSON-parse the body, does **not** target a nested key, and does
-**not** support Greater Than / Less Than (those filter types apply only to
-outgoing/synthetic checks like Response Time / Status Code / Metric Value).
-
-Consequence: the "dumb reporter, smart monitor" ideal (push a raw number, let OneUptime
-compare `> threshold`) is **not achievable for push monitors**. Instead the **worker makes
-the threshold decision** and emits a string token that OneUptime matches with `Contains`.
-OneUptime criteria for this monitor:
+pushed body (`checkOn: "Request Body"` supports only `Contains` / `NotContains` **string**
+matching — no JSON parse, no nested-key targeting, no Greater/Less Than). So the **worker
+makes the threshold decision** and emits a string token OneUptime matches with `Contains`.
 
+Payload body: `{status:"reporting"|"error", alarm:"HIGH"|"OK", <metric fields>, checkedAtUtc}`.
+OneUptime criteria:
 - Request Body **Contains** `"alarm":"HIGH"` → Offline + incident.
-- Request Body **Contains** `"status":"error"` → Offline + incident.
-- **Online** requires BOTH "received in 1 min" AND Request Body **Contains** `"alarm":"OK"`
-  — so status does not flap back to Operational while the alarm is still HIGH.
+- Request Body **Contains** `"status":"error"` → Offline + incident (distinguishes a
+  blind/dead checker from a real backlog).
+- **not received in 10 min** → Degraded.
+- **received in 1 min AND Contains `"alarm":"OK"`** → Online (the OK-gated recovery
+  prevents flapping back to Operational while the alarm is still HIGH).
+- **not received in 15 min** → Offline.
 
 ### Heartbeat / cron cadence timing
 
-Heartbeat missed-ping thresholds must match the cron cadence. With a **5-minute** push
-cadence: **Degraded at 10 min / Offline at 15 min**. An initial 3/5-min setting
-false-alarmed on a single missed ping. The Office Depot backlog alarm threshold is
-**10 aged files**.
+The 10-min-Degraded / 15-min-Offline heartbeat thresholds pair with a **5-minute** cron
+cadence. An initial 3/5-min setting false-alarmed on a single missed ping.
 
 ## Provisioning a monitor (runbook)
 
-1. Write the monitor method on `_Worker_Monitor_Compass` (or a new `_Worker_Monitor_<X>`
-   class). Keep it **fully self-contained**: no private helpers, no class constants — all
-   per-monitor config lives as `ALL_CAPS` local variables inside the method (PHP disallows
-   `const` at function scope), so the class stays clean as monitors accumulate.
-2. Provision the OneUptime monitor by cloning the reusable import/export template at
-   `monitor-import-OfficeDepot-EDI-1.0.json` (a local dev artifact, not a repo file) and
-   importing it into OneUptime; wire the Contains criteria above.
-3. Register the OneUptime push URL as a local/constant in the monitor method — it is a
+1. Write the monitor method on `_Worker_Monitor_Compass` (or a new `_Worker_Monitor_<X>`),
+   fully self-contained per above.
+2. Set the OneUptime heartbeat URL as an in-file constant/local in the method — it is a
    **push credential**; never log it and never record its value in a doc.
-4. Add the `Core.CronJobs` row (`action = 'Monitor/<Class>/<Method>'`) with the schedule,
-   and set OneUptime's Degraded/Offline thresholds to match the cadence.
+3. Provision the OneUptime monitor by importing the monitor's OneUptime resource-export
+   JSON (authored under a local staging dir, e.g. `d:\STAGE` — these are import artifacts,
+   not repo files) and wiring the Contains criteria above.
+4. Add the `Core.CronJobs` row: `action = 'Monitor/Compass/<Method>'`, schedule
+   `*/5 * * * *`, `maxExecutionTime` 120s, `parameters` NULL. Then deploy worker2.
+
+### CronJob scheduling for these monitors
+
+Run **all hours**, `*/5 * * * *` (every 5 min) — **not** the 1.0 `6-20` business-hours
+window. Integration backlogs must be caught outside business hours too.
+
+## DB monitor conventions
+
+- Query via `new _Query($sql, _Worker_Client_Compass::DB_CLIENT_COMPASS)`.
+- `_Query::fetchRow()` returns an **OBJECT** (`$row->pendingCount`), not an array.
+- The client DB connection is registered by the class `initialize()` hook (delegating to
+  `_Worker_Client_Compass::initialize()`), not per method.
+- All Compass id constants live on **`_Worker_Client_Compass`** (VENDOR_ID__*,
+  CUSTOMER_ID__*, UUID_*, DB_CLIENT_COMPASS) — moved out of the 1.0 `App_Client_Compass`.
+  Never reference `App_Client_Compass` from worker2 (see gotcha below).
+
+## Mailbox monitoring (EmailedAsnImport) — IMAP XOAUTH2, not Graph
+
+Use **IMAP with XOAUTH2** via the `javanile/php-imap2` library (mirrors the 1.0 monitor),
+**not** Microsoft Graph. The Graph `messages/$count` approach returned HTTP 403 because the
+app lacks Graph `Mail.Read` application consent and Entra consent cannot be obtained. IMAP
+XOAUTH2 uses the app's existing `IMAP.AccessAsApp` permission (the 1.0 monitor already
+relies on it) — no new Entra consent.
+
+- OAuth token scope: `https://outlook.office365.com/.default`.
+- Then `imap2_open('{outlook.office365.com:993/imap/ssl/novalidate-cert}INBOX', $mailbox,
+  $accessToken, OP_XOAUTH2|OP_READONLY)` → `imap2_num_msg`.
+- Guarded by `function_exists('imap2_open')` so a missing library reports `status:error`
+  rather than throwing an uncatchable `Error`.
+- Requires the `[mailbox_compass_statuses]` config group (`tenant_id`, `client_id`,
+  `client_secret`, `mailbox`) in each `Config/*.ini`, and **ext-imap enabled** on the
+  worker EB tier. The `client_secret` is a credential — it lives in the ini config group,
+  never in a doc.
+
+## Composer / deploy dependency
+
+`worker2/composer.json` added `javanile/php-imap2` (`^0.1.10`) for the IMAP path. The
+`composer require` refreshed `composer.lock`, bumping in-range packages (sentry, aws-sdk,
+phpseclib, phpspreadsheet) and transitive majors (psr/log 1→3, symfony/options-resolver
+5.4→7.4, paragonie/constant_time_encoding 2→3). `composer audit` reported 16 advisories.
+**Review the lockfile diff + `composer audit` before a production deploy.**
 
 ## Client variations
 
-None — the pattern is shared infrastructure. The first monitor targets Compass USA's
-Office Depot inbound EDI (vendor ODP), but the class and template are client-agnostic;
-clone the template to provision the same check for another client.
+None — the pattern is shared infrastructure. This suite targets Compass USA's Office Depot
+integration, but the class and templates are client-agnostic; clone to provision the same
+check for another client.
 
 ## Gotchas / known issues
 
 - OneUptime Incoming Request bodies are matched **as strings only** (Contains/NotContains) —
   no numeric comparison, no JSON key targeting. Always emit a decided token, never a raw
   number, for push monitors.
-- The OneUptime push URL is a credential — keep it as a local/constant in the method; never
-  log it or write its value into knowledge docs.
+- The OneUptime push URL is a credential — keep it as an in-file constant in the method;
+  never log it or write its value into knowledge docs.
+- **`App_Client_Compass` (1.0) is unavailable in worker2.** Referencing it throws a
+  class-not-found `Error`, which `catch (Exception)` does NOT catch — the whole monitor
+  dies uncaught. Use `_Worker_Client_Compass::` constants only.
+- `_Query::fetchRow()` returns an object, not an array — access `$row->field`.
 - Keep the metric POST non-fatal (`throwExceptionsOnFailure` off) so a monitoring outage
   never breaks the worker job it rides in.
+- The `agilant-as2` S3 bucket is in **us-west-2**, not the config-default us-east-1 — S3
+  monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-07-14 — Grew `_Worker_Monitor_Compass` to a 9-monitor suite (S3/DB/mailbox);
+  finalized the payload contract (`status`/`alarm`/`checkedAtUtc`) and the not-received
+  10-min-Degraded / 15-min-Offline + OK-gated recovery criteria; standardized cron on
+  `*/5 * * * *` all-hours (120s); chose IMAP XOAUTH2 over Graph for the emailed-ASN mailbox
+  (Graph 403, no Entra consent); moved Compass id constants to `_Worker_Client_Compass` and
+  registered its DB via `initialize()`; added `javanile/php-imap2`. (jcardinal)
 - 2026-07-13 — Ported Compass monitoring from the 1.0 worker tier into worker2 reporting to
-  OneUptime; built `_Worker_Monitor_Compass::OfficeDepotEdiImportQueue()` (Office Depot EDI
-  backlog), the token-based alarm contract (OneUptime Incoming Request can only string-match
-  Contains, not compare numbers), and the 5-min cadence → 10/15-min heartbeat timing. (jcardinal)
+  OneUptime; built `OfficeDepotEdiImportQueue()`, the token-based alarm contract, and the
+  5-min cadence → 10/15-min heartbeat timing. (jcardinal)
 
 ## Related docs
 - [Monitoring Framework](./monitoring-framework.md) — the parallel DB-driven, email-alert monitoring pattern
 - [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md) — `_Cloud::getS3Objects()` used to list the EDI bucket
 - [OneUptime 1.0 worker uptime monitoring](../../../1.0/apps/worker/features/oneuptime-worker-uptime-monitoring.md) — the 1.0 push-heartbeat predecessor
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 31 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 32 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 29 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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