toga-ai 1.0.68 → 1.0.70

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/2.0/apps/worker2/INDEX.md

@@ -7,3 +7,4 @@
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
+| [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini |

package/knowledge/2.0/apps/worker2/features/teams-transcript-export.md

@@ -0,0 +1,120 @@
+---
+title: Teams Meeting Transcript Export
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-12
+owners: ["ajean"]
+files:
+  - worker2/Worker/Team/Transcripts.php
+  - worker2/Config/production.ini
+related:
+  - ../architecture.md
+  - ./creating-worker-actions.md
+---
+
+## Summary
+
+`_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for
+Teams meeting transcripts produced by a set of organizers, classifies each meeting by
+client (from the meeting title), and archives the raw WebVTT to S3. Scheduled via three
+`Core.CronJobs` rows (weekdays 10:00 / 13:00 / 17:30 Central).
+
+## Key files / entry points
+
+- `Worker/Team/Transcripts.php` — the whole feature (abstract class, static methods).
+- `Config/production.ini` `[teams]` section — Entra app creds, organizer source, S3 target.
+- `[teamsClientAliases]` config section — alias → canonical client name for classification.
+- Ledger table `Team.TranscriptExports` (DB alias `_underscore::DB_TEAM`, core cluster).
+
+## How it works
+
+Per run, after acquiring a Graph client-credentials token:
+
+1. **Resolve organizers** via `resolveConfiguredOrganizers()`:
+   - **Preferred:** the Entra security group in `[teams] organizer_group_id`. `getGroupMemberIds()`
+     calls `GET /groups/{id}/members/microsoft.graph.user?$select=id`, which returns member
+     **object-ids (GUIDs)** directly — exactly what `getAllTranscripts` requires. Uses the
+     `GroupMember.Read.All` app permission. Admins add/remove organizers in Entra with **no redeploy**.
+   - **Fallback:** the comma-separated `[teams] organizer_user_ids` list (used only when no group
+     is configured or the group resolves no members; group-lookup failures are caught so they
+     can't abort the run).
+2. Per organizer: `getAllTranscripts(meetingOrganizerUserId='{guid}', startDateTime, endDateTime)`
+   over an incremental window (`MAX(dtCreated)` watermark from the ledger, else `now − lookbackDays`),
+   following `@odata.nextLink`.
+3. Per new transcript (dedup by `transcriptIdentifier`): fetch meeting `subject`+`startDateTime`
+   (cached per meeting), classify, download VTT (`?$format=text/vtt`), `putObject` to S3, insert
+   ledger row.
+
+**Classification:** case-insensitive substring match of the meeting title against active
+`Core.Clients` names + `[teamsClientAliases]`, longest needle wins, min length 3. No match → `general`.
+
+**S3 layout:** `s3://{[teams] s3_bucket}/{s3_prefix}{client-or-general}/{YYYY-MM-DD}/{HHMM}_{title-slug}_{shortId}.vtt`
+(date/time in Central). Currently `toga-private/transcripts/…`.
+
+## Data model
+
+`Team.TranscriptExports` — unique `transcriptIdentifier` (idempotency + per-organizer watermark
+via `MAX(dtCreated)`). Columns: `uuid, dtExported, dtCreated, dtMeeting, meetingSubject,
+sizeBytes, classification, transcriptIdentifier, meetingIdentifier, organizerUserIdentifier, s3Key`.
+
+## Entra app permissions (app-only / client credentials)
+
+The dedicated Entra app **Teams-Worker2-TranscriptExport** needs, admin-consented:
+
+- `OnlineMeetingTranscript.Read.All` — read transcript content.
+- `OnlineMeetings.Read.All` — read meeting metadata.
+- `GroupMember.Read.All` — read the organizer group's members (the object-ids).
+
+`User.Read.All` is **deliberately not used** — the group-members call already returns object-ids,
+so the old per-UPN `/users/{upn}?$select=id` lookup is unnecessary.
+
+No Teams **Application Access Policy** is required for this tenant — verified the app can read
+the organizers' transcripts directly once given a valid object-id.
+
+## Client variations
+
+None — uniform. Output is partitioned per client by meeting-title classification, but the
+process is identical for all.
+
+## Gotchas / known issues
+
+- **`getAllTranscripts` requires an AAD object-id (GUID), NOT a UPN.** Passing a UPN
+  (e.g. `ajean@togatech.com`) returns the opaque `HTTP 400 BadRequest / "UnknownError"`.
+  This is the single most likely cause of an export failure.
+- **The earlier UPN→GUID fix (PR #77) silently failed.** It resolved each UPN via
+  `GET /users/{upn}?$select=id`, but the app lacks `User.Read.All`, so that call returns
+  `403 Authorization_RequestDenied`, which `resolveUserId()` swallows and falls back to the UPN —
+  producing the same 400. Lesson: a "fix" that depends on an ungranted permission and silently
+  falls back will look correct in code review but never work in prod. The group-members approach
+  avoids the `/users` endpoint entirely.
+- `resolveUserId()` still exists for the `organizer_user_ids` fallback path and returns a GUID
+  unchanged (regex match); it is bypassed entirely when the group is configured.
+- Graph meeting/transcript ids are base64 and contain `+ / =` — they must be `rawurlencode()`'d
+  at every Graph call site (`getMeeting`, `downloadTranscriptVtt` fallback URL).
+- `resolveWatermark()` guards against an unparseable stored `dtCreated`: without the guard,
+  `strtotime(...) === false` minus 60 yields a 1969 date and a decades-wide Graph query window.
+- Plaintext `client_secret` lives in `Config/production.ini` `[teams]` — should be rotated /
+  moved to a secret store (out of scope as of this writing).
+
+## Diagnosing a 400
+
+A standalone bash diagnostic (`worker2/diagnose-transcripts.sh`) reproduces the Graph call
+chain step-by-step (token → group members → `getAllTranscripts`) and prints the **full** Graph
+error body that the worker discards (it keeps only `error.message`). It reads creds from the ini
+at runtime and prints none. Useful first stop for any future Graph failure here.
+
+## Change history
+
+- 2026-06-12 — Resolve organizers from the `organizer_group_id` Entra group (object-ids via
+  GroupMember.Read.All) instead of per-UPN lookup; fixes the recurring HTTP 400 that PR #77's
+  `/users` approach couldn't (no User.Read.All). Hardened watermark parsing, URL-encoding, and
+  silent catches. Verified live: 6/6 organizers, 32 transcripts. (ajean)
+
+## Related docs
+
+- [Worker (worker2) Architecture](../architecture.md)
+- [Creating Worker Actions](./creating-worker-actions.md)

package/knowledge/INDEX.md

@@ -6,13 +6,13 @@ _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
 
 - **_underscore** (_Underscore) _(framework core)_ — 5 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 5 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 6 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **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)

package/package.json

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