toga-ai 1.0.509 → 1.0.511

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

@@ -2,7 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md, tools/assets/css/theme.css, tools/assets/js/theme.js |
 | [ClickUp Sprint Dashboard (tools /clickup/react)](features/clickup-sprint-dashboard.md) | A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/clickup/react`, built for a wall-mounted **TV display** ("TOGa IQ" internal sprint metri | tools/_/app/clickup/sprint.php, tools/v2/sprints/tile/index.php, tools/v2/sprints/current/index.php, tools/v2/sprints/status-breakdown/index.php, tools/v2/sprints/worktype-breakdown/index.php, tools/v2/sprints/points-by-dev/index.php, tools/v2/sprints/burndown/index.php, tools/assets/clickup/sprint-dashboard.html, tools/mvc/clickup/react/get.php, tools/mvc/login/get.php, tools/_/app/nav.php |
 | [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
@@ -14,4 +14,5 @@
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |
 | [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | > **PER-AI-MODEL, DATA-DRIVEN SCOPING (2026-07-29).** The KB-documents and Vocabulary admin > UIs were refactored from a single hard-coded **"development-team"* | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/get.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/pg.php, tools/_/app/model/true/aimodels.php, tools/_/app/model/true/vectorindexes.php, tools/_/app/model/true/aimodels_vectorindexes.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf, tools/.platform/hooks/prebuild/01-install-php-pgsql.sh, tools/.platform/hooks/postdeploy/01-restart-php.sh |
 | [Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus the estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/_/app/talos/usage.php, tools/mvc/talos/contracts/get.php, tools/mvc/talos/contracts/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/usage/get.php, tools/mvc/talos/settings/get.php, tools/mvc/talos/settings/post.php, tools/assets/css/style.css |
+| [App-Wide Colour Theme (light / dark / auto)](features/theme-light-dark.md) | A **light / dark / auto** colour theme for the *entire* Tools app, built as a single semantic-token layer (`assets/css/theme.css`) rather than per-page edits. | tools/assets/css/theme.css, tools/assets/js/theme.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/common/header.php, tools/mvc/login/get.php, tools/assets/css/style.css, tools/assets/css/design.css, tools/assets/css/login.css, tools/assets/css/cloudfront-clients.css, tools/assets/css/gchart.css, tools/mvc/talos/usage/get.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/contracts/get.php, tools/mvc/clickup/dashboard/get.php, tools/mvc/email-migration/notify/post.php |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json, tools/ebs/setup_export_cache_folders.php, tools/_/app/frameworkindex.php |

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

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: architecture
 status: active
-updated: 2026-07-24
+updated: 2026-08-04
 owners: [jcardinal]
 files:
   - tools/index.php
@@ -23,7 +23,10 @@ files:
   - tools/mvc/get.php
   - tools/mvc/_TEMPLATE/get.php
   - tools/docs/ADDING_A_TOOL.md
+  - tools/assets/css/theme.css
+  - tools/assets/js/theme.js
 related:
+  - ./features/theme-light-dark.md
   - ./features/saml-sso-auth.md
   - ./features/persona-gated-navigation.md
   - ./features/developer-tools.md
@@ -47,7 +50,13 @@ double-gated (`[internal] dev_mode` AND `App_Registry::inDevMode()`). `config.*.
 (incl. `config.prod.ini`) is committed with plaintext production secrets that were **publicly
 web-readable** until the front-controller deny blocks added 2026-07-24 (see Known issues);
 rotation of every exposed secret is still owed. Never add more secrets, and keep config files
-denied at the front controller / out of the web root.
+denied at the front controller / out of the web root. New CSS must use `--c-*` tokens from
+`assets/css/theme.css`, never raw colour literals. **`assets/css/style.scss` is DEAD — edit
+`style.css` directly** (the `.css` has drifted ~450 lines ahead; there is no sass binary or
+`package.json`, so recompiling the SCSS would silently revert shipped work).
+`App_FrameworkIndex::setHeaderCode()` is the **only** hook for markup in `<head>`, and it
+**SETS rather than appends** — the theme bootstrap is its sole caller, so a second call
+silently clobbers it.
 
 ## Boot & structure
 
@@ -72,6 +81,14 @@ sibling apps. A fixed left two-column shell: dark left sidebar (`.app-nav`) with
 persona-filtered nav in the middle, pinned footer with the user's name + a ghost "Log out"
 button; content area on the right. **No top header bar** (see Critical rules).
 
+**All colour comes from a semantic token layer, `assets/css/theme.css`**, registered **first**
+in `App_FrameworkIndex_Tools::__construct()` so every other sheet resolves through it. The app
+supports light / dark / auto; the resolved theme is stamped on `<html>` as `data-theme` by an
+inline pre-paint script and the user's choice lives in `localStorage` (`toga-tools-theme`) —
+**not** the DB. The left sidebar and public header stay dark in **both** themes, which is why
+`toga-brandmark-white.png` still works everywhere. Login shows `toga-horizontal-colored.png` in
+light and `toga-horizontal-white.png` in dark. See `features/theme-light-dark.md`.
+
 ## Home route
 
 `/` (`mvc/get.php`) renders a persona-filtered dashboard of available tools (tiles grouped by
@@ -106,6 +123,11 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   composer package must `require_once` the autoloader itself.
 
 ## Change history
+- 2026-08-04 — Added the app-wide light/dark/auto theme: `assets/css/theme.css` token layer
+  registered first in `App_FrameworkIndex_Tools`, pre-paint `data-theme` stamping via the
+  one-and-only `setHeaderCode()` hook, `localStorage` preference (no DB column), nav/public
+  header dark in both themes. Recorded that `style.scss` is dead and `setHeaderCode()`
+  sets-not-appends. Not committed to `tools` yet (jcardinal)
 - 2026-07-24 — Fixed the config-file web-root exposure: `config.*.ini` was publicly readable via
   the `!-f`-only front controller (`GET /config.production.ini` served it verbatim); added
   `<FilesMatch>` deny blocks referencing the new 1.0 back-end security standard. Softened the

package/knowledge/1.0/apps/tools/features/clickup-sprint-dashboard.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-29
-owners: [kyalamarthi]
+updated: 2026-08-04
+owners: [kyalamarthi, jcardinal]
 files:
   - tools/_/app/clickup/sprint.php
   - tools/v2/sprints/tile/index.php
@@ -24,6 +24,7 @@ related:
   - ./persona-gated-navigation.md
   - ./saml-sso-auth.md
   - ./mvc-data-access-patterns.md
+  - ./theme-light-dark.md
   - ../architecture.md
   - ../../../2.0/apps/worker2/features/team-sprint-management.md
 ---
@@ -138,5 +139,15 @@ the React dashboard supersedes it.
   passed by reference", which the E_ALL error handler promotes to a fatal 500. Assign first:
   `$res = App_Database::query(...); buildArrayOfRows($res, false);`.
 
+- **The old Power BI embed page (`mvc/clickup/dashboard/get.php`) keeps ~6 fixed colour
+  literals on purpose — do NOT theme them.** Its card/frame colour `#0b1020` is matched to the
+  embedded Power BI report canvas so nothing flashes white while the iframe loads. Themed
+  surfaces there would reintroduce the flash in one theme or the other. Everything else on the
+  page was tokenised for the app-wide theme — see
+  [App-Wide Colour Theme](./theme-light-dark.md).
+
 ## Change history
+- 2026-08-04 — Tokenised the `/clickup/dashboard` page-local styles for the app-wide light/dark
+  theme, keeping ~6 deliberate fixed literals (incl. the `#0b1020` frame that matches the
+  embedded Power BI canvas so the iframe load does not flash white). Not committed. (jcardinal)
 - 2026-07-29 — Built `/clickup/react` as a native tools feature (data engine, `/v2/sprints/*` routes, CDN-React TV UI, iframe embed, "Dashboard/Clickup" nav); removed the old `/clickup/dashboard` Power BI nav entry; documented two reusable 1.0 gotchas (queryLogging preflight on Defaults-less DBs, buildArrayOfRows by-ref). (kyalamarthi)

package/knowledge/1.0/apps/tools/features/design-demo-admin.md

@@ -208,5 +208,4 @@ None — internal/shared design-team tool.
 - [Tools Architecture](../architecture.md)
 - [Static Demo Hosting](../../../standalone/apps/forward/features/static-demo-hosting.md)
 - [Deploying Tools to Elastic Beanstalk (AL2023)](../workflows/deploy-to-elastic-beanstalk-al2023.md)
-</content>
-</invoke>
+

package/knowledge/1.0/apps/tools/features/legacy-email-notifier.md

@@ -6,14 +6,15 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
-owners: [bala]
+updated: 2026-08-04
+owners: [bala, jcardinal]
 files:
   - tools/mvc/email-migration/notify/get.php
   - tools/mvc/email-migration/notify/post.php
   - tools/_/app/nav.php
 related:
   - ./mvc-data-access-patterns.md
+  - ./theme-light-dark.md
   - ../workflows/deploy-to-elastic-beanstalk-al2023.md
   - ../architecture.md
 ---
@@ -104,7 +105,19 @@ endpoint that swallows non-fatal diagnostics (returns `true`) for the duration o
 fatals and thrown exceptions still reach the `catch`. The framework mechanism is documented in
 [mvc-data-access-patterns](./mvc-data-access-patterns.md).
 
+## Gotcha — the colour literals in `post.php` are EMAIL HTML; never tokenise them
+
+`post.php` builds the digest **email** body. Email clients cannot resolve CSS custom
+properties, so its colour literals must stay hard-coded — a `var(--c-…)` there renders as no
+colour at all. This is easy to get wrong because the on-screen `get.php` in the same folder
+*was* tokenised for the app-wide theme (see
+[App-Wide Colour Theme](./theme-light-dark.md)). Rule: styles that leave the browser are not
+themed.
+
 ## Change history
+- 2026-08-04 — Tokenised the on-screen `get.php` page styles for the app-wide light/dark theme
+  and recorded that `post.php`'s email-HTML colour literals must stay hard-coded (email clients
+  cannot resolve CSS custom properties). Not committed. (jcardinal)
 - 2026-08-03 — Built the Legacy Email Notifier: multi-file xlsx merge via vendored PhpSpreadsheet,
   legacy-domain filter, `Client_True.Users` local-part resolution with always-domain-swap
   (never-skip), one digest per person per legacy domain, and chunked (25/batch) browser-driven

package/knowledge/1.0/apps/tools/features/talos-pricing-ui.md

@@ -20,6 +20,7 @@ files:
   - tools/mvc/talos/settings/post.php
   - tools/assets/css/style.css
 related:
+  - ./theme-light-dark.md
   - ./persona-gated-navigation.md
   - ./mvc-data-access-patterns.md
   - ../architecture.md
@@ -97,6 +98,20 @@ about cost; cost is driven by tool-call **intensity** via the profile
 - **Voice multipliers (0.25 / 0.50) are UNVALIDATED** — supplied second-hand, never measured,
   and possibly inverted. Flagged in the UI. **Do not quote voice from them.**
 - **`db_team`** is read/write on Contracts and Settings, read-only on the dashboards.
+- **Chart.js colours must come from theme tokens, and a live theme switch needs
+  `chart.update()`.** These pages now read series/axis/tick/gridline colours via
+  `TogaTheme.color('--c-…')` inside a `paint()` registered with `TogaTheme.onChange(paint)`,
+  then call `chart.update()` — `update()` clears Chart.js's resolver cache, so without it a
+  `Chart.defaults` change does not reach charts that already exist. Chart.js otherwise defaults
+  axis/tick text to a dark colour that is unreadable in dark mode. See
+  [App-Wide Colour Theme](./theme-light-dark.md).
+- **These pages keep an explicit `--c-bs-*` token group** because they were authored against
+  Bootstrap's palette (`#0d6efd`, `#6c757d`, `#495057`, `#dc3545`, `#198754`…), which is close
+  to but not the TOGA brand palette — folding them into `--c-primary` visibly restyles them.
+- **Open (dark mode):** the error toast measures ~2.4:1 (white on `--c-danger`) and likely
+  wants a fixed dark fill; the Pricing Dashboard target-band dataset never had a
+  `backgroundColor` (pre-existing authoring slip) so the band shades rather than tints; the
+  three chart pages cannot be statically proven light-identical and still need a browser pass.
 
 ## Security
 - `config.*.ini` carries committed plaintext secrets (team-accepted, see architecture Known
@@ -104,5 +119,10 @@ about cost; cost is driven by tool-call **intensity** via the profile
   (`[api] talos_backend_url` / `talos_backend_key`); no values recorded. Do not add secrets.
 
 ## Change history
+- 2026-08-04 — Tokenised these pages for the new app-wide light/dark theme: page-local styles
+  now use `--c-*` tokens (Talos pages keep their own `--c-bs-*` Bootstrap ramp), and the three
+  Chart.js pages read colours via `TogaTheme.color()` + repaint on `TogaTheme.onChange()` with
+  `chart.update()`. Recorded the dark-mode open items (error-toast contrast, missing
+  target-band `backgroundColor`). Not committed. (jcardinal)
 - 2026-08-04 — Restructured to **Contracts / Pricing Dashboard / Usage / Pricing Settings**. New Contracts pages replace Onboarding with a real PROSPECT/ACTIVE/CHURNED lifecycle (signed contracts churn, never hard-delete — `TalosPricingBands` cascades; post-signature edits append to `TalosContractAmendments`), plus actual-vs-estimate variance, month history chart and one-click apply-recommended-org-fee. Settings replaces the Cost Factors editor with measured rows read-only (`UPDATE ... AND isDerived = 0`). Benchmarks page deleted. Pricing Dashboard rebuilt for sales leadership. Fixed `usage.php clientOptions()` reading an always-empty `TalosClients` (selector rendered empty) → `GET /api/usage/clients` with Team-DB fallback; added cost-intensity panel. Estimator moved to token unit price + workload profiles. Wrote the missing `.app-content:has(.tool--wide)` rule and consolidated Talos CSS into `style.css`. (jcardinal)
 - 2026-06-29 — Built the Talos Pricing UI: nav folder + 4 pages (Onboarding w/ live JS estimate and contract-signing that locks the band schedule into `TalosClients`+`TalosPricingBands` in one txn; read-only Pricing Dashboard + Usage Benchmarks; technical-only Cost Factors editor) and `App_Talos_Estimator` (reads `TalosCostFactors`, derives conversations/user so sales need not enter it). Reads Team DB via new `db_team` connection. Offerings CHAT/VOICE_TO_VOICE/NATURAL_VOICE = 1.0/0.25/0.50 (voice ambiguous, deferred). (jcardinal)

package/knowledge/1.0/apps/tools/features/theme-light-dark.md

@@ -0,0 +1,209 @@
+---
+title: App-Wide Colour Theme (light / dark / auto)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-08-04
+owners: [jcardinal]
+files:
+  - tools/assets/css/theme.css
+  - tools/assets/js/theme.js
+  - tools/_/app/frameworkindex.php
+  - tools/_/app/nav.php
+  - tools/common/header.php
+  - tools/mvc/login/get.php
+  - tools/assets/css/style.css
+  - tools/assets/css/design.css
+  - tools/assets/css/login.css
+  - tools/assets/css/cloudfront-clients.css
+  - tools/assets/css/gchart.css
+  - tools/mvc/talos/usage/get.php
+  - tools/mvc/talos/pricing/get.php
+  - tools/mvc/talos/contracts/get.php
+  - tools/mvc/clickup/dashboard/get.php
+  - tools/mvc/email-migration/notify/post.php
+related:
+  - ../architecture.md
+  - ./persona-gated-navigation.md
+  - ./talos-pricing-ui.md
+  - ./clickup-sprint-dashboard.md
+  - ./legacy-email-notifier.md
+  - ./design-demo-admin.md
+  - ../../../standards/frontend.md
+---
+
+## Summary
+
+A **light / dark / auto** colour theme for the *entire* Tools app, built as a single
+semantic-token layer (`assets/css/theme.css`) rather than per-page edits. The user's choice
+is a three-way switcher rendered next to their name in the left-nav footer, persisted in
+**`localStorage` (`toga-tools-theme`) — deliberately not a DB column**, and applied
+**before first paint** by an inline bootstrap script so there is no flash of the wrong theme.
+
+**Light mode is a hard constraint: pixel-identical to before the change**, verified
+mechanically (see [Verification](#verification-how-to-prove-light-mode-did-not-change)).
+Any new page or stylesheet in this app should consume `--c-*` tokens and will then theme for
+free.
+
+> **Status (2026-08-04): NOT COMMITTED.** All of this lives in the working tree of the local
+> `tools` checkout, which is on `_production` — it needs a feature branch before it lands.
+> Verified **statically only**: resolver diffs, contrast maths, `php -l` on the 14 changed PHP
+> files, `node --check` on `theme.js`. **No browser check and no specialist-reviewer pass has
+> been run.** See [Open items](#open-items).
+
+## How it works
+
+### 1. The token layer — `assets/css/theme.css`
+
+~142 semantic CSS custom properties are declared on `:root` **with the original light
+values**, and overridden in a `:root[data-theme="dark"]` block. It is registered **first** in
+`App_FrameworkIndex_Tools::__construct()` so every other stylesheet resolves through it.
+
+Token groups and their meaning:
+
+| Group | Meaning |
+| --- | --- |
+| `--c-surface*` | fills |
+| `--c-text*` | foregrounds |
+| `--c-border*` | borders |
+| `--c-primary*` | brand (`-tNN` = alpha tint) |
+| `--c-nav-*` | left nav / public header — **dark in BOTH themes** |
+| `--c-on-accent`, `--c-on-dark-tNN` | white in BOTH themes; content sitting on a permanently dark/coloured fill |
+| `--c-slate-*`, `--c-indigo-*`, `--c-green-*`, `--c-red-*` | secondary ramp used by `design.css` + `cloudfront-clients.css` |
+| `--c-bs-*` | legacy Bootstrap ramp, Talos pages only (see gotchas) |
+| `--c-code-bg`, `--c-code-fg` | fixed dark code slab (not themed) |
+
+`color-scheme` is itself tokenised as `--c-color-scheme` so native scrollbars and form
+controls follow the theme. Note `style.css` previously hard-coded `color-scheme: light` on
+`html, body`, which beat the `:root` token — that had to be removed.
+
+### 2. Pre-paint application (no flash)
+
+`App_FrameworkIndex_Tools::themeBootstrapScript()` returns a tiny inline `<script>` injected
+with `App_FrameworkIndex::setHeaderCode()`; `library` echoes it inside `<head>` **after** the
+CSS/JS includes. It reads `localStorage` and stamps `data-theme` + `data-theme-pref` onto
+`<html>` before the first paint. **An external JS file cannot do this** — it runs too late and
+you get a flash of the wrong theme.
+
+### 3. Runtime API — `assets/js/theme.js` (`window.TogaTheme`)
+
+- `get()` → `'light' | 'dark'` (resolved theme)
+- `getPreference()` → `'light' | 'dark' | 'system'`
+- `set(pref)` — persists + applies
+- `onChange(fn)` — **fires immediately with the current theme**, then on every change, so a
+  caller has one code path for both "colour yourself now" and "recolour"
+- `color('--token')` — read a themed colour out of CSS for JS-driven visuals
+
+Persistence: `localStorage` key **`toga-tools-theme`**, values `light|dark|system`. Every
+access is `try`/`catch`ed — Safari private mode *throws* rather than returning `null`.
+`system` follows the OS live via a `matchMedia('(prefers-color-scheme: dark)')` change
+listener (with the `addListener` fallback for Safari <14), and a `storage` event listener keeps
+multiple open tabs in agreement.
+
+### 4. The switcher (server-rendered)
+
+Rendered in `common/header.php` inside `.app-nav-footer` — next to the signed-in user's name,
+above **Log out** — as a `role="radiogroup"` of three buttons carrying
+`data-theme-choice="light|dark|system"` (labelled **Light / Dark / Auto**). `theme.js` manages
+`aria-checked` + a roving `tabindex` and supports arrow keys. Icons come from a new
+`App_Nav::themeIcon($theme)` that returns **inline SVG** from a fixed 3-key allowlist — inline
+so the glyph inherits `currentColor`.
+
+### 5. Login-page wordmark
+
+Two `<img>` wordmarks are in the markup and CSS shows one per theme
+(`.login-logo--light` / `.login-logo--dark`, keyed off `:root[data-theme="dark"]`):
+`toga-horizontal-colored.png` in light, `toga-horizontal-white.png` in dark.
+
+Chosen over swapping `src` in JS or using `<picture>`: CSS honours an **explicit** Light/Dark
+choice, whereas a `<picture>` media query only sees `prefers-color-scheme` and would ignore a
+forced override — and CSS cannot flash the wrong logo. Both PNGs are 3610×700 so there is no
+reflow. Tradeoff: the browser downloads both (~49 KB extra).
+
+### 6. Chart.js pages
+
+`talos/usage`, `talos/pricing` and `talos/contracts` read series/axis/tick/gridline colours
+from tokens via `TogaTheme.color()` inside a `paint()` function registered with
+`TogaTheme.onChange(paint)`, followed by `chart.update()`. **`chart.update()` is required** —
+it clears Chart.js's resolver cache so `Chart.defaults` changes take effect on charts that
+already exist. Without this, Chart.js defaults axis/tick text to a dark colour that is
+unreadable on a dark background.
+
+## Decisions
+
+- **Left nav and public header stay dark in BOTH themes** (deepened for dark). Preserves the
+  app's identity, guarantees zero light-mode regression there, and keeps the existing white
+  brandmark PNG usable in both themes.
+- **Preference is browser-local (`localStorage`), not a DB column** — explicit developer
+  requirement.
+- **Light mode must be pixel-identical**, proven mechanically rather than by eye.
+- **`assets/css/style.scss` left untouched** — neither revived nor deleted (out of scope; that
+  is already the status quo — see gotcha below).
+
+## Verification (how to prove light mode did not change)
+
+1. **Resolver diff.** Resolve every `var(--c-*)` back through the `:root` (light) block and
+   diff the result against the pre-change file. Identical output = light mode unchanged.
+2. **Dark-coverage assert.** Every `:root` token must have a `[data-theme="dark"]` override
+   unless it is intentionally fixed.
+3. **Per-file colour multiset vs. `git HEAD`.** Compare the *multiset* of resolved colour
+   values per file, not a line-by-line diff — an index/line-based diff is useless once lines
+   are inserted, whereas a multiset comparison is immune to line-number shifts.
+
+## Gotchas
+
+- **`assets/css/style.scss` is DEAD in this repo — edit `style.css` directly.** Many recent
+  commits touch the `.css` while the `.scss` was last touched in an old ticket; the `.css` has
+  drifted ~450 lines ahead. There is no sass binary and no `package.json`. "Helpfully"
+  recompiling the SCSS would **silently revert a large amount of shipped work**.
+- **`App_FrameworkIndex::setHeaderCode()` is the only hook for injecting markup into `<head>`
+  in 1.0** (library echoes `$this->headerCode` inside `<head>` after the CSS/JS includes). It
+  **SETS rather than appends**, and before this feature it was unused anywhere in tools — so a
+  **second caller silently clobbers the first**. If another feature needs head markup, refactor
+  to compose both strings; do not add a second `setHeaderCode()` call.
+- **A colour literal used as both a foreground and a background must be split into two
+  tokens**, or dark mode inverts it the wrong way. Real cases in tools: `#10113A` (body text
+  *and* nav/public-header background), `#20242c` (text-strong *and* a dark chip fill), `#999`
+  (text grey *and* a badge fill), `#eef0f4` (border *and* badge fill), `#0f172a` (design.css
+  `--d-ink` text *and* the code-block background). Detect these **mechanically** — collect, per
+  candidate token, the set of CSS properties it appears with (background vs. colour/border).
+  Do not eyeball it.
+- **A brand colour needs TWO tokens in a dark theme.** `--c-primary` (text/borders on a panel)
+  is **lightened** in dark for legibility; `--c-primary-fill` (a fill behind white text) is
+  kept **dark enough** in dark mode to preserve contrast. The roles pull in opposite
+  directions — one token makes white-on-brand buttons fail contrast.
+- **The Talos admin pages keep their own `--c-bs-*` group.** They were authored against
+  Bootstrap's palette (`#0d6efd`, `#6c757d`, `#495057`, `#dc3545`, `#198754`…), which is close
+  to but **not** the TOGA brand palette; folding them into `--c-primary` visibly restyles those
+  pages. Only map a literal onto a token whose light value is **identical**.
+- **`mvc/email-migration/notify/post.php` generates EMAIL HTML — its colour literals must stay
+  hard-coded.** Email clients cannot resolve CSS custom properties. It is the same file family
+  as the on-screen page, so it is easy to tokenise by mistake.
+- **`mvc/clickup/dashboard/get.php` keeps ~6 fixed literals on purpose.** Its card/frame colour
+  `#0b1020` matches the embedded Power BI report canvas so nothing flashes white while the
+  iframe loads. Do not theme those.
+
+## Open items
+
+- The three Chart.js pages **cannot** be statically proven light-identical — their colours are
+  now generated at runtime. Needs a browser pass.
+- The Talos error toast measures ~2.4:1 in dark (white text on `--c-danger`) and probably wants
+  a fixed dark fill.
+- `talos/pricing`'s target-band dataset never had a `backgroundColor` (a pre-existing authoring
+  slip), so its band renders as a faint darkening rather than a green tint.
+- A few Talos overlay shadows shifted from black-based to slate-based (imperceptible but real),
+  and 7 imperceptible colour substitutions were accepted on Talos pages (largest:
+  `#f8f9fa` → `#f8f9fb`).
+
+## Change history
+- 2026-08-04 — Built the app-wide light/dark/auto theme: `assets/css/theme.css` (~142 `--c-*`
+  tokens on `:root` + a `[data-theme="dark"]` override, registered first in
+  `App_FrameworkIndex_Tools`), `assets/js/theme.js` (`window.TogaTheme`), a pre-paint inline
+  bootstrap via `setHeaderCode()`, a Light/Dark/Auto radiogroup in the nav footer
+  (`App_Nav::themeIcon()`), per-theme login wordmarks, and token-driven Chart.js repaint on the
+  three Talos chart pages. Preference in `localStorage` (`toga-tools-theme`), no DB column; nav
+  + public header stay dark in both themes; light mode proven unchanged by resolver diff.
+  **Not committed — working tree on `_production`, no browser verification yet.** (jcardinal)

package/knowledge/1.0/standards/frontend.md

@@ -5,12 +5,13 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-07-30
+updated: 2026-08-04
 owners: [jcardinal]
 files: []
 related:
   - ./backend-php.md
   - ./framework-rules.md
+  - ../apps/tools/features/theme-light-dark.md
   - ../apps/tools/features/design-demo-admin.md
   - ../apps/tools/features/talos-kb-documents-admin.md
 ---
@@ -66,10 +67,48 @@ Each round trip adds a level. Equality comparisons then fail too, because a fres
 - `tools/_/app/design/github.php` — `App_Design_Github::decodeEntities()` applied to tab
   names and project titles on both the storage-read and request-read sides.
 
+## Tokenising an existing stylesheet for a second theme
+
+When retrofitting light/dark onto a legacy sheet, four rules turn a guessing game into a
+mechanical exercise.
+
+**1. Split any literal used as both a foreground and a background into two tokens.** A single
+token inverts the wrong way in the second theme. Detect these **mechanically** — collect, per
+candidate token, the set of CSS properties it appears with (`background*` vs.
+`color`/`border*`) — do not eyeball it. Real cases in `tools`: `#10113A` (body text *and* nav
+background), `#20242c`, `#999`, `#eef0f4`, `#0f172a`.
+
+**2. A brand colour needs TWO tokens.** `--c-primary` (text/borders on a panel) must be
+**lightened** in dark for legibility; `--c-primary-fill` (a fill behind white text) must stay
+**dark enough** in dark to preserve contrast. The roles pull in opposite directions; one token
+makes white-on-brand buttons fail contrast.
+
+**3. Only map a literal onto a token whose light value is IDENTICAL.** Measure perceptual
+distance before accepting a "close enough" substitution — a near-match silently restyles the
+page. Legacy pages authored against a *different* palette (the Talos admin pages use
+Bootstrap's `#0d6efd`/`#6c757d`/`#dc3545`/`#198754`) keep their own token group with their
+exact original values rather than being folded into the brand tokens.
+
+**4. Prove the original theme is unchanged, mechanically.** (a) Resolve every `var(--…)` back
+through the `:root` block and diff against the pre-change file; (b) assert every `:root` token
+has a second-theme override unless intentionally fixed; (c) compare the per-file **multiset**
+of resolved colour values against `git HEAD` — a line-index diff is useless once lines are
+inserted, a multiset comparison is immune to line shifts.
+
+Two things are **never** tokenised: HTML destined for an **email** (email clients cannot
+resolve custom properties) and colours deliberately matched to third-party embedded content
+(e.g. an iframe's canvas colour, to prevent a white flash on load).
+
+Reference implementation:
+[tools App-Wide Colour Theme](../apps/tools/features/theme-light-dark.md).
+
 ## Change history
 
+- 2026-08-04 — Added "Tokenising an existing stylesheet for a second theme": split
+  dual-role colour literals, two tokens per brand colour, identical-value-only substitutions,
+  and the mechanical proof that the original theme is unchanged; plus the never-tokenise cases
+  (email HTML, colours matched to third-party embeds). Drawn from the `tools` light/dark
+  build. (jcardinal)
 - 2026-07-30 — Created. Establishes the escape-once/plain-text-storage invariant after a
   second independent occurrence in `tools` (Design Demo Admin, following the Talos
   vocabulary tool). (jcardinal)
-</content>
-</invoke>

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-08-03
+updated: 2026-08-04
 owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -82,6 +82,50 @@ tenant's other APIs at all. See
 > result above is authoritative; the code path is misleading. Anyone tempted to reason it out
 > from V2.php will reach the wrong answer.
 
+## The dispatch is UNGUARDED — a row naming a method that does not exist hard-fatals the endpoint
+
+The derived name (step 2 above) is **pure convention with nothing validating it**, and there is
+**no `phpMethod` column in production** to override it. All **four** call sites in
+`api2/Component/Api/V2/V2.php` invoke the derived name **without a `method_exists()` check**:
+
+| Site | Phase |
+|------|-------|
+| `~L8655` | builds the interceptor lookup |
+| `~L3148` | pre-processing dispatch |
+| `~L5694` | post-processing dispatch |
+| `~L7411` / `~L7437` | alternate pre-processing path |
+
+So a **single `ApiPayloadInterceptors` row whose (recordId, phase, method) resolves to a method the
+model does not define takes the endpoint down** with a PHP fatal —
+`Call to undefined method _Model_<Slug>_<Model>::postPost()` — not a handled 4xx/5xx. This is the
+mirror image of the "missing row" failure mode above: a *missing* row is silent, an *extra/wrong*
+row is fatal.
+
+**Fix direction:** guard all four sites with `method_exists()` and raise a logged `Logs.Issue`
+instead of letting the request fatal.
+
+### The client-model resolution that decides which class must define the method
+
+At `~L5681-5690` the engine derives the concrete class by `str_replace`-ing `_Model_Client_` →
+`_Model_<jwt client slug>_` on `$record->model`, guarded by `class_exists`. For Compass USA that
+yields `_Model_Compass_Usa_*`.
+
+The chain is `_Model_Compass_Usa_X extends _Model_Compass_X extends _Model_Client_X`, so **a method
+defined on the shared Compass base is inherited by both the Usa and Canada subclasses** — a
+per-region subclass does *not* need its own copy. Do not add duplicate hooks per region.
+
+### `Core.Records` facts for interceptor debugging
+
+- **`Core.Records.model` is UNIQUE** — exactly one record row per model class, so an interceptor's
+  `recordId` maps to precisely one model. No ambiguity to resolve.
+- The column is **`route`** (not `routePlural` / `routeSingular`) in the current schema. Example:
+  `recordId 15` = route `sales-order-items` = `_Model_Client_SalesOrderItem`.
+- **Diagnostic:** join the client's active interceptor rows to `Core.Records` and check each derived
+  method actually exists in `_underscore/Model/<Slug>/`. Compass's legitimate rows (records **14**
+  sales-orders, **17** purchase-orders, **19** vendor-items, **21** items, **37** contacts, **55**
+  advance-shipping-notices, **179** approval-decisions) all map 1:1 to real methods — **the row whose
+  record has no corresponding method is the anomaly.**
+
 ## Worked example — the EV-10 that was not a code bug
 
 `_Model_Client_ItemFulfillment::prePost()` defaults `itemFulfillmentStageId` to the shipped stage on
@@ -99,6 +143,14 @@ and the failing environment**. It is a small table, and the drift is usually exa
 - **⚠ A hook that "isn't running" is a missing registration row before it is a code bug.** Check
   `ApiPayloadInterceptors` for `(recordId, phase, method)` **first** — never start by re-reading the
   PHP.
+- **⚠ An interceptor row for a method that does not exist is a production outage, not a no-op.**
+  The dispatch is unguarded at all four call sites — the endpoint fatals with *"Call to undefined
+  method"*. If a write endpoint suddenly 500s for one client only, list that client's
+  `ApiPayloadInterceptors` rows and confirm every derived method exists.
+- **⚠ A migration that enables an interceptor must insert `isActive = 0`.** Activation is a *data*
+  change that switches on a *code* path; if the PHP defining the method is not confirmed deployed to
+  that environment, the row takes the endpoint down. Insert inactive, verify the deploy, then flip
+  `isActive = 1` — and remember every environment activates independently.
 - **The method name is derived, so a typo'd enum silently misses.** A row with
   `prePostProcessing = 'PRE'`, `httpMethod = 'PUT'` resolves to `prePut`, not `prePost`; the engine
   will simply find no method and move on.
@@ -114,6 +166,17 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-04 — Documented the **inverse failure mode**: the derived-name dispatch is **unguarded at
+  all four `V2.php` call sites** (`~L8655` lookup, `~L3148` pre, `~L5694` post, `~L7411`/`~L7437`
+  alternate pre) and there is **no `phpMethod` column in production**, so one row naming a
+  nonexistent method hard-fatals the endpoint (*"Call to undefined method
+  `_Model_Compass_Usa_SalesOrderItem::postPost()`"*). Added the client-model resolution at
+  `~L5681-5690` (`_Model_Client_` → `_Model_<slug>_`, `class_exists`-guarded) and the
+  `Usa → Compass → Client` inheritance rule (define once on the Compass base; no per-region copy),
+  the `Core.Records` debugging facts (`model` is UNIQUE, column is `route`, record 15 =
+  `sales-order-items`, Compass's 1:1 legitimate row set), and the rule that a migration enabling an
+  interceptor must land `isActive = 0` first. Diagnosed from a production incident; no code change.
+  (dfranks)
 - 2026-08-03 — Added two verified behaviours from a live dev probe: (1) interceptor registration
   is **per-API** (`apiId` on the row, in both the Core and `Client_<X>` tables), so a guard in a
   hook is scoped by **DB config rather than code** and a new row widens its blast radius; (2) the

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-04
 owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,7 +15,9 @@ files:
   - _underscore/Model/Core/Logs/Api.php
 related:
   - ../architecture.md
+  - ./api-payload-interceptors.md
   - ../../../../clients/aig/features/entitlement-intake.md
+  - ../../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
 ---
 
 ## Summary
@@ -61,6 +63,28 @@ That is the deciding factor when choosing between `_Exception_Validation` (400,
 request, no Issue) and `_Exception_Business` (500, Sentry + a routed Issue). Do **not** reach for
 `_Exception_Business` merely to "make sure the rejection is recorded" — it already is.
 
+### ⚠ But an uncaught PHP **fatal** can leave NO log row anywhere
+
+The commit-the-logs / roll-back-the-data contract above holds for the **handled** paths — a
+validation rejection or an exception the controller catches. It did **not** hold for an **uncaught
+`Error`** observed in production on 2026-08-04 (a `Call to undefined method` raised from an
+[API payload interceptor](api-payload-interceptors.md) dispatch): the fatal was reported to the
+error tracker, but **`Logs_Compass.Api` contained zero 5xx rows for the entire day and the failing
+request appears nowhere in it at all.** Suspected regression in the recent `Error.php` /
+Issue-Event table normalization work.
+
+Practical consequences:
+
+- **Do not conclude "the request never happened" from an empty log table.** For a fatal, absence of
+  a log row is not evidence of absence of the request. Check the error tracker's per-event detail —
+  that may be the *only* record of the individual request.
+- **Diagnose from the DATA, not the log.** The data transaction rolls back while a *previous*
+  successful request already committed its own rows, so a fatal on a multi-request write sequence
+  leaves a detectable **orphan / zero-child parent**. Sweep for those instead of grepping logs — see
+  [Compass Order Lifecycle & Data-Integrity Invariants](../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md#detecting-empty-shell-orders-left-by-a-fatal-mid-sequence).
+- **Orphan sweeps only find PARTIAL casualties.** An attempt that rolled back completely leaves no
+  row in any table and, with no API log row, no trail at all.
+
 ## Blind spots when auditing a client's API traffic
 
 Looking only at `Logs_<Client>.Api` misses four sources:
@@ -110,6 +134,12 @@ re-send.
 
 ## Change history
 
+- 2026-08-04 — Added the limit of the commit-logs contract: an **uncaught PHP fatal** (a
+  `Call to undefined method` from an interceptor dispatch) produced **zero rows in
+  `Logs_Compass.Api`** — no 5xx row for the whole day and no row for the failing request — while
+  still reaching the error tracker. Suspected regression in the `Error.php` / Issue-Event
+  normalization work. So log-based diagnosis fails for this class of 500; sweep the **data** for
+  zero-child parents instead, and accept that fully-rolled-back attempts leave no trail. (dfranks)
 - 2026-08-03 — Corrected a common wrong assumption: an **HTTP 400 leaves a full log row**.
   `Controller/Index.php` L369-377 commits `DB_LOGS`/`DB_CLIENT_LOGS` and rolls back only the
   business transaction, so rejections are queryable and attributable to the credential; what they

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 15 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 19 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 20 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 11 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 14 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 13 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 14 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

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

@@ -12,5 +12,6 @@
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [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 | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [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 | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
-| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |
+| [Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)](workflows/odp-edi-import-recovery.md) | 1.0 | How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron **3a** created the ODP SalesOrder header, the follow-up item | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json |
+| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/client/compass.php |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

package/knowledge/clients/compass-usa/workflows/odp-edi-import-recovery.md

@@ -0,0 +1,111 @@
+---
+title: Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)
+framework: "1.0"
+repo: worker
+project: Worker
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-08-04
+owners: ["dfranks"]
+files:
+  - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
+  - worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php
+  - worker/schedules/cron.worker.sync.json
+related:
+  - clients/compass-usa/workflows/odp-order-pipeline-to-netsuite.md
+  - clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
+  - ../../../2.0/apps/api2/features/api-payload-interceptors.md
+  - ../../../2.0/apps/api2/features/request-logging.md
+  - clients/compass-usa/profile.md
+---
+
+## Summary
+
+How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron
+**3a** created the ODP SalesOrder header, the follow-up item write died (e.g. an api2 fatal), and 3a
+then **deleted the S3 object**, leaving a zero-item order and nothing to retry.
+
+The recovery works because the raw x12 is archived in `Logs.FileLog` and **3a is fully idempotent**:
+re-uploading the file makes it repair the items, the ODP PO, and both bridges. Verified end-to-end
+in **production** on 2026-08-04 for ODP PO `41608261-1135` / ODP SO `475390815001`.
+
+## When to use this
+
+Symptoms: a zero-item ODP SalesOrder (see the orphan sweeps in
+[order lifecycle & data integrity](order-lifecycle-and-data-integrity.md)), and cron 5 re-attempting
+the NetSuite SO every 10 minutes because it selects on `c_dtTransmittedToNetsuite IS NULL`.
+
+## The runbook
+
+### Step 1 — retrieve the archived x12
+
+The raw EDI is on the **legacy-core cluster**, table **`Logs.FileLog`**:
+
+- `job = 'ODP_EDI'`
+- `fileName = '<odpPoNumber>.x12'` — note **`.x12`**, even though the inbound S3 filename is
+  `EDI_<odpPoNumber>.txt`.
+
+**Query it bounded by `job` + `fileTimestamp`.** An unbounded `fileName LIKE` scan times out on this
+table.
+
+Extract with `mysql --raw --batch --skip-column-names`, then **strip the trailing newline the client
+appends** so the byte count matches the stored `LENGTH(fileData)` exactly. A byte-count mismatch means
+you have a corrupted payload — do not upload it.
+
+### Step 2 — know that S3 has nothing left
+
+3a **deletes the S3 object after processing** (`:769`), so a failed import leaves no file to retry.
+Recovery is a **re-upload**, to:
+
+```
+s3://agilant-as2/OfficeDepot/EDI_<odpPoNumber>.txt
+```
+
+### Step 3 — clear the cause BEFORE re-uploading
+
+**Confirm no `ApiPayloadInterceptors` row exists for the `sales-order-items` record** (`recordId 15`)
+whose derived method the model does not define. If one is still active, the item write fatals again
+**and the file is deleted a second time**. See
+[API payload interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md).
+
+### Step 4 — let 3a repair it (≤ 5 minutes)
+
+3a runs `*/5`. Because every step is existence-guarded it **reuses** the existing SO and **backfills**
+what is missing: unmatched items (matched case-insensitively by `partNumber`), the ODP PO if absent,
+and both the `PurchaseOrders_SalesOrders` and `PurchaseOrderItems_SalesOrderItems` bridges. No
+duplicates are created.
+
+**Then set `customerPurchaseOrder` manually** — 3a never updates the SalesOrder *header* on an
+existing order, so it stays `NULL`. Prefer direct SQL over a `PUT`; the reasoning and its two
+tradeoffs are in the
+[lifecycle doc](order-lifecycle-and-data-integrity.md#repairing-a-header-only-scalar-field-direct-sql-vs-put).
+
+### Step 5 — let cron 5 transmit to NetSuite
+
+Cron 5 (`*/10`) picks the now-complete ODP SO up and stamps `c_dtTransmittedToNetsuite` +
+`c_netsuiteInternalSalesOrderId`. It excludes `number LIKE 'MA%'`. Its stamps landing is the
+confirmation the recovery finished.
+
+## Gotchas / known issues
+
+- **⚠ Re-uploading before fixing the root cause destroys the file again** (3a deletes on the way
+  through). Step 3 is not optional.
+- **⚠ The archive filename extension differs from the S3 one** — `.x12` in `Logs.FileLog`,
+  `EDI_<po>.txt` in S3. Searching for the wrong one finds nothing.
+- **Don't search for the ODP SalesOrder by the `BEG` number.** `BEG` is the ODP *PO*; the SO number
+  is `REF~QC`. Full segment map in the
+  [ODP pipeline doc](odp-order-pipeline-to-netsuite.md).
+- **`Logs.FileLog` has limited retention** (~30 days) — beyond that there is no archived x12 and the
+  recovery must come from ODP re-sending.
+- A **fully** rolled-back import leaves no row anywhere and no API log row, so it will not show up in
+  an orphan sweep at all; only the error tracker's per-event detail can enumerate those.
+
+## Change history
+
+- 2026-08-04 — Documented the runbook after recovering a production ODP order whose item write was
+  killed by an api2 fatal: `Logs.FileLog` (`job = 'ODP_EDI'`, `<po>.x12`, bounded by `fileTimestamp`)
+  as the x12 archive, the trailing-newline/byte-count check, the re-upload path to
+  `s3://agilant-as2/OfficeDepot/`, the mandatory "clear the interceptor first" step, 3a's idempotent
+  repair plus the `customerPurchaseOrder` header gap, and cron 5's `*/10` stamps as the completion
+  signal. (dfranks)

package/knowledge/clients/compass-usa/workflows/odp-order-pipeline-to-netsuite.md

@@ -6,16 +6,18 @@ project: Worker
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-08-03
-owners: ["rgirish", "bala"]
+updated: 2026-08-04
+owners: ["rgirish", "bala", "dfranks"]
 files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
   - worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php
   - worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
   - worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php
+  - worker/schedules/cron.worker.sync.json
   - library/app/client/compass.php
 related:
+  - clients/compass-usa/workflows/odp-edi-import-recovery.md
   - clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
   - clients/compass-usa/features/mits-po-transmission-to-vendors.md
   - clients/compass-usa/features/mits-po-to-so-item-linking.md
@@ -40,7 +42,8 @@ Commerce → Compass SalesOrder            (SalesOrders.customerId = 2)
 MITS → PurchaseOrder                      (PurchaseOrders.vendorId = 1 = OFFICE DEPOT; POST /v2/purchase-orders; PO number e.g. 50305906-1)
   [cron 2_transmit_mits_purchase_orders_to_vendors] → ODP (cXML; email fallback per integration)   [sets PurchaseOrders.dtSubmitted]
 ODP → 850 EDI dropped to S3 (AS2)         (bucket agilant-as2, prefix OfficeDepot/)
-  [cron edi/1_download_edi_s3_create_po_toga]     → creates ODP SalesOrder (customerId = 1); deletes the S3 file after processing
+  [cron workflow/3a_import_office_depot_purchase_orders  — NOT edi/1, see correction below]
+                                                → creates ODP SalesOrder (customerId = 1); deletes the S3 file after processing
 ODP SalesOrder (customerId = 1)
   [cron 5_create_netsuite_sales_orders_from_office_depot_purchase_orders, hourly] → NetSuite SO
      writes back c_dtTransmittedToNetsuite + c_netsuiteInternalSalesOrderId ONTO the ODP SO (customerId=1)
@@ -56,12 +59,57 @@ ODP SalesOrder (customerId = 1)
    `PurchaseOrders.dtSubmitted` when transmitted (~2 min after PO creation). (See the dedicated
    [MITS PO Transmission to Vendors](../features/mits-po-transmission-to-vendors.md) feature for
    the item-less-PO gotcha and the CXML-vs-EMAIL routing detail.)
-3. **`edi/1_download_edi_s3_create_po_toga.php`** — pulls the ODP **850** from S3 bucket
-   `agilant-as2`, prefix `OfficeDepot/` (delivered via AS2), and creates a downstream **ODP
-   SalesOrder** (customerId=1 = Office Depot). **Deletes the file from S3 after processing** —
-   so an absent S3 object is expected once ingested, not evidence of a miss.
-4. **`workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php`** — runs
-   **hourly**; picks up ODP SalesOrders
+3. **`workflow/3a_import_office_depot_purchase_orders.php`** — pulls the ODP **850** from S3 bucket
+   `agilant-as2`, prefix `OfficeDepot/` (excluding `OUTBOX/` and `SENT/`; `:46` S3 read,
+   `:54-58` prefix filters) and creates the downstream **ODP SalesOrder** (customerId=1 = Office
+   Depot). **Deletes the S3 object after processing** (`:769`) — so an absent S3 object is expected
+   once ingested, not evidence of a miss, *and* a failed import leaves nothing to retry.
+
+   > **⚠ Correction (2026-08-04): `edi/1_download_edi_s3_create_po_toga.php` is DEAD CODE.** It
+   > appears in **no** schedule file. The scheduled entry *named* "Download EDI From S3 Files &
+   > Create PO - EDI Office Depot" (`*/5 * * * *`, `worker/schedules/cron.worker.sync.json`
+   > `:254-259`) actually points at **`toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`**.
+   > The two scripts have **different idempotency and different API call shapes** — `edi/1`'s create
+   > branch POSTs the SO with *nested* items and a `customer.name`, while **3a POSTs the header alone
+   > (uuids) and then POSTs the items in a separate request**. Reasoning from `edi/1` gives wrong
+   > answers about what production does.
+   >
+   > **General rule: never infer which script runs from its filename or folder.** Verify against
+   > `worker/schedules/cron.*.json` — and note the schedule entry's **name can be actively
+   > misleading**.
+
+### 3a is idempotent — re-dropping an EDI file is safe
+
+Every step of 3a is gated by a `totalRecordCount == 0` existence check, so a re-drop produces **no
+duplicates and backfills whatever is missing**:
+
+| Step | Guard | Behavior on re-run |
+|------|-------|--------------------|
+| ODP SalesOrder | `:162-227` existence check | reuses the existing SO |
+| SO items | `:470-498` | matches existing items **case-insensitively by `partNumber`**; creates only unmatched ones |
+| ODP PurchaseOrder | `:356-436` | creates only if missing |
+| `PurchaseOrders_SalesOrders` + `PurchaseOrderItems_SalesOrderItems` bridges | `:632` | creates only if missing |
+
+**KNOWN GAP: 3a never updates the SalesOrder HEADER on an existing order.** So
+`customerPurchaseOrder` stays `NULL` on a repaired order and must be set manually. See
+[Recovering a lost ODP EDI import](odp-edi-import-recovery.md).
+
+### The EDI 850 → TOGa identifier mapping (not guessable — this is the key to tracing an ODP order)
+
+| 850 segment | Meaning | Where it lands |
+|-------------|---------|----------------|
+| **`BEG`** | the **Office Depot PO number** (e.g. `41608261-1135`) | `PurchaseOrders.number`, vendor "Agilant Solutions Inc" |
+| **`REF~QC`** | the **ODP SALES ORDER number** (e.g. `475390815001`) | `SalesOrders.number` with `customerId = 1` |
+| **`REF~EU` / `REF~PO`** | the **Compass MITS PO number** (e.g. `50310002-1`) | its `c_mitsSalesOrder` field holds the ODP SO number |
+| **`REF~LU`** | the **Compass sales order** (e.g. `SA135273`) | `SalesOrders` with `customerId = 2` |
+| **`PO1`** | the line | qty, UOM, unit price, vendor part, ODP item id |
+
+**⚠ `REF~QC` — not `BEG` — is the value to search on for the ODP SalesOrder.** Searching
+`PurchaseOrders` / `SalesOrders` for the `BEG` number finds nothing for the SO and wastes time.
+(This is the segment-level detail behind the "don't search by the MITS PO number" rule below.)
+4. **`workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php`** — scheduled
+   **every 10 minutes** (`*/10`, verified against `worker/schedules/` on 2026-08-04; this doc
+   previously said "hourly"); picks up ODP SalesOrders
    (`OfficeDepotSalesOrders.customerId = 1 AND c_dtTransmittedToNetsuite IS NULL`), creates the
    SO in NetSuite, and writes back `c_dtTransmittedToNetsuite` + `c_netsuiteInternalSalesOrderId`
    **onto the ODP SalesOrder (customerId=1), never the Compass SO (customerId=2)**.
@@ -70,6 +118,10 @@ ODP SalesOrder (customerId = 1)
    - **computer-kit orders** (Bundles 187–196) wait for a **2nd PO** before syncing.
    - a **30-minute delay** after the first ODP PO is created.
 
+   Because the selection is only `c_dtTransmittedToNetsuite IS NULL` (plus `number NOT LIKE 'MA%'`),
+   a **zero-item ODP SalesOrder sits in this queue retrying every 10 minutes** until its lines are
+   restored — the retry loop is the symptom, not the cause.
+
 ## Cron 5 NetSuite SO creation — failure modes & the two ODP error emails
 
 Two different Compass ODP error emails exist, from **two different pipeline stages**. They look
@@ -141,6 +193,15 @@ wrong record makes every order look "stuck." Use the **join**, never a number ma
   transmission feature.)
 
 ## Change history
+- 2026-08-04 — **Corrected the 850-import step**: `edi/1_download_edi_s3_create_po_toga.php` is
+  **dead code in no schedule**; the schedule entry named "Download EDI From S3 Files & Create PO -
+  EDI Office Depot" (`*/5`) actually runs `workflow/3a_import_office_depot_purchase_orders.php`,
+  which has different idempotency and posts the SO header and its items as **two separate API
+  requests**. Added 3a's full existence-check/idempotency map (re-dropping a file is safe; header is
+  never updated so `customerPurchaseOrder` stays NULL), the **EDI 850 → TOGa identifier mapping**
+  (`BEG` = ODP PO, `REF~QC` = ODP SO — the one to search on, `REF~EU`/`REF~PO` = MITS PO,
+  `REF~LU` = Compass SO), and corrected cron 5's schedule to `*/10`. Production incident
+  investigation; no code change. (dfranks)
 - 2026-08-03 — Documented cron 5's "Please enter a value for Ext Price" root cause (`rate` set
   only for NetSuite item groups, never plain items → NetSuite `add()` USER_ERROR, order re-emails
   hourly while stuck), the two distinct ODP error emails (3a PO-import vs 5 SO-creation) and cron

package/knowledge/clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md

@@ -5,8 +5,8 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-06-30
-owners: ["jcardinal", "bala"]
+updated: 2026-08-04
+owners: ["jcardinal", "bala", "dfranks"]
 files: []
 related:
   - clients/compass-usa/profile.md
@@ -93,6 +93,41 @@ one-upstream for bundles.
 5. **Mirror back-links:** every IF on a non-source SO (ODP/Agilant) should have
    `upstreamItemFulfillmentId` set, and each of its items `upstreamItemFulfillmentItemId` set.
 
+## Detecting "empty shell" orders left by a fatal mid-sequence
+
+The ODP EDI import creates a SalesOrder **header** and its **line items** in **separate API
+requests** (`POST /sales-orders`, then `POST /sales-order-items` ~4s later — see the
+[ODP pipeline doc](odp-order-pipeline-to-netsuite.md)). If the *second* request dies, the header is
+already committed and the items roll back, leaving a **zero-item sales order**. This is the
+signature to sweep for whenever an api2 write fatals — and, because a fatal can leave **no API log
+row at all** ([request logging](../../../2.0/apps/api2/features/request-logging.md)), the **data is
+the only trail**.
+
+Sweeps against `Client_Compass`:
+
+1. **Zero-item sales orders** — `SalesOrders LEFT JOIN SalesOrderItems … GROUP BY so.id HAVING
+   COUNT(soi.id) = 0`.
+2. **Zero-item purchase orders** — the same shape over `PurchaseOrders` / `PurchaseOrderItems`.
+3. **ODP SOs with no upstream PO** — ODP SOs (`customerId = 1`) `LEFT JOIN
+   PurchaseOrders_SalesOrders WHERE` the bridge row `IS NULL`.
+
+> **⚠ LIMITATION: this finds only PARTIAL casualties.** An attempt that rolled back *completely*
+> leaves no row in any table, and with no API log row there is no trail anywhere — only the error
+> tracker's **per-event detail** can enumerate those. Never report an orphan sweep as a complete
+> casualty list.
+
+### Repairing a header-only scalar field: direct SQL vs `PUT`
+
+When only a scalar needs setting on an existing order (e.g. `customerPurchaseOrder`, which the ODP
+importer never backfills), **direct SQL is the deliberate choice over `PUT /sales-orders/{uuid}`**: a
+`PUT` fires the record-14 `POST`/`PUT` [payload
+interceptor](../../../2.0/apps/api2/features/api-payload-interceptors.md) and drags the whole order
+back through MITS/NetSuite logic for one field.
+
+Accept the two tradeoffs: **no API log row** for the change, and **`dtUpdated` still moves** (the
+column is `ON UPDATE CURRENT_TIMESTAMP`), which can look like a fresh modification to anything doing
+`dtUpdated`-based change detection downstream.
+
 ## Verified schema corrections (older code/scripts assume these wrongly)
 - **`ItemFulfillmentPackages` does NOT exist** — header IF tracking is `ItemFulfillments_TrackingNumbers`.
 - `ItemFulfillmentItemUnits` has **no `trackingNumberId`** — unit tracking is the bridge
@@ -120,6 +155,13 @@ runtime workflow.
 - High-multiplier over-fulfillment (5×–20×) does not fit the split-PO spurious-link pattern — separate cause.
 
 ## Change history
+- 2026-08-04 — Added the **"empty shell" order signature** — the ODP importer writes the SO header
+  and its items in two separate API requests, so a fatal on the second leaves a committed,
+  zero-item order — plus the three orphan sweeps that detect it (zero-item SOs, zero-item POs, ODP
+  SOs with no `PurchaseOrders_SalesOrders` bridge) and the limitation that they only find *partial*
+  casualties. Also recorded why a header-only scalar repair uses **direct SQL over `PUT`** (a `PUT`
+  fires the record-14 interceptor and the whole MITS/NetSuite path) and its two tradeoffs (no API
+  log row; `dtUpdated` still moves via `ON UPDATE CURRENT_TIMESTAMP`). (dfranks)
 - 2026-06-30 — Updated the IF-stage invariant: `itemFulfillmentStageId` is now NOT NULL and
   picked/packed/shipped stages are all in use (resolved by slug), superseding "stage 3 = Shipped;
   stages 1/2 unused". Compass order status remains shipped-only. (bala)

package/package.json

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