toga-ai 1.0.201 → 1.0.203

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

@@ -6,6 +6,7 @@
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | `App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal used across all TOGa service request views. | library/app/model/toga/diagnostic.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
+| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php |

package/knowledge/1.0/apps/library/features/mvc-page-pattern-and-app-skeleton.md

@@ -0,0 +1,113 @@
+---
+title: 1.0 MVC Page Pattern & New-App Skeleton
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - library/app/framework.php
+  - library/app/frameworkindex.php
+  - library/app/mvc.php
+  - library/app/database.php
+  - library/app/model.php
+  - library/app/config.php
+related:
+  - ../architecture.md
+  - ../../togaview/architecture.md
+---
+
+## Summary
+
+This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding
+pages to one — the folder-based MVC routing, the page lifecycle, the model/DB conventions, and
+the minimal new-app skeleton. The `library` core supplies all of it; an app contributes only its
+`index.php`, config, `_/app/` framework subclasses, `mvc/` pages, and `common/` templates.
+togaview is the reference implementation (see its architecture doc for the multi-tenant
+specifics); this doc captures the framework-level pattern that any new 1.0 app reuses.
+
+## How it works
+
+### Folder-based, classless routing
+A URL maps directly to a file on disk — **the file path IS the route**, there is no routing
+config and no controller classes. `App_MVC::parseRoute()` turns the request URI into
+`mvc/<folder…>/<httpmethod>.php`, matching **longest-to-shortest** so overlapping paths resolve
+to the most specific folder.
+
+```
+GET  /task_list/ajax   ->  mvc/task_list/ajax/get.php
+POST /login            ->  mvc/login/post.php
+```
+
+- `<httpmethod>` is `get` or `post`, taken from the HTTP verb (overridable via a `_method` POST param).
+- `get.php` renders a page; `post.php` does writes then redirects via `App_MVC::routeTo()`
+  (`header('Location: …'); exit;`).
+- Because matching is longest-to-shortest, keep route folders distinct to avoid surprise matches.
+
+### Entry point (3 lines)
+```php
+require '_.php';                          // bootstraps library core + autoloader
+App_Framework_<App>::initialize();        // env, config, DB links, session, Sentry
+App_Framework_<App>::renderIndex();       // resolves stylePath + dispatches the page
+```
+App-specific framework classes live in `<app>/_/app/` and extend the library bases
+`App_Framework` (`framework.php`) and `App_FrameworkIndex` (`frameworkindex.php`).
+
+### Page lifecycle (no template engine)
+`App_FrameworkIndex::body()` loads the matched mvc file **inline** between
+`common/<stylePath>/header.php` and `common/<stylePath>/footer.php`. There is no master-template
+engine — pages are inline PHP + HTML. `stylePath` is selected by `$_SERVER['HTTP_HOST']` in
+`framework.php::renderIndex()`, giving per-brand CSS under `assets/css/<stylePath>/`. Pages guard
+auth themselves by checking `$_SESSION` at the top.
+
+### Adding a page
+Create `mvc/<page>/get.php` (and `post.php` if it writes). Scaffold from `mvc/_TEMPLATE/`.
+
+### Models
+Extend `App_Model`, named `App_Model_<Db>_<Table>`, declaring `const TABLENAME`, `const DATABASE`,
+and `public $field = self::FIELDTYPE_*` for each column. Field types: `PRIMARYKEY`, `INT`, `CHAR`,
+`DATETIME`, `BLOB`, `BLOBSTORAGE`, `FOREIGNKEY`, `SERIALIZED`, `DATETIME_CREATED`,
+`DATETIME_UPDATED`.
+
+```php
+class App_Model_Toga_Client extends App_Model {
+    const TABLENAME = 'Clients';
+    const DATABASE  = 'db_toga';
+    public $id         = self::FIELDTYPE_PRIMARYKEY;
+    public $clientName = self::FIELDTYPE_CHAR;
+}
+```
+Usage: `new App_Model_X($id)` loads a row; `->save()` persists; `App_Model_X::lookupValueByField()`.
+
+### Databases (multiple are first-class)
+DB access is mysqli via `App_Database::query($sql, 'db_<name>')`. **Multiple databases are
+first-class:** each `[database_<name>]` section in `config.<env>.ini` is registered as registry
+key `db_<name>` by `App_Database::registerDatabaseConnect()`. SELECTs **auto-route to
+`<link>_read`** when the host is an RDS cluster (read-cluster support). Escape with
+`App_Database::sqlEscape()`; read results with `buildArrayOfRows()` / `fetchRow()`.
+
+### Config
+`App_Config` does `parse_ini_file(config.<ENVIRONMENT>.ini)`; the environment comes from
+`getenv('ENVIRONMENT')` (defaults to `'worker'` — an unset env loads the wrong file). Sections:
+`[internal]`, `[database_*]`, `[email]`, `[external]`, `[modules]`, `[api]`.
+
+> **Secrets are currently stored in plaintext ini files** — a known practice, not a recommended
+> one. Document where a credential lives, never its value.
+
+## Minimal new-app skeleton
+```
+index.php                              # the 3-line entry point
+config.<env>.ini                       # per-environment config + DB sections
+mvc/_TEMPLATE/get.php                  # page scaffold
+mvc/<page>/{get,post}.php              # one folder per route
+common/<stylePath>/{header,footer}.php # brand shell wrapped around each page
+common/404.php
+assets/                                # css/js per stylePath
+```
+The app depends on the `library` core repo (bootstrapped via `_.php`).
+
+## Change history
+- 2026-06-25 — Documented the 1.0 folder-based MVC page pattern, model/multi-DB conventions, and the minimal new-app skeleton, discovered while planning the new "Toolbox" 1.0 app (reference: togaview) (jcardinal)

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

@@ -3,4 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [saml Architecture](architecture.md) | The `saml` repo is the SAML 2.0 / SSO gateway for all TOGa applications. | saml/index.php, saml/_.php, saml/Controller/Index.php, saml/Config/production.ini, saml/.platform/hooks/prebuild/git.sh, saml/.ebextensions/git.php |
+| [SAML Downstream Integration Contract](features/downstream-integration-contract.md) | The contract a **downstream TOGa app** implements to authenticate users through the SAML gateway (`saml.togahub.com`). | saml/Controller/Index.php, _underscore/Model/Core/ClientAuthentication.php, _underscore/Model/True/ClientAuthentication.php |
 | [Rate SAML User Provisioning](features/rate-user-provisioning.md) | When a Rate user authenticates via SSO, `_Model_Rate_ClientAuthentication::getAuthenticatedSsoUser()` is called by the saml gateway. | _underscore/Model/Rate/ClientAuthentication.php, _underscore/Model/Rate/User.php, _underscore/Model/Rate/Customer.php, _underscore/Model/Rate/Contact.php |

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

@@ -7,7 +7,7 @@ client: shared
 type: architecture
 status: active
 updated: 2026-06-11
-owners: ["rgirish"]
+owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
   - saml/_.php
@@ -80,9 +80,11 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 ## Gotchas / known issues
 
 - **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026).** Any code that registers DBs then writes must call `_Database::transactionCommit()` before exiting — otherwise MySQL silently rolls back all writes on connection close. The `/acs` handler calls `transactionCommit()` after `getAuthenticatedSsoUser()` succeeds and before the redirect. See `_underscore/Database.php:48`.
-- **SAML signature verification is commented out.** The IdP X509 cert verification block is disabled. The only gate is the encrypted RelayState. Re-enabling per-IdP signature verification is a priority security improvement.
+- **SAML signature verification is commented out — this is the repo's top security priority.** The IdP X509 cert verification block in the `/acs` flow is disabled, so the gateway accepts any well-formed, status-success `SAMLResponse` without proving it was signed by the expected IdP. The only remaining gate is the encrypted RelayState, which authenticates the *originating TOGa request* — not the *asserting IdP*. Threat model: an attacker who can craft or replay a `SAMLResponse` (or a malicious/compromised IdP) can forge an identity assertion for any user, since nothing binds the assertion to a trusted signing key. Re-enabling per-IdP X509 signature verification is the single highest-impact security fix for this repo.
+- **Plaintext secrets in source — move to AWS SSM Parameter Store.** `saml/Config/production.ini` stores credentials in plaintext, and a Sentry DSN is hardcoded in `saml/Controller/Index.php`. Both are checked into the repo. Migrate these to AWS SSM Parameter Store (SecureString) and load at runtime; the source tree should reference parameter names only, never literal credential values.
 - **SLS not implemented.** `/sls` falls through to the default banner.
 - **`set_exception_handler(null)` at top of `saml()`.** Unhandled exceptions output raw PHP errors. All exceptions from `getAuthenticatedSsoUser()` are caught and sent to Sentry.
 
 ## Change history
 - 2026-06-11 — Added `transactionCommit()` before redirect; wrapped `getAuthenticatedSsoUser()` in try/catch with Sentry; echo+exit on auth failure (rgirish)
+- 2026-06-25 — Sharpened signature-verification gotcha with explicit threat model and flagged it as the repo's top security priority; documented plaintext secrets in `production.ini` + hardcoded Sentry DSN in `Controller/Index.php` with SSM Parameter Store recommendation (jcardinal)

package/knowledge/2.0/apps/saml/features/downstream-integration-contract.md

@@ -0,0 +1,81 @@
+---
+title: SAML Downstream Integration Contract
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - saml/Controller/Index.php
+  - _underscore/Model/Core/ClientAuthentication.php
+  - _underscore/Model/True/ClientAuthentication.php
+related:
+  - ../architecture.md
+  - ../../_underscore/architecture.md
+  - ../../../clients/rate/features/saml-sso.md
+---
+
+## Summary
+
+The contract a **downstream TOGa app** implements to authenticate users through the SAML gateway
+(`saml.togahub.com`). The architecture doc covers the gateway internals; this doc is the
+**integration recipe** for an app that wants SSO — how to initiate the flow, what the gateway
+hands back, and how to consume it. Reusable for any new SSO-consuming app.
+
+## How it works
+
+### SP-initiated flow
+1. The downstream app calls
+   `_Model_Core_ClientAuthentication::singleSignOnServiceUrl(uuid, domainUuid, urlParameters)`
+   to build a signed SAML AuthnRequest (HTTP-Redirect binding). The RelayState
+   (`{v:1, time, domain, urlParameters}`) is encrypted with the Core `API_SECRET_ACCESS_TOKEN`
+   and carries a 300-second TTL.
+2. The user authenticates at the client IdP, which POSTs the `SAMLResponse` to the gateway `/acs`.
+3. `/acs` decrypts RelayState (supports key rotation via `API_SECRET_ACCESS_TOKEN_PREVIOUS`),
+   resolves Core `Domain → Client → Environment`, **dynamically registers the client DBs**
+   (`DB_CLIENT`, `DB_CLIENT_LOGS`, `DB_CLIENT_ARCHIVE`), then calls the client-specific mapper
+   `_Model_<ClientIdentifier>_ClientAuthentication::getAuthenticatedSsoUser($assertion)` to
+   resolve or create the user.
+   - Base `_Model_True_ClientAuthentication` matches by **email** (from the NameID).
+   - Compass matches `c_hrEmpUsername`; Rate matches `borrowerID`.
+
+### Handoff back to the downstream app
+The gateway redirects the browser to:
+```
+<appDomain>?saml=<base64(json)>
+```
+where the JSON is:
+```json
+{
+  "auth": "encrypted-user-uuid",
+  "payload": { "client": "encryptWithKey(client.uuid)", "user": "encryptWithKey(user.uuid)" }
+}
+```
+all encrypted under the Core `API_SECRET_ACCESS_TOKEN`. An optional `?urlParameters` is forwarded
+through.
+
+The downstream app then: base64-decodes the `saml` param, JSON-parses it, decrypts the client and
+user UUIDs with `_String::decryptWithKey()`, loads the user, and **establishes its own session**.
+The gateway holds no session — session ownership is entirely the downstream app's.
+
+### Integrating a NEW downstream app
+1. Ensure an SSO config row exists in `_Model_Core_ClientAuthentications_Sso`.
+2. Implement/extend `_Model_<Client>_ClientAuthentication::getAuthenticatedSsoUser()` in
+   `_underscore` (the gateway repo is not modified — see the per-client extension pattern in the
+   architecture doc).
+3. Initiate SSO via `singleSignOnServiceUrl()`.
+4. Consume the `?saml=` handoff and decrypt the UUIDs with `API_SECRET_ACCESS_TOKEN`.
+
+## Gotchas / known issues
+
+- **Lazy-transaction write-drop.** `_Database::register()` auto-starts a lazy transaction (since
+  Apr 2026). Any `/acs` write path (e.g. user auto-creation) must call
+  `_Database::transactionCommit()` before exit or the writes are silently rolled back.
+- **Gateway holds no session** — every downstream app must build and own its own session from the
+  decrypted handoff.
+
+## Change history
+- 2026-06-25 — Documented the downstream integration contract (SP-initiated flow, `?saml=` handoff shape, and the 4 onboarding steps), discovered while planning a new SSO-consuming app (reference: saml) (jcardinal)

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -3,7 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md |
+| [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/ |
 | [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 |

package/knowledge/2.0/apps/toga25-supply/features/action-button-rule-engine.md

@@ -0,0 +1,119 @@
+---
+title: Action-Button Rule Engine (Flag / Rule grammar)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [apeterson]
+files:
+  - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx
+related:
+  - client-configurable-fields.md
+  - ../architecture.md
+---
+
+## What it is
+
+A declarative, fully config-driven rule engine that resolves the boolean-ish flags
+(`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. Every such
+flag is a **`Flag`** — either a static `true`/`false` or a **`Rule`** tree evaluated against
+the order's runtime state. Because the entire grammar is data, the backend can ship a rule
+tree verbatim and adding or re-gating a button becomes a pure config change with no frontend
+code edit. This is the realization of the long-stated goal that SalesOrders action-button
+config be completely field-driven and backend-suppliable.
+
+## How it works
+
+The engine lives in `src/pages/SalesOrders/helpers/evaluateEnableRule.ts` and is applied by
+`buildPatchedTenantFields.ts`.
+
+### The grammar
+
+```ts
+type Flag = boolean | Rule | undefined;
+
+type Rule =
+  | { all: Rule[] }                          // AND — every child true
+  | { any: Rule[] }                          // OR  — at least one child true
+  | { not: Rule }                            // NOT
+  | { field: string; op: FieldOp; value? }   // dot-path predicate into RuleContext
+  | { type: string };                        // named domain primitive (rare)
+
+type FieldOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte"
+             | "in" | "nin" | "truthy" | "falsy";
+```
+
+- **Field predicates** address into the `RuleContext` by dot-path (e.g. `order._status`,
+  `currentStage.ApprovalTemplateStages.step`). `getByPath` walks the path with optional
+  chaining; a missing path yields `undefined`.
+- **`RuleContext`** is `{ order, currentStage?, stages? }`. `currentStage`/`stages` carry
+  approval-workflow state when available.
+- **Named rules** (`{ type }`) are bespoke leaf checks that a field predicate cannot express
+  — they live in the `NAMED_RULES` registry. Currently only `stepTwoAssigned` (walks the
+  approval stages to confirm a step-2 assignee exists). An unknown `type` resolves to `true`.
+
+### Resolution primitives
+
+- `evaluateRule(rule, ctx): boolean` — recursive evaluator over the combinators.
+- `resolveFlag(flag, ctx, fallback = false): boolean` — the single primitive behind every
+  flag. Static booleans pass through; an object is treated as a `Rule` and evaluated;
+  `undefined` returns `fallback`. The same prop can therefore be static for one client and
+  rule-driven for another with **no code change**.
+
+### Applying flags to tenant config
+
+`buildPatchedTenantFields({ tenantFields, context })` maps over
+`tenantFields.recordActionFields.actionOptions` and patches each option's resolvable flags:
+
+- `isEnabled` — via `resolveActionEnabled` (see back-compat below).
+- `isVisible` and `isComplete` — only patched when the key is present on the option, each via
+  `resolveFlag(..., false)`.
+
+It returns a new `tenantFields` with a patched `recordActionFields.actionOptions`. Callers:
+`useSalesOrderRecordModalLayoutModel.tsx` and `useApprovalModalViewModel.tsx`.
+
+### Back-compat shim
+
+The previous single-purpose `EnableRule` grammar (`alwaysEnabled`, `requireStepTwoAssigned`,
+`requireOrderField`, `statusIn`) is mapped onto the generic engine via `evaluateEnableRule`,
+so existing configs keep working while they migrate to `Rule`. `resolveActionEnabled` picks
+the path:
+
+1. `isEnabled` is an object → treat as a `Rule`, `resolveFlag`.
+2. else a separate `enableRule` exists → legacy `evaluateEnableRule`.
+3. else → return the static `isEnabled`.
+
+Retire the shim once all configs express flags as `Rule`.
+
+## Adding or re-gating a button
+
+1. **Pure config change (preferred):** edit the action option's `isEnabled` / `isVisible` /
+   `isComplete` in the per-client `recordActionFields` config to a static boolean or a `Rule`
+   tree. No code edit. The backend can ship the same tree.
+2. **New primitive check only:** if a gate genuinely can't be expressed as field predicates
+   + combinators (e.g. it must walk approval stages), add one entry to `NAMED_RULES` and
+   reference it as `{ type: "yourCheck" }`. This is the only expected reason to edit the
+   engine file.
+
+## Gotchas
+
+- **`recordActionFields` is the current key** (renamed from `approvalActionFields` /
+  `orderViewFields`-era naming). `buildPatchedTenantFields` reads
+  `recordActionFields.actionOptions`; missing config falls back to `[]`.
+- **`isVisible` / `isComplete` default to `false`** when present-but-undefined, while
+  `isEnabled` falls through to its static value. Don't assume a missing flag means "shown".
+- **The table row menu (`RowActionButtons.tsx`) reads raw config directly** and is
+  intentionally out of scope for rule-driven enablement — it does not go through
+  `buildPatchedTenantFields`.
+- **Prefer the `Rule` grammar over magic named keys.** Anything expressible as a field
+  comparison must stay config-only; adding to `NAMED_RULES` is the rare exception, not the
+  default.
+
+## Change history
+- 2026-06-25 — Documented the generic Flag/Rule engine: combinators, field predicates, named-rule registry, `resolveFlag`/`buildPatchedTenantFields`, and the legacy `EnableRule` back-compat shim. (apeterson)

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-23
+updated: 2026-06-25
 owners: [apeterson]
 files:
   - toga25-supply/src/fieldsConfig/index.ts
@@ -14,9 +14,12 @@ files:
   - toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/
   - toga25-supply/src/pages/Inventory/viewModel/FIELDS/
   - toga25-supply/src/pages/Inventory/README.md
+  - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/
+  - toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/
 related:
   - ../architecture.md
   - column-visibility.md
+  - action-button-rule-engine.md
 ---
 
 ## What it is
@@ -28,10 +31,13 @@ and the `useClientFields()` hook.
 
 ## How it works
 
-1. **Per-client JSON lives next to the consuming page**, under `FIELDS/<CLIENT>/`
-   (e.g. `src/pages/SalesOrders/viewModel/FIELDS/COMPASS/salesOrdersPageFields.json`). There is
-   **always a `DEFAULT/`** folder every client falls back to. `<CLIENT>` must match the hostname
-   `clientSlug` (uppercase — `COMPASS`, `NYCHH`, …).
+1. **Per-client JSON lives next to the consuming page _or layout_**, under `FIELDS/<CLIENT>/`
+   (e.g. `src/pages/SalesOrders/viewModel/FIELDS/COMPASS/salesOrdersPageFields.json`, or for a
+   record-modal layout `src/layout/ItemRecordModalLayout/viewModel/FIELDS/COMPASS/itemRecordViewFields.json`).
+   There is **always a `DEFAULT/`** folder every client falls back to. `<CLIENT>` must match the
+   hostname `clientSlug` (uppercase — `COMPASS`, `COMPASSCANADA`, `NYCHH`, …). Record-modal layouts
+   typically split their config per modal mode — `*ViewFields.json`, `*EditFields.json`,
+   `*CreateFields.json` — one file per mode, per client.
 2. **`src/fieldsConfig/index.ts`** imports those JSON files and wires them into the
    `ClientFields` bundle — a normalized `FIELDS[clientSlug][role]` map merged over `DEFAULT`.
 3. **`useClientFields()`** resolves the active `clientSlug` (from `useHostnameStore`) + `role`
@@ -64,6 +70,22 @@ registry that maps enum → real value (e.g. `MODAL_RENDERERS: Record<ModalKey,
 This is the one place app-owned JSX is grafted back onto client-authored config. Clients never
 author JSX.
 
+### Record-modal header & action config
+
+Record-modal layouts (`ItemRecordModalLayout`, `VendorItemRecordModalLayout`) now drive the
+modal's chrome from the same per-client JSON, not from the component:
+
+- **`header`** — `{ modalTag: { icon, iconStyle, title }, labelTemplate, statusBadge }`.
+  `labelTemplate` is a `"{dotted.path} literal"` string resolved against the record (same
+  `fillTemplate` convention as `optionLabelTemplate`). `statusBadge` is
+  `{ field, activeLabel, inactiveLabel }` — the component reads `record[field]` (e.g.
+  `isActive`) and renders the matching label. The component bakes in no titles or labels.
+- **`editItem`** — a `{ valueKey, kind: "button", label, icon, isVisible, isEnabled }` action
+  block. `isVisible` / `isEnabled` are `Flag`s, so the Edit button is gated declaratively per
+  client (e.g. visible+enabled for vendor items, hidden for the DEFAULT item view). These flags
+  resolve through the same engine as SalesOrder action buttons — see
+  [action-button-rule-engine.md](action-button-rule-engine.md).
+
 ## Adding a new client-configurable field
 
 1. Author the serializable JSON under `FIELDS/DEFAULT/<thing>.json` + a folder per overriding client.
@@ -81,8 +103,18 @@ author JSX.
 - **New client *file* = no code change** (just import/wiring). **New render style/modal type
   (new enum value) = code change** in the hydration registry — that's the intended boundary
   between client config and app rendering.
+- **Flat (un-wrapped) bundles need a fallback that tolerates the missing `DEFAULT` key.** Some
+  bundles wrap their config under a top-level `DEFAULT` key, others are authored flat. In
+  `fieldsConfig/index.ts`, derive the default defensively rather than assuming the wrapper exists:
+  `const DEFAULT_ORDER_VIEW_FIELDS = (defaultBundle as any).DEFAULT ?? (defaultBundle as any) ?? {};`
+  — fall through to the bundle itself, then `{}`, so a flat JSON file does not resolve to `undefined`.
 - Worked examples: `salesOrdersPageFields` (client × role) and `inventoryGroupings` (client-only +
-  hydration; full write-up in `src/pages/Inventory/README.md`).
+  hydration; full write-up in `src/pages/Inventory/README.md`); `itemRecordViewFields` /
+  `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 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)
+- 2026-06-25 — Client field JSON also lives under `src/layout/<Modal>/viewModel/FIELDS/<CLIENT>/`
+  (record-modal layouts; split per mode: View/Edit/Create). Documented the defensive
+  `?? (defaultBundle) ?? {}` fallback for flat (un-`DEFAULT`-wrapped) bundles. (apeterson)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 8 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 9 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 10 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
@@ -20,14 +20,14 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 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)
-- **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
+- **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 4 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 6 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 6 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework
@@ -51,6 +51,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
+- **TOGA Technology** (`true`) → [clients/true/INDEX.md](clients/true/INDEX.md)
 - **Walmart Client Profile** (`walmart`) → [clients/walmart/INDEX.md](clients/walmart/INDEX.md)
 - **Wiss, Janney, Elstner Associates, Inc.** (`wje`) → [clients/wje/INDEX.md](clients/wje/INDEX.md)
 

package/knowledge/clients/true/INDEX.md

@@ -0,0 +1,6 @@
+# Client: TOGA Technology `true`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [True Users / Personas Data Model](features/users-personas-data-model.md) | 2.0 | The `Client_True` schema models internal/staff users and their **personas** — used to gate UI and navigation by staff role in downstream tooling. |  |
+| [TOGA Technology](profile.md) | 2.0 | "True" is TOGa's own **internal / staff tenant** — the base client whose data lives in the `Client_True` schema in production. |  |

package/knowledge/clients/true/features/users-personas-data-model.md

@@ -0,0 +1,45 @@
+---
+title: True Users / Personas Data Model
+framework: "2.0"
+project: _Underscore
+client: true
+type: client-feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files: []
+related:
+  - clients/true/profile.md
+  - 2.0/apps/saml/features/downstream-integration-contract.md
+---
+
+## Summary
+
+The `Client_True` schema models internal/staff users and their **personas** — used to gate UI and
+navigation by staff role in downstream tooling. After SSO resolves a user, an app looks up that
+user's personas and drives visibility from persona membership.
+
+## How it works
+
+### Tables
+- **`Users`** — key columns: `id`, `uuid` (char, unique), `email` (varchar, unique), `firstName`,
+  `lastName`, `displayName`, `isActive` (tinyint, default `1`), `password` (char, nullable), plus
+  FKs `contactId`, `clientId`, `locationId`, `userTypeId`, `supervisorUserId`.
+- **`Personas`** — `id`, `uuid`, `name`, `number`.
+- **`Users_Personas`** (many-to-many bridge) — `id`, `uuid`, `userId`, `personaId`.
+
+### Live personas (production)
+TOGa Technology, Development Team, Legal Team, Contact Center, Operations, Executive, Audit.
+
+### Usage pattern for downstream apps
+After SSO resolves the user, look up their personas via
+`Users JOIN Users_Personas JOIN Personas`, then drive UI / navigation visibility by persona
+membership.
+
+## Gotchas / known issues
+
+- **Cache personas in session.** Cache the resolved persona names in `$_SESSION` at login to avoid
+  a per-request DB read for visibility checks.
+
+## Change history
+- 2026-06-25 — Documented the Client_True Users/Personas data model and persona-gated UI usage pattern, discovered via prod DB schema inspection while planning persona-gated internal tooling (jcardinal)

package/knowledge/clients/true/profile.md

@@ -0,0 +1,26 @@
+---
+title: "TOGA Technology"
+framework: "2.0"
+apps:
+  - _underscore
+project: _Underscore
+client: true
+type: profile
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files: []
+related:
+  - clients/true/features/users-personas-data-model.md
+---
+
+## Summary
+
+"True" is TOGa's own **internal / staff tenant** — the base client whose data lives in the
+`Client_True` schema in production. It is also the default SSO identity mapper
+(`_Model_True_ClientAuthentication`, which matches users by email). Internal tooling that gates UI
+by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` model.
+
+- **Client DB:** `Client_True`
+- **Client identifier:** `True`
+- **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)

package/package.json

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