toga-ai 1.0.166 → 1.0.168

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |

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

@@ -0,0 +1,107 @@
+---
+title: ACL Permission Chain (Record & Field Authorization)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["jcardinal"]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Core/Page.php
+  - dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql
+  - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
+---
+
+## Summary
+
+Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete
+a record is decided by rows across **four linked tables**, not by code. Granting access by
+inserting only an `AclRecordPermissions` row is the single most common mistake — the permission
+silently does nothing without the rest of the chain. A complete grant requires **all four** tables,
+plus `AclFieldPermissions` for the fields to be readable/writable.
+
+## The complete chain (all four are required)
+
+```
+AclRecordPermissions   →  AclLogicGroups   →  AclLogicGroupExpressions  →  AclRecordExpressions
+  (the role × record       (operator AND/OR,     (binds a group to an          (the SQL test,
+   CRUD grant)              parent group tree)     expression)                   e.g. '1' = all)
+```
+
+1. **`AclRecordPermissions`** — the grant: `recordId`, `roleId`, `allowCreate/Read/Update/Delete`
+   (optional `appId`, `indirectRecordId`). Unique on `(appId, recordId, roleId, indirectRecordId)`.
+2. **`AclLogicGroups`** — at least one root group per permission: `aclRecordPermissionId` (FK),
+   `operator` **`enum('AND','OR') NOT NULL`** (this column is mandatory and easy to forget),
+   optional `parentAclLogicGroupId` for nested groups.
+3. **`AclLogicGroupExpressions`** — binds a logic group to a record expression: `aclLogicGroupId`
+   (FK), `aclRecordExpressionId` (FK). Unique on `(aclLogicGroupId, aclRecordExpressionId)`.
+4. **`AclRecordExpressions`** — the actual SQL test: `recordId`, `slug`, `description`,
+   `sqlExpression` (TEXT). Unique on `(recordId, slug)`. The conventional "always allow" row is
+   `slug = 'all'`, `sqlExpression = '1'`.
+
+**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 omitted from responses (and rejected on write).
+
+## Where ACL rows live: Core vs. Client database
+
+`Core.Records.aclDatabase` decides which database holds the ACL rows for that record:
+
+- **`aclDatabase = 'CORE'`** → ACL rows live in the **Core** database.
+- **`aclDatabase = 'CLIENT'`** → ACL rows live in **each client's own database**. A migration
+  granting access therefore goes in `dbchanges2/Client/` (or a specific `Client_<Name>/`) so it
+  runs against every client DB.
+
+**Role ids differ per client DB**, so never hardcode a `roleId` in a `CLIENT` ACL migration —
+resolve it with a subselect, e.g. the Base role:
+
+```sql
+roleId = (SELECT id FROM Roles WHERE `name` = 'Base')
+```
+
+## Canonical example (grant the Base role full CRUD on a record)
+
+```sql
+INSERT INTO AclRecordPermissions SET
+	uuid = '…', recordId = 331, roleId = (SELECT id FROM Roles WHERE `name` = 'Base'),
+	allowCreate = 1, allowRead = 1, allowUpdate = 1, allowDelete = 1;
+
+INSERT INTO AclRecordExpressions SET
+	uuid = '…', recordId = 331, slug = 'all', description = 'All', sqlExpression = '1';
+
+INSERT INTO AclLogicGroups SET
+	uuid = '…', aclRecordPermissionId = (SELECT MAX(id) FROM AclRecordPermissions), operator = 'AND';
+
+INSERT INTO AclLogicGroupExpressions SET
+	uuid = '…', aclLogicGroupId = (SELECT MAX(id) FROM AclLogicGroups),
+	aclRecordExpressionId = (SELECT id FROM AclRecordExpressions WHERE recordId = 331 AND slug = 'all');
+
+-- and one AclFieldPermissions row per exposed field (recordFieldId, roleId, isWritable)
+```
+
+## How it is enforced
+
+`_Component_Api_V2::buildLookups()` bulk-loads these tables (from the Core and/or Client ACL
+database per `Records.aclDatabase`) into in-memory lookups once per request; `processRoutePairs()`
+then checks the caller's roles against `AclRecordPermissions` (→ `EZ-1` if no grant) and computes
+readable/writable fields from `AclFieldPermissions`. `_Model_Core_Page::meta()` reads the same
+tables to return per-page ACL to the frontend.
+
+## Checklist (so the chain is never half-built)
+
+- [ ] `AclRecordPermissions` row for the role × record with the right CRUD flags.
+- [ ] `AclRecordExpressions` row (`slug='all'`, `sqlExpression='1'` for unconditional access).
+- [ ] `AclLogicGroups` row with `operator` set (AND/OR) referencing the permission.
+- [ ] `AclLogicGroupExpressions` row binding the group to the expression.
+- [ ] `AclFieldPermissions` rows for every field that must be readable/writable.
+- [ ] For `aclDatabase = 'CLIENT'` records: rows go in client DB(s); resolve `roleId` by subselect.
+
+## Change history
+
+- **2026-06-23** — Documented after repeatedly missing the logic-group/expression rows when
+  granting access to new records. Created alongside the `item-translations` record (331) ACL,
+  whose grant in `dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql` is a worked example of
+  the full chain for a `CLIENT`-aclDatabase record targeting the Base role.

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -2,5 +2,8 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
+| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx |
+| [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |

package/knowledge/2.0/apps/toga2-commerce/architecture.md

@@ -0,0 +1,246 @@
+---
+title: TOGa Commerce (toga2-commerce / commerce2-react) Architecture
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: architecture
+status: active
+updated: 2026-06-23
+owners: ["apeterson"]
+files:
+  - src/main.tsx
+  - src/App.tsx
+  - src/routes.tsx
+  - src/contexts/AuthContext.tsx
+  - src/contexts/helpers/getLoginSettings.ts
+  - src/api/axiosInstance.ts
+  - src/stores/
+  - src/themeConfig/ThemeContext.tsx
+  - src/fieldsConfig/index.ts
+  - src/hooks/useAssignClientFields.ts
+  - vite.config.ts
+  - package.json
+related:
+  - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/workflows/amplify-build-and-deploy.md
+  - 2.0/apps/api2/architecture.md
+---
+
+## Summary
+
+`toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the
+customer-facing **B2B commerce storefront** of the 2.0 platform. It is a **React 18 + TypeScript +
+Vite 5 single-page app** styled with **Tailwind**, and it is the React front end in the 2.0
+"decoupled" architecture: it talks to **`api2`** (the TOGa v2 JSON API) for all data, and renders
+nothing server-side.
+
+It is **multi-tenant**: a single codebase serves several clients (currently **COMPASS**,
+**COMPASSCANADA**, **QUAD**, plus a **DEFAULT** fallback). The tenant is resolved at runtime from
+the **hostname** and drives three independent systems — the API base URL, the theme, and the
+per-tenant field/content config. See [multi-tenant-theming](features/multi-tenant-theming.md) and
+[client-fields](features/client-fields.md) for those subsystems in depth.
+
+> Note: this is a **2.0 *app* with no PHP**. Its registry `dependsOn` is `api2`; it consumes the
+> `_underscore`/`api2` backend over HTTP but contains no framework PHP classes itself.
+
+## Tech stack (verified versions, package.json)
+
+| Concern | Library | Version |
+|---|---|---|
+| UI | react / react-dom | ^18.3.1 |
+| Routing | react-router-dom | ^7.5.1 |
+| Server state / cache | @tanstack/react-query (+ persist-client, sync-storage-persister) | ^5.59.19 |
+| Client state | zustand | ^4.5.4 |
+| HTTP | axios | 1.7.7 |
+| Forms | react-hook-form | ^7.53.1 |
+| Animation | framer-motion | ^11.0.18 |
+| Styling | tailwindcss | ^3.4.4 |
+| Errors / monitoring | @sentry/react | ^8.50.0 |
+| Build / tooling | vite ^5.4.10, typescript ^5.8.2 |
+| Tables | @tanstack/react-table, react-table (v7), react-table-sticky |
+| Misc | dayjs, react-select, nouislider, classnames, uuid, react-lottie, @agilant/toga-blox, FontAwesome Pro |
+
+E2E tests use **Cypress** (`cypress/`, `cypress.config.ts`).
+
+## Bootstrap & provider stack
+
+- `src/main.tsx` — initializes **Sentry** (browser tracing + replay) and mounts `<App/>` in React
+  `StrictMode`; imports global CSS.
+- `src/App.tsx` — creates a single `QueryClient` (default `staleTime: 24h`) and a
+  `createSyncStoragePersister` (localStorage key **`"commerce"`**). Provider nesting, **outermost → innermost**:
+
+  ```
+  PersistQueryClientProvider (client=queryClient, persister → localStorage "commerce")
+    └─ AuthProvider            (contexts/AuthContext.tsx — auth state, tenant/login resolution)
+        └─ ThemeProvider       (themeConfig/ThemeContext.tsx — CSS-variable theming)
+            └─ ToasterProvider (contexts/ToasterContext.tsx — toast notifications)
+                └─ RouterProvider (routes.tsx)
+    + ReactQueryDevtools (initialIsOpen=false)
+  ```
+
+  `App` also runs a mount effect managing **edit-order mode**: it reads a `localStorage.synced`
+  flag and calls `exitEditOrderModeGlobalSyncReset()` when an edit-order session was abandoned
+  outside `/cart`, and subscribes to `useReturnOriginalUserFromViewAsStore` (the "view-as" feature).
+
+> The cache is **persisted**: query results survive refreshes via `PersistQueryClientProvider`.
+> Combined with the 24h default `staleTime`, catalog data is aggressively cached — invalidate
+> deliberately with `queryClient.invalidateQueries(...)` when freshness matters.
+
+## Routing (`src/routes.tsx`, createBrowserRouter)
+
+Public:
+- `/` → `AuthRedirect` (→ `/home` if authenticated, else renders nothing while the auth flow runs)
+- `/login` → `LoginRoute` (→ `/home` if already authenticated, else `<Login/>`)
+- `/reset-password` → `ResetPasswordPage`
+
+Authenticated (wrapped by `PrivateRoute` → `AuthLayout`):
+- `/home`, `/bundle-view`, `/filter`, `/cart`, `/get-support`, `/account`, `/item-view`,
+  `/order-details`, `/privacy-policy`, `/terms-conditions`; unmatched → `Navigate to="/home"`.
+
+Mechanics:
+- **`PrivateRoute`** gates on `useAuth().isAuthenticated` + `useAuthenticationFlow().isLoading`;
+  shows an `AuthLoading` spinner while loading, redirects to `/login` if unauthenticated.
+- **`AuthLayout`** wraps every authenticated route and **stays mounted across route changes**
+  (header, footer, nav, notifications live here). Its `errorElement` renders `<ErrorMessage errorType={500}/>`.
+  ⚠️ Because it never remounts, React Query `refetchOnMount` only fires **once per session** for
+  queries owned by AuthLayout — route-change refreshes must be wired explicitly (e.g. the
+  notifications query invalidates on route change keyed on `user?.uuid`).
+- Routes are **statically imported** (no `React.lazy`); Vite handles chunking at build time.
+
+## Page architecture — MVVM convention
+
+Every page under `src/pages/<Page>/` follows the same shape (View ← ViewModel ← API ← FIELDS):
+
+```
+src/pages/<Page>/
+├── <Page>Page.tsx / index.ts   # View — layout & rendering only
+├── types.ts                    # page-local TS types
+├── view/                       # sub-components, modals, loading skeletons
+├── viewModel/
+│   ├── use<Page>ViewModel.ts   # state + React Query hooks + business logic
+│   ├── index.ts
+│   └── FIELDS/<CLIENT>/[<LANGUAGE>/][<ROLE>/]*.json|*.ts   # per-tenant content/config
+├── api/<Page>Api.ts            # axios calls for this page
+├── hooks/                      # page-scoped hooks
+└── helpers/                    # pure compute/format helpers
+```
+
+Pages: `Account, BundleView, Cart, Filter, GetSupport, Home, ItemsView, Login, OrderDetails,
+PrivacyPolicy, ResetPassword, TermsConditions`. The **ViewModel hook is the seam**: it calls
+`useAssignClientFields(fieldKey, language, user)` to load the right tenant/role/language content,
+runs the page's queries, and returns ready-to-render data to the View. (See client-fields doc.)
+
+## State management
+
+### Zustand stores (`src/stores/`)
+Most use the `persist` middleware (localStorage). Verified files:
+
+| Store | Responsibility |
+|---|---|
+| `useUserStore` | Logged-in user (persona ids, role flags, currency) |
+| `useCartStoreZu` | Cart items + bundles, per-item quantity-change loading |
+| `useCartSalesQuoteZu` | Active sales order (ship-to, contact, cost center, notes, emails) |
+| `useCartOverlayZu` | Cart preview overlay state |
+| `useEditOrderZu` | "Edit existing order" mode flag + original snapshot |
+| `useEditOrderUuidStore` | UUID of the order being edited |
+| `useSelectedUserZu` | "Order for" user selected in cart |
+| `useReturnOriginalUserFromViewAsStore` | "View as another user" return-to-self tracking |
+| `useEmailOptionsStore` | Notification CC email options (see cart-notification-emails) |
+| `useBundleBuilderZu` | Bundle-builder wizard selections |
+| `useFieldsStore` | **`fieldKey` (tenant) + `language`** — drives field/theme resolution (persist key `fields-key`) |
+| `useSettingsModalStore` | Login/settings modal open flag |
+| `useSettingsErrorStore` | Settings validation errors (suppresses data queries when set) |
+
+### React Query (`src/queries/`, `src/hooks/useApiQuery.ts`, `useApiMutation.ts`)
+- Global default `staleTime` 24h; per-query overrides (user/persona data fetched fresh on login).
+- Cache persisted to localStorage (`"commerce"`); rehydrated on load.
+- Page queries are typically `enabled` on `isAuthenticated && user?.uuid && !settingsModalEnabled`.
+
+**Two-layer state model:** React Query owns *server* state (catalog, orders, user); Zustand owns
+*local* state (cart, selected user, edit mode, tenant/language). The cart is synced to the backend
+sales order via `src/api/syncSalesOrder*.ts` helpers.
+
+## API layer (`src/api/`)
+
+`src/api/axiosInstance.ts` is the shared client. Key behaviors (all verified):
+- **Base URL by tenant:** `host = "VITE_API_" + window.location.hostname.toUpperCase().split(".")[0]`;
+  `baseURL = import.meta.env[host] || import.meta.env.VITE_API`. So `compass.togacommerce` →
+  `VITE_API_COMPASS`, falling back to `VITE_API`. `timeout: 180000`.
+- **Transaction id:** a request interceptor stamps every call with `params.transactionId = uuidv4()`.
+- **Auth token:** a second request interceptor attaches `Authorization: Bearer <token>` — using the
+  stored `accessToken` if a `user` exists in localStorage, otherwise fetching a **public token** via
+  `POST {baseURL}/auth/public`.
+- **1 ms delay interceptor:** a third request interceptor `await delay(1)` before sending.
+- **401 handling:** response interceptor attempts `POST {baseURL}/auth/refresh` (Bearer refresh
+  token) once (`_retry`), retries the original request on success, else calls `performLogout()`
+  (clears all auth + cart + `commerce` cache keys and redirects to `/`).
+- Failures are reported to **Sentry** with `errorType: "API"` tags.
+
+The backend (`api2`) returns the standard 2.0 envelope (`success`/`data`/`errors`; see api2 arch);
+generic CRUD helpers live in `src/api/genericApi.ts` (paginated `getData`, `saveData`, `updateData`,
+`deleteData`, optional `?depth=-1` for nested responses).
+
+## Authentication & roles
+
+- `src/contexts/AuthContext.tsx` derives `host` from the hostname (`hostname.toUpperCase().split(".")[0]`),
+  loads `getClientLoginFields(host)` (tenant config), decides persona-switcher visibility
+  (`determineShouldShowPersonaSwitcher` — QUAD special-cased), then runs
+  `getLoginSettings(...)` which writes `useFieldsStore.fieldKey = host` and the language, and
+  hydrates `useUserStore`.
+- `src/hooks/useAuthenticationFlow.ts` orchestrates the post-login fetch sequence
+  (user data → persona → contact → settings).
+- **Role flags** on the user object are tenant-specific:
+  - COMPASS / COMPASSCANADA → `ADMIN` (`_isAdmin`), `SUPERUSER` (`_isSuperAdmin`),
+    `MANAGER` (`_isSupervisor`), else `USER`.
+  - QUAD → `GLOBALADMIN` (`_isGlobalAdmin`), `BUYER` (`_isBuyer`), `ITSHOPPER` (`_isItShopper`), else `USER`.
+- **Personas:** `user._personaIds` is a colon-delimited string; `getLoginSettings` has special
+  handling collapsing persona-24 cases for non-QUAD tenants.
+
+## Build & deploy
+
+- **Per-tenant dev/build scripts** (`package.json`): `compass`, `compasscanada`, `quad`,
+  `togacommerce` run `vite --mode development --host <tenant>.togacommerce`; production builds are
+  `build` / `buildAlpha` / `buildBeta` / `buildGamma` / `buildQcSecurity` (each installs the matching
+  `@agilant/toga-blox` npm channel, then `tsc` + `vite build --mode <env>`).
+- `vite.config.ts`: React plugin + Sentry Vite plugin (sourcemap upload); dev `server.allowedHosts`
+  = `compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`; PostCSS via
+  `postcss.config.cjs`; `optimizeDeps.include: ["react-router-dom"]`.
+- Local dev requires `*.togacommerce` hostnames to resolve to localhost (hosts file) so tenant
+  resolution works.
+- Deployment runs on **AWS Amplify** — see [amplify-build-and-deploy](workflows/amplify-build-and-deploy.md).
+  A `Dockerfile`/`docker-compose.yml` also exist for containerized dev.
+
+## Directory map (`src/`)
+
+| Path | Purpose |
+|---|---|
+| `main.tsx` / `App.tsx` | bootstrap, Sentry, provider stack |
+| `routes.tsx` | router + route guards |
+| `api/` | axios instance, generic CRUD, sales-order sync helpers |
+| `contexts/` | `AuthContext`, `ToasterContext` (+ `helpers/getLoginSettings.ts`) |
+| `stores/` | Zustand stores (see table) |
+| `queries/` | login/prefetch React Query definitions |
+| `hooks/` | shared hooks (`useAssignClientFields`, `useAuthenticationFlow`, `useApiQuery/Mutation`, `useBreakpoint`, `useDynamicConditionalFieldOptions`, `useCancelEditOrder`) |
+| `pages/` | feature pages (MVVM) |
+| `components/` | shared UI (Base* atoms, `AuthLayout`, `Header`/`Footer`, `ThemeSwitcher`, `BaseDetailField`, guardrails, error messages, address forms, cards) |
+| `themeConfig/` | `themes.json`, `ThemeContext.tsx`, `types.ts` (theming) |
+| `fieldsConfig/` | global per-tenant client config + the master `FIELDS` registry |
+| `styles/`, `fonts/`, `assets/` | global CSS, web fonts, images/SVGs (some per-tenant) |
+| `utils/` | formatting, cart/address/persona helpers, query helpers |
+| `globalTypes.ts` | shared TS types (API envelope, User, Address, Item/Bundle, SalesOrder, …) |
+
+## Gotchas
+
+- **`AuthLayout` never remounts** → `refetchOnMount` fires once per session; wire explicit
+  invalidation for data that must refresh on navigation.
+- **24h `staleTime` + persisted cache** → users can see stale catalog/pricing; invalidate on the
+  events that should bust it.
+- **Tenant resolution depends on the hostname.** On `localhost` with no `*.togacommerce` host the
+  first DNS label won't match a tenant, so config falls back (`getClientLoginFields` → COMPASS,
+  theme → DEFAULT). Use the per-tenant dev scripts.
+- **Theme vs. fields language keys differ** — theme/field *folder* names are uppercase
+  (`COMPASSCANADA`, `ENGLISH`/`FRENCH`) but the runtime `FIELDS` registry keys language as
+  lowercase `en`/`fr`. See the client-fields doc.
+</content>

package/knowledge/2.0/apps/toga2-commerce/features/client-fields.md

@@ -0,0 +1,187 @@
+---
+title: Client Fields — per-tenant / language / role content & config
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["apeterson"]
+files:
+  - src/fieldsConfig/index.ts
+  - src/fieldsConfig/getClientLoginFields.ts
+  - src/fieldsConfig/clientFields/COMPASS.json
+  - src/fieldsConfig/clientFields/COMPASSCANADA.json
+  - src/fieldsConfig/clientFields/QUAD.json
+  - src/hooks/useAssignClientFields.ts
+  - src/hooks/useDynamicConditionalFieldOptions.ts
+  - src/stores/useFieldsStore.ts
+  - src/components/BaseDetailField/BaseDetailField.tsx
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+  - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+---
+
+## Summary
+
+Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. Instead
+each page's labels, field lists, validation, visibility, and static content come from **JSON config
+resolved per tenant, per language, and per role**. There are **two layers**:
+
+- **Layer A — global client config** (`src/fieldsConfig/clientFields/<TENANT>.json`): a small file
+  per tenant controlling the language switcher and which user API fields to fetch at login.
+- **Layer B — the per-page `FIELDS` registry** (`src/fieldsConfig/index.ts` → `FIELDS`): the big
+  `tenant → language → role → page-section` object that every page ViewModel reads.
+
+## Layer A — global client config
+
+`src/fieldsConfig/clientFields/{COMPASS,COMPASSCANADA,QUAD}.json`, each:
+
+```json
+{
+  "languageSwitcher": { "uuid": "1", "isEnabled": true|false },
+  "userApiFields": ["firstName", "lastName", "email", "uuid", "_isAdmin", ...]
+}
+```
+
+- `languageSwitcher.isEnabled` — **only COMPASSCANADA is `true`** (English/French). COMPASS and
+  QUAD are `false`.
+- `userApiFields` — the allow-list of user columns fetched at login; importantly it includes the
+  tenant's **role flags**: COMPASS/COMPASSCANADA carry `_isAdmin`, `_isSupervisor`, `_isSuperAdmin`;
+  QUAD carries `_isGlobalAdmin`, `_isItShopper`, `_isBuyer`. All include `_personaIds`.
+
+Resolved by **`src/fieldsConfig/getClientLoginFields.ts`** — a `switch(client)` returning the JSON;
+**default is `COMPASS`** (not DEFAULT). Called from `AuthContext` as `getClientLoginFields(host)`.
+The `languageSwitcher.isEnabled` value feeds the login-settings branch in `getLoginSettings.ts`.
+
+## Layer B — the per-page FIELDS registry
+
+`src/fieldsConfig/index.ts` (~1100 lines) imports every page's per-tenant field constants (which
+themselves wrap the on-disk JSON under `pages/<Page>/viewModel/FIELDS/...`) and assembles one object:
+
+```ts
+export const FIELDS: Record<string, any> = {
+  COMPASS: {
+    en: {
+      ADMIN:     { HEADERFIELDS, HOMEPAGEFIELDS, ORDERDETAILS, CARTPAGEFIELDS, /* ~20 sections */ },
+      SUPERUSER: { ... },
+      MANAGER:   { ... },
+      USER:      { ... },
+    },
+  },
+  COMPASSCANADA: { en: { ADMIN, SUPERUSER, MANAGER, USER }, fr: { ... } },
+  QUAD: { en: { GLOBALADMIN, BUYER, ITSHOPPER /*, USER */ } },
+};
+```
+
+### Resolution dimensions & order
+
+`FIELDS[ tenant ][ language ][ role ]` → an object of **page-section** constants
+(`HEADERFIELDS`, `HOMEPAGEFIELDS`, `FOOTERFIELDS`, `ITEMSPAGE`, `ORDERDETAILS`, `GETSUPPORTPAGE`,
+`BUNDLEDETAILSPAGE`, `FILTERPAGEFIELDS`, `CARTPAGEFIELDS`, `NEWUSERFORMFIELDS`, `CANTFINDUSERFIELDS`,
+`PRIVACYPOLICYPAGEFIELDS`, `TERMSCONDITIONSPAGEFIELDS`, `ACCOUNTTABFIELDS`, `MYACCOUNTFIELDS`,
+`ORDERHISTORYFIELDS`, `ADD/EDIT/SELECTNEWPRIMARY/SHIPPINGADDRESSESFIELDS`, `CARTOVERLAY`,
+`ERRORFIELDS`, `LOGINSETTINGSFIELDS`, …).
+
+- **Tenant** keys: `COMPASS`, `COMPASSCANADA`, `QUAD`.
+- **Language** keys are **lowercase `en` / `fr`** in the registry. ⚠️ This differs from the on-disk
+  **folder** names, which are uppercase `ENGLISH` / `FRENCH`. Only COMPASSCANADA has `fr`.
+- **Role** keys: COMPASS/COMPASSCANADA → `ADMIN`, `SUPERUSER`, `MANAGER`, `USER`;
+  QUAD → `GLOBALADMIN`, `BUYER`, `ITSHOPPER` (+ `USER`).
+
+On disk the JSON lives at `pages/<Page>/viewModel/FIELDS/<CLIENT>/[<LANGUAGE>/][<ROLE>/]<NAME>FIELDS.json`,
+and **not every page uses every dimension**:
+- Pages with full role split: Home, OrderDetails, BundleView, Filter, Cart, Account.
+- Pages with **no role layer** (role-neutral content): PrivacyPolicy, GetSupport, ItemsView,
+  TermsConditions, ResetPassword (resolved at tenant/language level, shared across roles).
+- Language layer (`ENGLISH`/`FRENCH` folders) only exists for COMPASSCANADA; COMPASS and QUAD put
+  files directly under the tenant (their registry language is `en`).
+
+## The resolver — `useAssignClientFields`
+
+`src/hooks/useAssignClientFields.ts` is called by **every page ViewModel** (and several form
+ViewModels) with `(fieldKey, language, user)`:
+
+```ts
+let role: string;
+if (clientName === "COMPASS" || clientName === "COMPASSCANADA") {
+  if (user?._isAdmin === "1") role = "ADMIN";
+  else if (user?._isSuperAdmin === "1") role = "SUPERUSER";
+  else if (user?._isSupervisor === "1") role = "MANAGER";
+  else role = "USER";
+} else { // QUAD (and any non-Compass tenant)
+  if (user?._isGlobalAdmin === "1") role = "GLOBALADMIN";
+  else if (user?._isBuyer === "1") role = "BUYER";
+  else if (user?._isItShopper === "1") role = "ITSHOPPER";
+  else role = "USER";
+}
+
+// wrapped in React Query, keyed for caching:
+const queryKey = ["clientFields", clientName, language, role];
+const data = FIELDS?.[clientName]?.[language]?.[role] || null;
+```
+
+Inputs:
+- **`clientName`** = `useFieldsStore.fieldKey` (the tenant `host`, set at login — see architecture doc).
+- **`language`** = `useFieldsStore.language` (default `"en"`; set to `"fr"` etc. via `setLanguage`
+  from the login settings switcher or `MySettingsView`).
+- **`user`** = the logged-in user (role flags).
+
+It returns `{ fields, loading, error, resetFieldsMapCache }`; `resetFieldsMapCache` invalidates the
+`["clientFields"]` query (used when role/language/tenant changes mid-session). Page ViewModels then
+pluck the section they need, e.g. `fieldsCall["MYACCOUNTFIELDS"]`.
+
+## What's inside a FIELDS JSON
+
+Shape varies by page, but common forms:
+- **Static content pages** (PrivacyPolicy, TermsConditions, GetSupport): headings + text/HTML blocks
+  (`label` may contain HTML).
+- **Form pages** (ResetPassword, address forms, NewUser): `formFields[]` with
+  `inputType`, `isRequired`, `validationRequirements[]`, labels, placeholders.
+- **Data/detail pages** (Account, OrderDetails): field descriptors mapping data to display, e.g.
+  `{ uuid, label, valueKey, valueType: "currency"|"address"|"status", icon, colSpan, classes }`,
+  plus `pageSettings` (e.g. which API fields to fetch: `fetchUserDataFields`, `fetchUserOrdersDetailsApiFields`).
+
+Common field attributes: `uuid`, `label`, `valueKey` (path into the data object), `inputType`,
+`valueType` (render hint), `colSpan`/`classes` (Tailwind), `isRequired`, `icon`, `options[]`.
+
+## Consumers
+
+- **`src/components/BaseDetailField/`** (`BaseDetailField.tsx`, `renderBaseDetailFieldLabel`,
+  `renderBaseDetailFieldValue`) — generic renderer: takes a field descriptor + data object, applies
+  `valueType` formatting (currency/address/status) and the descriptor's Tailwind classes.
+- **`src/pages/BundleView/hooks/useBundleFields.ts`** — wraps `useAssignClientFields` and reads
+  bundle quantity rules from `BUNDLEDETAILSPAGE.pageSettings`.
+- **`src/hooks/useDynamicConditionalFieldOptions.ts`** — swaps dependent select options at runtime
+  (e.g. state/province options change with the selected country).
+
+## Onboarding / editing fields — practical notes
+
+- **New tenant:** add `clientFields/<TENANT>.json`, a `getClientLoginFields` case, a `<TENANT>`
+  branch in `FIELDS` (with the tenant's role keys), and the per-page `FIELDS/<TENANT>/...` JSON +
+  the corresponding imports in `index.ts`.
+- **New role:** extend the role-derivation in `useAssignClientFields.ts` **and** add the role key
+  under each `FIELDS[tenant][lang]` branch + per-page role folders.
+- **New language:** set `languageSwitcher.isEnabled` in the tenant's `clientFields` JSON, add the
+  `fr`/`xx` branch to `FIELDS[tenant]`, and the `<LANGUAGE>` on-disk folders.
+- **Editing copy:** change the page's `FIELDS/<CLIENT>/[<LANG>/][<ROLE>/]<NAME>FIELDS.json`. Remember
+  to update **all** affected role/language variants — there is no inheritance/fallback between roles.
+
+## Gotchas
+
+- **`en`/`fr` (registry) vs `ENGLISH`/`FRENCH` (folders)** — mismatching these is the classic bug;
+  the runtime lookup uses lowercase.
+- **No fallback** in `FIELDS[client][language][role]` — a missing tenant/role/language combo returns
+  `null` and the page renders empty. Keep all role variants in sync.
+- Role is derived from string `"1"` flags on the user (`user?._isAdmin === "1"`), not booleans.
+- `getClientLoginFields` defaults to **COMPASS** for an unknown host, which can mask a
+  misconfigured tenant in local dev.
+
+## Change history
+- 2026-06-23 — Initial: documented the two-layer field system (global `clientFields/<TENANT>.json`
+  + the per-page `FIELDS` registry), the `tenant→language→role` resolution in `useAssignClientFields`,
+  the `en`/`fr` vs `ENGLISH`/`FRENCH` distinction, role derivation per tenant, and field JSON shapes
+  (apeterson)
+</content>

package/knowledge/2.0/apps/toga2-commerce/features/multi-tenant-theming.md

@@ -0,0 +1,142 @@
+---
+title: Multi-Tenant Resolution & Theming
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["apeterson"]
+files:
+  - src/themeConfig/themes.json
+  - src/themeConfig/ThemeContext.tsx
+  - src/themeConfig/types.ts
+  - src/components/ThemeSwitcher/ThemeSwitcher.tsx
+  - src/components/AuthLayout/AuthLayout.tsx
+  - src/api/axiosInstance.ts
+  - src/contexts/AuthContext.tsx
+  - tailwind.config.js
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+---
+
+## Summary
+
+`toga2-commerce` serves multiple clients from one codebase. A request's **tenant** is derived
+from the **hostname**, and that single tenant string fans out into three independent systems:
+
+1. **API base URL** — `axiosInstance.ts` picks `VITE_API_<TENANT>`.
+2. **Theme** — `ThemeContext` applies the tenant's color set as CSS variables.
+3. **Fields/content** — the per-tenant field config (separate doc: [client-fields](client-fields.md)).
+
+Current tenants: **COMPASS**, **COMPASSCANADA**, **QUAD**, plus a **DEFAULT** fallback theme.
+
+## Tenant resolution — the hostname is the source of truth
+
+The same derivation appears in three places (intentionally — there is no single shared tenant util):
+
+```ts
+const fullHostName = window.location.hostname.toUpperCase(); // "COMPASS.TOGACOMMERCE"
+const host = fullHostName.split(".")[0];                     // "COMPASS"
+```
+
+- **`src/api/axiosInstance.ts`** (lines ~8-11): `const host = "VITE_API_" + hostName[0];`
+  → `baseURL = import.meta.env[host] || import.meta.env.VITE_API`. So the API endpoint is
+  tenant-specific (`VITE_API_COMPASS`, `VITE_API_QUAD`, …) with `VITE_API` as fallback.
+- **`src/contexts/AuthContext.tsx`** (lines ~68-70): derives `host` and uses it for
+  `getClientLoginFields(host)`, persona-switcher logic, and to set `fieldKey` (see below).
+- **`src/themeConfig/ThemeContext.tsx`** (lines ~13-15): derives `host` as the **default** theme key.
+
+This is why the per-tenant **dev scripts** matter: `npm run compass` runs
+`vite --host compass.togacommerce`, and `vite.config.ts` `server.allowedHosts` permits
+`compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce`. Plain `localhost`
+won't match a tenant, so it falls back (theme → DEFAULT, fields → COMPASS).
+
+### From hostname to active theme — `fieldKey` is the real trigger
+
+The theme is **not** applied directly from the raw hostname at mount. The chain is:
+
+1. On login, `AuthContext` → `getLoginSettings(...)` writes `useFieldsStore.fieldKey = host`.
+2. **`src/components/AuthLayout/AuthLayout.tsx`** runs:
+   ```ts
+   const { theme, loadThemeForClient } = useThemeContext();
+   useEffect(() => { loadThemeForClient(fieldKey); }, [fieldKey, loadThemeForClient]);
+   ```
+   So whenever `fieldKey` resolves, the matching theme loads.
+3. **On first mount**, `ThemeProvider` loads `localStorage["current-client-id"]` (set by a prior
+   `loadThemeForClient`) or **`"DEFAULT"`** — not the hostname — so the very first paint before
+   login uses the last-saved or default theme.
+
+## Theme config & data shape
+
+- **`src/themeConfig/themes.json`** — top-level keys `DEFAULT`, `COMPASS`, `COMPASSCANADA`, `QUAD`.
+  Each entry: `{ id, name, colors: {...} }`.
+- **`src/themeConfig/types.ts`** (`ClientTheme`) — the `colors` object is the only themed data.
+  Token groups (each typically with `default/hover/disabled/active` states, some with `bg-`,
+  `text-`, `border-`, `icon-` prefixes):
+  - `primary` (a numeric color scale, e.g. `50`/`500`/`900`)
+  - `btn` (`primary`, `tertiary`), `btn-nav`, `btn-nav-badge`, `btn-tabView-alt1`
+  - `input`, `checkBox`, `tile`, `text` (`body-primary`/`secondary`/`tertiary`)
+
+> The theme controls **colors only**. Fonts, spacing, etc. are global Tailwind config / `@font-face`
+> in `src/fonts/`, not per-tenant theme data.
+
+## How the theme is applied — CSS variables on `<html>`
+
+`ThemeContext.applyThemeToDOM` recursively flattens `themeData.colors` into CSS custom properties
+on `document.documentElement`:
+
+```ts
+// leaf string → root.style.setProperty(`--${prefix}-${key}`, value)
+// nested object → recurse with prefix `${prefix}-${key}`
+applyNestedColors(themeData.colors, "color");
+```
+
+So `colors.btn.primary["bg-default"]` becomes `--color-btn-primary-bg-default`. **`tailwind.config.js`**
+maps semantic color tokens to these variables (`var(--color-...)`), so components style with normal
+Tailwind classes and automatically pick up the active tenant's palette. `loadThemeForClient` also
+persists the chosen key to `localStorage["current-client-id"]`.
+
+## ThemeSwitcher
+
+`src/components/ThemeSwitcher/ThemeSwitcher.tsx` is a manual `<select>` over `availableThemes`
+(from `Object.values(themes.json)`) calling `loadThemeForClient(e.target.value)`. It's an override
+/ dev-testing affordance for previewing tenants — normal users get their theme from `fieldKey`.
+
+## Per-tenant assets
+
+Logos and some imagery are **hard-coded imports with conditional rendering** keyed on `theme?.id`
+(e.g. AuthLayout selects the QUAD logo vs. the Compass logo). They are not part of `themes.json`.
+
+## Onboarding a new tenant — checklist
+
+1. **Theme** — add a new top-level key to `src/themeConfig/themes.json` with the full `colors` set
+   (copy DEFAULT/COMPASS and recolor); confirm `tailwind.config.js` tokens cover any new groups.
+2. **API env** — add `VITE_API_<TENANT>` to the `.env.<mode>` files (else it falls back to `VITE_API`).
+3. **Dev script + allowedHosts** — add `"<tenant>": "vite --mode development --host <tenant>.togacommerce"`
+   to `package.json` and `<tenant>.togacommerce` to `vite.config.ts` `server.allowedHosts`; add the
+   host to the local hosts file.
+4. **Client login config** — add `src/fieldsConfig/clientFields/<TENANT>.json` and a `case` in
+   `src/fieldsConfig/getClientLoginFields.ts` (see client-fields doc).
+5. **Fields** — add the `<TENANT>` branch to the master `FIELDS` registry and the per-page
+   `FIELDS/<TENANT>/...` JSON (see client-fields doc).
+6. **Roles** — if the tenant's role flags differ from COMPASS/QUAD, extend the role-derivation
+   in `src/hooks/useAssignClientFields.ts` and `AuthContext`'s persona logic.
+7. **Assets** — add tenant logos and wire the conditional `theme?.id` rendering.
+
+## Gotchas
+
+- Tenant detection is **hostname-only** — there is no env-var or build-flag override of the tenant
+  at runtime. Wrong host = wrong tenant.
+- The theme's first paint uses `localStorage["current-client-id"]` or DEFAULT, *then* corrects to
+  `fieldKey` once `AuthLayout` mounts — expect a brief default-themed flash pre-login.
+- Adding a color token group to `themes.json` does nothing visually unless `tailwind.config.js`
+  references the corresponding `--color-*` variable.
+
+## Change history
+- 2026-06-23 — Initial: documented hostname→tenant resolution (axios/AuthContext/ThemeContext),
+  `fieldKey`-driven theme application via AuthLayout, CSS-variable flattening of `themes.json` colors,
+  ThemeSwitcher, and the new-tenant onboarding checklist (apeterson)
+</content>

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

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php |
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
+| [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |

package/knowledge/2.0/apps/worker2/features/clickup-work-type-automation.md

@@ -0,0 +1,80 @@
+---
+title: ClickUp Work Type Automation (Committed / Conditional / Stretch)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["jcardinal"]
+files:
+  - worker2/Worker/Clickup.php
+  - worker2/Tests/Worker/ClickupWorkTypeTest.php
+related:
+  - ./clickup-project-routing.md
+---
+
+## Summary
+The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work
+Type** custom field — `Committed`, `Conditional`, or `Stretch` — based on the task's
+dependencies, its status, and its due date. The core rule: a task that should be Committed is
+demoted to **Conditional** while it still has an unfinished dependency, and promoted back to
+**Committed** once all its dependencies are complete. The logic lives in
+`updateTaskAndDependencies()`.
+
+## Key files / entry points
+- `Worker/Clickup.php` → `Webhook($payload, $headers)` — webhook entry; routes by
+  `$payload->event`.
+- `updateTaskAndDependencies($taskId, $dependsOnTaskId = null)` — the work-type engine.
+- `getWorkType($taskDetails)` — reads the current Work Type custom field value.
+- `isStatusComplete(string $statusType): bool` — true when a ClickUp status type is terminal.
+- `getTaskDetails($taskId)` — cached `GET /task/{id}` (static per-invocation cache).
+
+## How it works
+1. A ClickUp webhook hits the worker; `Webhook()` switches on `$payload->event`.
+2. `updateTaskAndDependencies()` is invoked from the `taskCreated`, `taskUpdated`, and
+   `taskStatusUpdated` events. For `taskStatusUpdated` the call is **gated to terminal
+   statuses** (`isStatusComplete()`) so the dependent re-evaluation cascade only runs when a
+   task actually completes — not on every status change.
+3. For the task, it builds `$waitingOn` — the list of dependencies (`$dependency->task_id ==
+   $taskId`) whose status is **not** complete. A dependency counts as complete when its status
+   `type` is one of `COMPLETE_STATUS_TYPES` (`done` **or** `closed`).
+4. It also computes `$isStalledTask` (status in `on hold` / `awaiting client` / `roadblocked`).
+5. Decision:
+   - `Committed` + (`$waitingOn` non-empty OR stalled) → set **Conditional** (+ comment).
+   - `Conditional` + `$waitingOn` empty + not stalled → set **Committed** (+ comment).
+   - `Stretch` with a due date inside the current sprint → set Committed/Conditional as above.
+6. When a task is depended on by another (`$dependency->depends_on == $taskId`), it recurses
+   into the blocking direction so completing a task re-evaluates the tasks it was blocking. The
+   `$dependsOnTaskId` argument breaks two-node cycles.
+
+## Data model
+Reads/writes the `Team` database (`Tasks`, `Developers`, `Tasks_Developers`, `Sprints`) and the
+ClickUp REST API. The Work Type itself lives in ClickUp as a custom field
+(`CLICK_UP_CUSTOM_FIELD_ID__WORKTYPE`), not in the DB.
+
+## Client variations
+None — internal team/sprint tooling, uniform across clients.
+
+## Gotchas / known issues
+- **Two terminal status types.** ClickUp has both `done` and `closed` terminal status types. A
+  completed dependency may be `closed`, not `done`. The completion check must treat **both** as
+  finished — see `COMPLETE_STATUS_TYPES`. Checking only `== 'done'` leaves dependents stuck on
+  Conditional after their blocker is closed.
+- **Status changes must trigger re-evaluation.** A dependency completing fires
+  `taskStatusUpdated` on the *dependency*, not the blocked task. The `taskStatusUpdated` case
+  must call `updateTaskAndDependencies()` (it recurses into dependents) or the auto-promotion
+  back to Committed never fires on its own.
+- **No PHPUnit harness** in worker2. The regression test
+  `Tests/Worker/ClickupWorkTypeTest.php` is a plain-PHP script (reflection on
+  `isStatusComplete`) run with `php Tests/Worker/ClickupWorkTypeTest.php`.
+
+## Change history
+- 2026-06-23 — Fixed dependents staying Conditional after a blocker completed: completion check
+  now treats `closed` as terminal alongside `done`, and `taskStatusUpdated` re-evaluates
+  dependents (gated to terminal statuses). Added `COMPLETE_STATUS_TYPES`, `isStatusComplete()`,
+  and a plain-PHP regression test. (jcardinal)
+
+## Related docs
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md)

package/knowledge/INDEX.md

@@ -15,8 +15,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 10 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 9 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 10 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
@@ -26,7 +26,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 5 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 

package/package.json

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