toga-ai 1.0.806 → 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/_underscore/features/model-interceptor-unit-testing.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-09-11
 owners: ["bala"]
 files:
   - _underscore/Test/bootstrap.php
   - _underscore/Test/Prudential/ServiceRequestTest.php
   - test/@Bala/tests/netsuite_salesorder_payload_tests.php
+  - _underscore/Test/Compass/
 related:
   - ../../../../clients/prudential/features/service-request-address-validation.md
   - ../../worker2/features/netsuite-salesorder-outbound-push.md
@@ -44,6 +45,7 @@ Prudential `validateCustomer()` guard (see the service-request address-validatio
 4. Run it with:
 
    ```
+   # there is no phpunit binary in the repo - see the section below
    phpunit --bootstrap _underscore/Test/bootstrap.php _underscore/Test
    ```
 
@@ -51,6 +53,29 @@ The initial suite covers the `validateCustomer()` guard: absent `customer`, null
 empty-string `uuid`, whitespace-only `uuid`, error-message content, and a valid `uuid` passing.
 Verified 6/6 passing against the real code.
 
+### There is no PHPUnit - newer suites are standalone runnable scripts
+
+`_underscore` still has **no `composer.json` and no `phpunit` binary**, so the `phpunit --bootstrap`
+line above only works if a developer has PHPUnit installed globally. The pattern that actually
+travels is a **plain runnable script**: `php Test/Compass/<file>.php`, **exit 0 on pass**. The
+Compass step-1 approval guard (`_underscore/Test/Compass/`, branch `TRUE-81900`) added three shapes
+worth reusing:
+
+1. **Stubbed** - fakes `_Query` and drives the real guard down every branch. No database.
+2. **Real-database** - points `_Query` at a **local MySQL copy** so the generated SQL actually
+   executes against the real schema. It finds its own fixtures **by query** and reports **SKIP**
+   (not FAIL) when a particular copy lacks them, so it never fails for the wrong reason.
+3. **Replay sweep** - replays real historic approvals and compares **every** verdict against plain
+   SQL (6,000 approvals for that guard).
+
+The stubbed suite proves the logic, the real-database suite proves the **SQL** is valid against the
+live schema, and the sweep proves the verdict matches production reality. They are complementary -
+picking only one leaves a whole class of bug uncovered.
+
+**Prove the suite catches regressions with mutation testing.** There is no coverage tool here, so
+three deliberate breaks were introduced and each had to be caught before the suite was trusted. Do
+this for any hand-rolled suite.
+
 ## Gotchas / known issues
 
 - **Reflection on private methods is the pattern here** — the interceptor validators are private,
@@ -69,7 +94,25 @@ Verified 6/6 passing against the real code.
   `--bootstrap` file to wire up requires. Adding more model tests means extending
   `Test/bootstrap.php` with the stubs that model needs.
 
+- **⚠ On a PUT, read request-only intent from `$api->httpPayload`, never from the merged
+  record.** The merged record always carries `isApproved` from the **existing DB row**, so a guard
+  that read it there treated a plain manager reassignment as a **false approval**. The stubbed suite
+  caught this during development - it is the concrete payoff of the stub-the-DB pattern.
+- **A real-database suite must SKIP on a missing fixture, not FAIL.** Local prod copies differ
+  between developers; a suite that hard-fails when a specific order is absent gets ignored, and an
+  ignored suite protects nothing.
+
 ## Change history
+- 2026-09-11 - **Corrected the run story and added the three-suite pattern.** `_underscore` has no
+  PHPUnit binary, so suites are **standalone scripts** run as `php Test/<path>.php` (exit 0 = pass).
+  The Compass step-1 approval guard shipped three complementary suites in `_underscore/Test/Compass/`
+  (branch `TRUE-81900`): a **stubbed** one that fakes `_Query` and covers every branch, a
+  **real-database** one that runs the generated SQL against a local prod copy and reports **SKIP**
+  when fixtures are missing, and a **replay sweep** that re-decides 6,000 real approvals and compares
+  each verdict against plain SQL. **Mutation testing** (three deliberate breaks, all caught) was used
+  to prove the suite detects regressions. Recorded the real bug the stubbed suite found: on a PUT the
+  merged record always carries `isApproved` from the DB row, so reading it there instead of
+  `$api->httpPayload` turns a manager reassignment into a false approval. (bala)
 - 2026-08-10 — Noted that the stub + reflect-into-privates pattern also carries to **worker2 actions**
   driven from the `test` repo (`test/@Bala/tests/netsuite_salesorder_payload_tests.php`, 76 tests,
   plain PHP, loading the real `Worker/Netsuite/SalesOrder.php`) — a second worked example of testing

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/api-payload-interceptors.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-02
+updated: 2026-09-11
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -623,6 +623,13 @@ and the failing environment**. It is a small table, and the drift is usually exa
   specifics belong in `_Model_<Slug>_X` overrides + interceptor hooks, **not** in `V2.php`.
 
 ## Change history
+- 2026-09-11 - Live instance of the "not registered = dead code" rule: `recordId 179`
+  (approval-decisions) carried only PRE/PUT, POST/PUT and POST/POST in **both** Compass tenants, so a
+  newly added `_Model_Compass_ApprovalDecision::prePost()` would never have run and would have raised
+  **no error**. `dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql`
+  and its `Client_CompassCanada` twin add the PRE/POST row, `NOT EXISTS`-guarded so they are safe to
+  re-run. Checking the registration table **before** writing a new hook is the cheap step that avoids
+  this. (bala)
 
 - 2026-09-02 — Recorded the **deliberate shared-model exception**: a hook may live on
   `_Model_Client_X` when the behaviour is client-agnostic and the interceptor row is the gate (no row,

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/2.0/apps/toga25-supply/features/action-button-rule-engine.md

@@ -6,13 +6,15 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
-owners: [apeterson]
+updated: 2026-09-11
+owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts
   - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.test.ts
   - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
   - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx
+  - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowForm.tsx
+  - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASS/approvalActionFields.json
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASSCANADA/approvalActionFields.json
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
@@ -151,7 +153,38 @@ Retire the shim once all configs express flags as `Rule`.
   comparison must stay config-only; adding to `NAMED_RULES` is the rare exception, not the
   default.
 
+- **⚠ A named rule must use a TRUTHY check, never `!== null`.** `stepTwoAssigned` tested
+  `stepTwo.AssignedTo?.uuid !== null`, which is **true** when the API omits `AssignedTo` altogether
+  (`undefined !== null`) - so a missing step-2 manager *enabled* the Approve button and let an admin
+  strand the order. Now a truthy check on the uuid. The `poNumberEntered` rule directly below it
+  already carried a comment warning about this exact trap. The matching server-side guard is in
+  [Compass Approval-Decision Flow](../../../clients/compass-usa/features/approval-decision-flow.md).
+- **⚠ The evaluator is DUPLICATED in the surface layer.** `src/surface/evaluateSurfaceRule.ts`
+  holds its own copy of the named rules and had the identical `!== null` bug. A change to a named
+  rule must be made in **both** files - fixing one is not a fix.
+- **Resolving a flag is not the same as gating the submit.** `isApproveButtonEnabled` disabled the
+  approve controls but **not Save Changes**, and "Approve All Stages" writes the decision straight
+  into form state, so a blocked approval still posted. `ApprovalFlowForm.tsx` now gates the Save
+  button **and** `handleValidSubmit` on an `isApprovalBlocked` flag, which requires **both** that
+  approving is disabled **and** that the approve is *newly* selected - compared against
+  `defaultValues`, because a stage approved earlier already defaults to `"1"`. The disabled Save
+  reuses the existing tooltip.
+- **`stepTwoAssigned` is configured only for COMPASS and COMPASSCANADA** (`approvalActionFields.json`).
+  DEFAULT and QUAD gate Approve on `order.purchaseOrderDetails.uuid` instead, so a change to this
+  rule cannot reach them.
+
 ## Change history
+- 2026-09-11 - **Fixed `stepTwoAssigned` reading a missing assignee as assigned.** The rule tested
+  `stepTwo.AssignedTo?.uuid !== null`, which is true when the API omits `AssignedTo` entirely, so the
+  Approve button was enabled on orders with no step-2 manager and admins stranded four prod orders.
+  Changed to a truthy uuid check, **in both** `helpers/evaluateEnableRule.ts` and the duplicate copy
+  in `src/surface/evaluateSurfaceRule.ts`. Also gated **Save Changes** (and `handleValidSubmit`) in
+  `ApprovalFlowForm.tsx` on a new `isApprovalBlocked` flag - disabling only the approve controls was
+  not enough, because "Approve All Stages" writes the decision into form state and the save still
+  posted; the flag compares against `defaultValues` so a previously approved stage is not treated as
+  a new approval. Affects COMPASS and COMPASSCANADA only; DEFAULT/QUAD gate on
+  `purchaseOrderDetails.uuid`. Ticket TRUE-81900. **Uncommitted on `_production` at capture time.**
+  (bala)
 - 2026-08-31 — **Added named rule `stepOneUndecided` and extended `buildPatchedTenantFields` to
   resolve flags on `approvalWorkflow.stages[].inputs[]`**, so a VIP-pre-approved step-2 manager can
   be reassigned (Compass USA + Compass Canada). `ApprovalFlowDetailInputs` now treats a resolved

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
-owners: [apeterson, tcox, jcardinal]
+updated: 2026-09-11
+owners: [apeterson, tcox, jcardinal, bala]
 files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
@@ -358,7 +358,37 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md) and
   [Transfer Orders page](transfer-orders-page.md).
 
+- **⚠ The approval modal has TWO approve paths, and the payload shape tells them apart.**
+  Both are dispatched from `RecordApprovalModal/hooks/useApprovalDecisionsMutation.ts`:
+  - `type: "single"` (the green per-stage tick) goes through `makeApprovalDecision` /
+    `updateApprovalDecision` in `api/approvalDecisionsApi.ts` and sends `isApproved` as a
+    **boolean** plus a `note` field.
+  - `type: "workflow"` ("Approve All Stages" / Approval Workflow) goes through
+    `helpers/handleFormatApprovalWorkflowPayload.ts` and sends `isApproved` as the **string `"1"`**
+    with **no** note.
+
+  That difference is how you tell from `Logs_<Tenant>.Api` which button a user actually pressed -
+  the first step in any approval investigation, and the reason a bug can live in one path only.
+- **⚠ The single-stage approve must NOT send `assignedToUserId`.** `makeApprovalDecision()`
+  and `updateApprovalDecision()` hardcoded `assignedToUserId: { uuid: userUuid }`, so every
+  green-tick approve re-sent the **logged-in user** as the stage assignee whether or not anyone
+  touched the field. An admin approving the manager stage therefore **overwrote the real manager
+  with themselves**, and the order timeline then read "Manager Approved" - it looked like the
+  manager had approved. Removed from both functions; `decidedByUserId` already records who approved.
+  The workflow path was always correct (it sends the assignee only when it actually changed), which
+  is exactly why the bug never reproduced through "Approve All Stages". Real orders: SA136901,
+  SA136807, SA137080. Client context:
+  [Compass Approval-Decision Flow](../../../clients/compass-usa/features/approval-decision-flow.md).
+
 ## Change history
+- 2026-09-11 - ⚠ **Removed the hardcoded `assignedToUserId` from the single-stage approve
+  payload** (`approvalDecisionsApi.ts`). Every green-tick approve was re-sending the logged-in user
+  as the stage assignee, so an admin approving the manager stage silently replaced the real manager
+  and the timeline then read "Manager Approved" (prod: SA136901, SA136807, SA137080). Also recorded
+  the **two approve paths and their differing payload shapes** (`single` = boolean `isApproved` +
+  `note`; `workflow` = string `"1"`, no note), which is how the two are told apart in
+  `Logs_<Tenant>.Api` and why the workflow path never showed the bug. Ticket TRUE-81900.
+  **Uncommitted on `_production` at capture time.** (bala)
 - 2026-09-04 — Added the Pattern 6 gotcha that the **item modal's VIEW is Surface-driven while its
   EDIT is still JSON**: a field visible only in edit mode means a missing client `SurfaceOverride`,
   not a data bug (found on Compass's "Restrict to Persona" field). Detail in

package/knowledge/2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-14
 owners: ["bala"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
@@ -47,9 +47,16 @@ re-read this doc if you last saw it on 2026-09-02: **the NetSuite customer is th
 destination location**, and `description` is now sent as the NetSuite **`memo`**. Committed as
 worker2 **`cbafd25`** on `_production` and deployed.
 
-**A third correction is written but NOT yet deployed (2026-09-09): the push was sending no ship-to
-address at all**, so NetSuite used the customer's default site on every order. That fix and the
-depth-6 read it needs are below.
+**Deployed 2026-09-14 and confirmed working end to end.** Two more things landed since 2026-09-08
+and are the reason to re-read this doc:
+
+1. **The push was sending no ship-to address at all**, so NetSuite used the customer's default site
+   on every order. Fixed by reading the destination Location's address, which needs a depth-6 read.
+2. **Sending that address then broke every create with an HTTP 400 tax error** from 2026-09-09 to
+   2026-09-14. The cause was **NetSuite customer data, not code** — the customer still carried the
+   retired tax group **-8**. Read
+   [the tax-item section](#-the-customers-netsuite-tax-item-must-be-avatax-or-every-create-400s)
+   before you touch anything tax related here, and before onboarding a new client to this push.
 
 ## Key files / entry points
 
@@ -104,11 +111,11 @@ status columns, so none are sent.
 | `tranDate` | `dateOrder`, date only; **omitted** when null |
 | `otherRefNum` | the PO number (the developer's explicit requirement) |
 | `memo` | `TransferOrders.description` — the NYCHH custom form renders it as **"ORDER DESCRIPTION"** |
-| `shippingAddress` | the **destination** Location's `primaryLocationAddress.address` (added 2026-09-09, not yet deployed). The key is **omitted** when the destination has no address, so NetSuite keeps its own default instead of getting an empty one. |
+| `shippingAddress` | the **destination** Location's `primaryLocationAddress.address` (added 2026-09-09, live 2026-09-14). The key is **omitted** when the destination has no address — and **omitting it is a bug, not a safe default**: NetSuite then ships to the customer's default site. See below. |
 | `externalId` | `toga-to-<transfer order uuid>` |
 | line `item` / `quantity` | each transfer-order item |
 | line `rate` | **0** — this is the zero-value part |
-| line `location` | the **origin** warehouse |
+| line `location` | the **origin** warehouse. **`location` is NOT a ship-to** — NetSuite never uses a line's location for delivery. |
 
 ### ⚠ Destination = CUSTOMER, origin = WAREHOUSE (this was built backwards first)
 
@@ -146,6 +153,12 @@ no NetSuite customer for.
 > multi-site tenant those are different NetSuite records, and the difference is invisible until
 > someone picks the non-default site.
 
+**A consequence worth knowing before you go hunting in supply:** `resolveTransferOrderCustomer()`
+always lands on the **client's** customer, so **changing the destination location cannot change the
+NetSuite customer**. When a problem is customer-level (a tax item, a hold, a wrong subsidiary),
+picking a different destination site is not a workaround — the destination only supplies the
+ship-to address.
+
 **Verified live 2026-09-08 on SO 289187 (id 7463537):** destination Woodhull (customer **31925**),
 customer on the NetSuite order came out **4490 / NYC Health + Hospitals**, and ORDER DESCRIPTION
 showed the transfer order's `description`.
@@ -155,7 +168,7 @@ destination whose customer id already equals the client's own (**30205** and **3
 and new rules produce the same id for them.
 
 
-### ⚠ The ship-to address was NEVER sent — and it needs a depth-6 read (fixed 2026-09-09, not deployed)
+### ⚠ The ship-to address was NEVER sent — and it needs a depth-6 read (fixed 2026-09-09, live 2026-09-14)
 
 `buildSalesOrderShapeFromTransferOrder()` never set a `shipToAddress` key, and the `shippingAddress`
 block in `buildNetSuiteOrder()` (~L922) only runs when that key exists. So **every transfer order
@@ -210,6 +223,35 @@ null, and the code fix would have been a **silent no-op**. Fixed by
 > row drops the branch silently instead of erroring — see
 > [nested FK ACL embedding](../../api2/features/nested-fk-acl-embedding.md).
 
+#### ⚠ Dropping the address is NOT a workaround — NetSuite ships to the customer default, silently
+
+When the payload omits the ship-to address the create **succeeds**, so it looks like a fix. It is
+not. NetSuite falls back to whichever entry in the **customer's** address book is flagged
+`defaultshipping = T`, with no warning anywhere in the response. Because the customer is the client's
+whole account (previous section), that is one fixed site for **every** destination — NYCHH customer
+28908 has **124** saved addresses and the default is *NYCHHC Jacobi Dental* (address id 6568575,
+1400 Pelham Parkway South, Bronx NY 10461). **5 of the 6** transfer orders that reached NetSuite
+before the fix shipped there regardless of their real destination (orders 7453238, 7462009, 7463537,
+7467799, 7482373); only 7462031 was right, and only by accident — it predates the switch to the
+parent customer and was built on destination sub-customer 33674, whose own default happens to be the
+destination.
+
+> **Durable rule: "drop the address to get past the 400" is a wrong-address bug, not a fix.** A
+> successful create proves nothing about where the goods go. And the line-level `location` does not
+> save you — that is the **source** warehouse (NetSuite internal id 117 for NYCHH) and NetSuite never
+> uses it for delivery.
+
+#### Depth 6 is verified, and there is a decoy branch next to it
+
+`_Model_Client_TransferOrder::NETSUITE_READ_DEPTH = 6` was checked against the raw
+`Core.WorkerJobs.parameters` blob of a real job, not just reasoned about: at 6 the full
+`destinationLocation.primaryLocationAddress.address.state.country` branch comes through.
+
+**The decoy:** the same payload also carries `contact.contactLocations[].location...address`, and
+*that* branch runs out of depth and has **no `state`**. If you are debugging a missing state or
+country, check which branch you are reading before you raise the depth again — the destination
+branch is complete.
+
 ### `description` → `memo` cannot leak into a plain sales order
 
 `memo` is sent only from the transfer-order shape. There is **no `memo` RecordField and no `memo`
@@ -229,6 +271,76 @@ bridge first** (that is what the Create Transfer Order modal writes), and falls
 [SO↔PO bridge direction](../../_underscore/features/sales-order-purchase-order-bridge-direction.md)
 for why the bridge, not the column, is the real source.
 
+## ⚠ The customer's NetSuite tax item must be AVATAX, or every create 400s
+
+**Symptom.** Every transfer order create fails with NetSuite HTTP **400**:
+
+```
+Error while accessing a resource. Invalid shippingtaxcode reference key -8 for subsidiary 1.
+```
+
+`Core.WorkerJobs` ids **1534082, 1534805, 1535235, 1536824, 1536920** (all 2026-09-14). It started on
+**2026-09-09**, the day the push began sending a ship-to address, and it blocked **every** transfer.
+
+**Cause — customer data, not code.** NetSuite customer **28908** (NYC Health + Hospitals, the
+client-level customer from `Core.Clients.netsuiteCustomerInternalId`) still carried the **retired tax
+group -8** as its `taxitem`. When an order carries an **inline ship-to address**, NetSuite rebuilds
+the address on the order and re-checks the shipping tax code against **subsidiary 1**; `-8` fails that
+check and the whole create is rejected. No address, no re-check — which is exactly why this only
+appeared once the address fix went in.
+
+**Fix.** NetSuite ops changed `taxitem` on customer **28908** from `-8` to **5050 (AVATAX)**. No code
+change. Verified working the same day. This is the normal value here: **7151** of subsidiary 1's
+customers are already on 5050, and only **61** are still on -8.
+
+> **Durable rule: before a new client's first transfer order, check that its NetSuite customer's
+> `taxitem` is 5050 AVATAX.** This is an onboarding step, not a bug to debug later — the first order
+> for any customer still on -8 will fail with the message above.
+
+### ⚠ Pinning `taxItem` / `shippingTaxCode` in the payload does NOTHING
+
+This cost several failed attempts, so it is written down in the code as well (comment in
+`buildNetSuiteOrder()` just below the `shippingAddress` block):
+
+- **NetSuite derives both fields from the customer AFTER applying the address and discards whatever
+  we send.** Proven twice: jobs **1534805** and **1536824** both sent `-7` and both still failed
+  reporting **-8**.
+- **Stripping `state` and `country` from the shipping address does not help either** (job
+  **1535235**). *Any* inline address at all triggers the re-check.
+
+A `NETSUITE_TAX_CODE__NOT_TAXABLE = '-7'` constant and its pin block were added and then **removed
+again**. A comment now sits in their place warning not to re-add them. **Do not re-add them.**
+
+### ⚠ -8 is NOT a dead id — it lives in `taxgroup`, not `salestaxitem`
+
+An earlier code comment claimed -8 "points at nothing". **That was wrong**, and it sent the debug off
+in the wrong direction:
+
+| Id | Name | Table |
+|---|---|---|
+| **-8** | `-Not Taxable-` | **`taxgroup`** — exists and is **active** |
+| **-7** | `-Not Taxable-` | **`salestaxitem`** |
+
+Two different tables, the same display name. **Checking only `salestaxitem` for a tax code id will
+tell you it does not exist when it does.** Query both before concluding an id is dead — SuiteQL
+details in [NetSuite SuiteQL API reference](../../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md).
+
+### Who else is still on -8 (scanned 2026-09-14, re-check before onboarding)
+
+**61** NetSuite customers on subsidiary 1 remain on tax group -8. The ones that touch Toga:
+
+| NetSuite customer | Who | Risk today |
+|---|---|---|
+| **34283** Yale New Haven Health | a **client-level** customer in `Core.Clients` | will fail its **first** transfer order; client DB has **0** transfer orders today |
+| **2661** Endeavor Health | a **client-level** customer in `Core.Clients` | same — **0** transfer orders today |
+| **31584** Coney Island | a NYCHH **sub-customer** in `Client_Nychh.Customers` | dormant, **0** sales orders |
+| **1101** Miami-Dade Police Department | used by `Client_Miamidade` | nothing failing today |
+| **32030** Security 101 | used by `Client_Miamidade` | nothing failing today |
+
+All **17** other NetSuite customer ids used by `Client_Nychh` are already on **5050 AVATAX**. A scan of
+`Core.WorkerJobs` shows this error has only ever hit the transfer-order action — 5 jobs, all on
+2026-09-14.
+
 ## The trigger — `postPost` on the SHARED `_Model_Client_TransferOrder`
 
 `_Model_Client_TransferOrder::postPost` queues the action. **Not** `_Model_Nychh_TransferOrder` — a
@@ -363,8 +475,11 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
   `postPost` reads **zero lines** and the push aborts — the trigger would then have to move. See
   [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 - **dev-sandbox metadata is incomplete** (record 325 + its RecordFields + both inherent-child rows).
-- **The ship-to fix is written, `php -l` clean, but NOT deployed and NOT committed** (worker2 +
-  `_underscore`). The two NYCHH SQL files it depends on **have** been run on prod.
+- ~~**The ship-to fix is written but NOT deployed.**~~ **Closed 2026-09-14** — deployed, and
+  confirmed working by the developer after NetSuite customer 28908 moved off tax group -8.
+- **The -8 tax-group list is a snapshot (2026-09-14).** Re-run the check before onboarding any new
+  client to this push; **34283 Yale New Haven Health** and **2661 Endeavor Health** are the two that
+  will fail on their first order.
 - **Undecided: should the delivery contact go into the NetSuite `attention` field?** NetSuite ship-to
   addresses carry a person on the first line (order **289193** shows *Frederick Roberts*, the Bellevue
   delivery contact). `TransferOrders.contactId` exists as an FK on `_Model_Client_TransferOrder` but
@@ -390,6 +505,9 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
   a lost PO number aborts the push. Do not "optimise" the depth.
 - **This action does not retry itself**, exactly like the sales-order push: a throw records
   `isSuccess = 0` and stops. An event-triggered push fires once.
+- **A NetSuite HTTP 400 naming a tax code is a CUSTOMER data problem, not a payload problem.** Check
+  the customer's `taxitem` first; do not try to pin the tax fields in the payload (they are ignored)
+  and do not drop the address to make the error go away (that silently ships to the wrong site).
 - **`git diff --stat` after any programmatic full-file write to `_underscore`.** A full-file write
   with an editor default flipped CRLF → LF on `_underscore/Model/Nychh/TransferOrder.php` — content
   identical, git reported it modified with no content hunks. Restored with `git checkout --`. The
@@ -397,6 +515,30 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
 
 ## Change history
 
+- 2026-09-14 — **Deployed the ship-to fix, then spent the day on the 400 it exposed. Root cause was
+  NetSuite customer data.** From 2026-09-09 every transfer order create failed with *"Invalid
+  shippingtaxcode reference key -8 for subsidiary 1"* (`Core.WorkerJobs` 1534082, 1534805, 1535235,
+  1536824, 1536920). NetSuite customer **28908** still carried the retired tax group **-8**; sending
+  an inline ship-to address makes NetSuite rebuild the address and re-check the shipping tax code
+  against subsidiary 1, and -8 fails it. **NetSuite ops moved 28908's `taxitem` from -8 to 5050
+  (AVATAX)** — no code change, and the push was confirmed working end to end. Recorded three things
+  that cost real time: **pinning `taxItem`/`shippingTaxCode` in the payload is ignored** (NetSuite
+  derives both from the customer *after* the address — jobs 1534805 and 1536824 both sent -7 and both
+  still failed on -8), so the `NETSUITE_TAX_CODE__NOT_TAXABLE = '-7'` constant and its pin block were
+  added and then removed with a warning comment left behind; **stripping `state`/`country` does not
+  help either** (job 1535235) because any inline address triggers the re-check; and **-8 is not a dead
+  id** — it is active in `taxgroup` as "-Not Taxable-", while `salestaxitem` holds -7 with the same
+  name, so an earlier comment claiming it "points at nothing" was wrong. Also documented that
+  **omitting the address is a wrong-address bug, not a fix**: NetSuite silently uses the customer's
+  `defaultshipping = T` entry (28908 has 124 addresses; the default is Jacobi, id 6568575), which is
+  why 5 of the 6 orders that reached NetSuite went to the wrong site. Confirmed the line `location` is
+  the source warehouse (117) and is never a ship-to; that `resolveTransferOrderCustomer()` always
+  lands on the client's customer, so changing the destination cannot work around a customer-level
+  problem; and that `NETSUITE_READ_DEPTH = 6` really does carry
+  `destinationLocation.primaryLocationAddress.address.state.country` (verified against a real job's
+  `parameters` blob), while the neighbouring `contact.contactLocations[]` branch runs out of depth and
+  is a decoy. Added the dated list of the **61** customers still on -8, of which **34283 Yale New Haven
+  Health** and **2661 Endeavor Health** are client-level and will fail their first transfer order. (bala)
 - 2026-09-09 — **The push had never sent a shipping address at all.**
   `buildSalesOrderShapeFromTransferOrder()` set no `shipToAddress` key, so the `shippingAddress` block
   in `buildNetSuiteOrder()` never ran and NetSuite substituted the **customer's default** site on every

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/features/approval-decision-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-11
 owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
@@ -15,6 +15,7 @@ files:
   - _underscore/Model/Compass/Canada/ApprovalDecision.php
   - _underscore/Model/Client/ApprovalTemplateStage.php
   - _underscore/Model/Quad/SalesOrder.php
+  - dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql
 related:
   - mr-ma-order-approval-and-status.md
   - ../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md
@@ -241,6 +242,38 @@ break the invariant and produce a stage with two competing approvers. Both exist
 paths already respect this (`_Model_Compass_SalesOrder` compares `assignedToUserId != managerId` and
 then PUTs).
 
+### Step-1 approval is blocked when step 2 has no assignee (guard - BUILT, NOT DEPLOYED)
+
+An admin could approve step 1 on an order whose step-2 stage had **no `assignedToUserId`**. The
+order then moved to *Pending Approval* assigned to nobody: no manager approval-request email is
+sent (that email is addressed from the step-2 assignee), nobody can act on it, and **no report
+surfaces it** - the order just goes silent. Real prod population: **SA136795, SA137088, SA137146,
+SA137235**.
+
+`_Model_Compass_ApprovalDecision` now carries a `prePost()` plus an extended `prePut()` that reject
+a **step-1 approval** when the step-2 stage has no `assignedToUserId`, throwing
+`_Exception_Validation` (api2 maps it to **HTTP 400**). Both tenants are covered automatically,
+because the subclasses are empty.
+
+**Every exemption is decided from the database, never from the request payload:**
+
+- **MR/MA orders** - matched on the `SalesOrders.number` prefix; see
+  [MR/MA order approval and status](mr-ma-order-approval-and-status.md).
+- **Step-2 decisions** - identified by the stage's step number, not by anything the caller sends.
+- **Templates that define no step 2** - nothing can strand, so nothing is blocked.
+
+Verified by replaying **6,000 real approvals** against a local copy of prod: 4,209 normal approvals
+and 1,786 MR/MA auto-approvals allowed, only the genuinely stranded orders blocked. Compass Canada:
+760 approvals, **none** blocked.
+
+**⚠ The guard does nothing until its interceptor row exists.** A `prePost` only runs when a
+matching `ApiPayloadInterceptors` row is registered, and `recordId 179` (approval-decisions) carried
+only PRE/PUT, POST/PUT and POST/POST - a newly added `prePost` is **dead code with no error**.
+`dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql` (and the
+`Client_CompassCanada` twin) insert the PRE/POST row, guarded with `NOT EXISTS` so they are safe to
+re-run. **Run both, then deploy api2** - otherwise nothing changes. Mechanics:
+[API Payload Interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md).
+
 ### Manager reassignment and the notification list
 When a step-2 (Manager) approval decision is **reassigned** to a new manager,
 `_swapManagerEmailAddress()` updates the order's CC/notification list in `SalesOrderEmailAddresses`:
@@ -436,7 +469,56 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   could not open the order from the "Manager Approval Needed" email, so admin Kai Wong had to
   approve as manager on his behalf. (Fixed 2026-07-23.)
 
+- **⚠ An exemption from a server-side guard must be decided from the DATABASE, never from a
+  client-supplied field.** The step-1 guard above originally skipped itself when the request payload
+  carried `approvalDecisionType` / `approvalDecisionTypeId`, treated as a "this is a system
+  auto-approval" marker. That value comes from the **request body**, so any caller could set it and
+  skip the check entirely. The early return and its `_isSystemAutoApproval` helper were removed in
+  PR review. Checked against prod before removing: all **5,028** step-1 auto-approvals in Compass
+  history are MR/MA orders (Canada has none), so the DB-backed order-number check covers every real
+  case, and VIP auto-approvals land on **step 2** and exit at the step check. Treat this as the
+  general rule for any guard added here.
+- **⚠ The green approve tick used to silently replace the step-2 manager with the approver.**
+  `makeApprovalDecision()` / `updateApprovalDecision()` in supply hardcoded
+  `assignedToUserId: { uuid: userUuid }` into every single-stage approve payload, so an admin
+  approving the manager stage **overwrote the real manager with themselves** - and the order
+  timeline then read "Manager Approved", making it look like the manager had acted. Confirmed on
+  **SA136901** (07:18:35 re-sent an assignee that had not changed; Dawn Anderson had already been
+  assigned by Emily at 06:50:06), and it also hit **SA136807** (Angel Almodovar replaced) and
+  **SA137080** (delegate manager Daniel Mezzanares replaced). Fixed front-end by removing the field
+  - `decidedByUserId` already records who approved. The "Approve All Stages" path was always
+  correct, which is why the bug never reproduced there. Detail:
+  [Record Modals & Nested Tables](../../../2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md).
+- **⚠ A manager swap sent in the SAME save as an approval is never logged, and the email list
+  keeps the old manager.** `_evaluateManagerVip()` returns immediately when the request carries
+  `isApproved`, on the assumption that a request is *either* an assignment *or* an approval. When
+  both arrive together the `"Manager reassigned"` note is skipped (the feature itself works - it has
+  fired **757** times since May) **and** so is the `SalesOrderEmailAddresses` swap, so the outgoing
+  manager stays on the notification list. A handler for the combined case was drafted on the
+  `_sandbox-client` branch only and is **NOT** on `TRUE-81900` - known gap, not shipped.
+- **The upstream cause of an unassigned step 2 is a user saved with no `supervisorUserId`.** The
+  admin add-user screen allows saving a user without one, and the PEOPLE-file import may or may not
+  backfill it later. That one data hole feeds both the `!$hasManager` wipe above and the
+  never-created step-2 decision at order creation. **Not fixed** - the guard only stops the order
+  being *stranded*, it does not give it a manager.
+
 ## Change history
+- 2026-09-11 - **Blocked step-1 approval when step 2 has no assignee** (`prePost()` + extended
+  `prePut()` on `_Model_Compass_ApprovalDecision`, `_Exception_Validation` -> HTTP 400), after four
+  prod orders (SA136795, SA137088, SA137146, SA137235) sat in *Pending Approval* assigned to nobody
+  with no email sent and no report surfacing them. Exemptions are **all DB-derived** - MR/MA by
+  `SalesOrders.number` prefix, step-2 decisions by step number, templates with no step 2 - after PR
+  review **removed a client-controlled bypass** that skipped the guard whenever the request payload
+  carried `approvalDecisionType`/`approvalDecisionTypeId` (prod check: all 5,028 historic step-1
+  auto-approvals are MR/MA, Canada none). Verified by replaying 6,000 real approvals from a local
+  prod copy (4,209 normal + 1,786 MR/MA allowed; Canada 760, none blocked). Also recorded: the green
+  approve tick was **overwriting the step-2 manager with the approver** (SA136901 / SA136807 /
+  SA137080) until `assignedToUserId` was removed from the single-stage payload, and that
+  `_evaluateManagerVip()` skips both the "Manager reassigned" note and the
+  `SalesOrderEmailAddresses` swap when an assignment and an approval arrive in one save (drafted on
+  `_sandbox-client` only, **not shipped**). Ticket TRUE-81900. **NOT DEPLOYED** - the `2026-09-10b`
+  interceptor SQL must run on `Client_Compass` **and** `Client_CompassCanada`, and api2 must be
+  deployed, before the guard does anything. (bala)
 - 2026-08-31 — **Root-caused the "decided but untyped" step-2 approvals that no admin can recover**
   (both tenants, via the shared parent). `_Model_Compass_SalesOrder::postPut`'s `!$hasManager` branch
   nulls the entire step-2 decision when the "Order for" contact has no `supervisorUserId`; a

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/knowledge/clients/nychh/features/transfer-order-netsuite-push.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-14
 owners: ["bala"]
 files:
   - _underscore/Model/Client/TransferOrder.php
@@ -33,7 +33,13 @@ and live in
 this doc holds the NYCHH-specific parts: the interceptor row, the **location → mapping-column
 roles** (verified in production), and the data/metadata state the push still needs.
 
-**LIVE since 2026-09-08.** NetSuite SO **289187** (internal id 7463537) was created from this path
+**LIVE since 2026-09-08, fully working since 2026-09-14.** Between 2026-09-09 and 2026-09-14 **every**
+transfer order failed on a NetSuite tax error caused by customer **28908**'s data — see
+[the tax item section](#-customer-28908-was-stuck-on-tax-group--8-and-it-blocked-every-transfer) —
+and before that, every order shipped to the wrong hospital. Both are now fixed and the push was
+confirmed working by the developer.
+
+NetSuite SO **289187** (internal id 7463537) was created from this path
 and is correct. The location-role table below still stands, but **the destination location is NOT
 the NetSuite customer** — that was corrected the same day; see the next section.
 
@@ -118,6 +124,34 @@ rows for records 69, 12, 23, `NOT EXISTS`-guarded). **Run on prod and verified:
 > Generalised on [nested FK ACL embedding](../../../2.0/apps/api2/features/nested-fk-acl-embedding.md):
 > deepening a `depth` is an ACL change, and the branch is dropped **silently**.
 
+## ⚠ Customer 28908 was stuck on tax group -8, and it blocked every transfer
+
+From **2026-09-09** (the day the push started sending a ship-to address) to **2026-09-14**, every
+NYCHH transfer order create returned NetSuite HTTP **400**:
+
+```
+Error while accessing a resource. Invalid shippingtaxcode reference key -8 for subsidiary 1.
+```
+
+`Core.WorkerJobs` ids **1534082, 1534805, 1535235, 1536824, 1536920**.
+
+**It was NetSuite customer data, not Toga code.** Customer **28908** (NYC Health + Hospitals — the
+client-level customer from `Core.Clients.netsuiteCustomerInternalId`, which every NYCHH transfer order
+uses) still carried the retired tax group **-8** as its `taxitem`. An inline ship-to address makes
+NetSuite rebuild the address on the order and re-check the shipping tax code against subsidiary 1,
+and -8 fails that check.
+
+**Fix: NetSuite ops changed 28908's `taxitem` from -8 to 5050 (AVATAX).** Verified working the same
+day. 7151 of subsidiary 1's customers were already on 5050.
+
+**Still on -8 inside NYCHH: sub-customer 31584 "Coney Island"** (present in `Client_Nychh.Customers`,
+0 sales orders today, so dormant). All **17** other NetSuite customer ids used by `Client_Nychh` are
+on 5050. The mechanism, the failed workarounds, and the cross-client -8 list are on
+[the shared push doc](../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md).
+
+> **Do not try to fix this from supply.** The customer is always the client (28908), so **changing the
+> destination location cannot change the NetSuite customer** — it only changes the ship-to address.
+
 ## Where the ship-to address comes from — and the location-2 problem
 
 The address is the **destination Location's** `primaryLocationAddress.address`. Until 2026-09-09 all
@@ -130,6 +164,21 @@ are in [location shipping addresses + delivery contacts](./location-shipping-add
 delivery site for that location — and location 2 is the destination on the large majority of NYCHH
 transfer orders. Any transfer order to location 2 will ship to Jacobi.
 
+### What "no address" actually did — 5 of 6 orders went to the wrong hospital
+
+Customer **28908** holds **124** saved addresses, and the one flagged `defaultshipping = T` is
+**“NYCHHC Jacobi Dental”** (address id **6568575**, 1400 Pelham Parkway South, Bronx NY 10461). With
+no address in the payload NetSuite used that one **silently** on every order:
+
+| NetSuite order | Ship-to |
+|---|---|
+| 7453238, 7462009, 7463537, 7467799, 7482373 | **wrong** — Jacobi Dental, whatever the real destination |
+| 7462031 | correct, **by accident** — it predates the switch to the parent customer and was built on destination sub-customer **33674**, whose own default *is* the destination |
+
+The line-level `location` does **not** rescue this: that is the **source** warehouse (NetSuite
+internal id **117**) and NetSuite never uses it for delivery. So dropping the address to get past a
+400 is a wrong-address bug, not a fix.
+
 ## Interceptor registration — record 312, and the deploy order matters
 
 `dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql` inserts into
@@ -164,6 +213,19 @@ switch that turns the feature on for NYCHH and nobody else.
 
 ## Change history
 
+- 2026-09-14 — **Push deployed and confirmed working; the blocker was NetSuite customer 28908's tax
+  item.** Every transfer order from 2026-09-09 failed with *"Invalid shippingtaxcode reference key -8
+  for subsidiary 1"* (`Core.WorkerJobs` 1534082, 1534805, 1535235, 1536824, 1536920) because 28908
+  still carried the retired tax group **-8**; sending an inline ship-to address makes NetSuite
+  re-check the shipping tax code against subsidiary 1. **NetSuite ops moved 28908 to 5050 (AVATAX)**
+  and the push worked with no code change. Confirmed the customer is always 28908, so a destination
+  change in supply cannot work around a customer-level problem. Quantified the old no-address
+  behaviour: 28908 has **124** addresses and its `defaultshipping` entry is **Jacobi Dental (id
+  6568575)**, which is why **5 of the 6** orders that reached NetSuite (7453238, 7462009, 7463537,
+  7467799, 7482373) shipped to the wrong hospital — only 7462031 was right, and only because it was
+  built on sub-customer 33674 before the switch to the parent. Remaining NYCHH exposure: sub-customer
+  **31584 Coney Island** is still on -8 but dormant; the other 17 NetSuite customer ids used by
+  `Client_Nychh` are all on 5050. (bala)
 - 2026-09-09 — **The push had never sent a shipping address**, so NetSuite used customer 28908's
   default site on every order: NetSuite order **7467799** was for North Central Bronx yet shipped to
   Jacobi's *1400 Pelham Parkway South*, and SO **289187** (Woodhull) shows the same. The fix reads the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.806",
+  "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",