toga-ai 1.0.807 → 1.0.808

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-14
 owners: ["jcardinal", "mhammontree", "tcox", "bala", "apeterson", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -46,6 +46,14 @@ AclRecordPermissions   →  AclLogicGroups   →  AclLogicGroupExpressions  →
    `sqlExpression` (TEXT). Unique on `(recordId, slug)`. The conventional "always allow" row is
    `slug = 'all'`, `sqlExpression = '1'`.
 
+> **A half-built chain fails with a NAMED message — search for it before guessing.** `V2.php`
+> tracks two flags as it walks a permission, `$aclLogicGroupsDefined` and
+> `$aclLogicGroupExpressionsDefined` (set ~L3930 and ~L5614). When the first is false the request is
+> rejected with the exact message **`No ACL Logic Groups defined for ACL Record Permissions`**
+> (~L4437 / ~L5845); a missing expression binding fails on the second flag the same way. So an
+> `AclRecordPermissions` row with no `AclLogicGroups` row returns UNAUTHORIZED carrying that string
+> — which means the **chain**, not the grant, is the problem.
+
 **Field visibility — `AclFieldPermissions`.** Record-level access alone does **not** expose
 fields. Each field needs a row: `recordFieldId`, `roleId`, `isWritable` (0 = read-only, 1 =
 writable). Without it the field is rejected on write **and** is unreadable:
@@ -314,6 +322,13 @@ Measured 2026-09-08: production `Core.Records` holds **328 rows, max id 358**; d
 > divergence recorded as an open question in the
 > [non-prod drift doc](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md), and it is why
 > the hardcoded-literal rule above is scoped to **established** rows only.)
+>
+> **One client/pair can match completely, and that still is not portability.** Checked 2026-09-10
+> for Compass: `Core.Records` ids, every `Core.RecordFields` id for the nine records in an ACL grant
+> script, plus `Client_Compass.AclRecordExpressions` and `CustomRecordFields` ids, were **identical
+> between production and client-sandbox**, so the prod-written script ran unchanged on
+> client-sandbox. Treat that as a **per-client, per-environment-pair** measurement you re-take each
+> time — never as licence to skip resolving ids to names.
 
 **3. In PRODUCTION you cannot join `Core` and `Client_<Tenant>` in one statement — so the diff query
 that works in sandbox breaks in prod.** Prod splits them across `prod-core` and `prod-client`; both
@@ -686,6 +701,31 @@ consequence, and the reason the "mirror a sibling field" practice works: **grant
 `Base` also grants it to the worker.** Conversely, when auditing what an end customer can reach,
 remember the reverse — a grant added "for the worker" on `Base` reaches customers too.
 
+### ⚠ That union is `Apis_Roles` and NOTHING else — and `appId` does not scope an API key
+
+Two facts verified in `api2/Component/Api/V2/V2.php` on 2026-09-10, both of which decide how you
+scope a machine consumer:
+
+1. **Roles are ASSIGNED, not merged (~L1639).** On API-key auth, `_Model_Client_Apis_Role` is
+   searched for the `apiId` and the result is assigned straight to `$id->client->roles` — the
+   `array_merge($id->client->roles, $clientRoles)` line immediately above it is **commented out**.
+   Core roles are then derived from those client roles' non-NULL `coreRoleId` values, so a new role
+   with `coreRoleId` NULL is perfectly fine for records whose `Core.Records.aclDatabase` is
+   `CLIENT`. A key's power is exactly its `Apis_Roles` rows.
+2. **`appId` scoping is void for an API key (~L1518 / L1961 / L3201).** `$this->app` is only set
+   when the JWT carries an app uuid, i.e. the domain/user login flow. API-key auth never sets it,
+   and every permission filter starts `(!isset($this->app) || is_null($perm->appId) || …)` — so
+   **every `appId`-scoped `AclRecordPermissions` row applies to an API key**. A grant deliberately
+   narrowed to one app (e.g. `appId = 5`, TOGa Commerce) is fully reachable by any key holding that
+   role.
+
+> **Consequence: the only way to limit a machine consumer is to give it its OWN role.** Wiring
+> several `Apis` rows to the same shared roles means the key identifies the caller but constrains
+> nothing. Worked example (first per-key role, Compass 2026-09-10):
+> [Giving a Compass API consumer its own scoped key](../../../../clients/compass-usa/workflows/granting-api-access.md),
+> and the auth/token mechanics in
+> [API-Key Authentication](../../api2/features/api-key-authentication-and-scoping.md).
+
 ## Client-DB grant migrations are re-runnable NO-OPs, and that is the design
 
 A `NOT EXISTS`-guarded `AclFieldPermissions` insert that finds its grants already present inserts
@@ -715,6 +755,16 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-09-14 — Added the **API-key scoping** rules, from building the first per-key Compass API role.
+  Three durable points, all verified in `V2.php`: a half-built chain fails with the exact message
+  **`No ACL Logic Groups defined for ACL Record Permissions`** (flags `$aclLogicGroupsDefined` /
+  `$aclLogicGroupExpressionsDefined`, ~L3930/L4437/L5614/L5845); an API key's roles are **assigned**
+  from `Apis_Roles` and merge with nothing (~L1639, the `array_merge` is commented out), with core
+  roles derived from `coreRoleId`; and **`appId` does not scope an API key** because `$this->app` is
+  only set on the domain/user login flow (~L1518/L1961), so every `appId`-scoped grant applies — the
+  only real lever is a dedicated role per key. Also recorded that Compass's `Core.Records` /
+  `RecordFields` / `AclRecordExpressions` / `CustomRecordFields` ids matched prod and client-sandbox
+  exactly, as a per-client measurement and not portability. No code changed. (bala)
 - 2026-09-08 — Added the **cross-environment ACL comparison** rules, from a read-only Adyen
   "works in sandbox, not in prod" investigation. Three durable points: **pin the environment from
   the JWT first** (a shared API domain resolves its tenant from the token, so `api.beta.togahub.com`

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

@@ -3,6 +3,7 @@
 | Doc | Summary |
 |-----|---------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. |
+| [API-Key Authentication (/v2/auth/api) and what a key can actually reach](features/api-key-authentication-and-scoping.md) | A machine caller authenticates with `POST /v2/auth/api` using a `Client_<Client>.Apis` row and gets a bearer token. |
 | [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli |
 | [cXML ShipNotice Gateway (ASN ingestion, carrier resolution, per-client provisioning)](features/cxml-shipnotice-gateway.md) | `_Component_Api_Cxml` accepts a supplier `ShipNoticeRequest` and translates it into a `POST /v2/advance-shipping-notices` on the V2 JSON engine. |

package/knowledge/2.0/apps/api2/features/api-key-authentication-and-scoping.md

@@ -0,0 +1,113 @@
+---
+title: API-Key Authentication (/v2/auth/api) and what a key can actually reach
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-09-14
+owners: ["bala"]
+files:
+  - api2/Component/Api/V2/V2.php
+related:
+  - ../architecture.md
+  - ./request-logging.md
+  - ../../_underscore/features/acl-permission-chain.md
+  - ../../../../clients/compass-usa/workflows/granting-api-access.md
+---
+
+## Summary
+
+A machine caller authenticates with `POST /v2/auth/api` using a `Client_<Client>.Apis` row and gets
+a bearer token. **The key's power is exactly the union of its `Apis_Roles` rows and nothing else.**
+Two consequences that surprise people: roles are **assigned, not merged**, so an API key never picks
+up any other role; and `appId` scoping on an ACL grant **does not constrain an API key at all**,
+because API-key auth never sets `$this->app`. If you want one consumer limited to a few reads, the
+only working lever is giving that key **its own role** (see
+[granting Compass API access](../../../../clients/compass-usa/workflows/granting-api-access.md) for
+a worked example).
+
+## The authentication call
+
+- **Route:** `POST {base}/auth/api`. The public caller base is `https://api.togahub.com/v2`.
+- **`transactionId` goes in the QUERY STRING**, not the body, and must be globally unique
+  (reuse → `EV-5`).
+- **Body is exactly three fields:**
+  - `client` — the `Core.Clients` uuid
+  - `api` — the `Client_<Client>.Apis` row uuid
+  - `secret` — that row's secret
+- **Response:** `data.tokens.access` and `data.tokens.refresh`, with
+  `expiresIn.access = 3600` (1 hour) and `expiresIn.refresh = 2592000` (30 days). Subsequent calls
+  carry `Authorization: Bearer <access>`.
+
+> **⚠ Do not copy the `authority` field into caller documentation.** The response envelope's
+> `authority` reports the **internal** server that handled the request (observed: `api1.togahub.com`,
+> `api-writer.togahub.com`). Callers must always use `https://api.togahub.com/v2`.
+
+### `maxAuthsPerHour` throttles authentication, not traffic
+
+`Apis.maxAuthsPerHour` (client keys are typically `255`) is enforced at ~L1131 of `V2.php` by
+counting `Logs_<Client>.Api` rows with `isAuthRequest = 1` in the last hour. Over the limit returns
+a message telling the caller to re-use tokens. Tell integrators to authenticate once, cache the
+access token for the hour, and use the refresh token — not to call `/auth/api` per request.
+
+## How an API key's authorization is decided
+
+At `V2.php` ~L1639, once the `Apis` row authenticates:
+
+1. `_Model_Client_Apis_Role` is searched for that `apiId`.
+2. Those `roleId`s are **assigned** to `$id->client->roles` — the `array_merge(...)` line directly
+   above it is **commented out**. So the key holds those roles and only those roles.
+3. Core roles are then derived by selecting `Client_<Client>.Roles.coreRoleId` for those client
+   roles, skipping NULLs.
+
+**A new client role with `coreRoleId` NULL is fine** for any record whose `Core.Records.aclDatabase`
+is `CLIENT`. Core roles only matter for records flagged `CORE` (the permission scan at ~L3159+).
+
+### ⚠ `appId` cannot scope an API key — every appId-scoped grant applies
+
+`$this->app` is only set when the JWT carries an app uuid (`V2.php` L1518 / L1961), which is the
+**domain/user login** flow. On API-key auth it is never set, and every permission filter reads:
+
+```php
+(!isset($this->app) || is_null($perm->appId) || $perm->appId == $this->app->id)
+```
+
+With `$this->app` unset the first clause short-circuits **true**, so **all** `appId`-scoped
+`AclRecordPermissions` rows for the key's roles apply. A grant that was deliberately narrowed to one
+app (e.g. `appId = 5`, TOGa Commerce) is fully available to any API key holding that role. Scope a
+machine consumer with a **dedicated role**, never with `appId`.
+
+### The grant chain still applies
+
+An `AclRecordPermissions` row on its own grants nothing — the request fails with
+`No ACL Logic Groups defined for ACL Record Permissions`. Full rules, tables and checklist:
+[ACL Permission Chain](../../_underscore/features/acl-permission-chain.md).
+
+## Auditing what a key actually did
+
+`Logs_<Client>.Api` carries `apiId`, `dtStamp`, `method`, `route`, `responseCode`, `queryString`,
+`requestPayload` and `responsePayload`. **Filter on `apiId`** to get one consumer's exact calls and
+responses — this is how you answer "what did this integrator really use". Note the client-vs-core
+log split (failed writes and pre-scope auth failures land in core `Logs`):
+[V2 Request Logging](./request-logging.md).
+
+## Gotchas
+
+- **Roles are replaced, not merged.** Auditing a key means reading `Apis_Roles` and nothing else.
+- **`appId` is not a security boundary for machine callers.** See above.
+- **A shared role across keys means the key identifies the caller but does not limit it.** If
+  several `Apis` rows point at the same roles, every one of them can do everything those roles
+  allow, regardless of what the integration's published documentation says.
+- **Never record a secret value in a doc or a committed SQL file.** Document only where it lives
+  (the `Client_<Client>.Apis` row) and hand it over out of band.
+
+## Change history
+- 2026-09-14 — Created from the Compass Refresh-team API build. Recorded the `/auth/api` call shape
+  (`transactionId` in the query string; body `{client, api, secret}`), the 1 hour / 30 day token
+  lifetimes, the `maxAuthsPerHour` auth-only throttle, and two authorization facts verified in
+  `V2.php`: API-key roles are **assigned** from `Apis_Roles` (the `array_merge` is commented out,
+  ~L1639), and `$this->app` is never set for key auth so **every `appId`-scoped ACL row applies**.
+  Also noted the `authority` response field exposes the internal host and must not be published to
+  callers. (bala)

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-14
 owners: ["mhammontree", "dfranks", "bala", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,6 +15,7 @@ files:
   - _underscore/Model/Core/Logs/Api.php
 related:
   - ../architecture.md
+  - ./api-key-authentication-and-scoping.md
   - ./api-payload-interceptors.md
   - ./v2-api-error-codes.md
   - ./v2-deadlock-retry.md
@@ -362,6 +363,16 @@ fact AIG **does** post live entitlements — the writes were **failing (HTTP 500
 core `Logs`**, not `Logs_Aig`. See
 [AIG entitlement intake → Intake is a live API feed](../../../../clients/aig/features/entitlement-intake.md).
 
+### Auditing ONE API consumer — filter `Logs_<Client>.Api` on `apiId`
+
+`Logs_<Client>.Api` carries `apiId` alongside `dtStamp`, `method`, `route`, `responseCode`,
+`queryString`, `requestPayload` and `responsePayload`. Filtering on a single `apiId` is how you
+answer "what did this integrator actually call, and what did it get back" — it was used to verify
+the new Compass Refresh key's routes and to lift real sample responses for its reference document.
+`isAuthRequest = 1` rows are that key's `/auth/api` calls, and are what `Apis.maxAuthsPerHour`
+counts. The blind spots above still apply — the key's **failed writes land in core `Logs`**. See
+[API-Key Authentication](./api-key-authentication-and-scoping.md).
+
 ## Querying prod `Logs.Api` without timing out (narrow first, fetch payloads last)
 
 Prod `Logs.Api` is large enough that **any `LIKE` over `requestPayload` / `responsePayload`
@@ -426,6 +437,11 @@ re-send.
 > replay operationally, not by pasting payloads into the KB.
 
 ## Change history
+- 2026-09-14 — Added the per-consumer audit note: filter `Logs_<Client>.Api` on **`apiId`** to get
+  one API key's exact routes, payloads and response codes (`isAuthRequest = 1` rows are its
+  `/auth/api` calls, the ones `Apis.maxAuthsPerHour` counts). Used to verify the new Compass Refresh
+  key. Cross-linked the new
+  [API-Key Authentication](./api-key-authentication-and-scoping.md) doc. (bala)
 - 2026-09-10 — Sharpened the client-vs-core routing on the auth codes: a **401 always lands in the
   base `Logs`** (decided in the auth chain ~L2088 before routing, client unresolved) while a **403
   lands in `Logs_<Client>`** (client already known) — verified on Prudential 31 Aug–1 Sep, where

package/knowledge/INDEX.md

@@ -20,8 +20,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 83 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 68 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 18 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 19 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 6 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -27,6 +27,7 @@
 | [Compass USA — reversing the 199-item catalog fold (MITS outage recovery)](workflows/catalog-fold-reversal.md) | 2.0 | The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items mer |
 | [Changing what is IN a Compass kit (adding / swapping a BundleItems line)](workflows/changing-a-kit-line-item.md) | 2.0 | "Add this fee/component to every kit that has X" is a recurring Compass request, and it looks like one `INSERT` into `Client_Compass.BundleItems`. |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe |
+| [Giving a Compass API consumer its own scoped key (one role per key)](workflows/granting-api-access.md) | 2.0 | "Give team X API access" on Compass used to mean handing out another key wired to the same two shared roles. |
 | [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. |
 | [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e |

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

@@ -20,7 +20,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-09-04
+updated: 2026-09-14
 owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani, ajean]
 files: []
 related:
@@ -32,6 +32,7 @@ related:
   - workflows/granting-persona-bundle-access.md
   - workflows/changing-a-kit-line-item.md
   - workflows/granting-navigation-access.md
+  - workflows/granting-api-access.md
   - features/mits-sales-order-transmission-alerting.md
   - features/oneuptime-ma-refresh-order-monitor.md
   - workflows/catalog-fold-reversal.md
@@ -206,6 +207,18 @@ separate, related client (see its own profile).
   the ⚠ rule that **deactivation is raw bulk SQL, so no model hook ever fires on it**.
 
 ## Notes
+- **⚠ Compass API keys: four of the five are NOT scoped (2026-09-10).** Agilant, MITS Service Hub,
+  Compass Group and Office Depot (Cxml) all share the same two roles — Base (1) and API (3) — so each
+  of them can create, update and delete across **291 records**, whatever its published integration
+  document says (MITS's lists 5 read lookups). `appId` cannot fix this: an API key never gets
+  `$this->app` set, so every appId-scoped grant applies to it. The **'Compass Refresh Team'** key
+  (prod `Apis.id 5`) is the first with its **own read-only role** ('Refresh API', prod roleId 17,
+  9 records / 0 writable) and is the template for the next consumer:
+  [Giving a Compass API consumer its own scoped key](workflows/granting-api-access.md).
+  **Open:** the generated secret is still in plain text inside
+  `dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql` (strip or rotate it), the
+  negative test was never run, the script was applied straight to prod, and the four older keys are
+  not migrated.
 - **Item modal "Restrict to Persona" needed a Surface opt-in that was never written (2026-09-04).**
   Core seeds the item modal's More-Info `restrictToPersona` field **OFF** for every client
   (surface 19 / element 57), expecting a per-client override — Compass USA had **none**, so the

package/knowledge/clients/compass-usa/workflows/granting-api-access.md

@@ -0,0 +1,142 @@
+---
+title: Giving a Compass API consumer its own scoped key (one role per key)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-09-14
+owners: ["bala"]
+files:
+  - dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql
+related:
+  - ../profile.md
+  - ./granting-navigation-access.md
+  - ../../../2.0/apps/api2/features/api-key-authentication-and-scoping.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/api2/features/request-logging.md
+---
+
+## Summary
+
+"Give team X API access" on Compass used to mean handing out another key wired to the same two
+shared roles. **Every pre-existing Compass key can read and write almost everything**, so the key
+identified the caller but did not limit it. The Refresh-team key (built 2026-09-10) is the first
+Compass key with **one dedicated, read-only role of its own**, and its migration
+`dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql` is the template for the next
+consumer: copy it and change the record list.
+
+Why a dedicated role is the only lever: an API key's roles come **only** from `Apis_Roles`, and
+`appId` scoping does not bind a key at all — see
+[API-Key Authentication](../../../2.0/apps/api2/features/api-key-authentication-and-scoping.md).
+
+## ⚠ The four older Compass keys are NOT scoped
+
+All four pre-existing `Client_Compass.Apis` rows — **Agilant**, **MITS Service Hub**,
+**Compass Group**, **Office Depot (Cxml)** — are wired in `Apis_Roles` to the **same two roles**:
+
+| Role | id | Record permissions | Writable |
+|---|---|---|---|
+| Base | 1 | 123 | 115 |
+| API | 3 | 291 | **all 291** |
+
+So MITS, whose published integration document lists **5 read lookups**, can in fact create, update
+and delete across 291 records. Nothing in the database constrains any of those four keys to its
+documented calls. Anyone auditing Compass API access needs to start from this fact. Migrating those
+four keys onto per-key roles (starting with MITS) is **intended but not done**.
+
+## The Refresh-team key (the worked example)
+
+Landed on **production** 2026-09-10:
+
+- `Client_Compass.Apis` row **'Compass Refresh Team'** (prod `id = 5`).
+- `Apis_Roles` binds it to exactly **one** new client role, **'Refresh API'** (prod `roleId = 17`).
+- Read-only: **9 records**, **83 field permissions**, **18 custom-field permissions**,
+  **0 writable anywhere**.
+- Records granted (`Core.Records.id`): **2** users, **11** locations, **37** contacts,
+  **38** contact-email-addresses, **39** contact-phone-numbers, **40** personas,
+  **201** user-personas, **273** user-roles, **274** roles.
+- Field grants were **cloned from the shared API role (roleId 3)** for those same records, minus the
+  two fields listed below.
+
+The consumer calls four requests: auth, cost center by number (`/locations`), user by email
+(`/users`), and user by Compass username (`/users`).
+
+## Steps
+
+1. Create the `Client_Compass.Roles` row for the consumer (one role, one key). `coreRoleId` may stay
+   NULL — every record here has `Core.Records.aclDatabase = 'CLIENT'`.
+2. Insert the `Client_Compass.Apis` row with a generated uuid and secret, then the single
+   `Apis_Roles` row binding it to that new role only.
+3. For each record the consumer needs, build the **whole** ACL chain — `AclRecordPermissions` +
+   `AclLogicGroups` + `AclLogicGroupExpressions` + `AclRecordExpressions`. A permission row alone
+   fails the request with `No ACL Logic Groups defined for ACL Record Permissions`
+   ([ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)).
+4. Clone the field grants from role 3 for those records, with `isWritable = 0`, **dropping**:
+   - `Users.password` — `recordFieldId 611`
+   - `Users.ldapDn` — `recordFieldId 1329`
+5. Reuse `AclRecordExpressions.id = 4` on record 2 (Users). That expression is the row filter that
+   **hides every user whose email ends in `@togatech.com`**, so internal TOGa staff accounts never
+   appear in an API user lookup. Any new role reading Users should reuse it.
+6. Verify before handover (see below), then hand the uuid and secret to the consumer out of band.
+7. Produce the consumer's reference document (see below).
+
+### ⚠ Do not clone `AclLogicGroup id 20` wholesale
+
+Logic group **20** (role 3, Users) also links `AclRecordExpressions id 16` — but expression 16
+belongs to `recordId 22`, not 2. It is a **stray mis-linked row** in the shared role. It was
+deliberately **not** copied into the Refresh role. Read what an expression actually points at before
+mirroring it.
+
+## Verification
+
+- Counts: 9 records / 83 field permissions / 18 custom-field permissions / 0 writable — all passed
+  on prod.
+- `Apis_Roles` for the new `apiId` returns **exactly one** `roleId`.
+- Call each intended route with the new key, then read `Logs_Compass.Api` filtered on the new
+  `apiId` to confirm the exact routes and response payloads
+  ([V2 Request Logging](../../../2.0/apps/api2/features/request-logging.md)).
+
+## Environment note — Compass Core ids matched prod and client-sandbox
+
+Checked 2026-09-10 for this client: `Core.Records` ids, every `Core.RecordFields` id for records
+2/11/37/38/39/40/201/273/274, `Client_Compass.AclRecordExpressions` ids and
+`Client_Compass.CustomRecordFields` ids were **identical between production and client-sandbox**. So
+this ACL script, written against prod ids, runs unchanged on client-sandbox for Compass.
+
+> This contradicts the usual assumption that `RecordFields` ids are environment-specific. Treat it
+> as a **Compass prod to client-sandbox** observation, not a general rule — re-check per client and
+> per environment before reusing a script elsewhere. The general rule (resolve ids to names before
+> diffing environments) still stands.
+
+## The consumer-facing reference document
+
+Each API consumer gets a Word reference document, mirroring the existing MITS one. It is generated
+with `python-docx` using the MITS `.docx` as the style template, and covers the four requests, real
+sample responses lifted from `Logs_Compass.Api`, Postman links, token lifetimes, and a plain-English
+"what your key can access" section. **Credentials in the document are placeholders only.** The file
+lives outside the repos (the developer's local Downloads) — the binary is not stored in git or the
+knowledge base.
+
+## Open items (as of 2026-09-14)
+
+- **⚠ The generated secret is sitting in plain text inside
+  `dbchanges2/Client_Compass/2026-09-10 - RefreshTeamApiAccess.sql`, which is a git repo.** Strip it
+  before commit or rotate the secret. Never commit a secret value.
+- The **negative test has not been run** — calling a route outside the grant (e.g. `/items`) with the
+  Refresh key to confirm `UNAUTHORIZED`.
+- The script was run **directly on production**; the intended client-sandbox dry run was skipped.
+- Migrating the four older keys (Agilant, MITS Service Hub, Compass Group, Office Depot (Cxml)) off
+  the shared Base + API roles onto per-key roles is **not started**.
+
+## Change history
+- 2026-09-14 — Created. Built the first per-key Compass API role: `Apis` row 'Compass Refresh Team'
+  (prod id 5) bound to the single read-only role 'Refresh API' (prod roleId 17) over 9 records / 83
+  field grants / 18 custom-field grants, 0 writable, cloned from role 3 minus `Users.password` (611)
+  and `Users.ldapDn` (1329). Recorded that the four older Compass keys all share Base (1) + API (3)
+  and are therefore fully writable across 291 records; that `AclRecordExpressions id 4` is the
+  `@togatech.com` staff-hiding row filter to reuse; that logic group 20 links a stray expression
+  (id 16, wrong record) not to be cloned; and that Compass Core metadata ids matched prod and
+  client-sandbox. Open: secret still in the SQL file, negative test not run, prod-only run, older
+  keys not migrated. (bala)

package/package.json

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