toga-ai 1.0.160 → 1.0.161

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

@@ -2,5 +2,5 @@
 
 | 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, worker2/Worker/Client/TowFoundation/TowFoundationVendors.php |
+| [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, worker2/Worker/Client/TowFoundation/TowFoundationVendors.php, worker2/Worker/Client/TowFoundation/TowFoundationCategories.php |
 | [Tow Foundation](profile.md) | 2.0 | Tow Foundation is a nonprofit client. |  |

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

@@ -5,12 +5,13 @@ project: Worker
 client: tow-foundation
 type: client-feature
 status: active
-updated: 2026-06-18
+updated: 2026-06-23
 owners: ["rgirish"]
 files:
   - worker2/Worker/Client/TowFoundation.php
   - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
   - worker2/Worker/Client/TowFoundation/TowFoundationVendors.php
+  - worker2/Worker/Client/TowFoundation/TowFoundationCategories.php
 related:
   - clients/tow-foundation/profile.md
 ---
@@ -86,7 +87,7 @@ Amex billing cycle runs 3rd-to-3rd. `computeRefNo()` returns the cycle-end date
 `TowFoundationVendors.php` holds 2,994 vendor names exported verbatim from Tow Foundation's
 QuickBooks vendor list (June 2026). `matchQbVendor()` runs three passes against this list:
 1. Exact match (case-insensitive)
-2. Substring match — QB name contains extracted name or vice versa (min 4 chars); picks shortest match on multiple hits
+2. Substring match — QB name contains extracted name or vice versa; minimum 3 chars. For needles shorter than 4 chars, a **whole-word boundary check** is used (regex `(?<![a-z])<needle>(?![a-z])`) to prevent short acronyms like `"UPS"` from matching inside `"USPS"`. Picks shortest QB name on multiple hits.
 3. `similar_text()` similarity ≥ 80% — picks highest scorer
 
 Returns the exact QB vendor string or `''` if no confident match. The AI only extracts
@@ -95,11 +96,35 @@ Returns the exact QB vendor string or `''` if no confident match. The AI only ex
 To update the vendor list: re-export from QuickBooks → run the extraction script →
 replace `TowFoundationVendors.php`. The matching logic is in `matchQbVendor()` and needs no changes.
 
-### AI category values
-The AI is prompted to return **specific expense types** — e.g. `"Dining"`, `"Travel"`,
-`"Accommodation"`, `"Transportation"`, `"Office Supplies"`, `"Entertainment"`,
-`"Professional Services"`, `"Subscriptions"`. It must not use broad accounting labels
-like `"Administrative Expenses"`.
+### AI category values and QB mapping
+The AI is prompted to return **specific expense types**. These are then mapped to the exact
+QB account string via `mapCategory()`, which loads `TowFoundationCategories.php` and does
+a case-insensitive lookup. Unmapped values are passed through as-is and logged as warnings.
+
+| AI category value | QB account string |
+|---|---|
+| `Dining` | `6640 Dining & Entertainment` |
+| `Entertainment` | `6640 Dining & Entertainment` |
+| `Travel` | `6609 Travel, conferences, meetings` |
+| `Transportation` | `6610 Travel expense` |
+| `Accommodation` / `Lodging` | `6620 Lodging` |
+| `Office Supplies` | `6751 Office supplies` |
+| `Professional Services` | `6400 Professional Fees & Consultants` |
+| `Subscriptions` | `67271 Subscriptions` |
+| `Technology` | `6710 Technology Systems Expense` |
+| `Software` | `6714 Software License Expense` |
+| `Printing` | `6722 Printing expense` |
+| `Postage` | `6721 Postage` |
+| `Membership` | `6730 Membership Dues` |
+| `Insurance` | `6740 Insurance` |
+| `Telephone` | `6755 Telephone & internet expense` |
+| `Photography` | `67241 Photography` |
+| `Board` | `6650 Board Expenses and Board Development` |
+| `Professional Development` | `6735 Staff Professional Development` |
+
+To update the mapping: edit `TowFoundationCategories.php` — keys are case-insensitive,
+values must be the exact QB account string. The AI prompt in `extractReceiptData()` lists
+the valid category names; keep them in sync with the map keys.
 
 ### Per-person constants
 `CLASS_MAP` and `PAYMENT_ACCOUNT_MAP` in `ProcessReceipts.php` map each cardholder's name
@@ -158,9 +183,13 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 - **`billingCycle` filter is suffix-match, not exact** — always pass just the date portion (`"06-03-2026"`), not the full folder name. Passing the full name (`"Amex ending in 06-03-2026"`) also works but would miss Mastercard folders.
 - **Ole Mole not in QB vendor list** — as of June 2026 this vendor is not in Tow Foundation's QuickBooks, so `qb_vendor` will be blank for Ole Mole charges until they add it to QB and the vendor list is refreshed.
 - **Duplicate detection is within-run only** — if the same receipt was processed in a prior run and archived, it won't be caught. The dedup only covers receipts present in the current run's `$pendingRenames`.
+- **Unmapped AI categories pass through** — if the AI returns a category string not in `TowFoundationCategories.php`, `mapCategory()` logs a warning and writes the raw AI string to the Excel. Check error logs after a run if the Category column looks odd; add the new value to the map file to fix it.
+- **Short vendor acronyms (< 4 chars) require whole-word match** — the substring pass uses a word-boundary regex for needles under 4 chars to avoid false positives (e.g. `"UPS"` inside `"USPS"`). If a short vendor name is not matching, check that the QB vendor list entry starts or ends with the acronym as a whole word.
+- **Archive restore script** — a one-shot CLI script `/tmp/tow_restore_archives.php` was written 2026-06-23 to move archived files back to their billing-cycle folders for reprocessing. It is not committed; re-create from the session transcript if needed. It uses the production credentials from `Config/production.ini`.
 
 ## Change history
 
+- 2026-06-23 — `TowFoundationCategories.php` added: AI category values now mapped to exact QB account strings via `mapCategory()`; `"Transportation"` → `"6610 Travel expense"` etc. (19 mappings). QB vendor substring match minimum lowered from 4 to 3 chars with whole-word boundary guard for short needles — fixes `"CVS"` → `"CVS Pharmacy"`, `"MTA"` → `"MTA Metro card"`, prevents `"UPS"` → `"USPS"` false positive. (rgirish)
 - 2026-06-18 — QB vendor matching via local fuzzy match against `TowFoundationVendors.php` (2,994 vendors); AI category prompt updated to return specific types (Dining, Travel, etc.); duplicate receipt detection added (person+date+vendor+amount dedup); `billingCycle` filter parameter added (suffix-match — card-type agnostic); person folder ` CC receipts` suffix stripped so CLASS_MAP/PAYMENT_ACCOUNT_MAP resolve correctly (rgirish)
 - 2026-06-12 — QB Excel upload moved to root-level `3. QB Excel/`; Archive/exception folders flattened (no person subfolder); unsupported mime types (`application/octet-stream`) now throw ReceiptProcessingException instead of being silently skipped (rgirish)
 - 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/package.json

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