toga-ai 1.0.228 → 1.0.230

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
@@ -41,7 +46,11 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
 - **`useFetchSurfaceMeta`** — the single fetch-once/React-Query-cached choke point for a surface's
   meta. Loading a different *record* into the same surface reuses cached meta. Builds the URL as
   `/surfaces/meta?slug=...` (query string), **not** `/surfaces/<slug>/meta` (the path form makes the
-  engine parse the slug as a record uuid → 404 EV-6).
+  engine parse the slug as a record uuid → 404 EV-6). Unwraps the bundle via **`extractBundle()`**,
+  which locates the bundle by its **structural fingerprint** (the `elements` array) across
+  `raw` / `raw.data` / `raw.data.<route-key>` — because V2 nests a scripted-API return value one
+  level deeper, under a route-keyed slot of `data` (e.g. `data.meta`, `data.surfaces`). On a malformed
+  payload it falls back to an empty-elements bundle so the page never crashes.
 - **`evaluateSurfaceRule`** — the Tier-1 rule evaluator: a **frozen `all/any/none` + `{field,op,value}`
   grammar** that **throws on an unknown op** (generalized from the SalesOrders
   `buildPatchedTenantFields`/`evaluateEnableRule`/`resolveFlag` helpers). Evaluated client-side against
@@ -61,13 +70,14 @@ legacy pre-Surface fallback branches at the wired screens removed). Legacy per-s
 
 ## What's wired
 
-Login + sales-orders list + the sales-order modal + the **Items LIST** screen. The SalesOrder action
+Login + sales-orders list + the sales-order modal + the **Items**, **VendorItems**, and
+**Inventory** LIST screens. The SalesOrder action
 bar reproduces `orderViewFields.json` approve/deny/approvalWorkflow/viewLog/editOrder by delegating
 to the existing `onActionClick`/`onOpenLog` handlers. TABLE-type surfaces stay on the existing
 TableView pipeline via `tableViewSlug` (see [meta-driven-table-data](meta-driven-table-data.md)) —
 the Surface layer references the TableView, never replaces it.
 
-## Per-screen migration recipe (proven on SalesOrders + Items)
+## Per-screen migration recipe (proven on SalesOrders + Items + VendorItems + Inventory)
 
 The screen-by-screen full-app refactor follows one recipe:
 1. Seed the screen's surface(s) in a `Core/*SurfaceSeed.sql` — a TABLE surface that references the
@@ -82,8 +92,51 @@ Keep TABLE rendering on the existing TableView pipeline; only the chrome (action
 moves to Surface. A screen with no client/role/lang variance ships a single DEFAULT bundle (no
 Client overrides), as Items did.
 
+**VendorItems (screen 2)** followed the recipe exactly: `vendor-items-list` (TABLE → TableView 10,
+recordId 19) + `vendor-items-list-actions` (Refresh / Columns[hidden+disabled] / New Vendor Item),
+page+view-model rewired to resolve title+buttons from the bundle, dropped the
+`useClientFields`/`vendorItemsPageFields` dependency, deleted `vendorItemsPageFields.json` + its
+`fieldsConfig/index.ts` entry.
+
+**Inventory (screen 3) — presentation-only, by decision.** Only the page title, header buttons
+(Group by / Refresh), the Group-by modal copy, and the entity icon/color tag map moved to Surface.
+The `inventoryGroupings` `groupings[].levels[]` topology
+(`fetchSlug`/`role`/`additionalDataSlug`/`urlParamKey` driving `GenericNestedTables`) is **data-fetch
+wiring, not presentation**, so per the config/logic boundary it **stays as JSON**. The
+`inventory-list` surface carries `groupByLabels` + `entityTags` in its surface `config`, with
+**recordId+tableViewId NULL** (the page has no single backing Record — it composes
+purchase-orders/items/units via per-level fetchSlugs). Labels + `entityTags` were stripped from both
+DEFAULT and NYCHH `inventoryGroupings.json` (groupings kept) and marked `@deprecated`/optional in the
+`InventoryGroupingsConfig` type.
+
+**The config/logic line for migration:** move presentation (titles, button labels, icons, colors,
+modal copy, visibility/enable) to Surface; **leave data-fetch wiring (fetch slugs, roles, URL params,
+nested-table topology) in JSON/code.** Not every screen reduces to a generic `SurfaceSection` swap —
+see SalesOrders below.
+
+## SalesOrders remaining migration — bespoke, NOT a generic SurfaceSection swap (deferred)
+
+The SalesOrders detail migration is the plan's explicitly-deferred "blessed escape hatch"/approval
+work — it is bespoke-component + business-logic work, not a generic swap. `SalesOrderSummaryGrid` is
+fully tenant-data-driven through three **bespoke renderers**: `detailSection` (blox `DetailSection` +
+custom `renderField`), `locationCard` (`OrderSectionCard`, structured contact data), and `totalsCard`
+(blox `BaseTotals` **with client-specific recurring-lease business logic**:
+`_totalLease !== 0 → recurringKey` fields). The generic `SurfaceSection` (label/value) cannot
+represent `BaseTotals`/`OrderSectionCard`, and the early-seeded order-details/ship-to/bill-to/
+order-summary SECTION surfaces do **not** cleanly map onto the grid's arbitrary client-keyed section
+model. A faithful migration needs a **registered-renderer approach** keyed off surface element config
+(`detailSection`/`locationCard`/`totalsCard` → their components), with the lease logic staying in
+code/`_underscore`, plus reconciling those seeds and the Compass approval-modal state machine.
+**Deferred to a dedicated design-first session.**
+
 ## Gotchas
 
+- **Scripted-API GET return values land under `data.<scriptRoute>`, not `data` directly.** V2 nests a
+  scripted-API return value inside the envelope under a route-keyed slot of `data` (e.g. `data.meta`,
+  `data.surfaces`), one level deeper than a normal data fetch. The bundle hook unwraps this with
+  `extractBundle()` by structural fingerprint (the `elements` array). Consumers (`SurfaceSection`,
+  `SurfaceActionBar`) are hardened to bail to `null` unless `elements` is a real array, so a malformed
+  payload never crashes the page. (Root cause of the "s.elements is not iterable" runtime crash.)
 - **No feature flag, no fallback.** Surface is the enforced path; a missing/broken surface bundle
   does not silently fall back to legacy JSON — that path is deleted per screen as it migrates.
 - **Endpoint is query-string form** — `GET /v2/surfaces/meta?slug=...`, not `/surfaces/<slug>/meta`
@@ -94,6 +147,13 @@ Client overrides), as Items did.
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-06-29 — Migrated VendorItems (screen 2, recipe-exact) and Inventory (screen 3,
+  **presentation-only by decision** — fetch topology stays JSON; only title/buttons/modal copy/entity
+  tags moved). Fixed the "s.elements is not iterable" crash: `extractBundle()` now finds the bundle by
+  its `elements`-array fingerprint across `raw`/`raw.data`/`raw.data.<route-key>` (V2 nests
+  scripted-API returns under `data.<scriptRoute>`), with an empty-bundle fallback + hardened
+  SurfaceSection/SurfaceActionBar guards. Recorded SalesOrders detail as deferred bespoke
+  (registered-renderer + lease logic + approval-modal) work. (jcardinal)
 - 2026-06-29 — DECISION: Surface is now enforced, not flagged — removed `VITE_SURFACE_ENABLED`/
   `SURFACE_ENABLED` (deleted `featureFlag.ts` + all gating/legacy-fallback branches). Fixed
   `useFetchSurfaceMeta` to the query-string endpoint `/surfaces/meta?slug=` (path form 404'd EV-6).

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

@@ -12,12 +12,12 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **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
 
 - **_underscore** (_Underscore) _(framework core)_ — 17 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 21 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 22 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

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