toga-ai 1.0.301 → 1.0.303

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

@@ -5,6 +5,7 @@
 | [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, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairorder.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
+| [Managed Service Order Create Flow (New MSO modal → tickets/add)](features/managed-service-order-create.md) | The **Managed Service Order (MSO) create flow** is how a TOGa Desk user manually creates a managed service order: pick an End User (or a Client Location), choos | desk/includes/controllers/actions/tickets/add.php, desk/template/modals/tickets/addNew.php, desk/template/pages/managed.php, desk/template/pages/getinfo.php, desk/template/footer.php, library/app/model/togadesk/repairorder.php |
 | [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 |

package/knowledge/1.0/apps/togadesk/features/managed-service-order-create.md

@@ -0,0 +1,109 @@
+---
+title: Managed Service Order Create Flow (New MSO modal → tickets/add)
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: feature
+status: active
+updated: 2026-07-09
+owners: ["mhammontree"]
+files:
+  - desk/includes/controllers/actions/tickets/add.php
+  - desk/template/modals/tickets/addNew.php
+  - desk/template/pages/managed.php
+  - desk/template/pages/getinfo.php
+  - desk/template/footer.php
+  - library/app/model/togadesk/repairorder.php
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togadesk/features/field-service-dispatch.md
+  - 1.0/apps/togadesk/features/ticket-lifecycle.md
+---
+
+## Summary
+The **Managed Service Order (MSO) create flow** is how a TOGa Desk user manually creates a
+managed service order: pick an End User (or a Client Location), choose a Contract, add one or
+more assets, and submit. The server builds a `ManagedServiceOrder`, creates its assets, then
+one `App_Model_TogaDesk_RepairOrder` per asset. This is the **entry/creation** side; the
+downstream repair-order lifecycle (dispatch, scheduling, status) lives in
+[Field-Service Dispatch](./field-service-dispatch.md).
+
+## Key files / entry points
+- **Entry link:** `desk/template/pages/managed.php` — the "NEW MANAGED SERVICE ORDER" link opens
+  modal `tickets/addNew`.
+- **Modal:** `desk/template/modals/tickets/addNew.php` — the New MSO form. It has **no own
+  `<form>` tag**; it relies on the global `#formModal` wrapper (rendered in
+  `desk/template/footer.php`) and `$("form").submit()`. Contains the Summary field, an optional
+  inline **new End User** sub-form (name/email/phone + a `#new-user-password` field), an inline
+  **new address** sub-form, and select2 dropdowns `#enduser`, `#userlocation`, `#location`.
+- **Server action:** `desk/includes/controllers/actions/tickets/add.php` — builds the
+  `ManagedServiceOrder`, creates assets, then a `RepairOrder` per asset. `ticketType`
+  `INSTALLATION` maps the repair order to `App_Model_TogaDesk_RepairOrder::TYPE_ONSITESERVICE`.
+- **Address AJAX:** `desk/template/pages/getinfo.php` — populates the End User Address dropdown.
+
+## How it works
+1. `managed.php` opens the `tickets/addNew` modal into the global `#formModal`.
+2. The user selects an existing End User (`#enduser` → `userid`) or creates a new one inline;
+   selects an End User Address (`#userlocation`) or a Client Location (`#location`); picks a
+   Contract; and adds assets.
+3. Submit runs the modal's client-side validator, then POSTs `?action=…` to `add.php`.
+4. `add.php` builds the `ManagedServiceOrder`, creates each asset, and for each asset builds a
+   `RepairOrder`. In the `TYPE_ONSITESERVICE` branch it reads optional per-asset fields
+   (`installation`, `access-instructions`) — see the getVar gotcha below.
+
+### Address sourcing — per-person vs. client location (important)
+There are **two** address sources, and they come from different tables:
+- **End User Address dropdown (`#userlocation`)** is per **person**. `getinfo.php` (uid branch,
+  ~L152–171) runs `SELECT … FROM people_addresses INNER JOIN addresses ON addresses.id =
+  people_addresses.addressid WHERE people_addresses.peopleid = <uid>`. Addresses are stored
+  **per person** in the `addresses` table + `people_addresses` junction (`peopleid` → `addressid`)
+  in the togadesk DB (`TOGaDeskSupport` / `db_togadesk`).
+- **An empty End User Address dropdown is a legitimate data state**, not a bug — it just means
+  that person has no `people_addresses` row. The **designed fallback** is the modal's inline
+  "add new address" form (`addNewAddress()` sets the `#newAddressCount` hidden field), which
+  `add.php` (~L119–148) fully supports creating.
+- **Client Location (`#location`)** is the alternative: client/site addresses live in the
+  `locations` table keyed by `clientid`, reachable via the modal's "Select either End User or
+  Client Location" toggle (`#checkbox` → `#servicelocation`/`#location`), enabled once a Contract
+  is chosen.
+
+History: the per-person-only End User query dates to a **2021-12-06** schema migration
+(`repair_order_addresses`/`primaryaddress` → `addresses`/`isprimary`, commit `bf1abaa06`, Jeff).
+The older query — still commented in `getinfo.php` ~L95–148 — UNIONed client `locations` into the
+End User dropdown. Dropping that UNION is **long-standing, not a recent regression**.
+
+## Gotchas / known issues
+- **`App_Page::getVar($var)` THROWS when the request var is absent** — it is **not** a
+  null-returning getter. In the `TYPE_ONSITESERVICE` branch, `add.php` (~L353–354) read the
+  optional `installation` and `access-instructions` fields; the manual MSO form doesn't post
+  `installation`, so the whole create aborted with a Sentry exception. **Fix:** use
+  `App_Page::getVarIfSet($var)` (returns `null`) — or guard with `App_Page::varIsSet()` — for any
+  **optional** request field. This is a framework-wide 1.0 `App_` gotcha, not togadesk-specific
+  (`library/app/page.php` — `getVar` L354 throws, `getVarIfSet` L382 returns null,
+  `varIsSet` L404).
+- **Chrome autofill silently breaks the modal.** The modal nests a new-user sub-form (including a
+  password field) inside `#formModal`, which had no `autocomplete` attribute. Chrome's
+  password/profile autofill then filled Summary + address fields **without firing jQuery
+  change/input events and without syncing the select2 widgets**, so validation saw empty values
+  (e.g. "Please select an address" on a field that looked filled). Manual typing worked because it
+  fires the events. **Fix:** `autocomplete="off"` on `#formModal` (and the new-user/new-address/
+  Summary/select2 fields) plus `autocomplete="new-password"` on the password field (Chrome ignores
+  form-level `off` for password fields).
+- **No-saved-address submit deadlock.** When an existing End User (`userid != 0`) had no saved
+  address, the validator required `#userlocation != 0` ("Please select an address."), but the
+  dropdown was empty and the modal auto-opened the inline add-address form — an unresolvable
+  deadlock. **Fix:** the validator now also reads `newAddressCount = parseInt($('#newAddressCount')
+  .val())||0` and only blocks when `selectedValue == 0 AND newAddressCount == 0`, since the server
+  already supports the inline address.
+- The addNew modal has **no `<form>` tag of its own** — it depends entirely on the global
+  `#formModal` in `footer.php` and `$("form").submit()`. Anything that alters that global wrapper
+  (attributes, nesting) affects this flow.
+
+## Change history
+- 2026-07-09 — TRUE-80100: documented the MSO create flow (entry, server action, per-person vs.
+  client-location address sourcing) and folded in three fixes: `getVar` → `getVarIfSet` for
+  optional request vars in the `TYPE_ONSITESERVICE` branch (server crash); `autocomplete` on
+  `#formModal` + password field to stop Chrome autofill bypassing select2/events; and the
+  validator now honors `#newAddressCount` so a no-address End User can submit an inline address.
+  (mhammontree)

package/knowledge/1.0/apps/tools/features/talos-kb-documents-admin.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-02
+updated: 2026-07-09
 owners: [jcardinal]
 files:
   - tools/mvc/talos/kb-documents/get.php
@@ -68,11 +68,18 @@ Classic view → Edit → Save per tab, with **full-set reconciliation** (transa
 back on error), trash-icon row removal, and an auto-dismissing toast. Backs the `Team.*`
 prompt/replacement tables that the worker2 pipeline reads at runtime.
 
+**Encoding (fixed 2026-07-09):** terms were stored HTML-encoded and then re-escaped at render,
+so they displayed **double-encoded** (e.g. "Grand & Toy"). `vocabulary/post.php` now
+`html_entity_decode()`s values on save so the DB stores **raw** text; `vocabulary/get.php`
+already escapes once at display. Do not re-add encoding on save.
+
 ## Helpers
 
 - **`App_Talos_S3`** (`_/app/talos/s3.php`) — S3 client; list KB slugs; list/count approved
   (UTC→Central for display); presigned URL; get/delete; `moveApprovedDocument`;
-  `updateApprovedDocument`; `sanitizeTitle`; `copyWithinBucket`; `putObjectBody`; slug
+  `updateApprovedDocument`; `sanitizeTitle` (**now converts `/` and `\` to hyphens** — it
+  previously converted them to spaces, which let a slashed title create an unintended S3
+  sub-folder; matches worker2's `filenameSafeTitle()`); `copyWithinBucket`; `putObjectBody`; slug
   sanitize+lowercase; approved-prefix path guard. **`client()` credential resolution:** prefers a
   dedicated **`[talos]`** config section (the **togaiq**-capable key), falling back to `[aws]`, then
   the SDK default chain — because `App_Talos_S3` only ever talks to **togaiq**, so it needs the
@@ -114,6 +121,12 @@ prompt/replacement tables that the worker2 pipeline reads at runtime.
 
 ## Change history
 
+- 2026-07-09 — Fixed `App_Talos_S3::sanitizeTitle()` to convert `/`,`\` to hyphens (was
+  spaces) so a slashed meeting title no longer creates a stray S3 sub-folder — matches
+  worker2's `filenameSafeTitle()`; `updateApprovedDocument()` already renames the S3 object and
+  updates the metadata-sidecar filename on a title edit. Fixed the vocabulary UI double-encoding
+  bug: `vocabulary/post.php` now `html_entity_decode()`s on save so the DB stores raw text
+  (`get.php` escapes once at display). (jcardinal)
 - 2026-07-02 — Added **move** (re-file a doc between KBs) and **edit** (title + Find&Replace + body,
   ported from the old `kb_processor.php`) to the doc modal, each via get+put (togaiq denies
   `CopyObject`) and each enqueuing a single `SyncKb("source,dest")` re-sync. Fixed togaiq

package/knowledge/1.0/standards/backend-php.md

@@ -5,8 +5,8 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-07-06
-owners: [jcardinal, rgirish]
+updated: 2026-07-09
+owners: [jcardinal, rgirish, mhammontree]
 files: []
 related:
   - ../apps/library/architecture.md
@@ -429,6 +429,26 @@ gracefully instead of dropping unrelated work or crashing the loop.
 
 * Validate and sanitize all user input (see SQL Injection Prevention and HTML escaping above).
 
+### Request variable access — `getVar` throws, `getVarIfSet` returns null
+
+`App_Page::getVar($var)` is **not** a null-returning getter — it **throws**
+`Exception("Variable '$var' does not exist in the request headers.")` when the request var is
+absent (`library/app/page.php` L354). Use it only for fields you *know* are always posted.
+
+For any **optional** request field, use `App_Page::getVarIfSet($var)` (returns `null` when
+missing, L382) or guard first with `App_Page::varIsSet($var)` (L404). Reading an optional field
+with `getVar()` aborts the whole request with an uncaught exception — this is a recurring 1.0
+crash class (e.g. TRUE-80100: an unconditional `getVar('installation')` in a create action
+crashed every submit that omitted the field).
+
+```php
+// WRONG — throws when 'installation' isn't posted
+$order->location = App_Page::getVar('installation');
+
+// CORRECT — optional field
+$order->location = App_Page::getVarIfSet('installation');
+```
+
 ### Secure Communication
 
 * Always use HTTPS to encrypt data in transit.

package/knowledge/2.0/apps/_underscore/features/async-query-execution.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-07
+updated: 2026-07-09
 owners: ["jcardinal"]
 files:
   - _underscore/Query.php
@@ -74,6 +74,23 @@ and is a harmless no-op.
   connection and started a local transaction it never committed. Fixed by moving the async
   dispatch to the **top** of `execute()`, before any read/write connection or transaction setup.
 
+## When to use async vs. synchronous (usage rule)
+
+Async is a **workaround for a stale connection after a long HTTP call**, not a
+general-purpose "make writes faster" switch. Use it **only** for writes that happen *after* a
+long-running (e.g. up to 600s) external call has left the local connection idle enough to hit
+"MySQL server has gone away" — for example the **post-AI `setStatus` writes** in the Talos
+transcript pipeline.
+
+**Do NOT use async for a write another poll/step must read back.** An async write is not
+durable on the caller's connection when control returns — it commits later, on the worker's
+connection. In the Talos pipeline the **pre-AI dedupe / discovery-ledger writes**
+(`recordExport`, `loadOrCreateProcessing` INSERT) were originally async and the rows weren't
+durable before the next poll, so dedupe and the watermark failed and meetings reprocessed.
+Those writes were changed to **synchronous + `_Database::transactionCommit(...)`**. Rule of
+thumb: **read-back-before-worker-runs → synchronous+committed; fire-and-forget-after-slow-call
+→ async.** A stale read after such a write may also need `_Database::useQueryCache(false)`.
+
 ## Known open items
 
 - **SECURITY (open, developer aware).** DB username/password are currently sent in **plaintext**
@@ -83,6 +100,10 @@ and is a harmless no-op.
 
 ## Change history
 
+- 2026-07-09 — Added the sync-vs-async usage rule (async is only for fire-and-forget writes
+  after a long external call that staled the connection; writes another step must read back
+  must stay synchronous+committed). Prompted by the Talos pipeline, where async pre-AI dedupe
+  writes weren't durable before the next poll and caused reprocessing. (jcardinal)
 - 2026-07-07 — Built writes-only async query execution (`_Query` `isAsync` → Worker
   `Infrastructure/Database/Query` action); fixed four correctness bugs found in review
   (constructor order, worker-side commit, double-dispatch sentinel, dangling local

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

@@ -18,14 +18,14 @@
 | [NetSuite ↔ ClickUp / TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Clickup.php, worker2/Worker/Clickup/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
-| [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, _underscore/Model/Client/EmailTemplate.php |
+| [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql |
-| [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` (in addition to the upstream `Export` action — see [Teams Meeting Transcript Export](./teams-transcript-export.md)) now runs a fully | worker2/Worker/Team/Transcripts.php, worker2/bin/reprocess-transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a |
+| [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` runs a fully automated, cron-driven pipeline that ingests raw Teams transcripts into the **Talos / TOGa IQ** AWS Bedrock knowledge ba | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a, dbchanges2/Team/2026-07-08a, dbchanges2/Team/2026-07-09a |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php |
-| [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 and archives t | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
+| [Teams Meeting Transcript Export](features/teams-transcript-export.md) | > **SUPERSEDED (2026-07-09) — the S3-staging model below is history.** `Export` is now a thin > **GRAPH-DIRECT** cron poller: it no longer archives raw VTT to ` | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |
 | [WJE Freshservice Sync (worker2)](features/wje-freshservice-sync.md) | WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose tickets, contacts, assets, groups, categories, and canned res | worker2/Worker/Wje.php, _underscore/Component/Api/Wje/Wje.php, _underscore/Model/Wje/Ticket.php, _underscore/Model/Wje/TicketNote.php, _underscore/Model/Wje/Contact.php, _underscore/Model/Wje/Unit.php, _underscore/Model/Wje/TicketTeam.php, _underscore/Model/Wje/TicketCategory.php, _underscore/Model/Wje/AssetType.php, _underscore/Model/Wje/PredefinedReply.php, library/app/api/wje.php, worker/crons/toga2/wje/import_supporting_records.php, worker/crons/toga2/wje/sync_togasupply_wje.php, worker/crons/notifications/reports/wje/wje_common.php, library/app/systemmonitor/wje.php, dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql |
 | [Ticket → ClickUp Pseudocode Planning (Talos-grounded)](workflows/ticket-to-pseudocode-planning.md) | A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation plan posted back to the ticket's `📝 Pseudocode` custom field. | test/@dave/clickup_md2delta.js |

package/knowledge/2.0/apps/worker2/architecture.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: architecture
 status: active
-updated: 2026-07-07
+updated: 2026-07-09
 owners: [jcardinal]
 files:
   - worker2/Controller/Index.php
@@ -154,6 +154,23 @@ worker tier creates the row itself on pickup.) Reason: the caller's MySQL transa
 open when SQS delivers; the worker reads in a separate connection and, if uncommitted, its
 SELECT returns nothing and the guard fires ("already processed or not found — skipping").
 
+## Long-running AI actions — sync vs. async writes
+
+A worker action that makes a long (up to 600s) AI/HTTP call leaves its **local MySQL
+connection idle** long enough to hit "MySQL server has gone away" on the *next* write. The
+pattern that works (proven in the Talos transcript pipeline):
+
+- **Writes that a later poll/step must read back go BEFORE the AI call, synchronous +
+  committed.** e.g. the transcript dedupe/discovery-ledger inserts. If these are dispatched
+  async (via `_Query` writes-only async → `Infrastructure/Database/Query`) the row is **not
+  durable** when control returns, so the next cron poll re-selects and reprocesses the same
+  item. A stale read immediately after may also need `_Database::useQueryCache(false)`.
+- **Writes AFTER the AI call (e.g. `setStatus`) go async** — the connection is already stale,
+  and these are fire-and-forget status updates nobody reads back synchronously.
+
+See [async query execution](../_underscore/features/async-query-execution.md) for the `_Query`
+`isAsync` mechanism and its correctness gotchas.
+
 ## Key design decisions
 
 MySQL-first for the **Lambda/webhook/cron ingestion paths** (SQS on success) prevents lost
@@ -194,6 +211,10 @@ the MySQL-first design was departed from **on purpose** here.
 
 ## Change history
 
+- 2026-07-09 — Added the "long-running AI actions — sync vs. async writes" rule: reads-back
+  writes go before the AI call, synchronous+committed; post-AI status writes go async.
+  Distilled from the Talos Graph-direct pipeline (async pre-AI dedupe writes weren't durable
+  before the next poll → reprocessing). (jcardinal)
 - 2026-06-08 — Initial worker2 architecture doc. (jcardinal)
 - 2026-07-07 — `_Worker::runTask()` moved to SQS-first (caller does no MySQL; worker tier
   creates/tracks the row on pickup); the former debug-only direct-payload path in

package/knowledge/2.0/apps/worker2/features/notification-email-template.md

@@ -6,10 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: ["mhammontree"]
+updated: 2026-07-09
+owners: ["mhammontree", "jcardinal"]
 files:
   - worker2/Worker/Notification/EmailTemplate.php
+  - worker2/Worker/Client/True.php
   - _underscore/Model/Client/EmailTemplate.php
 related:
   - ./notification-email.md
@@ -36,7 +37,8 @@ silently riding inside — the originating transaction.
 
 - `worker2/Worker/Notification/EmailTemplate.php` —
   `abstract class _Worker_Notification_EmailTemplate`. One method:
-  `public static Send(string $clientIdentifier, string $uuid, $to, $cc, $bcc, ...$args): string`.
+  `public static Send(string $clientIdentifier, string $uuid, string|array $to = [], string|array $cc = [], string|array $bcc = [], ...$args): string`.
+  `to`/`cc`/`bcc` accept a string or array and **default to `[]`** when omitted.
   - Resolves the numeric `clientId` from `$clientIdentifier` via a Core query.
   - Registers the client DB with
     `_Database::registerClientDatabases($clientId, $environment)` (see the DB-registration
@@ -61,7 +63,21 @@ silently riding inside — the originating transaction.
    pattern: `_Worker_Startech`). See
    [`creating-worker-actions.md`](./creating-worker-actions.md).
 3. **Dispatch the template.** `_Model_Client_EmailTemplate::send()` loads the `EmailTemplates`
-   row by UUID, substitutes `{placeholder}` vars from `...$args`, and sends via `_Email`.
+   row by UUID, substitutes `{placeholder}` vars from `...$args` into **both the stored subject
+   and body** (the body may contain HTML), and sends via `_Email`.
+4. **Failure handling.** A failed send **THROWS** and is recorded as a failed `WorkerJobs` row
+   (`isSuccess=0`) with **no retry**; the failure never affects whatever enqueued it (the send
+   is fully decoupled from the originating transaction).
+
+### TOGA Technology (`True`) template
+
+The TOGA Technology template constant lives in worker2:
+`_Worker_Client_True::EMAIL_TEMPLATE_UUID__TOGA_TECHNOLOGY = '232d4edb-c2fa-4a8b-b5b9-d5800c962e19'`
+(`worker2/Worker/Client/True.php`); its `clientIdentifier` is `'True'`. The stored template
+must define `{subject}` and `{body}` placeholders (the body may be HTML). This is the template
+the **Talos transcript recap email** uses — see
+[Talos Transcript Ingestion](./talos-transcript-ingestion.md). (The UUID is a template
+identifier, not a secret.)
 
 ### Enqueuing it
 
@@ -86,6 +102,12 @@ flow into `...$args` as the template variables.
 
 ## Change history
 
+- 2026-07-09 — Documented the full `Send` signature (`to`/`cc`/`bcc` default `[]`; extra
+  string-keyed params spread as named args into `...$args` → `{placeholder}` subs in subject
+  and body, body may be HTML) and the failure contract (throws → failed `WorkerJobs` row,
+  `isSuccess=0`, no retry, never affects the enqueuer). Added the TOGA Technology (`True`)
+  template constant `_Worker_Client_True::EMAIL_TEMPLATE_UUID__TOGA_TECHNOLOGY` — the template
+  the Talos recap email sends through. (jcardinal)
 - 2026-06-30 — Built the generic background email-template worker
   `_Worker_Notification_EmailTemplate::Send` (TRUE-79251): resolves the client, registers the
   client DB via `registerClientDatabases`, and dispatches a stored `EmailTemplates` row by

package/knowledge/2.0/apps/worker2/features/talos-transcript-ingestion.md

@@ -6,11 +6,10 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-02
+updated: 2026-07-09
 owners: [jcardinal]
 files:
   - worker2/Worker/Team/Transcripts.php
-  - worker2/bin/reprocess-transcripts.php
   - worker2/bin/sync-knowledge-bases.php
   - worker2/Config/production.ini
   - dbchanges2/Team/2026-06-30a
@@ -21,197 +20,197 @@ files:
   - dbchanges2/Core/2026-06-30a
   - dbchanges2/Core/2026-07-02a
   - dbchanges2/Team/2026-07-02a
+  - dbchanges2/Team/2026-07-08a
+  - dbchanges2/Team/2026-07-09a
 related:
   - ./teams-transcript-export.md
+  - ./notification-email-template.md
   - ./creating-worker-actions.md
   - ../architecture.md
+  - ../../_underscore/features/async-query-execution.md
   - ../../../1.0/apps/tools/features/talos-kb-documents-admin.md
   - ../../../1.0/apps/test/features/talos-kb-pipeline.md
 ---
 
 ## Summary
 
-`_Worker_Team_Transcripts` (in addition to the upstream `Export` action —
-see [Teams Meeting Transcript Export](./teams-transcript-export.md)) now runs a fully
-automated, cron-driven pipeline that ingests raw Teams transcripts into the **Talos / TOGa IQ**
-AWS Bedrock knowledge bases. It replaces the old **manual** two-page web tooling
-(`test/team/talos/kb_processor.php` + `kb_processor.ini` — see
-[Talos Knowledge Base Pipeline](../../../1.0/apps/test/features/talos-kb-pipeline.md)); the
-cleanup/classify/approve/archive/sync logic is a port of that script, but driven by cron jobs
-and by **DB-editable** config instead of an `.ini`.
-
-Flow: raw VTT at `s3://toga-private/transcripts/{date}/…` → `Scan` enqueues one `Process` job
-per unprocessed key → `Process` AI-cleans + AI-classifies → approved `.txt` + Bedrock metadata
-sidecar written to `s3://togaiq/development-team/{kb_slug}/approved/` → raw archived → Bedrock
-`startIngestionJob` on that KB's data source.
+`_Worker_Team_Transcripts` runs a fully automated, cron-driven pipeline that ingests raw
+Teams transcripts into the **Talos / TOGa IQ** AWS Bedrock knowledge bases and emails a
+recap to the meeting organizer. **As of 2026-07-09 the pipeline is GRAPH-DIRECT**: there is
+**no S3 staging bucket** in the loop anymore. `Export()` is a thin cron poller that pulls
+transcript references from Microsoft Graph and enqueues one `Process` job each; `Process()`
+downloads the VTT straight from Graph and does everything in-memory. The old
+`s3://toga-private/transcripts/` staging bucket is **no longer used at all**, the `Scan()`
+action was **removed**, and `bin/reprocess-transcripts.php` was **deleted** (the `Export`
+cron replaces it).
+
+Flow: `Export` (cron) polls Graph per configured organizer → records a discovery-ledger row
+in `Team.TranscriptExports` → enqueues one `Process` job per transcript → `Process` downloads
+the VTT from Graph, strips+groups it, AI clean+classify (pass 1), applies DB replacements,
+uploads approved `.txt` + metadata sidecar to `togaiq`, archives the raw VTT to `togaiq` from
+the in-memory copy → Bedrock `startIngestionJob` → a **second** AI pass returns structured
+JSON that PHP renders to an inline-styled HTML recap email, enqueued to the organizer.
 
 ## Key files / entry points
 
-- `Worker/Team/Transcripts.php` — actions `Scan`, `Process(string $sourceKey)`,
-  `SyncKb(string $kbSlug)` (comma-separated slug list), `SyncKnowledgeBases(bool $apply=true)`
-  (all alongside the existing `Export`).
-- `bin/reprocess-transcripts.php` — standalone CLI backlog reprocessor.
+- `Worker/Team/Transcripts.php` — actions `Export`, `Process`, `SyncKb`,
+  `SyncKnowledgeBases`. **`Scan` was removed.**
 - `bin/sync-knowledge-bases.php` — CLI entry for the Bedrock→`Team.KnowledgeBases` registry
   sync (`--dry-run` supported).
 - `Config/production.ini` `[talos]` and `[teams]` sections — S3/Bedrock targets + the two
-  per-account S3 credential sets (see Configuration).
-- DB config + ledger tables in the `Team.*` schema (see Data model), authored in dbchanges2
-  under `Team/2026-06-30a..e` + `Core/2026-06-30a`.
+  per-account S3 credential sets (see Configuration). Note the **toga-private raw read path
+  is gone**; the `[teams]` S3 key is no longer used by the ingestion loop.
+- DB config + ledger tables in the `Team.*` schema (see Data model).
 
 ## How it works
 
-### `Scan` (cron)
-Lists unprocessed raw transcripts under the `toga-private` `transcripts/` prefix (skips any
-`sourceKey` already in the `Team.TranscriptProcessing` ledger) and enqueues one `Process` job
-each via `_Worker::runTask('Team/Transcripts/Process', ['sourceKey' => …])`. Scheduled by a
-`Core.CronJobs` row (weekday business hours).
-
-### `Process(string $sourceKey)`
-Port of `kb_processor`, per transcript:
-1. Fetch the raw VTT from S3 (`toga-private`, **us-west-2**). Parse **date + meeting title up
-   front** (previously parsed from the filename only *after* classification).
-2. Call the TOGa IQ AI endpoint `https://api.togaiq.com/api/ai/generate`, model
-   `bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0`, with an **extended** `output_schema`
-   returning **both** `knowledge_doc` **and** `kb_slug` — the AI picks the single best active KB
-   from the supplied list, or `general`. The **meeting title is passed into**
-   `callAICleaningAPI` and surfaced as a `MEETING TITLE:` block; the classifier instruction
-   **prioritizes the title** (often the only KB signal on short transcripts). **Classification
-   rule: customer over company** — `toga-technology` is our *own* company, so a meeting involving
-   both a customer and TOGA staff must classify to the **customer** KB; pick `toga-technology`
-   only for purely-internal meetings; fall back to `general` when neither can be determined. The
-   system prompt is **assembled at runtime** from DB tables: a template body with
-   `{{APPLICATIONS}}`/`{{CLIENTS}}`/`{{PEOPLE}}`/`{{BUSINESS_TERMS}}`/`{{EXAMPLES}}`
-   placeholders filled from `Team.TranscriptPromptTerms`. The active template body also
-   **excludes personal/social/non-work content** and must never emit a "Personal Notes" section
-   (see Change history / the 2026-07-02a Team migration).
-3. Apply DB-driven text replacements from `Team.TranscriptReplacements` (`:c` case-sensitive,
-   `:w` whole-word, `:cw`) via `preg_replace_callback` **so replacement backrefs stay literal**.
-4. Build the approved name `"{YYYY-MM-DD} - {Title Case}.txt"`.
-5. Upload to `s3://togaiq/development-team/{kb_slug}/approved/` (**us-east-1**, togaiq account
-   client) plus a `{name}.txt.metadata.json` Bedrock sidecar.
-6. Archive the raw VTT to `…/{kb_slug}/archive/{date}/` via **get(raw) + put(talos)** (NOT
-   `CopyObject` — source and dest are in **different AWS accounts**, so cross-account
-   `CopyObject` is impossible), then delete the source.
-7. AWS Bedrock `startIngestionJob` on that KB's data source (retry 5×30s on
-   `ConflictException` / throttling). **If `kb_slug === 'general'`, sync ALL active KBs.**
-
-### `SyncKnowledgeBases(bool $apply=true)` (cron)
-Keeps `Team.KnowledgeBases` current with **Bedrock as the source of truth** — the table only
-had the KBs that existed as S3 folders at build time (`general`, `office-depot`), so the AI
-classifier could never pick a KB (e.g. `elite`) that wasn't already a candidate. Lists all
-Bedrock KBs (`listKnowledgeBases`, via helper `listAllKnowledgeBases()`), filters to the
-`{kb_prefix}*` prefix (`development-team-`), derives the slug, and **upserts**: new rows insert
-`isActive=1` (`isGeneral=1` only for `general`), name title-cased, `bedrockKbId` cached; existing
-rows keep their name/flags and only refresh `bedrockKbId`. **Nothing is deleted or deactivated.**
-CLI entry `bin/sync-knowledge-bases.php` (`--dry-run`). Cron: `Core.CronJobs` row action
-`Team/Transcripts/SyncKnowledgeBases`, schedule `0 5 * * *` (daily 05:00 CT), `maxExecutionTime`
-300 (dbchanges2 `Core/2026-07-02a`; depends on the 2026-05-14 `maxExecutionTime` migration).
-
-Idempotency + status are tracked in `Team.TranscriptProcessing`
-(`pending/cleaned/uploaded/archived/synced/failed`).
+### `Export(int $lookbackDays, ?int $limit = null, array $cc = [], array $bcc = [])` (cron)
+Thin poller. The old `organizers` parameter was **REMOVED** — organizers are always resolved
+from config now.
+1. For each configured organizer, poll Microsoft Graph for transcripts in the lookback window.
+2. Resolve the organizer email (see *Organizer email resolution*).
+3. Record a discovery-ledger row in `Team.TranscriptExports` — **synchronously, then
+   committed** (see the durability gotcha).
+4. Enqueue one `Process` job per transcript.
+
+- `$limit` caps enqueues per run (mainly for testing; e.g. `1` = a single meeting).
+- `cc` / `bcc` thread through each `Process` job into the recap email; validated in
+  `enqueueRecapEmail` (deduped, organizer excluded). **Fallback:** if the organizer email
+  can't be resolved but `cc` is present, the recap sends **TO** the cc addresses.
+- A Graph `callTranscript` already recorded (`alreadyExported()`) is skipped. Export treats a
+  Duplicate-entry exception as **"skipped"**, not a hard error.
+
+### `Process(int $transcriptId, string $graphUserId, string $meetingId, string $organizerEmail, string $subject, string $meetingStartIso, array $cc = [], array $bcc = [])`
+1. Download the VTT **straight from Graph** (no S3 round trip).
+2. `stripAndGroupVtt()` — strips WebVTT timestamps and **merges consecutive same-speaker cues
+   into one block** (~40% token reduction before the AI call).
+3. **AI clean + classify (pass 1)** — same single-best-KB-or-`general` contract as before
+   (title prioritized, customer-over-company). System prompt assembled at runtime from the
+   `Team.*` prompt tables.
+4. Apply DB replacements from `Team.TranscriptReplacements` via `preg_replace_callback`.
+5. Build the approved name and upload the approved `.txt` + `{name}.txt.metadata.json` Bedrock
+   sidecar to `s3://togaiq/development-team/{kb_slug}/approved/` (us-east-1, togaiq account).
+6. **Archive the raw VTT to `togaiq`** (`…/{kb_slug}/archive/{date}/`) **from the in-memory
+   Graph copy** — no `toga-private` round trip, no cross-account CopyObject.
+7. Bedrock `startIngestionJob` on that KB's data source (retries on `ConflictException` /
+   throttling). `SyncKb` handles multi-slug lists; `syncBedrock()` now syncs a **single** KB
+   (the old "general fans out to all KBs" behavior was **intentionally removed**).
+8. **Second AI pass** returns structured JSON, which **PHP renders to inline-styled HTML** (a
+   real `<table>` for Action Items) for a recap email. Subject is built in PHP:
+   `"Recap: {Meeting} - {Date}"`.
+9. Enqueue `Notification/EmailTemplate/Send` to the organizer (see
+   [Background Email-Template Worker](./notification-email-template.md); the template is the
+   TOGA Technology `True`-client template).
+
+### Organizer email resolution
+- `resolveOrganizerEmail()` calls Graph `/users/{id}?$select=mail,userPrincipalName` — but
+  this needs the **`User.Read.All`** app permission, which the app registration **lacks**.
+- **Reliable path = the FALLBACK:** `extractOrganizerUpn()` reads
+  `participants.organizer.upn` from the meeting. `getMeeting()` now requests
+  `$select=subject,startDateTime,participants`; the `OnlineMeetings` read scope already
+  exposes the organizer UPN, so **no extra permission** is needed.
+
+### `SyncKnowledgeBases(bool $apply = true)` (cron)
+Keeps `Team.KnowledgeBases` current with **Bedrock as source of truth**. Lists all Bedrock
+KBs, filters to `{kb_prefix}*` (`development-team-`), derives the slug, upserts (new →
+`isActive=1`; existing keep flags, refresh `bedrockKbId`); nothing is deleted. CLI:
+`bin/sync-knowledge-bases.php --dry-run`. Cron `0 5 * * *` (daily 05:00 CT).
 
 ### `SyncKb(string $kbSlug)`
-On-demand re-sync used by the Tools delete/move/edit flows (see
-[Talos KB Documents Admin](../../../1.0/apps/tools/features/talos-kb-documents-admin.md)).
-`$kbSlug` now accepts a **comma-separated slug list** and syncs each KB **sequentially** with
-`KB_SYNC_DELAY_SECONDS` spacing. This exists because **Bedrock allows only one in-flight
-ingestion per KB** — a move that fired two independent parallel `SyncKb` workers raced and one
-was dropped (only the destination synced). The Tools move now enqueues a **single**
-`SyncKb("source,dest")` job so both KBs sync in one job, in order.
-
-### `bin/reprocess-transcripts.php` (CLI backlog reprocessor)
-Standalone CLI that bootstraps `_underscore`, lists existing raw transcripts under the
-`toga-private` `transcripts/` prefix, and runs each through `Process()`. Flags
-`--prefix` / `--limit` / `--dry-run`. Tolerates **both** the old `{slug}/{date}/` layout and the
-new `{date}/` layout. Requires the `ENVIRONMENT` env var, e.g.
-`ENVIRONMENT=production php bin/reprocess-transcripts.php --dry-run`.
-
-### Graph download hardening
-The Graph transcript download is hardened against SSRF / token leak: `https`-only, a
-`*.microsoft.com` host allowlist, and `FOLLOWLOCATION` off.
+On-demand re-sync used by the Tools delete/move/edit flows. `$kbSlug` accepts a
+**comma-separated slug list** and syncs each KB **sequentially** with `KB_SYNC_DELAY_SECONDS`
+spacing (Bedrock allows only one in-flight ingestion per KB, so parallel syncs race).
 
 ## Data model (`Team.*` schema, DB alias core cluster)
 
-Authored in dbchanges2 (`Team/2026-06-30a..e`, `Core/2026-06-30a`, all dated 2026-06-30). All
-PKs `INT UNSIGNED` to match the existing Talos Team-table family.
-
 - **`Team.TranscriptReplacements`** — `pattern, replacement, isCaseSensitive, isWholeWord, isActive`.
-  Seeded ~109 rules from the old `.ini`.
-- **`Team.TranscriptPromptTerms`** — `category` ENUM (`application/client/person/businessTerm/example`),
-  `term, isActive, dtCreated, dtUpdated`. Seeded from the `.ini` CORRECTIONS lists. PEOPLE are
-  stored as full "First Last" names (only 2 confidently paired; the rest seeded as individual
-  tokens, intended to be reconciled via the Tools vocabulary UI).
-- **`Team.TranscriptPromptTemplate`** — `name, bodyText` (w/ placeholders), `instruction, model,
-  temperature, maxTokens, timeoutSeconds, isActive`. One active row seeded from the `.ini` system prompt.
-- **`Team.KnowledgeBases`** — `slug, name, isGeneral, bedrockKbId, isActive`. Seeded `general` +
-  `office-depot`, but now **auto-kept-current from Bedrock** by the daily `SyncKnowledgeBases`
-  action (Bedrock is the source of truth; the table is a cache/allowlist of classifier
-  candidates). NOTE: the Tools *browse* UI still derives its live KB list from S3 folders, not
-  this table.
-- **`Team.TranscriptProcessing`** — `sourceKey UNIQUE(255), kbSlug, approvedKey, archiveKey,
-  status` ENUM (`pending/cleaned/uploaded/archived/synced/failed`), `aiModel, failureReason,
-  dtProcessed`. Pipeline ledger + idempotency.
-- **`Core.CronJobs`** INSERT for action `Team/Transcripts/Scan` (weekday business hours);
-  includes `dtCreated = NOW()` since the column has no default, and depends on the
-  `maxExecutionTime` column migration.
+- **`Team.TranscriptPromptTerms`** — `category` ENUM, `term, isActive, …`.
+- **`Team.TranscriptPromptTemplate`** — `name, bodyText, instruction, model, temperature, …`.
+- **`Team.KnowledgeBases`** — `slug, name, isGeneral, bedrockKbId, isActive`; auto-kept-current
+  from Bedrock by the daily `SyncKnowledgeBases`.
+- **`Team.TranscriptProcessing`** — pipeline ledger + idempotency. `status` ENUM
+  (`pending/cleaned/uploaded/archived/synced/failed`). **`transcriptIdentifier` widened to
+  `VARCHAR(768)`** (dbchanges2 `Team/2026-07-09a`).
+- **`Team.TranscriptExports`** — discovery ledger written by `Export`.
+  `transcriptIdentifier` **also widened to `VARCHAR(768)`**. Graph-direct columns +
+  `organizerEmail` added (dbchanges2 `Team/2026-07-08a`).
 
 ## Configuration
 
 `worker2/Config/production.ini` `[talos]`: `s3_bucket=togaiq`, `s3_region=us-east-1`,
 `bedrock_region=us-east-1`, `kb_prefix=development-team-`, `s3_root_path=development-team/`.
-
-**Two S3 credential sets — one per AWS account (see the cross-account gotcha):**
-- `[teams]` `s3_access_key_id` / `s3_secret_access_key` — the **toga-private** key (raw
-  transcripts, us-west-2). Read by `s3Client()` / `getS3Client()`.
-- `[talos]` `s3_access_key_id` / `s3_secret_access_key` — the **togaiq** key (approved/archive
-  KB bucket, us-east-1). Read by `getTalosS3Client()` and `getBedrockClient()`.
-
-Credential **values live only in the deployed `production.ini`** — documented here by section
-and account, never by value. Pre-existing plaintext keys should be rotated (separate track).
+The `[talos]` key (togaiq account, us-east-1) is used for approved/archive writes, Bedrock,
+**and now the archive of the raw VTT**. The `[teams]`/`toga-private` S3 key is **no longer
+part of the ingestion loop** (raw reads removed). Credential values live only in the deployed
+`production.ini` — documented here by section/account, never by value.
 
 ## Gotchas / known issues
 
-- **Cross-ACCOUNT S3 (root cause of repeated PutObject/CopyObject `AccessDenied`).** `toga-private`
-  (raw, us-west-2) and `togaiq` (KB bucket, us-east-1) live in **different AWS accounts** — **no
-  single IAM key can write to both.** Credentials are therefore **per-bucket**: `[teams]` key for
-  toga-private, `[talos]` key for togaiq. Because it spans accounts, **`CopyObject` is impossible**;
-  the archive step is a **get(raw) + put(talos)**, not a server-side copy.
-- **`[talos]` keys were added to `production.ini` only** — the beta/development configs still
-  need them before the pipeline runs in those environments.
-- **`general` KB fans out.** A `Process()` classified as `general` (or a `general` sync) triggers
-  a sync of **all** active KBs, not one.
-- **Replacements must use `preg_replace_callback`** so replacement text with `$`/`\` backrefs is
-  treated literally (a plain `preg_replace` would interpret them).
-- **worker2 had no prior CLI precedent** — the backlog reprocessor bootstraps by
-  `chdir($projectRoot)` then `require vendor/autoload.php` + `_underscore.php`, and requires the
-  `ENVIRONMENT` env var.
-- **Deploy TODOs left in code:** verify the live Bedrock KB region and data-source name against
-  the actual account before first prod run.
-- **Pre-existing plaintext secrets** in `worker2/Config/production.ini` and the reference
-  `kb_processor.ini` (AWS / aegra) should be rotated — not introduced by this work; no new secret
-  literals were added to any new file or migration.
+- **Idempotency: 304-char Graph ids truncated at `VARCHAR(255)` (root cause of endless
+  reprocessing).** Graph `callTranscript` ids are ~304 chars; `transcriptIdentifier` columns
+  were `VARCHAR(255)`, so ids were silently truncated. `alreadyExported()` compared the full
+  (304) id against the stored (255) prefix and **never matched**, AND the INSERT collided on
+  the truncated prefix (`error 1062 Duplicate entry … uq_transcript`) — so the same meeting
+  reprocessed on every poll. **Fixed by widening `transcriptIdentifier` to `VARCHAR(768)`** on
+  **both** `TranscriptProcessing` and the legacy `TranscriptExports`. 768 is the max for a
+  utf8mb4 single-column UNIQUE index (3072 bytes / 4).
+- **Durability: dedupe-ledger writes must be SYNCHRONOUS + committed.** `recordExport()` and
+  the `loadOrCreateProcessing` INSERT had been dispatched **async** (see
+  [async query execution](../../_underscore/features/async-query-execution.md)), so the row
+  wasn't durable before the next poll → dedupe/watermark failed and meetings re-ran. These
+  pre-AI writes must run **synchronously** and `_Database::transactionCommit(_underscore::DB_TEAM)`.
+  Conversely the **post-AI `setStatus` writes stay async** — those run after long (up to 600s)
+  AI HTTP calls, which is exactly when the local Core connection has gone stale ("MySQL server
+  has gone away"). `alreadyExported()` must also `_Database::useQueryCache(false)` so it does
+  not read a stale empty result.
+- **S3 filename safety: a `/` in a meeting title created an unintended S3 sub-folder.**
+  `filenameSafeTitle()` replaces `/` and `\` with `-` when building the approved/archive/
+  metadata S3 key; the **email subject keeps the untouched original title**. (Tools-side
+  `App_Talos_S3::sanitizeTitle()` was fixed to match — see
+  [Talos KB Documents Admin](../../../1.0/apps/tools/features/talos-kb-documents-admin.md).)
+- **KB registry split — a KB known to Bedrock/Client_True but not `Team.KnowledgeBases` is
+  silently rejected.** worker2's sync validates a KB slug against `Team.KnowledgeBases`
+  (`loadActiveKbSlugs`). A KB added only in Bedrock + `Client_True.VectorIndexes` (the registry
+  the newer Tools UI reads) is rejected by `SyncKb` as "unknown or inactive knowledge base" and
+  silently no-ops — the worker still returns HTTP-200, so the UI falsely reports "sync
+  initiated". **Fix:** run `Team/Transcripts/SyncKnowledgeBases` (or
+  `bin/sync-knowledge-bases.php`) to discover `development-team-*` KBs from Bedrock and upsert
+  them into `Team.KnowledgeBases`. **Open architectural point:** two competing registries —
+  `Team.KnowledgeBases` (worker2) vs `Client_True.VectorIndexes` (Tools UI).
+- **Cross-ACCOUNT S3.** `togaiq` (us-east-1) approved/archive writes use the `[talos]` key;
+  `CopyObject` across accounts is impossible, so archive is get(in-memory)+put. (The old
+  toga-private cross-account read is no longer in the loop.)
 
 ## Change history
 
-- 2026-07-02 — Fixed cross-**account** S3 creds: `toga-private` and `togaiq` are separate AWS
-  accounts, so credentials are now per-bucket (`[teams]` vs `[talos]` in `production.ini`) and the
-  archive step is get+put instead of the impossible cross-account `CopyObject`. Built
-  `SyncKnowledgeBases` (Bedrock→`Team.KnowledgeBases` upsert) + `bin/sync-knowledge-bases.php` and a
-  daily `0 5 * * *` cron so the classifier's candidate KB list stays current. `SyncKb` now takes a
-  comma-separated slug list and syncs sequentially (Bedrock allows one in-flight ingestion per KB;
-  parallel syncs raced). Classification: meeting title now passed to and prioritized by the AI, and
-  customer-over-company (a customer meeting stays with the customer even when TOGA staff attend).
-  Prompt template surgically updated to exclude personal/social content ("Personal Notes"). (jcardinal)
-- 2026-06-30 — Built the automated cron-driven ingestion pipeline (`Scan`/`Process`/`SyncKb`) +
-  the `bin/reprocess-transcripts.php` backlog CLI, porting the manual `kb_processor.php`. Added
-  the `Team.*` config/ledger schema (DB-editable replacements, prompt terms, prompt template, KB
-  list, processing ledger) and the `Scan` cron. Classification moved from title-based to AI (single
-  best KB, or `general`). Config vocabulary/replacements are now DB-driven and editable via the
-  Tools UI. (jcardinal)
+- 2026-07-09 — **Re-architected to GRAPH-DIRECT.** `Export` is now a thin cron poller
+  (removed the `organizers` param; added `$limit`, `cc`/`bcc`); `Scan` and
+  `bin/reprocess-transcripts.php` deleted; the `toga-private` staging bucket dropped entirely.
+  `Process` downloads the VTT straight from Graph, `stripAndGroupVtt()` (~40% token cut), and a
+  **second AI pass** now produces a PHP-rendered HTML recap email to the organizer
+  (`Notification/EmailTemplate/Send`, `True` template). Organizer email resolved via the
+  meeting `participants.organizer.upn` fallback (no `User.Read.All`). Widened
+  `transcriptIdentifier` to `VARCHAR(768)` on both ledgers (304-char Graph ids were truncated
+  at 255 → dedupe never matched + 1062 collision → endless reprocessing). Made the pre-AI
+  dedupe/discovery writes synchronous+committed (they had been async and weren't durable before
+  the next poll); post-AI status writes stay async. `filenameSafeTitle()` converts `/`,`\` →
+  `-` in S3 keys. `syncBedrock()` no longer fans "general" out to all KBs. dbchanges2:
+  `Team/2026-07-08a`, `Team/2026-07-09a`. (jcardinal)
+- 2026-07-02 — Fixed cross-**account** S3 creds (per-bucket `[teams]`/`[talos]`, archive via
+  get+put); built `SyncKnowledgeBases` + `bin/sync-knowledge-bases.php` + daily cron; `SyncKb`
+  now takes a comma-separated slug list synced sequentially. Classification: title prioritized,
+  customer-over-company. Prompt template excludes personal/social content. (jcardinal)
+- 2026-06-30 — Built the automated cron-driven ingestion pipeline porting the manual
+  `kb_processor.php`; added the `Team.*` config/ledger schema; classification moved to AI. (jcardinal)
 
 ## Related docs
 
-- [Teams Meeting Transcript Export](./teams-transcript-export.md) — the upstream S3 producer.
+- [Teams Meeting Transcript Export](./teams-transcript-export.md) — now merged into this
+  Graph-direct `Export` poller.
+- [Background Email-Template Worker](./notification-email-template.md) — the recap email path.
+- [Async Query Execution](../../_underscore/features/async-query-execution.md) — the sync-vs-async write rule.
 - [Talos KB Documents Admin](../../../1.0/apps/tools/features/talos-kb-documents-admin.md) — the Tools UI.
 - [Talos Knowledge Base Pipeline](../../../1.0/apps/test/features/talos-kb-pipeline.md) — the manual script this ports.
 - [Creating Worker Actions](./creating-worker-actions.md)
+</content>
+</invoke>

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-09
 owners: ["ajean", "jcardinal"]
 files:
   - worker2/Worker/Team/Transcripts.php
@@ -21,6 +21,16 @@ related:
 
 ## Summary
 
+> **SUPERSEDED (2026-07-09) — the S3-staging model below is history.** `Export` is now a thin
+> **GRAPH-DIRECT** cron poller: it no longer archives raw VTT to `s3://toga-private/transcripts/`
+> at all. It records a discovery-ledger row and enqueues one `Process` job per transcript, and
+> `Process` downloads the VTT straight from Graph in-memory (raw is archived to `togaiq`, not
+> toga-private). The `toga-private` staging bucket, the flat `transcripts/{date}/…` layout, and
+> the `Backfill()` re-filer described here are no longer in the loop. See
+> [Talos Transcript Ingestion](./talos-transcript-ingestion.md) for the current pipeline. The
+> Graph organizer-resolution, GUID-vs-UPN, and Entra-permission material below is **still
+> accurate** and remains the reference for how `Export` talks to Graph.
+
 `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for
 Teams meeting transcripts produced by a set of organizers and archives the raw WebVTT to S3.
 As of 2026-06-30 it **no longer classifies by client**: raw transcripts land **flat** at
@@ -171,6 +181,13 @@ Policy gap; a `400` only on a UPN means the id was never resolved to a GUID. (A
 
 ## Change history
 
+- 2026-07-09 — **`Export` re-architected to GRAPH-DIRECT** (merged into the ingestion pipeline).
+  The `toga-private` staging bucket is dropped: `Export` is now a thin poller that records a
+  discovery row and enqueues one `Process` job per transcript; `Process` downloads the VTT
+  straight from Graph and archives the raw to `togaiq`. `Export` signature is now
+  `Export(int $lookbackDays, ?int $limit = null, array $cc = [], array $bcc = [])` (the
+  `organizers` param removed). The S3-layout / `Backfill()` sections above are historical. See
+  [Talos Transcript Ingestion](./talos-transcript-ingestion.md). (jcardinal)
 - 2026-06-30 — **Removed title-based client classification and the client-folder S3 layout.**
   Raw transcripts now land flat at `transcripts/{date}/…` with no client subfolder; deleted
   `classify()`/`buildClientIndex()`/`loadClientNames()`/`loadClientAliases()` and the old

package/knowledge/INDEX.md

@@ -7,7 +7,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **library** (Library) _(framework core)_ — 11 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 14 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
-- **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
+- **togadesk** (TOGa Desk) — 9 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)

package/knowledge/clients/nycdoe/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [NYCDOE Ticket Hold-Status Sync (ServiceNow ⇄ TOGaDesk)](features/hold-status-sync.md) | 1.0 | DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and **stay held** — holds are SLA-bearing in both systems. | worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/send_request_item_updates.php, library/app/model/togadesk/repairorder.php, library/app/api/nycdoev2.php, togadesk/desk/includes/classes/class.repair.php |
-| [NYCDOE ServiceNow / ASN Integration](features/servicenow-integration.md) | 1.0 | The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into local tables, turns vendor shipment notices into NetSuite Sales Orde | worker/crons/sync/nycdoe/import_asn.php, worker/crons/sync/nycdoe/import_inc.php, worker/crons/sync/nycdoe/legacy_import_asn.php, worker/crons/sync/nycdoe/legacy_process_asn_queue.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/1_send_asn_to_netsuite.php, worker/crons/sync/nycdoe/2_send_serials_to_netsuite.php, worker/crons/sync/nycdoe/3_create_installation_ticket.php, worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/send_request_item_updates.php, worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php, worker/crons/sync/nycdoe/sync_nycdoe_locations.php, worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/crons/sync/nycdoe/send_edi_open_invoices.php, worker/crons/notifications/nycdoe/, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.notification.json, library/app/api/nycdoe.php, library/app/api/nycdoev2.php, library/app/asnprocessor/manufacturer.php, library/app/asnprocessor/apple.php, library/app/asnprocessor/lenovo.php, library/app/asnprocessor/lexmark.php, library/app/asnprocessor/acer.php, library/app/edi.php |
+| [NYCDOE ServiceNow / ASN Integration](features/servicenow-integration.md) | 1.0 | The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into local tables, turns vendor shipment notices into NetSuite Sales Orde | worker/crons/sync/nycdoe/import_asn.php, worker/crons/sync/nycdoe/import_inc.php, worker/crons/sync/nycdoe/legacy_import_asn.php, worker/crons/sync/nycdoe/legacy_process_asn_queue.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/1_send_asn_to_netsuite.php, worker/crons/sync/nycdoe/2_send_serials_to_netsuite.php, worker/crons/sync/nycdoe/3_create_installation_ticket.php, worker/crons/sync/nycdoe/test_multi_po_receipt_resolution.php, worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/send_request_item_updates.php, worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php, worker/crons/sync/nycdoe/sync_nycdoe_locations.php, worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/crons/sync/nycdoe/send_edi_open_invoices.php, worker/crons/notifications/nycdoe/, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.notification.json, library/app/api/nycdoe.php, library/app/api/nycdoev2.php, library/app/asnprocessor/manufacturer.php, library/app/asnprocessor/apple.php, library/app/asnprocessor/lenovo.php, library/app/asnprocessor/lexmark.php, library/app/asnprocessor/acer.php, library/app/edi.php, library/app/netsuite.php |
 | [New York City Department of Education](profile.md) | 1.0 | NYC DOE (New York City Department of Education) is a TOGA client whose entire integration runs in the **1.0 worker tier** (~30 cron scripts under `worker/crons/ |  |

package/package.json

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