toga-ai 1.0.59 → 1.0.61

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-06-09
-owners: [jcardinal]
+updated: 2026-06-11
+owners: ["jcardinal", "rgirish"]
 files:
   - _underscore/_underscore.php
   - _underscore/Loader.php
@@ -273,3 +273,10 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 | `_Database` / `_Query` | Connection pool + read/write routing / MySQLi wrapper with caching |
 | `_Route` / `_Component` | URI router / HTML component renderer |
 | `_Config` / `_Environment` / `_Loader` / `_Http` / `_Error` | config, env/debug, autoload, JWT/HTTP, errors |
+
+## Gotchas / known issues
+
+- **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026, commit `fa7835ed`).** Any code that calls `register()` and then writes to that DB must call `_Database::transactionCommit()` before the request ends — otherwise MySQL silently rolls back all writes when the connection closes. Lazy transactions only materialise on the first write, so read-only callers are unaffected. See `_underscore/Database.php:48`. First discovered when Rate SAML user provisioning silently discarded all new user INSERTs (Jun 2026).
+
+## Change history
+- 2026-06-11 — Documented lazy transaction gotcha in `_Database::register()` (rgirish)

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

@@ -0,0 +1,6 @@
+# saml (SAML SSO Gateway) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [saml Architecture](architecture.md) | The `saml` repo is the SAML 2.0 / SSO gateway for all TOGa applications. | saml/index.php, saml/_.php, saml/Controller/Index.php, saml/Config/production.ini, saml/.platform/hooks/prebuild/git.sh, saml/.ebextensions/git.php |
+| [Rate SAML User Provisioning](features/rate-user-provisioning.md) | When a Rate user authenticates via SSO, `_Model_Rate_ClientAuthentication::getAuthenticatedSsoUser()` is called by the saml gateway. | _underscore/Model/Rate/ClientAuthentication.php, _underscore/Model/Rate/User.php, _underscore/Model/Rate/Customer.php, _underscore/Model/Rate/Contact.php |

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

@@ -0,0 +1,88 @@
+---
+title: saml Architecture
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: shared
+type: architecture
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - saml/index.php
+  - saml/_.php
+  - saml/Controller/Index.php
+  - saml/Config/production.ini
+  - saml/.platform/hooks/prebuild/git.sh
+  - saml/.ebextensions/git.php
+related:
+  - 2.0/apps/_underscore/architecture.md
+---
+
+## Summary
+
+The `saml` repo is the SAML 2.0 / SSO gateway for all TOGa applications. It acts as the
+SAML **Service Provider (SP)** — customer Identity Providers (IdPs: Azure AD, Compass,
+Rate, Prudential, etc.) POST authentication assertions here. The gateway validates the
+assertion, maps the identity to a TOGa user, and redirects the browser back to the
+requesting TOGa app with an encrypted auth handoff payload.
+
+Built on the `_underscore` PHP framework. Deployed on AWS Elastic Beanstalk (us-east-1).
+
+## Entry point & routing
+
+All requests rewrite to `index.php` via `.htaccess`. `_.php` sets
+`DEFAULT_CONTROLLER_METHOD = ['_Controller_Index', 'saml']`. Sub-routes:
+
+| Path | Purpose |
+|---|---|
+| `/meta` | SP metadata XML — IdPs consume this to configure the integration |
+| `/acs` | Assertion Consumer Service — receives IdP SAMLResponse + RelayState POST |
+| `/sls` | Advertised in metadata but not implemented |
+| *(default)* | Echoes `TOGaHub SAML SSO receiver` |
+
+Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
+
+## /acs flow
+
+1. **RelayState decryption** — `_String::decryptWithKey()` with `API_SECRET_ACCESS_TOKEN`; retries with `_PREVIOUS` for rotation window support.
+2. **Version + time check** — RelayState JSON: `v` (currently `1`), `time`, `domain` UUID, optional `urlParameters`. Validated against `MAX_TIME_TO_LIVE` (300s).
+3. **Parse SAMLResponse** — base64-decoded, deserialized via LightSaml.
+4. **Status check** — proceeds only on `STATUS_SUCCESS`.
+5. **Assertion decryption** — TOGa SP credential from `_underscore/Assets/ssl/`.
+6. **Resolve client + environment** — `_Model_Core_Domain` by RelayState `domain` UUID → `_Model_Core_Client` + `_Model_Core_Environment`. Dev on real AWS instance downgrades to beta.
+7. **Dynamic DB registration** — SQL joins `Clients`, `Databases`, `DatabaseHosts`, `Environments` for the environment slug. Calls `_Database::register()` + `connect()` for `DB_CLIENT`, `DB_CLIENT_LOGS`, `DB_CLIENT_ARCHIVE`.
+8. **Identity mapping** — `_Model_<ClientIdentifier>_ClientAuthentication::getAuthenticatedSsoUser($assertion)`. Wrapped in try/catch; exceptions sent to Sentry.
+9. **Commit DB writes** — `_Database::transactionCommit()` called after provisioning succeeds (see Gotchas).
+10. **Handoff** — encrypts client UUID + user UUID under `API_SECRET_ACCESS_TOKEN`, base64-encodes `{auth: 'encrypted-user-uuid', payload: {client, user}}`, redirects to `<domain>?saml=<payload>`.
+
+### Failure responses
+`Invalid SAMLResponse (Code = 1–4)`, `SAML Authentication Failed`, `User Authentication Failed`.
+
+## Per-client SSO extension pattern
+
+Identity mapping lives in `_underscore/Model/<ClientIdentifier>/ClientAuthentication.php`.
+Each class extends `_Model_Core_ClientAuthentication` + uses `_Trait_ClientAuthentication`.
+To onboard a new SSO client, add the class in `_underscore` — not in this repo.
+
+## Deployment
+
+- **EB environment:** `saml-production` (us-east-1). DNS: `saml.togahub.com → saml-production.us-east-1.elasticbeanstalk.com`
+- **`_underscore` pulled at deploy time** via `.ebextensions/git.php` + prebuild hook — clones branch `_production`. Deploy `saml` after `_underscore` merges to pick up framework changes.
+- **CodePipeline:** Source (GitHub `_production`) → ManualApproval → Deploy (EB).
+- **Composer deps** installed at postdeploy via `015_install_composer.sh`.
+
+## Dependencies
+
+- **`litesaml/lightsaml` ^3.0** — SAML 2.0 parsing, assertion decryption, X509.
+- **`sentry/sentry` ^4.9** — exception reporting, initialized at top of `saml()`.
+
+## Gotchas / known issues
+
+- **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026).** Any code that registers DBs then writes must call `_Database::transactionCommit()` before exiting — otherwise MySQL silently rolls back all writes on connection close. The `/acs` handler calls `transactionCommit()` after `getAuthenticatedSsoUser()` succeeds and before the redirect. See `_underscore/Database.php:48`.
+- **SAML signature verification is commented out.** The IdP X509 cert verification block is disabled. The only gate is the encrypted RelayState. Re-enabling per-IdP signature verification is a priority security improvement.
+- **SLS not implemented.** `/sls` falls through to the default banner.
+- **`set_exception_handler(null)` at top of `saml()`.** Unhandled exceptions output raw PHP errors. All exceptions from `getAuthenticatedSsoUser()` are caught and sent to Sentry.
+
+## Change history
+- 2026-06-11 — Added `transactionCommit()` before redirect; wrapped `getAuthenticatedSsoUser()` in try/catch with Sentry; echo+exit on auth failure (rgirish)

package/knowledge/2.0/apps/saml/features/rate-user-provisioning.md

@@ -0,0 +1,57 @@
+---
+title: Rate SAML User Provisioning
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Rate/ClientAuthentication.php
+  - _underscore/Model/Rate/User.php
+  - _underscore/Model/Rate/Customer.php
+  - _underscore/Model/Rate/Contact.php
+related:
+  - 2.0/apps/saml/architecture.md
+  - clients/rate/features/saml-sso.md
+---
+
+## Summary
+
+When a Rate user authenticates via SSO, `_Model_Rate_ClientAuthentication::getAuthenticatedSsoUser()`
+is called by the saml gateway. It either finds the existing user by `borrowerID` or
+provisions a full new user record chain in `Client_Rate`.
+
+## How it works
+
+1. **Extract attributes** from the SAML assertion — all keys use null-safe access (`?? null`).
+2. **Validate required attributes** — `borrowerID` and `email` must be non-empty. Throws `\Exception('SAML assertion missing required attributes: ...')` if either is missing; caught by saml controller and sent to Sentry.
+3. **Load existing user** — `_Model_Rate_User` searched by `c_borrowerId`. If found, return immediately.
+4. **Provision new user** (if not found):
+   - Create `_Model_Rate_Customer` (`c_borrowerId`, `name`)
+   - Create `_Model_Rate_Contact` (`firstName`, `lastName`, `customerId`)
+   - Create `_Model_Client_ContactEmailAddress` (`contactId`, `name`, `emailAddress`)
+   - Update Contact with `primaryContactEmailAddressId`
+   - Create `_Model_Rate_User` with all fields; reload by PK (`new _Model_Rate_User($userId)`) to populate `uuid`
+   - Create `_Model_Client_Users_Role` with `roleId = 1` (Loan Officer default)
+5. Return User object with `id` and `uuid` populated.
+
+## Data model
+
+- `Client_Rate.Users` — `c_borrowerId VARCHAR(64)` (UUID from IdP)
+- `Client_Rate.Customers` — `c_borrowerId VARCHAR(128)`, `c_netsuiteInternalCustomerId INT`
+- `Client_Rate.Contacts` — `c_loid VARCHAR(64)`, `c_togaCustomerId INT`
+- `Client_Rate.ContactEmailAddresses` — standard base model
+- `Client_Rate.Users_Roles` — `roleId = 1` hardcoded as Loan Officer default
+
+## Gotchas / known issues
+
+- **`borrowerID` from Rate's IdP is a UUID string**, not a numeric ID.
+- **`phoneNumber` may not be sent by the IdP** — null-safe, nullable in DB. Do not add to required validation.
+- **`_Database::register()` starts a lazy transaction (since Apr 2 2026).** The saml controller must call `_Database::transactionCommit()` after this method returns — otherwise all INSERTs are silently rolled back on connection close. This was the root cause of new users never persisting. See `_underscore/Database.php:48`.
+- **`load()` scopes only by `c_borrowerId`** — no `clientId` filter. Two users sharing a `borrowerID` causes `load()` to return false (count != 1) and triggers duplicate provisioning.
+
+## Change history
+- 2026-06-11 — Added null-safe attribute extraction, required validation for `borrowerID` + `email`, Sentry-caught exceptions (rgirish)

package/knowledge/INDEX.md

@@ -14,6 +14,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
+- **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
+- **toga2-view** (TOGa View Frontend) — 0 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 
 ## Clients
 
@@ -22,4 +24,6 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
+- **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
+- **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 

package/knowledge/clients/rate/INDEX.md

@@ -0,0 +1,6 @@
+# Client: Rate `rate`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
+| [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/saml-sso.md

@@ -0,0 +1,58 @@
+---
+title: Rate SAML SSO
+framework: "2.0"
+project: SAML SSO Gateway
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Rate/ClientAuthentication.php
+  - saml/Controller/Index.php
+  - toga2-view/src/hooks/useAuthenticationFlow.ts
+related:
+  - 2.0/apps/saml/architecture.md
+  - 2.0/apps/saml/features/rate-user-provisioning.md
+---
+
+## Summary
+
+Rate uses Azure AD as its IdP (`login.rate.com`). Users sign in at Rate's portal, which
+redirects to the TOGa SAML gateway at `saml.togahub.com/acs`. On success the gateway
+redirects the browser back to the Rate frontend with a `?saml=` encrypted payload.
+
+## SAML assertion attributes
+
+Rate's Azure AD sends these attributes in the assertion:
+
+| Attribute key | Description | Required |
+|---|---|---|
+| `borrowerID` | Borrower UUID — used as `c_borrowerId` to identify/create users | Yes |
+| `email` | User email address | Yes |
+| `firstName` | First name | No (null-safe) |
+| `lastName` | Last name | No (null-safe) |
+| `phoneNumber` | Phone number | No (null-safe) |
+
+`borrowerID` is a UUID string (not numeric).
+
+## Frontend SAML landing (`useAuthenticationFlow.ts`)
+
+1. If `?saml=` is in the URL: strip it immediately via `window.history.replaceState` (prevents stale payload replay on refresh), then call `/v2/auth/encrypted-user-uuid`.
+2. On success: decode `urlParameters` into localStorage, upsert loan officer contact, call `login()`, navigate to `/landing`.
+3. On error: navigate to `/login`.
+
+## Loan officer upsert
+
+After successful auth, if `urlParameters` contains `loid` + `loname`:
+1. Fetch the user's Contact to get their Customer UUID.
+2. Search `Contacts` by `c_loid` — PUT to update name if found; POST to create with `contactType = 'Loan Officer'` (UUID `d1f67efc-a984-aebc-42f5-5313f44f52ed`) linked to the customer.
+
+## Gotchas / known issues
+
+- **`?saml=` replay** — the frontend strips the param immediately after processing. Before this fix, refreshing replayed the stale payload → EZ-1 "Invalid User".
+- **New users silently not created (Apr 2 – Jun 11 2026)** — `_Database::register()` auto-starts a lazy transaction; saml gateway never called `transactionCommit()`, so all new user INSERTs were rolled back silently. Fixed by adding `_Database::transactionCommit()` before the redirect in `saml/Controller/Index.php`.
+- **Both saml and _underscore must be deployed together** — saml pulls `_underscore` at EB build time. A fix in `_underscore` requires a saml redeploy to take effect.
+
+## Change history
+- 2026-06-11 — Fixed new user creation (missing transactionCommit); fixed ?saml= URL replay; added null-safe attribute extraction and required validation (rgirish)

package/knowledge/clients/rate/profile.md

@@ -0,0 +1,24 @@
+---
+title: "Rate"
+framework: "2.0"
+project: SAML SSO Gateway
+client: rate
+type: profile
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files: []
+related:
+  - clients/rate/features/saml-sso.md
+---
+
+## Summary
+
+Rate is a mortgage/lending client. Their TOGa integration covers home warranty and home
+tech support products. Users authenticate via SAML SSO from Rate's Azure AD IdP
+(`login.rate.com`). New users are auto-provisioned on first login.
+
+- **Client DB:** `Client_Rate`
+- **Client identifier:** `Rate`
+- **Production domains:** `https://homewarranty.rate.com`, `https://hometechsupport.rate.com`
+- **Frontend app:** TOGa View (`toga2-view`)

package/knowledge/clients/tow-foundation/INDEX.md

@@ -0,0 +1,6 @@
+# Client: Tow Foundation `tow-foundation`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Credit Card Receipt Processing](features/receipt-processing.md) | 2.0 | Automated processing of credit card receipts uploaded to SharePoint. | worker2/Worker/Client/TowFoundation.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php |
+| [Tow Foundation](profile.md) | 2.0 | Tow Foundation is a nonprofit client. |  |

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -0,0 +1,130 @@
+---
+title: "Credit Card Receipt Processing"
+framework: "2.0"
+project: Worker
+client: tow-foundation
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files:
+  - worker2/Worker/Client/TowFoundation.php
+  - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
+related:
+  - clients/tow-foundation/profile.md
+---
+
+## Summary
+
+Automated processing of credit card receipts uploaded to SharePoint. Downloads each
+receipt, extracts structured data via Talos AI, cross-verifies against billing-cycle
+statements, renames the file, archives it per cardholder, generates a QuickBooks-ready
+Excel file per person, uploads it to SharePoint, and sends a summary email.
+
+Invocation: `{"action": "Client/TowFoundation/ProcessReceipts/Run", "parameters": {}}`
+
+Optional filter parameters: `limit` (int), `year` (string e.g. `"2026"`), `person` (string e.g. `"Brent Peterkin"`).
+
+## Key files / entry points
+
+- `TowFoundation.php` — base class; holds all email constants and `initialize()` (empty — no client DB)
+- `ProcessReceipts.php` — all logic; abstract class extending `_Worker_Client_TowFoundation`
+
+## How it works
+
+### SharePoint folder structure
+```
+Credit Card Receipts/
+  {Person}/
+    {Year}/
+      {BillingCycleFolder}/   ← receipt files live here (e.g. "Amex ending in 06-03-2026")
+      {Person} reports/        ← .xlsx billing statements for cross-verification
+      Archive/
+        {Person}/              ← successfully processed receipts land here (renamed)
+        exception/
+          {Person}/            ← failed receipts land here (original name preserved)
+      3. QB Excel/             ← generated Excel files uploaded here after each run
+```
+
+### Processing flow
+
+1. **Auth** — OAuth2 client-credentials token from Microsoft Graph
+2. **Walk** — `walkReceiptsFolder()` enumerates all receipt files and statement Excels
+3. **Filter** — optional `$year` / `$person` / `$limit` applied to the receipt list
+4. **Pre-load statements** — all billing-cycle `.xlsx` files under `reports/` are downloaded
+   and parsed upfront via PhpSpreadsheet (auto-detect header row by scanning for
+   description/amount keywords)
+5. **Pass 1 — Extract** — for each receipt:
+   - Enforce size limit (4 MB images, 10 MB documents)
+   - Download file bytes from SharePoint
+   - POST to Talos AI `/api/ai/generate` → structured `{vendor_name, invoice_date, total, payment_memo, category, ...}`
+   - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with statement description
+   - Build base filename (no suffix yet) and store in `$pendingRenames`
+   - On extract failure → move to `Archive/exception/{Person}/` immediately
+6. **Collision detection** — count base name occurrences across all pending renames
+7. **Pass 2 — Move** — for each pending rename:
+   - If base name appears more than once, assign `_a`, `_b`, `_c`... suffix to **all** colliding files (including the first)
+   - PATCH SharePoint to rename + move to `Archive/{Person}/`
+8. **Excel generation** — one `.xlsx` per person (PhpSpreadsheet); columns: Row #, Account Name, QB Vendor, Payment Amount, Date, Payment Method, Payment Memo, QB Description, Class, Category, Payment Account, Ref No.
+9. **SharePoint upload** — each Excel uploaded to `{Person}/{Year}/3. QB Excel/` via Graph API PUT
+10. **Summary email** — sent with Excel files attached; To: Jheanelle, CC: Magdalena, BCC: devteam@togatech.com
+
+### Renamed file format
+```
+YYYY.MM.DD Name of Cardholder_VendorName_Amount[_a].ext
+```
+- Vendor name: special chars stripped, spaces → underscores
+- Amount: two decimal places (e.g. `42.50`)
+- Suffix `_a`, `_b`... added when date + person + vendor + amount are all identical (e.g. multiple train tickets same day)
+
+### Ref No. (QuickBooks)
+Amex billing cycle runs 3rd-to-3rd. `computeRefNo()` returns the cycle-end date as `MMDDYYYY`.
+- Charge on or before the 3rd → cycle ends on the 3rd of the same month
+- Charge after the 3rd → cycle ends on the 3rd of the next month
+
+### Per-person constants
+`CLASS_MAP` and `PAYMENT_ACCOUNT_MAP` in `ProcessReceipts.php` map each cardholder's name
+to their QuickBooks Class and Payment Account strings. Ryan Farrell uses Bank of America
+Mastercard; all others use AMEX Open Credit Card.
+
+## Email routing
+
+Defined as constants in `TowFoundation.php`:
+
+| Constant | Value | Role |
+|---|---|---|
+| `NOTIFY_EMAIL_CLIENT` | `Jheanelle@towfoundation.org` | To |
+| `NOTIFY_EMAIL_CC` | `['Magdalena@towfoundation.org']` | CC |
+| `NOTIFY_EMAIL_BCC` | `['devteam@togatech.com']` | BCC |
+| `NOTIFY_EMAIL_DEV` | `devteam@goagilant.com` | To (always) |
+| `NOTIFY_EMAIL_EXTRA` | jcardinal, ajean, bmorton @goagilant.com | To |
+
+Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
+
+## Gotchas / known issues
+
+- **`$year` variable shadowing** — `Run()` uses `$year` as both a filter parameter and a
+  loop variable (line ~159: `$year = $receipt['year']`). After the loop `$year` holds the
+  last receipt's year, not the original filter value. Harmless now but fragile if the loop
+  is restructured.
+- **Two-pass rename is required** — collision detection must see ALL base names before any
+  file is moved. A single-pass approach would retroactively need to rename the first file
+  after discovering a duplicate, which is not possible once it's already on SharePoint.
+- **`_Loader::setThrowExceptionInAutoloaderIfClassNotFound(false)`** — must wrap all
+  PhpSpreadsheet calls. ZipStream is a Composer dependency that triggers the autoloader;
+  without this flag, it throws on missing class and aborts Excel generation.
+- **Graph API item-ID move** — `renameAndMoveToArchive()` resolves the target folder to an
+  item ID before PATCHing. Using path-based `parentReference` causes HTTP 400 on folder
+  names with special characters (spaces, dots). Always resolve to ID first.
+- **`ensureFolderPath()` for "3. QB Excel"** — the folder name contains a dot and space;
+  `ensureFolderPath` handles this correctly via `rawurlencode` on each path segment.
+- **Statement matching tolerance** — `matchStatementRow()` uses `abs($row['amount'] - $amount) < 0.01`
+  for amount matching, then date tie-break for multiple same-amount rows. Returns first
+  candidate if date tie-break also ambiguous.
+- **No client DB** — there is no audit trail in MySQL. All state lives in SharePoint folder
+  structure and email. If a run is interrupted mid-way, some receipts may be archived
+  without a corresponding Excel row.
+
+## Change history
+
+- 2026-06-11 — Added CC (Magdalena), BCC (devteam@togatech.com), per-cardholder Archive subfolders, Excel upload to "3. QB Excel" SharePoint folder, two-pass rename with alphabetical duplicate suffix, rename format changed to `YYYY.MM.DD Full Name_Vendor_Amount` (rgirish)

package/knowledge/clients/tow-foundation/profile.md

@@ -0,0 +1,35 @@
+---
+title: "Tow Foundation"
+framework: "2.0"
+project: Worker
+client: tow-foundation
+type: profile
+status: active
+updated: 2026-06-11
+owners: ["rgirish"]
+files: []
+related:
+  - clients/tow-foundation/features/receipt-processing.md
+---
+
+## Summary
+
+Tow Foundation is a nonprofit client. Their integration automates credit card receipt
+processing: receipts uploaded to SharePoint by cardholders are downloaded, extracted via
+Talos AI, cross-verified against Amex/Mastercard billing statements, renamed, archived,
+and exported as QuickBooks-ready Excel files.
+
+No client database is used (no persistence beyond SharePoint and email).
+
+## Contacts
+
+- **Jheanelle Gordon** — primary contact; receives the processing completion email
+- **Magdalena Minta** — CC on completion email
+- devteam@togatech.com — BCC on all emails
+
+## Key integration points
+
+- Microsoft SharePoint (Microsoft Graph API) — receipt file storage
+- Talos AI (`/api/ai/generate`) — structured receipt data extraction
+- PhpSpreadsheet — Excel generation and statement parsing
+- `_Email` — completion summary + fatal error notifications

package/knowledge/registry.json

@@ -5,5 +5,7 @@
   { "repo": "dbchanges2",  "project": "Database Changes", "framework": "2.0", "role": "core", "dependsOn": [] },
   { "repo": "library",     "project": "Library",     "framework": "1.0", "role": "core", "dependsOn": [] },
   { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
+  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
+  { "repo": "saml",        "project": "SAML SSO Gateway", "framework": "2.0", "role": "app",  "dependsOn": [] },
+  { "repo": "toga2-view",  "project": "TOGa View Frontend", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
 ]

package/package.json

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