toga-ai 1.0.782 → 1.0.784

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

@@ -1,5 +1,5 @@
 # dbchanges (Database Changes) — 1.0 knowledge
 
-| Doc | Summary | Files |
-|-----|---------|-------|
-| [Authoring & Shipping a 1.0 dbchanges SQL File](workflows/authoring-and-shipping-sql-files.md) | `dbchanges` is the **1.0** (legacy/V1) schema-and-data change repository — the 1.0 sibling of 2.0's `dbchanges2`. | dbchanges/index.php, dbchanges/Core/, dbchanges/TOGaDeskSupport/, worker/crons/infrastructure/execute_dbchanges.php, worker/.ebextensions/030_dbchanges.config |
+| Doc | Summary |
+|-----|---------|
+| [Authoring & Shipping a 1.0 dbchanges SQL File](workflows/authoring-and-shipping-sql-files.md) | `dbchanges` is the **1.0** (legacy/V1) schema-and-data change repository — the 1.0 sibling of 2.0's `dbchanges2`. |

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

@@ -1,24 +1,25 @@
 # library (Library) — 1.0 knowledge
 
-| Doc | Summary | Files |
-|-----|---------|-------|
-| [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
-| [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | `App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway. | library/app/api/officedepot.php, library/app/api/usps.php |
-| [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | In `library/app/`, choosing a folder is **not** a filing decision — the autoloader maps `App_<Folder>_<File>` to `app/<folder>/<file>.php`, and each folder's ba | library/app/model.php, library/app/client.php, library/app/api.php, library/app/api/servicerequest.php, library/app/api/volt.php, library/app/api/carrier/fedex.php |
-| [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability | library/app/sso.php, library/sso/togahub_private_key.key |
-| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l | library/app/framework.php |
-| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | Two "View Recommended Services" buttons exist in the TOGa Refresh 2026 SR view: 1. | library/app/model/toga/diagnostic.php, library/app/model/servicerequest.php |
-| [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
-| [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | `App_Email::send()` can either send **inline** (PHPMailer talks to SES right there) or **queue** the message: `base64(serialize($this))` is inserted into `Commo | library/app/email.php, library/phpmailer/class.phpmailer.php, worker/crons/notifications/infrastructure/send_emails.php, worker/crons/notifications/covid/send_covid_pending_vaccination_approval.php, togadesk/desk/includes/functions.php |
-| [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
-| [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | `App_Email::send()` is **not** side-effect free. | library/app/email.php, library/app/model/logs/email.php, library/app/framework.php |
-| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/api/toga2.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
-| [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | `App_SystemMonitor_500Error` (`library/app/systemmonitor/500error.php`, title **"HTTP 500 Error Alert"**) is the 1.0 system monitor that watches **`Logs.Api` fo | library/app/systemmonitor/500error.php, worker/crons/infrastructure/system_monitors.php, api2/Controller/Index.php, _underscore/Error.php |
-| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
-| [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls **File Cabinet binary content** (invoice PDFs) out of NetSuite over REST. | library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/netsuite_restlet_filecontent.js, worker/config.worker.ini |
-| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
-| [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
-| [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
-| [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |
-| [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php, library/app/api/startechticket.php, worker/crons/toga2/startech/common_import_supporting_records.php |
-| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php, test/@Mark/AIG/test_multi_email.php |
+| Doc | Summary |
+|-----|---------|
+| [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. |
+| [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | `App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway. |
+| [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | In `library/app/`, choosing a folder is **not** a filing decision — the autoloader maps `App_<Folder>_<File>` to `app/<folder>/<file>.php`, and each folder's ba |
+| [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability |
+| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l |
+| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | Two "View Recommended Services" buttons exist in the TOGa Refresh 2026 SR view: 1. |
+| [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. |
+| [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | `App_Email::send()` can either send **inline** (PHPMailer talks to SES right there) or **queue** the message: `base64(serialize($this))` is inserted into `Commo |
+| [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. |
+| [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | `App_Email::send()` is **not** side-effect free. |
+| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). |
+| [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | `App_SystemMonitor_500Error` (`library/app/systemmonitor/500error.php`, title **"HTTP 500 Error Alert"**) is the 1.0 system monitor that watches **`Logs.Api` fo |
+| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t |
+| [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls **File Cabinet binary content** (invoice PDFs) out of NetSuite over REST. |
+| [assetType from NetSuite itemtype during Item Sync (opt-in per client)](features/netsuite-item-assettype-sync.md) | `getCreateItem()` never sent `assetType`, so **every item the NetSuite importer created had `Items.assetTypeId = NULL`** — for every client, since the importer |
+| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant |
+| [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w |
+| [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. |
+| [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc |
+| [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. |
+| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross |

package/knowledge/1.0/apps/library/features/cron-execution-monitoring.md

@@ -6,12 +6,14 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-25
+updated: 2026-09-08
 owners: [dfranks, bala]
 files:
   - library/app/framework.php
 related:
   - ../../worker/architecture.md
+  - ./email-queue-attachments.md
+  - ../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md
   - ../../worker/workflows/tracing-a-worker-cron-run-in-production.md
 ---
 
@@ -51,6 +53,28 @@ row in `db_log` and of the per-job Sentry check-in monitors.
   (`db_common`), *not* by POSTing from 1.0 to a 2.0 API endpoint. Per Jeff Cardinal, 1.0 code
   must not POST to 2.0 code; the direct shared-DB write is the sanctioned path (TRUE-78182).
 
+## For an emailing cron, this table is the ONLY proof of a run
+
+There is **no sent-email log for a 1.0 `App_Email` / `App_Email_Agilant` ops email**, so
+`CronJobExecutions` is the only per-run evidence a 1.0 emailing cron leaves:
+
+- `Logs_<Client>.Email` holds **2.0 application email only**. Verified 2026-09-08: zero rows in
+  `Logs_Compass.Email` for the Compass Refresh Exception Report, a 1.0 cron email that has been
+  sending for months.
+- `Common.EmailsQueued` is a **queue drained on send**, holding a serialized object — not a log.
+  See [App_Email Queued Sending & Attachments](./email-queue-attachments.md).
+
+Two consequences:
+
+1. **A cron whose only output is a "something is wrong" email is effectively unmonitored** — a
+   silent day and a dead cron look identical. Monitor the **backlog the cron drains**, not the
+   email. See
+   [OneUptime push-metric monitors for 2.0 workers](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md).
+2. **worker2 (2.0) has no proven connection to the legacy `Common` DB**, so a 2.0 OneUptime
+   monitor cannot read `CronJobExecutions` today. A generic "this 1.0 cron has not checked in"
+   monitor is therefore blocked on that connection, not on the data — the columns needed
+   (`dtCheckIn`, `job`, `instanceId`) are already there.
+
 ## Gotchas
 
 - **⚠ A run skipped by the overlap guard leaves NO ROW — absence is ambiguous.**
@@ -76,6 +100,12 @@ row in `db_log` and of the per-job Sentry check-in monitors.
   logic. (Fixed 2026-07-06: consolidated back to one `db_common` INSERT/UPDATE pair.)
 
 ## Change history
+- 2026-09-08 — Recorded that `CronJobExecutions` is the **only** per-run proof for a 1.0
+  *emailing* cron, because there is no sent-email log: `Logs_<Client>.Email` is 2.0-only (zero
+  rows for a 1.0 report that has emailed for months) and `Common.EmailsQueued` is a queue drained
+  on send. Hence the rule to monitor the backlog rather than the email, and the note that worker2
+  has no proven legacy-`Common` connection, so a 2.0 "cron has not checked in" monitor is not
+  possible yet. No code change. (bala)
 - 2026-08-25 — Corrected the schema note (prod `CronJobExecutions` **does** carry a `note` TEXT
   column, unused by `App_Framework`, usable for temporary cron tracing) and separated it from the
   `note = 'Started execution'` row `cronInitialization()` writes to `Log` on `db_log`. Recorded

package/knowledge/1.0/apps/library/features/error-capture-1-0.md

@@ -6,12 +6,14 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-17
+updated: 2026-09-08
 owners: ["jcardinal", "mhammontree"]
 files:
   - library/app/error/capture.php
   - library/app/error.php
   - library/app/exception/business.php
+  - library/app/exception/api.php
+  - library/app/api/netsuite/rest.php
   - library/app/api/toga2.php
   - library/app/cloud.php
   - worker/config.worker.ini
@@ -78,6 +80,50 @@ whichever occurrence happened to be seen first — i.e. one arbitrary order numb
 
 Compass USA's sales-order → MITS transmit rejection was the first business-exception use case.
 
+### `App_Exception_Api` — one Issue per outbound-API outage across both frameworks (added 2026-09-08)
+
+The 1.0 twin of 2.0's `_Exception_Api`. Read the
+[2.0 section](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md#outbound-third-party-api-errors-fingerprint-on-servicestatusoperation-not-the-trace-added-2026-09-08)
+for the full rationale — this covers only the 1.0 specifics.
+
+- **`library/app/exception/api.php`** — `class App_Exception_Api extends Exception`, carrying
+  `service` / `httpStatus` / `operation`. **PHP 7.2, so untyped properties with `@var` docblocks**
+  (typed properties fail to parse in `library/` — same trap as `App_Exception_Business`). Extends
+  plain `Exception`, so it stays HTTP 500 + creates a `Logs.Issue`.
+- **`App_Error_Capture` gains the same `instanceof` fingerprint branch** →
+  `buildApiFingerprint()`, keyed on `service + httpStatus + operation`, with the fingerprint text
+  using the **FIXED literal `'apiError'` prefix** — byte-identical to 2.0's, so one
+  service+status+operation is **one Issue whichever framework threw it**. Do not derive the prefix
+  from the class name (`App_Exception_Api` ≠ `_Exception_Api`), and do not reformat the string on
+  either side.
+- **A new `firstApplicationArea()` helper was added here.** The 1.0 twin previously lacked it — the
+  DB fingerprint branch is 2.0-only, so 1.0 had no such helper before this. `buildApiFingerprint()`
+  caps `operation` at 200 chars, matching 2.0.
+
+#### The NetSuite client is where granularity is decided — `library/app/api/netsuite/rest.php`
+
+A private `buildApiException(message, method, url, statusCode)` was added, and the **3 HTTP-status
+throw sites** (OAuth token, API request, RESTlet call) switched from plain `\Exception` to it. The
+**3 config/parse-error throws** in the same file (no HTTP status) were left as plain `\Exception`
+on purpose.
+
+- **5xx** (NetSuite-side outage) → `operation = 'SERVER_ERROR'` (constant), so the whole outage
+  folds into ONE Issue regardless of endpoint or client.
+- **4xx** (request-specific) → `operation = "<METHOD> <path>"`, so a genuine per-endpoint problem
+  keeps its own Issue. Because every `list*` call goes through `suiteqlListAll()` hitting the one
+  endpoint `POST /query/v1/suiteql`, all the `list*` 400s collapse together on their own.
+- **cso hardening (in `buildApiException`):** id-like path segments are masked
+  (`preg_replace('#/\d+(?=/|$)#', '/{id}')`); an empty parsed path uses a fixed `UNKNOWN_PATH`
+  placeholder — **never the raw `$url`**, which would carry the query string back into the shared
+  fingerprint. Net guarantee: only `service` + `httpStatus` + `operation` (all controlled values)
+  reach `Logs.IssueFingerprint` — the vendor message body never does.
+
+> **OPEN (pre-existing, not fixed here):** the assembled failure message still carries
+> `print_r($response)` (the full vendor body, which can hold one tenant's PII) into
+> `Issue.subject` / `Event.errorMessage` on the shared `Logs` cluster. Unchanged from the old plain
+> throw; never touches the fingerprint. Worth a future ticket to cap/redact — same shape as the
+> raw-SQL-in-subject open item on the 2.0 doc.
+
 ### Client attribution — resolved from the API client uuid at `App_Api_Toga2::authenticate()`
 
 `App_Error::setCurrentClientId()` exists in 1.0 for parity with 2.0's ambient current-client, but
@@ -177,6 +223,10 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Gotchas / known issues
 
+- **A `*/` inside PHP docblock prose silently closes the comment early.** Writing something like
+  `list*/fetch*` in a `/** … */` block ends the docblock at the `*/`, and `php -l` then reports a
+  confusing `syntax error, unexpected token` on a later line. Hit while documenting the NetSuite
+  throw sites. Avoid the literal `*/` in docblock text.
 - **⚠ A grouped `Logs.Issue` row can show a STALE error id — read the live api2 transaction log for
   the current error.** Two facts combine to mislead: (1) `Event.errorMessage` is **`varchar(255)`**,
   so a long API response is **truncated** — often before the trailing error id; and (2)
@@ -229,6 +279,23 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Change history
 
+- 2026-09-08 — **Added the 1.0 twin of the outbound-API fingerprint fix.** NetSuite failures were
+  **over-splitting** into ~40 Issues per outage (top frames differ per `list*`/`fetch*` caller and
+  per-client cron; prod `Logs.Issue` 678–692 = one HTTP 500 OAuth outage, 699–731 = one HTTP 400
+  wave). New `App_Exception_Api` (`library/app/exception/api.php`, extends plain `Exception`,
+  **PHP 7.2 untyped `@var` props**; `service`/`httpStatus`/`operation`), an `instanceof`
+  `buildApiFingerprint()` branch in `App_Error_Capture` keyed on service+status+operation with a
+  **FIXED literal `'apiError'` prefix** byte-identical to 2.0's (so one outage = one Issue across
+  both frameworks), and a new `firstApplicationArea()` helper (1.0 lacked it — the DB branch is
+  2.0-only). `library/app/api/netsuite/rest.php` gained a private `buildApiException()` and its
+  3 HTTP-status throw sites moved off plain `\Exception` (the 3 config/parse throws stayed plain on
+  purpose); granularity is set there — 5xx → constant `operation='SERVER_ERROR'`, 4xx →
+  `"<METHOD> <path>"` (all `list*` go through one `suiteql` endpoint so their 400s collapse). cso
+  hardening: id-like path segments masked to `/{id}`, empty path → `UNKNOWN_PATH` (never the raw
+  URL), `operation` capped at 200 chars — only controlled values reach the fingerprint. Deploy
+  `_underscore`, then `library`, then redeploy `worker`; not yet proven against a live failure.
+  **OPEN (pre-existing):** the message still carries `print_r($response)` (vendor body / PII) into
+  `Issue.subject`/`Event.errorMessage` — never touches the fingerprint. (jcardinal)
 - 2026-08-17 — Recorded a diagnostic trap: a grouped `Logs.Issue` row can show a **stale error id**
   because `Event.errorMessage` is `varchar(255)` (truncates a long API response, often before the
   error id) and `Issue.subject`/`errorMessage` keep the **first-occurrence** text — observed issue

package/knowledge/1.0/apps/library/features/netsuite-item-assettype-sync.md

@@ -0,0 +1,202 @@
+---
+title: assetType from NetSuite itemtype during Item Sync (opt-in per client)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-09-04
+owners: [rgirish]
+files:
+  - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
+related:
+  - netsuite-item-isfulfillable-sync.md
+  - netsuite-suiteql-rest-shim.md
+  - toga2-api-client-and-bridge.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../2.0/apps/api2/features/nested-relationship-writes.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../clients/elite/features/netsuite-togasupply-sync.md
+---
+
+## Summary
+
+`getCreateItem()` never sent `assetType`, so **every item the NetSuite importer created had
+`Items.assetTypeId = NULL`** — for every client, since the importer began. The string `assetType`
+appeared nowhere in `library/app/api/toga2.php` nor in `worker/crons/toga2/netsuite/*`.
+
+Measured on production `Client_Elite.Items`: **113 rows, 110 with `assetTypeId = NULL`**. The only
+3 non-NULL rows (`Laptop`, `Test`, `Test 2`) have `c_netsuiteInternalItemId = NULL` and
+`inventoryType = HYBRID` — hand-made test rows, not imported ones.
+
+This doc covers the fix: NetSuite's `item.itemtype` is now mapped to an `AssetTypes.uuid` and
+stamped on the item. It is **opt-in per client** and deliberately narrow, because two platform
+facts (below) make the obvious implementation break item imports outright.
+
+Sibling doc: [isFulfillable](netsuite-item-isfulfillable-sync.md) — the other NetSuite flag stamped
+by the same function. **The two are not symmetric** and must not be implemented the same way; see
+[Why this is not modeled on isFulfillable](#why-this-is-not-modeled-on-isfulfillable).
+
+## ⚠⚠ TWO blockers — read before adding this for another client
+
+Both were found under CTO review of a first proposal that looked obviously correct. Either one
+turns "the asset type is not set" into **"the item create fails outright."**
+
+### 1. `Items.assetTypeId` is not writable by the API role in most tenants
+
+api2 **aborts the entire record write** when a payload names a field the authenticating role cannot
+write. The NetSuite sync authenticates as **roleId 3 (API)**. So simply adding `assetType` to the
+payload does not merely fail to set the asset type — it **fails the item create**.
+
+Verified on production `Client_Elite.AclFieldPermissions`:
+
+| recordFieldId | Field | Roles granted |
+|---|---|---|
+| **269** | `Items.assetTypeId` | roleId **1 (Base) only** |
+| 107 | `Items.manufacturerId` | roleId **1 and 3 (API)** |
+
+**A `dbchanges2/Client_<Tenant>/` grant must land BEFORE the code deploy.** Elite's is
+`dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql`. Mechanics:
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+
+### 2. `assetTypeId`'s childPolicy is `MATCH`, not `MATCH_UPSERT` — so get-or-create does NOT work
+
+`getCreateManufacturer()` sits in the **same function** and does a get-or-create by name. **That
+pattern does not transfer.** Manufacturers auto-create precisely because their field is
+`MATCH_UPSERT`; `assetTypeId` is plain `MATCH`.
+
+Verified on production `Core.RecordFields`: id **269** (`assetTypeId`) = `MATCH`; id **107**
+(`manufacturerId`) = `MATCH_UPSERT`.
+
+With `MATCH`, sending `assetType: {name: 'Services'}` for a name that has no row is a
+**field-reference error that fails the record** — it does not create the row. Correct approach:
+**resolve name → uuid up front (`GET /asset-types`) and send `{uuid}`.** Policy semantics:
+[nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+
+> **General lesson:** never reason by analogy from a sibling nested write in the same function.
+> Check that field's own `Core.RecordFields.childPolicy` first. Two fields on the same record
+> routinely differ.
+
+## Key files / entry points
+
+- `library/app/api/netsuite/rest.php` — `fetchItemFlagsByIds()` now selects `itemtype` in its
+  SuiteQL and exposes it as `->itemType`. **Free**: that query already selected from `item` once
+  per 500-id batch, so no extra round-trip. Returns `null` for an empty itemtype.
+- `library/app/api/toga2.php`
+  - `getAssetTypeUuidForNetsuiteItemType()` (~6358) — new private helper. Resolves a NetSuite
+    itemtype to an `AssetTypes.uuid` through the launcher's opt-in map. Returns `null` when the
+    client has not opted in or the itemtype is unmapped; **throws** when a configured mapping names
+    an asset type the client does not have.
+  - `getCreateItem()` (~6474) — sends `assetType: {uuid}` on create, and **fills it on existing
+    items only when currently NULL**.
+- `worker/crons/toga2/netsuite/common_sync_togasupply.php` (~298) — the bulk `/items` GET now
+  requests `assetType => ['uuid']`. **Without this the fill-NULL-only check has nothing to read and
+  would re-PUT every item every run** (the same trap `isFulfillable` fell into — see its doc).
+- `worker/crons/toga2/netsuite/sync_togasupply_elite.php` — the only launcher that opts in today.
+
+## How it works
+
+1. `fetchItemFlagsByIds()` returns `->itemType` alongside the serialized / fulfillable flags, one
+   SuiteQL query per 500 items.
+2. `getCreateItem()` calls `getAssetTypeUuidForNetsuiteItemType($itemFlags->itemType, …)`.
+3. The helper reads the launcher constant `NETSUITE_ITEM_TYPE_TO_ASSET_TYPE_NAME`
+   (`itemtype => AssetTypes.name`). **If the constant is not defined, it returns `null`** and the
+   `assetType` key is **omitted from the payload entirely**.
+4. On first need it `GET /asset-types` once and builds a `strtoupper(name) => uuid` map, skipping
+   rows with a NULL/blank name. **The cache is keyed by client uuid** — one worker process can
+   handle several clients in a run.
+5. Name not found → **throw**, naming the itemtype, the mapped name, and the fix. Fail loud, per the
+   team rule for import/sync/cron code.
+6. Create → `assetType: {uuid}` in the POST. Existing item → set it **only if
+   `$existingItem->assetType` is NULL**.
+
+## Design rules (and why each one)
+
+| Rule | Why |
+|---|---|
+| **Opt-in via a launcher constant** | `getCreateItem()` is shared by ~20 client sync launchers. Undefined constant ⇒ the payload key is absent ⇒ the other ~19 clients are **byte-for-byte unaffected**. |
+| **Link by uuid, never by name** | `assetTypeId` is `MATCH` — a name for a missing row fails the whole record (blocker 2). |
+| **Never auto-create an `AssetTypes` row** | `AssetTypes` is free text with per-client `AUTO_INCREMENT` ids and **no slug or code**, so nothing marks a row as sync-made vs. operator-made. Verified: `Client_Elite.AssetTypes` has 2 rows (1=`Laptop`, 2=`Services`); `Client_Compass.AssetTypes` has **38 hand-curated rows** (`ACCESSORY`, `EQUIPMENT`, `FEE`, `CONSULTING`, `WARRANTY`, `HP LAPTOP ACCESSORIES`, … plus an **empty-name row at id 23**) and **no `Services` row at all**. Auto-creating would pollute that taxonomy. |
+| **Fail loudly on a missing asset type** | A silent skip leaves a client half-stamped with no signal. |
+| **Fill-NULL-only on existing items** | `assetTypeId` is shared, **hand-curated per-client** data — unlike `isFulfillable`, which is a boolean NetSuite owns. Also means a manual TOGa correction of a NetSuite-mis-typed item **survives later syncs**. |
+| **Cache keyed by client uuid** | One worker process can service several clients. |
+
+## Why this is not modeled on isFulfillable
+
+[isFulfillable](netsuite-item-isfulfillable-sync.md) **refreshes on every difference** — and that
+doc's own ⚠ CRITICAL section records the cost: the refresh **reverts any local override**, so a
+hand fix silently disappears within a day.
+
+`assetType` deliberately does the opposite (**fill-NULL-only**). NetSuite does not own this field;
+the client's operators do. Do not "make it consistent" with `isFulfillable` — the asymmetry is the
+design.
+
+## NetSuite `itemtype` does NOT cleanly identify services
+
+`item.itemtype` **is** populated (account-wide: InvtPart 51336, NonInvtPart 2652, Group 585,
+Service 472, Kit 50, OthCharge 24, Discount 17, Expense 6, Description 3). But **`NonInvtPart` is
+mixed** — it holds real services. For Elite (113 items: 65 InvtPart, 11 Service, 17 NonInvtPart),
+`itemtype = 'Service'` alone marks only **11 of ~28** real services; the rest sit in `NonInvtPart`
+(`SVC-FS-DEPLOY`, `SVC-FS-SHIPPING-*`, `SVC-CI-RETAINER-RS`, `SVC-TS-Removal`, `Project - Cabling`).
+
+So a usable mapping must include the non-inventory types, not just `Service`. Elite's map is in
+[Elite's sync doc](../../../clients/elite/features/netsuite-togasupply-sync.md).
+
+**Residual gap: NetSuite data hygiene, not a code problem.** Three Elite items are typed
+`InvtPart` in NetSuite though they are services (`SVC-TS-ELITE-HDONBOARDING`, `CONFIG/INSTALL`,
+`CONF-RM-INSTALL-SUPP`). **Decided: this is a client data-hygiene ask, NOT a code special case** —
+a part-number allowlist inside a 20-client shared import is unmaintainable. Fill-NULL-only means a
+manual TOGa correction sticks.
+
+## Gotchas / known issues
+
+- **⚠ Existing items stay NULL until a cursor reset.** `getCreateItem()` only runs when a
+  transaction line references an item, so already-imported items are **not** back-stamped by
+  turning this on. Elite's 110 NULL items stay NULL until a cursor rollback makes the sync re-walk
+  transactions that reference them. Cursors live in the **client** database `Parameters` table
+  (key `NETSUITE_LAST_SYNC_CURSOR_*`, value `"<lastmodifieddate>|<netsuiteInternalId>"`), read via
+  `GET /parameters`. See [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+- **⚠ Lumping `Discount` / `Expense` / `Description` into a "Services" asset type is semantically
+  loose.** Harmless while `assetTypeId` only hides rows on a page — a **latent bug if it ever drives
+  billing or reporting.** Revisit the map before wiring `assetTypeId` into either.
+- **An empty-name `AssetTypes` row exists in the wild** (`Client_Compass` id 23). The name→uuid
+  cache skips NULL/blank names so it can never be matched by accident.
+- **⚠ PRE-EXISTING BUG, deliberately NOT fixed — needs its own ticket.** The fulfillability refresh
+  (`toga2.php` ~6547) reads `$existingItem->isFulfillable`, but the bulk `GET /items` lookup in
+  `common_sync_togasupply.php` **never requested that field**. So `$currentFulfillable` is always
+  `null` and the sync almost certainly **PUTs `isFulfillable` on every item, every run, for every
+  client**. Left untouched on purpose: fixing it changes behavior for all ~20 clients and was out of
+  scope. This is the exact trap `assetType` avoids by requesting `assetType => ['uuid']` in the same
+  lookup.
+
+## Change history
+
+- 2026-09-04 — **Built assetType stamping from NetSuite `itemtype`.** Root-caused that
+  `getCreateItem()` never sent `assetType`, so every imported item had `assetTypeId = NULL` (prod
+  `Client_Elite`: 110 of 113). Added `itemtype` to `fetchItemFlagsByIds()`'s existing SuiteQL
+  (free), the `getAssetTypeUuidForNetsuiteItemType()` helper, `assetType => ['uuid']` to the bulk
+  `/items` GET, and the create/fill paths. Recorded the **two blockers** that break the naive
+  version — `Items.assetTypeId` (recordField 269) is granted to **roleId 1 only** while the sync
+  authenticates as roleId 3, and api2 fails the **whole** record write on a non-writable field; and
+  269's childPolicy is **`MATCH`**, not the `MATCH_UPSERT` that makes the sibling
+  `getCreateManufacturer()` get-or-create work, so a name-only nested object is a hard failure.
+  Design: opt-in per launcher, link by uuid, never auto-create an `AssetTypes` row, fail loud on a
+  missing one, **fill-NULL-only** (the deliberate opposite of `isFulfillable`'s revert-everything
+  refresh). Also collapsed the existing-item branch's **three separate PUTs to the same
+  `/items/<uuid>`** into one, and recorded the pre-existing `isFulfillable`-never-requested bug as a
+  separate ticket. (rgirish)
+
+## Related docs
+
+- [isFulfillable from NetSuite during Item Sync](netsuite-item-isfulfillable-sync.md) — the sibling
+  flag on the same function, with the opposite refresh policy.
+- [Nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md) —
+  `MATCH` vs `MATCH_UPSERT` and why link-by-uuid is the only safe form.
+- [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md) — the
+  field-write grant this feature needs per tenant.
+- [Elite NetSuite → TOGa Supply sync](../../../clients/elite/features/netsuite-togasupply-sync.md)
+  — the only client opted in, and its itemtype map.

package/knowledge/1.0/apps/library/features/netsuite-item-isfulfillable-sync.md

@@ -6,14 +6,15 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
-owners: [bala]
+updated: 2026-09-04
+owners: [bala, rgirish]
 files:
   - library/app/netsuite.php
   - library/app/api/toga2.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php
 related:
+  - netsuite-item-assettype-sync.md
   - toga2-api-client-and-bridge.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
   - ../../worker/workflows/isfulfillable-multi-client-backfill.md
@@ -116,6 +117,22 @@ sweep that started 13:45 and set every item to `1`.
   each verified to trace through an Agilant source.
 
 ## Gotchas / known issues
+- **⚠⚠ The refresh's diff is BROKEN — `isFulfillable` is never read back, so it is PUT on every
+  item, every run, for every client.** The refresh at `toga2.php` ~6547 compares NetSuite's value
+  against `$existingItem->isFulfillable`, but the bulk `GET /items` lookup in
+  `common_sync_togasupply.php` **never requested that field** — so `$currentFulfillable` is always
+  `null` and the diff can never match. The 2026-07-28 entry below claims the field was added to that
+  field list; **it is not there** (verified 2026-09-04). Net effect: the "diff-only PUT keeps
+  re-syncs no-op" guarantee does not hold. **Not fixed — needs its own ticket**, because a fix
+  changes write volume for all ~20 clients. The sibling
+  [assetType feature](netsuite-item-assettype-sync.md) avoids this by requesting
+  `assetType => ['uuid']` in the same lookup.
+- **The existing-item branch now sends ONE PUT, not three.** It previously issued up to three
+  separate PUTs to the same `/items/<uuid>` with identical options (`inventoryType`,
+  `isFulfillable`, and now `assetType`). One payload is collected and a single PUT is sent when
+  non-empty. Side effect worth knowing: `inventoryType` was previously never written back to the
+  in-run lookup, so a repeat line for the same part number re-PUT it — all three fields now update
+  the lookup.
 - **Value stamped only on the Agilant source item here** — the client-facing copy is set by the 2.0
   interceptor. If the interceptor rows aren't deployed in the target env, api2 **403s the whole item
   write** on the unknown `isFulfillable` field (see the Phase-2 doc's deploy gotchas).
@@ -125,6 +142,15 @@ sweep that started 13:45 and set every item to `1`.
   in `Client_Compass.Apis` (name `Agilant`) — never reproduce the secret value.
 
 ## Change history
+- 2026-09-04 — **Two corrections found while building the sibling
+  [assetType stamping](netsuite-item-assettype-sync.md) on the same function.** (1) The
+  existing-item **refresh diff never works**: the bulk `GET /items` field list in
+  `common_sync_togasupply.php` does **not** request `isFulfillable` (contrary to the 2026-07-28
+  entry below), so `$currentFulfillable` is always `null` and the flag is almost certainly PUT on
+  every item, every run, for every client. Recorded as a separate ticket — not fixed, because it
+  changes write volume for ~20 clients. (2) The existing-item branch's up-to-**three** PUTs to the
+  same `/items/<uuid>` were collapsed into a **single** PUT, and `inventoryType` is now written back
+  to the in-run lookup (it previously was not, so a repeat part number re-PUT it). (rgirish)
 - 2026-08-12 — Prod investigation (no code change): recorded that the **existing-item refresh
   reverts any local override** (NetSuite returns `T` for services; audit-log proof on Compass items
   2382/2384/2385, stamped NULL→1 on 2026-08-04), so an override must be enforced by a write-time

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-02
+updated: 2026-09-08
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -413,6 +413,14 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-09-08 - Added `updateTransferOrderStageToClosed(&$nsOrder, array &$clientConfiguration): bool`
+  and the constant `TRANSFER_ORDER_STATUS__CLOSED = 'closed'` (also now used by the `case 'Closed'` in
+  the transfer-order status switch). It is a **stage-only** writer: it never touches line items, so it
+  cannot reproduce the URI-length / HTTP 414 blowup that the importer's `Closed` skip exists to avoid,
+  and it never creates a transfer order we did not import. It exists because the sync loop's
+  `status === 'Closed'` `continue` sits before the transfer-order branch, leaving 18 NYCHH transfer
+  orders on `Pending`. Written, **not committed or deployed**. Mechanism and the rejected alternative:
+  [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md). (bala)
 - 2026-09-02 — `syncPurchaseOrderFromNetsuite`'s cleanup DELETE ("remove dropped items") was a **bare
   throwing** DELETE that froze the whole PURCHASE_ORDERS section whenever a NetSuite-dropped PO line
   still had a RESTRICT child (item receipt `ItemReceiptItems.purchaseOrderItemId`, or an SO/TO link).

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

@@ -1,20 +1,20 @@
 # test (Test) — 1.0 knowledge
 
-| Doc | Summary | Files |
-|-----|---------|-------|
-| [Test (test) Architecture](architecture.md) | `test` (project **Test**) is a **repository of ad-hoc developer scripts** — not a deployed application. | test/team/ |
-| [2.0 Deployment — Per-Client SQL Generator](features/2-0-deployment-client-sql.md) | `team/2.0 deployment/generate_client_sql.php` fans a single SQL change-set out across **all 2.0 client databases**. | test/team/2.0 deployment/generate_client_sql.php, test/team/2.0 deployment/Clients_Db.txt, test/team/2.0 deployment/Client.sql |
-| [Active Directory Authentication Test](features/active-directory-auth-test.md) | `team/active_directory_authentication_test.php` is an interactive CLI tool to test **Active Directory authentication**. | test/team/active_directory_authentication_test.php |
-| [Compass retrofix2 — Retroactive Data-Fix SQL Generator](features/compass-retrofix2-sql-generator.md) | `@jeff/compass/retrofix2.php` is a standalone **1.0 `App_`** script that retroactively repairs historical Compass USA (`Client_Compass`, 2.0) order data left in | test/@jeff/compass/retrofix2.php |
-| [Create Elastic Beanstalk Environment (script)](features/create-elastic-beanstalk.md) | `team/aws/create_elastic_beanstalk.php` is a **standalone** (no `App_` framework) constants-driven PHP generator. | test/team/aws/create_elastic_beanstalk.php |
-| [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. | test/team/generate_password.php, test/team/uuid.php |
-| [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da | test/team/forecast-netsuite/discrepancy_analysis.php |
-| [GitHub Audit Script (team/github_audit.php)](features/github-audit-script.md) | `team/github_audit.php` is a **standalone** (no `App_` framework) browser/CLI script that reports lines added/removed, commits, unique authors, and active repos | test/team/github_audit.php |
-| [@goagilant.com → @togatech.com Email-Domain Migration (1.0 + 2.0)](features/goagilant-to-togatech-email-migration.md) | Reference + technique for migrating the company email domain `@goagilant.com` → `@togatech.com` across **both** platforms. | migrate_goagilant_to_togatech_2026-06-26.sql, migrate_goagilant_to_togatech_LEGACY_2026-06-26.sql |
-| [Static (no-DB) Regression Harness for 1.0 Logic + Source Drift Guard](features/static-no-db-regression-harness.md) | 1.0 has **no PHPUnit**, and most of its business logic sits inside methods that also write SQL, so "just call it" means standing up a client database. | test/@Mark/AIG/test_multi_email.php, test/@Mark/TRUE-80952/test_queued_email_attachments.php, library/app/database.php, library/app/api/toga2.php |
-| [TableView Builder (2.0 TableViews SQL generator)](features/tableview-builder.md) | `team/tableViewBuilder/` generates SQL `INSERT` statements for the **2.0 `TableViews`**, `TableViewFields`, and `TableViewJoins` tables from a plain SQL `SELECT | test/team/tableViewBuilder/TableViewGenerator.php, test/team/tableViewBuilder/index.php, test/team/tableViewBuilder/Instructions.md |
-| [Talos Knowledge Base Pipeline (Uploader + Processor)](features/talos-kb-pipeline.md) | `team/talos/` holds the two-script web tooling that feeds the **TOGa Talos** (TOGa IQ) AI knowledge bases. | test/team/talos/kb_uploader.php, test/team/talos/kb_processor.php, test/team/talos/kb_processor.ini |
-| [TOGa 2.0 Client Onboarding SQL Generator](features/toga2-client-onboarding-sql.md) | > **Superseded by the browser wizard.** The generation logic here was extracted into the reusable > `OnboardingSqlGenerator` class and wrapped in a local browse | test/team/generate_toga2_onboarding_sql.php |
-| [TOGa 2.0 Client Onboarding Wizard (local tool)](features/toga2-onboarding-wizard.md) | A **local browser wizard** (`test/team/onboarding/`) that automates 2.0 client onboarding end to end: it (1) gathers developer input and **generates all onboard | test/team/onboarding/index.php, test/team/onboarding/classes/OnboardingSqlGenerator.php, test/team/onboarding/classes/DbchangesConsolidator.php, test/team/onboarding/README.md |
-| [TOGa 2.0 User Cross-Client Access SQL Generator](features/toga2-user-cross-client-access-sql.md) | `team/generate_toga2_user_access_sql.php` generates SQL to grant an existing 2.0 user from a **home client** access to a **cross client**. | test/team/generate_toga2_user_access_sql.php |
-| [URL & Domain Markdown Document Builder](features/url-domain-markdown-document.md) | `team/build_url_domain_markdown_document.php` generates a **markdown document of our URLs and domains** by pulling environments and domains from the 2.0 platfor | test/team/build_url_domain_markdown_document.php |
+| Doc | Summary |
+|-----|---------|
+| [Test (test) Architecture](architecture.md) | `test` (project **Test**) is a **repository of ad-hoc developer scripts** — not a deployed application. |
+| [2.0 Deployment — Per-Client SQL Generator](features/2-0-deployment-client-sql.md) | `team/2.0 deployment/generate_client_sql.php` fans a single SQL change-set out across **all 2.0 client databases**. |
+| [Active Directory Authentication Test](features/active-directory-auth-test.md) | `team/active_directory_authentication_test.php` is an interactive CLI tool to test **Active Directory authentication**. |
+| [Compass retrofix2 — Retroactive Data-Fix SQL Generator](features/compass-retrofix2-sql-generator.md) | `@jeff/compass/retrofix2.php` is a standalone **1.0 `App_`** script that retroactively repairs historical Compass USA (`Client_Compass`, 2.0) order data left in |
+| [Create Elastic Beanstalk Environment (script)](features/create-elastic-beanstalk.md) | `team/aws/create_elastic_beanstalk.php` is a **standalone** (no `App_` framework) constants-driven PHP generator. |
+| [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. |
+| [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da |
+| [GitHub Audit Script (team/github_audit.php)](features/github-audit-script.md) | `team/github_audit.php` is a **standalone** (no `App_` framework) browser/CLI script that reports lines added/removed, commits, unique authors, and active repos |
+| [@goagilant.com → @togatech.com Email-Domain Migration (1.0 + 2.0)](features/goagilant-to-togatech-email-migration.md) | Reference + technique for migrating the company email domain `@goagilant.com` → `@togatech.com` across **both** platforms. |
+| [Static (no-DB) Regression Harness for 1.0 Logic + Source Drift Guard](features/static-no-db-regression-harness.md) | 1.0 has **no PHPUnit**, and most of its business logic sits inside methods that also write SQL, so "just call it" means standing up a client database. |
+| [TableView Builder (2.0 TableViews SQL generator)](features/tableview-builder.md) | `team/tableViewBuilder/` generates SQL `INSERT` statements for the **2.0 `TableViews`**, `TableViewFields`, and `TableViewJoins` tables from a plain SQL `SELECT |
+| [Talos Knowledge Base Pipeline (Uploader + Processor)](features/talos-kb-pipeline.md) | `team/talos/` holds the two-script web tooling that feeds the **TOGa Talos** (TOGa IQ) AI knowledge bases. |
+| [TOGa 2.0 Client Onboarding SQL Generator](features/toga2-client-onboarding-sql.md) | > **Superseded by the browser wizard.** The generation logic here was extracted into the reusable > `OnboardingSqlGenerator` class and wrapped in a local browse |
+| [TOGa 2.0 Client Onboarding Wizard (local tool)](features/toga2-onboarding-wizard.md) | A **local browser wizard** (`test/team/onboarding/`) that automates 2.0 client onboarding end to end: it (1) gathers developer input and **generates all onboard |
+| [TOGa 2.0 User Cross-Client Access SQL Generator](features/toga2-user-cross-client-access-sql.md) | `team/generate_toga2_user_access_sql.php` generates SQL to grant an existing 2.0 user from a **home client** access to a **cross client**. |
+| [URL & Domain Markdown Document Builder](features/url-domain-markdown-document.md) | `team/build_url_domain_markdown_document.php` generates a **markdown document of our URLs and domains** by pulling environments and domains from the 2.0 platfor |

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

@@ -1,6 +1,6 @@
 # toga (TOGa) — 1.0 knowledge
 
-| Doc | Summary | Files |
-|-----|---------|-------|
-| [Bundle Confirmation — Cart Preservation When Adding Add-On Services](features/bundleconfirmation-cart-preservation.md) | Fix: adding any add-on service (Data Transfer, Promotional Bundle, New PC Services, etc.) was silently removing the 1-year tech support SKU from the cart. | toga/app/togarefresh2026/servicerequests/bundleconfirmation.php |
-| [ODP Customer Search — Loyalty Number (merchantId) Persistence](features/odp-customer-search-loyalty-persistence.md) | Fix: the ODP loyalty number (`memberId`) stopped persisting to `Customers.merchantId` in the `TOGA_ODP` legacy database — the last non-null value was **2023-11- | toga/app/togarefresh2026/customersearch/view.php, library/app/model/customer.php |
+| Doc | Summary |
+|-----|---------|
+| [Bundle Confirmation — Cart Preservation When Adding Add-On Services](features/bundleconfirmation-cart-preservation.md) | Fix: adding any add-on service (Data Transfer, Promotional Bundle, New PC Services, etc.) was silently removing the 1-year tech support SKU from the cart. |
+| [ODP Customer Search — Loyalty Number (merchantId) Persistence](features/odp-customer-search-loyalty-persistence.md) | Fix: the ODP loyalty number (`memberId`) stopped persisting to `Customers.merchantId` in the `TOGA_ODP` legacy database — the last non-null value was **2023-11- |