toga-ai 1.0.296 → 1.0.298

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

@@ -8,5 +8,5 @@
 | [Ticket Email Notifications (notifications table)](features/notifications.md) | Which TOGa Desk emails fire for a given client is driven **entirely by data**, not code: the `TOGaDeskSupport.notifications` table holds one row per `(clientid, | desk/includes/classes/class.notification.php, crons/tickets.php, crons/tickets_prod.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 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 |
+| [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/includes/controllers/actions/tickets/addReply.php, desk/api/resources/tickets.php, desk/api/resources/ticket_replies.php, crons/tickets.php, crons/pipe.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/features/email-to-ticket-intake.md

@@ -6,8 +6,8 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-06-15
-owners: ["jcardinal"]
+updated: 2026-07-09
+owners: ["jcardinal", "dfranks"]
 files:
   - crons/tickets.php
   - crons/tickets_prod.php
@@ -61,6 +61,14 @@ Writes `tickets`, `tickets_replies`, attachment `files`; reads config from the `
 - **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.
+- **`adminid` clobber on reply routing:** after `emailToTicket()` sets `$data['adminid']` from
+  the FROM address (~line 1407), an asset lookup (~line 1437-1442) overwrites it with the
+  replying user's asset's assigned admin. On a matched-ticket reply this makes a user's email
+  look like a staff reply in `addReply()` (`isAdminReply=true`), so `Awaiting User` etc. never
+  transition. The asset-derived adminid is for NEW-ticket auto-assign in `add()`, not reply
+  classification. See the ticket-lifecycle doc.
 
 ## Change history
+- 2026-07-09 — documented the `emailToTicket()` adminid-overwrite reply misclassification
+  (TRUE-80114 planning investigation) (dfranks)
 - 2026-06-15 — documented from a source read of `crons/tickets*.php` and `emailToTicket()` (jcardinal)

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

@@ -6,13 +6,16 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-06-12
-owners: ["mhammontree"]
+updated: 2026-07-09
+owners: ["mhammontree", "dfranks"]
 files:
   - desk/includes/classes/class.ticket.php
   - desk/includes/controllers/actions.php
+  - desk/includes/controllers/actions/tickets/addReply.php
   - desk/api/resources/tickets.php
+  - desk/api/resources/ticket_replies.php
   - crons/tickets.php
+  - crons/pipe.php
   - desk/includes/controllers/actions/tickets/merge.php
 related:
   - 1.0/apps/togadesk/features/smb-contract-editing.md
@@ -40,6 +43,26 @@ Creation paths — all funnel through `Ticket::add($data)`:
 - Ticket merge (`actions/tickets/merge.php`) inserts a master ticket directly — it copies
   fields from the child, including `customerid` (since June 2026).
 
+### Reply entry points (FOUR doors — only two transition status)
+There are **four** inbound reply paths, but the status-transition switch lives ONLY inside
+`Ticket::addReply()`. Any door that does not route through `addReply()` will not change status:
+- **IMAP-poll cron** — `crons/tickets.php` → `emailToTicket()` → `addReply()`. ✅ transitions.
+- **Mail pipe** — `crons/pipe.php:113` → `emailToTicket()` (legacy 6-arg call) → `addReply()`.
+  ✅ transitions.
+- **Desk REST API** — `desk/api/resources/ticket_replies.php` `'add'` → `addReply($data)`
+  directly. ✅ transitions.
+- **togaview customer portal** — the portal reply form (`action="/ticket"` + `newReplyBtn`,
+  from the generic `common/togaview/ticket.php` and client variants e.g.
+  `common/newcenturyholdingsllc/ticket.php`, `common/towfoundation/ticket.php`) POSTs to
+  `togaview/mvc/ticket/post.php` `newReplyBtn` handler (~line 388). This handler inserts the
+  reply row **directly** via `App_Model_TogaDesk_TicketReply` and **bypasses the `Ticket` class
+  entirely** — it never updates `tickets.status`, `tickets_replies.newStatus`, or
+  `tickets_history`. ❌ **no status transition.** This is the gap behind "a reply from outside
+  Desk doesn't move the ticket."
+
+The in-Desk agent reply path is `desk/includes/controllers/actions/tickets/addReply.php` →
+`Ticket::addReply($_POST)`.
+
 ## How it works
 
 ### `Ticket::deriveCustomerId(int, string): ?int` (added June 2026)
@@ -64,6 +87,11 @@ means the reply lands but the ticket status silently never changes (no history e
 re-entry). That was the On Hold SLA bug; `case 'On Hold'` (admin ⇒ stays On Hold, client ⇒
 Open) was added June 2026.
 
+- **`origin` is the reliable "reply came from outside Desk" signal.** The in-app agent reply
+  path (`addReply.php` → `addReply($_POST)`) carries **no `origin` key**, whereas
+  `emailToTicket()` sets `tickets.origin = 'EMAIL'` and togaview sets `'TOGAVIEW'` on new
+  tickets. Absence of `origin` on a reply therefore identifies an in-app agent reply; presence
+  identifies an external reply. This is the safe hook for any "external reply → status" logic.
 - 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.
@@ -88,11 +116,29 @@ backfill (e.g. craftex:
   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)?
+- **`emailToTicket()` clobbers `adminid`, misclassifying user email replies as staff replies.**
+  After matching the sender and setting `$data['adminid']` from the FROM address (~line 1407),
+  an asset lookup (~line 1437-1442) **overwrites** `$data['adminid']` with the replying user's
+  asset's assigned admin. When the matched ticket goes to `addReply()`, the user's reply is
+  read as an admin/staff reply (`isAdminReply=true`), so states like `Awaiting User` stay put
+  instead of transitioning to `Open`. The asset-derived adminid is meant for auto-assigning
+  NEW tickets in `add()`, not for classifying replies — `adminid` serves two conflicting
+  purposes here.
+- **Cross-app DB coupling:** togadesk and togaview share the `TOGaDeskSupport` database
+  (`tickets`, `tickets_replies`, `tickets_history`, `people`), so a reply/status behavior
+  change on either side is visible to both immediately. togaview cannot load Desk's
+  `class.ticket.php`, so its writes go through the `App_Model_TogaDesk_*` models
+  (`TicketReply`, `TicketsHistory`, `Ticket`) — any shared status logic must account for that
+  the portal path never instantiates `Ticket`.
 - 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-07-09 — mapped the four reply entry points (togaview portal bypasses `addReply()` so
+  never transitions status); documented `emailToTicket()` adminid-overwrite reply
+  misclassification, the `origin`-absence agent-reply signal, and togadesk↔togaview shared-DB
+  coupling — from TRUE-80114 planning source investigation (dfranks)
 - 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)

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -21,3 +21,4 @@
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
+| [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. | _underscore/Environment.php, _underscore/Config.php, _underscore/Database.php, _underscore/Route.php, api2/Component/Api/V2/V2.php, api2/index.php, api2/.htaccess |

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
-owners: ["dfranks", "jcardinal"]
+updated: 2026-07-09
+owners: ["dfranks", "jcardinal", "mhammontree"]
 files:
   - _underscore/Database.php
   - _underscore/ApiRequest.php
@@ -93,6 +93,7 @@ registration is region-aware in `api2/Controller/Index.php`; the alias const is
 
 ## Change history
 
+- 2026-07-09 — Linked the new [Running a 2.0 app locally](../workflows/running-a-2.0-app-locally.md) runbook, which frames these three connections as one requirement of a full local browser run. (mhammontree)
 - 2026-07-07 — Noted the new shared **Cache** cluster (`Databases` id 145, alias `DB_CACHE`,
   region-aware) added for the api2 cross-client retrieval engine. (jcardinal)
 - 2026-06-18 — Documented after the `Logs_Growrk`/`Logs_Aig` local 500s while testing the
@@ -101,4 +102,5 @@ registration is region-aware in `api2/Controller/Index.php`; the alias const is
 ## Related docs
 
 - [_underscore architecture](../architecture.md)
+- [Running a 2.0 app locally (browser end-to-end)](../workflows/running-a-2.0-app-locally.md) — the full local-stack runbook these three connections are one requirement of.
 - [NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) — the work that surfaced this.

package/knowledge/2.0/apps/_underscore/workflows/running-a-2.0-app-locally.md

@@ -0,0 +1,124 @@
+---
+title: Running a 2.0 App Locally (browser, end-to-end via api2)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: workflow
+status: active
+updated: 2026-07-09
+owners: ["mhammontree"]
+files:
+  - _underscore/Environment.php
+  - _underscore/Config.php
+  - _underscore/Database.php
+  - _underscore/Route.php
+  - api2/Component/Api/V2/V2.php
+  - api2/index.php
+  - api2/.htaccess
+related:
+  - ../features/per-client-database-connections.md
+  - ../../dbchanges2/workflows/client-onboarding.md
+  - ../../dbchanges2/architecture.md
+---
+
+## Summary
+
+The full dependency chain required to run a 2.0 client app **through the browser**,
+end-to-end, against a **local `api2`** (e.g. pointing the `toga2-view` frontend at a laptop
+`api2` instead of beta/prod). This is separate from CLI/script backend testing — it exercises
+the web SAPI, the Apache-supplied environment, Core-driven client-DB registration, and the
+`/v2/auth/login` browser auth gate, none of which the CLI path touches. It cost hours to
+reverse-engineer; the notes below are platform-general (any 2.0 client app), with Rate used
+only as the running example.
+
+**Bottom line:** most local failures here are a **provisioning gap in the local stack**
+(missing/stale DB, unregistered origin, unseeded Core), *not* an app bug. The confusing
+`Route.php:525` "failed to determine how to render view" and stale-Core "missing model file"
+fatals below both mean "the local stack isn't fully stood up."
+
+> Cost/benefit note from the originating session: because standing the full local backend up
+> is this involved, the team's chosen shortcut for front-end work was to **deploy api2 to beta
+> and point the local frontend at beta** rather than rebuild the entire local backend stack.
+
+## Steps / requirements
+
+### 1. ENVIRONMENT comes from Apache for the web app (not the CLI)
+
+- `_Environment::initialize()` reads `getenv('ENVIRONMENT')` (`_underscore/Environment.php:11`)
+  and **throws if unset**. `_Config` then loads `Config/<ENVIRONMENT>.ini` (`Config.php:38`).
+- The **web app** gets `ENVIRONMENT` from **Apache** — a `SetEnv ENVIRONMENT <name>` in the
+  api2 vhost — *not* from your shell/CLI environment. Dev convention:
+  `ENVIRONMENT=dev-<name>-laptop` → loads `Config/dev-<name>-laptop.ini`.
+- To see what the **web** app actually resolves (the frontend URL/console won't show it — api2
+  is a separate host), temporarily add to the top of `api2/index.php`:
+  `if (isset($_GET['__env'])) die(getenv('ENVIRONMENT'));` and hit `http://api2/?__env=1`.
+  Remove it afterward.
+
+### 2. api2 collapses the environment name to a slug
+
+- `V2.php:146`: `$this->environment = (substr($name,0,4)=='dev-') ? 'dev' : $name`. So **any**
+  `dev-*` INI resolves to the slug **`dev`** for downstream lookups (notably Core DB host
+  selection, below).
+
+### 3. Client DB connections are Core-driven, not from the INI
+
+- `_Database::registerClientDatabases($environment, $clientId)` (`_underscore/Database.php:56`)
+  SELECTs from **Core**, joining `Clients → Databases → DatabaseHosts → Environments(slug=<env>)`
+  to resolve the client's **client, log, AND archive** databases (all three INNER-JOINed — a
+  missing row for any one drops the whole registration).
+- For local, Core must have an `Environments.slug='dev'` row plus `DatabaseHosts` rows pointing
+  all three DBs at `localhost`. A prod Core backup **already carries a `dev`→localhost row by
+  design** — do not assume it's missing.
+- There are **two** log connections: `DB_LOGS` (base framework `Logs`) and `DB_CLIENT_LOGS`
+  (per-tenant `Logs_<tenant>`). See
+  [per-client database connections](../features/per-client-database-connections.md) for the
+  three-alias mechanism and the logs-DB write trap.
+
+### 4. Browser login `POST /v2/auth/login` — requirements in the order code checks them
+
+Checked in `V2.php` (~lines 485–800):
+
+1. **POST with an `Origin` header.** A browser address-bar **GET** has neither → silent
+   fallthrough (no auth, no useful error). Requests must come from the frontend (fetch/XHR),
+   not a typed URL.
+2. **`Core.Domains` row for the port-stripped origin.** `V2.php:98-103` strips the port, so
+   `http://rate.togaview:5173` matches a `Core.Domains` row for `http://rate.togaview`. That
+   row's `clientId`/`appId` must resolve to the local client/app.
+3. **Active login user** must exist in `Client_<tenant>.Users`.
+4. **All four databases must exist WITH SCHEMAS:** `Client_<tenant>`, `Logs_<tenant>`,
+   `Archive_<tenant>`, and base `Logs`. An **empty** database is not enough — every request
+   writes a transaction log via `$log->save()` at `execute()` finalization (`V2.php:2138`) into
+   `Logs_<tenant>.Api` / `Logs.Api`. Structure-only imports of the log/archive DBs are fine.
+5. **`Core.Apis` must be seeded** — API auth uses `Apis.uuid`/`Apis.secret`. `Apis` is
+   deliberately **excluded from blanks/backups**, so a freshly restored Core often has it empty.
+
+## Gotchas / known issues
+
+- **The silent `Route.php:525` error** — `"Failed to determine how to render view for route
+  '/v2/...'"` (thrown at `_underscore/Route.php:525`) means the API handler returned **no**
+  response, so `_Route` fell through to view rendering. It is thrown during bootstrap
+  **outside** api2's JSON error handler, so the browser shows raw HTML and often **nothing** is
+  written to the PHP error log. The real cause is almost always a **local DB/registration gap**
+  (missing DB or schema, unresolved client-DB registration, or the auth gate being skipped per
+  step 4.1) — treat it as "the local stack isn't fully provisioned," not a request/app defect.
+
+- **A STALE local Core silently 500s every api2 request.** api2's V2 loops **every**
+  `Core.Records` model at request time (`$thisModelName::TABLE`, `V2.php:3442-3446`). If local
+  Core is missing recent migrations it still references removed models and **fatals on a missing
+  model file** — a confusing error that looks unrelated to the DB and breaks *all* requests.
+  Concrete example: `dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql` is **non-idempotent**
+  (fixed record ids 317–322, RecordFields 2171–2200 — cannot be re-run) and its Section 9
+  **DELETES** Core `Records` row 41 (`ItemFulfillmentPackages`, model
+  `\_Model_Client_ItemFulfillmentPackage`), consolidating it into
+  `ItemFulfillments_TrackingNumbers` (record 317). A local Core missing this migration still has
+  record 41, so V2 fatals on the removed `_Model_Client_ItemFulfillmentPackage` file.
+  **Fix:** bring local Core current — apply the missing Core migrations in date order, or refresh
+  Core wholesale. Do not re-run a single non-idempotent migration in isolation.
+
+## Change history
+
+- 2026-07-09 — Documented the full local browser-run dependency chain (Apache `ENVIRONMENT`,
+  `dev-*`→`dev` slug collapse, Core-driven client-DB registration, `/v2/auth/login` browser gate,
+  the `Route.php:525` silent-fallthrough gotcha, and the stale-Core "missing model file" fatal),
+  discovered while trying to run `toga2-view` against a local `api2`. (mhammontree)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 26 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 27 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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