toga-ai 1.0.205 → 1.0.207

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

@@ -103,3 +103,13 @@ packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
 - **Timezone** is always `America/Chicago` (set in `_.php`).
 - **`__APPROOT__`** is resolved by locating an ancestor folder named `_`; each app must
   have that `_` folder at its root.
+
+## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
+
+`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do
+**AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl
+flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0
+`_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0
+gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method
+changed, no behavior change for existing apps. First consumer: the Tools app's `App_Auth`
+(`1.0/apps/tools/features/saml-sso-auth.md`).

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

@@ -0,0 +1,8 @@
+# tools (Tools) — 1.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [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/_/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 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 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/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php |

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

@@ -0,0 +1,81 @@
+---
+title: Tools (1.0 Internal-Tools App) Architecture
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: architecture
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/index.php
+  - tools/_/app/framework.php
+  - tools/_/app/frameworkindex.php
+  - 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
+related:
+  - ./features/saml-sso-auth.md
+  - ./features/persona-gated-navigation.md
+  - ./features/developer-tools.md
+  - ../library/architecture.md
+  - ../library/features/mvc-page-pattern-and-app-skeleton.md
+---
+
+## Summary
+
+**Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind
+simple interfaces, gated by Client_True staff persona. It is modeled on `togaview` and depends on
+the `library` core. Auth comes via the SAML gateway `?saml=` handoff; the app owns its own
+session and reads `Client_True` **read-only**. Adding a tool = create `mvc/<route>/get.php`
+(copy `mvc/_TEMPLATE`) + add one `App_Nav::definition()` entry + `App_Auth::requireAuth([...])`.
+
+**Critical rules:** Do NOT use bare `<header>` elements in this app — they inherit the legacy
+dashboard stylesheet's `header{position:fixed;width:100vw}` rule and cause horizontal scroll
+(the top header bar was removed for exactly this reason). A nav action's `route` maps **1:1** to
+`mvc/<route>/get.php`. Auth fails **closed** and never auto-creates users; the dev bypass is
+double-gated (`[internal] dev_mode` AND `App_Registry::inDevMode()`). `config.*.ini`
+(incl. `config.prod.ini`) is committed with plaintext production secrets — a known, team-accepted
+risk (see Known issues); never add more secrets and treat these as compromised if leaked.
+
+## Boot & structure
+
+Standard 3-line `index.php`: `require '_.php'; App_Framework_Tools::initialize();
+App_Framework_Tools::renderIndex();`. App-specific framework subclasses
+`App_Framework_Tools` / `App_FrameworkIndex_Tools` live in `_/app/`. The 1.0 folder-based MVC
+page pattern is unchanged from the library skeleton (see the library feature doc).
+
+`App_Framework_Tools::initialize()` sets the session cookie HttpOnly + SameSite=Lax before
+calling the parent initialize.
+
+## Layout (single-style app)
+
+No per-host `stylePath` subfolder — one `assets/css/style.css`. Uses TOGA Technology logos in
+`assets/img` (`toga-brandmark-white.png` in the dark sidebar; `toga-horizontal-colored.png` on
+login/welcome). A fixed left two-column shell: dark left sidebar (`.app-nav`) with brand at top,
+persona-filtered nav in the middle, pinned footer with the user's name + a ghost "Log out"
+button; content area on the right. **No top header bar** (see Critical rules).
+
+## Home route
+
+`/` (`mvc/get.php`) renders a persona-filtered dashboard of available tools (tiles grouped by
+folder) when logged in, via `App_Nav::visibleGroups()`, or a welcome/sign-in card when not.
+
+## Adding a tool
+
+Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one entry to
+`App_Nav::definition()`, and put `App_Auth::requireAuth([...personas])` at the top. Documented in
+`docs/ADDING_A_TOOL.md`. See the App_Nav and App_Auth feature docs.
+
+## Known issues / security
+
+- **Plaintext secrets committed to git.** `config.*.ini` (incl. `config.prod.ini`) contains
+  plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The team has
+  **accepted this for now** (developer decision, 2026-06-25). Future remediation: git-ignore the
+  config files and rotate all exposed credentials. (Location only — no values recorded here.)
+- **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.

package/knowledge/1.0/apps/tools/features/developer-tools.md

@@ -0,0 +1,37 @@
+---
+title: Tools — Developers Folder (UUID & Password Generators)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/mvc/developers/uuid/get.php
+  - tools/mvc/developers/password/get.php
+related:
+  - ../architecture.md
+  - ./persona-gated-navigation.md
+---
+
+## Summary
+
+The first two tools shipped in the Tools app, both under the **Developers** folder and gated to
+personas **Development Team** / **TOGa Technology**. They are the reference example of the
+"one small tool = one `mvc/<route>/get.php`" pattern.
+
+## How it works
+
+### Generate UUID (`mvc/developers/uuid/get.php`)
+- Server generates an RFC 4122 **v4** UUID via `random_bytes(16)` with version/variant bits set.
+- UI is click-to-copy, then instant **client-side** regenerate using `crypto.getRandomValues`.
+
+### Generate Password (`mvc/developers/password/get.php`)
+- Reproduces the standalone `test/team/generate_password.php` script.
+- `App_String::generateSupportCode(8)` produces the password; `App_String::passwordHash()`
+  produces the bcrypt hash. The page shows **both** the password and the hash, each copyable.
+
+## Change history
+- 2026-06-25 — Built the first two Developers tools: RFC 4122 v4 UUID generator and a password+bcrypt-hash generator (ported from test/team/generate_password.php), both gated to Development Team / TOGa Technology personas (jcardinal)

package/knowledge/1.0/apps/tools/features/persona-gated-navigation.md

@@ -0,0 +1,44 @@
+---
+title: Tools Persona-Gated Navigation (App_Nav)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/_/app/nav.php
+related:
+  - ../architecture.md
+  - ./saml-sso-auth.md
+---
+
+## Summary
+
+`App_Nav` is the Tools app's two-level, **persona-gated** navigation. The structure is a single
+**hard-coded `definition()` array** (NOT in the DB), so developers/Claude edit it directly. It
+drives both the left-rail nav and the home dashboard, and is the single source of truth for which
+personas may reach a given route.
+
+## How it works
+
+### Structure
+- Two levels: **folders** (grouping) → **actions** (each loads a page).
+- Each folder and each action carries a `personas` list. An item is visible iff
+  `App_Auth::hasAnyPersona()` matches — folder gate plus an optional per-action gate.
+
+### Render surfaces
+- `render()` — emits the filtered left-rail nav with active-route highlighting.
+- `visibleGroups()` — returns the filtered structure as data for the home dashboard tiles.
+- `personasForRoute()` — returns the union of folder+action personas so a page can self-guard
+  with `App_Auth::requireAuth(...)` using the same data the nav used.
+
+### Route convention
+An action's `route` (e.g. `/developers/uuid`) maps **1:1** to `mvc/<route>/get.php`. Adding a
+tool means creating that file and adding one entry to `definition()` — see
+`docs/ADDING_A_TOOL.md` and the architecture doc.
+
+## Change history
+- 2026-06-25 — Built App_Nav: hard-coded two-level persona-gated navigation; render() for the left rail, visibleGroups() for the dashboard, personasForRoute() for page self-guarding; route maps 1:1 to mvc/<route>/get.php (jcardinal)

package/knowledge/1.0/apps/tools/features/saml-sso-auth.md

@@ -0,0 +1,76 @@
+---
+title: Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/_/app/auth.php
+  - tools/mvc/sso/get.php
+  - tools/mvc/login/get.php
+  - tools/mvc/login/post.php
+  - tools/mvc/logout/get.php
+related:
+  - ../architecture.md
+  - ../../../2.0/apps/saml/features/downstream-integration-contract.md
+  - ../../../clients/true/features/users-personas-data-model.md
+---
+
+## Summary
+
+`App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=`
+handoff (see the 2.0 SAML downstream integration contract), establishes its own session, and
+gates every page by **Client_True persona**. The gateway holds no session — session ownership
+is entirely this app's. Auth fails **closed** to a self-contained 401 page; users are **never**
+auto-created.
+
+## How it works
+
+### Consuming the `?saml=` handoff (`mvc/sso/get.php` → `App_Auth`)
+1. Length-guard `$_GET['saml']`, then base64-decode → `json_decode` → read `payload.client`
+   and `payload.user`.
+2. Decrypt each with `App_String::decryptWithKey()` using config `[saml] api_secret_access_token`,
+   with a **dual-key retry** against `api_secret_access_token_previous` (supports gateway key
+   rotation). This interoperates byte-for-byte with the 2.0 `_String::encryptWithKey()` that
+   produced the token (see the library `App_String` crypto methods).
+3. Validate the decrypted **client uuid == configured `true_client_uuid`** via `hash_equals`,
+   and that both decrypted values match a UUID regex.
+4. Load the active Client_True user: `WHERE uuid = ? AND isActive = 1`. No match → fail closed.
+
+### Session establishment (`establishSession()`)
+- Calls `session_regenerate_id(true)`, then caches the user and **persona names** in `$_SESSION`.
+- Persona lookup (read-only `db_true`):
+  `SELECT p.name FROM Users u JOIN Users_Personas up ON up.userId=u.id JOIN Personas p ON p.id=up.personaId WHERE u.uuid = <escaped>`.
+- The session cookie is set **HttpOnly + SameSite=Lax** in `App_Framework_Tools::initialize()`
+  before the parent initialize runs.
+
+### Page guarding
+- `requireAuth([personas])` at the top of each page; `hasAnyPersona()` is `array_intersect`
+  against the cached session personas. App_Nav uses the same cached data to filter the nav.
+
+### Dev bypass (double-gated, fails closed in prod)
+`mvc/login/post.php` permits **email-only** login **only** when config `[internal] dev_mode`
+is truthy **and** `App_Registry::inDevMode()` — both must hold. When used it writes a `SECURITY`
+line to `error_log`.
+
+## Gotchas / known issues
+
+- **SSO initiation is not implemented in this 1.0 app.** Building the signed AuthnRequest lives
+  in 2.0 `_underscore` (`singleSignOnServiceUrl()`); login here points at a configurable
+  `[saml] initiation_url` **placeholder**. Open item: needs a gateway initiation entry point or
+  a ported builder.
+- **No app-side replay defense.** The handoff token carries no nonce/timestamp the app verifies.
+  Recommend the gateway embed `iat` + `jti`.
+
+## Config keys
+
+`[database_true]` (read-only Client_True); `[saml]` `api_secret_access_token` /
+`api_secret_access_token_previous`, `initiation_url`, `client_authentication_uuid`,
+`domain_uuid`, `true_client_uuid`; `[internal]` `dev_mode`.
+
+## Change history
+- 2026-06-25 — Built App_Auth: SAML `?saml=` handoff consumer with dual-key decrypt, hash_equals client-uuid check, fail-closed 401, persona-cached session (HttpOnly+SameSite=Lax), and a double-gated dev bypass. Initiation + replay defense left as open items (jcardinal)

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

@@ -11,5 +11,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, _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/architecture.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-06-11
+updated: 2026-06-25
 owners: ["jcardinal", "rgirish"]
 files:
   - _underscore/_underscore.php
@@ -32,6 +32,9 @@ Minimum PHP 8.1 (enforced in `_underscore.php`). The current architecture is
 `_Worker_*`). Always use parameterized queries / the `_Db` layer — never interpolate input into SQL.
 Beware the **lazy-transaction gotcha**: writes issued outside an explicitly committed transaction
 can be silently dropped — confirm commit semantics before relying on a write.
+The Surface presentation layer replaces `Page::meta()` but `meta()` must NOT be deleted until
+every page is cut over (per-surface, with a parity diff); config describes, PHP decides —
+business logic never moves into Surface config.
 
 ## Entry point & boot sequence
 
@@ -44,6 +47,41 @@ Every 2.0 project's `index.php` is just `<?php require '_underscore.php';`.
    (parses INI) → `_Time::initialize()` → **`_underscore::initialize()`** (project hook,
    required) → `_Session::initialize()` → `_Route::initialize()` (web only).
 
+## Surface — platform UI presentation/configuration layer
+
+A DB-driven UI presentation layer (2026-06-25, CTO-reviewed: AGREE-WITH-ADJUSTMENTS) that
+serves UI config (labels, theme tokens, visibility/enable, icons, tooltips, button bars,
+table quick-actions, status badges, modals) to React frontends so UI changes need no
+front-end deploy and are editable by a future admin app over plain CRUD. Platform-wide
+across all 2.0 apps — not client-specific. Replaces `_Model_Core_Page::meta()`.
+
+**Model:** `Surfaces` (a configurable UI region) + `SurfaceElements` (ordered items: ~15
+typed attribute columns + one JSON `config` long-tail) — typed columns, NOT EAV. Behavior
+via an `Actions` catalog (string key + JSON payload; FE registry maps key→handler). i18n via
+`Messages` + per-client `MessageTranslations` (ICU). Theming via semantic `ThemeTokens` (no
+raw CSS in config). `Vocabularies`/`VocabularyTerms` for value→token/label sets. The entire
+cascade lives in ONE sparse `SurfaceOverrides` table (precedence base < client < persona <
+role, language overlay) replacing the ~40-table EAV settings cascade.
+
+**Decisions:** typed-columns-not-EAV; `TableViews` kept as the table query/data engine and
+only REFERENCED (Surface type=TABLE → `tableViewSlug`); ACL kept as-is and COMPOSED
+(`aclActionId`), never absorbed; no versioning/draft/publish; server-side cached resolver
+(`_Model_Core_Surface::resolve`, parameterized, zero-write-on-read). Two-tier gating —
+Tier-1 trivial declarative rules (frozen `all/any/none + {field,op,value}` grammar) evaluated
+client-side; Tier-2 business logic computed in PHP returning booleans (lives in
+`_Model_<Client>_*` overrides + interceptors). Config/logic boundary: **config describes,
+PHP decides.** M2M-safe delivery via opt-in `surface=<slug>` request option → response
+`meta.surface`, never `data`. Generic FE machinery destined for `@agilant/toga-blox`.
+
+**Rejected alternatives:** a generic EAV settings cascade (the old `*Settings` tables —
+proven near-empty in prod); raw-CSS-in-config (the old "Dummy Fields" anti-pattern).
+
+**CTO-mandated guardrails (CI-enforced, not intentions):** rule grammar is a frozen
+allowlist that throws on unknown ops, with a CI test asserting the op-set; defensive
+resolver with logged fallbacks; debug-bundle endpoint ships WITH the resolver; `c_longValue`
+on overrides with strict per-attribute casting; per-surface meta() cutover with a parity
+diff (do NOT delete meta() until every page is migrated); `BLANK_CLIENT_DATABASE` as a CI gate.
+
 ## Naming convention & autoloader
 
 Class names map **directly** to file paths: replace each `_` with `/`; the last segment
@@ -285,3 +323,4 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 
 ## Change history
 - 2026-06-11 — Documented lazy transaction gotcha in `_Database::register()` (rgirish)
+- 2026-06-25 — Added the Surface platform UI presentation/configuration layer (DB-driven UI config replacing `Page::meta()`, CTO-reviewed AGREE-WITH-ADJUSTMENTS) (jcardinal)

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

@@ -0,0 +1,104 @@
+---
+title: Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _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
+related:
+  - ../../dbchanges2/features/surface-layer-schema.md
+  - ../../api2/features/surface-meta-option.md
+  - acl-permission-chain.md
+---
+
+## What it is
+
+The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a
+cached resolver, `_Model_Core_Surface::resolve(&$api, string $slug)`, that merges base config +
+cascade overrides + ACL + messages + theme tokens into one flat, serializable bundle. It is the
+**replacement for `_Model_Core_Page::meta()`** and is shipped as a scripted-API method behind
+`GET /v2/surfaces/{slug}/meta`. Platform/shared — not client-specific. Schema:
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
+
+## The 9 models
+
+Core: `_Model_Core_{Surface,SurfaceElement,Action,Vocabulary,VocabularyTerm,Message}`.
+Client: `_Model_Client_{SurfaceOverride,MessageTranslation,ThemeToken}`. Each `extends _Model_True`
+with `const DATABASE`/`TABLE`, typed public-prop fields, and array FKs declaring
+`FIELDOPT_FOREIGNKEY_MODEL` (cross-DB FKs are soft — no SQL constraint). Modeled on
+`RecordField.php`/`TableView.php`.
+
+## How `resolve()` works
+
+Inputs come from `$api` (the same accessor `_Model_Client_TableView::meta` uses):
+`clientIdentifier`, `personaIds`, `roleIds`, `languageId`; `$slug` is the query arg.
+
+1. Load `Surface` by slug via ORM `->load()` — **parameterized** (fixes the old `LIKE '$slug'`
+   injection).
+2. One query: all `SurfaceElements` for `surfaceId`, ordered by `sortOrder`.
+3. One query: matching `SurfaceOverrides`; apply **most-specific-last** in a single in-memory pass
+   (`ORDER BY (roleId IS NULL) DESC, (personaId IS NULL) DESC`; language filtered to active or NULL).
+   Precedence **base < client < persona < role**, language an orthogonal overlay.
+4. **ACL composition, not absorption** — batch-resolve permissions via
+   `_Model_Client_AclActionPermission`; drop elements whose `aclActionId` isn't permitted (ACL stays
+   exactly as-is, see [acl-permission-chain](acl-permission-chain.md)).
+5. Batch-load (one integer-`IN` query each): `Messages`+`MessageTranslations` (referenced keys only),
+   `Vocabularies`+`VocabularyTerms`, `Actions`, client `ThemeTokens`.
+6. `type=TABLE` → emit `{tableViewSlug}` only; the FE keeps calling the existing `TableView::meta`
+   table pipeline (referenced, never duplicated).
+7. Assemble the flat bundle. **Zero INSERTs.**
+
+A `debug()` inspector returns the resolved bundle plus the raw cascade layers (shipped with the
+resolver, not "later").
+
+## Caching & invalidation
+
+- Disk cache keyed `surface:meta:{app}:{slug}:{client}:{sortedPersonaIds}:{sortedRoleIds}:{lang}`.
+- **Bust on write, never TTL-only.** `postPost/postPut/postPatch/postDelete` interceptors on all 9
+  models do a broad client-scoped bust; a write to a **Core** table must bust all clients' bundles
+  (or fold a Core-version stamp into the key).
+- **Keep the bust OUTSIDE the DB transaction** (the lazy-transaction write-drop rule).
+
+## Config vs logic boundary (the hard rule)
+
+**Config describes; PHP decides.** Two-tier gating:
+- **Tier 1** — trivial declarative gates (`{all|any|none:[{field,op,value}]}`, nestable) shipped as
+  JSON on the element and evaluated **client-side** against the loaded record. Grammar is a **frozen
+  allowlist** — a new op is an escalation to Tier 2, not a config change.
+- **Tier 2** — business logic (multi-stage approvals, "reviewer assigned", anything touching
+  `Approvals`) is **computed in PHP** and returned as a resolved boolean. It lives in
+  `_Model_<Client>_*` overrides + `Client_ApiPayloadInterceptor` hooks — the Surface layer does
+  **not** absorb business logic.
+
+## Gotchas
+
+- **`_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
+  basis for the typed-over-EAV design: in `Client_Compass` the whole EAV settings cascade (`Settings`
+  16-key registry + ~40 `*Settings` tables) is almost all 0 rows, while typed `TableViews`/
+  `TableViewFields`/`SectionRecordFields` ARE populated. **Do not delete `meta()`** until every page
+  is migrated — cut over per-surface with a parity diff (old bundle vs new bundle).
+- **The resolver must be defensive** — config writes bypass code review/CI, so missing/invalid config
+  falls back to sane defaults and never crashes a page. Strict per-`attribute` casting with logged
+  fallback on bad `SurfaceOverrides` data.
+- **Cross-DB reads are batched** (DB_CORE vs DB_CLIENT) and FKs are soft — tolerate dangling refs.
+
+## Change history
+- 2026-06-25 — Built the 9 models + `resolve()`/`debug()` as the cached, parameterized,
+  zero-write-on-read replacement for `_Model_Core_Page::meta()`; cache-bust interceptors on all 9
+  models (outside the transaction). meta() retained until per-page cutover with parity diff. (jcardinal)

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

@@ -5,6 +5,7 @@
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
+| [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, _underscore/Route.php |

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

@@ -0,0 +1,47 @@
+---
+title: Surface action-state via the surface=<slug> request option (M2M-safe)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Core/Surface.php
+related:
+  - ../../_underscore/features/surface-resolver.md
+---
+
+## What it is
+
+An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state
+(`isVisible`/`isEnabled`) to a GET response **under `meta.surface`, never `data`**. It is the
+M2M-safe delivery mechanism for the platform-wide Surface layer (see
+[surface-resolver](../../_underscore/features/surface-resolver.md)): the same core data API serves
+both the UI and machine-to-machine integrations, so presentation state must never leak into the
+business data that integrations consume.
+
+## How it works
+
+When `surface=<slug>` is present on a GET, after loading the record(s) the engine calls
+`_Model_Core_Surface::resolveRecordState($api, $slug, $record)` and attaches per-record
+`{isVisible, isEnabled}` action state under `meta.surface` (single-record and list shapes; a list is
+resolved in one batched pass, per row in `meta`). When the option is **absent** (all M2M/integration
+traffic), behavior is **byte-for-byte unchanged** — pure data, zero extra work. The path is
+**defensive**: it catches `Throwable` and omits `meta.surface` on error rather than failing the call.
+
+## Key rules
+
+- **Presentation state lives in `meta.surface`, never `data`.** Integrations get pure business data.
+- **The business rule is enforced at the action endpoint** (the source of truth that also protects
+  M2M — e.g. an integration approving a `fulfilled` order is rejected by the same rule). The surface
+  option merely **previews** that rule for the UI; it is a read-only preview, not a second copy of
+  the logic.
+- **One call, no extra round-trip** — the state pass rides the existing data fetch.
+
+## Change history
+- 2026-06-25 — Added the `surface=<slug>` opt-in option to the V2 engine; attaches per-record action
+  state under `meta.surface` (M2M-safe, defensive, absent = unchanged). (jcardinal)

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

@@ -3,4 +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/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

@@ -0,0 +1,90 @@
+---
+title: Surface Layer Schema (UI presentation/config tables)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql
+  - dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql
+  - dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.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
+related:
+  - ../../_underscore/features/surface-resolver.md
+---
+
+## What it is
+
+The persistent schema for the platform-wide **Surface** UI presentation/configuration layer
+(see the `_underscore` [surface-resolver](../../_underscore/features/surface-resolver.md) feature
+for the runtime). DB-driven UI config (labels, colors via tokens, visibility/enable, icons,
+tooltips, button bars, table quick-actions, status badges, modals) so UI changes need no
+front-end deploy and are editable by a future admin app over plain CRUD. **Platform/shared — not
+client-specific** (Compass is only the first seed/test tenant). It replaces the legacy
+`_Model_Core_Page::meta()` EAV settings cascade (the old ~40 `*Settings` tables — almost all empty
+in prod).
+
+## The 9 tables — Core (structural) vs Client (per-tenant deltas)
+
+Structural definitions live in **Core** (platform-shared, mirrors `Records`/`RecordFields`);
+per-tenant deltas live in **Client** (mirrors `TableViews`/ACL/`ItemTranslations`).
+
+| Table | DB | Purpose |
+|---|---|---|
+| `Surfaces` | Core | A configurable UI region (`type` ENUM TABLE/SECTION/BUTTON_BAR/ROW_ACTIONS/TAB_STRIP/FILTER_SET/MODAL/DRAWER) |
+| `SurfaceElements` | Core | Ordered items: ~15 typed attr columns + one JSON `config` long-tail + `visibilityRule`/`enabledRule` JSON |
+| `Actions` | Core | Behavior action catalog (FE registry keys + JSON payload) |
+| `Vocabularies` | Core | A value-set (status/stage/priority/type/channel) per record |
+| `VocabularyTerms` | Core | value → token/label/order |
+| `Messages` | Core | i18n key catalog + ICU default value |
+| `SurfaceOverrides` | Client | THE single sparse cascade table (+`c_longValue mediumtext`) replacing ~40 EAV tables |
+| `MessageTranslations` | Client | per-language overlay (sidecar pattern) + `c_longValue` |
+| `ThemeTokens` | Client | per-tenant semantic token → value (the only place a hex/icon name lives) |
+
+`SurfaceOverrides` carries the entire cascade in one sparse table: scope columns
+`personaId`/`roleId`/`languageId` (NULL = not scoped on that axis), an `attribute` ENUM, and
+`value varchar(255)` + `c_longValue mediumtext`. Precedence **base < client < persona < role**
+with language as an orthogonal overlay; the resolver applies it most-specific-last in one pass.
+
+## Migration files (typed columns, not EAV)
+
+CREATE order is FK-safe (`Messages → Actions → Vocabularies → VocabularyTerms → Surfaces →
+SurfaceElements`). Core migrations run first; Client after. The session built/seeded the
+**SalesOrders + login** vertical (not Tickets) as the review proof:
+
+- `Core/2026-06-25a - SurfaceCoreTables.sql` — the 6 Core tables.
+- `Core/2026-06-25b - SurfaceRecordsAndFields.sql` — `Core.Records`+`RecordFields` for all 9 tables (reserved id block **2300–2399**; `recordId` via `model=` subselect).
+- `Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql` — Core seed + the `RecordScripts` resolve row.
+- `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.
+
+## Gotchas
+
+- **Cross-DB FKs (Core↔Client) are SOFT** — the ORM declares `FIELDOPT_FOREIGNKEY_MODEL` but **no
+  SQL constraint** exists (e.g. `Surfaces.tableViewId`, `SurfaceOverrides.surfaceId`,
+  `MessageTranslations.messageId`). This keeps Core/Client migration ordering safe and lets the
+  resolver tolerate dangling refs. Never add a real cross-DB constraint.
+- **`BLANK_CLIENT_DATABASE.sql` MUST append** the 3 new Client tables + the `Languages` `en` seed,
+  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).
+- **`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.
+- **Reserved id block 2300–2399** for the Surface `Records`/`RecordFields` rows (Core max was 331);
+  use `model=` subselects for `recordId`, never hardcoded ids.
+- **CLIENT-aclDatabase records** (`SurfaceOverrides`, `MessageTranslations`, `ThemeTokens`) need the
+  full 4-step ACL chain + field permissions in **each** client DB; resolve `roleId` by subselect.
+
+## Change history
+- 2026-06-25 — Initial schema for the Surface layer: 6 Core + 3 Client tables, `Records`/`RecordFields`
+  (ids 2300–2399), SalesOrders+login seed, ACL chain, and `BLANK_CLIENT_DATABASE` append. Typed
+  columns chosen over EAV (the old `*Settings` cascade was empirically near-empty in prod). (jcardinal)

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

@@ -8,3 +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/{slug}/meta` instead of statically-imported JSON f | 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/featureFlag.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 |

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

@@ -0,0 +1,71 @@
+---
+title: Surface Frontend (DB-driven UI consumption, src/surface/)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - 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/featureFlag.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
+related:
+  - ../../_underscore/features/surface-resolver.md
+  - meta-driven-table-data.md
+---
+
+## What it is
+
+The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from
+`GET /v2/surfaces/{slug}/meta` instead of statically-imported JSON field bundles. Lives in
+`src/surface/` for now with a `TODO(blox)` to extract the generic machinery into `@agilant/toga-blox`
+so all 2.0 apps inherit it. Backend: [surface-resolver](../../_underscore/features/surface-resolver.md).
+
+## How it works
+
+- **`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.
+- **`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
+  the loaded record. A new op is an escalation to a backend Tier-2 capability method, never a grammar
+  change.
+- **`actionRegistry`** — string action key → existing app handler (the proven `MODAL_RENDERERS`
+  pattern). The DB ships keys + payloads; the app supplies the actual handlers.
+- **theme/message resolvers** (`resolve.ts`) — token → CSS and ICU message rendering.
+- **`SurfaceActionBar`/`SurfaceActions` + `SurfaceSection`** — generic renderers.
+
+## What's wired (review proof)
+
+Login + sales-orders list + the sales-order modal, all behind the **`SURFACE_ENABLED`** flag (env
+`VITE_SURFACE_ENABLED`, **default OFF**). The SalesOrder action bar reproduces
+`orderViewFields.json` approve/deny/approvalWorkflow/viewLog/editOrder by delegating to the existing
+`onActionClick`/`onOpenLog` handlers. The table stays 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.
+
+## Gotchas
+
+- **Default OFF.** Nothing renders through the Surface path unless `VITE_SURFACE_ENABLED` is set —
+  the existing JSON-bundle path remains live until per-surface cutover.
+- **Tier-1 only on the client.** Business-logic gates (Tier-2) arrive as resolved booleans from the
+  backend (`meta.surface`); never re-encode business rules in the FE evaluator.
+- **`tsc` not yet run** this session (the private `@agilant/toga-blox` registry needs npm creds);
+  treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
+
+## Change history
+- 2026-06-25 — Built `src/surface/` (fetch hook, frozen Tier-1 rule evaluator, action registry, theme/
+  message resolvers, action-bar + section renderers); wired login + SalesOrders list + SO modal behind
+  the OFF-by-default `SURFACE_ENABLED` flag. Generic machinery destined for toga-blox. (jcardinal)

package/knowledge/INDEX.md

@@ -12,13 +12,14 @@ _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) — 11 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) — 4 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 15 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 16 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 15 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **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)
+- **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)
 - **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)
@@ -27,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **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) — 6 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 7 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

package/knowledge/clients/true/profile.md

@@ -3,6 +3,7 @@ title: "TOGA Technology"
 framework: "2.0"
 apps:
   - _underscore
+  - tools
 project: _Underscore
 client: true
 type: profile
@@ -24,3 +25,6 @@ by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` mode
 - **Client DB:** `Client_True`
 - **Client identifier:** `True`
 - **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)
+
+The new **Tools** app (1.0; repo `tools`) reads the `Client_True` DB **read-only** to gate its
+internal tooling by staff persona (see `1.0/apps/tools/`).

package/knowledge/registry.json

@@ -182,5 +182,14 @@
     "framework": "2.0",
     "role": "app",
     "dependsOn": []
+  },
+  {
+    "repo": "tools",
+    "project": "Tools",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
   }
 ]

package/package.json

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