toga-ai 1.0.320 → 1.0.322

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

@@ -7,6 +7,6 @@
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |
-| [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | A Tools (1.0) admin UI to browse/fix the Talos knowledge-base documents and manage the transcript-cleanup vocabulary — without a deploy. | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf |
+| [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | A Tools (1.0) admin UI to browse/fix the Talos knowledge-base documents and manage the transcript-cleanup vocabulary — without a deploy. | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/get.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/pg.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf, tools/.platform/hooks/prebuild/01-install-php-pgsql.sh, tools/.platform/hooks/postdeploy/01-restart-php.sh |
 | [Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus a client-side estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/mvc/talos/onboarding/get.php, tools/mvc/talos/onboarding/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/benchmarks/get.php, tools/mvc/talos/factors/get.php, tools/mvc/talos/factors/post.php, tools/assets/css/style.css |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json |

package/knowledge/1.0/apps/tools/features/talos-kb-documents-admin.md

@@ -11,16 +11,20 @@ owners: [jcardinal]
 files:
   - tools/mvc/talos/kb-documents/get.php
   - tools/mvc/talos/kb-documents/post.php
+  - tools/mvc/talos/knowledge-bases/get.php
   - tools/mvc/talos/knowledge-bases/post.php
   - tools/mvc/talos/vocabulary/get.php
   - tools/mvc/talos/vocabulary/post.php
   - tools/_/app/talos/s3.php
   - tools/_/app/talos/bedrock.php
+  - tools/_/app/pg.php
   - tools/_/app/worker.php
   - tools/_/app/nav.php
   - tools/config.production.ini
   - tools/config.alpha.ini
   - tools/.platform/httpd/conf.d/timeouts.conf
+  - tools/.platform/hooks/prebuild/01-install-php-pgsql.sh
+  - tools/.platform/hooks/postdeploy/01-restart-php.sh
 related:
   - ./mvc-data-access-patterns.md
   - ./persona-gated-navigation.md
@@ -34,7 +38,8 @@ A Tools (1.0) admin UI to browse/fix the Talos knowledge-base documents and mana
 transcript-cleanup vocabulary — without a deploy. It is the human front-end to the worker2
 [Talos Transcript Ingestion](../../../2.0/apps/worker2/features/talos-transcript-ingestion.md)
 pipeline. A new **"Talos Knowledge Base"** nav group (personas *Development Team* / *TOGa
-Technology*) exposes two pages.
+Technology*) exposes the pages below. **"Knowledge Bases"** is registered as the **first**
+action in the `talos-kb` nav group (above "KB Documents") and inherits the group's personas.
 
 ## Pages
 
@@ -76,12 +81,32 @@ so they displayed **double-encoded** (e.g. "Grand & Toy"). `vocabulary/post.
 `html_entity_decode()`s values on save so the DB stores **raw** text; `vocabulary/get.php`
 already escapes once at display. Do not re-add encoding on save.
 
+### `/talos/knowledge-bases` — KB list + inline rename
+
+The list/admin page (`get.php`) for Talos knowledge bases. Unlike KB Documents (whose KB
+list is derived from **live S3 folders**), this page's list comes from the
+**`Team.KnowledgeBases` MySQL table** (via `db_team`) — the two are distinct sources of
+truth. Columns: Slug, Name, Bedrock KB ID, Created On (`dtCreated`, converted UTC→
+America/Chicago). **Name is the only editable field** and is edited **in place** (Edit→Save);
+there is **no delete option**. Server strings are escaped before `innerHTML` (XSS guard).
+
+Rename posts `action=rename` → `UPDATE Team.KnowledgeBases SET name WHERE slug` (`db_team`),
+preceded by an **existence SELECT** so a stale slug reports **"not found"** instead of a
+false success.
+
 ### `POST /talos/knowledge-bases` — create a new KB (synchronous provisioning)
 
 Admin action that provisions a brand-new Talos knowledge base end to end in **one
 synchronous request**: creates the S3 prefix, creates the Bedrock KB and **waits for it to
 reach `ACTIVE`**, creates the Bedrock data source (`MANAGED_KNOWLEDGE_BASE_CONNECTOR`), and
-inserts 2 MySQL (`Team.KnowledgeBases`, `Team.VectorIndexes`) + 2 Postgres rows. This flow
+inserts rows across **5 systems with no shared transaction**: `Team.KnowledgeBases` (`db_team`,
+Team MySQL cluster), `Client_True.VectorIndexes` (`db_true`, **Client MySQL cluster** — not the
+Team cluster), and 2 Talos **Postgres** rows (`public.knowledge_bases` +
+`public.assistant_knowledge_bases`, the latter linking a hard-coded assistant id). Step order:
+validate name (≤255) + derive slug via **`App_Talos_S3::slugify()`** (kebab-case, `iconv` ASCII
+translit; rejects a duplicate slug — `slug` is UNIQUE); create 3 S3 folder markers
+`development-team/{slug}/{approved,archive,upload}/` via **`App_Talos_S3::putFolderMarker()`**;
+create the Bedrock KB and wait for `ACTIVE`; create the data source; then the DB inserts. This flow
 **stays synchronous by design** — moving it to worker2/SQS async was explicitly rejected;
 the fix path is to raise timeouts, never to background the work.
 
@@ -115,6 +140,13 @@ orphaned KB).
   the SDK default chain — because `App_Talos_S3` only ever talks to **togaiq**, so it needs the
   togaiq-account key (the tools `[aws]` key is the toga-private key, which can cross-account *read*
   togaiq but not *write* it).
+- **`App_Pg`** (`_/app/pg.php`) — a **tools-only** minimal PDO `pgsql` wrapper for the Talos
+  Postgres DB (host `writer.talos.database.togahub.com:5432`, db `tenant_true`, user
+  `talosadmin`). Deliberately **not** added to the shared 1.0 `library` (the App_ framework has
+  no Postgres support). The password is **read from the existing `[database_team]` config
+  section** (shared with the MySQL DBs) — **no new secret introduced**. `execute()` uses real
+  PDO prepared statements (bound params). If the `pdo_pgsql` extension is missing it returns
+  `ok=false` with a generic message (detail goes only to `error_log`, never to the client).
 - **`App_Worker::enqueue()`** (`_/app/worker.php`) — inserts a `Core.WorkerJobs` row and sends
   the `{"workerJobId": id}` SQS message, so a 1.0 app can enqueue worker2 jobs. Requires the
   `[worker]` (`queue_url`/`queue_region`) and `[aws]` (main-account key for SQS `SendMessage`)
@@ -130,6 +162,12 @@ orphaned KB).
   - **`[aws]`** — main-account key for SQS `SendMessage` (toga-private key; cross-account reads
     togaiq but cannot write it — that's why `[talos]` exists).
   - `[database_toga2core]` — writable 2.0 Core (already present).
+- **`pdo_pgsql` PHP extension** must be installed on the tools Elastic Beanstalk environment
+  (the create flow writes to Talos Postgres via `App_Pg`). Provided by two `.platform` hooks
+  (mirroring worker2's): `hooks/prebuild/01-install-php-pgsql.sh` (installs `php-pgsql`,
+  idempotent, **fails the deploy loudly** if `pgsql` won't load) and
+  `hooks/postdeploy/01-restart-php.sh` (restarts php-fpm/httpd). **EB runs `.platform/hooks`
+  regardless of the git exec bit** — worker2's equivalents are committed `100644`.
 - Apply the dbchanges2 `Team/2026-06-30a..e` + `Core/2026-06-30a` migrations in order.
 - Verify the Bedrock KB region / data-source name against the live account (TODOs in code).
 
@@ -171,12 +209,37 @@ orphaned KB).
   allows same-name KBs with new ids). After a failed create: either
   `aws bedrock-agent delete-knowledge-base` the orphan and re-run clean, or finish the DB rows
   manually.
+- **Newest KBs use Bedrock's fully-MANAGED type** (`knowledgeBaseConfiguration.type=MANAGED`,
+  `managedKnowledgeBaseConfiguration.embeddingModelType=MANAGED`) — **AWS owns the vector store**,
+  so there is **no S3 Vectors index, no `embeddingModelArn`, and no `storageConfiguration`** to
+  build. Config was replicated from the existing `development-team-craftex` KB. Account
+  `654654170868`, region `us-east-1`, execution role `…ForKnowledgeBase_ofl5a`.
+- **KB-list source differs per page.** The new `/talos/knowledge-bases` page lists from
+  `Team.KnowledgeBases` (`db_team`); `/talos/kb-documents` lists from live S3 folders. Don't
+  assume one reflects the other.
+- **Schemas.** `Team.KnowledgeBases`: `id, uuid`(UNIQUE)`, slug`(UNIQUE)`, name, isGeneral,
+  bedrockKbId`(nullable)`, isActive, dtCreated`(datetime default `CURRENT_TIMESTAMP`)`, dtUpdated`.
+  `Client_True.VectorIndexes` (Client cluster): `id, uuid`(UNIQUE)`, name, docSlug`(UNIQUE,
+  nullable)`, sectionSlug, chunkSlug, description` — create sets `docSlug=sectionSlug=chunkSlug=
+  bedrockKbId`.
+- **Not yet run end-to-end in production.** The whole feature is code-complete, `php -l` clean,
+  and reviewed, but the create flow has not been exercised in prod pending the `pdo_pgsql`
+  deploy plus network/IAM prerequisites (the developer is handling those).
 - No new secret literals introduced; credentials live in the config sections above (documented by
   section/account, never by value). AWS account id `654654170868`, bucket `togaiq`, and the KB
   execution-role ARN are non-secret resource identifiers.
 
 ## Change history
 
+- 2026-07-13 — Added the **`/talos/knowledge-bases` list + inline-rename page** (`get.php`;
+  lists from `Team.KnowledgeBases`, rename-only, no delete, existence-check before update),
+  registered first in the `talos-kb` nav group. Added the **`App_Pg`** tools-only PDO `pgsql`
+  wrapper (password reused from `[database_team]`; not added to shared library) and the
+  **`.platform` pdo_pgsql install/restart hooks**. Documented the create flow's 5-system fan-out
+  (incl. `Client_True.VectorIndexes` on the **Client** cluster + 2 Postgres rows), the
+  `slugify()`/`putFolderMarker()` helpers, the fully-**MANAGED** Bedrock KB type (AWS-owned vector
+  store, no storageConfiguration), and the two DB schemas. Feature is code-complete/reviewed but
+  not yet run end-to-end in prod. (jcardinal)
 - 2026-07-13 — Added the **synchronous KB-create flow** (`POST /talos/knowledge-bases`) via new
   `App_Talos_Bedrock` helper. Fixed the **504 at 60s**: EB AL2023 PHP = Apache→php-fpm over
   `mod_proxy_fcgi` with a 60s default proxy read timeout; added

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

@@ -2,6 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |

package/knowledge/2.0/apps/_underscore/architecture/surface-authoring-proposal.md

@@ -0,0 +1,67 @@
+---
+title: Proposed — git-sourced base+overlay JSON authoring for the Surface layer
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: architecture
+status: draft
+updated: 2026-07-13
+owners: [apeterson]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/SurfaceOverride.php
+related:
+  - ../features/surface-resolver.md
+---
+
+## Summary
+
+A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model
+move off hand-authored SQL against the `SurfaceOverrides` EAV table onto **git-sourced JSON**: a full
+neutral `_base/<surface>.json` per surface plus partial per-client overlay files holding only diffs,
+merged by the resolver at read time. The runtime resolver is kept for the dynamic parts (per-record
+Tier-2 evaluation + ACL element-drop). This doc records the motivation, the design, and interim
+guardrails so the lead dev can decide.
+
+**Critical rules:** This is a **proposal, status: draft — nothing here is implemented.** Do not treat
+any of it as the current system. The live authoring path is still hand-written SQL against
+`SurfaceOverrides`; if you stay on it, apply the interim guardrails below (unique index, strict SQL
+mode, autocommit on, idempotent migrations) or you will hit the silent EAV failure modes.
+
+## Problem
+
+Surface config is authored as hand-written SQL against the `SurfaceOverrides` EAV table. This has:
+- **No git diff / review / rollback** — config changes bypass code review and CI.
+- **No team-merge story** — concurrent work on a shared surface collides with no merge tooling.
+- **Silent DB failure modes** — ENUM coercion of unknown values to `''` (non-strict mode), a missing
+  unique constraint letting duplicate override rows pile up, and autocommit-off swallowing writes.
+
+Cost signal: 2 of ~17 surfaces took ~5 days.
+
+## Recommendation
+
+**Source of truth = git.** For each surface author a full neutral `_base/<surface>.json`, plus partial
+per-client overlay files holding **only diffs**, merged by the resolver at read time. Keep the
+resolver for the dynamic parts it must still compute (per-record Tier-2 evaluation + ACL
+element-drop — see [surface-resolver](../features/surface-resolver.md)).
+
+**Framing: "source of truth = git; read substrate = a choice."** Three read substrates, in order of
+preference:
+1. Read the JSON files directly at read time.
+2. Seed the JSON documents into a DB column at deploy (git still authors; DB is a materialized cache).
+3. (Avoid) DB-as-master authored by hand — the status quo.
+
+## Optional future — bounded live toggles
+
+An admin UI (a screen + a validating API endpoint + an `admin_flags` DB table) that writes a
+**bounded, whitelisted** set of per-client feature toggles, merged at **highest precedence**. This
+gives live no-deploy toggles without undermining git-as-truth, because the whitelist bounds what can
+be changed outside git.
+
+## Interim guardrails (if staying on SQL/EAV)
+
+- Unique index on `SurfaceOverrides(surfaceElementId, attribute, roleId, personaId, languageId)`.
+- Strict SQL mode (so unknown ENUM values error instead of coercing to `''`).
+- Autocommit on.
+- Idempotent, re-runnable migrations.

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-01
+updated: 2026-07-13
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -137,6 +137,70 @@ breaks logic.
   `_Model_<Client>_*` overrides + `Client_ApiPayloadInterceptor` hooks — the Surface layer does
   **not** absorb business logic.
 
+## Per-client override of the Tier-1 gating RULES (not just static flags)
+
+Originally only static flags (`isVisible`/`isEnabled`) and `config` were per-client overridable
+via `SurfaceOverrides`; the **Tier-1 gating rules** (`visibilityRule`/`enabledRule`) were frozen on
+the Core element. That meant two-stage-approval clients could not be expressed as data — they needed
+per-client PHP. Two new override attributes make the declarative rules per-client overridable so the
+two-stage behavior is **pure data**:
+
+- `_Model_Client_SurfaceOverride` now declares `ATTRIBUTE__VISIBILITY_RULE` and
+  `ATTRIBUTE__ENABLED_RULE` constants.
+- In `Surface.php` `_resolveElement`, the resolver decodes and applies both attributes: the locals
+  are seeded from the Core element's own `visibilityRule`/`enabledRule`, then overridden by any client
+  override row. `_castOverride` decodes them as JSON alongside `CONFIG`.
+
+> **⚠ LOCAL only (as of 2026-07-13).** The `_underscore` code change **and** the ENUM migration below
+> must ship together to beta/prod on promotion. php-reviewer pass + a PHPUnit regression test for the
+> rule-override path are still outstanding.
+
+**Mandatory ENUM migration (ships with the code).** Each client schema's
+`SurfaceOverrides.attribute` ENUM must be widened *before* any rule-override row is inserted:
+`ALTER TABLE Client_*.SurfaceOverrides MODIFY attribute ENUM(...,'VISIBILITY_RULE','ENABLED_RULE') NOT NULL`
+across all 32 `Client_*` schemas. In **non-strict SQL mode** an insert of an unknown ENUM value
+**silently coerces to `''`** — which makes the resolver ignore the rows and `NOT EXISTS` guards never
+match (duplicate rows pile up). Widen the ENUM first, always.
+
+### Override semantics: REPLACE, not deep-merge
+A `CONFIG` (and now `VISIBILITY_RULE`/`ENABLED_RULE`) override **replaces the whole decoded object**
+— it does **not** deep-merge (`Surface.php` ~line 818). So a `CONFIG` override value must carry the
+**full** config (e.g. `role` + `filterKey` + `additionalData`), not just the changed key.
+
+### Two separate gating mechanisms on the sales-order listing (do not conflate)
+- The **Approvals FILTER** on the sales-order listing is driven by `config.additionalData._status`.
+- The **per-button record actions** are gated by `visibilityRule`/`enabledRule`.
+These are separate mechanisms on separate surfaces; a filter change is a `CONFIG` override, a
+button-gating change is a rule override.
+
+## Core re-baselined to a neutral default + per-client diffs (decision, 2026-07-13)
+
+Core was effectively "Client Zero = Compass", not a neutral default, so every client inherited
+Compass's shape. Core was re-baselined as a true shared default so clients store **only diffs**:
+
+1. The approvals gate is governed by the **`navigation-approvals` ACL grant**, not per-tenant
+   `IS_VISIBLE` overrides.
+2. Default approvals filter = `pendingApproval` only (single-stage).
+3. No Tier-2 `config.tier2` caveat baked into Core.
+4. Edit-in-Commerce only for Compass / CompassCanada.
+5. Columns button hidden by default.
+
+Per-client diffs layered on top:
+- **Quad** — Approve + Deny only; filter narrowed to `pendingApproval`; filter button visible.
+- **Compass USA / Compass Canada** — two-stage approvals: record-action `visibilityRule`/`enabledRule`
+  = `in [pendingApproval, pendingInitialApproval]`. **Compass Canada** additionally gets a `CONFIG`
+  override on the approvals filter button (surface `sales-order-listing-actions`) to add
+  `pendingInitialApproval`.
+
+> ⚠ **Regression left open:** the Compass / CompassCanada **non-rule** overrides (Edit-in-Commerce
+> flags, role-8 Manager hides) were **wiped during the rebuilds and not re-added**. The two-stage rule
+> overrides are also LOCAL only (see above).
+
+### Operational gotcha — raw SQL bypasses the cache-bust
+Raw SQL against the surface tables bypasses the model-layer cache-bust, so the on-disk bundle cache
+at `~/toga/cache/surface_meta/*.json` **must be cleared manually** after any raw-SQL surface edit.
+(Cache confusion earlier was a local-setup artifact, not an inherent design issue.)
+
 ## 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
@@ -234,6 +298,17 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-13 — Made the Tier-1 gating RULES per-client overridable: added
+  `ATTRIBUTE__VISIBILITY_RULE`/`ATTRIBUTE__ENABLED_RULE` to `_Model_Client_SurfaceOverride`;
+  `_resolveElement` seeds locals from the Core element's rules then applies overrides;
+  `_castOverride` decodes them as JSON — so two-stage approvals are pure data, not per-client PHP.
+  Requires widening `Client_*.SurfaceOverrides.attribute` ENUM (32 schemas) first (non-strict mode
+  silently coerces unknown ENUM → `''`). Documented override REPLACE-not-merge semantics, the
+  filter (`config.additionalData._status`) vs button-rule split, the raw-SQL cache-bust bypass
+  (`~/toga/cache/surface_meta/*.json`), and the Core neutral-default re-baseline (ACL-gated
+  approvals, single-stage default, per-client diffs: Quad = Approve+Deny, Compass/CC = two-stage).
+  ⚠ Code + ENUM migration are LOCAL only; non-rule Compass/CC overrides wiped in rebuild not yet
+  re-added; php-reviewer + regression test outstanding. (apeterson)
 - 2026-07-01 — Clarified vocabulary/label per-client relabeling (new section): Vocabulary `slug`
   and VocabularyTerm `value` are stable internal ids never shown to users; the displayed label
   always resolves from `Core.Messages`; clients relabel via a `SurfaceOverrides` `LABEL_MESSAGE`

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

@@ -8,5 +8,5 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.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/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.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/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-13
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -27,6 +27,7 @@ files:
   - 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/SurfaceRowActions.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx
   - toga25-supply/src/pages/Items/ItemsPage.tsx
   - toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx
@@ -245,10 +246,24 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   (the path form 404s EV-6).
 - **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.
+- **A React portal overlay's click bubbles through the COMPONENT tree, not the DOM tree.** The
+  SalesOrders row-actions menu (`SurfaceRowActions.tsx`) renders its dismiss overlay via a portal;
+  an outside-click on that fixed overlay propagated up the React component tree to the row's
+  `handleRowClick` and **opened the record modal**. Fix: call `e.stopPropagation()` (plus close) in
+  the overlay's `onClick`. Portal DOM position does not stop React synthetic-event bubbling.
+- **The sticky row-actions column must be gated on the active filter.** In `SalesOrders.tsx` the
+  `actionColumns` array is only included when `activeFilterKey === APPROVALS_FILTER_KEY`
+  (`"approvals"`); otherwise the row-actions column showed unconditionally.
 - **`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-07-13 — Fixed two SalesOrders row-actions bugs: (1) the portal dismiss overlay in
+  `SurfaceRowActions.tsx` propagated an outside-click up the React component tree to the row handler
+  and opened the record modal — added `e.stopPropagation()` (+ close) on the overlay `onClick`;
+  (2) gated the sticky `actionColumns` array in `SalesOrders.tsx` on
+  `activeFilterKey === APPROVALS_FILTER_KEY` so the row-actions column only shows under the Approvals
+  filter. (apeterson)
 - 2026-06-30 — Follow-up: fixed the GROUPED meta fetch returning `{}` (every migrated-client
   SalesOrders section had vanished). The meta-group envelope double-nests the slug-keyed `surfaces`
   map under an outer ROUTE-keyed `surfaces` slot; the old `extractGroup` grabbed the first (outer,

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 28 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 29 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 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)

package/package.json

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