toga-ai 1.0.160 → 1.0.162

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
+| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | `App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal used across all TOGa service request views. | library/app/model/toga/diagnostic.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem |

package/knowledge/1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md

@@ -0,0 +1,49 @@
+---
+title: Diagnostic Dialog — View Recommended Services Routing
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - library/app/model/toga/diagnostic.php
+related:
+  - ../../../clients/office-depot/features/togarefresh2026-linkbuilder-routing.md
+---
+
+## Summary
+`App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal
+used across all TOGa service request views. It includes a "View Recommended Services"
+button whose URL depends on whether the store is a TOGaRefresh 2026 store and whether
+the diagnostic passed or failed.
+
+## How it works
+1. Checks `$_SESSION['isTogaRefresh2023']` or `$_SESSION['isTogaRefresh2026']` to
+   determine if this is a refresh store.
+2. For refresh stores, casts `$serviceRequestId` to `(int)` then queries `Diagnostics`
+   for the latest `pass` value for the service request.
+3. Routes:
+   - **Diagnostic pass** (`pass >= 1`) → `?content=togarefresh2026_servicerequests_techsupport&serviceRequestId=...`
+   - **Diagnostic fail / no diagnostic** (`pass < 1`) → `?content=togarefresh2026_servicerequests_serviceselection&jobJacketId=1&showServices=195,101899&serviceRequestId=...`
+4. For non-refresh stores, falls back to `App_Model_ServiceRequest::linkBuilder()`.
+
+## Data model
+- Table: `Diagnostics` (db_toga)
+- Field read: `pass` (TINYINT boolean — 1 = passed, 0 = failed)
+- Query: latest record by `id DESC LIMIT 1` for the given `serviceRequestId`
+
+## Gotchas / known issues
+- `$serviceRequestId` is cast to `(int)` before SQL interpolation — do not remove this cast (SQL injection prevention).
+- If no diagnostic record exists, `$diagnosticPass` defaults to `0` (fail path) — shows service selection with `showServices=195,101899`.
+- The same pass/fail routing logic exists in `toga/app/togarefresh2026/servicerequests/view.php` (lines 2358–2381) — keep both in sync.
+- `isTogaRefresh2023` is kept alongside `isTogaRefresh2026` for backward compatibility — do not remove it.
+- `$_SESSION['isTogaRefresh2026']` is set in `toga/_/app/frameworkindex.php` and `toga/app/home/action.php` at login time.
+
+## Related docs
+- `clients/office-depot/features/togarefresh2026-linkbuilder-routing.md`
+
+## Change history
+- 2026-06-23 — Initial doc. Diagnostic modal now routes pass→techsupport, fail→serviceselection with showServices=195,101899. (snaredla)

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

@@ -0,0 +1,4 @@
+# toga (TOGa) — 1.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|

package/knowledge/INDEX.md

@@ -4,13 +4,14 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 6 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 7 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 10 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **toga** (TOGa) — 1 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/clients/office-depot/INDEX.md

@@ -3,4 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [ODP Tech Support Agent (Office Depot variant)](features/odp-tech-support.md) | 2.0 | ODP-specific customization of the shared TOGa Voice agent. | voice-to-voice/clients/odp/agent.py, voice-to-voice/clients/odp/agents/tech_support.py, voice-to-voice/clients/odp/prompts.py, voice-to-voice/clients/odp/config.yaml, voice-to-voice/clients/odp/.env.example |
+| [TOGaRefresh 2026 — linkBuilderRefresh URL Routing (ODP)](features/togarefresh2026-linkbuilder-routing.md) | 1.0 | In the TOGaRefresh 2026 UI, any button that navigates to the service builder must use `App_Model_ServiceRequest::linkBuilderRefresh()` (→ `togarefresh2026_servi | toga/app/togarefresh2026/servicerequests/review.php, toga/app/togarefresh2026/customers/view.php, library/app/model/toga/diagnostic.php |
 | [Office Depot](profile.md) | 2.0 | Office Depot is the first deployed tenant of the **TOGa Voice** (`voice-to-voice`) platform. |  |

package/knowledge/clients/office-depot/features/togarefresh2026-linkbuilder-routing.md

@@ -0,0 +1,49 @@
+---
+title: TOGaRefresh 2026 — linkBuilderRefresh URL Routing (ODP)
+framework: "1.0"
+repo: toga
+project: TOGa
+client: office-depot
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: [snaredla]
+files:
+  - toga/app/togarefresh2026/servicerequests/review.php
+  - toga/app/togarefresh2026/customers/view.php
+  - library/app/model/toga/diagnostic.php
+related:
+  - ../profile.md
+  - ../../../1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md
+---
+
+## Summary
+In the TOGaRefresh 2026 UI, any button that navigates to the service builder must use
+`App_Model_ServiceRequest::linkBuilderRefresh()` (→ `togarefresh2026_servicerequests_serviceselection`)
+instead of the legacy `linkBuilder()` (→ `servicerequests_builder`).
+
+## Key files / entry points
+- `App_Model_ServiceRequest::BUILDER` = `'servicerequests_builder'` (legacy)
+- `App_Model_ServiceRequest::BUILDERREFRESH` = `'togarefresh2026_servicerequests_serviceselection&jobJacketId=1'`
+- Both constants defined in `library/app/model/servicerequest.php` lines 11–12.
+
+## How it works
+Files updated to use `linkBuilderRefresh`:
+
+| File | Location | Context |
+|------|----------|---------|
+| `togarefresh2026/servicerequests/review.php` | line 217 | Quote submission POST URL for non-EXISTING job jackets |
+| `togarefresh2026/customers/view.php` | line 64 | "Create Work Order For This Customer" button |
+| `library/app/model/toga/diagnostic.php` | `initializeDiagnosticDialog()` | Device modal button — routes by diagnostic pass/fail (see library doc) |
+
+## Gotchas / known issues
+- The old `servicerequests/view.php` (legacy non-refresh view) intentionally keeps `linkBuilder()` — 2026 stores do not route through it.
+- Do not change `App_Model_ServiceRequest::BUILDER` — legacy stores still depend on it.
+- The diagnostic modal routing is pass/fail conditional — see `1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md` for full details.
+- `toga` app repo was not in registry.json before this session — it has been added (framework 1.0, role app, dependsOn library).
+
+## Related docs
+- `1.0/apps/library/features/diagnostic-dialog-view-recommended-services.md`
+
+## Change history
+- 2026-06-23 — Initial doc. All 2026 builder buttons now use linkBuilderRefresh; diagnostic modal uses pass/fail routing. toga added to registry.json. (snaredla)

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/knowledge/registry.json

@@ -158,6 +158,17 @@
     "project": "TOGa Commerce",
     "framework": "2.0",
     "role": "app",
-    "dependsOn": ["api2"]
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "toga",
+    "project": "TOGa",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
   }
-]
+]

package/package.json

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