toga-ai 1.0.119 → 1.0.121

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
+| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |

package/knowledge/1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md

@@ -0,0 +1,134 @@
+---
+title: Compass Partial In-Transit & Delivered Emails (per package)
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["bala"]
+files:
+  - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
+  - worker/crons/toga2/compass/workflow/test_partial_in_transit_email.php
+  - worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php
+  - worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php
+related: []
+---
+
+## Summary
+
+Compass USA and Compass Canada send a **per-package** in-transit email (and a matching
+delivered email) instead of one email listing the whole order. For each tracking number the
+cron builds three zones: **Items in this shipment** (just that package), **Already shipped**
+(earlier packages), and **Remaining items being prepared** (ordered minus what shipped in this
+and earlier packages). The dynamic HTML is injected into a stored `EmailTemplates` body via the
+`sendEmail` scripted API. Canada renders EN or FR per the user's language setting.
+
+## Key files / entry points
+
+- `worker/crons/toga2/compass/update_salesorder_status_from_odp.php` — Compass USA prod cron.
+- `worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php`
+  — Compass Canada prod cron.
+- `*/workflow/test_partial_in_transit_email.php` — read-only prod test scripts for each client
+  (email goes only to a test recipient, no DB writes). Use these to preview rendering.
+- Shared helper set in each cron: `getOrderFulfillmentData`, `buildItemRowsHtml`,
+  `buildSectionHeaderHtml`, `buildPackageBlockHtml`, `buildTrackingUrl`, `buildOrderItemsHtml`.
+
+## How it works
+
+1. **Driving query** finds shipped sales orders and their tracking numbers (`computedStatusSlug
+   = 'shipped'`, `c_dtInTransitEmailSent IS NULL`, date cutoff) via the ASN chain
+   (`AdvanceShippingNoticeItemUnits_TrackingNumbers`), one row per `TrackingNumbers.number`.
+2. Per tracking number: skip if the carrier API already reports delivered.
+3. **`getOrderFulfillmentData`** returns the order's packages (grouped by tracking number,
+   ordered by `dtCreated`) and ordered items, sourced from the **`ItemFulfillmentItems`** line
+   bridge (`ItemFulfillmentItems` → `ItemFulfillments` (scoped to the buyer SO) →
+   `ItemFulfillmentItems_TrackingNumbers`).
+4. The current package's index determines which packages are "Already shipped" (earlier
+   `dtCreated`). "Remaining being prepared" is **cumulative as of this package**: ordered minus
+   what shipped in this and all earlier packages, so later-package items still show as remaining
+   in an earlier package's email.
+5. Build `shipmentItemsHtml` + `additionalSectionsHtml` + `statusMessage`, then send via
+   `App_Api_Toga2::send(..., 'POST', '/email-templates/sendEmail', $payload, [], true)`.
+6. On a successful (non-throwing) send, set `c_dtInTransitEmailSent = NOW()`.
+
+### Tracking-URL building (`buildTrackingUrl`)
+
+The "Track Shipment" button and each per-package link resolve in this precedence:
+1. carrier `ShippingCarriers.urlLinkPrefix` + tracking number — **only when the prefix is an
+   append-template** (ends in `=`, or a non-root path ending in `/` like `/odn/`); this yields
+   the modern carrier URL.
+2. else `TrackingNumbers.trackingUrl` (covers freight carriers whose prefix is a bare homepage).
+3. else the homepage-style prefix as-is.
+4. else `App_Misc::generateTrackingNumberLink()`.
+The append-template guard (via `parse_url`) is what stops a bare `https://carrier.com/` from
+getting a tracking number glued onto it. Both queries `LEFT JOIN ShippingCarriers` and select
+`urlLinkPrefix AS carrierUrlPrefix`.
+
+### POST body transport (HTTP 414 fix)
+
+Scripted-API args ride in the URL query string by default
+(`App_Api_Toga2::sendUsingAccessToken` → `assembleOptions`). A multi-package email's HTML
+overflowed Apache's `LimitRequestLine` (~8190) → **HTTP 414**. The fix sends the variables in
+the **POST body** (`$payload`, empty options) and relies on the api2 POST scripted-API body
+merge. `throwExceptionOnApiError = true` so a failed send throws and the cron does **not** mark
+the tracking number as emailed (it retries next run).
+
+### Styling spec (matches Figma)
+
+- Section headers (`buildSectionHeaderHtml`): all **18px**; first ("Items in this shipment")
+  dark `#1a1a1a` weight 700; muted ("Already shipped" / "Remaining items being prepared")
+  `#535662` weight 600, each preceded by a 30px / 1px divider / 30px block.
+- Item rows (`buildItemRowsHtml`): title, P/N, and Qty all **14px**. Title medium (500) dark
+  `#111928`; P/N `#666666`; Qty regular dark `#111928`.
+- **20px** gap between consecutive "Already shipped" packages (16px spacer + 4px heading top).
+
+## Data model
+
+- `TrackingNumbers`: `number`, `trackingUrl`, `shippingCarrierId`, `dtCreated`, `status`,
+  `c_dtInTransitEmailSent` (the idempotency flag the cron sets).
+- `ShippingCarriers`: `urlLinkPrefix` (carrier URL template).
+- `ItemFulfillmentItems` / `ItemFulfillmentItems_TrackingNumbers` — package contents (line
+  bridge). `ItemFulfillments.salesOrderId` ties a package to the buyer SO.
+- `EmailTemplates` — the stored template body with `{placeholder}` tokens.
+
+## Client variations
+
+- **Compass USA** — English only; `update_salesorder_status_from_odp.php`.
+- **Compass Canada** — EN/FR by `UserGlobalSettings.settingId = 2` (FR when the value starts
+  with `fr`); French section labels and a French (HTML-entity) status message; uses
+  `htmlentities` in the section header builder and a 7-param French-aware `buildPackageBlockHtml`.
+
+## Gotchas / known issues
+
+- **Canada now uses the `ItemFulfillmentItems` line bridge, not the ASN chain**, for
+  `getOrderFulfillmentData` — same query as Compass USA. Canada was originally on the ASN chain
+  because it had **zero `ItemFulfillmentItems`**; if that line-bridge data is not populated for a
+  Canada order, `getOrderFulfillmentData` returns no packages and the cron falls back to the
+  full email. Verify line-bridge data exists for Canada before relying on the partial path.
+- **Line bridge is moving-forward only** — it began populating ~2026-06-12; pre-cutoff tracking
+  numbers are intentionally out of scope (driving-query date cutoff).
+- The driving query still uses the ASN chain (to find shipped orders + tracking) for **both**
+  clients — that is correct and unrelated to the package-contents source.
+- Test scripts only ever email a test recipient and never write `c_dtInTransitEmailSent`.
+- **Not yet deployed.** These crons depend on the api2 POST scripted-API change and the
+  `RecordScripts`/`AclRecordScripts` registration (prod done, beta pending) — see related docs.
+
+## Change history
+
+- 2026-06-18 — Switched Canada `getOrderFulfillmentData` from the ASN chain to the
+  `ItemFulfillmentItems` line bridge (match Compass USA); item info all 14px. (bala)
+- 2026-06-18 — Brought both prod crons to parity: per-package partial assembly, `buildTrackingUrl`
+  carrier-URL precedence, POST body transport + `throwExceptionOnApiError=true`, mark-sent only
+  on success; restored crons after a git stash/merge had duplicated helper functions. (bala)
+- 2026-06-17 — Styling pass: 18px headers, medium dark item titles, regular dark Qty, 20px
+  between packages. (bala)
+
+## Related docs
+
+- `2.0/apps/_underscore/features/email-template-sending.md` — the `sendEmail` scripted API +
+  its silent-failure hardening.
+- `2.0/apps/api2/features/scripted-api-post-body-args.md` — POST + body-args support that makes
+  the body transport work.
+- `clients/compass-usa/profile.md`, `clients/compass-canada/profile.md`.

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -57,6 +57,9 @@ the window's upper bound after each successful section.
 
 ### Adding a new client (the full recipe)
 
+A wrapper + schedule alone is **not enough** — the client must also be provisioned in three
+places or the sync runs but imports nothing (or 403s). All five steps are required:
+
 1. **Wrapper** — copy `sync_togasupply_canon.php` to `sync_togasupply_<client>.php`; set
    `CLIENT_CONFIGURATION` (literal UUIDs, or `App_Api_Toga2::*` consts if defined). Keep the
    rest identical.
@@ -64,8 +67,35 @@ the window's upper bound after each successful section.
    `"cron": "toga2/netsuite/sync_togasupply_<client>.php"`). Deploys regenerate the crontab.
 3. **Seed Parameters** — add `dbchanges2/Client_<Id>/<date> - NetsuiteSyncParameters.sql`
    inserting the 12 keys. **Without this the sync 404s on the first `/parameters` GET and the
-   run aborts.** `Client_<Id>` directory selects the DB — no `USE` statement (dbchanges2 rule).
+   run aborts.** Seed start date = the canonical **`2026-03-04`** (from
+   `_modules/netsuite/2026-04-01 - Parameters.sql`) unless backfilling earlier history for that
+   client. `Client_<Id>` directory selects the DB — no `USE` statement (dbchanges2 rule).
    `lint`: `C:\xampp7\php\php.exe -l` (prod worker is PHP 7.2).
+4. **Client→NetSuite customer link** (`Core.Clients.netsuiteCustomerInternalId`) — **MUST be
+   set** to the client's NetSuite customer internal id. The lookup phase calls
+   `listChildCustomers((int)$client->netsuiteCustomerInternalId)`; if it's `NULL` the walk
+   seeds off `0`, the customer→client map is empty, and **no order ever matches → silent
+   zero-import** (the sync "runs" and even advances windows, but writes nothing). Find the id
+   with a SuiteQL `customer` lookup (`test/@dave/find_aig_netsuite_customer.php` is a template);
+   set it via a `dbchanges2/Core/` migration. Verify the client *has* supply transactions on
+   that customer before bothering (see the AIG gotcha).
+5. **Per-client custom fields on the synced records** — the shared engine hardcodes a fixed set
+   of `c_netsuite*` field names it reads/writes (see *Custom field contract* below). Each must
+   exist on the client's records as **column + `CustomRecordFields` row + `AclCustomFieldPermissions`
+   grant** (custom fields are per-client — see the 2.0 `_underscore` per-client-database doc). A
+   missing one → **403 EZ-2** ("not authorized to read the specified fields") aborting the run.
+   The most commonly-missing one is `c_netsuiteInternalCustomerId` on the **Customers** record
+   (`recordId 113`, `isIdentifier=1`).
+
+### Custom field contract (hardcoded in `common_sync_togasupply.php`)
+
+The engine requests these `c_` fields by literal name per route — every synced client must have
+them provisioned: `/customers`→`c_netsuiteInternalCustomerId`; `/countries`→`c_netsuiteCountry`;
+`/locations`→`c_netsuiteInternalCustomerId` + `c_netsuiteInternalLocationId` + the
+`c_dtNetsuiteLast*Integration` timestamps; `/subsidiaries`→`c_netsuiteInternalSubsidiaryId`;
+`/vendors`→`c_netsuiteInternalVendorId`; `/payment-terms`→`c_netsuiteInternalTermsId`;
+`/shipping-methods`→`c_netsuiteInternalShipMethodId`. The names are a **convention**, not
+discovered per-client.
 
 ## Data model
 
@@ -74,7 +104,8 @@ Per-client `Parameters` table (2.0 client DB, e.g. `Client_Canon.Parameters`; co
 `/parameters`:
 
 - `NETSUITE_LAST_SYNC_DATETIME_{SALES_ORDERS,PURCHASE_ORDERS,INVOICES,ITEM_RECEIPTS,ITEM_FULFILLMENTS,INVENTORY_ADJUSTMENTS}`
-  — seed `'2025-01-01 00:00:00'` (or chosen backfill start).
+  — seed `'2026-03-04 00:00:00'` (the canonical start; use an earlier date only to backfill a
+  client whose history predates it — e.g. AIG seeded `2023-01-01` to reach its 2023/2025 records).
 - `NETSUITE_EXECUTION_MODE_{...same six...}` — seed `'864000-IDLE'`.
 
 Parameters are stored **per client DB** but accessed **through the TOGa2 API**, not direct SQL.
@@ -102,13 +133,28 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   `Client_<Id>.Parameters`: a healthy client advances to ~now every 5 min. As of 2026-06-17,
   Quad was seeded but frozen at 2025-04/05 (not advancing) while the other 12 deployed clients
   were current.
+- **Silent zero-import = missing `netsuiteCustomerInternalId`.** If a client "runs" (sections
+  flip RUNNING→IDLE, windows advance) but imports nothing, check
+  `Core.Clients.netsuiteCustomerInternalId` — a NULL there empties the customer map so no order
+  matches. Distinct from the EZ-2 *abort* caused by a missing `c_netsuite*` field.
+- **"Listed ≠ functioning" — the AIG case (2026-06-17).** AIG was in the original combined
+  array but had **never** imported anything in prod (0 SalesOrders/POs/Invoices/Locations/Customers)
+  and *couldn't* have: its `netsuiteCustomerInternalId` was NULL and its Customers record lacked
+  `c_netsuiteInternalCustomerId`. After provisioning all three (custom field, Parameters, customer
+  link → NetSuite customer **34902**), it still imports ~nothing because AIG's entire NetSuite
+  supply footprint is **1 sales order (2025-09-11) + 15 opportunities** — it's an
+  opportunity/entitlement account, not a procurement/supply customer. Lesson: before onboarding a
+  client, confirm it actually transacts supply orders in NetSuite (SuiteQL the `customer`'s
+  transaction history) — being in the array doesn't mean it belongs on this engine.
 
 ## Change history
 
-- 2026-06-17 — Added AIG + Growrk thin wrappers (the two clients from the original array that
-  never got one), registered both in `cron.worker.sync.json`, and added their dbchanges2
-  Parameters seeds (`Client_Aig`, `Client_Growrk`). Verified the other 13 clients' Parameters
-  against prod. (dfranks)
+- 2026-06-17 — Documented the full onboarding prerequisites (client→NetSuite customer link +
+  per-client `c_netsuite*` custom fields) after AIG ran but imported nothing. Added AIG + Growrk
+  thin wrappers, schedule entries, and dbchanges2 Parameters seeds; built AIG's
+  `c_netsuiteInternalCustomerId` field migration + `Core.Clients` customer-link migration (id
+  34902). Confirmed AIG is not a real supply client; Growrk ships, AIG held. Canonical seed start
+  is `2026-03-04` (not `2025-01-01`). (dfranks)
 
 ## Related docs
 

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-15
-owners: ["jcardinal"]
+updated: 2026-06-18
+owners: ["jcardinal", "bala"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
   - _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php
@@ -40,7 +40,8 @@ sends via `_Email`. The only client-specific input the send actually needs is th
 
 ## How it works
 
-1. Load the template by `uuid`; return `false` immediately if `!isActive`.
+1. Load the template by `uuid` (`load(true)` throws if the uuid is not found); **throw** if
+   `!isActive` so a misconfigured/disabled template is not silently dropped.
 2. Search `EmailTemplateOutgoingEmailAddress` for the template and append each stored
    address to `$to` / `$cc` / `$bcc` by its `toCcBcc` value.
 3. Build `_Email`, set the client identifier, add recipients, set From from the template's
@@ -51,6 +52,12 @@ sends via `_Email`. The only client-specific input the send actually needs is th
 Both `sendEmail()` and `send()` are thin wrappers that forward to `dispatch()`, so the API
 and non-API paths run identical code — no behavioral drift between them.
 
+**Failure surfacing (as of 2026-06-18):** the send path no longer fails silently. `dispatch()`
+throws on an inactive template, and `_Email::send()` throws when the underlying
+`PHPMailer::Send()` returns false (it logs `isSuccess` + `error` on the CloudWatch event
+first, then throws). A scripted-API caller running with `throwExceptionOnApiError=true` now
+gets a real error instead of a `true`/`false` it would otherwise ignore.
+
 ## Data model
 
 - `EmailTemplates` (client DB): `uuid`, `isActive`, `sendFromEmailAddress`, `sendFromName`,
@@ -75,9 +82,19 @@ can keep using `sendEmail($api, ...)`.
   argument, so the first param must stay `&$api`. Do not "clean it up" by removing it.
 - `_Email::send()` throws if the client identifier is empty — `send('')` will fail at send
   time, not at call time.
+- **A failed send now throws — callers that ignore the return value will see exceptions.**
+  As of 2026-06-18 an inactive template or an SMTP send failure raises an `Exception`
+  (previously the inactive case returned `false` and an SMTP failure was swallowed entirely).
+  Any fire-and-forget caller now propagates that exception, which is intended (so an email is
+  never silently marked as sent). Blast radius is every client, including the Compass/Quad
+  `SalesOrder`/`ApprovalDecision` order-placed emails — verify on beta before shipping.
 
 ## Change history
 
+- 2026-06-18 — Hardened against silent failure: `dispatch()` throws on an inactive template
+  (was `return false`) and `_Email::send()` throws + logs `isSuccess`/`error` when
+  `PHPMailer::Send()` fails (was swallowed with no return/throw/log). Affects all clients;
+  not yet deployed. (bala)
 - 2026-06-15 — Added non-API `send(clientIdentifier, …)` entry point + private `dispatch()`;
   `sendEmail(&$api, …)` kept unchanged as a wrapper for backward compatibility. Migrated the
   `worker2` Compass Report and AI-BDR NetSuite callers off the fake-`$api` hack. (jcardinal)
@@ -86,3 +103,7 @@ can keep using `sendEmail($api, ...)`.
 
 - `2.0/standards/backend-php.md` — *Record Scripts* (the `&$api` contract).
 - `2.0/apps/api2/architecture.md` — scripted-API dispatch in `V2.php`.
+- `2.0/apps/api2/features/scripted-api-post-body-args.md` — accepting POST + JSON-body args
+  for scripted APIs, used to send large email payloads without hitting HTTP 414.
+- `1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md` — a heavy
+  consumer of `sendEmail` via the scripted API.

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

@@ -3,5 +3,6 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
+| [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, _underscore/Route.php |

package/knowledge/2.0/apps/api2/features/scripted-api-post-body-args.md

@@ -0,0 +1,90 @@
+---
+title: POST + JSON-body args for scripted APIs
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["bala"]
+files:
+  - api2/Component/Api/V2/V2.php
+related: []
+---
+
+## Summary
+
+The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted
+API can receive its arguments from the **JSON request body** instead of only the URL query
+string. This lets callers send large argument values (e.g. fully rendered email HTML) in the
+body and avoid Apache's `LimitRequestLine` (~8190 bytes) which otherwise produces **HTTP 414
+URI Too Long**. Query-string values still win over body values, so existing GET-based scripted
+calls are unaffected.
+
+## Key files / entry points
+
+- `api2/Component/Api/V2/V2.php` — the scripted-call dispatch inside `processRoutePairs()`:
+  - **READ branch (~line 3583)** — already ran scripted methods for GET; now also merges
+    body args.
+  - **CREATE branch (~line 3846)** — added a scripted-dispatch block so a POST to a route that
+    has a POST-registered Record Script runs the script (guarded by `$isUsingScriptedCall`)
+    instead of being treated as a record create.
+- Args are built from `parse_str($_SERVER['QUERY_STRING'])`, then the decoded JSON body
+  (`$httpPayload`) is merged in. Keys `transactionId` and `api`, and any key already present
+  from the query string, are skipped (query string wins). `$args['api'] = $this` is always set
+  last per the Record Script contract.
+
+## How it works
+
+1. A scripted call is matched via `getRecordScriptPhpMethod(record, httpMethod, route, roleIds)`,
+   which looks up `RecordScripts` (by method + route) joined to the client's `AclRecordScripts`
+   for the caller's roles.
+2. `$args` is parsed from the query string (minus `transactionId`).
+3. If the JSON body is non-empty, each body key not already in `$args` (and not `transactionId`
+   / `api`) is added to `$args`.
+4. The method is invoked as `$model::$phpMethod(...$args)` with `$args['api'] = $this`. Extra
+   named args land in the method's `...$args` variadic.
+
+## Data model
+
+- `RecordScripts` (Core DB): `uuid`, `recordId`, `method` (e.g. `POST`), `route`, `phpMethod`.
+- `AclRecordScripts` (per-client DB): `recordScriptId`, `roleId` — grants a role permission to
+  run the script.
+
+To enable a scripted endpoint for POST you must register **both**: a `RecordScripts` row with
+`method = 'POST'` and the matching `route`/`phpMethod`, and `AclRecordScripts` rows for each
+allowed role. A GET-only script will not fire for a POST until its POST row exists.
+
+## Client variations
+
+None — this is engine behavior. Per-client access is controlled by `AclRecordScripts` rows.
+
+## Gotchas / known issues
+
+- **Normal CRUD is unaffected.** The POST scripted block only fires when a POST Record Script
+  is registered for the route; otherwise the request falls through to the usual create path
+  (`if (!$isUsingScriptedCall && empty($routePairs))` / `locateRecord`).
+- **Registration is environment-specific.** The `RecordScripts` (Core) + `AclRecordScripts`
+  (client) rows must exist in every environment the API reads. As of this writing they were
+  run in **prod** for the email `sendEmail` script (Core + Client_Compass + Client_CompassCanada);
+  **beta still needs them** before the POST path dispatches there.
+- **Deploys with `_underscore`.** api2 pulls `_underscore` at deploy; `http://api2` and
+  `api.beta.togahub.com` resolve to deployed boxes (`/var/app/current`), not a local checkout —
+  so testing the change requires deploying it, not just editing locally.
+- **CI commit policy.** Subject must be `TRUE-<ticket>: <Subject>` (≤80 chars, capitalized,
+  imperative, no trailing period, more than one word).
+
+## Change history
+
+- 2026-06-18 — Added POST scripted-API dispatch (CREATE branch) and JSON-body arg merge (READ +
+  CREATE branches) so large scripted-API payloads avoid HTTP 414; query string still wins over
+  body. Written, not yet merged/deployed. (bala)
+
+## Related docs
+
+- `2.0/apps/api2/architecture.md` — the JSON engine and `processRoutePairs()`.
+- `2.0/apps/_underscore/features/email-template-sending.md` — the `sendEmail` scripted API that
+  this enables to be POSTed with body args.
+- `1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md` — the consumer that
+  hit the 414 and drove this change.

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 8 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/package.json

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