toga-ai 1.0.507 → 1.0.509

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

@@ -8,7 +8,7 @@
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | Two "View Recommended Services" buttons exist in the TOGa Refresh 2026 SR view: 1. | library/app/model/toga/diagnostic.php, library/app/model/servicerequest.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
-| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
+| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/api/toga2.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
 | [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |

package/knowledge/1.0/apps/library/features/error-capture-1-0.md

@@ -12,11 +12,13 @@ files:
   - library/app/error/capture.php
   - library/app/error.php
   - library/app/exception/business.php
+  - library/app/api/toga2.php
   - library/app/cloud.php
   - worker/config.worker.ini
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
 related:
   - ../architecture.md
+  - ./toga2-api-client-and-bridge.md
   - ../../../2.0/apps/_underscore/features/error-reporting-issue-event.md
   - ../../../2.0/apps/worker2/features/error-escalation-cron.md
   - ../../tools/features/errors-curation-console.md
@@ -76,13 +78,42 @@ whichever occurrence happened to be seen first — i.e. one arbitrary order numb
 
 Compass USA's sales-order → MITS transmit rejection was the first business-exception use case.
 
-### Client attribution
+### Client attribution — resolved from the API client uuid at `App_Api_Toga2::authenticate()`
 
 `App_Error::setCurrentClientId()` exists in 1.0 for parity with 2.0's ambient current-client, but
-**1.0 has no central hook** equivalent to `_Database::registerClientDatabases()`. Client-scoped
-1.0 crons therefore **set it explicitly** (see
-`worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php`). Capture
-prefers an explicit `clientId` argument and falls back to the ambient value.
+**1.0 has no central hook** equivalent to `_Database::registerClientDatabases()`. Because of that,
+the explicit setter was only ever called by **one** hand-edited Compass cron, so
+**every other 1.0 cron recorded `clientId` NULL**. Evidence: `Logs.Event` held **2,093 rows with
+`clientId` NULL** against **107** with a client (all of them 2.0/api2 JWT traffic); issue `1Q`
+traced back to the 1.0 cron `crons/toga2/quad/import_po_and_asn.php`.
+
+**`App_Api_Toga2::authenticate()` is 1.0's true choke point.** `send()` authenticates before every
+call, and every 1.0→2.0 cron arrives there holding its `UUID_CLIENT`. It now calls
+`App_Error_Capture::setCurrentClientUuid($uuid)` — a **store only, no lookup**, because
+`authenticate()` is a happy-path function and must not take on a query.
+
+`App_Error_Capture` then resolves uuid → `Core.Clients.id` **lazily**, only when an error is
+actually captured, cached per process (`resolveClientIdFromUuid()`, private). It walks
+**`CORE_DATABASE_LINK_CANDIDATES = ['db_toga2core', 'db_prod_toga2core', 'db_core']`** because 1.0
+apps register the same Core connection under different link names. **Every failure path returns
+`null` and records no client rather than throwing.**
+
+Precedence is unchanged: an explicit `clientId` argument wins, then an explicit
+`setCurrentClientId()`, then the ambient uuid.
+
+> **⚠ The resolution must run INSIDE the existing
+> `App_Error::setThrowExceptionsEnabled(false)` guard.** An unconfigured DB link **warns** before
+> it fails, and in 1.0 a warning outside that guard terminates the cron (see the first gotcha
+> below). Do not hoist the lookup out of the guarded block.
+
+### The reference encoder is a byte-identical mirror of 2.0's
+
+`capture.php` carries its own copy of `encodeReference()` plus `REFERENCE_ALPHABET`
+(`'0123456789ACDEFGHJKMNPQRSTUVWXYZ'`) and `REFERENCE_OFFSET` (`128`), matching
+`_Model_Core_Logs_Issue` **byte for byte**. Both write the same **UNIQUE** `Issue.reference`
+column in the same shared table, so a divergence between them is a failed INSERT and a **lost**
+error. Change one, change both, deploy together. Rationale for the alphabet and the offset lives in
+the [2.0 doc](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md#the-quotable-reference--base-32-over-an-unambiguous-alphabet-reworked-2026-08-04).
 
 ### Fingerprint fallback (no usable stack)
 
@@ -151,6 +182,17 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — **Fixed: 1.0 errors recorded
+  `clientId` NULL on every cron but one** (2,093 NULL `Logs.Event` rows vs 107 with a client; issue
+  `1Q` from `crons/toga2/quad/import_po_and_asn.php`). `App_Api_Toga2::authenticate()` — 1.0's real
+  choke point, since `send()` authenticates before every call — now records the ambient client uuid
+  (store only, no lookup), and `App_Error_Capture` resolves uuid → `Core.Clients.id` lazily and
+  per-process on capture, walking `CORE_DATABASE_LINK_CANDIDATES`
+  (`db_toga2core`/`db_prod_toga2core`/`db_core`) because 1.0 apps name the Core link differently;
+  every failure path returns null rather than throwing, and the lookup deliberately runs inside the
+  `setThrowExceptionsEnabled(false)` guard because an unconfigured link *warns* before it fails.
+  Also mirrored 2.0's **base-32 reference encoder** (`REFERENCE_ALPHABET` + `REFERENCE_OFFSET = 128`)
+  byte-for-byte. (jcardinal)
 - 2026-08-04 — Built the 1.0 side of TRUE-78188: `App_Error_Capture` writing occurrences into the
   shared 2.0 `Logs` DB (opt-in via `[database_toga2logs]`, hand-written escaped SQL);
   `App_Exception_Business` with a fingerprint string byte-identical to 2.0's so one `issueKey`

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-04
 owners: [jcardinal, mhammontree]
 files:
   - library/app/api/toga2.php
@@ -22,6 +22,7 @@ related:
   - netsuite-suiteql-rest-shim.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
   - ../architecture.md
+  - ./error-capture-1-0.md
 ---
 
 ## Summary
@@ -77,6 +78,18 @@ belong to the NetSuite importer — documented in the per-client-sync doc, not h
 - Returns the decoded response object; callers read `->data->{resource}`, `->meta->nextPage`,
   `->isSuccess`, `->status`, `->messages[].code`.
 
+> **`authenticate()` is also 1.0's ambient-client choke point for error reporting** (added
+> 2026-08-04). Every 1.0→2.0 cron passes through it holding its `UUID_CLIENT`, so it calls
+> `App_Error_Capture::setCurrentClientUuid()` — **store only, no lookup**: this is a happy-path
+> function and must not acquire a query. The uuid → `Core.Clients.id` resolution happens lazily
+> inside error capture. Keep it that way; see
+> [error-capture-1-0](./error-capture-1-0.md).
+
+> **Latent, pre-existing, uninvestigated:** several `self::$togaClientUuid` references sit in
+> methods of this class (roughly lines 2880–4250) with **no such property declared** — an
+> undefined-property bug waiting to fire (and in 1.0, a warning inside an unguarded path
+> terminates the cron). Not introduced by, and not fixed by, the 2026-08-04 error-reporting work.
+
 ### Options DSL (how 1.0 expresses 2.0 queries)
 
 `$options` is an assoc array assembled into the 2.0 query string:
@@ -340,6 +353,11 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-04 (**uncommitted/undeployed** at time of writing) — `authenticate()` now records the
+  ambient client uuid for error reporting (`App_Error_Capture::setCurrentClientUuid()`, store-only)
+  because it is the one place every 1.0→2.0 cron passes through holding its `UUID_CLIENT` — this is
+  what fixed 1.0 errors recording `clientId` NULL. Also noted the pre-existing undeclared
+  `self::$togaClientUuid` references (~L2880–4250) as a latent undefined-property bug. (jcardinal)
 - 2026-08-03 (later pass) — TRUE-79401 **static regression harness + one correction.** BUILT a
   no-DB PHP harness (`test/@Mark/AIG/test_multi_email.php`, 12 cases, PHP 7.2.33, `php -l` clean)
   that feeds mocked `/contacts` fragments through the email transform and asserts the delimited

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

@@ -9,9 +9,9 @@
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only triage/curation screen for the 2.0 Issue/Event error-reporting pipeline, built as a 1.0 Tools MVC page reading the **shared Core Logs DB** through | tools/mvc/errors/get.php, tools/mvc/errors/post.php, tools/mvc/errors/issue/get.php, tools/assets/css/style.css, tools/_/app/nav.php, tools/config.production.ini |
 | [Legacy Email Notifier (tools /email-migration/notify)](features/legacy-email-notifier.md) | An SSO-gated admin tool at **`/email-migration/notify`** (nav group **Email Migration** > **Legacy Notifier**, personas `['TOGa Technology','Development Team']` | tools/mvc/email-migration/notify/get.php, tools/mvc/email-migration/notify/post.php, tools/_/app/nav.php |
-| [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php, library/app/error.php |
+| [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php, library/app/error.php, library/app/database.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |
 | [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | > **PER-AI-MODEL, DATA-DRIVEN SCOPING (2026-07-29).** The KB-documents and Vocabulary admin > UIs were refactored from a single hard-coded **"development-team"* | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/get.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/pg.php, tools/_/app/model/true/aimodels.php, tools/_/app/model/true/vectorindexes.php, tools/_/app/model/true/aimodels_vectorindexes.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf, tools/.platform/hooks/prebuild/01-install-php-pgsql.sh, tools/.platform/hooks/postdeploy/01-restart-php.sh |
-| [Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus a client-side estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/mvc/talos/onboarding/get.php, tools/mvc/talos/onboarding/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/benchmarks/get.php, tools/mvc/talos/factors/get.php, tools/mvc/talos/factors/post.php, tools/assets/css/style.css |
+| [Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus the estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/_/app/talos/usage.php, tools/mvc/talos/contracts/get.php, tools/mvc/talos/contracts/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/usage/get.php, tools/mvc/talos/settings/get.php, tools/mvc/talos/settings/post.php, tools/assets/css/style.css |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json, tools/ebs/setup_export_cache_folders.php, tools/_/app/frameworkindex.php |

package/knowledge/1.0/apps/tools/features/errors-curation-console.md

@@ -72,6 +72,48 @@ curated text, affected clients) right, with an always-present Type chip.
   time.
 - Hourly-occurrence chart; fingerprints table re-sized for the narrow column with an icon-only
   Move button.
+- Header chip order is **Issue / Environment / Type / Urgency** — Type was moved ahead of Urgency so
+  urgency finishes the row at the far right.
+
+### Table presentation rules (established 2026-08-04)
+
+**Stacked datetimes in every table on both pages** — listing *Last seen*; detail *Events → When*,
+*Affected clients → Last*, *ClickUp episodes → Opened/Resolved*, *Fingerprints → First seen*. A
+shared `$datetime` closure emits
+`<span class="dt"><span class="dt-date">…</span><span class="dt-time">…</span></span>`, each part
+`nowrap`, split on the single space MySQL puts between date and time; a blank value renders an em
+dash. Tabular figures keep digits aligned down the column.
+
+> **Why:** letting a datetime wrap naturally let the browser pick its own break point, and the point
+> it picked was **inside the day of the month** (`2026-08-` / `04`). This replaced the old
+> `.wrap-date` / `.wrap-anywhere` approach, whose now-dead CSS rule was removed.
+
+**The summary column has a 100px floor via table overflow, not a cell `min-width`.** The summary
+`<col>` is deliberately left **unwidthed** so it absorbs leftover space — which is also why *every
+other* column must declare a width, or `col-type` absorbs it instead. The floor comes from
+`.issue-listing { min-width: 1026px }` inside a new `.table-scroll { overflow-x: auto }` wrapper.
+
+> **⚠ Under `table-layout: fixed` a browser compresses ALL columns proportionally at narrow
+> viewports and ignores `min-width` on a cell.** A cell-level `min-width` therefore cannot work —
+> the table has to overflow and scroll. `col-when` narrowed 168px → 104px now that dates stack (the
+> 64px went to the summary), and a duplicate `.col-type` rule was removed in favour of the
+> pre-existing 104px one. **The pager sits outside the scroll wrapper.**
+
+**Whole-row click replaced the two per-cell links** (Issue ID and Summary). The `<tr>` carries
+`class="row-link"`, `data-href`, `tabindex="0"` and an `aria-label`; `.issue-id-link` was renamed
+`.issue-id` (keeping the accent colour as the affordance) and `tr.row-link` got cursor/hover/
+`focus-visible` rules.
+
+This page was deliberately **JavaScript-free**, and this is the one thing that cannot be done
+without it: no element but an anchor is clickable, and an anchor cannot wrap a `<tr>`. A small
+**delegated** click+keydown handler was added. Ctrl/Cmd/Shift-click still opens a new tab;
+Enter/Space work because removing the anchors removed the tab stop; clicks on `a`, `button`,
+`input`, `select`, `textarea`, `summary` or `label` are ignored so future in-row controls keep their
+own behaviour.
+
+> **Known trade-off:** a screen reader now announces these as **labelled rows, not links**.
+> `role="link"` was deliberately **not** applied, because it would stop the element being a table
+> row.
 
 **This page notifies nobody.** Escalation, ClickUp ticketing, and email are owned entirely by
 `_Worker_Infrastructure_Errors::Escalate`. Adding a notify action here would create a second,
@@ -128,6 +170,21 @@ They were renamed from plural on 2026-08-01, after the pipeline was already in p
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — UI pass on both `/errors`
+  pages: **stacked datetimes** in every table via a shared `$datetime` closure emitting
+  `.dt`/`.dt-date`/`.dt-time` (a naturally wrapping datetime broke inside the day of the month), and
+  the dead `.wrap-date`/`.wrap-anywhere` rules removed; a **100px floor on the summary column**
+  delivered as `.issue-listing { min-width: 1026px }` inside a new `.table-scroll` overflow wrapper
+  (with the pager outside it), because `table-layout: fixed` ignores a cell `min-width` and
+  compresses all columns proportionally — `col-when` narrowed 168px → 104px and a duplicate
+  `.col-type` rule removed; the two per-cell links replaced by a **whole-row click**
+  (`tr.row-link` + `data-href` + `tabindex` + `aria-label` and one small delegated click/keydown
+  handler — the single unavoidable use of JS on this deliberately JS-free page, since an anchor
+  cannot wrap a `<tr>`), honouring Ctrl/Cmd/Shift-click and ignoring clicks on interactive
+  descendants, with the accepted trade-off that screen readers announce labelled rows rather than
+  links (`role="link"` would stop the element being a row); and issue-detail header order changed to
+  Issue / Environment / Type / Urgency. Note **`library` and `tools` must both deploy** for any of
+  this to be visible. (jcardinal)
 - 2026-08-04 — Console build-out: the listing gained real pagination (25/page with a filtered
   `COUNT`, replacing a silent `LIMIT 200`), an EB Environment column **and filter**, a
   BUSINESS/TECHNICAL Type column derived from `issueKey` (no new DB column), and a 3-column filter

package/knowledge/1.0/apps/tools/features/mvc-data-access-patterns.md

@@ -6,12 +6,13 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-04
 owners: [jcardinal, bala]
 files:
   - tools/_/app/nav.php
   - tools/mvc/get.php
   - library/app/error.php
+  - library/app/database.php
 related:
   - ./persona-gated-navigation.md
   - ./saml-sso-auth.md
@@ -71,6 +72,38 @@ $res  = App_Database::query($sql, 'db_team');
 $rows = App_Database::buildArrayOfRows($res, false);
 ```
 
+### Gotcha — `fetchOne()` CANNOT be used as an existence test (library-wide footgun)
+`App_Database::fetchOne()` (`library/app/database.php:335-340`) does `mysqli_data_seek()` and
+then returns `$row[$col]` with **no empty-result check**. On zero rows it dereferences `null`,
+and the 1.0 error handler escalates that to an uncaught `ErrorException` — a bare **500**.
+This affects **every 1.0 app**, not just Tools.
+
+```php
+// WRONG — 500s whenever the row does not exist (i.e. exactly the case you're testing for)
+$res = App_Database::query("SELECT id FROM TalosClients WHERE slug = '$slug'", 'db_team');
+if (App_Database::fetchOne($res)) { ... }
+
+// CORRECT — COUNT(*) always returns exactly one row
+$res    = App_Database::query("SELECT COUNT(*) FROM TalosClients WHERE slug = '$slug'", 'db_team');
+$exists = (int) App_Database::fetchOne($res) > 0;
+
+// CORRECT — or materialise and check
+$rows = App_Database::buildArrayOfRows($res, false);
+if (!empty($rows)) { ... }
+```
+
+## Gotcha — Tools runs PHP 8.5, where a deprecation is a fatal
+The framework escalates deprecations (see the error-handler gotcha below), and **"Using null
+as an array offset" is deprecated in PHP 8.5 even inside `isset()`**. So
+`$arr[$row['nullableColumn']]` is a **fatal**, not a notice. Cast before indexing:
+
+```php
+$bucket = $arr[(string) $row['nullableColumn']] ?? null;
+```
+
+**Local dev on PHP 8.2 does not reproduce this.** 8.5-strictness is a hard requirement for
+this app, not a warning — test against it before shipping.
+
 ## Gotcha — a page CANNOT set HTTP status/headers (preloader already flushed)
 `App_FrameworkIndex::render()` turns on the preloader and calls `App_Page::flushCapture()`
 (`ob_end_flush + flush`, `library/app/page.php:213`) **before** `body() → App_MVC::loadFile()` runs
@@ -109,6 +142,7 @@ set_error_handler(fn(): bool => true); // swallow non-fatal notices/deprecations
 `App_Talos_Estimator` → `_/app/talos/estimator.php`.
 
 ## Change history
+- 2026-08-04 — Added two gotchas found rebuilding the Talos Pricing UI: (1) `App_Database::fetchOne()` is **not** an existence test — it `data_seek`s and returns `$row[$col]` with no empty check, so zero rows dereferences null → uncaught `ErrorException` → bare 500; a **library-wide** footgun affecting every 1.0 app (use `COUNT(*)` or `buildArrayOfRows` + `empty()`). (2) Tools runs **PHP 8.5**, where "using null as an array offset" is deprecated even inside `isset()` and the framework escalates deprecations to fatals — cast to `(string)` before indexing; PHP 8.2 local dev does not reproduce it. (jcardinal)
 - 2026-08-03 — Added the error-handler escalation gotcha: `App_Error::handleError` promotes ANY PHP
   notice/deprecation to a thrown `ErrorException` (ignoring `error_reporting`) and, without Sentry,
   echoes "Sentry is not installed…" into the response — corrupting JSON on AJAX endpoints; workaround

package/knowledge/1.0/apps/tools/features/talos-pricing-ui.md

@@ -1,22 +1,23 @@
 ---
-title: Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)
+title: Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)
 framework: "1.0"
 repo: tools
 project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-08-04
 owners: [jcardinal]
 files:
   - tools/_/app/nav.php
   - tools/_/app/talos/estimator.php
-  - tools/mvc/talos/onboarding/get.php
-  - tools/mvc/talos/onboarding/post.php
+  - tools/_/app/talos/usage.php
+  - tools/mvc/talos/contracts/get.php
+  - tools/mvc/talos/contracts/post.php
   - tools/mvc/talos/pricing/get.php
-  - tools/mvc/talos/benchmarks/get.php
-  - tools/mvc/talos/factors/get.php
-  - tools/mvc/talos/factors/post.php
+  - tools/mvc/talos/usage/get.php
+  - tools/mvc/talos/settings/get.php
+  - tools/mvc/talos/settings/post.php
   - tools/assets/css/style.css
 related:
   - ./persona-gated-navigation.md
@@ -30,65 +31,78 @@ related:
 ## Summary
 
 The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder
-with four pages plus a client-side estimate engine. Sales onboard a client and sign a
-contract here; everything else is read-only or technical-only. All four pages read the
-**Team DB** through a new `db_team` connection (`[database_team]` in `config.*.ini`; creds
-added by the developer separately).
+with four pages plus the estimate engine. Restructured 2026-08-03 to
+**Contracts / Pricing Dashboard / Usage / Pricing Settings**. All pages read the **Team DB**
+through the `db_team` connection (`[database_team]` in `config.*.ini`).
 
 ## How it works
 
-### Nav
-`App_Nav::definition()` gains a **"Talos Pricing"** folder with 4 actions: Onboarding,
-Pricing Dashboard, Usage Benchmarks, Cost Factors. Persona-gated like every other folder
-(see `persona-gated-navigation`). **Cost Factors is technical-only** — because
-`personasForRoute()` returns the *union* of folder+action personas, the Factors page must
-**narrow** explicitly with its own `requireAuth([technical])` rather than trusting
-`personasForRoute()`.
+### Contracts (`mvc/talos/contracts/{get,post}.php`) — replaces `onboarding/*`
+The old Onboarding page could only **INSERT** (hardcoded `status='ONBOARDED'`, no edit, no
+delete), which is why nothing ever reached the tables. Contracts is a real lifecycle, reusing
+the existing status enum: **PROSPECT** = draft, **ACTIVE** = signed, **CHURNED** = ended.
 
-### Estimator (`App_Talos_Estimator`, `_/app/talos/estimator.php`)
-Reads `TalosCostFactors` (with built-in fallback defaults if a key is missing) and produces
-a live cost/user + monthly estimate and recommended per-band per-user fees. **Sales never
-enters conversations-per-user** — that is the input they cannot know; it is derived from the
-cost factors / usage data we already have. The same math drives the live JS estimate on the
-Onboarding page.
+- **A signed contract can never be hard-deleted.** `TalosPricingBands` is
+  `ON DELETE CASCADE`, so deleting the client would destroy the agreed rate schedule and the
+  margin history with it. Signed contracts **churn**; they do not delete.
+- **Post-signature edits append to `TalosContractAmendments`** rather than mutating the
+  signed terms.
+- Includes an **Actual-vs-Estimate** comparison with variance chips, a month-by-month history
+  table plus cost/margin chart, and a one-click **"apply recommended org fee"**.
+
+### Pricing Dashboard (`pricing/get.php`) — rebuilt for sales leadership
+Portfolio KPIs, a 12-month blended-margin trend with the target band shaded, an exception
+list with deterministic explanations, and licensed-vs-active utilisation.
 
-### Onboarding (`onboarding/get.php` + `post.php`)
-Sales enters name / slug / offering / # users / features / # apps / min-max margin band /
-org fee / consecutive-months smoothing window. Live JS shows the estimate and recommended
-per-band fees; fees are editable. **"Sign contract" locks the band schedule** and writes
-`TalosClients` + `TalosPricingBands` in a single transaction. Write goes through
-`mvc/talos/onboarding/post.php` (the App_MVC `post.php` convention — see
-`mvc-data-access-patterns`).
+### Usage (`usage/get.php`, `_/app/talos/usage.php`)
+Adds `costIntensity()` and a **Cost intensity** panel (tool-mix driven cost).
 
-### Pricing model surfaced in the UI
-A flat monthly **org fee** (the adjustable margin lever) PLUS a **per-user fee that steps by
-user-count band**. The band rate schedule is locked at signing; when user count crosses a
-band the per-user fee auto-steps to the pre-agreed rate, then the org fee is adjusted to
-restore margin. The per-user fee never changes outside the agreed schedule. (Full
-methodology + COGS economics in the talos `pricing-cogs-model` doc.)
+**Fixed:** `clientOptions()` read `TalosClients WHERE status='ONBOARDED'` from an
+always-empty table, so the client selector rendered **empty**. It now calls
+`GET /api/usage/clients` with a Team-DB fallback.
 
-### Service offerings + cost multipliers
-Three offerings with cost multipliers stored in `TalosCostFactors`: **CHAT = 1.0** (base),
-**VOICE_TO_VOICE = 0.25**, **NATURAL_VOICE = 0.50**.
+### Pricing Settings (`settings/{get,post}.php`) — replaces `factors/*`
+Technical-only (persona-narrowed on the action, per `mvc-data-access-patterns`). **Measured
+(derived) cost-factor rows are worker-owned and read-only**, enforced server-side with
+`UPDATE ... AND isDerived = 0`. Policy rows are editable and carry full-sentence labels.
 
-### Read-only pages
-- **Pricing Dashboard** (`pricing/get.php`) — read-only per-client margin/recommendation view.
-- **Usage Benchmarks** (`benchmarks/get.php`) — read-only Langfuse-derived benchmarks.
-- **Cost Factors** (`factors/get.php` + `post.php`) — technical-only editor for the
-  `TalosCostFactors` key/value constants (the "technical tab").
+### Removed
+- `mvc/talos/benchmarks/get.php` — read the never-populated `TalosUsageMonthly` and
+  duplicated a worse subset of the Usage page.
+- `mvc/talos/onboarding/*` and `mvc/talos/factors/*` — superseded above.
+
+### Estimator (`App_Talos_Estimator`, `_/app/talos/estimator.php`)
+Now driven by the **token unit price** and **workload profiles** instead of the feature
+checklist and per-client calibration factor (methodology in `pricing-cogs-model`). Service
+offering (CHAT / VOICE_TO_VOICE / NATURAL_VOICE) describes **modality only** and says nothing
+about cost; cost is driven by tool-call **intensity** via the profile
+(retrieval / general / analytics).
 
 ## Gotchas
-- **`db_team` is read-only on the dashboards** but read/write on onboarding + factors. Add
-  the `[database_team]` config section (alias `db_team`) — same pattern as `db_true → Client_True`.
-- **Voice multiplier wording is ambiguous** — "1/4 / 1/2 the cost of chat" is flagged; full
-  voice modeling is deferred. Treat 0.25 / 0.50 as placeholders.
-- **Narrowing personas:** do not use `personasForRoute()` for a page stricter than its folder
-  (Cost Factors). See `mvc-data-access-patterns`.
+
+- **`App_Database::fetchOne()` is not an existence test** — it 500s on zero rows. See
+  [mvc-data-access-patterns](./mvc-data-access-patterns.md); the original
+  `onboarding/post.php` carried this exact bug and would have fataled on the first save
+  anyone attempted, which is good evidence nobody ever completed an onboarding through it.
+- **This app runs PHP 8.5 and escalates deprecations to fatals** — `$arr[$row['nullableCol']]`
+  is fatal even inside `isset()`. Local dev on PHP 8.2 does **not** reproduce it. Cast to
+  `(string)` before indexing. See `mvc-data-access-patterns`.
+- **`.tool--wide` did nothing.** `assets/css/style.css` documented the class as escaping the
+  960px `.app-content` cap "via `:has()`", but that rule was never written. Added
+  `.app-content:has(.tool--wide) { max-width: 100% }` — which also makes the pre-existing
+  `mvc/errors` pages genuinely full-width for the first time.
+- **Put Talos page CSS in `style.css`, not a page-local `<style>` block.** The Contracts page
+  **returns early** for list mode, so a `<style>` block placed after that return applied to
+  the calculator only and the list rendered with no CSS at all.
+- **Voice multipliers (0.25 / 0.50) are UNVALIDATED** — supplied second-hand, never measured,
+  and possibly inverted. Flagged in the UI. **Do not quote voice from them.**
+- **`db_team`** is read/write on Contracts and Settings, read-only on the dashboards.
 
 ## Security
-- `config.*.ini` already carries committed plaintext secrets (team-accepted, see architecture
-  Known issues), including a reused plaintext DB password across `config.production.ini`
-  sections — flagged for rotation. Location only; no values recorded. Do not add more secrets.
+- `config.*.ini` carries committed plaintext secrets (team-accepted, see architecture Known
+  issues) — **all still owe rotation**. Config keys referenced by name only
+  (`[api] talos_backend_url` / `talos_backend_key`); no values recorded. Do not add secrets.
 
 ## Change history
+- 2026-08-04 — Restructured to **Contracts / Pricing Dashboard / Usage / Pricing Settings**. New Contracts pages replace Onboarding with a real PROSPECT/ACTIVE/CHURNED lifecycle (signed contracts churn, never hard-delete — `TalosPricingBands` cascades; post-signature edits append to `TalosContractAmendments`), plus actual-vs-estimate variance, month history chart and one-click apply-recommended-org-fee. Settings replaces the Cost Factors editor with measured rows read-only (`UPDATE ... AND isDerived = 0`). Benchmarks page deleted. Pricing Dashboard rebuilt for sales leadership. Fixed `usage.php clientOptions()` reading an always-empty `TalosClients` (selector rendered empty) → `GET /api/usage/clients` with Team-DB fallback; added cost-intensity panel. Estimator moved to token unit price + workload profiles. Wrote the missing `.app-content:has(.tool--wide)` rule and consolidated Talos CSS into `style.css`. (jcardinal)
 - 2026-06-29 — Built the Talos Pricing UI: nav folder + 4 pages (Onboarding w/ live JS estimate and contract-signing that locks the band schedule into `TalosClients`+`TalosPricingBands` in one txn; read-only Pricing Dashboard + Usage Benchmarks; technical-only Cost Factors editor) and `App_Talos_Estimator` (reads `TalosCostFactors`, derives conversations/user so sales need not enter it). Reads Team DB via new `db_team` connection. Offerings CHAT/VOICE_TO_VOICE/NATURAL_VOICE = 1.0/0.25/0.50 (voice ambiguous, deferred). (jcardinal)

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -190,15 +190,47 @@ A uniform shape is what lets a viewer render context **generically** (see the To
 card/JSON-tree renderer). Consumers must read **both** the old and new key positions during the
 7-day `Event` retention overlap.
 
-### The quotable reference
+### The quotable reference — base-32 over an unambiguous alphabet (reworked 2026-08-04)
 
-`Issues.reference` is a Sentry-style base-26 encoding of `Issues.id`: 1 → `1A`, 26 → `1Z`,
-27 → `2A`. Because `AUTO_INCREMENT` never reuses ids, gaps are expected and permanent — a
-reference can never be recycled onto a different problem, so it is safe to quote to a customer.
+`Issue.reference` encodes `Issue.id` in **base 32** over
+`REFERENCE_ALPHABET = '0123456789ACDEFGHJKMNPQRSTUVWXYZ'`, most-significant character first, no
+padding (`_Model_Core_Logs_Issue::encodeReference()`). **All ten digits are kept; `O`, `I`, `L`
+and `B` are removed** because in the contexts a reference actually gets used — read aloud on a
+call, typed from a screenshot, pasted into a ClickUp title — they impersonate `0`, `1`, `1` and
+`8`. A reference exists to be quoted, so ambiguity is the one defect it cannot have.
+
+It replaced a decimal-counter + letter, base-26 scheme (`1A`, `2Q`, `3O`).
+
+> **⚠ `REFERENCE_OFFSET = 128` exists to stop the new scheme from OVERWRITING the old one —
+> do not remove it.** `Issue.reference` is **UNIQUE**, and every legacy value begins `1`–`3`.
+> With no offset, new id 75 encodes to `2A`, which id 27 already holds — the INSERT fails and the
+> error is **lost instead of recorded**, precisely the failure mode this pipeline exists to
+> prevent. The offset burns the first 128 (= 4 × 32) code points so every new reference starts at
+> `4` or later and both generations coexist forever. Verified by script over 200,000 ids: no
+> collisions among themselves, none against the legacy values, no banned characters.
+
+The column is `varchar(16)`, so the growth to 3 characters (≈ id 897) and 4 (≈ id 29,000) cannot
+truncate. Because `AUTO_INCREMENT` never reuses ids, gaps are expected and permanent — a reference
+can never be recycled onto a different problem.
+
+**The 1.0 encoder in `library/app/error/capture.php` must stay byte-identical** — both write the
+same UNIQUE column in the same shared table. Change one, change the other, deploy together.
 
 The reference is written by PHP in a second statement (see MySQL constraints below), which is
 why the column is nullable even though it is always populated.
 
+#### Existing data is NOT being truncated (decided 2026-08-04)
+
+Nothing needs deleting to adopt the new scheme. References are **stored, never re-derived from
+the id at read time**: the listing search, the Tools Move-fingerprint prompt (which accepts a
+reference *or* a numeric id) and every display path read the stored string, so both generations
+work side by side. Accepted cost: 10 of the 68 existing issues keep ambiguous references (`1B`,
+`1I`, `2B`, `2I`, `2L`, `2O`, `3B`, `3I`, `3L`, `3O`) until they age out through the normal GC.
+
+> **If you ever do truncate `Logs.Issue`:** `TRUNCATE` **resets `AUTO_INCREMENT`**, and
+> `IssueFingerprint`, `IssueEmailAddress`, `IssueClickupTask` and `Event` all reference
+> `Issue.id` — they must be cleared in the **same** operation or they orphan onto reused ids.
+
 ### Shutdown handler
 
 `register_shutdown_function` is registered with a **pre-allocated memory reserve**. Before this,
@@ -249,6 +281,13 @@ DB, so the pipeline is no longer 2.0-only; see
 has to opt in by adding a `[database_toga2logs]` config section, so Sentry must remain for any 1.0
 app that has not been wired up yet.
 
+## Deploy order for a change that spans this pipeline
+
+`_underscore` **first** (api2 and worker2 clone it at prebuild), then api2, worker2, `library`,
+`worker`, `tools`. Anything touching the reference encoder or a shared `Logs` table name must land
+in `_underscore` and `library` in the **same** release, and the `/errors` console work needs
+**both** `library` and `tools` deployed before it is visible.
+
 ## Gotchas / known issues
 
 - **Read-your-writes: reads go to the READ host and cannot see an uncommitted write.** A
@@ -379,6 +418,16 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — **Reference encoding reworked
+  to base 32** over `'0123456789ACDEFGHJKMNPQRSTUVWXYZ'` (all digits kept; `O`/`I`/`L`/`B` dropped
+  as impersonators of `0`/`1`/`1`/`8`), replacing the base-26 decimal-counter+letter scheme, with
+  **`REFERENCE_OFFSET = 128`** so new values start at `4` and cannot collide with the legacy `1`–`3`
+  values on the UNIQUE column — a collision would fail the INSERT and *lose* the error. Verified
+  over 200,000 ids. The 1.0 encoder in `library/app/error/capture.php` mirrors it byte-for-byte.
+  **Decided: existing Issue/Event data is not truncated** — references are stored and never
+  re-derived, so both generations coexist; 10 of 68 issues keep ambiguous references until GC.
+  Recorded the TRUNCATE warning (it resets `AUTO_INCREMENT` and four child tables reference
+  `Issue.id`). Next production reference will be `68` (max id 72). (jcardinal)
 - 2026-08-04 — **Decided: `_Exception_Business` extends `_Exception_Validation`** so api2 answers
   4xx for a business condition while still recording it — with the ordering trap that every
   `catch (_Exception_Validation …)` must now test business **first** (api2's controller and the

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

@@ -7,5 +7,5 @@
 | [Deployment — Docker, Compose, Entrypoint, External PG/Redis](features/deployment.md) | TOGa IQ ships as a **single container** (`aegra` service) wrapping the `aegra-api` FastAPI server. | talos/docker-compose.yml, talos/deployments/docker/Dockerfile, talos/deployments/docker/entrypoint.sh |
 | [MCP Servers — clickup-mcp and toga-db-mcp](features/mcp-servers.md) | Two internal **FastMCP** servers exposed over **HTTP** with API-key auth and PM2 process management: - **`clickup-mcp`** — ClickUp workspace surface (spaces / f | talos/mcp-servers/clickup-mcp/src, talos/mcp-servers/clickup-mcp/ecosystem.config.js, talos/mcp-servers/clickup-mcp/ecosystem.dev.config.js, talos/mcp-servers/clickup-mcp/pyproject.toml, talos/mcp-servers/clickup-mcp/.env.example, talos/mcp-servers/toga-db-mcp/src, talos/mcp-servers/toga-db-mcp/clusters.yaml, talos/mcp-servers/toga-db-mcp/ecosystem.config.js, talos/mcp-servers/toga-db-mcp/pyproject.toml, talos/mcp-servers/toga-db-mcp/.env.example |
 | [Observability — Langfuse, OTEL, Prometheus, OneUptime](features/observability.md) | TOGa IQ uses **two complementary tracing planes** plus optional Prometheus metrics and external uptime monitoring: - **Langfuse (native v3 SDK)** — LLM-shaped t | talos/libs/aegra-api/src/aegra_api/observability/__init__.py, talos/libs/aegra-api/src/aegra_api/observability/setup.py, talos/libs/aegra-api/src/aegra_api/observability/base.py, talos/libs/aegra-api/src/aegra_api/observability/langfuse_provider.py, talos/libs/aegra-api/src/aegra_api/observability/langfuse_client.py, talos/libs/aegra-api/src/aegra_api/observability/otel.py, talos/libs/aegra-api/src/aegra_api/observability/metrics.py, talos/libs/aegra-api/src/aegra_api/observability/span_enrichment.py, talos/libs/aegra-api/src/aegra_api/observability/targets |
-| [Pricing & COGS Model (Talos / TOGa IQ Pricing Calculator)](features/pricing-cogs-model.md) | The cost basis and pricing methodology for selling Talos (TOGa IQ) chat and voice deployments. |  |
+| [Pricing & COGS Model (Talos / TOGa IQ Pricing Calculator)](features/pricing-cogs-model.md) | The cost basis and pricing methodology for selling Talos (TOGa IQ) chat and voice deployments. | worker2/Worker/Talos/Pricing.php, tools/_/app/talos/estimator.php, dbchanges2/Team/2026-08-03a - TalosPricingTokenCostModel.sql |
 | [talos_agent — LangGraph ReAct Agent with Plan, BLP, MCP, Canvas](features/talos-agent.md) | `talos_agent` is the **reference LangGraph agent** shipped under `agents/talos_agent/`. | talos/agents/talos_agent/graph.py, talos/agents/talos_agent/state.py, talos/agents/talos_agent/context.py, talos/agents/talos_agent/prompts.py, talos/agents/talos_agent/tool_router.py, talos/agents/talos_agent/model_helpers.py, talos/agents/talos_agent/config/context.py, talos/agents/talos_agent/config/model_config.py, talos/agents/talos_agent/config/tool_config.py, talos/agents/talos_agent/config/plan_config.py, talos/agents/talos_agent/config/memory_config.py, talos/agents/talos_agent/config/mcp_config.py, talos/agents/talos_agent/config/blp_config.py, talos/agents/talos_agent/config/interrupt_config.py, talos/agents/talos_agent/config/artifact_config.py, talos/agents/talos_agent/plan/planner.py, talos/agents/talos_agent/plan/nodes.py, talos/agents/talos_agent/llm/system_prompt.py, talos/agents/talos_agent/llm/tool_binding.py, talos/agents/talos_agent/llm/message_ops.py, talos/agents/talos_agent/mcp/client.py, talos/agents/talos_agent/mcp/security.py, talos/agents/talos_agent/mcp/session_manager.py, talos/agents/talos_agent/blp/registry.py, talos/agents/talos_agent/blp/embedder.py, talos/agents/talos_agent/blp/nodes.py, talos/agents/talos_agent/tools/__init__.py, talos/agents/talos_agent/tools/code_interpreter.py, talos/agents/talos_agent/tools/canvas.py, talos/agents/talos_agent/tools/knowledge_base.py, talos/agents/talos_agent/tools/skill_injector.py, talos/agents/talos_agent/thread_name/nodes.py |

package/knowledge/2.0/apps/talos/features/pricing-cogs-model.md

@@ -6,9 +6,12 @@ project: TOGa IQ
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-08-04
 owners: [jcardinal]
-files: []
+files:
+  - worker2/Worker/Talos/Pricing.php
+  - tools/_/app/talos/estimator.php
+  - dbchanges2/Team/2026-08-03a - TalosPricingTokenCostModel.sql
 related:
   - ../architecture.md
   - aegra-api.md
@@ -38,7 +41,67 @@ a platform architecture doc captures the cross-framework topology.
 Treat the numbers below as the **April 2026 baseline**; re-measure before relying
 on them in a later period.
 
-## Cost methodology — calibrate Langfuse to AWS (decision, 2026-06-29)
+## Cost methodology — measured token unit price (decision, 2026-08-03) ← CURRENT
+
+**Supersedes the Langfuse calibration-factor method below.** Cost is tokens, priced at the
+real AWS rate:
+
+```
+unitCostPer1kTokens = AWS Bedrock-family actual $ / measured tokens
+clientMonthlyCost   = client tokens × unitCostPer1kTokens
+```
+
+**Measured July 2026:** $1,013.76 / 258.3M tokens = **$0.00392447 per 1k tokens**.
+
+- **Why not cost-per-conversation.** Measured on True, questions per conversation range
+  **1.0–61.0** (median 2.1, p90 6.5) — a 60× spread. A conversation cannot anchor a price.
+- **Why not usage-API dollars.** The usage API reports cost **~2.5× below** the real AWS bill
+  because it undercounts prompt caching (cache reads are 47% of True's tokens). Its **token
+  counts** are a real measurement and are used; **its dollars never are.**
+- The per-client **calibration factor** is retired.
+
+### Workload profiles replace the feature checklist (decision, 2026-08-03)
+
+Service offering (CHAT / VOICE_TO_VOICE / NATURAL_VOICE) describes **modality** and says
+nothing about cost. Cost is driven by tool-call **intensity**, which varies by what the client
+uses Talos for. Measured on True, cost is **42% `mcp_or_other`** (app integrations), **26%
+`code_interpreter`**, only **19% `knowledge_base`** — the opposite of what was assumed.
+
+Cost per tool call is near flat across categories ($0.046–$0.062; `canvas` the outlier at
+$0.122), so **a single unit price × an intensity figure** models this and a per-tool price
+list is unnecessary. Three seeded profiles in `TalosWorkloadProfiles`:
+**retrieval** / **general** (measured from True) / **analytics** (estimated).
+
+### Model mix is a bigger lever than any contracted feature
+
+Measured on True: `amazon.nova-pro` serves **70%** of LLM calls at $0.00092/1k while
+`claude-sonnet-4-5` serves **25%** at $0.00142/1k (76.3% cache). A **routing change moves
+COGS more than any feature flag**, so `TalosUsageModelMonthly` records model mix per
+client-month — cheap now, expensive to backfill, and the most likely explanation for a future
+margin swing.
+
+### App integrations are recorded but NOT yet priced
+
+`tokensPerIntegrationPerUser` is seeded **0**, `isValidated 0`. Integrations are almost
+certainly the largest cost driver (`mcp_or_other` = 42% of True's cost), but a slope needs
+**≥2 clients** with a known integration count and real usage, and there is exactly one.
+Inventing a coefficient repeats the mistake of the old $2.00/user default. The plumbing is
+wired so the estimate, band recommendations, and tool-mix chart all respond the moment a real
+figure is set. Method recorded in the migration: **regress each client's `mcp_or_other`
+tokens-per-user against its `appIntegrationCount`.**
+
+### orgFeeShareOfRevenue (decision, 2026-08-03)
+
+Default **0.25**. Fixes a double-count: the per-user fee was priced to hit the full target
+margin on its own, so the org-fee recommendation collapsed to ~$0.07 on a $1,036 contract,
+making the one adjustable lever useless. The seat fee now covers `(1 − share)` of target
+revenue and the flat fee covers the rest — **effective price per user is identical, only the
+split changes**. `share = 0` reduces exactly to the old formula. Verified to reconcile to the
+target margin to the cent.
+
+## Cost methodology — calibrate Langfuse to AWS (2026-06-29) — SUPERSEDED
+
+> Retired 2026-08-03 by the token unit price above. Kept for context on pre-August figures.
 
 Langfuse provides the **structure** (granular per-feature / per-user breakdown);
 AWS provides the **absolute dollars**. Each month, per client:
@@ -181,9 +244,16 @@ Technical / Actuals / Engine tabs, per-client file under the shared AI drive) is
   hack, not a bug to silently correct.
 - **OpenSearch +$350/mo is conditional** — only counts when Document Search is
   enabled; do not bake it into every quote.
+- **Voice multipliers 0.25 / 0.50 are UNVALIDATED** — supplied second-hand, never measured,
+  and may be **inverted**. Flagged in the UI. Do not quote voice from them.
+- **`infraFixedMonthly` is 0** — shared platform cost has never been measured, so band
+  recommendations come out flat. That flat table is the **honest output, not a bug**.
+- **Internal tenants are costed but not quoted** — True (TOGA Technology) feeds the platform
+  unit price and is excluded from fee recommendations; see `talos-pricing-automation`.
 - **Do not embed the absolute drive path as canonical** — the calculator lives
   under the team shared AI drive; the path can move.
 
 ## Change history
+- 2026-08-04 — **Cost model replaced**: measured **token unit price** (AWS Bedrock-family actual ÷ measured tokens; July 2026 = $0.00392447/1k) retires the per-client Langfuse calibration factor. Rejected cost-per-conversation (1.0–61.0 questions/conversation, 60× spread) and usage-API dollars (~2.5× below the AWS bill; undercounts caching — token counts used, dollars never). **Workload profiles** (retrieval/general/analytics) replace the feature checklist: offering = modality only; cost = tool-call intensity, measured 42% mcp_or_other / 26% code_interpreter / 19% knowledge_base with near-flat cost per tool call. Added model-mix tracking (nova-pro 70% of calls at $0.00092/1k vs sonnet-4-5 25% at $0.00142/1k — routing beats any feature flag), **orgFeeShareOfRevenue** (default 0.25) to stop the seat fee double-counting the whole target margin, and integrations recorded-but-unpriced pending a second client. (jcardinal)
 - 2026-06-29 — Pricing **delivery pivoted** from the Excel calculator to a DB platform (Team DB 9 `Talos*` tables + tools 1.0 UI + worker2 crons). Cost methodology recorded as **calibrate Langfuse→AWS** (per-client factor = AWS/Langfuse_corrected; global-blended fallback for new clients; always use cache-corrected Langfuse). Methodology refined: per-user fee is now a **locked band schedule** (steps with headcount) with the **org fee** as the margin lever (was fixed per-user + midpoint-solved flat fee). COGS token economics unchanged. (jcardinal)
 - 2026-06-29 — Initial pricing/COGS model doc: chat token + feature drivers, voice per-minute drivers, two-part flat+per-user methodology with mid-band solve and consecutive-month smoothing. Captured from TALOS Pricing Calculator v9 (replaces v8). v9 verified to reproduce v8 exactly ($0.811182/conversation, $2,071.18/mo for 50 users × 20 conversations, Document Search only). History ×7 vs ×15-exchanges quirk preserved for parity and flagged for technical review. (jcardinal)

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

@@ -18,7 +18,7 @@
 | [Compass VIP Support Importer (worker2)](features/compass-vip-support-importer.md) | A worker2 action that ingests Compass's quarterly VIP spreadsheet and assigns each VIP user's support technician by setting `Users.c_supportedByUserId` in `Clie | worker2/Worker/Client/Compass/VipSupport.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
-| [Error Escalation Cron (Errors::Escalate → ClickUp / email)](features/error-escalation-cron.md) | `_Worker_Infrastructure_Errors::Escalate` (renamed from `SyncWithClickup`) is the sole owner of **escalation, de-escalation, ClickUp ticketing, reminders, busin | worker2/Worker/Infrastructure/Errors.php, worker2/Worker/Clickup/ErrorTask.php, worker2/Worker/Clickup.php, worker2/Controller/Index.php, worker2/Config/production.ini, _underscore/Model/Core/Logs/Issue.php, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql, dbchanges2/Logs/2026-08-03a - Issue clickupPriority.sql |
+| [Error Escalation Cron (Errors::Escalate → ClickUp / email)](features/error-escalation-cron.md) | `_Worker_Infrastructure_Errors::Escalate` (renamed from `SyncWithClickup`) is the sole owner of **escalation, de-escalation, ClickUp ticketing, reminders, busin | worker2/Worker/Infrastructure/Errors.php, worker2/Worker/Notification/Email.php, worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, worker2/Worker/Clickup/ErrorTask.php, worker2/Worker/Clickup.php, worker2/Controller/Index.php, worker2/Config/production.ini, _underscore/Model/Core/Logs/Issue.php, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql, dbchanges2/Logs/2026-08-03a - Issue clickupPriority.sql |
 | [Etilize Catalog Item Import & Refresh](features/etilize-catalog-item-import.md) | Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. | worker2/Worker/Etilize/Items.php |
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
@@ -31,7 +31,7 @@
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.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 Pricing Automation (worker2 Cron — Usage Import, AWS Actuals, Margins, Profiles)](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, dbchanges2/Team/2026-08-03a - TalosPricingTokenCostModel.sql, dbchanges2/Team/2026-08-03b - TalosInternalTenant.sql, dbchanges2/Team/2026-08-03c - TalosIntegrationCostFactor.sql, dbchanges2/Core/2026-08-03a - Talos pricing cron jobs.sql |
 | [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | > **DB-DRIVEN AI-MODEL ROUTING (2026-07-29).** Which knowledge base a transcript is cleaned > into is now decided by the **meeting organizer's "home" AI model** | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Client_True/2026-07-27a - TranscriptAiModelRoutingColumns.sql, dbchanges2/Client_True/2026-07-27b - TranscriptAiModelRoutingData.sql, dbchanges2/Team/2026-07-27a - TranscriptVocabularyAiModelScope.sql, dbchanges2/Team/2026-07-29a - TranscriptVocabularyBackfillAllModels.sql, 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, dbchanges2/Team/2026-07-10a, dbchanges2/Team/2026-07-28a - TranscriptProcessingRetryAttempts.sql, dbchanges2/Team/2026-07-28b - TranscriptPromptTemplateConverseModel.sql, dbchanges2/Core/2026-07-28a - TeamsTranscriptRetryCron.sql |
 | [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, _underscore/Model/Team/Sprint.php, dbchanges2/Core/CronJobs (SprintLockScheduled seed) |
 | [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 |

package/knowledge/2.0/apps/worker2/features/error-escalation-cron.md

@@ -10,6 +10,9 @@ updated: 2026-08-04
 owners: ["jcardinal"]
 files:
   - worker2/Worker/Infrastructure/Errors.php
+  - worker2/Worker/Notification/Email.php
+  - worker2/Worker/Notification/EmailTemplate.php
+  - worker2/Worker/Client/True.php
   - worker2/Worker/Clickup/ErrorTask.php
   - worker2/Worker/Clickup.php
   - worker2/Controller/Index.php
@@ -23,6 +26,8 @@ related:
   - ../../../1.0/apps/library/features/error-capture-1-0.md
   - ./creating-worker-actions.md
   - ./clickup-project-routing.md
+  - ./notification-email.md
+  - ./notification-email-template.md
 ---
 
 ## Summary
@@ -107,10 +112,64 @@ which is safe only because the automation never sets status itself.
 > stamping `dtAcknowledged` ~1s after `dtCreated` and permanently disabling the neglect axis for
 > that issue. Status webhooks arriving within 60s of creation are ignored.
 
+### ⚠ Escalation email had never been sent once — two independent causes (fixed 2026-08-04)
+
+Evidence: `Logs_True.Email` contained **zero** error-escalation rows *ever*, while unrelated
+worker2 mail (merge-conflict notices, sprint reports) delivered within ~60s — so the mail pipeline
+itself was healthy. Every `Infrastructure/Errors/Escalate` run reported `"emailsSent":0` alongside
+`"failures":0` and therefore **read as healthy**. All 48 HIGH/URGENT issues sat at
+`notificationCount` 4 — the last rung of the ladder — having sent nothing.
+
+**Root cause A (structural — the important one).** `processTechnicalIssue()` returned early when
+the ClickUp task would read identically (priority already correct **and** count unchanged), and
+**that `return` sat before the `if ($shouldNotify)` block.** `persistIssueState()` still ran on the
+way out with `didNotify: $shouldNotify`, stamping `dtLastNotified` and incrementing
+`notificationCount`. So a run that sent nothing still **consumed a rung** of the
+30/60/240/1440-minute `REMINDER_INTERVAL_MINUTES` ladder — and since a live issue normally sits at
+a settled priority with an unchanged count, that was **nearly every run**.
+
+Fix: the ClickUp write is now skipped on its own merits, inside
+`if ($needsPriorityWrite || $hasCountChanged)`, and the notification decision is made
+**independently, below it**.
+
+> **Lesson worth generalizing: "does ClickUp need writing?" and "does anyone need telling?" are two
+> separate questions.** Conflating them into one early return silenced the entire reminder ladder
+> while every metric reported success.
+
+**Root cause B.** Both send paths built a `_Email` and called `->send()` **inline inside the cron's
+open `DB_LOGS` transaction**. `_Email::send()` resolves the client's log database, registers a
+second connection and toggles the read host from in there; anything it threw was caught into
+`error_log` only — invisible in the console *and* in the run summary. Both paths now **enqueue via
+`_Worker::runTask`**, so a failure is a visible failed `WorkerJobs` row.
+
+### `emailFailures` in the run summary
+
+`Escalate()`'s JSON gained **`emailFailures`**, threaded through `processIssue()` /
+`processTechnicalIssue()`'s outcome arrays and counting notifications that were *meant* to go out
+and did not. It is reported **separately from `failures`** (which counts issues that threw). It
+exists specifically so the failure mode above — `emailsSent:0` with `failures:0` reading as
+healthy — cannot recur silently.
+
 ### Notification and task presentation
 
 - The technical escalation email to **devteam@togatech.com** now **coexists** with the ClickUp
   update. It was an `elseif`, so only one of the two ever fired.
+- **The technical escalation email uses the TOGA Technology stored email template.**
+  `sendTechnicalEscalationEmail()` enqueues **`Notification/EmailTemplate/Send`** with
+  `clientIdentifier` `'True'` and
+  `_Worker_Client_True::EMAIL_TEMPLATE_UUID__TOGA_TECHNOLOGY`
+  (`232d4edb-c2fa-4a8b-b5b9-d5800c962e19`) — the same pattern `Team/Transcripts.php` uses. Verified
+  against `Client_True.EmailTemplates`: `isActive = 1`; `{subject}` appears in **both** the subject
+  line and the branded header banner; `{body}` sits inside a **600px-wide** content cell that
+  already sets Plus Jakarta Sans 16px; the row carries its own `sendFromEmailAddress`
+  (`noreply@togatech.com`) and a single priority column (`NORMAL`).
+  - **`buildTechnicalEmailBody()` is therefore a FRAGMENT, not a document.** Its wrapper was
+    changed from `max-width:680px` + its own `font-family` to `max-width:100%` and no font —
+    680px would overflow the template's 600px cell.
+  - **Per-send priority is not available on the template path**, so urgency rides in the subject
+    and body instead.
+- **Business-issue emails moved to `Notification/Email/Send`**, which *does* keep per-client log
+  attribution and per-send priority.
 - ClickUp titles carry the **reference only** — `[1E]`, not `[1E-1]`. Including the occurrence
   number made the title churn on every escalation.
 - **Occurrences** and **Last Occurrence** custom fields are synced, and task bodies open with a
@@ -172,6 +231,13 @@ this controller needs the same treatment.**
 
 ## Gotchas / known issues
 
+- **Never send email inline inside this cron's open transaction — enqueue it.** `_Email::send()`
+  registers a second connection and toggles the read host, and a throw from in there was only ever
+  `error_log`'d. Use `_Worker::runTask` so a failure becomes a visible failed `WorkerJobs` row.
+- **A "nothing changed, return early" shortcut must not sit above the notification block.** It
+  consumed reminder-ladder rungs without sending anything, for months, while reporting
+  `emailsSent:0 / failures:0` as success. Decide the outbound write and the notification
+  independently.
 - **Persist state before, or independently of, any outbound call.** A regression chain took the
   whole run down every minute: `syncCustomFields()` read `$issue->dtLastOccurred`, which
   `loadWorkingSet()` never selected; `_Error::errorHandler()` promotes the undefined-property
@@ -207,6 +273,25 @@ this controller needs the same treatment.**
 
 ## Change history
 
+- 2026-08-04 (later, **uncommitted/undeployed** at time of writing) — **Fixed: escalation email had
+  never been sent, ever**, for two independent reasons. (A) `processTechnicalIssue()` returned early
+  when the ClickUp task would read identically, and that return sat *above* the `if ($shouldNotify)`
+  block while `persistIssueState()` still stamped `dtLastNotified`/`notificationCount` on the way
+  out — so nearly every run silently consumed a rung of the 30/60/240/1440-minute ladder; all 48
+  HIGH/URGENT issues had reached rung 4 having sent zero mail. The ClickUp write is now gated on its
+  own merits (`$needsPriorityWrite || $hasCountChanged`) and the notification decision is made
+  independently below it. (B) Both send paths built `_Email` and called `->send()` **inline inside
+  the open `DB_LOGS` transaction**, where a throw was only `error_log`'d — both now enqueue via
+  `_Worker::runTask`. **Built:** the technical escalation email now goes through the stored TOGA
+  Technology template (`Notification/EmailTemplate/Send`, clientIdentifier `True`,
+  `_Worker_Client_True::EMAIL_TEMPLATE_UUID__TOGA_TECHNOLOGY`), which makes
+  `buildTechnicalEmailBody()` a fragment (`max-width:100%`, no font — 680px would overflow the
+  template's 600px cell) and removes per-send priority (urgency moves into the subject/body);
+  business emails moved to `Notification/Email/Send`, which keeps per-client log attribution and
+  priority. **Built:** an **`emailFailures`** counter in `Escalate()`'s run summary, separate from
+  `failures`, so `emailsSent:0 / failures:0` can never read as healthy again. Verified by reading
+  only — proof will be `emailsSent` going non-zero (or `emailFailures` naming the problem) on the
+  first Escalate run after the worker2 deploy. (jcardinal)
 - 2026-08-04 — **Fixed: worker job failures were never captured at all** — worker2's front
   controller catches `Throwable` and returns 200, so six catch sites in
   `worker2/Controller/Index.php` now call `_Error::captureException()` after rollback and before the

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

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
-owners: ["mhammontree"]
+updated: 2026-08-04
+owners: ["mhammontree", "jcardinal"]
 files:
   - worker2/Worker/Notification/Email.php
   - _underscore/Model/Client/EmailTemplate.php
@@ -39,7 +39,7 @@ migration backfilled first).
 - `worker2/Worker/Notification/Email.php` — `abstract _Worker_Notification_Email`. One method:
   `Send(string $clientIdentifier, string $subject, string $body, string|array $to=[],
   string|array $cc=[], string|array $bcc=[], string $fromEmail='donotreply@togatech.com',
-  string $fromName='TOGA Technology')`. The entry point. Self-registers the client DB (no
+  string $fromName='TOGA Technology', ?int $priority=null)`. The entry point. Self-registers the client DB (no
   `initialize()` — see below), wraps the body, and sends.
 - `_underscore/Model/Client/EmailTemplate.php` — supplies `WRAPPER_UUID` and
   `renderWrappedBody($subject, $body)`. Documented in
@@ -69,6 +69,20 @@ migration backfilled first).
 5. **Send** via a plain `_Email`: `setClientIdentifier`, `addTo/Cc/Bcc`, `setFrom`,
    `setSubject`, `setBody($wrapped ?? $raw)`, `send()`.
 
+### Optional per-send priority (added 2026-08-04)
+
+The trailing **`?int $priority = null`** maps to `_Email::setPriority()`, which emits the
+`X-Priority` / `Importance` / `X-MSMail-Priority` headers. Omit it and nothing changes — the
+dispatcher spreads **named** parameters, so a new trailing optional parameter is backward
+compatible for every existing caller and queued job.
+
+It was added so that moving the error pipeline's **business** escalation email off an inline
+`_Email` and onto this worker did not silently drop the urgency headers (see
+[error-escalation-cron](./error-escalation-cron.md)). Note the sibling
+[`Notification/EmailTemplate/Send`](./notification-email-template.md) path has **no** per-send
+priority — a stored template carries its own single priority column — so urgency there has to live
+in the subject and body.
+
 ### Enqueuing it
 
 `_Worker::runTask('Notification/Email/Send', ['clientIdentifier'=>…, 'subject'=>…, 'body'=>…, …])`
@@ -130,6 +144,11 @@ working recipe — verified in classic + new Outlook:
   are replaced simultaneously, so a `{body}` literal inside the subject can't be re-expanded.
 
 ## Change history
+- 2026-08-04 (**uncommitted/undeployed** at time of writing) — Added an optional trailing
+  `?int $priority = null` to `Send()`, mapping to `_Email::setPriority()`
+  (`X-Priority`/`Importance`/`X-MSMail-Priority`). Backward compatible because the dispatcher
+  spreads named parameters. Added so the error pipeline's business escalation email kept its urgency
+  headers when it moved off an inline `_Email` onto this worker. (jcardinal)
 - 2026-06-24 — Built the DB-driven notification-email mechanism (TRUE-79240): new
   `_Worker_Notification_Email::Send` entry point; branded shell moved out of code (deleted
   `_underscore/Email/Template.php`, which also carried the 1.0 double-render bug) into a reserved

package/knowledge/2.0/apps/worker2/features/talos-pricing-automation.md

@@ -1,16 +1,20 @@
 ---
-title: Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)
+title: Talos Pricing Automation (worker2 Cron — Usage Import, AWS Actuals, Margins, Profiles)
 framework: "2.0"
 repo: worker2
 project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-08-04
 owners: [jcardinal]
 files:
   - worker2/Worker/Talos/Pricing.php
   - worker2/Database/TalosPricingCrons.sql
+  - dbchanges2/Team/2026-08-03a - TalosPricingTokenCostModel.sql
+  - dbchanges2/Team/2026-08-03b - TalosInternalTenant.sql
+  - dbchanges2/Team/2026-08-03c - TalosIntegrationCostFactor.sql
+  - dbchanges2/Core/2026-08-03a - Talos pricing cron jobs.sql
 related:
   - ./creating-worker-actions.md
   - ../architecture.md
@@ -21,64 +25,140 @@ related:
 
 ## Summary
 
-The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model`
-and tools `talos-pricing-ui` docs for the other halves). `_Worker_Talos_Pricing` is an
-**abstract** worker class with three monthly cron actions that turn raw usage/cost data
-into per-client margin tracking and a leadership report. All state lives in the **Team DB**
-(9 `Talos*` tables — schema home is the platform architecture doc); the worker reads/writes
-it via `_underscore::DB_TEAM`.
+The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and
+tools `talos-pricing-ui` docs for the other halves). `_Worker_Talos_Pricing` is an
+**abstract** worker class whose monthly cron actions turn raw usage and AWS cost data into a
+measured platform **unit price per 1k tokens**, per-client cost, and margin tracking. All
+state lives in the **Team DB** (`Talos*` tables), reached via `_underscore::DB_TEAM`.
 
-This replaces the Excel "Actuals" tab as the monthly recompute mechanism. The COGS token
-economics are unchanged — only the delivery/automation changed.
+**Switched on and verified in production 2026-08-03** for period `2026-07-01`. Before that
+every `Talos*` table was empty, the crons were never registered as `Core.CronJobs` rows, and
+the estimator ran only on placeholder constants — i.e. the platform was built but had never
+run. It now reconciles to the AWS bill exactly: July 2026 = **$1,013.76** (True-tagged
+$549.18 + untagged $464.58 + Towfoundation $0.0016), measured unit price
+**$0.00392447 / 1k tokens**.
 
 ## How it works
 
-`initialize()` registers the Team DB connection via `_underscore::DB_TEAM` (same pattern as
-`_Worker_Team_Transcripts`) so every action has it. The three actions are registered as
-`Core.CronJobs` rows (no code wiring — see `creating-worker-actions`), fired on the **4th of
-the month**, sequenced 06:00 / 07:00 / 08:00 Central so each step's inputs are present
-before the next runs.
-
-### 1. ImportAwsActuals (06:00)
-Calls AWS Cost Explorer `GetCostAndUsage` per client, filtered by `LINKED_ACCOUNT` or a
-cost-allocation **tag** (assumed key `Client` — open item, confirm). Upserts one row per
-`(clientIdentifier, periodMonth)` into `TalosAwsActualsMonthly`. The AWS Cost Explorer SDK
-is vendored in `worker2/vendor`.
-
-### 2. RecomputeMargins (07:00)
-The core calibration step. For each client/month:
-- **Calibration factor** = `AWS_actual / Langfuse_costCorrected` (write to
-  `TalosCalibrationMonthly`, `DECIMAL(14,8)`). Always use Langfuse's **cache-corrected**
-  cost — Langfuse badly undercounts cache cost (sample: $201 recorded vs $1,088 corrected).
-- **New clients** (no AWS history) use a **global blended factor** = `SUM(aws) / SUM(langfuse)`
-  across all clients, until they have their own rolling-3-month factor.
-- Apply the factor to Langfuse's granular per-feature/per-user structure so **structure comes
-  from Langfuse, absolute dollars from AWS**.
-- Compute per-client margin vs. the client's min/max band, update the consecutive out-of-band
-  **streak**, and only emit a `TalosFeeRecommendations` row once the streak ≥ the client's
-  configured `consecutiveMonths`.
-
-### 3. MonthlyReport (08:00)
-Builds an `.xlsx` with **PhpSpreadsheet** (vendored at
-`_underscore/Component/Library/PhpOffice` — first use in worker2) and sends a templated
-leadership email via `_Model_Client_EmailTemplate::send(...)` to the `True` client,
-rendering `{var}` placeholders through AWS SES.
+`initialize()` registers the Team DB connection via `_underscore::DB_TEAM`. The four actions
+are `Core.CronJobs` rows (no code wiring — see `creating-worker-actions`), fired on the
+**4th of the month** at 06:00 / 07:00 / 08:00 / 09:00 Central.
+
+**The order is load-bearing:** `ImportUsage` → `ImportAwsActuals` → `RecomputeMargins` →
+`RecomputeProfiles`. Each step's inputs are the prior step's outputs; running them out of
+order produces wrong prices rather than an error.
+
+**Why the 4th, not the 1st:** the usage API's `token_data_as_of` lagged ~5 days. Reading a
+partial month understates the token denominator and therefore **inflates** the unit price.
+
+### 1. ImportUsage (06:00)
+Pulls token/activity data from the Talos usage API into `TalosUsageMonthly` (now split by
+token class) and `TalosUsageModelMonthly` (model mix per client-month).
+
+**The API cannot return an arbitrary past calendar month.** It answers only `7d` / `30d` /
+`mtd` / `ytd`, and its xlsx export carries only MTD and YTD sheets. A calendar month is
+therefore derived by **differencing two year-to-date snapshots**, persisted in
+`TalosUsageSnapshots`. Three edge cases are handled explicitly:
+- **First-ever run** — no prior snapshot, so it falls back to the `30d` window and flags the
+  row `API_30D_APPROX`.
+- **January year-rollover** — detected, so YTD resetting to zero is not read as negative usage.
+- **Multi-month gap** — flagged `API_YTD_ROLLOVER_GAP` rather than passed off as a clean month.
+
+The proper fix is a `from_date`/`to_date` parameter on `/api/usage/overview`; the refresh
+endpoint already accepts `from_date`, so the backend plumbing exists. Open with the Talos
+backend developer.
+
+### 2. ImportAwsActuals (07:00)
+AWS Cost Explorer `GetCostAndUsage`, upserted per `(clientIdentifier, periodMonth)` into
+`TalosAwsActualsMonthly`, which now records `unitCostPer1kTokens`, `serviceScope`, and the
+tagged/untagged cost split. Three defects found and fixed here — see Gotchas; each one alone
+made every quote wrong.
+
+Untagged spend is attributed to the **defaultTenant**, and every row records
+`isDefaultTenantApplied` so the day a second tenant makes that attribution wrong is visible.
+
+### 3. RecomputeMargins (08:00)
+Computes `clientMonthlyCost = client tokens × unitCostPer1kTokens`, margin vs. the client's
+band, the consecutive out-of-band streak, and emits a `TalosFeeRecommendations` row only once
+the streak ≥ the client's `consecutiveMonths`. **Internal tenants are excluded from fee
+recommendations** (see below). The old per-client "calibration factor" is gone.
+
+### 4. RecomputeProfiles (09:00)
+Recomputes the measured workload profiles (`TalosWorkloadProfiles`) and the measured cost
+factors from actual tool-mix data.
+
+### Measured vs. policy cost factors
+`TalosCostFactors` is now split by `isDerived` / `isValidated` (plus `name`, `description`).
+**Derived rows are worker-owned and must never be hand-edited** — the tools Settings page
+enforces this server-side with `UPDATE ... AND isDerived = 0`.
+
+### Internal tenants
+`TalosClients.isInternal` (migration `2026-08-03b`). True is TOGA Technology, not a paying
+client, but it holds nearly all usage and — via `defaultTenant` — all untagged AWS spend, so
+it **must** exist as a row or there is no unit price at all. Modelling it as a zero-revenue
+contract made every margin figure lie (margin computes as 0%, so it sits permanently in
+"Needs attention" and drags blended portfolio margin negative). Internal tenants are
+**costed and do feed the platform unit price** (our own usage consumes real Bedrock capacity)
+but are **excluded from `TalosFeeRecommendations`**.
+
+### Schema (dbchanges2 migrations, 2026-08-03)
+- **Team `2026-08-03a` TalosPricingTokenCostModel** — token split on `TalosUsageMonthly`;
+  `unitCostPer1kTokens` / `serviceScope` / tagged+untagged cost on `TalosAwsActualsMonthly`;
+  measured-vs-policy split on `TalosCostFactors`; new `TalosWorkloadProfiles`,
+  `TalosUsageModelMonthly`, `TalosUsageSnapshots`, `TalosContractAmendments`; seeds 13 cost
+  factors and 3 workload profiles.
+- **Team `2026-08-03b` TalosInternalTenant** — `isInternal` on `TalosClients`.
+- **Team `2026-08-03c` TalosIntegrationCostFactor** — `tokensPerIntegrationPerUser`.
+- **Core `2026-08-03a` Talos pricing cron jobs** — registers the 4 crons.
+
+### Configuration
+The existing `[talos]` config group gains **`usage_url`** and **`usage_api_key`** (the same
+values the tools app holds as `[api] talos_backend_url` / `talos_backend_key`). Keys are
+referenced by name only.
 
 ## Gotchas / open items
+
+- **AWS cost query — three defects that all produced badly wrong prices** (found 2026-08-03):
+  1. **No service filter.** The query summed every dollar in the linked account (RDS alone is
+     ~$9,917/mo), so one client would have been charged ~$18k instead of ~$1k.
+  2. **Wrong tag key.** It filtered `Tags.Key='Client'`; no such tag exists. The activated
+     cost-allocation tag is **`tenant`** (activated alongside `model` and `model_role`).
+  3. **Service-name trap.** AWS bills **each Claude model as its own service**
+     ("Claude Sonnet 4.5 (Amazon Bedrock Edition)", etc.). Filtering the literal
+     `"Amazon Bedrock"` captured **3.3%** of real model spend — $31.49 of $1,013.76 for July
+     2026. The family had 8 members in July and grows with every model launch, so the member
+     list must be resolved **at run time** via `ce:GetDimensionValues --search-string "Bedrock"`
+     and **snapshotted per row**. Never hardcode the service list.
+- **IAM:** the EB instance role now needs **`ce:GetDimensionValues`** in addition to
+  `ce:GetCostAndUsage`.
+- **Cost-allocation tagging went live 2026-07-16.** Before that, 100% of Bedrock spend is
+  untagged (June 2026: $798.44) and is **not recoverable per-tenant**. After, untagged fell to
+  ~8% for the rest of July and 0.8% in August. The gap is **temporal and self-correcting**,
+  not structural: `defaultTenant` is a backfill mechanism with a shelf life.
+- **July's unit price is ~8% conservative** — the cost numerator is a full calendar month
+  while the token denominator was a 30-day rolling window (`API_30D_APPROX`). August
+  differences two snapshots and the windows align.
+- **Never use the usage API's dollar figures.** It reports cost ~2.5× **below** the real AWS
+  bill because it undercounts prompt caching (cache reads are 47% of True's tokens). Its
+  **token counts** are a real measurement and are used; its dollars never are.
 - **Idempotent upsert key** — every fact table is keyed `(clientIdentifier, periodMonth)`
-  (usage-by-feature adds `toolCategory`), with a UNIQUE on those columns, so re-running a
-  cron is safe.
-- **`REPORT_EMAIL_TEMPLATE` is a placeholder UUID** — needs a real `EmailTemplates` record in
-  `Client_True` before MonthlyReport sends.
-- **`_Email` attachment support unconfirmed** — verify before relying on the xlsx attachment.
-- **AWS cost-tag key assumed `Client`** — confirm against the actual cost-allocation tag.
-- **Importer contract (other dev):** `TalosUsageMonthly` + `TalosUsageFeatureMonthly` are the
-  Langfuse → MySQL targets. Map the Langfuse org tag `org:True` → `clientIdentifier` `"True"`;
-  upsert on `(clientIdentifier, periodMonth[, toolCategory])`.
+  (usage-by-feature adds `toolCategory`) with a UNIQUE, so re-running a cron is safe.
+- **Tow Foundation has no token extract** — `/api/usage/overview` returns 83 messages /
+  10 conversations / 2 users for ytd but `tokens=0`, `cost=$0`, and nothing in the last 30
+  days; their tagged AWS spend was $0.0016 for July, far too low for 83 real questions. The
+  activity counters and the token/cost extract are **separate sources with their own
+  `token_data_as_of` high-water mark**, and the extract appears never to have run for that
+  org. "Refresh token data" does not populate it. Note the Talos Postgres DB the weekly
+  report queries is named **`tenant_true`**, hinting at per-tenant databases — if the extract
+  job points at that one DB, no refresh will ever produce Tow Foundation tokens. With the
+  Talos backend developer.
 
 ## Security
-- Hardcoded AWS SES SMTP credentials live in `_underscore/Email.php` (pre-existing, not
-  introduced here) — flagged for rotation. Location only; no values recorded.
+- Config keys referenced by name only (`[talos] usage_url` / `usage_api_key`); no values are
+  recorded anywhere in the knowledge base.
+- Hardcoded AWS SES SMTP credentials live in `_underscore/Email.php` (pre-existing) — flagged
+  for rotation. Location only.
 
 ## Change history
+- 2026-08-04 — **Platform switched on and verified in production** for 2026-07. Cost model replaced: per-client calibration factor → measured **unit cost per 1k tokens** from the Bedrock-family AWS actual. Fixed three AWS cost-query defects (no service filter; wrong tag key `Client` → `tenant`; per-model service names resolved at run time via `ce:GetDimensionValues` and snapshotted — the literal "Amazon Bedrock" captured only 3.3% of spend). New actions `ImportUsage` + `RecomputeProfiles`; `ImportAwsActuals`/`RecomputeMargins` rewritten; crons on the 4th at 06/07/08/09:00 in a load-bearing order. Calendar months derived by differencing YTD snapshots (`API_30D_APPROX` / `API_YTD_ROLLOVER_GAP` flags). Added `isInternal` tenants (costed, feed the unit price, excluded from fee recommendations). New `[talos] usage_url`/`usage_api_key` config keys and `ce:GetDimensionValues` IAM permission. (jcardinal)
 - 2026-06-29 — Built `_Worker_Talos_Pricing` (abstract) with 3 monthly crons — ImportAwsActuals (Cost Explorer), RecomputeMargins (calibrate Langfuse→AWS, rolling-3mo + global-blended fallback, margin/streak/recommendation), MonthlyReport (PhpSpreadsheet xlsx + templated SES email to True). Registers Team DB via `_underscore::DB_TEAM`; crons are `Core.CronJobs` rows on the 4th, 06/07/08:00 CT. Replaces the Excel "Actuals" recompute. (jcardinal)

package/knowledge/clients/tow-foundation/profile.md

@@ -3,12 +3,14 @@ title: "Tow Foundation"
 framework: "2.0"
 apps:
   - worker2
+  - tools
+  - dbchanges2
 project: Worker
 client: tow-foundation
 type: profile
 status: active
-updated: 2026-06-11
-owners: ["rgirish"]
+updated: 2026-08-04
+owners: ["rgirish", "jcardinal"]
 files: []
 related:
   - clients/tow-foundation/features/receipt-processing.md
@@ -23,6 +25,23 @@ and exported as QuickBooks-ready Excel files.
 
 No client database is used (no persistence beyond SharePoint and email).
 
+## Talos Pricing — first external client
+
+Tow Foundation is the **first real external Talos client** (`clientIdentifier` `Towfoundation`).
+A contract was created and signed through the tools Contracts page on 2026-08-03.
+
+**Open issue — no token extract exists for this org.** `/api/usage/overview` returns 83
+messages / 10 conversations / 2 users for `ytd` but `tokens = 0` and `cost = $0`, and nothing
+at all in the last 30 days; their tagged AWS spend was **$0.0016** for July, far too low for
+83 real questions. The activity counters and the token/cost extract are separate sources with
+their own `token_data_as_of` high-water mark, and the extract appears never to have run for
+this org — "Refresh token data" does not populate it. The Talos Postgres DB the weekly report
+queries is named `tenant_true`, hinting at per-tenant databases; if the extract job points at
+that one DB, no refresh will ever produce Tow Foundation tokens. With the Talos backend
+developer. Until it is fixed, this client has **no measurable usage and no real margin
+figure**. See
+[talos-pricing-automation](../../2.0/apps/worker2/features/talos-pricing-automation.md).
+
 ## Contacts
 
 - **Jheanelle Gordon** — primary contact; receives the processing completion email

package/knowledge/clients/true/profile.md

@@ -11,7 +11,7 @@ project: _Underscore
 client: true
 type: profile
 status: active
-updated: 2026-07-24
+updated: 2026-08-04
 owners: [jcardinal, kyalamarthi]
 files: []
 related:
@@ -39,3 +39,15 @@ The **Tools** app (1.0; repo `tools`) authenticates True users via **SSO** throu
 staff persona (see `1.0/apps/tools/`). Its gateway return domain is registered in `Core.Domains`
 (`uuid 2927bc15-e347-4358-a430-fb28f9446d27`, `clientId 1`, `appId 30`, env 1,
 `https://tools.togatech.com/sso`).
+
+### Talos Pricing — the internal tenant
+
+True is an **internal tenant** in the Talos Pricing platform (`TalosClients.isInternal = 1`,
+formal name **TOGA Technology**), not a paying client. It holds nearly all Talos usage and,
+via `defaultTenant`, all untagged AWS Bedrock spend, so it **must** exist as a contract row
+or there is no platform unit price at all. It is **costed and feeds the unit price** but is
+**excluded from fee recommendations** — modelling it as a zero-revenue contract made margin
+compute as 0%, parking it permanently in "Needs attention" and dragging blended portfolio
+margin negative. A contract row was created and signed 2026-08-03. Measured July 2026:
+$549.18 tagged of a $1,013.76 total. See
+[talos-pricing-automation](../../2.0/apps/worker2/features/talos-pricing-automation.md).

package/package.json

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