toga-ai 1.0.68 → 1.0.69

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

@@ -2,6 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [TogaDesk Architecture](architecture.md) | TogaDesk is the staff-facing support desk (analysts work at `/desk/`). | desk/includes/classes/class.ticket.php, desk/includes/controllers/actions.php, desk/api/resources/tickets.php, crons/tickets.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |
 | [Ticket Lifecycle (class.ticket.php)](features/ticket-lifecycle.md) | All TogaDesk ticket creation and reply handling funnels through `Ticket` in `desk/includes/classes/class.ticket.php`. | desk/includes/classes/class.ticket.php, desk/includes/controllers/actions.php, desk/api/resources/tickets.php, crons/tickets.php, desk/includes/controllers/actions/tickets/merge.php |
 | [Standalone PHP Test Script Bootstrap (TogaDesk)](workflows/standalone-test-scripts.md) | How to write a standalone CLI PHP script that bootstraps the TogaDesk framework for read-only testing of desk classes (e.g. |  |

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

@@ -0,0 +1,87 @@
+---
+title: TogaDesk Architecture
+framework: "1.0"
+repo: togadesk
+project: TogaDesk
+client: shared
+type: architecture
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files:
+  - desk/includes/classes/class.ticket.php
+  - desk/includes/controllers/actions.php
+  - desk/api/resources/tickets.php
+  - crons/tickets.php
+related:
+  - 1.0/apps/togaview/architecture.md
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+  - 1.0/apps/togadesk/features/smb-contract-editing.md
+---
+
+## Summary
+TogaDesk is the staff-facing support desk (analysts work at `/desk/`). It is a framework 1.0
+(`App_`) app bootstrapped from the `library` core (`_.php`). The on-disk repo root contains
+legacy top-level code; **the live application root is `desk/`** — e.g. the live
+`class.ticket.php` is `desk/includes/classes/class.ticket.php`, while the root
+`includes/classes/class.ticket.php` is an ancient variant that must never be extended.
+
+## System topology
+| System | Serves | DB connections |
+|---|---|---|
+| TogaDesk (`desk/`) | Staff/analysts | `db_togadesk` (TOGaDeskSupport), `db_toga` (TOGA), `db_client_aig`, per-client by name |
+| TogaView (sibling repo) | Clients at `<client>.togaview.com` | same cluster, same link names |
+
+- **TogaDesk and TogaView share the `TOGaDeskSupport` database** — tickets, clients,
+  contacts, departments, ClientMsp all live there. A change to ticket data semantics affects
+  both apps.
+- All legacy databases (TOGaDeskSupport, TOGA, TOGA_*, RetailServices) are on the same MySQL
+  cluster, so cross-schema joins (e.g. `TOGaDeskSupport.ClientMsp` from a `db_toga`
+  connection) work and are used everywhere.
+- `db_X` link names resolve generically to `[database_X]` sections in the per-environment
+  `config.<env>.ini`. Environment comes from the `ENVIRONMENT` env var — it defaults to
+  `worker` if unset, so a CLI script without it fails looking for `config.worker.ini`.
+
+## The MSP data model (the core of everything)
+```
+TOGaDeskSupport.clients          (togadesk client)
+   ▲ clientId
+TOGaDeskSupport.ClientMsp        (id, clientId, type ENUM 'msp'|'reseller',
+   ▲                              ticketDepartmentId, companyName)
+   │ clientMspId
+TOGaDeskSupport.ClientMspContacts(togadeskContactId → TOGaDeskSupport.contacts.id)
+                                  = the people who get MSP logins in togaview
+
+TOGA.Clients                     (toga client registry; togadeskClientId, databaseName)
+TOGA_<databaseName>.SMBContracts (clientMspId → ClientMsp.id, mainContactId,
+                                  serviceSeats, dateContractEnd)
+TOGA_*.SMBContractItems          (seats; serviceRequestId NULL = open seat)
+TOGA_*.ServiceRequests           (contactId → Contacts.id)
+TOGA_*.Contacts                  (customerId → Customers.id)
+TOGA_*.Customers                 (the managed business)
+```
+Invariants:
+- An MSP's "customers" are **TOGA-side `Customers` rows**, NOT togadesk clients. All of an
+  MSP's tickets carry the MSP's own `tickets.clientid`.
+- A togadesk client can own **multiple ClientMsp rows** (clients 18 and 26 do). Never assume
+  exactly one.
+- **Multiple TOGA clients can share one TOGA_* database** (e.g. TOGA clients 9 and 20 both
+  use `TOGA_True`). Any page listing `SMBContracts` for a `togaClientId` lists every tenant's
+  contracts in that database — the root of the clientMspId corruption bug.
+- `tickets_departments.clientId` maps support departments to a togadesk client; a client can
+  have several, but `ClientMsp.ticketDepartmentId` holds only ONE — never build
+  department-scoping logic on it.
+
+## Key flows
+- All ticket creation/replies funnel through `Ticket` (`desk/includes/classes/`):
+  staff UI (`actions.php`), API (`desk/api/resources/tickets.php`), email intake
+  (`crons/tickets.php` IMAP poll → `emailToTicket()`), merge. See ticket-lifecycle feature doc.
+- SMB contract administration edits TOGA_* `SMBContracts` from `/desk/?route=toga/smbcontracts`.
+  See smb-contract-editing feature doc.
+
+## Key decisions
+- `Ticket::deriveCustomerId()` (June 2026) resolves `tickets.customerid` at creation so
+  staff/API/email tickets are visible in the TogaView MSP portal; it returns null rather than
+  guess when ambiguous, and swallows (logs) exceptions so email intake is never blocked.
+- DB access for tooling: legacy cluster via the TOGa Database Integration MCP, environment
+  `legacy`; schemas `TOGaDeskSupport`, `TOGA`, `TOGA_True`, etc.

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

@@ -2,6 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [TogaView Architecture](architecture.md) | TogaView is the client-facing support portal, served per client at `<client>.togaview.com`. | index.php, _/app/framework.php, mvc/login/post.php |
 | [TogaView Login Flows & Session Variables](features/login-flows.md) | `mvc/login/post.php` tries login flows in order; the first match wins. | mvc/login/post.php, _/app/framework.php |
 | [MSP Dashboard & Ticket Visibility Rules](features/msp-dashboard.md) | Why tickets "disappear" in the TogaView client portal: different pages scope tickets **differently**, and the MSP pages depend on `tickets.customerid` and `SMBC | common/togaview/msp_dashboard.php, mvc/msp_client_dashboard, mvc/enterprise_dashboard, mvc/support/support.php |
 | [Ticket Detail Page Security (common/togaview/ticket.php)](features/ticket-detail-page.md) | `common/togaview/ticket.php` is the ticket detail page for nearly ALL hosts — only towfoundation/newcenturyholdingsllc have their own variants; every other clie | common/togaview/ticket.php |

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

@@ -0,0 +1,67 @@
+---
+title: TogaView Architecture
+framework: "1.0"
+repo: togaview
+project: TogaView
+client: shared
+type: architecture
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files:
+  - index.php
+  - _/app/framework.php
+  - mvc/login/post.php
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togaview/features/login-flows.md
+  - 1.0/apps/togaview/features/msp-dashboard.md
+  - 1.0/apps/togaview/features/ticket-detail-page.md
+---
+
+## Summary
+TogaView is the client-facing support portal, served per client at `<client>.togaview.com`.
+Framework 1.0 (`App_`) app bootstrapped from the `library` core (`_.php`). It shares the
+`TOGaDeskSupport` database with TogaDesk (tickets, clients, contacts, departments, ClientMsp)
+— see the TogaDesk architecture doc for the cluster topology and the full MSP data model;
+those invariants apply here unchanged.
+
+## Page routing (stylePath model)
+`index.php → App_Framework_TogaView::renderIndex()` (in `_/app/framework.php`):
+
+1. A giant `switch ($_SERVER['HTTP_HOST'])` sets `$_SESSION['stylePath']` (and sometimes
+   `$_SESSION['host']`). Client subdomains are **hardcoded** — a new client subdomain must be
+   added to this switch (e.g. `craftex.togaview.com` → stylePath `togatechnology`, no `host`).
+2. Page files: `mvc/<page>/get.php` typically resolves the template as:
+   - host in `HOSTS_USING_TOGA_TECH_STYLE` (= `['towfoundation','newcenturyholdingsllc']`)
+     → `common/<host>/<page>.php`;
+   - else `common/<stylePath>/<page>.php` if it exists;
+   - else **fallback `common/togaview/<page>.php`** — the generic implementation.
+3. `common/togatechnology/` has only header/footer/sidebar — so most clients run the
+   **generic** `common/togaview/*.php` pages. Only towfoundation, newcenturyholdingsllc (and
+   partially rumcsi via inline branches) have real page variants.
+
+**Implication:** a change to `common/togaview/<page>.php` affects nearly every client at
+once; a per-client behavior change belongs in a host/stylePath variant or an inline branch.
+
+## Session / identity model
+Login (`mvc/login/post.php`) tries flows in order — Retail, MSP contact, SMB admin, end user,
+plus inline client branches (staplesprotection) and SAML clients handled in `framework.php`
+(rumcsi, newcenturyholdingsllc). **Each flow sets a different session shape**; notably
+staplesprotection sets `$_SESSION['email']` (not `emailAddress`) and no `togadeskClientId`.
+Full matrix: login-flows feature doc. Any page reading session identity must tolerate the
+divergent shapes (read `emailAddress` with `email` fallback).
+
+## Ticket visibility
+Each page scopes tickets differently (msp_dashboard, msp_client_dashboard,
+enterprise_dashboard, support.php) — see the msp-dashboard feature doc. The MSP portal
+depends on `tickets.customerid` being populated (TOGA `Customers.id`), which TogaDesk's
+`Ticket::deriveCustomerId()` now sets at creation.
+
+## Key decisions
+- The ticket detail page `common/togaview/ticket.php` enforces an ownership check (clientid
+  match OR requester-email match) on both ticket view and attachment download; the email arm
+  is intentionally NOT restricted to unassigned tickets (staplesprotection and support.php
+  semantics require it). See ticket-detail-page feature doc.
+- New client onboarding touches at minimum: the HTTP_HOST switch in `framework.php`, a login
+  flow (or SAML branch), and possibly the `smbContractSkus` whitelist in `login/post.php`.

package/knowledge/INDEX.md

@@ -6,8 +6,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 4 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
-- **togadesk** (TogaDesk) — 3 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
-- **togaview** (TogaView) — 3 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
+- **togadesk** (TogaDesk) — 4 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
+- **togaview** (TogaView) — 4 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 
 ## 2.0 framework
 

package/package.json

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