toga-ai 1.0.133 → 1.0.135

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [_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 |
-| [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/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/Carriers/Ups/Ups.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 |
+| [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/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.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 |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -6,12 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-16
+updated: 2026-06-18
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Model/Client/ItemFulfillments/TrackingNumber.php
+  - _underscore/Component/Library/LabelPdf/LabelPdf.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
@@ -29,21 +31,26 @@ related:
 
 Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label
 (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracking
-number and label attached. Includes the **authoritative label-storage architecture
-decision** (dev lead Jeff, June 2026) that supersedes what the code currently does.
+number and label attached. As of 2026-06 the label is requested + stored as a raw
+**PNG** and the printable PDF is **generated on demand** via `_Component_Library_LabelPdf`
+(FPDF) — superseding the old Labelary ZPL→PDF approach.
 
 ## Key files / entry points
 
 - `upsShipmentApi` / `fedexShipmentApi` (scripted APIs on
-  `Model/Client/ItemFulfillment.php`): build the carrier request, call the carrier,
-  (currently) convert ZPL→PDF via Labelary, save the PDF to NetSuite File Cabinet +
-  the DB storage field, return `{ trackingNumber, pdfLabel, fileInternalId }` or
-  `{ error, trackingNumber }`. UPS path now checks `$shipmentResponse->success` and
-  fast-fails on an empty service code (it previously swallowed UPS errors and surfaced
-  a misleading "Failed to save PDF to NetSuite"). These methods (plus `fulfill` and
-  `createNetsuiteItemFulfillment`'s package-detail query) resolve the tracking record by
+  `Model/Client/ItemFulfillment.php`): build the carrier request **requesting a PNG label**,
+  store the raw PNG on `TrackingNumbers.labelPdfFile`, generate a printable PDF via
+  `_Component_Library_LabelPdf`, save that PDF to the NetSuite File Cabinet, and return
+  `{ trackingNumber, pdfLabel, fileInternalId }` or `{ error, trackingNumber }`. UPS path
+  checks `$shipmentResponse->success` and fast-fails on an empty service code (it previously
+  swallowed UPS errors → misleading "Failed to save PDF to NetSuite"). These methods (plus
+  `fulfill` and `createNetsuiteItemFulfillment`'s package query) resolve the tracking record by
   joining **`ItemFulfillments_TrackingNumbers`** (the bridge); they previously joined the
   dropped `ItemFulfillmentPackages` table — see Gotchas.
+- `_Component_Library_LabelPdf::buildFromPngLabels($labels)`
+  (`Component/Library/LabelPdf/LabelPdf.php`): builds a multi-page 4x6 PDF from raw PNG label
+  images (one per page, optional "Return Label" caption) via FPDF; returns the PDF as a binary
+  string. Built to take N pages so a combined shipping + return label is one print-once PDF.
 - `_Component_Library_Carriers_Ups::submitShipmentRequest`
   (`Component/Library/Carriers/Ups/Ups.php`): returns `{ success, errorMessage,
   trackingNumber, encodedLabel }`.
@@ -58,21 +65,24 @@ decision** (dev lead Jeff, June 2026) that supersedes what the code currently do
   (`_Model_Growrk_ItemFulfillment extends _Model_Client_ItemFulfillment`), not the base
   model.
 
-## Label-storage architecture (AUTHORITATIVE — dev lead Jeff, 2026-06)
+## Label-storage architecture (implemented 2026-06; dev lead Jeff)
 
-Supersedes the Labelary-PDF + manual-S3 approach:
+The label is **stored as the raw carrier PNG** (not a Labelary PDF) and the printable PDF is
+**generated on demand** server-side:
 
-1. **Do NOT touch S3 by hand.** The model's `FIELD_STORAGE` abstraction, accessed via
-   the 2.0 API, already handles label fetch + storage.
-2. **Store the raw carrier response as a GIF**, not a Labelary-converted PDF.
-3. **Generate the printable PDF on demand**, combining the shipping label AND the
-   return label into one PDF (the browser print dialog handles one file at a time).
-   Leaning **backend** generation — `pdf-lib` (client-side) cannot embed GIF.
+1. **Carrier returns PNG.** UPS via `[ups] label_format = "PNG"` config (the client's
+   `getLabelFormat()` reads it; defaults ZPL); FedEx via `$shipmentRequest->labelImageType =
+   'PNG'` + `labelStockType = 'PAPER_4X6'`. Labelary is gone.
+2. **Store the raw PNG** on `TrackingNumbers.labelPdfFile` (a `FIELD_STORAGE` field; the name is
+   retained though it now holds a PNG) via the model/S3 mechanism — never touch S3 by hand.
+3. **Generate the PDF on demand** with `_Component_Library_LabelPdf::buildFromPngLabels([...])`
+   — FPDF, one label image per 4x6 page, optional "Return Label" caption — for the immediate
+   display + the NetSuite File Cabinet copy.
 
-Not yet implemented. Open questions before building: backend vs frontend for the
-GIF→PDF step; which existing 2.0 label-fetch/storage calls to build on. Combining
-shipping + return also depends on the return-label flow existing — outbound-only can
-come first.
+Jeff approved **PNG over GIF**: a PDF lib embeds PNG with **no extra extension** (FPDF parses
+non-alpha PNG in pure PHP — no GD/Imagick). Remaining wiring: the reprint/return-label combine
+(frontend calls a backend generate endpoint instead of the client-side `pdf-lib` merge), and
+the return-label generation itself.
 
 ## `FIELD_STORAGE` mechanics (reference)
 
@@ -119,8 +129,33 @@ attempted.
   bridge-linked `TrackingNumbers` row shows `number = NULL` after a "successful" ship. Backend
   change — only effective once deployed to beta. Worth grepping `ItemFulfillmentPackage::TABLE`
   across `_underscore`/`api2`/`library` for the same staleness elsewhere.
+- **FPDF is a Composer dep, and `_Loader` throws on it.** `setasign/fpdf` lives in api2's
+  `vendor/` (not an `_underscore` Component library), so the framework autoloader throws
+  "could not find source file for 'FPDF'". `LabelPdf` wraps `new \FPDF()` with
+  `_Loader::setThrowExceptionInAutoloaderIfClassNotFound(false)` (restored after) so the chain
+  falls through to Composer's autoloader — same pattern as `Model/Client/TableView.php`.
+- **Commit `composer.lock`.** EB runs `composer install` (installs strictly from the lock). If
+  `composer.json` declares `setasign/fpdf` but the lock wasn't committed, the dep never installs
+  → runtime `Class "FPDF" not found`. Verify `vendor/setasign/fpdf/` exists after deploy.
+- **FedEx tracking-cred config fallback.** `_Config::fedex('tracking_client_id')` **throws** when
+  the key is missing; the intended `?:` fallback to the ship `client_id`/`client_secret` only
+  works with the no-throw second arg: `_Config::fedex('tracking_client_id', false) ?: …` (same as
+  the UPS client). Without it, FedEx shipping dies with "Configuration parameter
+  'tracking_client_id' … has not been defined".
+- **`labelPdfFile` (`FIELD_STORAGE`) write can silently skip** when set on a lazy
+  `new _Model_Client_TrackingNumber($id)` (never loaded): `number` (a real column) saves but the
+  storage write is skipped (no error, no S3 object — and `copyFileToS3` re-throws, so a skip ≠ a
+  failed write). Likely needs `->load()` before setting `labelPdfFile`. **Open issue** — the S3
+  label save was still not landing as of 2026-06-18.
+- **FPDF can't embed alpha-channel or interlaced PNG** — carrier label PNGs must be flat raster.
+  If one isn't, `buildFromPngLabels` throws; fix = GD normalize (flatten/de-interlace) or TCPDF.
+- **UPS shipper number must match the endpoint.** Beta hits the UPS **CIE test** endpoint
+  (`wwwcie.ups.com`); a production account number there returns `120100`/`120121`
+  ("missing/invalid shipper number" / "cannot be used"). Use a CIE-enabled shipper number for
+  test, or point at prod UPS. `SHIPPER_NUMBER` is a hardcoded constant in the UPS client.
 
 ## Change history
+- 2026-06-18 — Implemented the label-storage rework: request PNG from UPS/FedEx, store the raw PNG, generate the printable PDF on demand via the new `_Component_Library_LabelPdf` (FPDF); dropped Labelary. Added the FedEx tracking-cred config-fallback fix and the `_Loader`→Composer FPDF autoloader toggle. Open: the `labelPdfFile` S3 write still skips on a lazy-model save. (mhammontree)
 - 2026-06-16 — Repointed the carrier-label/NS-IF tracking-number queries (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) from the dropped `ItemFulfillmentPackages` table to the `ItemFulfillments_TrackingNumbers` bridge — they had been saving the label/`number` to the wrong/null record (reprint `labelPdfFile` null; NS IF missing tracking). Confirmed working on beta. (mhammontree)
 - 2026-06-10 — Documented carrier shipping label mechanics (UPS/FedEx) + the authoritative GIF label-storage decision and NetSuite IF attachment. (mhammontree)
 

package/knowledge/2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: workflow
 status: active
-updated: 2026-06-16
-owners: ["jcardinal"]
+updated: 2026-06-18
+owners: ["jcardinal", "mhammontree"]
 files: []
 related: []
 ---
@@ -68,6 +68,27 @@ anything repo-specific. The AWS CLI cannot introspect the GitHub App installatio
 account proves it is not a GitHub/repo/branch problem — connections and App installations are
 per-account, so the fault is local to the failing account's connection.
 
+### Gotcha: a terminated EB instance must be manually re-registered with the load balancer
+We do **not** pay for EB-managed (auto) registration of instances on the load balancer. When you
+terminate an instance — e.g. to force a clean redeploy / fresh `composer install` — the
+**replacement instance is NOT automatically added as an LB target**. Until you register it by
+hand (EC2 → the new instance → add it as a target in the environment's target group), the LB
+keeps routing to the old/healthy target (or none), so your freshly-deployed code **never serves
+traffic** and the deploy looks like it "didn't take" / the bug looks unfixed. After terminating:
+grab the new instance ID, register it as a target, wait for it to go healthy, then test. This
+masquerades as deploy-lag — confirm the LB is actually pointing at the new instance before
+debugging the code. (Seen 2026-06-18 chasing a "missing FPDF / old code still running" loop on
+beta that was really the LB still pointing at a terminated instance's replacement that was never
+registered.)
+
+### On-instance composer install (when a dep is missing post-deploy)
+If a Composer dep is missing on the running instance (e.g. `Class "FPDF" not found` because
+`composer.lock` wasn't committed), you can install it on the box over SSH/PuTTY — but
+`composer require setasign/fpdf:^1.8` must have **no space** after the colon (`fpdf: ^1.8`
+parses `^1.8` as a separate package and errors), and run it as the web app user / `chown` the
+result so the webserver can read `vendor/`. The real fix is to **commit `composer.lock`** so EB's
+`composer install` picks it up — the on-instance install is a stopgap that a redeploy wipes.
+
 ### CloudShell triage commands (read-only)
 ```bash
 PIPELINE="<pipeline-name>"; REGION="us-east-1"
@@ -82,6 +103,7 @@ aws codeconnections get-connection --connection-arn "<CONN_ARN>" --region "$REGI
 ```
 
 ## Change history
+- 2026-06-18 — Added two EB-instance gotchas surfaced during the TOGa Supply beta/prod label deploys: (1) terminated instances must be **manually re-registered** as LB targets (we don't pay for auto-registration) — until then the new code never serves traffic and looks like deploy-lag; (2) on-instance `composer require` stopgap syntax (no space after the colon, fix root cause by committing `composer.lock`). (mhammontree)
 - 2026-06-16 — Documented after a pipeline (API-QC-Security, account 975050298201) failed every
   run at Source with "[GitHub] GitHub returned an Internal Error"; connection was AVAILABLE and
   IAM was correct — root cause was a pending GitHub App access-request approval in the

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/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, _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/api/UpdateShipmentApi.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/FulfilledShipments/view/FulfilledShipmentsPage.tsx, _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

@@ -6,15 +6,17 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-16
+updated: 2026-06-18
 owners: [mhammontree]
 files:
   - 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/api/UpdateShipmentApi.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/FulfilledShipments/view/FulfilledShipmentsPage.tsx
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Trait/Netsuite/ItemFulfillment.php
   - _underscore/Component/Library/Carriers/Ups/Ups.php
@@ -57,13 +59,18 @@ GroWrk, June 2026); FedEx + UPS both need verification before prod.
    `saveShipmentToNetsuite` → `createNetsuiteItemFulfillment`, which attaches the label
    to the IF **after** creating it (the IF doesn't exist yet when the label is bought).
 
-## Reprint (first pass — being reworked)
+## Reprint (being rewired to the backend)
 
-Fulfilled-shipments view: multi-select shipments, merge each stored label into one
-multi-page PDF with `pdf-lib`, print once. **Superseded by the label-storage decision**
-(see the carrier-shipping-labels doc): labels will be stored as raw carrier GIFs and
-the combined PDF generated on demand — note `pdf-lib` cannot embed GIF, so generation
-likely moves to the backend.
+Fulfilled-shipments view (`FulfilledShipmentsPage` → `ShipmentsCardTableForm` with
+`isFulfilledShipmentsView`): multi-select shipments, merge each stored label into one
+multi-page PDF, print once. The label-storage rework (see the carrier-shipping-labels doc)
+now stores the raw carrier **PNG** on `TrackingNumbers.labelPdfFile` and builds the PDF on the
+**backend** (`_Component_Library_LabelPdf`/FPDF). So the current client-side `pdf-lib` merge —
+which reads `labelPdfFile` expecting a base64 **PDF** — is now **stale**: it receives a PNG.
+Reprint must be rewired to call a backend generate endpoint that returns the combined
+(shipping + return) PDF; until then it won't produce a printable label even when one is stored.
+The reprint reference was also corrected from `shipment.itemFulfillmentPackages` to
+`itemFulfillmentTrackingNumbers` (bridge migration).
 
 ## Gotchas / known issues
 
@@ -117,11 +124,24 @@ likely moves to the backend.
   `item-fulfillment-tracking-numbers` bridge requires the bridge record's ACL logic-group
   chain to exist for the user's role, or it 403s and `itemFulfillmentTrackingNumbers` returns
   `null` (so reprint has no label). See the tracking-number-bridges doc's ACL gotcha + fix.
+- **Two separate page components + a scroll/clip trap.** `/shipments` renders `ShipmentsPage`;
+  `/fulfilled-shipments` renders `FulfilledShipmentsPage` — **separate components** (a fix to one
+  does NOT touch the other; the shared list is `ShipmentsCardTableForm`). Both pages used
+  `overflow-scroll` across nested containers — Tailwind `overflow-scroll` forces *always-visible*
+  scrollbars (the "scrollbars everywhere" look) — and `FulfilledShipmentsPage`'s outer had
+  `h-full min-h-full max-h-full` with **no overflow**, so its content (incl. the Reprint button
+  below the `min-h-[862px]` form) was clipped by `AuthLayout`'s `overflow-hidden` with no way to
+  scroll to it — the button was only reachable when zoomed out. Layout chain: `AuthLayout`'s
+  content area is `h-[calc(100vh-80px)]` inside `overflow-hidden`, so **each page's outer must own
+  its own scroll** (`h-full overflow-auto`). Fix (2026-06-18): `overflow-scroll` → `overflow-auto`
+  everywhere (and `overflow-y-auto` on the `max-h-[530px]` card list in `ShipmentsCardTableForm`),
+  and the fulfilled-page outer → `h-full overflow-auto`.
 
 ## Remaining work
 
-- Label storage + reprint rework per the carrier-shipping-labels doc (raw GIF +
-  on-demand combined PDF).
+- Reprint rewire: call the backend `LabelPdf` generate endpoint (PNG → combined PDF) instead
+  of the stale client-side `pdf-lib` merge (per the carrier-shipping-labels doc). The backend
+  half (PNG store + on-demand PDF) is done.
 - Return-label flow: `returnTrackingNumberId` (nullable) on `ItemFulfillmentItemUnits`;
   "needs return label" checkbox; return-address editable combo ("Rolodex pattern" of
   client locations, overridable, validated); "return label" text on return pages of the
@@ -138,5 +158,6 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 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)
 - 2026-06-16 — Drove the full beta flow green for UPS/GroWrk. Updated the save step to the `/item-fulfillment-tracking-numbers` bridge (FE commit `b5c16592d`, key `itemFulfillmentTrackingNumbers`). Added gotchas: local-FE↔deployed-beta-BE skew, `dtSubmitted` fulfilled/pending gating, `createNetsuiteItemFulfillment` orderLine fragility on partial/already-fulfilled orders, and the bridge-ACL 403 that nulls tracking/labels (reprint). (mhammontree)
 - 2026-06-10 — Documented the Fulfill & Ship flow (SO sync, label purchase, NetSuite IF creation, success gating, reprint). Driven green on beta for UPS/GroWrk; FedEx + prod verification pending. (mhammontree)

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-17
+updated: 2026-06-18
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite.php
@@ -90,7 +90,15 @@ second, independently-gated concern in the same handler.
 
 1. `findClickupTaskByOpportunityNumber($tranId)` — GET the list filtered by the `Opportunity #`
    custom field (`include_closed=true&include_archived=true&custom_fields=[{field_id,operator:'=',value}]`).
-2. **Match → `updateTask()`**: **diffs first, writes only what changed** (change-detection backstop,
+2. **Match → `updateTask()` — but ONLY when `UPDATE_CLICKUP === true`.** `const UPDATE_CLICKUP = false`
+   ([Opportunity.php](worker2/Worker/Netsuite/Opportunity.php)) is a **deliberate one-way guard, NOT a
+   temporary backstop to flip**: once a ClickUp opportunity task exists, ClickUp is the source of truth
+   for it, and a NetSuite edit must **not** clobber edits made on the ClickUp side. With the flag false
+   (its production value), a match returns `skipped update (update disabled)` and ClickUp is left
+   untouched — so the *designed, correct* behavior of a NetSuite edit to an opportunity that already has
+   a task is: **Forecast upserts, ClickUp unchanged.** Do not "enable updates" by flipping it. The
+   change-detection logic below only runs in the (currently-off) update path. When enabled, it:
+   **diffs first, writes only what changed** (change-detection backstop,
    since 2026-06-17). PUT name/description **only if** one differs; POST **only** the custom fields
    that differ (each to `/task/{id}/field/{fieldId}` — ClickUp has no bulk custom-field set). When
    nothing differs it writes nothing and returns `task unchanged`. This kills the no-op-write echo: a
@@ -204,6 +212,13 @@ None — platform-wide Forecast sync.
   (`https://webhook.togahub.com/netsuite`) with `debugWrap` off. Also flip the enqueuer deployment
   `Testing → Released` (Testing fires only for the deploying user). Full checklist in
   `DEPLOY_RUNBOOK.md` §6.
+- **ClickUp's `=` custom-field filter is substring/prefix, NOT strict equality.** `findClickupTaskByOpportunityNumber($tranId)`
+  filters the `Opportunity #` field with `operator:'='`, but for a short-text custom field ClickUp matches
+  loosely: a lookup for `74266` still returns a task whose value is `74266--` (confirmed live 2026-06-18).
+  So **appending** to the dedup value does NOT defeat the match — to force a dedup *miss* (e.g. to exercise
+  the create branch) you must change the **leading** content or clear the field entirely. Verified both ways
+  on opp 74266/internalId 7161054: `74266--` → matched (update branch, skipped); field removed → missed
+  (create branch, new task `868k2rfj8`).
 - **ClickUp dedup keys on the `Opportunity #` field, not a DB column.** We deliberately did NOT add
   a `clickupTaskId` column — the dedup lookup queries ClickUp itself by `Opportunity #` (= tranId).
   Consequences to know:
@@ -262,6 +277,16 @@ same **skip-if-unchanged** compare on the extracted values, and **actor-identity
 trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
 
 ## Change history
+- 2026-06-18 — **Verified live in production** (no code change): real NetSuite SuiteScript webhooks
+  (`user-agent: NetSuite/2026.1`) arrive at `webhook.togahub.com/netsuite` and process successfully
+  (e.g. opp 6926224 PUT). Clarified that **`UPDATE_CLICKUP = false` is an intentional one-way guard**
+  (NS edits must not overwrite ClickUp-side edits), not a flag to flip — so "NS edit → Forecast upserts,
+  existing ClickUp task untouched" is the *designed* behavior. Documented that ClickUp's `=` custom-field
+  filter is **substring/prefix**, not exact (a `74266` lookup matched `74266--`); confirmed both dedup
+  branches on opp 74266/internalId 7161054. Testing note: the webhook needs the **internalId**, not the
+  opportunity number — resolve it via `Forecast.Opportunities.netsuiteOpportunityInternalId` for a given
+  `opportunityNumber` (tranId). Fire a manual test with
+  `curl -X POST https://webhook.togahub.com/netsuite -d '{"recordType":"opportunity","eventType":"edit","internalId":<id>}'`. (dfranks)
 - 2026-06-17 — ClickUp **change-detection backstop** added to `updateTask()`: diff before write, skip
   no-op syncs (`task unchanged`), PUT name/description only when changed, POST only changed custom
   fields. `findClickupTaskByOpportunityNumber()` now returns the full task object; added

package/package.json

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