toga-ai 1.0.966 → 1.0.968

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

@@ -12,6 +12,7 @@
 | [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 |
+| [App_Email SES Sender Identity (every From address must be verified in SES first)](features/email-ses-sender-identity.md) | 1.0 `App_Email` sends through Amazon SES SMTP; any new From address must be a verified SES identity first or SES rejects the send. |
 | [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 |

package/knowledge/1.0/apps/library/features/email-ses-sender-identity.md

@@ -0,0 +1,42 @@
+---
+title: App_Email SES Sender Identity (every From address must be verified in SES first)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-10-07
+owners: ["bala"]
+files:
+  - library/app/email.php
+related:
+  - ./email-queue-attachments.md
+  - ./email-test-mode-and-write-free-sends.md
+  - ../../tools/features/legacy-email-notifier.md
+  - ../../test/features/goagilant-to-togatech-email-migration.md
+  - ../../../../clients/compass-canada/profile.md
+---
+
+1.0 `App_Email` sends through Amazon SES SMTP; any new From address must be a verified SES identity first or SES rejects the send. Open before changing a `sendFromEmailAddress` / `fromEmailAddress` to a new address or a customer domain.
+
+## Summary
+
+`App_Email` (`library/app/email.php`) sends via PHPMailer to SES SMTP at `email-smtp.us-west-2.amazonaws.com`, in the **toga-legacy** AWS account, region **us-west-2** (not us-east-1). SES only accepts a From address that is a verified identity in that account and region. The account is out of the SES sandbox, so To/CC recipients need no verification. Only the sender does.
+
+## How it works
+
+- **Domain identity:** `togatech.com` is verified as a whole domain, so any `@togatech.com` From works.
+- **Customer-domain addresses are single EMAIL_ADDRESS identities**, not domains. Verified so far: `techhub@compass-usa.com`, `Techhub.Canada@compass-canada.com`.
+- **Verifying one address:** SES mails a link from `no-reply-aws@amazon.com`, subject "Amazon Web Services – Email Address Verification Request in region US West (Oregon)". The customer's mailbox owner must click it within **24h**. Until then the identity is pending and sends fail.
+- **Alternative:** a domain identity for the customer domain. Needs the customer's IT to add DKIM DNS records. Use it when several addresses on that domain will send.
+- **Order of work:** verify the identity in SES, confirm it shows verified, *then* run the SQL that switches `EmailTemplates.sendFromEmailAddress` / `IntegrationsEmail.fromEmailAddress`. Flipping the data first breaks every send from those templates.
+
+## Gotchas
+
+- **The AWS verification email often lands in the customer's quarantine or spam.** Tell the mailbox owner to look there, and to release it within the 24h window. If it expires, re-send the verification.
+- **A verified customer address is not proof it is used as a sender.** Compass USA vendor PO emails send from `compasssupport@togatech.com` (`Client_Compass.IntegrationsEmail`, 6 rows). `techhub@compass-usa.com` appears there only as To/CC.
+- Apps that cannot run `App_Email::send()` (the tools app) still hit SES with the same rule. See [legacy email notifier](../../tools/features/legacy-email-notifier.md).
+
+## Change history
+- 2026-10-07 — Documented the SES sender-identity rule and customer-address verification flow, after moving the Compass Canada TechHub sender to `Techhub.Canada@compass-canada.com` (bala)

package/knowledge/1.0/apps/test/features/2-0-deployment-client-sql.md

@@ -6,8 +6,8 @@ project: Test
 client: shared
 type: feature
 status: active
-updated: 2026-09-22
-owners: [jcardinal]
+updated: 2026-10-07
+owners: [jcardinal, mhammontree]
 files:
   - test/team/2.0 deployment/generate_client_sql.php
   - test/team/2.0 deployment/INPUT.sql
@@ -31,6 +31,12 @@ Use [Tools Multi-Client SQL](../../tools/features/multi-client-sql.md) instead (
 2. Reads one static list file; switch lists by commenting between `Clients_Db.txt` / `Logs_Clients_Db.txt` / `NetSuite_Clients_Db.txt` in the script.
 3. Per DB: banner comment, `` USE `<db>`; ``, then the SQL. Prints the combined script with a header and DB count.
 
+## The three list files (verified prod 2026-10-07)
+
+- **`Clients_Db.txt` — 35 entries, and all 35 match the live tenant databases exactly. It is NOT stale.** The 11 extra `Core.Clients` rows have no database (see [per-client DB connections](../../../../2.0/apps/_underscore/features/per-client-database-connections.md)); adding them would point the fan-out at databases that do not exist.
+- **`NetSuite_Clients_Db.txt` — 22 clients, an exact duplicate** of the clients whose `dbchanges2/Client_<Name>/_modules.txt` names `netsuite`. Same list kept twice; `_modules.txt` is the better source because it sits next to the client it describes.
+- Retiring these files means retiring `generate_client_sql.php` (it reads all three, including a commented-out `Logs_Clients_Db.txt`) — not just deleting text files. Production already uses tools `/developers/multi-client-sql`.
+
 ## Gotchas
 
 - Lists are static — a stale/missing DB is silently skipped. The Tools tool reads them live.
@@ -42,4 +48,6 @@ Use [Tools Multi-Client SQL](../../tools/features/multi-client-sql.md) instead (
 
 ## Change history
 
+- 2026-10-07 — Verified the list files: `Clients_Db.txt` is accurate (35/35); `NetSuite_Clients_Db.txt` duplicates dbchanges2 `_modules.txt`. (mhammontree)
+
 - 2026-09-22 — Marked superseded by Tools Multi-Client SQL; corrected input file (`INPUT.sql`) and list-switching. (jcardinal)

package/knowledge/1.0/apps/tools/features/multi-client-sql.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-09-24
-owners: [jcardinal]
+updated: 2026-10-07
+owners: [jcardinal, mhammontree]
 files:
   - tools/_/app/developers/multiclientsql.php
   - tools/mvc/developers/multi-client-sql/get.php
@@ -38,8 +38,19 @@ Replaces `test/team/2.0 deployment/generate_client_sql.php`. Development Team pe
 5. Every list returns a `skipped` array, shown on the page ("Skipped N (database not built — no DatabaseHosts row): …").
 6. Every DB/folder name is checked against `^[A-Za-z0-9_]{1,64}$` before it goes into GraphQL or a `USE` line. Page writes via `textContent`/`.value` only.
 
+## Reusing it from another tools page
+
+- `token()` is already `public static` and reads `GITHUB_TOKEN` from `getenv()` + `$_SERVER` + `$_ENV`. That token already has read access to `agilantsolutions/dbchanges2` in production — a second page needs **no new PAT and no new EB property**.
+- `graphql(string $fields, string $step)` is `private static` and carries the whole transport (curl, host pinned to `api.github.com`, bearer token, 30s timeout, one retry on a dropped connection, GraphQL error handling, and never logging the request because it holds the Authorization header). Making it `public static` is a one-keyword change with no behavior change — do that rather than re-implementing curl.
+- `GITHUB_BRANCH` is a const `_main` baked into expressions inside private methods. A page needing another branch builds its own field strings and borrows only the transport — do **not** thread a `$branch` parameter through the shipped class.
+- `DB_NAME_PATTERN` is `^[A-Za-z0-9_]{1,64}$` and **rejects dbchanges2 filenames** (`2026-06-03- BLANK_CLIENT_DATABASE.sql` has dashes, spaces, a dot). A page listing files needs its own filename pattern.
+- `treeFolders()` keeps only `type === 'tree'` — folders only, never files.
+- The `_modules.txt` parse (lowercase, trim, skip blank lines) already tolerates the trailing blank lines in `Client_Spglobal/_modules.txt`.
+
 ## Gotchas
 
+- Nested module folders are not handled: `_modules/Ai/Bdr/` makes the module list show `Ai` with zero member clients. Pre-existing live limitation, not a regression.
+
 - `Databases` is a MySQL reserved word: `FROM Databases` / `JOIN Databases AS X` fails with error 1064. Backtick it (`` `Databases` ``) or qualify it (`Core.Databases`).
 - dbchanges2 has **no** `_production` branch; its deployed branch is `_main`.
 - A missing `[database_...]` config section is not catchable in 1.0 — `App_Error` renders its HTML error page and exits. The tool pre-checks `config['database_toga2core']` and throws a user-safe message. Local `config.dev-*.ini` files may lack that section.
@@ -52,5 +63,7 @@ Replaces `test/team/2.0 deployment/generate_client_sql.php`. Development Team pe
 
 ## Change history
 
+- 2026-10-07 — Added the reuse map for other tools pages (`token()`, `graphql()`, the branch const and name patterns) and the nested `_modules/Ai/Bdr` limitation. (mhammontree)
+
 - 2026-09-22 — Created; shipped and verified in production. (jcardinal)
 - 2026-09-24 — Lists filtered by `Core.DatabaseHosts` for `ENVIRONMENT`; `skipped` list shown; verified prod 35 of 46. (jcardinal)

package/knowledge/1.0/apps/tools/features/saml-sso-auth.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-10-02
+updated: 2026-10-07
 owners: [jcardinal, ajean, mhammontree]
 files:
   - tools/_/app/auth.php
@@ -88,6 +88,7 @@ The platform's rotating key/value parameter store, on the **2.0 PROD Core DB** (
 - **Failure path also fataled → fixed (2026-06-30).** `tools_ssoFail()` called `http_response_code(401)` to render the "Authentication failed" page, which itself fataled with "headers already sent" and the error handler escalated it to an uncaught `ErrorException` → a bare **500** instead of the intended 401 page. Root cause: `App_FrameworkIndex::render()` turns on the preloader and runs `App_Page::flushCapture()` (`ob_end_flush + flush`, `library/app/page.php:213`) **before** `body()/App_MVC::loadFile()` runs the mvc page. Fixed with the same `if (!headers_sent()) { http_response_code(401); }` guard (matches `App_MVC::routeTo`'s own check).
 - **`App_Sso::initiate()` hard-requires a non-empty `apiSecretAccessToken`** (`library/app/sso.php:64-65`, `empty()` guard → `InvalidArgumentException`; the token encrypts the RelayState). An empty/absent token surfaces as a redirect to **`/login?error=1` ("Sign in failed. Please try again.")** — the initiate leg catches the exception (`sso/initiate/get.php:30-34`) and routes to `/login?error=1`. This fails **before** the IdP round-trip, so it never reaches the consumer's **"Authentication failed"** (`tools_ssoFail`) page. **The two error UIs tell you which leg failed:** `/login?error=1` = initiate (RelayState encryption / token), "Authentication failed" = consumer (decrypt). This was the 2026-06-30 regression — removing the config token per the (wrong) earlier note made initiate throw.
 - **Both legs depend on `db_toga2core` + a populated `Core.Parameters` token.** If `[database_toga2core]` is not configured, `currentApiSecret()`/`handoffKeys()` runs `App_Database::query` against an unregistered alias and **throws**. Because initiate only catches `InvalidArgumentException`/`RuntimeException`, that surfaces as a **500** — not the login banner. **Diagnostic:** a 500 at initiate = missing `db_toga2core`; `/login?error=1` = empty/absent `API_SECRET_ACCESS_TOKEN`.
+- **Local dev-bypass login fails with a bare "Sign in failed." — the cause is usually a missing config section, not SSO.** `tools/mvc/login/post.php` routed an invalid/empty email **and** a not-found user to `/login?error=1` with no logging, so three different causes looked identical. Each failure branch now writes one `error_log` line naming which branch fired (the not-found branch points at `[database_true]`). Root cause in practice: `config.dev-<name>.ini` is missing **`[database_true]`** and/or **`[database_toga2core]`**. Those two sections are commonly absent from local `config.dev-*.ini` files; without `[database_toga2core]` the Multi-Client SQL and Central IDs pages also fail. Copy them from a config that has both.
 - **No app-side replay defense.** The handoff token carries no nonce/timestamp the app verifies. Recommend the gateway embed `iat` + `jti`.
 
 ## Related
@@ -99,4 +100,6 @@ The platform's rotating key/value parameter store, on the **2.0 PROD Core DB** (
 - [TOGa Desk staff SSO (same pattern)](../../togadesk/features/staff-sso-login.md)
 
 ## Change history
+
+- 2026-10-07 — Dev-bypass login now logs which failure branch fired; documented the missing `[database_true]` / `[database_toga2core]` local-config cause. (mhammontree)
 - 2026-10-02 — Clarified sign-in is one click on an SSO button; no auto-detect of a Microsoft session (mhammontree)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-09-23
+updated: 2026-10-07
 owners: ["jcardinal", "rgirish", "mhammontree", "ajean"]
 files:
   - _underscore/_underscore.php
@@ -177,22 +177,32 @@ string** has a single leading capital, rest lower-case (e.g. `Towfoundation`):
 | Tenant logs | `Logs_<Tenant>` | Per-client activity/audit logs. |
 | Framework logs | `Logs` | Generic 2.0 logs not tied to any client. |
 
-**Resolving a tenant string from a client name:** query `Core.Clients`. The
-`clientIdentifier` field **is** the exact suffix used in `Client_`, `Archive_`, and
-`Logs_` database names; the `name` field is the human-readable label. Look up by either
-to find the other:
+**Resolving a tenant's real database names:** query `Core.Clients`, then follow the id
+columns into `Core.Databases` — **never build the name as `'Client_' . $clientIdentifier`.**
 
 ```sql
 SELECT
-    name,
-    clientIdentifier
-FROM Clients
+    c.name,
+    c.clientIdentifier,
+    cd.name AS clientDatabase,
+    ld.name AS logDatabase,
+    ad.name AS archiveDatabase
+FROM Clients AS c
+    LEFT JOIN `Databases` AS cd ON cd.id = c.clientDatabaseId
+    LEFT JOIN `Databases` AS ld ON ld.id = c.logDatabaseId
+    LEFT JOIN `Databases` AS ad ON ad.id = c.archiveDatabaseId
 WHERE
-    name LIKE '%<keyword>%'
+    c.name LIKE '%<keyword>%'
 ```
 
-A client whose `clientIdentifier` is `Towfoundation` therefore lives in
-`Client_Towfoundation`, `Archive_Towfoundation`, and `Logs_Towfoundation`.
+`clientIdentifier` usually matches the suffix (`Towfoundation` → `Client_Towfoundation`,
+`Archive_Towfoundation`, `Logs_Towfoundation`), but that is a **convention, not a rule**.
+Verified in prod: `Compass_Usa` → `Client_Compass` / `Logs_Compass` / `Archive_Compass`, and
+`Compass_Canada` → `Client_CompassCanada` / `Logs_CompassCanada` / `Archive_CompassCanada`.
+There is no `Client_Compass_Usa`. A string-built name passes local testing and breaks in
+production for exactly those clients. Precedent that does it right:
+`App_Developers_MultiClientSql::coreLists()` in 1.0 `tools`. See
+[per-client database connections](features/per-client-database-connections.md).
 
 #### Non-production environments
 
@@ -428,3 +438,7 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
   message/trace to the client if `display_errors` is on unconditionally. Confirm `display_errors` is
   disabled in production and that the framework's error surface returns a sanitized envelope (not a raw
   stack trace) to API consumers. Not yet done — tracked as a follow-up.
+
+## Change history
+
+- 2026-10-07 — Corrected tenant DB-name resolution: resolve `Core.Clients` id columns into `Core.Databases`; `clientIdentifier` is not the suffix (Compass). (mhammontree)

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-06
+updated: 2026-10-07
 owners: ["dfranks", "jcardinal", "mhammontree", "apeterson", "kyalamarthi", "bala"]
 files:
   - _underscore/Database.php
@@ -59,7 +59,7 @@ When `_underscore` serves a request for a client it opens **three distinct per-c
 
 ## Gotchas
 
-- **`Core.Clients` has rows for clients whose DBs were never built** (prod 2026-09-24: 46 rows, 35 built). "DB exists" = a `Core.DatabaseHosts` row (`databaseId` + `environmentId` [+ `regionId`]) for the current `Environments.slug` — the same rows `registerClientDatabases()` resolves. Any fan-out over all clients must filter `EXISTS` on `DatabaseHosts` for the env, not `Core.Clients` alone; `isActive`-style flags are wrong (inactive clients still have DBs). Host-row count varies (e.g. `Archive_Nychh` has 1, others 4) — still built. Example: [Tools Multi-Client SQL](../../../../1.0/apps/tools/features/multi-client-sql.md).
+- **`Core.Clients` has rows for clients whose DBs were never built** (prod 2026-09-24: 46 rows, 35 built). "DB exists" = a `Core.DatabaseHosts` row (`databaseId` + `environmentId` [+ `regionId`]) for the current `Environments.slug` — the same rows `registerClientDatabases()` resolves. Any fan-out over all clients must filter `EXISTS` on `DatabaseHosts` for the env, not `Core.Clients` alone; `isActive`-style flags are wrong (inactive clients still have DBs). Host-row count varies (e.g. `Archive_Nychh` has 1, others 4) — still built. The 11 registered-but-never-provisioned clients (prod 2026-10-07): **Agilant, Athena, Cloudcsp, Companycom, Eclinicalworks, Ims, Newegg, Officedepot, Staples, Synnex, Walmart** — each has a `Core.Databases` row naming `Client_<Name>`, but no schema. Do **not** add them to any fan-out list. Also on the prod client cluster: a stray `Client_Compass_20260831_120000` schema (looks like an Aug-31 manual backup copy) — confirm with the owner before dropping. Example: [Tools Multi-Client SQL](../../../../1.0/apps/tools/features/multi-client-sql.md).
 - **⚠ NEVER read `LAST_INSERT_ID()` (or any other per-connection session value) through `_Query`.** `_Query` defaults `_isReadHostEnabled = true` (`Query.php:8`) and routes SELECTs to `CONNECTION_READ` (`Query.php:273-276`). `LAST_INSERT_ID()` is scoped to the connection that did the INSERT, so a read-host SELECT returns **0** — silently wrong, and now an FK violation wherever the id is used as a foreign key. Use `mysqli_insert_id` on the write/transaction connection and reject `<= 0`. It is not biting today only because most client registrations leave `writeHost`/`readHost` null, and `Database.php:488` then points READ and WRITE at the **same** `mysqli` handle (so raw `mysqli_query` and `new _Query(...)` share one connection and one transaction). Configuring a real read host for any client would break every such call at once. Worked example: [Compass PEOPLE-file user lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
 - **Locks and just-committed rows: force the writer and skip the cache.** A `_Query` SELECT goes to the read host and may be served from the query cache. For `GET_LOCK`/`RELEASE_LOCK` (session-scoped — must be on the writer) or reading a row another job just committed, call `$query->setisReadHostEnabled(false)` and `_Database::useQueryCache(false)`. Worked example: NYCDOE `Sftp/Import` per-checksum lock in [2.0 ASN SFTP Ingestion](../../../../clients/nycdoe/features/asn-sftp-ingestion-2-0.md).
 - **`_Database::transactionCommit()` / `transactionRollback()` with NO database argument leave each alias's "started" flag `true`.** A later `transactionStart()` in the same PHP process then never begins a transaction — writes autocommit and a rollback undoes nothing. Prod worker jobs and api2 requests are safe (one job/request = fresh process state); it bites long-lived processes and test harnesses. Reset with `\_Database::$_transactionStarts = []` before `transactionStart()` (see `runAsWorkerJob` in [worker2 Codeception tests](../../worker2/features/codeception-integration-tests.md)).
@@ -94,6 +94,7 @@ Methodology lesson — why the wrong conclusion was reached: the model-class com
 - [Re-pointing a DB alias mid-request](./database-alias-repointing.md)
 
 ## Change history
+- 2026-10-07 — Named the 11 registered-but-unprovisioned prod clients and the stray `Client_Compass_20260831_120000` backup schema. (mhammontree)
 - 2026-10-06 — Writer+no-cache reads for locks/just-committed rows; no-arg commit/rollback leaves the transaction-started flag set (mhammontree)
 - 2026-09-23 — Added the read-host routing trap: `_Query` sends SELECTs to `CONNECTION_READ`, so `LAST_INSERT_ID()` read through `_Query` can return 0; noted that null `writeHost`/`readHost` currently collapses both to one handle, and that raw `mysqli_query` needs a manual `resetQueryCache()`. (mhammontree)
 - 2026-09-24 — Added gotcha: filter client fan-outs by `DatabaseHosts` for the environment; `Core.Clients` includes never-built clients. (jcardinal)

package/knowledge/2.0/apps/dbchanges2/workflows/client-onboarding.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-10-07
 owners: ["mhammontree"]
 files:
   - Client/
@@ -51,6 +51,21 @@ Order matters — each step assumes the prior one ran.
 - **api2 / _underscore** — the API the client calls; verify here.
 - **Bastion** — production deploy path (upload SQL, source per cluster).
 
+## Planned onboarding tool — settled design (TRUE-79864)
+
+Platform-level and host-independent. Decided 2026-10-07; **host moved to Desk 2.0 (`toga25-desk`)**, which already plans an "Add Client" button. The 1.0 `tools` hosting plan is dead (no `App_Devops_*` classes, no 1.0 MVC page, no persona nav entry, and `App_Developers_MultiClientSql` is a 1.0 class Desk cannot reach). Builds on the 2026-06-22 Jeff design spec (ticket TRUE-79702) at `2.0-new-client-onboarding-consolidation.md` — read that file for the spec; it is not copied here.
+
+- **Generates SQL and guides. It never executes SQL and never writes to a repository.** Because it never writes, the "two onboardings at once" branch-lock problem does not exist.
+- **Output is split by cluster:** (A) `CREATE DATABASE` Client_/Logs_/Archive_; (B) the apply order for `Client_<Id>` — newest-dated blank, then loose `Client/*.sql` in filename order, then the chosen modules' files, **file names and order only, not the SQL text**; (C) the `Logs_Client/` blank for `Logs_<Id>`; (D) Core registration inserts (secret-free, committable); (E) `Apis` + `Apis_Roles` (secrets, shown once, never committed).
+- **`Logs_<Name>` is IN scope** even though the 2026-06-22 spec deferred it: the API logs there and checks the auth rate limit against it, so deferring it leaves a client that registers fine and then cannot authenticate.
+- **Branch is picked from a drop-down**, excluding the repo default branch (`_main`) and any protected branch — onboarding always runs against a ticket branch. Read the default branch name from the API; never hardcode it.
+- **Modules: selection only** (spec step 5 — read `_modules/`, tick what the client uses, fold its files into the apply order, write the client's `_modules.txt` line). Module **consolidation** (spec step 4) is OUT; it is a write. **Blank consolidation is also OUT** — `Client/HISTORIC` shows ~15 rewrites over ~2 years, so it is periodic maintenance on its own clock, not part of onboarding.
+- **The `Apis` secret is generated in the browser** with `crypto.getRandomValues` and the INSERT is built client-side, so plaintext never reaches the server or a log. (`crypto.randomUUID` and `crypto.subtle` are undefined on a non-secure origin; `getRandomValues` is not.)
+- **Run history: two new prod `Core` tables** — `ClientOnboardings` (client, branch, commit SHA, blank filename, loose-file count, ticket ref, who, status, email domains, modules, the ordered file list as TEXT) and `ClientOnboardingEnvironments` (FK to `Core.Environments.id`, isApplied, dtApplied, appliedByEmail). `Core.Environments` exists in prod with 27 rows (production = id 1). Two constraints: **no FK to the user** (`Client_True` is on the client cluster, `Core` on the core cluster), and **never store the `Apis` secret**.
+- **The internal API-key row is named `TOGA Technology`, not `Agilant`** — the old company name is not used for new work. The existing generator still emits `Agilant`.
+- **The one real correctness risk is a stale local checkout.** If the developer's checkout is ahead of the branch the tool reads, the tool lists *fewer* files than exist and the new client silently misses migrations, with no error. Mitigation: print the branch, the commit SHA, the file count, each file's blob SHA, and one verify command.
+- **Open question:** Desk is React talking to api2, so the GitHub read must move server-side into api2 or worker2 — a long read inside a web request hits a timeout problem.
+
 ## Gotchas
 
 - **🚨 The blank can be WRONG, not just behind — an open example (2026-08-28).** `Client/2026-06-03- BLANK_CLIENT_DATABASE.sql` creates `TransferOrderItems` (`CREATE` at ~line 9462) **without `dtCreated`/`dtUpdated`**, but `_Model_Client_TransferOrderItem` declares them as `FIELD_DATETIME_CREATED`/`FIELD_DATETIME_UPDATED`, so `_Model` puts them in **every SELECT it builds**. Every tenant provisioned from this blank has a table the model cannot read — nothing in a request has to ask for the columns. `Client/2026-08-28b - TransferOrderItemsTimestamps.sql` repairs existing tenants; **the blank itself is still unfixed**, so the next onboarding reproduces it. When a model-vs-blank mismatch is found, fix **both**: a catch-up `Client/` file for live tenants *and* the blank.
@@ -69,3 +84,7 @@ Order matters — each step assumes the prior one ran.
 - [TOGa 2.0 client onboarding SQL generator](../../../1.0/apps/test/features/toga2-client-onboarding-sql.md)
 - [TOGa 2.0 Client Onboarding Wizard](../../../1.0/apps/test/features/toga2-onboarding-wizard.md)
 - [Tickets API](../../api2/features/tickets-api.md)
+
+## Change history
+
+- 2026-10-07 — Recorded the settled design for the onboarding tool (TRUE-79864) and the decision to host it in Desk 2.0, not 1.0 tools. (mhammontree)

package/knowledge/2.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-10-06
+updated: 2026-10-07
 owners: [jcardinal, mhammontree, dfranks, bala, ajean]
 files: []
 related:
@@ -666,6 +666,9 @@ can follow. Do not type the child alone.
 
 * Use comments to explain the "why" behind the code, not the "how".
 * Inline comments should be used sparingly.
+* Keep a file docblock short: what the file is, plus the one or two traps that bite the next
+  editor. Design history, scope decisions, reuse notes and rejected approaches go to the
+  knowledge base at `/capture`, not into the file — they bury the code and go stale.
 
 #### **DocBlocks**
 
@@ -1023,3 +1026,7 @@ Existing static-key paths (ZoomInfo, VipSupport, `_Cloud` CLI) are grandfathered
 is deferred, not sanctioned for new work. Never record access-key values anywhere but the ini.
 
 See: 2.0/apps/worker2/features/cross-account-aws-access.md
+
+## Change history
+
+- 2026-10-07 — Added the short-file-docblock rule (design history belongs in the knowledge base). (mhammontree)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 32 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 33 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 42 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/compass-canada/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-10-05
+updated: 2026-10-07
 owners: [jcardinal, bala, tcox, apeterson, ajean, mhammontree, rgirish]
 files: []
 related:
@@ -43,6 +43,7 @@ related:
   - ../compass-usa/features/saml-sso.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md
+  - ../../1.0/apps/library/features/email-ses-sender-identity.md
 ---
 
 ## Summary
@@ -81,6 +82,19 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   CXML). Prod `Vendors` 4 COMPASS CANADA and 5 AGILANT SOLUTIONS INC have no integration, and the 1.0
   constants for them (`'2'`, `'3'`) do not match prod. PO transmit cron quirks and the OneUptime monitor
   (cron 87): [PO-to-vendor monitor](features/oneuptime-po-transmissions-to-vendors-monitor.md).
+- **TechHub sender address is `Techhub.Canada@compass-canada.com` (prod, 2026-10-07).** Was
+  `TechHubCanada@togatech.com`. Changed on 28 `EmailTemplates.sendFromEmailAddress` rows (EN+FR
+  order / approval / transit / delivered / reminder / auto-cancel) and `IntegrationsEmail` id 1
+  (integration 2, "Grand & Toy - Email") by
+  `dbchanges2/Client_CompassCanada/2026-10-07a - TechHubCanadaFromEmail.sql`. Kept on togatech.com
+  on purpose: Request Submitted (`compasssupport@`), Get Support (`donotreply@`), Forgot Password x2
+  (`noreply@`). It is a single verified SES identity, so any new sender needs SES verification
+  first: [SES sender identity](../../1.0/apps/library/features/email-ses-sender-identity.md).
+  The hardcoded TechHub CC in 4 worker crons had a typo (`TechHub@compass-canada.com`, missing
+  `.Canada`); now `Techhub.Canada@compass-canada.com` in `workflow/2_transmit_mits_purchase_orders_to_vendors.php`
+  (G&T PO email CC), `workflow_beta/2_…`, `compass_email_reminders.php` and
+  `compass_cancel_pending_approval_orders.php` (all under `worker/crons/toga2/compasscanada/`).
+  **Not yet deployed.**
 - **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
   back ASNs. ASN ingestion (email CSV + the auto-created ItemFulfillment chain + bilingual
   in-transit email) is documented in [Grand & Toy ASN Import](features/grand-and-toy-asn-import.md).

package/package.json

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