toga-ai 1.0.507 → 1.0.508

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/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/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

@@ -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/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.508",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",