toga-ai 1.0.67 → 1.0.69

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

@@ -0,0 +1,8 @@
+# togadesk (TogaDesk) — 1.0 knowledge
+
+| 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/togadesk/features/smb-contract-editing.md

@@ -0,0 +1,90 @@
+---
+title: SMB Contract Editing & the clientMspId Corruption Trap
+framework: "1.0"
+repo: togadesk
+project: TogaDesk
+client: shared
+type: feature
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files:
+  - 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
+related:
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+  - 1.0/apps/togaview/features/msp-dashboard.md
+---
+
+## Summary
+The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits
+`TOGA_*.SMBContracts` rows via a modal. Because multiple TOGA clients can share one TOGA_*
+database, this page historically corrupted `clientMspId` on save — the root cause of MSP
+portal users seeing "You have no assigned clients" in TogaView. Fixed June 2026.
+
+## Key files / entry points
+- Modal template: `desk/template/modals/toga/smbcontracts/smbContract.php`
+- Modal controller: `desk/includes/controllers/modals/toga/smbcontracts/smbContract.php`
+- Submit action: `desk/includes/controllers/actions/toga/smbcontracts/smbContract.php`
+- `edit.php` in the same actions folder is a separate, partly-legacy path that does NOT touch
+  `clientMspId`.
+- The same controller serves the CSP variant (`csp=true` → `type='reseller'`).
+
+## How it works
+The bug pattern (now guarded against):
+1. Multiple TOGA clients share one TOGA_* database (e.g. TOGA clients 9 "True" and 20
+   "craftex" both use `TOGA_True`), so the contracts page under client A lists client B's
+   contracts too.
+2. The modal's MSP dropdown was scoped to client A's `ClientMsp` rows; the contract's real MSP
+   wasn't an option; no option got `selected`; **the browser silently auto-selects the first
+   option**; saving wrote the wrong `clientMspId`.
+3. TogaView msp_dashboard's `SMBContracts WHERE clientMspId = <session clientMspId>` then
+   matched nothing for the real MSP's users.
+
+Fixes in place (June 2026):
+- The modal appends the contract's current MSP to the option list when missing.
+- The action only assigns a posted `clientMspId` that is `> 0` AND exists in `ClientMsp`
+  (`App_Model_TogaDesk_ClientMsp::exists()`); otherwise it keeps the stored value.
+- `SMBContracts.clientMspId` is nullable — NEW + "None" saves NULL (fine).
+
+## Data model
+```
+TOGaDeskSupport.clients           (togadesk client)
+   ▲ clientId
+TOGaDeskSupport.ClientMsp         (id, clientId, type ENUM 'msp'|'reseller',
+   ▲                               ticketDepartmentId, companyName)
+   │ clientMspId
+TOGA.Clients                      (toga client registry; togadeskClientId, databaseName)
+TOGA_<databaseName>.SMBContracts  (clientMspId → ClientMsp.id, mainContactId,
+                                   serviceSeats, dateContractEnd)
+```
+- A togadesk client can own **multiple ClientMsp rows** (clients 18 and 26 do — mixes of msp
+  and reseller). Code must not assume exactly one.
+- **Multiple TOGA clients can share one TOGA_* database** — any page listing `SMBContracts`
+  for a `togaClientId` actually lists every tenant's contracts in that database.
+
+Integrity audit query (run per shared TOGA_* db, eyeball contractNumber vs companyName
+mismatches):
+```sql
+SELECT sc.id, sc.contractNumber, sc.clientMspId, cm.companyName, cm.clientId
+FROM SMBContracts sc
+LEFT JOIN TOGaDeskSupport.ClientMsp cm ON cm.id = sc.clientMspId
+```
+
+## Client variations
+None in code — uniform. Craftex reference values: togadesk clientid 169, ClientMsp 42, TOGA
+client 20 (`TOGA_True`), SMBContract 230 (Customer 932297).
+
+## Gotchas / known issues
+- `dateContractEnd` in the past is display-only — it does not hide tickets in the MSP portal.
+- `ClientMsp.ticketDepartmentId` holds only ONE department even when the client has several —
+  never build department logic on it (see TogaView msp-dashboard doc).
+
+## Change history
+- 2026-06-12 — documented; modal + action guards shipped to togadesk dev branch (mhammontree)
+
+## Related docs
+- [Ticket lifecycle](ticket-lifecycle.md)
+- [TogaView MSP dashboard](../../togaview/features/msp-dashboard.md)

package/knowledge/1.0/apps/togadesk/features/ticket-lifecycle.md

@@ -0,0 +1,102 @@
+---
+title: Ticket Lifecycle (class.ticket.php)
+framework: "1.0"
+repo: togadesk
+project: TogaDesk
+client: shared
+type: feature
+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
+  - desk/includes/controllers/actions/tickets/merge.php
+related:
+  - 1.0/apps/togadesk/features/smb-contract-editing.md
+  - 1.0/apps/togaview/features/msp-dashboard.md
+---
+
+## Summary
+All TogaDesk ticket creation and reply handling funnels through `Ticket` in
+`desk/includes/classes/class.ticket.php`. This doc covers the creation paths, the
+`deriveCustomerId()` resolution added June 2026, and the `addReply()` status-transition
+switch — including its known gaps.
+
+⚠ There are TWO `class.ticket.php` files. The live one is
+`desk/includes/classes/class.ticket.php`. The root `includes/classes/class.ticket.php` is an
+ancient variant (random 6-digit ticket numbers, schema that no longer matches) — never extend it.
+
+## Key files / entry points
+Creation paths — all funnel through `Ticket::add($data)`:
+- Staff UI: `desk/includes/controllers/actions.php` → `Ticket::add($_POST)`
+- API: `desk/api/resources/tickets.php`
+- Email intake: `crons/tickets.php` (IMAP poll per `tickets_departments.email`, called via
+  `tickets_<ENV>.php` wrappers; loads desk classes via `appClassAutoload`) →
+  `Ticket::emailToTicket()` → parses "Ticket #NNNNNNN" from subject → matched ticket ⇒
+  `addReply()`, else ⇒ `add()`.
+- Ticket merge (`actions/tickets/merge.php`) inserts a master ticket directly — it copies
+  fields from the child, including `customerid` (since June 2026).
+
+## How it works
+
+### `Ticket::deriveCustomerId(int, string): ?int` (added June 2026)
+Called from `add()` when no `customerId` was supplied — fixes MSP-portal-invisible tickets
+(togaview MSP pages filter on `tickets.customerid`, which only togaview-side creation set;
+staff/API/email tickets left it NULL).
+
+Logic: collect ALL ClientMsp ids for the clientid (non-MSP ⇒ null) →
+`TOGA.Clients.databaseName` → try email match against contracted end users
+(`SMBContracts→SMBContractItems→ServiceRequests→Contacts`) → fallback to the MSP's **sole
+distinct** customer via `SMBContracts.mainContactId`; multiple customers + no email match ⇒
+null (never guess). Exceptions are logged and swallowed — the email cron must never be blocked.
+
+Read-only test harness pattern: see the standalone-test-scripts workflow doc.
+
+### `Ticket::addReply($data)` status transitions
+When the caller supplies no status, a `switch ($ticket['status'])` decides. Pattern: staff
+reply preserves "waiting" states; client reply moves to `Open`; Closed/Review → `Reopened`.
+
+**The status write is gated on `isset($data['status'])`** — a status missing from the switch
+means the reply lands but the ticket status silently never changes (no history entry, no queue
+re-entry). That was the On Hold SLA bug; `case 'On Hold'` (admin ⇒ stays On Hold, client ⇒
+Open) was added June 2026.
+
+- Special case: an admin replying to their OWN ticket is treated as a user reply.
+- Auto-assign on first staff reply requires the role perm `allowAutoAssign` via
+  profiles/profile_departments.
+- Side integrations on reply: Syncro status push (`referenceId='SYNCRO'`), Talos AI summaries
+  (TogaIQ), merged-ticket fan-out (replies propagate to child tickets).
+
+## Data model
+- `TOGaDeskSupport.tickets` — `clientid`, `customerid` (TOGA `Customers.id`, drives MSP portal
+  visibility), `departmentid`, `email`, `status`. **No closed-date column.**
+- `tickets_replies` (`newStatus`), `tickets_history`.
+
+## Client variations
+None — uniform. Pre-fix tickets for a given MSP client may need a one-time `customerid`
+backfill (e.g. craftex:
+`UPDATE TOGaDeskSupport.tickets SET customerid = 932297 WHERE clientid = 169 AND customerid IS NULL;`).
+
+## Gotchas / known issues
+- `'Resolved'` is STILL missing from the `addReply()` switch — a client reply to a Resolved
+  ticket changes nothing. Known gap, awaiting product decision.
+- **There is NO 72-hour reopen window in code**, despite SME belief. `Closed` → `Reopened` is
+  unconditional, email intake has no age check, and the `tickets` table has no closed-date
+  column (close time would have to come from `tickets_replies.newStatus='Closed'` or
+  `tickets_history`). Implementing it is a product decision: what happens to a lapsed reply
+  (attach-but-closed / new ticket / bounce)?
+- Legacy `togadesk/includes/class.ticket.php` has active email-reopen logic; the live
+  `desk/includes` version has it commented out — email replies never set status to "Reopened"
+  via `emailToTicket()`.
+
+## Change history
+- 2026-06-12 — documented from craftex MSP portal debugging session (mhammontree)
+- 2026-06 — added `deriveCustomerId()`; added `On Hold` case to addReply() switch; merge
+  copies `customerid` (mhammontree)
+
+## Related docs
+- [SMB contract editing](smb-contract-editing.md)
+- [TogaView MSP dashboard](../../togaview/features/msp-dashboard.md)

package/knowledge/1.0/apps/togadesk/workflows/standalone-test-scripts.md

@@ -0,0 +1,49 @@
+---
+title: Standalone PHP Test Script Bootstrap (TogaDesk)
+framework: "1.0"
+repo: togadesk
+project: TogaDesk
+client: shared
+type: workflow
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files: []
+related:
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+---
+
+## Summary
+How to write a standalone CLI PHP script that bootstraps the TogaDesk framework for
+read-only testing of desk classes (e.g. `Ticket::deriveCustomerId()`), without running the
+web stack. Example harness: `C:\WWW\test\@Mark\TOGaDeskSupport\test_derive_customer_id.php`
+(local path — adapt per machine).
+
+## Steps
+1. `chdir()` to the desk app root (`<togadesk>/desk`).
+2. Fake `$_SERVER['SCRIPT_FILENAME']` so the framework resolves paths.
+3. `require` the 1.0 framework bootstrap `<library>/_.php`, then desk `functions.php` +
+   `config.php`.
+4. Register `vendorClassAutoload` / `appClassAutoload`, plus composer autoload.
+5. Set the `ENVIRONMENT` env var BEFORE bootstrap (or default it in the script). If unset it
+   defaults to `worker` and the script dies looking for `config.worker.ini`.
+6. Wrap `App_Framework_TOGaDesk::initialize()` in `ob_start()` … `ob_end_clean()` — the
+   framework echoes a Sentry warning during init, which marks headers as sent and makes the
+   session `ini_set()` throw.
+7. Restore error/exception handlers after init to see real errors instead of the HTML error
+   page.
+8. Skip medoo unless needed (PHP 8.2 deprecation noise); `App_Database` is enough.
+
+## Systems involved
+- `library` (1.0 framework core), togadesk desk classes, legacy MySQL cluster.
+- DB link names (`db_togadesk`, `db_toga`, …) resolve to `[database_X]` sections in
+  `config.<ENVIRONMENT>.ini`.
+
+## Edge cases & escalation
+- "Sentry is not installed" output followed by an `ini_set` session error = you missed the
+  output-buffer wrap (step 6).
+- Scripts should stay read-only against shared/mirrored data unless explicitly doing a data
+  fix.
+
+## Change history
+- 2026-06-12 — captured from deriveCustomerId test harness work (mhammontree)

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

@@ -0,0 +1,8 @@
+# togaview (TogaView) — 1.0 knowledge
+
+| 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/1.0/apps/togaview/features/login-flows.md

@@ -0,0 +1,65 @@
+---
+title: TogaView Login Flows & Session Variables
+framework: "1.0"
+repo: togaview
+project: TogaView
+client: shared
+type: feature
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files:
+  - mvc/login/post.php
+  - _/app/framework.php
+related:
+  - 1.0/apps/togaview/features/msp-dashboard.md
+  - 1.0/apps/togaview/features/ticket-detail-page.md
+---
+
+## Summary
+`mvc/login/post.php` tries login flows in order; the first match wins. Each flow sets a
+DIFFERENT session shape — any code reading session vars must know which flows set what.
+Several production bugs (ownership checks rejecting valid users) came from assuming a
+uniform session.
+
+## How it works
+
+| Flow | userType | Key session vars |
+|---|---|---|
+| Retail (walmart/walmartplus) | `RETAIL` | `togadeskClientId=11` (hardcoded), `emailAddress`, `supportSkuExists=true` |
+| MSP contact (ClientMspContacts join) | `MSP` | `clientMspId`, `togadeskClientId` (=ClientMsp.clientId), `clientDepartmentId` (=ClientMsp.ticketDepartmentId), `emailAddress`, `customerId` → redirects `/msp_dashboard` |
+| SMB admin (SMBContracts.mainContactId) | `CUSTOMER` | same family as MSP, `togadeskClientId` from ClientMsp.clientId |
+| End user (SMBContractItems→ServiceRequests→Contacts) | `ENDUSER` | `emailAddress`, `clientMspId`, `togadeskClientId`, `clientDepartmentId`, `supportSkuExists` → `/enterprise_dashboard` |
+| staplesprotection (inline, AIG-backed) | `ENDUSER` | ⚠ sets `$_SESSION['email']` **not** `emailAddress`, and **no `togadeskClientId`** |
+| rumcsi / newcenturyholdingsllc (SAML in framework.php) | `ENDUSER`/`ADMIN` | `togadeskClientId` = their togadesk clientid; newcentury auto-creates `people` rows from SAML |
+
+- `$_SESSION['supportSkuExists']` gates the entire ticket block on enterprise_dashboard. Set
+  by checking the contract's service SKU against a **hardcoded whitelist** in login/post.php
+  (`smbContractSkus` = [190001, 190002, 190003, 210001, 210002, 210003, 24477039, 160202,
+  160203]). New support SKUs must be added there.
+- MSP logins join through `TOGaDeskSupport.ClientMspContacts` →
+  `TOGaDeskSupport.contacts` — a malformed contact email breaks the match (e.g. contact 76
+  "Wendy Williams" had `Wendy@craftex` missing `.com`).
+
+## Data model
+`TOGaDeskSupport.ClientMsp` / `ClientMspContacts` / `contacts`; TOGA-side
+`SMBContracts` / `SMBContractItems` / `ServiceRequests` / `Contacts` for SMB admin and
+end-user flows.
+
+## Client variations
+- walmart/walmartplus: hardcoded `togadeskClientId=11`.
+- staplesprotection: inline branch, end-user style, divergent session keys (see table).
+- rumcsi / newcenturyholdingsllc: SAML handled in `_/app/framework.php`, not login/post.php.
+
+## Gotchas / known issues
+- Code consuming the session must read `emailAddress` with an `email` fallback (and tolerate
+  missing `togadeskClientId`) or it rejects all staplesprotection users — this broke the
+  ticket.php ownership check until the fallback was added (June 2026).
+- The flows are order-dependent: a contact matching an earlier flow never reaches later ones.
+
+## Change history
+- 2026-06-12 — documented from craftex MSP portal debugging session (mhammontree)
+
+## Related docs
+- [MSP dashboard & ticket visibility](msp-dashboard.md)
+- [Ticket detail page](ticket-detail-page.md)

package/knowledge/1.0/apps/togaview/features/msp-dashboard.md

@@ -0,0 +1,84 @@
+---
+title: MSP Dashboard & Ticket Visibility Rules
+framework: "1.0"
+repo: togaview
+project: TogaView
+client: shared
+type: feature
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files:
+  - common/togaview/msp_dashboard.php
+  - mvc/msp_client_dashboard
+  - mvc/enterprise_dashboard
+  - mvc/support/support.php
+related:
+  - 1.0/apps/togaview/features/login-flows.md
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+  - 1.0/apps/togadesk/features/smb-contract-editing.md
+---
+
+## Summary
+Why tickets "disappear" in the TogaView client portal: different pages scope tickets
+**differently**, and the MSP pages depend on `tickets.customerid` and `SMBContracts`
+integrity. Covers the per-page filters and the June 2026 multi-department stats fix.
+
+## How it works
+
+### Ticket filters per page
+| Page | Ticket filter |
+|---|---|
+| `common/togaview/msp_dashboard.php` (MSP/CUSTOMER) | per-customer counts: `clientid` + `customerid` + `departmentid IN (client's departments)`; customer list driven by `SMBContracts WHERE clientMspId = session clientMspId` — **zero contracts ⇒ "You have no assigned clients" and no ticket query at all** |
+| `mvc/msp_client_dashboard` (ticket list) | `tickets.customerid IN (<customers>) AND tickets.clientid = <session togadeskClientId>` — **no department filter** |
+| `mvc/enterprise_dashboard` (ENDUSER) | `tickets.email = session emailAddress AND tickets.departmentid = session clientDepartmentId AND status <> 'Closed'`, gated by `supportSkuExists` |
+| `mvc/support/support.php` | `tickets.email = <email>` only — no client filter |
+
+**The #1 trap: `tickets.customerid`.** The MSP portal can only show tickets whose
+`customerid` matches a TOGA `Customers.id` under the MSP's SMBContracts. Only togaview-side
+ticket creation set it; tickets created in togadesk (staff UI, API, email intake)
+historically left it NULL ⇒ invisible to the MSP portal. Fixed June 2026 by
+`Ticket::deriveCustomerId()` (see togadesk ticket-lifecycle doc). Pre-fix tickets need a
+one-time backfill per client.
+
+`$disableTickets` on msp_client_dashboard is seat-arithmetic only
+(`serviceSeats < activeUsers`) — it hides Create-Ticket buttons, never the list.
+
+### Multi-department stats (fixed June 2026)
+`common/togaview/msp_dashboard.php` used to filter every stat on the single
+`ClientMsp.ticketDepartmentId`. It now derives **all** of the client's departments once
+(`tickets_departments WHERE clientId = <togadeskClientId>`) into `$departmentIdList` and uses
+`departmentid IN (...)` everywhere (status counts, priority counts, per-day chart, KB
+category resolution).
+- The department fetch is **MSP-level on purpose** — don't move it inside the customer loop.
+- Empty department list → `'0'` sentinel (valid SQL, matches nothing) + `error_log`.
+- A ticket with `departmentid = 0` is excluded from stats by design.
+
+## Data model
+- `TOGaDeskSupport.tickets` (`clientid`, `customerid`, `departmentid`, `email`, `status`)
+- `TOGaDeskSupport.tickets_departments.clientId` maps support departments to a togadesk
+  client — a client can have several (craftex: 317, 318, 319), but
+  `ClientMsp.ticketDepartmentId` holds only ONE. Never build department logic on it.
+- 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`.
+
+## Client variations
+- The single-department pattern still exists in the `newcenturyholdingsllc` and
+  `towfoundation` dashboard variants (not yet fixed there) and in enterprise_dashboard's
+  `clientDepartmentId` filter for end users.
+- Only towfoundation / newcenturyholdingsllc have their own dashboard variants; everyone else
+  runs the generic `common/togaview/` pages.
+
+## Gotchas / known issues
+- "You have no assigned clients" usually means the MSP's `SMBContracts.clientMspId` was
+  corrupted by the togadesk contract modal (see smb-contract-editing doc) — check data before
+  debugging code.
+- An expired `SMBContracts.dateContractEnd` is display-only; it does not hide tickets.
+
+## Change history
+- 2026-06-12 — documented; multi-department stats fix shipped to dev (mhammontree)
+
+## Related docs
+- [Login flows](login-flows.md)
+- [TogaDesk ticket lifecycle](../../togadesk/features/ticket-lifecycle.md)
+- [SMB contract editing](../../togadesk/features/smb-contract-editing.md)

package/knowledge/1.0/apps/togaview/features/ticket-detail-page.md

@@ -0,0 +1,76 @@
+---
+title: Ticket Detail Page Security (common/togaview/ticket.php)
+framework: "1.0"
+repo: togaview
+project: TogaView
+client: shared
+type: feature
+status: active
+updated: 2026-06-12
+owners: ["mhammontree"]
+files:
+  - common/togaview/ticket.php
+related:
+  - 1.0/apps/togaview/features/login-flows.md
+  - 1.0/apps/togaview/features/msp-dashboard.md
+---
+
+## Summary
+`common/togaview/ticket.php` is the ticket detail page for nearly ALL hosts — only
+towfoundation/newcenturyholdingsllc have their own variants; every other client's style falls
+back to it. Hardened June 2026 against IDOR (ticket view + file attachment download) and a
+"Deactivated Seat" false positive that blocked MSP admins.
+
+## How it works
+
+### Ownership check (IDOR fix)
+Applies to BOTH the ticket view AND the `fileId` attachment download (which runs first and
+`exit`s). Access allowed iff:
+- `tickets.clientid == (int) $_SESSION['togadeskClientId']`, OR
+- ticket email == session email (case-insensitive; reads `emailAddress` with `email` fallback
+  for staplesprotection sessions).
+
+Attachment ownership resolves `files → tickets_replies → tickets`. Unauthorized or missing ⇒
+"Ticket Not Found" + exit.
+
+**Do NOT "tighten" the email arm to clientid<=0-only tickets** (a CodeRabbit suggestion,
+reviewed and declined): staplesprotection sessions have no `togadeskClientId`, and
+support.php lists tickets by email with no client filter — the requester is always entitled
+to their own ticket.
+
+### Deactivated-seat gate
+Only `USERTYPE_ENDUSER` gets the "Deactivated Seat" block. It fires when the ticket's
+requester email isn't a provisioned SMB seat user (the SMBContractItems JOIN returns empty) —
+which is NORMAL for email-intake tickets, so it must never apply to MSP/CUSTOMER viewers.
+
+### Input handling
+`$_GET['ticketId']` is int-cast once at the top — it is interpolated into several queries in
+this file (was a live SQL injection before June 2026).
+
+## Data model
+`TOGaDeskSupport.tickets`, `tickets_replies`, `files`; TOGA-side `SMBContractItems` →
+`ServiceRequests` → `Contacts` for the seat check.
+
+## Client variations
+- All style variants fall back to this file — no style has its own ticket.php except
+  towfoundation/newcenturyholdingsllc.
+- staplesprotection: session uses `email`/`clientId` keys (not
+  `emailAddress`/`togadeskClientId`) — the ownership check's email fallback exists for them.
+
+## Gotchas / known issues
+- Pre-existing warts (untouched): unescaped `$emailAddress` in the walmart branch query;
+  unguarded `explode(' ', name)` in rumcsi/towfoundation branches.
+- Pending as of 2026-06-12: MSP/CUSTOMER bypass for the ownership check (MSP session's
+  `togadeskClientId` is the MSP's own client id — matches their customers' tickets since those
+  carry the MSP's clientid, but verify when an MSP views a ticket whose clientid differs);
+  togaview changes were uncommitted at session end.
+
+## Change history
+- 2026-06-12 — file-attachment IDOR fix (ownership check now covers fileId branch);
+  email-key fallback for staplesprotection (mhammontree)
+- 2026-06 — ownership check added (ticket view), deactivated-seat gate restricted to
+  ENDUSER, ticketId int-cast (mhammontree)
+
+## Related docs
+- [Login flows](login-flows.md)
+- [MSP dashboard & ticket visibility](msp-dashboard.md)

package/knowledge/INDEX.md

@@ -6,6 +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) — 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/knowledge/registry.json

@@ -7,5 +7,7 @@
   { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] },
   { "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"] }
+  { "repo": "toga2-view",  "project": "TOGa View Frontend", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
+  { "repo": "togadesk",    "project": "TogaDesk",    "framework": "1.0", "role": "app",  "dependsOn": [] },
+  { "repo": "togaview",    "project": "TogaView",    "framework": "1.0", "role": "app",  "dependsOn": [] }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.67",
+  "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",