toga-ai 1.0.828 → 1.0.830

package/agents/knowledge-writer.md

@@ -53,12 +53,19 @@ Search first: `node .claude/knowledge.js search --repo=<repo> --q=<keywords>`
 
 ## Step 5 — Write the doc
 
-Structure: YAML frontmatter → one-paragraph overview → main content → code examples (correct framework prefix).
-
-**On an UPDATE, append to `## Change history`, don't silently overwrite.** Every standard/architecture
-doc ends with a dated, attributed change-history list. Add a new line —
-`- YYYY-MM-DD — <what changed and why>. (<git-username>)` — and bump `updated:` in the frontmatter.
-Prefer a small UPDATE to an existing doc over a new near-duplicate.
+**Follow the doc schema (CONVENTIONS → Required sections).** Frontmatter → **first line = the
+menu entry** (one sentence: what it is + when to open it) → the type's fixed sections in order
+(feature: `## Summary` → `## How it works` → `## Gotchas` → `## Related`; workflow: `## Summary`
+→ `## Steps` → `## Gotchas` → `## Related`; standard: rules only, cases in `<name>-cases.md`).
+Correct framework prefix in code examples.
+
+**Write for Claude, not humans (CONVENTIONS → Efficiency doctrine).** Terse and exact; no
+narrative preamble, no restating the ticket. One rule, one home — link, don't restate.
+
+**On an UPDATE, TIGHTEN — never append.** Re-read the whole doc and make it leaner. Bump
+`updated:`. Prefer a small UPDATE over a near-duplicate; merge same-subject docs; delete a doc
+that is no longer true (git keeps history). Do **not** keep an in-doc changelog — git history is
+that record.
 
 ## Step 6 — Validate and re-index
 

package/agents/session-capture.md

@@ -44,14 +44,19 @@ subject doc — the default), **DEPRECATE/DELETE** (removed/obsolete), or **NO-O
 **Guardrails (enforce):**
 - One doc per **subject**, never one per change/bug/ticket.
 - **Bias UPDATE over CREATE.** A small "how it works" change updates the feature's
-  *How it works* section + a dated *Change history* line — it does not spawn a file.
+  *How it works* section — it does not spawn a file.
+- **Follow the doc schema + write for Claude (CONVENTIONS → Required sections / Efficiency
+  doctrine).** First line = menu entry; the type's fixed sections in order; terse, no human
+  prose; one rule, one home (link, don't restate).
+- **UPDATE tightens, never appends.** Make the doc leaner; merge same-subject docs; delete
+  no-longer-true docs (git keeps history).
 - Relevance test: *"Will a teammate act differently in six months because this is
   written?"* If no → **NO-OP**. NO-OP is a blessed outcome; never manufacture a doc.
 
 **Type assignment (you assign; default `feature`):** capability/model/class → `feature`;
 standalone multi-step process → `workflow`; a client's override of a shared feature →
 `client-feature`; a reversible team-wide rule → `standard` (⚠ ELEVATED); a bug's durable
-lesson → a *gotcha* / *Change history* line on the owning doc, never its own doc.
+lesson → a *gotcha* on the owning doc, never its own doc.
 
 ## Step 2 — Clients (auto — never wait to be asked)
 

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

@@ -2,4 +2,4 @@
 
 | 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`. |
+| [Authoring & Shipping a 1.0 dbchanges SQL File](workflows/authoring-and-shipping-sql-files.md) | Authoring & shipping a 1.0 `dbchanges` `.sql` file: the crude runner's parse/fail-stop model, the only working all-or-nothing guard, folder=database, and which |

package/knowledge/1.0/apps/dbchanges/workflows/authoring-and-shipping-sql-files.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-14
+updated: 2026-09-16
 owners: [sking]
 files:
   - dbchanges/index.php
@@ -19,42 +19,36 @@ related:
   - ../../../../clients/nycdoe/features/servicenow-integration.md
 ---
 
+Authoring & shipping a 1.0 `dbchanges` `.sql` file: the crude runner's parse/fail-stop model, the only working all-or-nothing guard, folder=database, and which branches auto-apply; open before writing any 1.0 dbchanges SQL.
+
 ## Summary
 
-`dbchanges` is the **1.0** (legacy/V1) schema-and-data change repository — the 1.0 sibling of
-2.0's `dbchanges2`. Unlike `dbchanges2` it ships **its own runner**, `dbchanges/index.php`, which
-is invoked by the worker tier. The runner's parsing model is crude and its error path is
-**fail-stop for the whole queue**, so *how* you write the `.sql` file decides whether your change
-(and everyone else's queued behind it) applies at all.
+`dbchanges` is the **1.0** (legacy/V1) schema-and-data change repo — the 1.0 sibling of 2.0's `dbchanges2`. Unlike `dbchanges2` it ships **its own runner**, `dbchanges/index.php`, invoked by the worker tier. The runner's parsing model is crude and its error path is **fail-stop for the whole queue**, so *how* you write the `.sql` file decides whether your change (and everyone else's queued behind it) applies at all.
 
 Two rules dominate everything below:
+1. **A chunk that contains only comments aborts the entire queue.** Put all commentary *before* the final statement; never end a commented line with a semicolon.
+2. **`_production` does NOT auto-apply.** Merged production data changes land on the next worker **deploy**, not within minutes.
 
-1. **A chunk that contains only comments aborts the entire queue.** Put all commentary *before*
-   the final statement; never end a commented line with a semicolon.
-2. **`_production` does NOT auto-apply.** Merged production data changes land on the next worker
-   **deploy**, not within minutes.
+> `dbchanges/Core/*` targets the **legacy (V1) `Core` schema** — not the 2.0 prod `Core`. Confirm the target environment before writing anything.
 
-> `dbchanges/Core/*` targets the **legacy (V1) `Core` schema** — not the 2.0 prod `Core`. Confirm
-> the target environment before writing anything.
+## Steps
 
-## How the runner parses a file (`dbchanges/index.php`)
+1. Confirm the target schema/environment (`Core/` = legacy V1 `Core`).
+2. Branch per the git-workflow rules (`fix/...`, `feature/...`) — never commit to `_production`.
+3. Write **one file, commentary first, statements last**, no trailing comment chunk, no explicit `COMMIT`, and no `DELIMITER`/stored-routine constructs.
+4. Wrap any risky data change in the derived-table preflight guard (below) so a drifted before-state is a no-op rather than a wrong write.
+5. Open a PR into `_production` (or the target `_<env>` branch).
+6. After merge: `_<env>` branches apply within ~2 min; **`_production` waits for the next worker deploy** — verify with a read-only query afterward rather than assuming. **Merging the PR applies nothing by itself** — `dbchanges` has no CI, no workflow, no runner of its own; every application is driven from the worker tier.
+7. If the change spans more than one top-level (database) folder, verify **each database separately** — see the silent-skip trap below.
 
-- Each `.sql` file is read whole and split on the **literal `";\n"`** (semicolon + newline)
-  — `index.php` ~L140. There is no SQL lexer: no awareness of strings, comments, or delimiters.
-- Every non-empty chunk is sent to MySQL through a single **`mysqli_query()`** (~L145). Multi-
-  statement execution is not used.
-- On error (~L146–170) the runner writes to `Logs.Errors` and, on the prod path, **`exit()`s** —
-  which **blocks every dbchanges file queued behind it** until the offending file is fixed.
-- Each file runs **inside a transaction**: `mysqli_autocommit($link, false)` is set before the
-  `_dbchanges` bookkeeping INSERT, and autocommit is only re-enabled (implicit COMMIT) after the
-  whole file succeeds. So on error the statement **and** its `_dbchanges` row roll back together,
-  and the file is retried on the next run.
+### How the runner parses a file (`dbchanges/index.php`)
 
-### Consequence: the "empty query" trap
+- Each `.sql` file is read whole and split on the **literal `";\n"`** (semicolon + newline) — `index.php` ~L140. There is no SQL lexer: no awareness of strings, comments, or delimiters.
+- Every non-empty chunk is sent to MySQL through a single **`mysqli_query()`** (~L145). Multi-statement execution is not used.
+- On error (~L146–170) the runner writes to `Logs.Errors` and, on the prod path, **`exit()`s** — which **blocks every dbchanges file queued behind it** until the offending file is fixed.
+- Each file runs **inside a transaction**: `mysqli_autocommit($link, false)` is set before the `_dbchanges` bookkeeping INSERT, and autocommit is only re-enabled (implicit COMMIT) after the whole file succeeds. So on error the statement **and** its `_dbchanges` row roll back together, and the file is retried on the next run.
 
-A chunk consisting solely of `--` comment lines comes back as MySQL error **1065 "Query was
-empty"** — a hard failure that stops the queue. This is easy to trigger accidentally by pasting
-verification queries or explanatory notes *after* the last statement.
+**The "empty query" trap:** a chunk consisting solely of `--` comment lines comes back as MySQL error **1065 "Query was empty"** — a hard failure that stops the queue. Easy to trigger by pasting verification queries or notes *after* the last statement.
 
 ```sql
 -- CORRECT: all commentary lives above the statement, one trailing statement.
@@ -71,22 +65,14 @@ UPDATE ...;
 
 All 13 pre-existing files under `dbchanges/Core/` comply with this. Follow them.
 
-## Expressing an all-or-nothing guard (the only pattern that works)
+### The all-or-nothing guard pattern (the only one that works)
 
 Procedural guards are **not expressible** in a dbchanges file:
+- `IF` / `SIGNAL` / conditional `COMMIT`-`ROLLBACK` on `ROW_COUNT()` are legal only inside a stored routine.
+- A routine body cannot be shipped anyway: its internal semicolons are shredded by the `";\n"` split, and `DELIMITER` is a **client** directive that `mysqli` does not understand.
+- An explicit `COMMIT` is **actively harmful** — it lands the data change independently of the `_dbchanges` bookkeeping row, breaking retry-on-failure.
 
-- `IF` / `SIGNAL` / conditional `COMMIT`-`ROLLBACK` on `ROW_COUNT()` are legal only inside a
-  stored routine.
-- A routine body cannot be shipped anyway: its internal semicolons are shredded by the `";\n"`
-  split, and `DELIMITER` is a **client** directive that `mysqli` does not understand.
-- An explicit `COMMIT` is **actively harmful** — it lands the data change independently of the
-  `_dbchanges` bookkeeping row, breaking retry-on-failure.
-
-The working pattern is a **single-statement inline preflight guard**: a derived-table subquery
-that counts the rows in the expected *before* state and requires an exact count, so the statement
-is a no-op unless reality matches the assumption. The **derived-table wrapper is load-bearing** —
-it is what avoids MySQL error **1093** ("can't specify target table for update in FROM clause").
-Validated on **MySQL 8.0.42**.
+The working pattern is a **single-statement inline preflight guard**: a derived-table subquery that counts the rows in the expected *before* state and requires an exact count, so the statement is a no-op unless reality matches the assumption. The **derived-table wrapper is load-bearing** — it is what avoids MySQL error **1093** ("can't specify target table for update in FROM clause"). Validated on **MySQL 8.0.42**.
 
 ```sql
 UPDATE SomeTable t
@@ -98,28 +84,15 @@ WHERE t.id IN (<ids>)
       ) AS preflight) = <expected-row-count>;
 ```
 
-## One top-level folder = one DATABASE (and the silent-skip trap)
+### One top-level folder = one DATABASE (and the silent-skip trap)
 
-The repo's top level is a list of **database names**, not modules: `Core`, `TOGaDeskSupport`,
-`Common`, `Logs`, `Bridge_NetSuite`, … The runner walks every top-level directory and treats the
-**folder name as the database to connect to** (`index.php` ~L55–60), then — for each folder — scans
-`config.<env>.ini` and uses the **first `[database*]` group it finds** (`~L76–80`; in
-`config.prod.ini` that is `[database_main]`) for hostname/username/password. So *all* folders are
-attempted with **one** set of credentials against one host, with only the DB name varying.
+The repo's top level is a list of **database names**, not modules: `Core`, `TOGaDeskSupport`, `Common`, `Logs`, `Bridge_NetSuite`, … The runner walks every top-level directory and treats the **folder name as the database to connect to** (`index.php` ~L55–60), then — for each folder — scans `config.<env>.ini` and uses the **first `[database*]` group it finds** (~L76–80; in `config.prod.ini` that is `[database_main]`) for hostname/username/password. So *all* folders are attempted with **one** set of credentials against one host, with only the DB name varying.
 
-Consequence: **a folder whose database is not reachable from that host is skipped silently.**
-The failure path is a bare `echo "Skipping <db> Database... unable to connect"` (`~L189`) — no
-`Logs.Errors` row, no `exit()`, no `_dbchanges` bookkeeping. Nothing retries it, and nothing tells
-you. A change that spans two databases on two different clusters (e.g. `Core` on **db_core** and
-`TOGaDeskSupport` on **db_togadesk**) therefore needs **two separate runs**, one per cluster, and
-an applier pointed at only one of them **half-applies the change and reports success**.
+Consequence: **a folder whose database is not reachable from that host is skipped silently.** The failure path is a bare `echo "Skipping <db> Database... unable to connect"` (~L189) — no `Logs.Errors` row, no `exit()`, no `_dbchanges` bookkeeping. Nothing retries it, and nothing tells you. A change spanning two databases on two different clusters (e.g. `Core` on **db_core** and `TOGaDeskSupport` on **db_togadesk**) therefore needs **two separate runs**, one per cluster, and an applier pointed at only one of them **half-applies the change and reports success**.
 
-**Rule: a multi-database change is not done until you have verified each database independently.**
-Verify **per-pair** (does *this* key have *this* value?), not by a `COUNT(*) ... IS NOT NULL` total —
-a per-count check passes on the cluster that applied and tells you nothing about the one that
-didn't.
+**Rule: a multi-database change is not done until you have verified each database independently.** Verify **per-pair** (does *this* key have *this* value?), not by a `COUNT(*) ... IS NOT NULL` total — a per-count check passes on the cluster that applied and tells you nothing about the one that didn't.
 
-## Which branches actually auto-apply
+### Which branches actually auto-apply
 
 | Path | Trigger | Timing |
 |---|---|---|
@@ -127,64 +100,20 @@ didn't.
 | Elastic Beanstalk container command (`worker/.ebextensions/030_dbchanges.config`) | worker **deploy** | on next deploy |
 
 The repo ships `config.alpha/beta/demo/hotfix/prod/stage/test/worker.ini`, therefore:
-
 - **Auto-apply within ~2 min of a push:** `_alpha`, `_beta`, `_demo`, `_hotfix`, `_stage`.
-- **`_production` does NOT auto-apply** — it would need `config.production.ini`, which does not
-  exist (the shipped file is `config.prod.ini`). Production applies via the EB deploy container
-  command instead, i.e. **on the next worker deploy**. Plan comms and expectations accordingly.
-
-## Steps
-
-1. Confirm the target schema/environment (`Core/` = legacy V1 `Core`).
-2. Branch per the git-workflow rules (`fix/...`, `feature/...`) — never commit to `_production`.
-3. Write **one file, commentary first, statements last**, no trailing comment chunk, no explicit
-   `COMMIT`, and no `DELIMITER`/stored-routine constructs.
-4. Wrap any risky data change in the derived-table preflight guard above so a drifted before-state
-   is a no-op rather than a wrong write.
-5. Open a PR into `_production` (or the target `_<env>` branch).
-6. After merge: `_<env>` branches apply within ~2 min; **`_production` waits for the next worker
-   deploy** — verify with a read-only query afterwards rather than assuming. **Merging the PR
-   applies nothing by itself** — `dbchanges` has no CI, no workflow, no runner of its own; every
-   application is driven from the worker tier.
-7. If the change spans more than one top-level (database) folder, verify **each database
-   separately** — see the silent-skip trap above.
+- **`_production` does NOT auto-apply** — it would need `config.production.ini`, which does not exist (the shipped file is `config.prod.ini`). Production applies via the EB deploy container command instead, i.e. **on the next worker deploy**. Plan comms and expectations accordingly.
 
 ## Gotchas
 
-- **A comment-only chunk stops the whole queue** (error 1065 + `exit()` on the prod path). Your
-  malformed file blocks unrelated teammates' migrations, so this is a team-wide failure, not a
-  local one.
-- **No `DELIMITER`, no stored routines, no explicit `COMMIT`.** See above.
+- **A comment-only chunk stops the whole queue** (error 1065 + `exit()` on the prod path). Your malformed file blocks unrelated teammates' migrations — a team-wide failure, not a local one.
+- **No `DELIMITER`, no stored routines, no explicit `COMMIT`.** See the guard-pattern section.
 - **Error 1093** is why the preflight subquery must be wrapped in a derived table.
-- **A merged PR is not an applied change.** Confirmed live 2026-08-13 (PR dbchanges#265): after the
-  merge into `_production`, both target tables were still 100% unchanged. Never tell a customer or a
-  ticket "applied" off a merge — always re-read the data.
-- **A cross-database change half-applies without warning.** Same incident: the `TOGaDeskSupport`
-  file landed and the `Core` file did not, leaving `assets.tag` 87/87 correct while
-  `Core.AdvanceShippingNoticeUnits.assetTag` was 87/87 still empty — a state that *looks* fixed in
-  the UI. Cause is the one-credential-set / folder-is-a-database model above. Verify every database
-  in the change, per-pair.
-- **Retry semantics are a feature**: because the data change and the `_dbchanges` row share a
-  transaction, a failing file re-runs next cycle. Do not "help" it with a manual COMMIT.
-- **⚠ SECURITY — hardcoded GitHub token.** `worker/crons/infrastructure/execute_dbchanges.php`
-  contains a **plaintext GitHub personal access token** in the small config block near the top of
-  the file (~L14–18), and interpolates it into a `shell_exec()` git-clone command line — which
-  also exposes it in the worker host's process listing. Treat the token as **compromised**:
-  rotate it, move it to config/env (`config.<env>.ini`), and pass it without embedding it in an
-  argv string. No credential value is recorded here by design.
-
-## Change history
-- 2026-08-14 — Documented that each **top-level folder is a database name** and that the runner uses
-  the **first `[database*]` config group** for every folder, so a folder on another cluster is
-  **silently skipped** (bare echo, no `Logs.Errors`, no `exit()`, no retry). Confirmed live during
-  the DOE asset-tag backfill (PR dbchanges#265): merging the PR applied nothing, and then a
-  `TOGaDeskSupport`-only run left `Core` untouched — a half-fix that looked complete in the UI.
-  Added the rule that a multi-database change needs one run per cluster and **per-pair**
-  verification, not a non-null count. (sking)
-- 2026-07-29 — Repo onboarded to the KB (1.0 `dbchanges`, framework core sibling of `dbchanges2`).
-  Documented the `index.php` `";\n"` split + `mysqli_query()` model and the comment-only-chunk /
-  error-1065 queue abort, the per-file transaction & retry semantics, the derived-table preflight
-  guard as the only workable all-or-nothing pattern (verified MySQL 8.0.42), and which `_%`
-  branches actually auto-apply (`_production` does **not** — it lands on the next worker deploy).
-  Flagged the plaintext GitHub token in `worker/crons/infrastructure/execute_dbchanges.php` for
-  rotation. (sking)
+- **A merged PR is not an applied change.** Confirmed live 2026-08-13 (PR dbchanges#265): after the merge into `_production`, both target tables were still 100% unchanged. Never tell a customer or a ticket "applied" off a merge — always re-read the data.
+- **A cross-database change half-applies without warning.** Same incident: the `TOGaDeskSupport` file landed and the `Core` file did not, leaving `assets.tag` 87/87 correct while `Core.AdvanceShippingNoticeUnits.assetTag` was 87/87 still empty — a state that *looks* fixed in the UI. Cause is the one-credential-set / folder-is-a-database model above. Verify every database in the change, per-pair.
+- **Retry semantics are a feature**: because the data change and the `_dbchanges` row share a transaction, a failing file re-runs next cycle. Do not "help" it with a manual COMMIT.
+- **⚠ SECURITY — hardcoded GitHub token.** `worker/crons/infrastructure/execute_dbchanges.php` contains a **plaintext GitHub personal access token** in the small config block near the top of the file (~L14–18), and interpolates it into a `shell_exec()` git-clone command line — which also exposes it in the worker host's process listing. Treat the token as **compromised**: rotate it, move it to config/env (`config.<env>.ini`), and pass it without embedding it in an argv string. No credential value is recorded here by design.
+
+## Related
+
+- [Worker architecture](../../worker/architecture.md) — the worker tier drives every dbchanges application.
+- [NYCDOE ServiceNow integration](../../../../clients/nycdoe/features/servicenow-integration.md)

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

@@ -2,26 +2,26 @@
 
 | 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 |
-| [NetSuite classification → ItemClasses sync (opt-in per client)](features/netsuite-item-class-sync.md) | `App_Api_Toga2::getCreateItemClass()` mirrors NetSuite's **classification tree** into the client's `ItemClasses` table and stamps `Items.itemClassId`. |
-| [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 |
-| [Rendering a 1.0 App_Email Template to HTML Offline (no DB, no send)](workflows/render-1-0-email-templates-offline.md) | How to produce a standalone `.html` copy of any 1.0 `App_Email` template — no database, no mail server, no `EmailsQueued` row. |
+| [Library (1.0 Framework) Architecture](architecture.md) | The 1.0 `App_` framework core: bootstrap/autoloader, the `app/` (`App_`) + `browser/` (`Browser_`) class trees, and vendored packages; open for how any 1.0 app |
+| [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | The shared 1.0 address-validation gateway (`App_Api_OfficeDepot::validateAddress` → USPS fallback); open when standardizing/verifying a typed address before sav |
+| [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | Where a new `App_` class goes — each `app/` folder's base class carries real inherited behavior; open before creating any class under `app/model|client|api`. |
+| [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | Reusable 1.0 SP-initiated SAML SSO via `saml.togahub.com` (`App_Sso::initiate`); the canonical doc to follow for any "add SSO to `<1.0 app>`" request. |
+| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | 1.0 cron check-in/out lifecycle via `App_Framework::cronInitialization()`/`cronFinished()` → `Common.CronJobExecutions`; open to monitor a 1.0 cron or read its |
+| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | TOGa Refresh 2026 "View Recommended Services" routing — per-device diagnostic `resultCode` decides serviceselection vs techsupport; open when touching that rout |
+| [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | Elite bidirectional ticket/attachment sync between TOGA 2 and TOGaDesk (`App_Api_Toga2::syncWithTogadesk`); open for the sync mechanics, watermarks, and Elite-s |
+| [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | 1.0 `App_Email` queued sending + attachment embedding via `Common.EmailsQueued`; open when a queued email loses attachments or when deploying worker/togadesk to |
+| [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | Branded HTML email base class `App_Email_Template` (header/body/footer); open when building or fixing a 1.0 branded email or its Outlook rendering. |
+| [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | 1.0 `App_Email::send()` side effects (log/queue writes, test-mode recipient rewrite) and how to send a genuinely write-free test; open before writing any 1.0 dr |
+| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | 1.0 error-reporting into the shared 2.0 Logs DB (`App_Error_Capture::captureException`), mirroring 2.0's Issue/Event; open when adding a 1.0 capture path or deb |
+| [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | 1.0 monitor `App_SystemMonitor_500Error` watching `Logs.Api` responseCode=500; open when an api2 500 alert arrives — its "Error Type" is noise, use `error.id`. |
+| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | Recipe for a new 1.0 (`App_`) app and for adding pages: folder-based MVC routing, page lifecycle, models, multi-DB config; open when standing up a 1.0 app or ad |
+| [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls NetSuite File Cabinet binary content (invoice PDFs) via a SuiteScript RESTlet (`fetchInvoiceFile`); open when fetching NetSuite file bytes over RE |
+| [assetType from NetSuite itemtype during Item Sync (opt-in per client)](features/netsuite-item-assettype-sync.md) | Stamp `Items.assetTypeId` from NetSuite `item.itemtype` during item sync (opt-in per client, fill-NULL-only); open before enabling asset-type mapping for a clie |
+| [NetSuite classification → ItemClasses sync (opt-in per client)](features/netsuite-item-class-sync.md) | Mirror NetSuite's classification tree into client `ItemClasses` + stamp `Items.itemClassId` (`getCreateItemClass`, opt-in per client); open before enabling item |
+| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | 1.0 Phase-1 stamping of the NetSuite `isfulfillable` flag onto the Agilant source item during sync; open before changing fulfillability sync or a client overrid |
+| [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | Working reference for the Agilant NetSuite REST/SuiteQL integration (`App_Api_Netsuite_Rest`): auth, SuiteQL mechanics, table schemas, type/status codes, perfor |
+| [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | Non-obvious NetSuite SuiteQL/REST field semantics behind `App_Api_Netsuite_Rest` shims (signs, `tl.id`==line, `iscogs`, ShipItem cost, `createdFrom`, shim-shape |
+| [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | 1.0 monitor `App_SystemMonitor_NetSuiteIntegration` — flags stale per-client NetSuite sync checkpoints (>48h) to ClickUp; open when a sync-stale alert is missin |
+| [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | PC Matic B2B bidirectional ticket sync between TOGaDesk 1.0 and TOGA 2.0 (`App_Api_Toga2`); open for ticket-type maps, StarTech client onboarding, and the V1 th |
+| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` — the 1.0-side client for the TOGa2/api2 REST API + cross-framework sync routines (`send`/`authenticate`, options DSL, `syncWithToga`/`syncWithT |
+| [Rendering a 1.0 App_Email Template to HTML Offline (no DB, no send)](workflows/render-1-0-email-templates-offline.md) | Produce a standalone `.html` copy of any 1.0 `App_Email` template offline (no DB / mail / queue) via stubs; open when asked "show me exactly what we email the c |

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

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: architecture
 status: active
-updated: 2026-06-08
+updated: 2026-09-17
 owners: [jcardinal]
 files:
   - library/_.php
@@ -15,57 +15,47 @@ files:
 related: []
 ---
 
+The 1.0 `App_` framework core: bootstrap/autoloader, the `app/` (`App_`) + `browser/` (`Browser_`) class trees, and vendored packages; open for how any 1.0 app loads and where server-side classes live.
+
 ## Summary
 
-`library` is the shared library repository for **all 1.0 (legacy) applications** — the
-`App_` framework. It provides every server-side PHP asset those apps consume:
-server-side classes, vendored third-party packages, and the bootstrap/autoloader.
-Target PHP 7.2+, compatible through 8.1.
+`library` is the shared repo for **all 1.0 (legacy) applications** — the `App_` framework. It provides every server-side PHP asset those apps consume: server-side classes, vendored third-party packages, and the bootstrap/autoloader. Target PHP 7.2+, compatible through 8.1. Each app `require`s `library/_.php` to bootstrap.
+
+**Critical rules:** All folder/file names under `app/` and `browser/` are **lowercase** (autoloader lowercases before lookup). **No front-end assets here** — JS/CSS belong in the `resources/` repo. **No Composer in consuming apps** — add packages directly to `library/`. Remove all `debugVar()` calls before merging. A class that only makes HTTP calls to an external/cross-framework API belongs in `app/api/` and should **extend nothing** (see the class-placement feature doc).
 
 ## Role in the stack
 
 - **`library/`** — server-side PHP classes, third-party packages, bootstrap/autoloader.
-- **Application repos** — each app `require`s `library/_.php` to bootstrap the framework.
-- **`resources/` repo** — purely front-end assets (JS/CSS). **Do not put front-end here.**
+- **Application repos** — each `require`s `library/_.php` to bootstrap the framework.
+- **`resources/` repo** — purely front-end assets (JS/CSS).
 
 ## Bootstrap & autoloader (`_.php`)
 
-`_.php` is the single framework include. Every app starts with
-`require_once '/path/to/library/_.php';`. It:
+`_.php` is the single framework include. Every app starts with `require_once '/path/to/library/_.php';`. It:
 
-1. Sets PHP environment — `display_errors`, `error_reporting(E_ALL)`, timezone
-   `America/Chicago`.
-2. Defines constants — `__APPROOT__` (resolved by walking up from the script's directory
-   until a folder named `_` is found) and `__LIBROOT__` (the `library/` dir).
+1. Sets PHP environment — `display_errors`, `error_reporting(E_ALL)`, timezone `America/Chicago`.
+2. Defines constants — `__APPROOT__` (resolved by walking up from the script's directory until a folder named `_` is found) and `__LIBROOT__` (the `library/` dir).
 3. Registers the autoloader via `spl_autoload_register('autoloader')`.
 
-Global helper: `debugVar($input, $stopExecution, $withHrLineBreaker)` — dumps a variable
-as HTML `<PRE>`, optionally halting. **Remove all `debugVar()` calls before merging.**
+Global helper: `debugVar($input, $stopExecution, $withHrLineBreaker)` — dumps a variable as HTML `<PRE>`, optionally halting.
 
 ### Class-to-file mapping
 
-Convert the class name to a path by replacing every `_` with `/`, then **lowercase the
-entire result** and append `.php`:
+Convert the class name to a path by replacing every `_` with `/`, then **lowercase the entire result** and append `.php`:
 
 ```
 App_Email_Nycdoe_InstallationConfirmation
   → app/email/nycdoe/installationconfirmation.php   (under __APPROOT__ or __LIBROOT__)
 ```
 
-- All folder/file names **must be lowercase**.
 - Class names are **not** case-sensitive (autoloader lowercases before lookup).
-- Both `__APPROOT__` and `__LIBROOT__` are checked, so app-level classes can **shadow**
-  library classes. Namespace separators (`\`) normalize to `_`.
+- Both `__APPROOT__` and `__LIBROOT__` are checked, so app-level classes can **shadow** library classes. Namespace separators (`\`) normalize to `_`.
 
 ## Custom code — `app/` and `browser/`
 
 ### `app/` — back-end logic (prefix `App_`)
 
-Pure server-side business logic, no HTML output. Core singletons at root (`App_Config`,
-`App_Database`, `App_Auth`, `App_Api`, `App_Model`, `App_Email`, `App_Session`).
-Subfolders: `api/` (vendor integrations), `model/`, `email/`, `notification/`, `pdf/`,
-`asnprocessor/`, `catalog/`, `client/` (client overrides), `events/`, `edi/`, `trait/`,
-`systemmonitor/`, `mvc/`.
+Pure server-side business logic, no HTML output. Core singletons at root (`App_Config`, `App_Database`, `App_Auth`, `App_Api`, `App_Model`, `App_Email`, `App_Session`). Subfolders: `api/` (vendor integrations), `model/`, `email/`, `notification/`, `pdf/`, `asnprocessor/`, `catalog/`, `client/` (client overrides), `events/`, `edi/`, `trait/`, `systemmonitor/`, `mvc/`.
 
 ```php
 class App_Model_Client extends App_Model {
@@ -76,40 +66,23 @@ class App_Model_Client extends App_Model {
 }
 ```
 
-API pattern: `abstract class App_Api` with static methods; `class App_Api_Microsoft
-extends App_Api` with `initialize()`.
+API pattern: `abstract class App_Api` with static methods; `class App_Api_Microsoft extends App_Api` with `initialize()`.
 
 ### `browser/` — server-rendered UI (prefix `Browser_`)
 
-PHP classes that emit HTML. Core components (`Browser_Form`, `Browser_Datagrid`,
-`Browser_Dialog`, `Browser_Widget`, `Browser_Sidebar`) plus subfolders: `datagrid/`
-(140+ grid views), `form/`, `dialog/`, `search/`, `widget/`, `status/` (35+ states),
-`sidebar/`, `buttonbar/`, `calendar/`, `chat/`.
+PHP classes that emit HTML. Core components (`Browser_Form`, `Browser_Datagrid`, `Browser_Dialog`, `Browser_Widget`, `Browser_Sidebar`) plus subfolders: `datagrid/` (140+ grid views), `form/`, `dialog/`, `search/`, `widget/`, `status/` (35+ states), `sidebar/`, `buttonbar/`, `calendar/`, `chat/`.
 
 ## Third-party packages (vendored, no Composer)
 
-The consuming apps use **no Composer** — this library is the "vendor" directory. Packages
-are top-level folders: `phpmailer/`, `twilio/`, `php-imap2/`, `fpdf/`/`tcpdf/`,
-`PhpOffice/`/`phpexcel/`, `Smalot/`, `phpseclib/`, SAML libs, barcode/chart libs,
-`netsuitetoolkit/`, `payeezy/`, `Zend/`/`Psr/`/`pear/`, etc. The only Composer-managed
-packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
+Consuming apps use **no Composer** — this library is the "vendor" directory. Packages are top-level folders: `phpmailer/`, `twilio/`, `php-imap2/`, `fpdf/`/`tcpdf/`, `PhpOffice/`/`phpexcel/`, `Smalot/`, `phpseclib/`, SAML libs, barcode/chart libs, `netsuitetoolkit/`, `payeezy/`, `Zend/`/`Psr/`/`pear/`, etc. The only Composer-managed packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
 
-## Key conventions
+## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
 
-- **Lowercase everything** under `app/` and `browser/`.
-- **No front-end assets here** — JS/CSS belong in `resources/`.
-- **No Composer in consuming apps** — add packages directly to `library/`.
-- **`debugVar()`** is the debug helper; remove all calls before merging.
-- **Timezone** is always `America/Chicago` (set in `_.php`).
-- **`__APPROOT__`** is resolved by locating an ancestor folder named `_`; each app must
-  have that `_` folder at its root.
+`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do **AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0 `_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0 gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method changed. First consumer: the Tools app's `App_Auth` (`1.0/apps/tools/features/saml-sso-auth.md`).
 
-## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
+## Gotchas
 
-`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do
-**AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl
-flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0
-`_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0
-gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method
-changed, no behavior change for existing apps. First consumer: the Tools app's `App_Auth`
-(`1.0/apps/tools/features/saml-sso-auth.md`).
+- **`debugVar()` can halt execution** (its `$stopExecution` arg) — remove all calls before merging.
+- **app/ classes silently shadow library/ classes.** The autoloader checks both `__APPROOT__` and `__LIBROOT__`, so an app-level file with the same class path overrides the core one with no warning.
+- **`__APPROOT__` resolution needs the `_` folder.** It is found by locating an ancestor folder named `_`; each app must have that `_` folder at its root or the constant won't resolve.
+- **⚠ SECURITY — OPEN, SYSTEMIC, not fixed (2026-09-17): TLS peer verification is OFF by default for EVERY `App_ApiTransaction` call.** `library/app/apitransaction.php:363` computes `CURLOPT_SSL_VERIFYPEER` from `$sslVerifyPeer` (default `null`, line 77) as `(((is_null($sslVerifyPeer) && isHTTPS()) || !$sslVerifyPeer) ? false : true)` — which resolves to **`false` on HTTPS**. So every outbound HTTPS call through the shared transport (NetSuite OAuth token exchange, every REST read, the RESTlet call, and any other `App_Api_*` integration) runs with peer verification disabled — a MITM can capture the bearer token or inject responses. Pre-existing core defect, **not** caused by the NetSuite retry; affects all callers. Fix: `CURLOPT_SSL_VERIFYPEER = is_null($sslVerifyPeer) ? isHTTPS() : (bool)$sslVerifyPeer;` and have `rest.php` pass `setSSLVerifyPeer(true)` explicitly. No fix chosen yet. The paired token-logging defect (`send()` writes the bearer token to the request log) is on the [SuiteQL/REST shim doc](features/netsuite-suiteql-rest-shim.md).

package/knowledge/1.0/apps/library/features/address-validation-gateway.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-13
+updated: 2026-09-16
 owners: [jcardinal]
 files:
   - library/app/api/officedepot.php
@@ -15,63 +15,29 @@ related:
   - ../../toga/features/odp-customer-search-loyalty-persistence.md
 ---
 
+The shared 1.0 address-validation gateway (`App_Api_OfficeDepot::validateAddress` → USPS fallback); open when standardizing/verifying a typed address before save, or debugging a saved-raw-address bug.
+
 ## Summary
-`App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway.
-It is the entry point every TOGa 1.0 flow calls (via classic AJAX
-`ajaxAction('App_Api_OfficeDepot','validateAddress')`) to standardize/verify a typed address
-before it is saved. It wraps ODP's address-validation service and falls back to
-`App_Api_USPS::validateAddress()` (USPS REST API v3, OAuth `client_credentials`, in
-`library/app/api/usps.php`). It returns a standardized address (corrected city/casing/zip) that
-callers are expected to write back before saving.
 
-## Key files / entry points
+`App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway. Every TOGa 1.0 flow calls it (via classic AJAX `ajaxAction('App_Api_OfficeDepot','validateAddress')`) to standardize/verify a typed address before save. It wraps ODP's address-validation service, falls back to `App_Api_USPS::validateAddress()` (USPS REST API v3, OAuth `client_credentials`), and returns a standardized address (corrected city/casing/zip) that callers must write back before saving.
+
+## How it works
+
+Entry points:
 - `library/app/api/officedepot.php` — `App_Api_OfficeDepot::validateAddress()`, the gateway.
 - `library/app/api/usps.php` — `App_Api_USPS::validateAddress()`, the fallback carrier.
 
-## How it works
-1. **Endpoint selection.** The gateway calls the ODP **sandbox** endpoint when
-   `App_Registry::inTestMode()` is true (`inTestMode` = `config['internal']['test_mode'] > 0`),
-   and the **live** ODP endpoint otherwise. Production is effectively hard-pinned to live
-   (comment "2024-01-22 JC - Always using production...").
-2. **On a real ODP answer** (HTTP 200, whether it accepts or rejects the address) the gateway
-   returns ODP's standardized result.
-3. **On any non-200 ODP response** (sandbox down/expired, etc.) it falls back to
-   `App_Api_USPS::validateAddress()` and returns the USPS result — a genuine standardization
-   **or** a genuine bad-address rejection both count as a real answer and are returned.
-4. **Only when BOTH ODP and USPS are unavailable** does it return `array('success' => true)`
-   with no standardized fields (fail-open, so associates are never hard-blocked by an outage).
+1. **Endpoint selection.** Calls the ODP **sandbox** endpoint when `App_Registry::inTestMode()` is true (`inTestMode` = `config['internal']['test_mode'] > 0`), and the **live** ODP endpoint otherwise. Production is effectively hard-pinned to live (comment "2024-01-22 JC - Always using production...").
+2. **On a real ODP answer** (HTTP 200, accept or reject) returns ODP's standardized result.
+3. **On any non-200 ODP response** (sandbox down/expired, etc.) falls back to `App_Api_USPS::validateAddress()` and returns the USPS result — a genuine standardization **or** a genuine bad-address rejection both count as a real answer and are returned.
+4. **Only when BOTH ODP and USPS are unavailable** returns `array('success' => true)` with no standardized fields (fail-open, so associates are never hard-blocked by an outage).
+
+## Gotchas
 
-## Gotchas / known issues
-- **Beta-bypass class of bug (fixed 2026-08-13).** Previously the ODP-failure `else` branch
-  returned `array('success' => true)` with **no** standardized address fields and the USPS
-  fallback was commented out. Beta/test uses the ODP **sandbox**; when the sandbox was
-  down/expired, callers saw `success:true` and saved the **raw typed address** (wrong city,
-  wrong casing) with no validation. Production was unaffected because it hits the working live
-  ODP endpoint. The fix restores the USPS fallback so a validation only truly fails open when
-  **both** carriers are down.
-- **"Both unavailable" must check BOTH USPS service-down strings.** USPS signals unavailability
-  two ways: `'Address validation service is temporarily unavailable'` **and**
-  `'USPS OAuth authentication failed'`. The fail-open condition must match either. Checking only
-  the first string wrongly blocks associates when ODP is down *and* USPS OAuth also fails
-  (a php-reviewer pass caught this).
-- **Front-end write-back anti-pattern (widespread, mostly UNFIXED).** Many 1.0 front-end
-  callbacks use the gateway response only as a pass/fail **gate**, then rebuild the save payload
-  from the raw DOM inputs — discarding the standardized `address1`/`city`/`state`/`zipCode` the
-  gateway returned. So even a successful validation never persists the corrected address. Known
-  flows with this anti-pattern still present:
-  `toga/app/togarefresh2026/servicerequests/finalizequote.php`,
-  `toga/app/togarefresh2026/appointment/select.php`,
-  `toga/app/servicerequests/builder.php`, `toga/app/loaners/checkout.php`,
-  `toga/app/jobjackets/view.php`, and the `togarefresh2023` variants. The 2026-08-13 gateway fix
-  protects all of them from the beta bypass, but the write-back was only corrected in the
-  `togarefresh2026` customersearch flow (see related doc). When touching any of these, write the
-  standardized address back into the inputs before building the save payload.
+- **Beta-bypass class of bug (fixed 2026-08-13).** Previously the ODP-failure `else` branch returned `array('success' => true)` with **no** standardized address fields and the USPS fallback was commented out. Beta/test uses the ODP **sandbox**; when the sandbox was down/expired, callers saw `success:true` and saved the **raw typed address** (wrong city, wrong casing) with no validation. Production was unaffected (working live ODP endpoint). The fix restores the USPS fallback so validation only truly fails open when **both** carriers are down.
+- **"Both unavailable" must check BOTH USPS service-down strings.** USPS signals unavailability two ways: `'Address validation service is temporarily unavailable'` **and** `'USPS OAuth authentication failed'`. The fail-open condition must match either. Checking only the first wrongly blocks associates when ODP is down *and* USPS OAuth also fails (a php-reviewer pass caught this).
+- **Front-end write-back anti-pattern (widespread, mostly UNFIXED).** Many 1.0 front-end callbacks use the gateway response only as a pass/fail **gate**, then rebuild the save payload from the raw DOM inputs — discarding the standardized `address1`/`city`/`state`/`zipCode` the gateway returned. So even a successful validation never persists the corrected address. Known flows still with this anti-pattern: `toga/app/togarefresh2026/servicerequests/finalizequote.php`, `toga/app/togarefresh2026/appointment/select.php`, `toga/app/servicerequests/builder.php`, `toga/app/loaners/checkout.php`, `toga/app/jobjackets/view.php`, and the `togarefresh2023` variants. The 2026-08-13 gateway fix protects all from the beta bypass, but the write-back was only corrected in the `togarefresh2026` customersearch flow (see related doc). When touching any of these, write the standardized address back into the inputs before building the save payload.
 
-## Related docs
-- `../../toga/features/odp-customer-search-loyalty-persistence.md` — the customersearch save
-  flow, where the write-back fix was applied.
+## Related
 
-## Change history
-- 2026-08-13 — Fix: restored the USPS fallback in `App_Api_OfficeDepot::validateAddress` so the
-  beta/sandbox path no longer fakes `success:true` and saves unvalidated addresses; fail-open now
-  requires BOTH ODP and USPS down, checking both USPS service-down strings. (jcardinal)
+- `../../toga/features/odp-customer-search-loyalty-persistence.md` — the customersearch save flow, where the write-back fix was applied.