toga-ai 1.0.258 → 1.0.260

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

@@ -14,6 +14,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-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, 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 |
+| [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, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, 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

@@ -6,12 +6,16 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: [jcardinal]
+updated: 2026-07-01
+owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/AclRecordScript.php
+  - _underscore/Model/Core/RecordScript.php
   - dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql
   - dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql
+  - dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql
+  - dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql
   - dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql
   - dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql
   - dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql
@@ -113,6 +117,32 @@ which surfaced latent resolution gaps in `_buildBundle`/`_resolveElement`:
   `_Model_<Client>_*` overrides + `Client_ApiPayloadInterceptor` hooks — the Surface layer does
   **not** absorb business logic.
 
+## How a surfaces scripted-API call is authorized (route-level gate)
+
+Authorizing a surfaces script (`meta`, `meta-group`, `debug`) is a **two-layer** check. Get the
+first layer wrong and you get a **403 `EZ-1 AUTHORIZATION`** before any element ACL runs.
+
+1. **Route-level dispatch gate — `Client_<tenant>.AclRecordScripts`.** The surfaces dispatcher
+   authorizes each API script (route + method + phpMethod) via the **CLIENT-tier**
+   `AclRecordScripts` table (cols `uuid`, `recordScriptId` → `Core.RecordScripts`, `roleId` →
+   `Client_<tenant>.Roles`). The check is keyed on the JWT's **`id.client.roles`** (client roles),
+   **NOT** the platform `core.roles` and **NOT** the Core `AclRecordPermissions` chain.
+   `Core.RecordScripts` maps route/method/phpMethod → an ACL "record" (`recordId`). The three
+   surfaces scripts: `meta` (GET, phpMethod `meta`), `meta-group` (GET, `metaGroup`), `debug` (GET,
+   `metaDebug`). `_Model_Core_Surface::resolve/metaGroup` read the caller's roles from
+   **`id.client.roles`** (Surface.php ~lines 56/87).
+2. **Element-level ACL (runs *inside* `meta`/`metaGroup`, AFTER the route gate passes)** — dropping
+   individual surface elements uses a **separate** client-tier table `_Model_Client_AclActionPermission`,
+   gated by each `SurfaceElement.aclActionId`. This is the "composition, not absorption" step in
+   `resolve()` step 4; it never causes the route-level 403.
+
+**Debugging a surfaces 403 EZ-1 (hard-won):** it is the route-level gate — a missing
+`Client_<tenant>.AclRecordScripts` grant resolved by **client role**. Do **not** chase
+`Core.AclRecordPermissions`, `appId` scoping, or `AclLogicGroups`/`AclRecordExpressions` — all were
+investigated and ruled out as red herrings: `appId = NULL` is the normal working pattern, and the
+Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The gate is purely
+"does this client role have an `AclRecordScripts` row for this `recordScriptId`?"
+
 ## Gotchas
 
 - **A Core RecordScript needs `Client.AclRecordScripts` rows per role to be invokable — record-level
@@ -167,8 +197,33 @@ which surfaced latent resolution gaps in `_buildBundle`/`_resolveElement`:
   per-role `Client.AclRecordScripts` dispatch grant. Verified via toga-db — `meta` script id 25 was
   granted roles 1/3/4 but `meta-group` (id 27) had **none** until the grant ran. Any new surfaces
   scripted-API method repeats this: record READ never authorizes dispatch.
+- **The meta-group grant is seeded per-tenant, not globally — new tenants repeat the 403.** When
+  `meta-group` shipped, the `AclRecordScripts` grant was seeded **only** for `Client_Compass`
+  (recordScriptId → roles 1,3,4). `Client_Quad` and `Client_CompassCanada` had **no** grant for the
+  meta-group recordScriptId at all — their `meta` was granted to client role 1 (why `meta` worked but
+  `meta-group` 403'd for the same user/token). Same-user-different-script + same-script-different-tenant
+  is the fingerprint of this gap. Fix (2026-07-01): two `dbchanges2/Client_<tenant>/` migrations
+  granting meta-group to **client role 1** (parity with each tenant's existing `meta` grant),
+  id-agnostic (resolve `Core.RecordScripts` id by route/method/phpMethod, cross-DB read of `Core.*`
+  per the 2026-06-29c ACL pattern) and re-runnable via `NOT EXISTS`. Surface-layer DB changes ship to
+  the **beta** environment only. ⚠ **Root-cause not yet closed:** the meta-group grant should be
+  added to the `dbchanges2/Client/` **baseline (blank) seed** so newly-cut clients get it
+  automatically — otherwise the next migrated tenant hits the identical 403. Only Compass (already
+  correct), Quad, and CompassCanada are addressed. Also note **role breadth**: Compass exposes
+  surfaces to roles 1,3,4; Quad/CC got role 1 only (parity with their `meta`). If Quad/CC should
+  match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-01 — Documented the full route-level authorization mechanism (new section): the surfaces
+  script gate is `Client_<tenant>.AclRecordScripts` keyed on JWT `id.client.roles` (client roles,
+  not `core.roles`, not `Core.AclRecordPermissions`); element-drop is a separate
+  `_Model_Client_AclActionPermission`/`aclActionId` layer running inside `resolve()` after the route
+  gate; captured the red-herring list (`appId=NULL` is normal, Core grants all evaluate `all`/`"1"`).
+  Fixed the `meta-group` 403 EZ-1 for **Quad** and **Compass Canada** — the meta-group
+  `AclRecordScripts` grant had been seeded for Compass only; added two id-agnostic, NOT-EXISTS-guarded
+  `Client_<tenant>/` migrations granting meta-group to client role 1 (beta env only). Flagged the
+  open root-cause: add the grant to the `Client/` baseline seed, and decide role breadth (1 vs 1,3,4)
+  for Quad/CC. (apeterson)
 - 2026-06-30 — Added `metaGroup()` (`GET /v2/surfaces/meta-group?slugs=a,b,c`): batched composition
   over the existing per-slug `resolve()` cache, capped at `META_GROUP_MAX_SLUGS=25`, unknown slug →
   empty bundle (chosen over a `parentSurfaceId` GROUP row post-CTO-review). Fixed latent

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-07-01
 owners: [apeterson]
 files:
   - toga25-supply/src/fieldsConfig/index.ts
@@ -64,6 +64,22 @@ and the `useClientFields()` hook.
   `yourKey: BY_CLIENT[clientSlug] ?? DEFAULT_*`. Avoids editing all ~13 role bundles.
   `DEFAULT_CLIENT_FIELDS` must also carry the new key (ultimate fallback).
 
+### De-roling a client×role bundle to client-only
+
+Some bundles were role-keyed (`{ADMIN, MANAGER}`) only for historical reasons — the roles held
+byte-identical config. Those are being flattened to **client-only** (part of the ongoing
+backend-driven / de-role goal). `orderViewFields` is now client-only: `COMPASS` and `COMPASSCANADA`
+read their flat client JSON via `mergeOrderView(<client>OrderViewFields)` in
+`src/fieldsConfig/index.ts` instead of reading `.ADMIN`/`.MANAGER` off the file, and
+`FIELDS/COMPASSCANADA/orderViewFields.json` was flattened from `{ADMIN, MANAGER}` to a flat object.
+
+When de-roling, watch the read path: `COMPASS`'s JSON was **already flat** but was still being read
+via `.ADMIN` → `undefined` → the client silently fell back to `DEFAULT` and lost its
+`salesOrderDetailsConfig` joins. This is the flat-bundle trap from the gotcha below — the fix is to
+read the bundle itself, not a role key. `approvalViewFields` and `salesOrdersPageFields` remain
+role-keyed (their ADMIN/MANAGER genuinely differ); fully de-roling those and removing `resolveRole`
+is a separate pending task.
+
 ### Hydration (non-serializable bits)
 
 Keep JSON **serializable** — strings, enums, arrays. No JSX, no functions, no Tailwind classes.
@@ -143,6 +159,12 @@ modal's chrome from the same per-client JSON, not from the component:
   `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 2026-07-01 — De-roled `orderViewFields` from client×role to **client-only**: COMPASS/COMPASSCANADA
+  now read a flat client JSON via `mergeOrderView(...)` in `fieldsConfig/index.ts` (COMPASSCANADA's
+  JSON flattened from byte-identical `{ADMIN,MANAGER}`). Fixed a latent bug where COMPASS's
+  already-flat JSON was read via `.ADMIN` → `undefined` → silent fallback to DEFAULT (lost its
+  `salesOrderDetailsConfig` joins). `approvalViewFields`/`salesOrdersPageFields` stay role-keyed;
+  full de-role + `resolveRole` removal remains pending. Type-check clean. (apeterson)
 - 2026-06-25 — SalesOrder action buttons render by presentation intent: `kind` (icon/text/viewLog) picks the renderer, `variant` a closed color set, `valueKey` is pure click-dispatch; a `componentRegistry` keyed by `kind` hydrates dedicated components (e.g. ViewLogButton). Added the `recordActionFields`-shape gotcha (per-persona blocks + sibling `poNumber` sub-config; walk `actionOptions` only). (apeterson)
 - 2026-06-25 — Extended to record-modal layouts: per-mode `*ViewFields`/`*EditFields` JSON under `src/layout/.../viewModel/FIELDS/`, JSON-driven modal `header` (modalTag/labelTemplate/statusBadge) + `editItem` button gated via the Flag/Rule engine, and the flat-bundle defensive-default gotcha. (apeterson)
 - 2026-06-23 — Documented from the `add-client-fields` skill during initial knowledge seed. (apeterson)

package/knowledge/clients/compass-canada/profile.md

@@ -15,12 +15,13 @@ client: compass-canada
 type: profile
 status: active
 updated: 2026-06-30
-owners: [jcardinal, bala, tcox]
+owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - ../compass-usa/profile.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../2.0/apps/_underscore/features/surface-resolver.md
 ---
 
 ## Summary
@@ -50,6 +51,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   see [Config-Driven Expedited Shipping Gating](../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md).
 
 ## Notes
+- **Surface layer (beta):** like Quad, `Client_CompassCanada` had **no** `AclRecordScripts` dispatch
+  grant for the surfaces `meta-group` script (only `meta`, to client role 1) → `GET /v2/surfaces/meta-group`
+  403'd EZ-1 while `meta` worked. Fixed 2026-07-01 via
+  `dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql` (meta-group →
+  client role 1, id-agnostic + NOT-EXISTS-guarded, beta only). Exposes surfaces to role 1 only, vs
+  Compass USA's 1/3/4. See [Surface Resolver](../../2.0/apps/_underscore/features/surface-resolver.md).
 - Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
   facing emails are sent in EN or FR accordingly.
 - Assortment (product-grouping) names are served in fr-CA via the `AssortmentTranslations` sidecar

package/knowledge/clients/quad/profile.md

@@ -14,11 +14,12 @@ client: quad
 type: profile
 status: active
 updated: 2026-06-30
-owners: ["jcardinal", "bala"]
+owners: ["jcardinal", "bala", "apeterson"]
 files: []
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../2.0/apps/_underscore/features/surface-resolver.md
 ---
 
 ## Summary
@@ -48,6 +49,13 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   (`_underscore/Model/Quad/SalesOrder.php`): non-SA orders use the inline machine, `SA%` orders
   delegate to the base `_Model_Client_SalesOrder`. Contrast Compass, which is shipped-only. See
   [IF stage lifecycle & order status](../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md).
+- **Surface layer (beta):** the surfaces `meta-group` script had **no** `AclRecordScripts` dispatch
+  grant for `Client_Quad` (only `meta` was granted, to client role 1), so `GET /v2/surfaces/meta-group`
+  403'd (EZ-1) while `meta` worked. Fixed 2026-07-01 via
+  `dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql` (grants meta-group to
+  client role 1, id-agnostic + NOT-EXISTS-guarded, beta only). Quad exposes surfaces to role 1 only,
+  vs Compass's 1/3/4 — revisit if broader roles are needed. See
+  [Surface Resolver](../../2.0/apps/_underscore/features/surface-resolver.md).
 - Tracking data: record 318 (item-level) is currently empty for this client; their tracking
   populates the IF/shipment level (record 317, ~98% coverage) and unit level (record 319). The
   rebuilt views use 318 (per the Compass pattern) and will show tracking once item-level

package/knowledge/sessions/2026-06-30-talos-pricing-platform-jcardinal.md

@@ -14,40 +14,41 @@ updated: 2026-06-30
 # Session: talos-pricing-platform
 **Date:** 2026-06-30
 **Project/Repo:** tools (1.0) + worker2 (2.0) + dbchanges2 (2.0 Team DB)
-**Task:** Build a data-driven Talos pricing platform (Team-DB schema + tools onboarding/dashboard UI + worker2 cron automation) to replace the Excel calculator; then fix tools SSO login that was failing in production.
+**Task:** Build a data-driven Talos pricing platform (Team-DB schema + tools onboarding/dashboard UI + worker2 cron automation) to replace the Excel calculator; then fix tools SSO login (both consumer and initiate legs) that was failing in production.
 
 ---
 
 ## What WORKED
-- **Schema (Team DB):** `dbchanges2/Team/2026-06-29a - TalosPricingTables.sql` — 9 tables created, SQL-reviewed (0 critical), all 7 important review fixes applied (dtUpdated on fact tables, DECIMAL(6,4) margins, isFeature* boolean naming, DECIMAL(14,8) calibration factors, full column comments, band-range CHECK). Tables live in the **Team** DB; `dbchanges2/Team/` is the migration folder (Team-DB migrations use unqualified table names).
-- **worker2 automation:** `worker2/Worker/Talos/Pricing.php` (`_Worker_Talos_Pricing`) + `worker2/Database/TalosPricingCrons.sql` — `php -l` clean. Three monthly cron actions: ImportAwsActuals (Cost Explorer), RecomputeMargins (calibration + margin/streak/recommendation), MonthlyReport (PhpSpreadsheet xlsx + templated email). initialize() registers Team DB via `_underscore::DB_TEAM` (mirrors `_Worker_Team_Transcripts`).
-- **tools UI:** nav folder + 6 pages + estimator + CSS, all `php -l` clean. `App_Talos_Estimator` (`tools/_/app/talos/estimator.php`), onboarding get/post, pricing dashboard, usage benchmarks, cost-factors get/post. Live JS estimate + recommended per-band fees on the onboarding form.
-- **SSO 500 fix:** `tools/mvc/sso/get.php` `tools_ssoFail()` — added `if (!headers_sent())` guard around `http_response_code(401)`. `php -l` clean. Root cause confirmed: `App_FrameworkIndex::render()` flushes the preloader buffer (`page.php:213`) BEFORE `body()`/`loadFile()`, so headers are already sent when an mvc page runs.
-- **SSO key sourcing:** `tools/_/app/auth.php` `App_Auth::decryptHandoffValue()` rewritten to read `API_SECRET_ACCESS_TOKEN` / `API_SECRET_ACCESS_TOKEN_PREVIOUS` from `Core.Parameters` (rotated there) via new cached `handoffKeys()` + `const CORE_DB='db_toga2core'`. `php -l` clean.
-- **Crypto format confirmed:** `App_String::encryptWithKey/decryptWithKey` (library/app/string.php:1075-1094) = AES-256-CBC, `base64(iv . base64ciphertext)`, interoperable with 2.0 `_String`. The user's real `?saml=` payload decoded to exactly that shape — proving the SSO failure was a stale-key/config mismatch, not a format bug.
-- **Knowledge captured + pushed twice:** pricing platform (6 docs incl. an approved ELEVATED architecture section in `2.0/apps/talos/architecture.md`) and SSO fixes (2 tools feature-doc updates). Both PUSHED to `_main`.
+- **Schema (Team DB):** `dbchanges2/Team/2026-06-29a - TalosPricingTables.sql` — 9 tables, SQL-reviewed (0 critical), all 7 important review fixes applied (dtUpdated on fact tables, DECIMAL(6,4) margins, isFeature* booleans, DECIMAL(14,8) calibration factors, column comments, band-range CHECK). `dbchanges2/Team/` is the Team-DB migration folder (unqualified table names).
+- **worker2 automation:** `worker2/Worker/Talos/Pricing.php` (`_Worker_Talos_Pricing`) + `worker2/Database/TalosPricingCrons.sql` — `php -l` clean. 3 monthly crons: ImportAwsActuals (Cost Explorer), RecomputeMargins (calibration + margin/streak/recommendation), MonthlyReport (PhpSpreadsheet xlsx + EmailTemplate). initialize() registers Team DB via `_underscore::DB_TEAM`.
+- **tools UI:** nav folder + 6 pages + `App_Talos_Estimator` + CSS, all `php -l` clean. Onboarding get/post (live JS estimate + recommended per-band fees), pricing dashboard, usage benchmarks, cost-factors get/post.
+- **SSO 500 fix (consumer leg):** `tools/mvc/sso/get.php` `tools_ssoFail()` — added `if (!headers_sent())` guard around `http_response_code(401)`. Root cause: `App_FrameworkIndex::render()` flushes the preloader buffer (`page.php:213`) BEFORE `body()`/`loadFile()`, so headers are already sent when any mvc page runs.
+- **SSO key sourcing → Core.Parameters (BOTH legs):** `tools/_/app/auth.php` — `decryptHandoffValue()` (consumer) reads keys via new cached `handoffKeys()`; added public `currentApiSecret()` for the initiate leg; `const CORE_DB='db_toga2core'`. `tools/mvc/sso/initiate/get.php` now passes `'apiSecretAccessToken' => App_Auth::currentApiSecret()`. Both `php -l` clean.
+- **Crypto format confirmed:** `App_String::encryptWithKey/decryptWithKey` (library/app/string.php:1075-1094) = AES-256-CBC, `base64(iv . base64ciphertext)`, interoperable with 2.0 `_String`. The real `?saml=` payload decoded to exactly that shape — proving SSO failure was a key/config issue, not a format bug.
+- **"Sign in failed" root cause found + fixed:** that banner is `login/get.php` `?error=1`, set ONLY by `sso/initiate/get.php:33,38` when `App_Sso::initiate()` throws. The initiate leg still read `api_secret_access_token` from config; after it was removed from config (per earlier wrong advice), `App_Sso::initiate()` (library/app/sso.php:64-65, empty() guard) threw InvalidArgumentException → `/login?error=1`. Fixed by sourcing the secret from Core.Parameters on the initiate leg too.
+- **Knowledge captured + pushed (4 times):** pricing platform (6 docs incl. approved ELEVATED `2.0/apps/talos/architecture.md` section), SSO fixes (`saml-sso-auth.md` + `mvc-data-access-patterns.md`), and the SSO-initiate correction (`saml-sso-auth.md` again). All PUSHED to `_main`.
 
 ## What did NOT work — DO NOT RETRY THESE
-- **`App_Database::escape()` does NOT exist** — the 1.0 escaper is `App_Database::sqlEscape()`. Using `::escape` fatals.
-- **Passing `App_Database::query(...)` inline to `buildArrayOfRows()`/`fetchOne()`** triggers PHP "Only variables should be passed by reference" (both take `&$res`); with display_errors on it renders into output. MUST assign the query result to a variable first (the login post.php does this).
-- **Reading SSO tokens from `config.production.ini` `[saml]`** — they go stale because the gateway rotates `API_SECRET_ACCESS_TOKEN`; that stale token was why decrypt returned false and login failed. Do not rely on config tokens; use Core.Parameters.
-- **Calling `http_response_code()` / `header()` / `session_regenerate_id()` from any page loaded inside `body()`** — the preloader buffer is already flushed, so it fatals/no-ops. Always guard with `headers_sent()`.
-- **Writing `[database_team]`/`[database_toga2core]` into config with a guessed host** — avoided deliberately; the 2.0 Core/Team host (`production-core-cluster…us-west-2`, from config.alpha.ini `[database_prod_toga2core]`) differs from the 1.0 prod-cluster and the 2.0 client cluster (`reader1.client.database.togahub.com` = db_true). Don't assume they're the same host.
+- **Removing `api_secret_access_token` from `config.production.ini` `[saml]`** — broke SSO. The INITIATE leg (`sso/initiate/get.php`) reads it from config to encrypt the RelayState; empty → `App_Sso::initiate()` throws `InvalidArgumentException('...missing required parameter: apiSecretAccessToken')` → `/login?error=1` "Sign in failed". DO NOT keep the rotating secret in config; it now comes from Core.Parameters on both legs.
+- **`App_Database::escape()`** does NOT exist — use `App_Database::sqlEscape()`.
+- **Passing `App_Database::query(...)` inline to `buildArrayOfRows()`/`fetchOne()`** (both take `&$res`) — triggers PHP "Only variables should be passed by reference" (renders with display_errors on). Assign the query result to a variable first.
+- **Calling `http_response_code()`/`header()`/`session_regenerate_id()` from a page loaded inside `body()`** — preloader buffer already flushed → fatals/no-ops. Guard with `headers_sent()`.
+- **Writing `[database_team]`/`[database_toga2core]` with a guessed host** — avoided. The 2.0 Core/Team host is `production-core-cluster…us-west-2` (from config.alpha.ini `[database_prod_toga2core]`), distinct from the 1.0 prod-cluster and the 2.0 client cluster (`reader1.client.database.togahub.com` = db_true).
 
 ## Not tried yet (candidates for next session)
-- Seeding/calibrating `TalosCostFactors` from the real Langfuse aggregates (estimator currently ships placeholder DEFAULTS).
-- Wiring the xlsx as an actual email attachment — `_Email` attachment support is unconfirmed (`MonthlyReport` writes xlsx to a temp path; email body has the HTML table meanwhile).
+- Seeding/calibrating `TalosCostFactors` from real Langfuse aggregates (estimator ships placeholder DEFAULTS).
+- Wiring xlsx as an email attachment — `_Email` attachment support unconfirmed (MonthlyReport writes xlsx to temp; email body has HTML table).
 - Confirming the AWS Cost Explorer cost-allocation tag key (worker assumes `Client`).
-- Creating the leadership `EmailTemplates` record in Client_True and replacing the placeholder `REPORT_EMAIL_TEMPLATE` UUID in `_Worker_Talos_Pricing`.
-- Verifying the live SSO login end-to-end after the `[database_toga2core]` connection is added + deployed.
+- Creating the leadership `EmailTemplates` record in Client_True and replacing the placeholder `REPORT_EMAIL_TEMPLATE` UUID.
+- Live end-to-end SSO verification after `[database_toga2core]` is configured + deployed.
 
 ## Current file state
 | File | Status | Notes |
 |------|--------|-------|
 | dbchanges2/Team/2026-06-29a - TalosPricingTables.sql | created | 9 Talos* tables, reviewed+fixed. Apply to Team DB. |
-| worker2/Worker/Talos/Pricing.php | created | `_Worker_Talos_Pricing`; lint clean. REPORT_EMAIL_TEMPLATE is a placeholder UUID. |
+| worker2/Worker/Talos/Pricing.php | created | `_Worker_Talos_Pricing`; lint clean. REPORT_EMAIL_TEMPLATE placeholder UUID. |
 | worker2/Database/TalosPricingCrons.sql | created | 3 Core.CronJobs seeds (4th of month). Not yet inserted. |
-| tools/_/app/nav.php | modified | Added "Talos Pricing" folder (4 links; Cost Factors narrowed to technical personas). |
+| tools/_/app/nav.php | modified | "Talos Pricing" folder (4 links; Cost Factors narrowed to technical personas). |
 | tools/_/app/talos/estimator.php | created | `App_Talos_Estimator`; placeholder DEFAULT factors. |
 | tools/mvc/talos/onboarding/get.php + post.php | created | Form + live estimate; writes TalosClients + TalosPricingBands in a txn. |
 | tools/mvc/talos/pricing/get.php | created | Read-only margin/recommendation dashboard (db_team). |
@@ -55,21 +56,23 @@ updated: 2026-06-30
 | tools/mvc/talos/factors/get.php + post.php | created | Technical-only cost-factor editor (upsert TalosCostFactors). |
 | tools/assets/css/style.css | modified | Appended .pricing-table / .badge / form-grid / estimate-readout styles. |
 | tools/mvc/sso/get.php | modified | headers_sent() guard in tools_ssoFail() (500→graceful 401). |
-| tools/_/app/auth.php | modified | decryptHandoffValue() reads keys from Core.Parameters via db_toga2core; added handoffKeys() + CORE_DB const. |
+| tools/_/app/auth.php | modified | decryptHandoffValue() + currentApiSecret() read tokens from Core.Parameters via db_toga2core; handoffKeys() cache; CORE_DB const. |
+| tools/mvc/sso/initiate/get.php | modified | apiSecretAccessToken now from App_Auth::currentApiSecret() (Core.Parameters), not config. |
 
 ## Decisions made
-- **Pricing model:** flat monthly ORG FEE (the adjustable margin lever) + per-user fee that STEPS by user-count band; band rate schedule locked at signing. On a band crossing the per-user fee auto-steps to the agreed rate, THEN the org fee is adjusted to restore margin. Rejected: pure per-user banded (no lever) and both-vary.
-- **Cost methodology:** calibrate Langfuse→AWS (monthly factor = AWS_actual / Langfuse_costCorrected; new clients use a global blended factor). Rejected: AWS-only and Langfuse-only. Always use Langfuse's cache-corrected cost (it undercounts cache badly).
-- **Table location:** the **Team** DB (`_underscore::DB_TEAM`) — what the user called "Core.Teams". Tenant link to Core.Clients is a plain indexed column, NOT a hard FK (Team DB may be a separate instance).
+- **Pricing model:** flat monthly ORG FEE (adjustable margin lever) + per-user fee that STEPS by user-count band; band rate schedule locked at signing; on a band crossing the per-user fee auto-steps, THEN org fee is adjusted. Rejected: pure per-user banded; both-vary.
+- **Cost methodology:** calibrate Langfuse→AWS (monthly factor = AWS_actual / Langfuse_costCorrected; new clients use a global blended factor). Always use cache-corrected Langfuse cost. Rejected: AWS-only; Langfuse-only.
+- **Table location:** Team DB (`_underscore::DB_TEAM`). Tenant link to Core.Clients is a plain indexed column, NOT a hard FK (Team DB may be a separate instance).
 - **Onboarding writes:** direct DB write from the 1.0 tools app (not via api2) for speed.
-- **SSO keys from Core.Parameters:** sourced at runtime (rotated) instead of static config, via a `db_toga2core` connection alias; keeps current→previous rotation fallback. Rejected: continuing to read config `[saml]` tokens.
+- **SSO secret source:** the rotating `API_SECRET_ACCESS_TOKEN` (+ `_PREVIOUS`) lives ONLY in `Core.Parameters`, read by BOTH SSO legs (initiate encrypts RelayState; consumer decrypts current→previous) via the `db_toga2core` connection. Config copies go stale on rotation and silently break SSO. `[saml] true_client_uuid` and the IdP URLs STAY in config. Rejected: config-stored tokens.
 
 ## Blockers
-- **SSO login still fails until the `[database_toga2core]` connection is added to the tools configs and tools is redeployed** — the `db_toga2core` alias is referenced by `App_Auth::CORE_DB` but no `[database_toga2core]` section exists in `config.production.ini` yet (developer is handling creds). Section template: hostname `production-core-cluster.cluster-clwbyqvxdm4q.us-west-2.rds.amazonaws.com`, username awsroot, dbname `Core`.
-- All Talos UI pages need the `[database_team]` connection (db_team → Team DB) before they render data (also developer-supplied creds).
+- **SSO login still fails until `[database_toga2core]` is added to the tools configs AND tools is redeployed.** `App_Auth::CORE_DB='db_toga2core'` is referenced by both SSO legs, but no `[database_toga2core]` section exists in `config.production.ini` yet (developer handling creds). Template: hostname `production-core-cluster.cluster-clwbyqvxdm4q.us-west-2.rds.amazonaws.com`, username awsroot, dbname `Core`. DIAGNOSTIC: a **500 at initiate** = db_toga2core unconfigured (query against unregistered alias throws, uncaught); **/login?error=1** = empty/absent token in Core.Parameters.
+- `Core.Parameters.API_SECRET_ACCESS_TOKEN` must be populated and match the gateway; `[saml] true_client_uuid` must remain in config (consumer leg sso/get.php:80-84 reads it).
+- All Talos UI pages need the `[database_team]` connection (db_team → Team DB) before they render data.
 
 ## Exact next step
-> Add the `[database_toga2core]` section (alias db_toga2core, dbname=Core, host=production-core-cluster…us-west-2) to `tools/config.production.ini` (and the dev configs you test with), deploy tools, then attempt a fresh SSO login at https://tools.togatech.com/sso to confirm `decryptHandoffValue()` succeeds against the live rotated key.
+> Add `[database_toga2core]` (alias db_toga2core, dbname=Core, host=production-core-cluster…us-west-2) to `tools/config.production.ini` (and the dev configs you test with), confirm `Core.Parameters.API_SECRET_ACCESS_TOKEN` is set and `[saml] true_client_uuid` is still present, deploy tools, then click "Sign in with SSO" at https://tools.togatech.com — expect redirect to the IdP (not `/login?error=1`); a 500 at initiate means db_toga2core isn't wired.
 
 ---
 _Saved by /session-save on 2026-06-30_

package/package.json

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