toga-ai 1.0.227 → 1.0.229

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

@@ -4,6 +4,8 @@
 |-----|---------|-------|
 | [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
 | [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 |
+| [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 |
 | [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 |
+| [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 |
 | [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 |

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

@@ -0,0 +1,77 @@
+---
+title: Tools MVC — Routing, CSRF & App_Database Access Patterns
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [jcardinal]
+files:
+  - tools/_/app/nav.php
+  - tools/mvc/get.php
+related:
+  - ./persona-gated-navigation.md
+  - ../architecture.md
+  - ../../library/features/mvc-page-pattern-and-app-skeleton.md
+---
+
+## Summary
+
+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_Database` — with the gotchas
+that bite if you assume the legacy 1.0 behavior. Discovered while building the Talos Pricing
+UI; these apply to any tools-app page.
+
+## Routing
+- `App_MVC::parseRoute` maps a URL to `mvc/<segments>/<method>.php`: **GET → `get.php`,
+  POST → `post.php`**.
+- **Writes use `mvc/<route>/post.php`** — NOT the legacy
+  `App_FrameworkIndex::actionHandler` `targetAction → app/<x>.php` path. A form posts to the
+  same route as its GET page; the `post.php` handler does the write and redirects.
+
+## Nav persona narrowing (gotcha)
+`App_Nav::personasForRoute()` returns the **union** of folder + action personas. A page that
+must be **narrower** than its folder (e.g. a technical-only editor inside a broader folder)
+must `requireAuth()` the narrow persona set **explicitly** — do not pass
+`personasForRoute()`, or the page inherits the wider folder grant. (See
+`persona-gated-navigation` for the nav model.)
+
+## CSRF
+`App_Page::validateCrossSiteRequestForgery()` is **Origin/Referer-based**: for any non-GET
+request the request host must equal `HTTP_HOST`. **No hidden token field is needed** — do not
+add one expecting the framework to validate it.
+
+## App_Database
+- Query: `App_Database::query($sql, $alias)`.
+- Row helpers: `buildArrayOfRows(&$res, $includeNumericIndexes)`, `fetchOne(&$res)`,
+  `fetchRow(&$res, true)`.
+- Escaper is `App_Database::sqlEscape()` — **not** `::escape`. (Prefer parameterized queries
+  per the security rules; `sqlEscape()` is the framework escaper when needed.)
+- Transactions: `beginTransaction` / `commitTransaction` / `rollbackTransaction`.
+- **Connections** come from `config.*.ini` `[database_<x>]` → alias `db_<x>`. A page can read a
+  2.0 DB read-only through its own connection (e.g. `db_true → Client_True`); adding
+  `db_team → Team` is the same pattern.
+
+### Gotcha — by-reference row helpers
+`buildArrayOfRows`, `fetchOne`, and `fetchRow` take `$res` **by reference**. Assign the
+`query()` result to a **variable first**, then pass it — passing the call result inline emits
+PHP "Only variables should be passed by reference", which **renders to the page** when
+`display_errors` is on.
+
+```php
+// WRONG — warning leaks to the page
+$rows = App_Database::buildArrayOfRows(App_Database::query($sql, 'db_team'), false);
+
+// CORRECT
+$res  = App_Database::query($sql, 'db_team');
+$rows = App_Database::buildArrayOfRows($res, false);
+```
+
+## Autoloader
+`App_Foo_Bar` → `app/foo/bar.php`, **all lowercase** (per the library CLAUDE.md). E.g.
+`App_Talos_Estimator` → `_/app/talos/estimator.php`.
+
+## Change history
+- 2026-06-29 — Documented tools MVC routing (GET→get.php / POST→post.php; writes via mvc/<route>/post.php, not the legacy actionHandler path), Origin/Referer CSRF (no token field), `App_Database` query/row/txn API + `sqlEscape()` name, the by-reference row-helper warning gotcha, the persona-narrowing gotcha, and the lowercase autoloader mapping. Discovered building the Talos Pricing UI. (jcardinal)

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

@@ -0,0 +1,94 @@
+---
+title: Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+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/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
+related:
+  - ./persona-gated-navigation.md
+  - ./mvc-data-access-patterns.md
+  - ../architecture.md
+  - ../../../2.0/apps/talos/architecture.md
+  - ../../../2.0/apps/talos/features/pricing-cogs-model.md
+  - ../../../2.0/apps/worker2/features/talos-pricing-automation.md
+---
+
+## 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).
+
+## 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()`.
+
+### 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.
+
+### 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`).
+
+### 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.)
+
+### 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**.
+
+### 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").
+
+## 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`.
+
+## 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.
+
+## Change history
+- 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/INDEX.md

@@ -12,6 +12,6 @@
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
-| [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
+| [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -11,6 +11,8 @@ owners: [jcardinal]
 files:
   - _underscore/Model/Core/Surface.php
   - dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql
+  - dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql
+  - dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql
   - _underscore/Model/Core/SurfaceElement.php
   - _underscore/Model/Core/Action.php
   - _underscore/Model/Core/Vocabulary.php
@@ -88,6 +90,20 @@ resolver, not "later"). It is **not** named `debug()` — see gotchas.
 
 ## Gotchas
 
+- **A Core RecordScript needs `Client.AclRecordScripts` rows per role to be invokable — record-level
+  `AclRecordPermissions` is necessary but NOT sufficient.** V2 authorizes a scripted-API call **not**
+  via `AclRecordPermissions` but via the Client-DB `AclRecordScripts` table
+  (`V2.php getRecordScriptPhpMethod: SELECT ... FROM AclRecordScripts WHERE recordScriptId=? AND
+  roleId IN(...)`). The original Surface ACL seed built the record-level `AclRecordPermissions` chain
+  (Public(1) READ on `surfaces`) but MISSED the per-role dispatch grants, so every meta call 403'd
+  (EZ-1) even though record-level READ was granted. Fix: grant the surfaces `meta` script to roles
+  Public(1)/SuperUser(3)/Base(4) and the `debug` (metaDebug) script to SuperUser(3) — mirrors the
+  existing TableView/Page `meta` scripts. The grant migration is **id-agnostic** (resolves
+  `recordScriptId` by route join, so it works on the renumbered 333 block or the originally-provisioned
+  2300 block) and **NOT EXISTS-guarded** (re-runnable). ⚠ Provisioning risk: a `BLANK_CLIENT_DATABASE`
+  snapshot may not carry these `AclRecordScripts` rows, so a newly-cut client could repeat the 403
+  unless the dated migrations replay on provision — confirm BLANK-snapshot vs migration-replay before
+  the next client is cut.
 - **`_Model_Core_Page::meta()` (Model/Core/Page.php, ~1300 lines) is the engine being replaced** and
   is dangerous to extend: it interpolates `LIKE '$slug'` (injection-prone), **runs INSERTs during a
   read**, is N+1, hand-duplicates the 5-layer cascade 6× via UNION, and is uncached. The empirical
@@ -104,7 +120,11 @@ resolver, not "later"). It is **not** named `debug()` — see gotchas.
   framework base `_Model` defines a NON-static `debug()` (Model.php:167) and the scripted-API
   dispatch calls the method statically. Renamed to `metaDebug` and remapped the RecordScript
   (`route 'debug' → phpMethod 'metaDebug'`). Vet any new scripted-API method name against the
-  `_Model` base (e.g. `debug`, and check others) before mapping it.
+  `_Model` base (e.g. `debug`, and check others) before mapping it. **Already-provisioned envs are a
+  latent fatal:** the rename landed in code + the renumbered seed, but envs provisioned before it
+  (dev.sandbox) keep the old `phpMethod='debug'` and would fatal if `GET /v2/surfaces/debug` were hit.
+  Ship an id-agnostic idempotent `UPDATE` (`SurfaceDebugPhpMethodFix.sql`) to repoint the existing
+  RecordScript on those envs.
 - **The endpoint is `GET /v2/surfaces/meta?slug=<slug>`, not `/v2/surfaces/<slug>/meta`.** TOGA
   RecordScripts read their args from the **query string**; the path form makes the engine parse the
   slug as a record uuid and return 404 EV-6. Pattern for any RecordScript:
@@ -118,6 +138,12 @@ resolver, not "later"). It is **not** named `debug()` — see gotchas.
   admin-CRUD sibling records stay Super-User-only (the resolver reads their tables server-side).
 
 ## Change history
+- 2026-06-29 — Deploy fixes (round 2): grant the surfaces `meta`/`debug` RecordScripts in
+  `Client.AclRecordScripts` per role (Public/SuperUser/Base) — record-level `AclRecordPermissions`
+  alone left every meta call 403 EZ-1 because V2 dispatch authorizes via `AclRecordScripts`
+  (`SurfaceRecordScriptAcl.sql`, id-agnostic + NOT EXISTS-guarded). Shipped the id-agnostic idempotent
+  `SurfaceDebugPhpMethodFix.sql` to repoint the still-`debug` phpMethod on pre-rename envs (latent
+  fatal). Flagged BLANK-provision may not carry these dispatch grants. (jcardinal)
 - 2026-06-29 — Deploy fixes: renamed the scripted inspector `debug()`→`metaDebug()` (name collided
   with non-static `_Model::debug()`, fatal); corrected the endpoint to query-string form
   `GET /v2/surfaces/meta?slug=` (path form 404'd EV-6); granted CORE Public(1) READ on the `surfaces`

package/knowledge/2.0/apps/api2/features/surface-meta-option.md

@@ -50,8 +50,16 @@ traffic), behavior is **byte-for-byte unchanged** — pure data, zero extra work
   them. Grant Public(1) `allowRead` on `surfaces` only (the admin-CRUD sibling records stay
   Super-User-only — the resolver reads their tables server-side). See
   [surface-resolver](../../_underscore/features/surface-resolver.md) gotchas for the full chain.
+- **Record-level READ is necessary but NOT sufficient — dispatch is authorized via
+  `Client.AclRecordScripts`.** V2 (`getRecordScriptPhpMethod`) checks `AclRecordScripts` by
+  `recordScriptId` + `roleId`, not `AclRecordPermissions`. Even with Public(1) READ on `surfaces`,
+  meta 403'd until the `meta`/`debug` scripts were granted per role in `AclRecordScripts`. See
+  [surface-resolver](../../_underscore/features/surface-resolver.md) gotchas.
 
 ## Change history
+- 2026-06-29 — Documented the second ACL layer: scripted-API dispatch is authorized via
+  `Client.AclRecordScripts` (per `recordScriptId`+`roleId`), not record `AclRecordPermissions` —
+  record READ alone still 403'd meta until the dispatch grants were seeded. (jcardinal)
 - 2026-06-29 — Documented the meta-endpoint ACL: normal app users (CORE Public role 1) need
   `allowRead` on the `surfaces` record or meta returns 403 EZ-1. (jcardinal)
 - 2026-06-25 — Added the `surface=<slug>` opt-in option to the V2 engine; attaches per-record action

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

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -14,6 +14,10 @@ files:
   - dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql
   - dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql
   - dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql
+  - dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql
+  - dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql
+  - dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql
+  - dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
   - dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql
   - dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql
@@ -66,6 +70,24 @@ SurfaceElements`). Core migrations run first; Client after. The session built/se
 - `Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql` — Core seed + the `RecordScripts` resolve row.
 - `Core/2026-06-29a - ItemsSurfaceSeed.sql` — the Items LIST screen seed: surfaces `items-list` (TABLE → existing `items` TableView id 9, recordId 21) + `items-list-actions` (BUTTON_BAR: refresh/columns/newItem) + Actions + ~11 Messages. Single DEFAULT bundle, no Client overrides.
 - `Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql` — grants CORE role Public(1) `allowRead` on the `surfaces` record (so app users stop getting 403 EZ-1 on meta). **Id-agnostic**: matches the record by `route='surfaces'`, so it works whether the record id is 333 or the legacy 2300.
+- `Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql` — id-agnostic idempotent `UPDATE` repointing the
+  surfaces `debug` RecordScript `phpMethod` from `debug`→`metaDebug` on already-provisioned envs (the
+  rename only landed in the renumbered seed; pre-rename envs would fatal on `GET /surfaces/debug`).
+- `Core/2026-06-29d - VendorItemsSurfaceSeed.sql` — the VendorItems LIST screen seed: `vendor-items-list`
+  (TABLE → existing `vendor-items` TableView id 10, recordId 19) + `vendor-items-list-actions`
+  (BUTTON_BAR: Refresh / Columns[hidden+disabled] / New Vendor Item) + 2 Actions + 11 Messages.
+  Single DEFAULT bundle, mirrors Items. (appId supply=1.)
+- `Core/2026-06-29e - InventorySurfaceSeed.sql` — the Inventory LIST screen, **presentation-only**:
+  `inventory-list` (TABLE, **recordId NULL + tableViewId NULL** — the page composes
+  purchase-orders/items/units via per-level fetchSlugs and has no single backing Record; carries
+  `groupByLabels` + `entityTags` in surface `config`) + `inventory-list-actions` (BUTTON_BAR:
+  Group by / Refresh). Actions anchored to `items(21)` because `Actions.recordId` is NOT NULL.
+- `Client/2026-06-29c - SurfaceRecordScriptAcl.sql` — grants the surfaces `meta`/`debug` RecordScripts
+  in **`Client.AclRecordScripts`** per role (meta → Public(1)/SuperUser(3)/Base(4); debug →
+  SuperUser(3)). V2 authorizes scripted-API dispatch via `AclRecordScripts`, NOT record
+  `AclRecordPermissions`, so record READ alone left meta 403 EZ-1. Id-agnostic (resolves
+  `recordScriptId` by route join) + NOT EXISTS-guarded (re-runnable). See
+  [surface-resolver](../../_underscore/features/surface-resolver.md).
 - `Client/2026-06-25a - SurfaceClientTables.sql` — the 3 Client tables + `INSERT IGNORE Languages('en','English')`.
 - `Client/2026-06-25b - SurfaceClientSeed.sql` — `ThemeTokens` + `MessageTranslations(en)`.
 - `Client/2026-06-25c - SurfaceClientAcl.sql` — full ACL chain for the 3 CLIENT-aclDatabase records (recordId refs updated to the 333-block renumber).
@@ -80,6 +102,12 @@ SurfaceElements`). Core migrations run first; Client after. The session built/se
   or every newly provisioned client is born broken. This was appended and provisioning-tested.
   Treat it as a CI gate (provision a throwaway client; assert the surface meta endpoint returns the
   seed).
+- **⚠ Unconfirmed: BLANK-provision may not carry the `AclRecordScripts` dispatch grants.** The
+  surface meta endpoint is authorized by `Client.AclRecordScripts` rows (see
+  [surface-resolver](../../_underscore/features/surface-resolver.md)), seeded by the dated
+  `SurfaceRecordScriptAcl.sql`. If a new client is cut from a BLANK snapshot rather than by replaying
+  the dated migrations, it could be born with no dispatch grants and repeat the 403 EZ-1. Confirm how
+  BLANK-snapshot vs migration-replay provisioning works before the next client is cut.
 - **`SurfaceOverrides.value` is a stringly-typed escape hatch** — a long `CONFIG`/label override
   would silently truncate at varchar(255); that is why `c_longValue mediumtext` exists, and the
   resolver MUST cast strictly per `attribute` (bool/int/string/json) with a logged fallback.
@@ -95,6 +123,11 @@ SurfaceElements`). Core migrations run first; Client after. The session built/se
   full 4-step ACL chain + field permissions in **each** client DB; resolve `roleId` by subselect.
 
 ## Change history
+- 2026-06-29 — Added VendorItems + Inventory LIST seeds (`VendorItemsSurfaceSeed.sql` recordId 19 /
+  TableView 10; `InventorySurfaceSeed.sql` presentation-only, recordId+tableViewId NULL, Actions
+  anchored to items(21)). Added `SurfaceRecordScriptAcl.sql` (per-role `AclRecordScripts` dispatch
+  grants — record READ alone 403'd) and `SurfaceDebugPhpMethodFix.sql` (repoint `debug`→`metaDebug`
+  on pre-rename envs). Flagged BLANK-provision may miss the `AclRecordScripts` grants. (jcardinal)
 - 2026-06-29 — Renumbered the reserved seed id blocks (Records 2300-2308→**333–341**, RecordFields
   2400+→**2246–2433**) in the seed files only — known file-vs-DB drift in provisioned envs. Added
   the Items LIST seed (`ItemsSurfaceSeed.sql`) and the id-agnostic CORE Public(1) READ ACL grant on

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

@@ -6,8 +6,8 @@ project: TOGa IQ
 client: shared
 type: architecture
 status: active
-updated: 2026-06-16
-owners: [akhokhani]
+updated: 2026-06-29
+owners: [akhokhani, jcardinal]
 files:
   - talos/libs/aegra-api/src/aegra_api/main.py
   - talos/libs/aegra-api/src/aegra_api/settings.py
@@ -28,6 +28,9 @@ related:
   - features/mcp-servers.md
   - features/observability.md
   - features/deployment.md
+  - features/pricing-cogs-model.md
+  - ../worker2/features/talos-pricing-automation.md
+  - ../../1.0/apps/tools/features/talos-pricing-ui.md
 ---
 
 ## Summary
@@ -152,6 +155,31 @@ lives (env var name, config key) but never the value itself.
   user-managed** (external). Health check hits `/live`. See
   `features/deployment.md`.
 
+## Talos Pricing Platform (cross-framework)
+
+A database-backed pricing/margin system replacing the Excel calculator. Three tiers:
+
+- **System of record — Team DB (9 `Talos*` tables, dbchanges2):** TalosClients (contract
+  header), TalosPricingBands (locked per-user band schedule), TalosCostFactors (editable
+  key/value cost constants — the "technical tab"), TalosUsageMonthly + TalosUsageFeatureMonthly
+  (Langfuse import targets), TalosAwsActualsMonthly (Cost Explorer), TalosClientUserCounts
+  (headcount for band-breach), TalosCalibrationMonthly + TalosFeeRecommendations (cron-derived).
+  Keyed by `clientIdentifier` (= Langfuse `org:<slug>` tag and AWS cost tag) + `periodMonth`
+  (1st-of-month DATE), UNIQUE on those for idempotent upsert. Tenant link to `Core.Clients` is a
+  plain **indexed column, not a hard FK** (Team DB may be a separate instance). Conventions:
+  id+uuid, dtCreated/dtUpdated, InnoDB, utf8mb4_0900_ai_ci.
+- **Sales/admin UI — tools (1.0):** onboarding (locks band schedule), dashboard, benchmarks,
+  technical-only Cost Factors editor + `App_Talos_Estimator`. Reads Team DB via `db_team`.
+- **Automation — worker2 (2.0):** monthly crons import AWS actuals, calibrate Langfuse→AWS,
+  recompute margins/recommendations, send the leadership report. Uses `_underscore::DB_TEAM`.
+
+**Data flow:** Langfuse usage (structure) + AWS Cost Explorer (dollars) → calibrate per client →
+margin vs. locked band → org-fee recommendation after N consecutive out-of-band months.
+
+**Critical rules:** Team-DB fact tables are upsert-keyed on `(clientIdentifier, periodMonth
+[, toolCategory])` — never INSERT-only. The Core tenant link is an indexed column, not an FK.
+Always use Langfuse's cache-corrected cost (it undercounts cache badly).
+
 ## Key decisions
 
 - **Agent Protocol over a custom shape** — clients (TOGa Hub, TOGa View, third-party)

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

@@ -13,20 +13,45 @@ related:
   - ../architecture.md
   - aegra-api.md
   - observability.md
+  - ../../worker2/features/talos-pricing-automation.md
+  - ../../../1.0/apps/tools/features/talos-pricing-ui.md
 ---
 
 ## Summary
 
 The cost basis and pricing methodology for selling Talos (TOGa IQ) chat and
-voice deployments. The deliverable is a **per-client Excel workbook — TALOS
-Pricing Calculator v9** (replaces v8) — that lives on the team's shared AI drive
-(under `P:\Work\AI\`), **not** in any repo. This doc captures the durable
-knowledge: the cost drivers, measured production rates, and the pricing
-decisions, so anyone can re-price Talos without re-deriving the model.
-
-There is no Talos source code behind this — it is a sales/finance model. Treat
-the numbers below as the **April 2026 baseline**; re-measure before relying on
-them in a later period.
+voice deployments. This doc captures the durable knowledge: the cost drivers,
+measured production rates, and the pricing decisions, so anyone can re-price
+Talos without re-deriving the model.
+
+The COGS token economics below remain valid. **The delivery mechanism has
+pivoted** (2026-06-29) from the per-client Excel workbook (TALOS Pricing
+Calculator v9) to a **database-backed platform**: a Team-DB system of record +
+an onboarding/dashboard UI in the **tools** app (1.0) + **worker2** cron
+automation that calibrates Langfuse usage to AWS actuals each month. Why: Excel
+can't scale and forced sales to guess inputs (esp. avg conversations/user) they
+don't know but we already have in Langfuse. See
+[talos-pricing-ui](../../../1.0/apps/tools/features/talos-pricing-ui.md) and
+[talos-pricing-automation](../../worker2/features/talos-pricing-automation.md);
+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)
+
+Langfuse provides the **structure** (granular per-feature / per-user breakdown);
+AWS provides the **absolute dollars**. Each month, per client:
+
+```
+calibration_factor = AWS_actual / Langfuse_costCorrected
+```
+
+Apply the factor to Langfuse's granular figures so structure comes from Langfuse,
+dollars from AWS. New clients (no AWS history) use a **global blended factor**
+(`SUM(aws) / SUM(langfuse)` across clients) until they have their own rolling
+3-month factor. **Langfuse badly undercounts cache cost** (sample: $201 recorded
+vs $1,088 corrected) — always use the **cache-corrected** Langfuse figure.
 
 ## Chat COGS model
 
@@ -111,31 +136,41 @@ approach. Per-minute drivers:
 
 Adopted to **reduce client-facing price fluctuation while protecting margin**:
 
-1. **Two-part price.** Client pays a **flat monthly org fee** PLUS a **fixed
-   monthly per-user fee**. The per-user fee is a stable rate-card value and does
-   **not** change.
-2. **Margin band.** Sales sets a min and max gross-margin band. The recommended
-   flat fee is solved so projected margin lands at the **midpoint** of the band:
-
-   ```
-   flat = COGS / (1 - mid_margin) - per_user_fee * users     (floored at 0)
-   ```
-3. **Smoothing rule.** Actual COGS is tracked monthly per client. The flat fee
-   is changed **only after** actual margin sits outside the band for a
-   configurable number of **consecutive** months (**default 3**). The per-user
-   fee is **never** adjusted.
-
-### Workbook structure (TALOS Pricing Calculator v9)
-
-| Tab | Purpose |
-|---|---|
-| Sales | Rep-facing inputs + recommended flat fee + min/mid/max margin-band options |
-| Voice | Per-minute band pricing |
-| Technical | Single source of truth for all raw rates — sales never edits |
-| Actuals | Monthly actual-AWS-COGS entry, margin-vs-band status, consecutive-breach flags, suggested mid-band flat fee |
-| Engine | Hidden calculation engine |
-
-The workbook is a **per-client** file on the shared AI drive (`P:\Work\AI\`).
+1. **Two-part price.** Client pays a **flat monthly org fee** (the adjustable
+   margin lever) PLUS a **per-user fee that steps by user-count band**.
+2. **Locked band schedule.** The per-user **band rate schedule** is fixed at
+   **contract signing**. When user count crosses a band, the per-user fee
+   auto-steps to the **pre-agreed band rate**; then the **org fee** is adjusted
+   to restore margin. The per-user fee **never changes outside the agreed band
+   schedule**.
+3. **Smoothing rule.** Actual margin is tracked monthly per client. The org fee
+   change is **only recommended after** margin sits outside the min/max band for
+   a configurable number of **consecutive** months (`consecutiveMonths`,
+   per-client; default 3).
+
+> **Pivot note (2026-06-29):** the earlier model used a *fixed* per-user fee +
+> flat fee solved to the band midpoint. The current model makes the per-user fee
+> a **locked band schedule** (steps with headcount) and uses the **org fee** as
+> the margin lever. The band schedule is stored in `TalosPricingBands`, locked at
+> signing in the tools onboarding UI.
+
+### Delivery (current — database platform)
+
+The model now lives across three repos (schema home + topology in the platform
+architecture doc):
+
+- **Team DB (9 `Talos*` tables)** — `TalosClients`, `TalosPricingBands`,
+  `TalosCostFactors`, `TalosUsageMonthly` + `TalosUsageFeatureMonthly`,
+  `TalosAwsActualsMonthly`, `TalosClientUserCounts`, `TalosCalibrationMonthly`,
+  `TalosFeeRecommendations`. (`dbchanges2/Team/...TalosPricingTables.sql`)
+- **tools app (1.0)** — onboarding (locks the band schedule), pricing dashboard,
+  usage benchmarks, technical-only Cost Factors editor + `App_Talos_Estimator`.
+- **worker2 (2.0)** — monthly crons: import AWS actuals, recompute calibration +
+  margins/recommendations, send leadership report.
+
+The previous **TALOS Pricing Calculator v9** Excel workbook (Sales / Voice /
+Technical / Actuals / Engine tabs, per-client file under the shared AI drive) is
+**superseded** by this platform but documents the same economics.
 
 ## Gotchas / known issues
 
@@ -150,4 +185,5 @@ The workbook is a **per-client** file on the shared AI drive (`P:\Work\AI\`).
   under the team shared AI drive; the path can move.
 
 ## Change history
+- 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/toga25-supply/INDEX.md

@@ -8,4 +8,4 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -22,6 +22,11 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx
   - toga25-supply/src/pages/Items/ItemsPage.tsx
   - toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx
+  - toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx
+  - toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx
+  - toga25-supply/src/pages/Inventory/Inventory.tsx
+  - toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx
+  - toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts
   - toga25-supply/src/fieldsConfig/index.ts
 related:
   - ../../_underscore/features/surface-resolver.md

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

@@ -18,6 +18,7 @@
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
+| [Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |

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

@@ -0,0 +1,84 @@
+---
+title: Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [jcardinal]
+files:
+  - worker2/Worker/Talos/Pricing.php
+  - worker2/Database/TalosPricingCrons.sql
+related:
+  - ./creating-worker-actions.md
+  - ../architecture.md
+  - ../../talos/architecture.md
+  - ../../talos/features/pricing-cogs-model.md
+  - ../../../1.0/apps/tools/features/talos-pricing-ui.md
+---
+
+## 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`.
+
+This replaces the Excel "Actuals" tab as the monthly recompute mechanism. The COGS token
+economics are unchanged — only the delivery/automation changed.
+
+## 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.
+
+## Gotchas / open items
+- **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])`.
+
+## Security
+- Hardcoded AWS SES SMTP credentials live in `_underscore/Email.php` (pre-existing, not
+  introduced here) — flagged for rotation. Location only; no values recorded.
+
+## Change history
+- 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/INDEX.md

@@ -5,14 +5,14 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 10 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 10 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 11 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 12 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 5 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 7 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/clients/nycdoe/INDEX.md

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

package/knowledge/clients/nycdoe/features/hold-status-sync.md

@@ -0,0 +1,127 @@
+---
+title: NYCDOE Ticket Hold-Status Sync (ServiceNow ⇄ TOGaDesk)
+framework: "1.0"
+repo: worker
+project: Worker
+client: nycdoe
+type: client-feature
+status: active
+updated: 2026-06-29
+owners: [mhammontree]
+files:
+  - worker/crons/sync/nycdoe/send_ticket_updates.php
+  - worker/crons/sync/nycdoe/process_tickets.php
+  - worker/crons/sync/nycdoe/send_request_item_updates.php
+  - library/app/model/togadesk/repairorder.php
+  - library/app/api/nycdoev2.php
+related:
+  - servicenow-integration.md
+  - ../profile.md
+  - ../../../1.0/apps/worker/architecture.md
+---
+
+## Summary
+
+DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and
+**stay held** — holds are SLA-bearing in both systems. This doc covers the bidirectional
+hold-status sync for DOE Incidents (INC) and Request Items (RITM), the authoritative
+business rule that governs it, and the TRUE-79922 fix that made hold persist. It is the
+status-sync companion to the broader [ServiceNow / ASN integration](servicenow-integration.md)
+doc; the underlying crons and `App_Api_NYCDOEV2` plumbing are documented there.
+
+> DOE "tickets" are **`repair_orders`** rows (`App_Model_TogaDesk_RepairOrder`,
+> `db_togadesk` / legacy `TOGaDeskSupport`, **clientid = 16**) — NOT the generic `tickets`
+> table / `class.ticket.php`. All four DOE crons filter to client 16 / `NYCDOETickets`, so
+> hold behavior here is **NYCDOE-only**; no other client is affected.
+
+## The authoritative business rule (SME-confirmed — contact-center)
+
+1. **A DOE hold persists until MANUALLY set to a new status.** Nothing auto-reverts a hold.
+2. **TOGaDesk is the AUTHORITATIVE system for releasing a hold.** A manual change *in
+   ServiceNow* does NOT release a TOGaDesk hold — the outbound cron **re-asserts On Hold**
+   onto SNOW every run until the hold is cleared in TOGaDesk.
+3. Scheduling metadata (ETA / assigned technician) is **separate from the hold STATE** — an
+   on-site visit can be scheduled weeks out (e.g. summer break) **without releasing the
+   hold**. ETA syncs *inside* the hold payload.
+
+## How it works
+
+### Status model (TOGaDesk side)
+- There are **six `HOLD_*` status constants** on `App_Model_TogaDesk_RepairOrder`. All bucket
+  to main status **`Hold`** via `App_Model_TogaDesk_RepairOrder::statusDisplayMain()`.
+- `Hold` has **statusRank 6**, beating `Work in Progress` (rank 5) in the downgrade-guard
+  added by TRUE-76812 — so a downstream sync cannot silently demote a held order.
+
+### Status field (ServiceNow side)
+- The SNOW **native `state` field** (human-readable: `On Hold`, `In Progress`, `Assigned`,
+  `Resolved`, …) is the **SLA-bearing, authoritative status**. Read/write this for hold.
+- The custom **`u_status_task`** field is a *separate concept* with a different vocabulary;
+  it can lag/disagree with `state` (observed: native `state="In Progress"` while
+  `u_status_task="Open"`). **Never use `u_status_task` for hold detection.**
+- Numeric `state` codes seen on the wire: INC `On Hold` = **3**, `In Progress` = **2**;
+  RITM `On Hold` = **8**, the scheduled-update state = **"-14"**.
+
+### Outbound (TOGaDesk → ServiceNow)
+- `send_ticket_updates.php` (INC) pushes the hold as `state:3`. The "Assigned → In Progress"
+  auto-start block is **guarded** so it never pushes `state:2` when the local repair order is
+  in any `HOLD_*` status (this is what caused the self-clobber — see Change history).
+- `send_request_item_updates.php` (RITM) pushes `state:"8"` (On Hold) and carries a
+  defensive `HOLD_*` guard on the scheduled-update path so it can't push `state:"-14"` while
+  held.
+
+### Inbound (ServiceNow → TOGaDesk)
+- `process_tickets.php` determines local status from the native **`$data->state`** field
+  (NOT `u_status_task`): after the `u_status_task` switch — before the completion-preserve
+  step and the `statusRank` downgrade-guard — if native `state` is `On Hold`
+  (case-insensitive) it sets `$newStatus = STATUS_HOLD`. Both inbound "Assigned-force"
+  `patchINC(state:2)` blocks are guarded against a local hold.
+
+### RITM "ETA-in-hold"
+- `send_request_item_updates.php` syncs `scheduled_date` (ETA) to ServiceNow **inside the
+  hold block, in the same payload as `state:"8"`**, when a held order has an ETA + assigned
+  technician. This mirrors the INC cron, which already sends `u_eta` while holding — keeping
+  scheduling metadata flowing while the hold STATE stays asserted.
+
+## Reference facts (DOE sync debugging)
+
+- **SNOW request/response logs:** logged to the legacy `Logs` schema, **`API` table**
+  (`App_Model_Logs_API`, `db_logs`, `_databaseNameOverride 'Logs'`). `requestPayload` /
+  `responsePayload` are queryable CHAR columns — the primary debugging avenue. Filter
+  `endpoint LIKE '%nycd3%'`; the custom DOE endpoint base is **`/api/nycd3/`**. The
+  state:3↔state:2 oscillation in TRUE-79922 was proven from this table (INC2074899,
+  INC2185183 showed `state:3` then `state:2` pushed seconds apart in one run).
+- **`NYCDOETickets` (`App_Model_Common_NYCDOETicket`, `db_common` / legacy `Common`)** stores
+  the inbound SNOW record in `rawData`, a **`FIELDTYPE_BLOBSTORAGE`** field (S3 bucket
+  `asifiles`, key `prod/Common/NYCDOETickets/rawData/{id}`) — **NOT a queryable DB column.**
+- **Worker prod code cannot run on a Windows dev box.** The DB/S3 data layer fetches EC2
+  instance-metadata (IMDSv2) credentials and fails off-EC2. Investigate with the toga DB MCP
+  and the `Logs.API` table instead of running the crons locally.
+
+## Gotchas / known issues
+
+- **The self-clobber (root cause #1 of TRUE-79922):** an unguarded "Assigned → In Progress"
+  auto-start fought the hold push — `state:3` then `state:2` pushed seconds apart, every run,
+  so SNOW never stayed On Hold. Any future auto-start/auto-status block on these crons MUST
+  short-circuit when the local RO is in a `HOLD_*` status.
+- **The wrong-field read (root cause #2 of TRUE-79922):** reading `u_status_task` instead of
+  native `state` meant a hold set on the SNOW side never reached TOGaDesk. Hold detection is
+  on native `state` only.
+- Holds are **never auto-released** — if a SNOW user manually changes status, the outbound
+  cron correctly re-asserts On Hold; that is intended, not a bug. Clear the hold in TOGaDesk.
+
+## Change history
+- 2026-06-29 — TRUE-79922: fixed DOE holds never persisting (reverted to In Progress, broke
+  SLA reporting both sides). Two coupled defects: outbound self-clobber (`send_ticket_updates.php`
+  unguarded Assigned→In-Progress pushing `state:2` over a held `state:3`) and inbound
+  wrong-field read (`process_tickets.php` read `u_status_task` instead of native `state`).
+  Guarded all Assigned-force blocks (INC outbound + both inbound) against local `HOLD_*`,
+  added native-`state`="On Hold"→`STATUS_HOLD` inbound mapping, and a RITM scheduled-update
+  `HOLD_*` guard. Built RITM ETA-in-hold sync (`scheduled_date` in the same `state:"8"`
+  payload). Recorded the SME business rule (hold persists until manual; TOGaDesk authoritative
+  for release). (mhammontree)
+
+## Related docs
+- [NYCDOE ServiceNow / ASN Integration](servicenow-integration.md) — full integration map,
+  crons, schedules, and `App_Api_NYCDOEV2` plumbing.
+- [NYC DOE client profile](../profile.md)
+- [Worker (1.0) architecture](../../../1.0/apps/worker/architecture.md)

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

@@ -36,6 +36,7 @@ files:
   - library/app/edi.php
 related:
   - ../profile.md
+  - hold-status-sync.md
   - ../../../1.0/apps/worker/architecture.md
 ---
 
@@ -230,6 +231,11 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-06-29 — Outbound status sync now keeps DOE holds authoritative (TRUE-79922). Hold
+  detection moved to the SNOW native `state` field (not `u_status_task`); Assigned-force
+  blocks guarded against local `HOLD_*` to stop the `state:3`↔`state:2` self-clobber; RITM
+  now syncs ETA inside the On-Hold payload. Split into dedicated
+  [hold-status-sync.md](hold-status-sync.md). (mhammontree)
 - 2026-06-19 — Investigated (read-only) the replacement-PO-suffix duplicate-fulfillment bug: PO-scoped serial dedupe defeated by per-manufacturer suffix-format variance (`-RPL`/`-REPL`/`-RPLE`/`-N`/`_N`); confirmed live case WR260150152/V60095WK (ROs 772308+801064) and ~14 systemic pairs across Lenovo+Lexmark. Refined business rule #6; added OPEN-BUG gotcha + adjacent anomalies (numeric-PO↔WR cluster, "NA"/integer serials). No code changes. (mhammontree)
 - 2026-06-10 — Documented the NYC DOE ServiceNow/ASN integration (ticket mirror, dual ASN ingestion, NetSuite freeze pipeline, EDI surface, dedupeKey gotchas). (mhammontree)
 

package/knowledge/clients/true/profile.md

@@ -4,11 +4,13 @@ framework: "2.0"
 apps:
   - _underscore
   - tools
+  - worker2
+  - dbchanges2
 project: _Underscore
 client: true
 type: profile
 status: active
-updated: 2026-06-26
+updated: 2026-06-29
 owners: [jcardinal]
 files: []
 related:

package/package.json

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