toga-ai 1.0.71 → 1.0.73

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

@@ -1,8 +1,11 @@
-# togadesk (TogaDesk) — 1.0 knowledge
+# togadesk (TOGa Desk) — 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 |
+| [TOGa Desk Architecture](architecture.md) | TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at `/desk/`). | desk/index.php, desk/includes/loader.php, desk/config.php, desk/includes/controllers/actions.php, desk/includes/controllers/data.php, desk/includes/controllers/modals.php, desk/includes/classes/class.app.php, desk/includes/classes/class.ticket.php, desk/api/index.php, desk/api/resources/tickets.php, crons/tickets.php |
+| [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php |
+| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php |
+| [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.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. |  |
+| [Ticket Lifecycle (class.ticket.php)](features/ticket-lifecycle.md) | All TOGa Desk 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 (TOGa Desk)](workflows/standalone-test-scripts.md) | How to write a standalone CLI PHP script that bootstraps the TOGa Desk framework for read-only testing of desk classes (e.g. |  |

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

@@ -1,38 +1,137 @@
 ---
-title: TogaDesk Architecture
+title: TOGa Desk Architecture
 framework: "1.0"
 repo: togadesk
-project: TogaDesk
+project: TOGa Desk
 client: shared
 type: architecture
 status: active
-updated: 2026-06-12
-owners: ["mhammontree"]
+updated: 2026-06-15
+owners: ["mhammontree", "jcardinal"]
 files:
-  - desk/includes/classes/class.ticket.php
+  - desk/index.php
+  - desk/includes/loader.php
+  - desk/config.php
   - desk/includes/controllers/actions.php
+  - desk/includes/controllers/data.php
+  - desk/includes/controllers/modals.php
+  - desk/includes/classes/class.app.php
+  - desk/includes/classes/class.ticket.php
+  - desk/api/index.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
+  - 1.0/apps/togadesk/features/rest-api.md
+  - 1.0/apps/togadesk/features/field-service-dispatch.md
+  - 1.0/apps/togadesk/features/email-to-ticket-intake.md
+  - 1.0/apps/togadesk/workflows/standalone-test-scripts.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.
+TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at
+`/desk/`). It is a framework 1.0 (`App_`) app bootstrapped from the `library` core (`_.php`).
+Beyond ticketing it covers asset/license/inventory management, repair-order dispatch (depot +
+onsite technicians), a knowledge base, host/service monitoring, RBAC, a REST-ish API, and
+IMAP email intake. 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.
+
+Primary database `db_togadesk` (schema `TOGaDeskSupport`); also `db_common` and per-client
+databases. TOGa Desk shares `TOGaDeskSupport` with **TOGa View** (the client-facing portal,
+sibling repo `togaview`).
+
+## Entry points & request pipeline
+- **Web:** `desk/index.php` → `desk/includes/loader.php`. The repo-root `index.php` / `ajax.php`
+  are thin wrappers around the `desk/` versions.
+- **Bootstrap order** (`loader.php`): local `functions.php` → `config.php` → register the two
+  custom autoloaders `vendorClassAutoload` (`desk/vendor/classes/`) and `appClassAutoload`
+  (`desk/includes/classes/`) → Composer autoload → `require _.php` + `App_Framework_TOGaDesk::initialize()`
+  (starts session with `HttpOnly`/`Secure`, inits Sentry, XSS-protects `$_REQUEST`/`$_GET`/`$_POST`)
+  → `App_Page::validateCrossSiteRequestForgery()` → Medoo `$database` instantiated from config →
+  resolve logged-in user `$liu` via `people.sessionid` → unserialize the user's role `perms`.
+- **`$route`** comes from `$_GET['route']` (defaults to `dashboard`) and is sanitized against
+  path traversal.
+- **Sequential controller pipeline**, each stage gated on a query param:
+  | Stage | Trigger | File | Role |
+  |---|---|---|---|
+  | general | always | `controllers/general.php` | signin / signout / password reset |
+  | modals | `?modal=` | `controllers/modals.php` | assemble modal form data → `template/modals/<modal>.php` |
+  | quickactions | `?qa=` | `controllers/quickactions.php` | small AJAX/JSON/file-stream ops, then `exit` |
+  | actions | `?action=` | `controllers/actions.php` | CRUD; `isAuthorized()` → domain class → status code → `reroute()` |
+  | data | always | `controllers/data.php` | populate page context; route-specific `controllers/data/<route>.php` |
+- **Render** (when no modal/qa): `template/header.php` + `template/pages/<route>.php` + `template/footer.php`.
+- Unmatched `?action=` values fall back to `controllers/actions/<action>.php` — so actions live
+  either inline in `actions.php` or as files under `controllers/actions/<domain>/`.
+
+## Server-rendered UI model
+Classic **page ← data + modal + action** loop:
+1. A page (`template/pages/<route>.php`) instantiates a **DataTable**
+   (`desk/_/browser/datatable/<domain>.php`, extends `Browser_Datatable_TogaDesk`) that builds
+   the grid SQL/joins and renders row action buttons.
+2. A button calls `showM("?modal=<domain>/<action>&id=…")`, which XHR-loads the modal; its modal
+   controller (`controllers/modals/<domain>/<action>.php`) assembles dropdowns/dependent data and
+   the modal template renders a form with hidden `routeid` / `id` / `reroute` fields.
+3. The form POSTs `?action=…` → a domain class static method → a numeric **status code** →
+   `reroute()` redirects back to the originating page. Status codes map to user-facing messages
+   via the `statuscodes` table (`10`=add, `20`=edit, `30`=delete, etc.).
+
+## Domain class layer
+- ~41 thin classes in `desk/includes/classes/class.<name>.php` with **plain names** (`Ticket`,
+  `Asset`, `Repair`, `Client`…), all extending an **empty `App` base** (`class.app.php`) —
+  behavior lives in **static facade methods** (`Ticket::add($data)`), not inheritance or DI.
+- Persistence pairs these with **`App_Model_TogaDesk_*` ORM models** (defined in `library`),
+  instantiated by id (`new App_Model_TogaDesk_Ticket($id)`).
+- **DB access is mixed:** the Medoo global `$database` (`->select/insert/get`) for simple work,
+  and `App_Database::query()` / `App_Database::fetchRow()` for complex SQL. Link names:
+  `db_togadesk` (main), `db_common` (shared: States, carriers, ASN), and per-client databases via
+  `App_Model_Client::changeDbLinkToClientDatabase()`.
+- **Functional groups:**
+  - **Ticketing/support** — `Ticket` (the ~2,200-line core: creation, the `addReply()` status
+    switch, `deriveCustomerId()`, Talos AI, policy tasks), `TicketHistory`, `Comment`,
+    `Resolution`, `Preply`.
+  - **Asset & inventory** — `Asset`, `License`, `Category`, `Attribute`, `CustomField`,
+    `Certificate`, `Credential` (encrypted).
+  - **Repair & dispatch** — `Repair` (depot + onsite work orders), `RepairHistory`.
+  - **Client/contact** — `Client`, `ClientDepartment`, `ClientPortal`, `Contact`.
+  - **Users & RBAC** — `User`/`Staff` (both in `people`, by `type`), `Profile`, `Role`,
+    `ApiKey`, `Policy`. Permissions are stored **serialized** in `roles.perms`.
+  - **Knowledge base** — `Kb` (articles/docs/FAQs; uploads to S3 `asifiles`).
+  - **Projects** — `Project`, `Issue`, `Milestone`. **Monitoring** — `Monitoring`, `Diagnostic`.
+  - **Comms** — `Notification`, `ChatWidget`, `Timelog`. **Data** — `Import`, `File`.
+
+## REST-ish API
+`desk/api/index.php` is an **RPC-over-POST** dispatcher (NOT verb/URL REST): params `key`,
+`method` (get/add/edit/delete/attach/detach), `resource`, `filters`, `data`, `id` route to one
+of ~37 handlers in `desk/api/resources/<resource>.php`. API-key auth resolves a role → perms;
+each op calls `isAuthorizedApi(...)`. Responses use the `{status, status_message, result}`
+envelope. See the **REST API** feature doc.
+
+## Background jobs & integrations
+Crons live at the **repo root** (`crons/`), bootstrapped via the library framework +
+`App_Framework::cronInitialization()`, with per-environment wrappers (`*_prod.php` etc.):
+- `tickets.php` — IMAP **email→ticket** intake from O365 (OAuth2 in prod). See the
+  **email-to-ticket intake** feature doc.
+- `monitoring.php` — `Monitoring::runAll()` host/port checks + up/down alerts.
+- `pipe.php` — postfix stdin push variant; `general.php` — stub.
+
+External integrations: **Talos/TogaIQ** AI (ticket summaries / improved replies), **Syncro**
+PSA status push (when `tickets.referenceId='SYNCRO'`), **S3** (`asifiles`,
+`App_Cloud::copyFileToS3()`), **Sentry** (client-side JS), **PHPMailer** SMTP, and **NetSuite**
+customer id captured on SMB contracts. The `controllers/actions/toga/` and
+`controllers/data/toga/` subsystems bridge to the **TOGA** database (inventory items/levels/orders,
+SMB contracts, customer renewals).
 
 ## 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 |
+| TOGa Desk (`desk/`) | Staff/analysts | `db_togadesk` (TOGaDeskSupport), `db_toga` (TOGA), `db_client_aig`, per-client by name |
+| TOGa View (sibling repo) | Clients at `<client>.togaview.com` | same cluster, same link names |
 
-- **TogaDesk and TogaView share the `TOGaDeskSupport` database** — tickets, clients,
+- **TOGa Desk and TOGa View 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
@@ -78,10 +177,30 @@ Invariants:
   (`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.
+- Field-service dispatch (repair orders, technician scheduling, onsite/depot, tracking) runs
+  through `controllers/actions/central/` + `class.repair.php`. See field-service-dispatch 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
+  staff/API/email tickets are visible in the TOGa View 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.
+
+## Gotchas / known issues
+- `ENVIRONMENT` defaults to `worker` when unset → CLI scripts read the wrong config file.
+- Heavy **hardcoded client-ID branching** in `central` dispatch and `tickets/add` (Walmart,
+  WJE, Compass/ODP, AIG, RUMCSI) — verify the client arm before changing shared logic.
+- **Two `class.ticket.php` files** — only `desk/includes/classes/` is live; the root variant is
+  dead (random ticket numbers, stale schema).
+- The API has **no pagination** — `get` returns full result sets; Medoo `filters` pass straight
+  to the WHERE clause.
+- The prod O365 OAuth secret used by `crons/tickets_prod.php` has a **hard expiry (~2026-12-20)**.
+
+## Related docs
+- [TOGa View architecture](../togaview/architecture.md)
+- [Ticket lifecycle](features/ticket-lifecycle.md)
+- [REST API](features/rest-api.md)
+- [Field-service dispatch (central)](features/field-service-dispatch.md)
+- [Email-to-ticket intake](features/email-to-ticket-intake.md)
+- [SMB contract editing](features/smb-contract-editing.md)

package/knowledge/1.0/apps/togadesk/features/email-to-ticket-intake.md

@@ -0,0 +1,66 @@
+---
+title: Email-to-Ticket Intake (crons/tickets.php)
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: feature
+status: active
+updated: 2026-06-15
+owners: ["jcardinal"]
+files:
+  - crons/tickets.php
+  - crons/tickets_prod.php
+  - crons/pipe.php
+  - desk/includes/classes/class.ticket.php
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+---
+
+## Summary
+TOGa Desk ingests support email into tickets through a cron-driven IMAP poller
+(`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). Both funnel into
+`Ticket::emailToTicket()`, which threads replies onto existing tickets or creates new ones.
+
+## Key files / entry points
+- `crons/tickets.php` — the IMAP poll loop. Per-environment wrappers (`tickets_prod.php`,
+  `tickets_alpha.php`, `tickets_beta.php`) set `$env`/`$processName` and `require` it; the base
+  script refuses to run unwrapped.
+- `crons/pipe.php` — reads a single message from stdin (postfix pipe delivery) and calls the
+  same intake; minimal autoload bootstrap (no full framework include path).
+- `Ticket::emailToTicket()` in `desk/includes/classes/class.ticket.php` — the parser/router.
+
+## How it works
+1. **Bootstrap:** cron wrappers load the `library` framework + `App_Framework::cronInitialization()`,
+   set `$env`, and register the IMAP (`Imap2`) helper. `tickets_prod.php` additionally performs
+   **OAuth2/MSAL** token acquisition for the O365 mailbox.
+2. **Poll:** connect to `outlook.office365.com:993` INBOX and loop for ~22 minutes (header
+   comment suggests running every ~30 min), processing each message then deleting it.
+3. **Parse & route (`emailToTicket()`):** extract from/to/cc/subject/body (with encoding fixes);
+   match an existing ticket via `In-Reply-To` + `Message-ID` headers and **plus-addressing**
+   (`support+<ticketnum>@…`). Matched ⇒ `addReply()`; otherwise ⇒ `add()`.
+4. **Side effects:** auto-create a user when the sender domain maps to an existing client; assign
+   to a department via the department email lookup; save attachments locally then push to **S3**
+   (`App_Cloud::copyFileToS3()`, bucket `asifiles`); optionally generate Talos/TogaIQ summaries.
+5. **Post-pass:** `Ticket::processRules()` (escalation) and `Ticket::autoClose()` (SLA auto-close)
+   run after the mailbox sweep.
+
+## Data model
+Writes `tickets`, `tickets_replies`, attachment `files`; reads config from the `config` table
+(`tickets_defaultdepartment`, `tickets_defaultclient`, `auto_close_tickets`,
+`email_from_address`, `timezone`). Department routing keys on `tickets_departments.email`.
+
+## Gotchas / known issues
+- **`$processName` guard:** `tickets.php` throws if executed directly instead of via an env
+  wrapper — and `ENVIRONMENT`/`$env` must be set or it loads the wrong config.
+- **OAuth2 expiry:** the prod O365 app secret in `tickets_prod.php` has a hard expiry
+  (~2026-12-20); rotate before then or intake silently stops.
+- **Loop prevention** only excludes FROM==department-TO addresses; CC/reply-all across multiple
+  department addresses can still loop.
+- **Auto-reply filters** are partly hardcoded (e.g. ignore `TechHub@compass-usa.com`
+  "Automatic reply:" messages).
+- Attachments are deleted locally immediately after the S3 upload with **no retry** if S3 fails.
+
+## Change history
+- 2026-06-15 — documented from a source read of `crons/tickets*.php` and `emailToTicket()` (jcardinal)

package/knowledge/1.0/apps/togadesk/features/field-service-dispatch.md

@@ -0,0 +1,76 @@
+---
+title: Field-Service Dispatch (central / repair orders)
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: feature
+status: active
+updated: 2026-06-15
+owners: ["jcardinal"]
+files:
+  - desk/includes/controllers/actions/central/
+  - desk/includes/classes/class.repair.php
+  - desk/includes/classes/class.repairhistory.php
+  - desk/_/browser/datatable/central.php
+  - desk/template/pages/central.php
+  - desk/template/pages/central/view.php
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+---
+
+## Summary
+The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle,
+technician scheduling, onsite vs depot service, parts, and shipment tracking. It is the largest
+action domain (~23 files under `controllers/actions/central/`) and is heavily client-aware.
+
+## Key files / entry points
+- Action controllers: `desk/includes/controllers/actions/central/*.php` — repair-order create
+  /clone, status transitions (`awaitingDispatch.php`, `awaitingDiagnostic.php`,
+  `installStarted.php`, `reviewInstallation.php`, `reworkAwaitingScheduling.php`), technician
+  assignment & scheduling (`assignTechnicians.php`, `scheduleDispatch.php`, `setSchedule.php`),
+  onsite state (`technicianEnRoute.php`, `technicianOnsite.php`), parts/tracking
+  (`part.php`, `addTracking.php`, `voidshipment.php`), and bulk ops
+  (`bulkCloseInstallTickets.php`, `bulkEditOnsiteServiceTickets.php`).
+- Domain class: `desk/includes/classes/class.repair.php` (`Repair`) with the
+  `App_Model_TogaDesk_RepairOrder` / `RepairOrderCustomer` / `RepairOrderAddress` models.
+- Grid: `desk/_/browser/datatable/central.php` — joins `repair_orders`
+  + `repair_order_customers` + `ServiceRequests` + departments, renders status badges and the
+  per-row action buttons that open the central modals.
+- Pages: `desk/template/pages/central.php` (list) and `central/view.php` (detail).
+
+## How it works
+A page renders the central DataTable; row buttons `showM("?modal=central/<action>&id=…")` open a
+modal whose controller (`controllers/modals/central/<action>.php`) assembles technicians,
+contracts, vendor POs, schedule data, etc. The modal form POSTs `?action=<central action>`,
+which resolves to the inline `actions.php` switch or to
+`controllers/actions/central/<action>.php`, mutates `repair_orders` / `repair_order_technicians`
+and calls `Repair`/`RepairOrder::updateStatus()` to recompute state, then `reroute()`s back to
+the originating page. Status changes are audited through `RepairHistory` (`repair_history`).
+
+**State model (typical):** awaiting diagnostic → awaiting dispatch → scheduled → en-route →
+onsite/install started → review → closed; depot repairs add parts/tracking steps. Bulk actions
+exist for closing installs and editing onsite tickets.
+
+## Data model
+`repair_orders`, `repair_order_customers`, `repair_order_addresses`, `repair_order_technicians`,
+`repair_history` (in `db_togadesk`), joined to TOGA `ServiceRequests` for managed-service-order
+context. One repair order generally maps to one serviced unit.
+
+## Client variations
+Dispatch flows branch on hardcoded client ids (e.g. Walmart / Walmart Plus, WJE, Office
+Depot / Compass, AIG, RUMCSI) for department mapping, scheduling rules, and notification copy —
+always confirm the client arm before changing shared central logic.
+
+## Gotchas / known issues
+- Actions are split across two locations: the inline `actions.php` switch **and**
+  `controllers/actions/central/*.php` (the default fallback). Check both when tracing an action.
+- Status recomputation is centralized in `updateStatus()` — write paths that bypass it can leave
+  an order in an inconsistent state.
+- Cross-database context: some central data controllers switch the DB link to a client database
+  (`App_Model_Client::changeDbLinkToClientDatabase()`).
+
+## Change history
+- 2026-06-15 — documented from a source read of `controllers/actions/central/` and
+  `class.repair.php` (jcardinal)

package/knowledge/1.0/apps/togadesk/features/rest-api.md

@@ -0,0 +1,87 @@
+---
+title: REST API (RPC-over-POST) & API-Key Auth
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: feature
+status: active
+updated: 2026-06-15
+owners: ["jcardinal"]
+files:
+  - desk/api/index.php
+  - desk/api/resources/tickets.php
+  - desk/api/resources/assets.php
+  - desk/api/resources/authenticate.php
+  - desk/includes/classes/class.apikey.php
+  - desk/includes/functions.php
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+---
+
+## Summary
+TOGa Desk exposes a programmatic API at `desk/api/`. Despite the name it is **not** verb/URL
+REST — it is an **RPC-over-POST** dispatcher: every request is a POST to `desk/api/index.php`
+carrying a `resource` and a `method` in the body. ~37 resource handlers under
+`desk/api/resources/` delegate to the same domain classes the web UI uses.
+
+## Key files / entry points
+- `desk/api/index.php` — the single entry point: authenticates, validates the request shape,
+  and `include`s the matching `resources/<resource>.php` (handlers run in index.php scope).
+- `desk/api/resources/*.php` — one file per resource (`tickets`, `ticket_replies`,
+  `ticket_departments`, `assets`, `asset_categories`, `clients`, `contacts`, `credentials`,
+  `licenses`, `users`, `staff`, `roles`, `kb_articles`, `monitoring_hosts`,
+  `monitoring_checks`, `time_log`, `files`, `qrcodes`, lookup/reference resources, etc.).
+- `desk/includes/classes/class.apikey.php` — API key generation/storage.
+- `isAuthorizedApi()` and `signInApi()` in `desk/includes/functions.php`.
+
+## How it works
+**Request (POST to `desk/api/index.php`):**
+- `key` — the API secret (required).
+- `method` — one of `get | add | edit | delete | attach | detach`.
+- `resource` — e.g. `tickets`, `assets`, `users`.
+- `filters` — array, for `get` (passed to Medoo as the WHERE clause).
+- `data` — array, for `add`/`edit`/`attach`/`detach`.
+- `id` — string, for `delete`/`detach`.
+
+**Auth & authorization:**
+1. `index.php` looks up `api_keys` by `secretkey`; invalid ⇒ status `903`.
+2. The key's `roleid` loads `roles.perms` (unserialized PHP array).
+3. Each handler calls `isAuthorizedApi("<permission>")` (e.g. `viewTickets`, `addAsset`,
+   `manageSettings`); missing permission ⇒ status `905` + `exit`.
+4. `resources/authenticate.php` is a **separate** path: user/password login via `signInApi()`
+   (not API-key auth).
+
+**Response envelope (always JSON):**
+```json
+{ "status": 1, "status_message": "Success!...", "result": [ ... ] }
+```
+Handlers post-process rows: serialized fields (`tickets.ccs`, `roles.perms`) are unserialized
+and encrypted fields (license `serial`) are decrypted before returning.
+
+**Status codes:** `1` success, `2` generic error; `901` unknown, `902` key missing, `903` auth
+failed, `904` resource not found, `905` not authorized, `906` method not found, `907` method not
+allowed for resource, `908–912` malformed `filters`/`data`/`id`. Domain-class return codes
+(`10` add / `20` edit / `30` delete) are mapped to `1`/`2` in the handler.
+
+**Delegation:** handlers call the same static facades as the UI — e.g. `tickets.php` →
+`Ticket::add()/edit()/delete()`, `ticket_replies.php` → `Ticket::addReply()` (add-only),
+`files.php` → `File::upload($data, $_FILES)`, `qrcodes.php` uses `attach`/`detach`. For `get`,
+many resources query Medoo directly (`$database->select(...)`).
+
+## Data model
+Backed by the same `db_togadesk` (`TOGaDeskSupport`) tables as the UI, plus `api_keys`
+(`name`, `secretkey`, `roleid`) and `roles` (`perms` serialized).
+
+## Gotchas / known issues
+- **No pagination.** `get` returns the full result set; large tables (tickets, assets) can be
+  expensive. `filters` is passed straight into the Medoo WHERE clause.
+- **RPC, not REST.** Clients send `method`/`resource` in the POST body — there are no per-verb
+  HTTP semantics and no `/api/tickets/123` URLs.
+- **Per-resource permission strings** must exist in the API key's role `perms`, or every call
+  returns `905`.
+- Minimal request validation in `index.php`; real validation lives in the domain classes.
+
+## Change history
+- 2026-06-15 — documented from a full source read of `desk/api/` (jcardinal)

package/knowledge/1.0/apps/togadesk/features/smb-contract-editing.md

@@ -2,7 +2,7 @@
 title: SMB Contract Editing & the clientMspId Corruption Trap
 framework: "1.0"
 repo: togadesk
-project: TogaDesk
+project: TOGa Desk
 client: shared
 type: feature
 status: active
@@ -22,7 +22,7 @@ related:
 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.
+portal users seeing "You have no assigned clients" in TOGa View. Fixed June 2026.
 
 ## Key files / entry points
 - Modal template: `desk/template/modals/toga/smbcontracts/smbContract.php`
@@ -40,7 +40,7 @@ The bug pattern (now guarded against):
 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
+3. TOGa View msp_dashboard's `SMBContracts WHERE clientMspId = <session clientMspId>` then
    matched nothing for the real MSP's users.
 
 Fixes in place (June 2026):
@@ -80,11 +80,11 @@ 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).
+  never build department logic on it (see TOGa View 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)
+- [TOGa View MSP dashboard](../../togaview/features/msp-dashboard.md)

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

@@ -2,7 +2,7 @@
 title: Ticket Lifecycle (class.ticket.php)
 framework: "1.0"
 repo: togadesk
-project: TogaDesk
+project: TOGa Desk
 client: shared
 type: feature
 status: active
@@ -20,7 +20,7 @@ related:
 ---
 
 ## Summary
-All TogaDesk ticket creation and reply handling funnels through `Ticket` in
+All TOGa Desk 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.
@@ -99,4 +99,4 @@ backfill (e.g. craftex:
 
 ## Related docs
 - [SMB contract editing](smb-contract-editing.md)
-- [TogaView MSP dashboard](../../togaview/features/msp-dashboard.md)
+- [TOGa View MSP dashboard](../../togaview/features/msp-dashboard.md)

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

@@ -1,8 +1,8 @@
 ---
-title: Standalone PHP Test Script Bootstrap (TogaDesk)
+title: Standalone PHP Test Script Bootstrap (TOGa Desk)
 framework: "1.0"
 repo: togadesk
-project: TogaDesk
+project: TOGa Desk
 client: shared
 type: workflow
 status: active
@@ -14,7 +14,7 @@ related:
 ---
 
 ## Summary
-How to write a standalone CLI PHP script that bootstraps the TogaDesk framework for
+How to write a standalone CLI PHP script that bootstraps the TOGa Desk 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).

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

@@ -1,8 +1,9 @@
-# togaview (TogaView) — 1.0 knowledge
+# togaview (TOGa View) — 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 |
+| [TOGa View Architecture](architecture.md) | TOGa View is the client-facing support portal, served per client at `<client>.togaview.com`. | index.php, reset.php, _/app/framework.php, _/app/frameworkindex.php, _/browser/pagination.php, mvc/login/post.php, mvc/ticket/get.php |
+| [TOGa View 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 TOGa View client portal: different pages scope tickets **differently**, and the MSP pages depend on `tickets.customerid` and `SMB | common/togaview/msp_dashboard.php, mvc/msp_client_dashboard, mvc/enterprise_dashboard, mvc/support/support.php |
+| [Retail Commerce Lifecycle (winback, purchase, claims, activation)](features/retail-commerce-lifecycle.md) | Beyond support, TOGa View hosts the **retail tech-support commerce flows**: subscription purchase/renewal (with payment), service activation, and insurance-styl | mvc/winback_landing/get.php, mvc/winback_payment/get.php, mvc/winback_payment/post.php, mvc/purchase/get.php, mvc/service_activation/get.php, mvc/claims/get.php, mvc/techsupport_app/get.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

@@ -1,37 +1,60 @@
 ---
-title: TogaView Architecture
+title: TOGa View Architecture
 framework: "1.0"
 repo: togaview
-project: TogaView
+project: TOGa View
 client: shared
 type: architecture
 status: active
-updated: 2026-06-12
-owners: ["mhammontree"]
+updated: 2026-06-15
+owners: ["mhammontree", "jcardinal"]
 files:
   - index.php
+  - reset.php
   - _/app/framework.php
+  - _/app/frameworkindex.php
+  - _/browser/pagination.php
   - mvc/login/post.php
+  - mvc/ticket/get.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
+  - 1.0/apps/togaview/features/retail-commerce-lifecycle.md
 ---
 
 ## Summary
-TogaView is the client-facing support portal, served per client at `<client>.togaview.com`.
+TOGa View 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;
+`TOGaDeskSupport` database with TOGa Desk (tickets, clients, contacts, departments, ClientMsp)
+— see the TOGa Desk architecture doc for the cluster topology and the full MSP data model;
 those invariants apply here unchanged.
 
+Architecturally it is a **multi-tenant, single-codebase MVC portal**: one deploy serves every
+client, and `$_SERVER['HTTP_HOST']` selects a per-client *stylePath* (templates/branding) at
+bootstrap. Pages are procedural `mvc/<page>/{get,post}.php` scripts; most clients render the
+generic `common/togaview/*.php` templates, while a handful have full per-client overrides.
+
+## Entry points & bootstrap
+- **Entry:** `index.php` → `require _.php` (autoloader from `library`) →
+  `App_Framework_TogaView::initialize()` → `renderIndex()` (in `_/app/framework.php`).
+  `reset.php` is a small session-clear utility.
+- **`initialize()`** (extends `App_Framework`): resolves `ENVIRONMENT` (defaults `worker`),
+  loads `config.<env>.ini` via `App_Config`, registers DB links (`db_togadesk` →
+  `[database_togadesk]`, plus `db_toga`, `db_retail`, `db_log`, per-client), XSS-protects
+  superglobals, starts the session (`HttpOnly`/`Secure`), inits Sentry, and registers the
+  NetSuite toolkit + SAML.
+- **`frameworkindex.php`** is the page-shell renderer (CSS/JS registration, page title).
+  **`framework_DOA.php`** is a near-duplicate variant of `framework.php`.
+
 ## 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`).
+   The default stylePath is `true`.
 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`;
@@ -44,6 +67,24 @@ those invariants apply here unchanged.
 **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.
 
+## MVC request lifecycle
+- `App_MVC::parseRoute()` (in `library`) turns the request URI into route parts and resolves
+  `mvc/<route…>/<method>.php`, where `<method>` is `get` or `post` (from the HTTP verb,
+  overridable via a `_method` POST param). It matches longest-to-shortest, so overlapping
+  paths can surprise — keep route folders distinct.
+- **GET** (`get.php`) selects a template via the fallback chain above and passes data to it
+  (no central master-layout system — each `common/<…>/<page>.php` is self-contained).
+- **POST** (`post.php`) reads input with `App_Page::getVar()/getVarIfSet()`, does the work,
+  then `header("Location: …"); exit;`. Login/auth, ticket creation, user management live here.
+- AJAX requests dispatch through `App_Framework::ajaxHandler()`; `?fileId=` downloads route
+  through `App_MVC::loadFile()`. `mvc/_TEMPLATE/` is the scaffold for new pages.
+
+## Browser subsystem (grids & modals)
+`_/browser/`: `Browser_Datatable_*` classes (`initialize()` registers fields/joins/DB link via
+`setDatabaseLinkString()` / `setTableJoins()`, `Browser_DataTableField` for cell rendering),
+`Browser_Modal_*` classes (capture HTML via `App_Page::startCapture()/stopCapture()`, e.g.
+`Browser_Modal_CreateNewTicket`, `CreatenewUser`), and `Browser_Pagination_TogaView`.
+
 ## 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`
@@ -52,12 +93,49 @@ staplesprotection sets `$_SESSION['email']` (not `emailAddress`) and no `togades
 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
+**SAML** (rumcsi, towfoundation, newcenturyholdingsllc) is handled in `framework.php`
+(`meta`/`acs`/`sls`); newcenturyholdingsllc and towfoundation **auto-create `people` rows** for
+unknown SAML users. rumcsi additionally accepts a legacy `?hash=<base64 email>` auto-login.
+
+## Dashboards
+Five dashboards, one per audience/business model, each delegating to a client override or the
+generic template:
+- **retail_dashboard** — retail warranty/subscription end users (Walmart+, ODP): profile,
+  software locker, support app download, service activation status.
+- **msp_dashboard** — MSP admins managing many SMB customers: per-customer ticket metrics,
+  seat/contract capacity, Excel/Charts export (see msp-dashboard feature doc).
+- **msp_client_dashboard** — end users under an MSP-managed SMB contract: seat capacity, add-user
+  (disabled when oversubscribed), resend welcome.
+- **enterprise_dashboard** — enterprise/insurance clients (rumcsi, staplesprotection,
+  towfoundation): client-specific logic incl. claims and asset tracking.
+- **wb2b_dashboard** — Walmart B2B (hardcoded `TOGA_WalmartB2B`, clientId 13): managed services
+  + activation status.
+
+## Self-service identity lifecycle
+`signup` / `register` / `activate` (retail, token + encrypted `clientAccountId` link, password
+policy), `forgot_password` / `reset_password`, and the MSP/enterprise side: `create_account`,
+`manage_users`, `msp_user`, `user_account`, `activation_admin` (WalmartBusiness bulk admin
+creation). Models: `App_Model_RetailServices_ClientAccount`, `App_Model_Toga_Contact`,
+`App_Model_Customer`.
+
+## Knowledge / content surface
+Read-only client-facing KB sourced from TOGa Desk's `db_togadesk` KB tables, gated behind
+`$_SESSION['togadeskClientId']`: `article` / `article_list` (`kb_articles`), `faq` / `faq_list`
+(`kb_faqs`), `doc` / `doc_list` (`kb_documents`, file download via `?fileId=`).
+
+## Support / ticketing
+`support` (ticket hub + `Browser_Modal_CreateNewTicket`), `ticket` (detail; ownership-checked —
+see ticket-detail-page feature doc), `task_list` (`issues`), and `service_desk` (Walmart B2B
+service activation against `db_toga` `ServiceRequests`). The MSP portal depends on
+`tickets.customerid` being populated (TOGA `Customers.id`), which TOGa Desk's
 `Ticket::deriveCustomerId()` now sets at creation.
 
+## Commerce / retail lifecycle
+`winback_landing` → `winback_payment` → `winback_activating` (ODP renewal), `purchase` /
+`purchase_service`, `service_activation`, `claims` (Staples Protection / AIG), and
+`techsupport_app` (Optimum Desk app download). Payment via **Braintree**. See the
+retail-commerce-lifecycle feature doc.
+
 ## 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
@@ -65,3 +143,22 @@ depends on `tickets.customerid` being populated (TOGA `Customers.id`), which Tog
   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`.
+
+## Gotchas / known issues
+- **Template fallback is per-page, not central.** Each `get.php` re-implements the
+  host→stylePath→togaview chain; it's easy to miss a host-specific branch.
+- **`common/togaview/*` is the blast radius** — editing a generic page changes nearly every
+  client at once.
+- **Divergent session shapes** across login flows (see Session model) — always use the
+  `emailAddress`/`email` fallback and tolerate a missing `togadeskClientId`.
+- **Hardcoded Braintree credentials (including a private key) are committed under
+  `mvc/winback_payment/`** — these should be rotated and moved to `config.<env>.ini`
+  secret management. Flagged 2026-06-15; not yet remediated.
+- `ENVIRONMENT` defaults to `worker` when unset → wrong config file.
+
+## Related docs
+- [TOGa Desk architecture](../togadesk/architecture.md)
+- [Login flows & session variables](features/login-flows.md)
+- [MSP dashboard & ticket visibility](features/msp-dashboard.md)
+- [Ticket detail page security](features/ticket-detail-page.md)
+- [Retail commerce lifecycle](features/retail-commerce-lifecycle.md)

package/knowledge/1.0/apps/togaview/features/login-flows.md

@@ -1,8 +1,8 @@
 ---
-title: TogaView Login Flows & Session Variables
+title: TOGa View Login Flows & Session Variables
 framework: "1.0"
 repo: togaview
-project: TogaView
+project: TOGa View
 client: shared
 type: feature
 status: active

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

@@ -2,7 +2,7 @@
 title: MSP Dashboard & Ticket Visibility Rules
 framework: "1.0"
 repo: togaview
-project: TogaView
+project: TOGa View
 client: shared
 type: feature
 status: active
@@ -20,7 +20,7 @@ related:
 ---
 
 ## Summary
-Why tickets "disappear" in the TogaView client portal: different pages scope tickets
+Why tickets "disappear" in the TOGa View 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.
 
@@ -80,5 +80,5 @@ category resolution).
 
 ## Related docs
 - [Login flows](login-flows.md)
-- [TogaDesk ticket lifecycle](../../togadesk/features/ticket-lifecycle.md)
+- [TOGa Desk ticket lifecycle](../../togadesk/features/ticket-lifecycle.md)
 - [SMB contract editing](../../togadesk/features/smb-contract-editing.md)

package/knowledge/1.0/apps/togaview/features/retail-commerce-lifecycle.md

@@ -0,0 +1,75 @@
+---
+title: Retail Commerce Lifecycle (winback, purchase, claims, activation)
+framework: "1.0"
+repo: togaview
+project: TOGa View
+client: shared
+type: feature
+status: active
+updated: 2026-06-15
+owners: ["jcardinal"]
+files:
+  - mvc/winback_landing/get.php
+  - mvc/winback_payment/get.php
+  - mvc/winback_payment/post.php
+  - mvc/purchase/get.php
+  - mvc/service_activation/get.php
+  - mvc/claims/get.php
+  - mvc/techsupport_app/get.php
+related:
+  - 1.0/apps/togaview/architecture.md
+  - 1.0/apps/togaview/features/login-flows.md
+---
+
+## Summary
+Beyond support, TOGa View hosts the **retail tech-support commerce flows**: subscription
+purchase/renewal (with payment), service activation, and insurance-style claims. These are
+client-specific surfaces (chiefly ODP/Office Depot, Walmart B2B, and Staples Protection/AIG)
+that mostly bypass the generic dashboards.
+
+## Key files / entry points
+- **Winback (renewal):** `mvc/winback_landing/get.php` → `mvc/winback_payment/get.php` +
+  `post.php` → `mvc/winback_activating/`. ODP tech-support renewal (1-year subscription).
+  Returning customers arrive via an encrypted email link.
+- **Purchase:** `mvc/purchase/get.php` (routes to `mvc/purchase/pts/`) and
+  `mvc/purchase_service/` — subscription purchase.
+- **Service activation:** `mvc/service_activation/get.php` — finalizes remote/on-site service
+  against `TOGA_WalmartB2B`; surfaces the desktop support app download and per-`SMBContract`
+  support phone.
+- **Claims:** `mvc/claims/get.php` — Staples Protection Plan (AIG) claim submission; looks up
+  asset serial / contract, auto-creates a ticket + asset when not found, routes printer vs.
+  general equipment.
+- **techsupport_app:** `mvc/techsupport_app/get.php` — Optimum Desk (`dws.optimumdesk.com`)
+  download link, service type via query params.
+
+## How it works
+The winback flow validates the customer (new vs. returning via encrypted `clientAccountId`),
+collects a Braintree payment nonce, runs the transaction, and on success writes the TOGA
+`Customer` / `Contact` / `ClientAccountService` records that grant the subscription. Claims and
+service-activation flows read/write the relevant per-client TOGA database and create TOGa Desk
+tickets/assets as needed. All are reached as standalone `mvc/` pages, not via a dashboard tab.
+
+## Data model
+- Retail: `App_Model_RetailServices_ClientAccount`, `ClientAccountService` (`db_retail`).
+- TOGA-side: `Customers`, `Contacts`, `SMBContracts`/`SMBContractItems`, `ServiceRequests`
+  (per-client `TOGA_*` / `TOGA_WalmartB2B`).
+- Claims also touch `db_togadesk` `assets` / `tickets`.
+
+## External integrations
+- **Braintree** payment gateway (`assets/braintree/` and `assets/braintree_latest_version/`),
+  used by `mvc/winback_payment/`. Two SDK copies are vendored.
+- **Optimum Desk** remote-support app download links.
+
+## Gotchas / known issues
+- **SECURITY — hardcoded payment credentials:** Braintree merchant/public/**private** keys are
+  committed directly in `mvc/winback_payment/get.php` rather than read from config. Treat the
+  committed keys as compromised: rotate them and move all three into `config.<env>.ini`
+  (`[external]`/secret section). Flagged 2026-06-15; not yet remediated.
+- **Two vendored Braintree SDKs** (`assets/braintree/` vs `assets/braintree_latest_version/`) —
+  confirm which the live flow includes before upgrading.
+- Encrypted email-link parameters (`clientAccountId`) gate returning-customer flows — a bad/old
+  link silently falls back to the new-customer path.
+
+## Change history
+- 2026-06-15 — documented from a source read of the `mvc/` commerce pages; flagged the
+  committed Braintree credentials for rotation (jcardinal)

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

@@ -2,7 +2,7 @@
 title: Ticket Detail Page Security (common/togaview/ticket.php)
 framework: "1.0"
 repo: togaview
-project: TogaView
+project: TOGa View
 client: shared
 type: feature
 status: active

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) — 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)
+- **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
+- **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/clients/compass-usa/INDEX.md

@@ -3,7 +3,7 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql |
-| [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql |
+| [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

package/knowledge/clients/compass-usa/features/item-fulfillment-tracking-tableview.md

@@ -5,11 +5,12 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-11
+updated: 2026-06-15
 owners: ["jcardinal"]
 files:
   - dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql
   - dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql
+  - dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql
 related:
   - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
 ---
@@ -35,8 +36,9 @@ Both views are re-rooted at **`ItemFulfillmentItems` (record 29)** so every fulf
 with the unit/tracking chain made **OUTER** so missing units no longer drop rows.
 
 **View 13 — `item-fulfillments-for-sales-order-items`:**
-- INNER `SalesOrderItems`; OUTER `ItemFulfillmentItemUnits` → OUTER `Units` → OUTER
-  `ItemFulfillmentItemUnits_TrackingNumbers` (record 319) → OUTER `TrackingNumbers` → OUTER `ShippingCarriers`.
+- INNER `SalesOrderItems`; OUTER `ItemFulfillmentItemUnits` → OUTER `Units` (kept for Serial #
+  / Asset Tag columns); OUTER `ItemFulfillmentItems_TrackingNumbers` (record **318**) joined
+  directly onto `ItemFulfillmentItems` → OUTER `TrackingNumbers` → OUTER `ShippingCarriers`.
 - Columns: **Sales Order Line Number, Quantity Fulfilled (`ItemFulfillmentItems.quantity`),
   Outbound Tracking #, Carrier, Serial #, Asset Tag.**
 
@@ -48,14 +50,19 @@ with the unit/tracking chain made **OUTER** so missing units no longer drop rows
 - Default sort re-pointed to the line-number field.
 
 Stable Core ids used: records 29 IFI, 30 IFIU, 31 Units, 15 SalesOrderItems, 14 SalesOrders,
-28 ItemFulfillments, 21 Items, 319 IFIU-tracking bridge, 62 TrackingNumbers, 9 ShippingCarriers.
+28 ItemFulfillments, 21 Items, **318 IFI-tracking bridge** (item-level), 62 TrackingNumbers,
+9 ShippingCarriers. (Record 319, the IFIU/unit-level bridge, is no longer used for tracking —
+see Change history 2026-06-15.)
 
 ## Data model
 
 Join keys (RecordField ids): 60 SOI.id / 368 IFI.salesOrderItemId; 360 IF.id / 367 IFI.itemFulfillmentId;
 59 SO.id / 254 SOI.salesOrderId; 105 Item.id / 66 SOI.itemId; 374 IFIU.itemFulfillmentItemId / 365 IFI.id;
-236 Unit.id / 375 IFIU.unitId; 2183 bridge.itemFulfillmentItemUnitId / 372 IFIU.id;
-336 TN.id / 2184 bridge.trackingNumberId; 21 SC.id / 613 TN.shippingCarrierId.
+236 Unit.id / 375 IFIU.unitId; **2178 IFI-bridge.itemFulfillmentItemId / 365 IFI.id**;
+336 TN.id / **2179 IFI-bridge.trackingNumberId**; 21 SC.id / 613 TN.shippingCarrierId.
+(Record 318 fields: 2176 id, 2178 itemFulfillmentItemId, 2179 trackingNumberId, 2180
+returnTrackingNumberId. Superseded unit-level keys: 2183 IFIU-bridge.itemFulfillmentItemUnitId
+/ 372 IFIU.id; 2184 IFIU-bridge.trackingNumberId.)
 
 ## Gotchas / known issues
 
@@ -64,9 +71,22 @@ Join keys (RecordField ids): 60 SOI.id / 368 IFI.salesOrderItemId; 360 IF.id / 3
   ItemFulfillmentItemUnits / 0 Units** → view 12 showed "0 records" while the re-rooted sibling
   view 13 showed the items fine. Fix is structural (re-root + OUTER chain), independent of the
   missing-unit data issue.
-- Tracking is sourced through the bridge join (`ItemFulfillmentItemUnits_TrackingNumbers.trackingNumberId`),
-  NOT the dropped `ItemFulfillmentItemUnits.trackingNumberId` column. The bridge record/fields
-  (319 / 2183 / 2184) come from the Core migration and must exist before these files run.
+- **Tracking must be sourced at the ITEM level** via `ItemFulfillmentItems_TrackingNumbers`
+  (record 318), joined directly onto `ItemFulfillmentItems` (rec 29). The original re-root
+  (2026-06-10/11) left tracking on the **unit-level** bridge `ItemFulfillmentItemUnits_TrackingNumbers`
+  (record 319), which is empty for **non-serialized** lines (no `ItemFulfillmentItemUnits` rows) →
+  the OUTER join yielded NULL and the tracking column rendered blank even though the data was
+  correct. Symptom: SO **MR243437** (id 105730) showed tracking at the order level but not the
+  item level; item 266006 had 0 unit rows but a valid `ItemFulfillmentItems_TrackingNumbers` row
+  (→ TN 67248). Fixed 2026-06-15.
+- **Compass imports exactly one tracking number per item fulfillment** (NetSuite does not support
+  multiple tracking numbers at the unit level; a different tracking number arrives as a separate
+  item fulfillment). So the item-level bridge (318) is always the complete source and re-pointing
+  away from the unit-level bridge (319) loses nothing.
+- Re-pointing the bridge is **not** a one-column swap: records 318 and 319 have different
+  `RecordFields` ids, so `joinRecordId` (319→318), `joinOnRecordFieldId` (2183→2178),
+  `parentRecordFieldId` (372→365), and the downstream `TrackingNumbers` join's parent field
+  (2184→2179) all change in lockstep.
 - `TableViews.sortPrimaryTableViewFieldId` is a FK to `TableViewFields`; set it NULL before deleting
   the old fields, then re-point via a multi-table UPDATE (not a self-subquery) to avoid MySQL 1093.
 - `TableViewFields` must be deleted before `TableViewJoins` (`tableViewJoinId` FK).
@@ -78,6 +98,7 @@ Join keys (RecordField ids): 60 SOI.id / 368 IFI.salesOrderItemId; 360 IF.id / 3
 Compass-only. The underlying bridge model is shared (see the _underscore feature doc).
 
 ## Change history
+- 2026-06-15 — Re-pointed tracking from the unit-level bridge (319) to the item-level bridge `ItemFulfillmentItems_TrackingNumbers` (318) in views 12 & 13; fixes blank item-level tracking on non-serialized lines (e.g. SO MR243437). Migration `2026-06-15a`. (jcardinal)
 - 2026-06-11 — Re-rooted `item-fulfillments-for-sales-orders` (id 12) from Units to ItemFulfillmentItems with OUTER unit/tracking chain; fixes 0-records on orders lacking unit breakdown (e.g. SA132740). (jcardinal)
 - 2026-06-10 — Re-rooted `item-fulfillments-for-sales-order-items` (id 13) and moved tracking to the bridge join. (jcardinal)
 

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -38,7 +38,7 @@ related:
 ## Summary
 
 The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into
-local tables, turns vendor shipment notices into NetSuite Sales Orders and TogaDesk
+local tables, turns vendor shipment notices into NetSuite Sales Orders and TOGa Desk
 installation repair orders (the **ASN pipeline** — the heart of the integration), and pushes
 ticket state / ETA / proof-of-delivery back to ServiceNow. A parallel EDI surface exchanges
 850 POs and invoices over DOE's SFTP.
@@ -57,7 +57,7 @@ ticket state / ETA / proof-of-delivery back to ServiceNow. A parallel EDI surfac
 | `NYCDOELocations` | Site-id → address mirror (backs ASN ship-to resolution) |
 | `AdvanceShippingNoticeQueue` | Stage-1 landing zone; **UNIQUE index `idx_dedupeKey`** |
 | `AdvanceShippingNotices` / `…Items` / `…Units` | ASN header (vendor+PO) → per-part items (`qtyOrder`) → individual units |
-| `managed_service_orders`, `repair_orders` (`db_togadesk`) | TogaDesk-side fulfillment (one MSO per ASN; `nycDoeTicketId` links back to the RITM) |
+| `managed_service_orders`, `repair_orders` (`db_togadesk`) | TOGa Desk-side fulfillment (one MSO per ASN; `nycDoeTicketId` links back to the RITM) |
 
 ## Integration surfaces (live schedule)
 
@@ -66,11 +66,11 @@ ticket state / ETA / proof-of-delivery back to ServiceNow. A parallel EDI surfac
 | Incidents in | `import_inc.php` (500/batch into `NYCDOETickets`) | every 15 min |
 | RITMs in (ASN Stage 1a) | `import_asn.php` via `App_Api_NYCDOEV2::listRequestItems(500)` | every 15 min |
 | Vendor SFTP in (ASN Stage 1b) | `legacy_import_asn.php` — "Will NOT be turned off" | every 5 min |
-| Incident → TogaDesk ticket | `process_tickets.php` (client 16; throws if >200 unprocessed — flood valve) | every 15 min |
+| Incident → TOGa Desk ticket | `process_tickets.php` (client 16; throws if >200 unprocessed — flood valve) | every 15 min |
 | Queue → ASN records (Stage 2) | `legacy_process_asn_queue.php` | every 15 min |
 | NetSuite SO create (Stage 3, **freeze**) | `1_send_asn_to_netsuite.php` | every 2 h at :07 |
 | NetSuite PO/serials (Stage 4) | `2_send_serials_to_netsuite.php` | every 2 h at :27 |
-| TogaDesk repair orders (Stage 5) | `3_create_installation_ticket.php` | every 5 min |
+| TOGa Desk repair orders (Stage 5) | `3_create_installation_ticket.php` | every 5 min |
 | NetSuite Item Fulfillment (Stage 6) | `4_create_ns_item_fulfillment.php` (**paused**, `active: 0`); `5_DOA_…` unscheduled | not running |
 | ETA → ServiceNow | `send_ticket_updates.php` | every 6 min |
 | RITM state → ServiceNow | `send_request_item_updates.php` | every 5 min |
@@ -98,11 +98,11 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
           │                        │                    │
           │             1_send_asn_to_netsuite.php      3_create_installation_ticket.php
           │                        ▼                    ▼
-          │             NetSuite Sales Order        TogaDesk repair orders (1 per Unit)
+          │             NetSuite Sales Order        TOGa Desk repair orders (1 per Unit)
           │             ★ FREEZE qtyOrder ★
           │                        │
           ▼             2_send_serials_to_netsuite.php
-   TogaDesk "Receiving Summary" → "#received / #ordered" (denominator = SUM(qtyOrder))
+   TOGa Desk "Receiving Summary" → "#received / #ordered" (denominator = SUM(qtyOrder))
 ```
 
 - **Stage 1a (API):** vendor detected by string match on `u_asset_mfg` (apple=1, acer=2,
@@ -128,8 +128,8 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 - **Stage 4:** reconciles the NetSuite **PO** (`netSuiteInternalPurchaseOrderId` — not the
   SO id) and sends serial inventory assignments.
 - **Stage 5:** for units `WHERE togadeskRepairOrderId IS NULL`, reads serials from NetSuite
-  item receipts (so TogaDesk RO serials are **driven by NetSuite**, not the ASN unit),
-  creates/reuses TogaDesk manufacturers/models/assets/serial-numbers/MSO and creates **a
+  item receipts (so TOGa Desk RO serials are **driven by NetSuite**, not the ASN unit),
+  creates/reuses TOGa Desk manufacturers/models/assets/serial-numbers/MSO and creates **a
   new repair_orders row unconditionally per loop iteration** — one RO per Unit (a 50-cable
   line = 1 unit = 1 RO). Existing-serial lookup is scoped **per item row** (`$asnItemId`).
 - **"#/N received" UI** (`togadesk/desk/template/pages/managedserviceorders/view.php`):

package/knowledge/clients/nycdoe/profile.md

@@ -17,14 +17,14 @@ NYC DOE (New York City Department of Education) is a TOGA client whose entire in
 runs in the **1.0 worker tier** (~30 cron scripts under `worker/crons/sync/nycdoe/` and
 `worker/crons/notifications/nycdoe/`, on the `sync` and `notification` worker roles).
 ServiceNow is DOE's system of record for tickets (Incidents and RITMs); TOGA mirrors those
-locally, drives fulfillment through TogaDesk and NetSuite, and pushes status / ETA /
+locally, drives fulfillment through TOGa Desk and NetSuite, and pushes status / ETA /
 proof-of-delivery back to ServiceNow. A parallel EDI relationship (850 POs in, invoices out)
 runs over DOE's SFTP.
 
 ## Platforms & data
 - **1.0 worker tier only** — no 2.0 footprint. Local mirror tables live in `db_common`
   (`NYCDOETickets`, `NYCDOELocations`, `AdvanceShippingNotice*`).
-- **TogaDesk:** DOE is client id **16** (`db_togadesk`) — repair orders, managed service
+- **TOGa Desk:** DOE is client id **16** (`db_togadesk`) — repair orders, managed service
   orders, and the "#received / #ordered" Receiving Summary UI.
 - **NetSuite:** Sales Orders, PO reconciliation, item receipts, Item Fulfillments, invoices
   (SuiteTalk toolkit in `library`).

package/knowledge/registry.json

@@ -8,6 +8,6 @@
   { "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": "togadesk",    "project": "TogaDesk",    "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "togaview",    "project": "TogaView",    "framework": "1.0", "role": "app",  "dependsOn": [] }
+  { "repo": "togadesk",    "project": "TOGa Desk",   "framework": "1.0", "role": "app",  "dependsOn": [] },
+  { "repo": "togaview",    "project": "TOGa View",   "framework": "1.0", "role": "app",  "dependsOn": [] }
 ]

package/package.json

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