toga-ai 1.0.638 → 1.0.640

package/knowledge/2.0/apps/ai-bdr/INDEX.md

@@ -5,6 +5,7 @@
 | [AI-BDR Architecture](architecture.md) | **AI-BDR** is TOGA's outbound AI sales-development representative. | ai-bdr/README.md, ai-bdr/requirements.txt, ai-bdr/.env.example, ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/vapi/templates/assistant.template.json, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py |
 | [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Execution status (2026-07-16):** PLAN **Phases 0–5 are BUILT and QA'd**, Phase 6 > was **mostly already built** (the `info` contract was implemented at comm | bdr/PLAN.md, bdr/mockup/app.jsx, bdr/mockup/screens.jsx, bdr/mockup/components.jsx |
 | [Call Orchestration — PHP Worker ↔ Vapi (the integration seam)](features/call-orchestration.md) | The **PHP worker** is the orchestrator; **Vapi** is the actor. | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/scripts/update_structured_output.py |
+| [AI-BDR Campaign Chat — Backend Contract + Frontend Widget Handoff](features/campaign-chat-handoff.md) | The consolidated backend + frontend handoff for the **AI-BDR campaign chat** — a grounded AI-BDR chat widget for landing pages, powered by the Talos backend at | ai-bdr-campaign-handoff.md |
 | [Live Call Status — Vapi call API → funnel Success screen lifecycle](features/live-call-status.md) | The BDR funnel's Success screen shows the **real** state of the call it just requested — dialing / ringing / answered-and-talking / ended / not-answered — inste | bdr/src/server/vapiCall.ts, bdr/src/server/callStatus.ts, bdr/src/server/statusToken.ts, bdr/src/server/callbackService.ts, bdr/src/server/workerDialer.ts, bdr/src/lib/callStatus.ts, bdr/src/app/api/call-status/route.ts, bdr/src/app/api/call-now/route.ts, bdr/src/flow/useCallStatusViewModel.ts, bdr/src/flow/callStatusApi.ts, bdr/src/flow/screens/Success.tsx, bdr/src/content/schema.ts, bdr/src/content/default.ts, bdr/src/proxy.ts |
 | [Cybersecurity Landing Page (/landing — the site's current main page)](features/security-landing-page.md) | A single-page **cybersecurity services marketing landing page** at **`/landing`** in the `bdr` repo — and, as of 2026-08-24, **the site's main page**: `/` **307 | bdr/src/app/landing/page.tsx, bdr/src/app/security.css, bdr/src/flow/screens/SecurityLanding.tsx, bdr/src/content/security.ts, bdr/src/components/LogoSymbol.tsx, bdr/src/components/AssistantMark.tsx, bdr/src/components/Ico.tsx, bdr/src/components/Particles.tsx, bdr/next.config.ts, bdr/eslint.config.mjs |
 | [Vapi Integration — Assistants, Tools, Structured Output](features/vapi-integration.md) | Everything inside Vapi: the three assistants, the three shared tools, the shared structured-output schema, the Liquid-templated system prompt, and the Python sc | ai-bdr/vapi/templates/assistant.template.json, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md |

package/knowledge/2.0/apps/ai-bdr/features/campaign-chat-handoff.md

@@ -0,0 +1,190 @@
+---
+title: AI-BDR Campaign Chat — Backend Contract + Frontend Widget Handoff
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: active
+updated: 2026-08-24
+owners: [tcox]
+files:
+  - ai-bdr-campaign-handoff.md
+related:
+  - security-landing-page.md
+  - web-funnel-app.md
+  - ../architecture.md
+  - ../../talos/features/aegra-api.md
+---
+
+## What this is
+
+The consolidated backend + frontend handoff for the **AI-BDR campaign chat** — a
+grounded AI-BDR chat widget for landing pages, powered by the Talos backend at
+**`https://api.togaiq.com`**. A landing page passes an opaque `campaign_id`; the
+backend resolves the owning tenant, grounds the answer in that campaign's
+distilled PDF collateral, and returns **markdown prose + a structured `data`
+object** carrying the interactive UI (quick-reply chips, one CTA button, cited
+deck slides) and a **silent lead/qualification signal**.
+
+**Authoritative source:** `ai-bdr-campaign-handoff.md` (the single consolidated
+handoff; supersedes `docs/talos-bdr-generative-ui-contract.md` and
+`docs/ai-bdr-campaign-backend-handoff.md`, which are retained for history;
+architecture deep-dive in `docs/ai-bdr-campaign-chat-architecture.md`). This
+knowledge doc distills the contract and records the load-bearing decisions and
+gotchas — the source handoff carries the full copy-paste implementation code.
+
+**Direct relevance to BDR:** the cybersecurity landing page's inert
+**"Ask Me Anything"** header CTA (see [security-landing-page.md](security-landing-page.md) —
+the mockup's un-ported chat drawer) is exactly the kind of consumer this widget
+was specified for, and the first live campaign is **"External Pen Testing"** —
+the same offer the landing page sells.
+
+## Design decision (settled — do not re-litigate)
+
+Response format is **markdown + structured action data** (Option A), chosen over
+XML component tags / component trees / AG-UI: markdown fails soft and fits a
+non-streaming reply; the interactive actions live in a reliable JSON side-channel
+(`data`), never embedded in the prose. Consequences:
+
+- **No XML parser and no tag allowlist** on the frontend (the prior XML-tag
+  version required both).
+- **No server-side normalization** — `message` is returned exactly as the model
+  produced it.
+
+## Backend (what exists, verified live 2026-08-21)
+
+- **Model:** Claude Sonnet 4.6 (`us.anthropic.claude-sonnet-4-6`), server-pinned,
+  via tenant **True**'s Application Inference Profile (cost-attributed Bedrock
+  spend). Temp 0.7, max tokens 1200. **Non-streaming direct Bedrock** via
+  `ai_chat_service` (not `talos_agent`, not `deep_agent`).
+- **Grounding:** per campaign = a few PDFs → distilled markdown (≤8k chars/doc,
+  ≤24k aggregate) + per-page rendered images. **No KB / vectors / RAG.** Injected
+  server-side; the browser never sees or supplies it.
+- **Tenant resolution:** `campaign_id` → control-plane `campaign_registry` →
+  `org_id` → tenant DB. Only `status='active'` campaigns resolve. No
+  `campaign_id` → falls back to `TALOS_CHAT_ORG_ID=True` (plain togatech.com
+  chat). The browser cannot forge a tenant.
+- **Prompt + schema in one place:**
+  `libs/aegra-api/src/aegra_api/services/talos_chat_prompt.py`
+  (`TALOS_SYSTEM_PROMPT` + `TALOS_OUTPUT_SCHEMA`). To add an interactive element:
+  add a field to the schema there + a renderer in the app's allow-list.
+
+## Endpoints (base `https://api.togaiq.com`)
+
+| Method & path | Auth | Called by |
+|---|---|---|
+| `POST /api/ai/talos-session` | none (origin/UA gated) | Browser |
+| `POST /api/ai/talos-chat` | `Bearer <session_token>` | Browser |
+| `GET /api/ai/campaign/{campaign_id}` | none (origin/UA gated) | Browser |
+| `POST /api/ai/campaigns` | `X-API-Key` (`campaign:manage`) | **Backend/ops only** |
+
+- **Session:** `talos-session` mints a **15-min JWT** bound to a browser
+  `fingerprint` (exactly 64 lowercase hex) + IP + User-Agent. Anti-abuse only —
+  carries no tenant. Bot UAs (curl/postman/axios) are denylisted; requests need
+  real browser `Origin`/`Referer`/`Sec-Fetch-*` headers.
+- **Chat request:** `messages` (1..30, alternating, starts AND ends with `user`),
+  `fingerprint`, optional `campaign_id`. Body is `extra="forbid"` — sending
+  `model`, `system_prompt`, `temperature`, etc. returns **422** (all model params
+  server-pinned). Unknown/draft campaigns fall back gracefully to the base
+  prompt, never a chat error.
+- **Campaign read:** resolves `cited_slides` page numbers to deck images.
+  Unknown/draft/archived → 404.
+
+## Response contract
+
+```jsonc
+{ "message": "<markdown>", "data": { … } | null }
+```
+
+`data` fields — every one optional/nullable:
+
+| Field | Rendered? | Meaning |
+|---|---|---|
+| `name`, `email`, `company`, `phone` | **NO** | Silent lead capture |
+| `intent`, `use_case`, `timeline`, `qualified` | **NO** | Silent qualification |
+| `suggestions` (string[], 2–4) | Yes | Quick-reply chips; click sends chip text as next user message |
+| `cta` (`{label, action}`) | Yes | One CTA; `action` ∈ `book_call` \| `contact` \| `learn_more` |
+| `cited_slides` (number[]) | Yes | Deck pages backing the answer; resolve via the campaign read |
+
+**Never render the lead/qualification fields** — they feed CRM/lead routing
+only. Only `suggestions`, `cta`, `cited_slides` are rendered, from an app-owned
+allow-list.
+
+## Frontend build (for the widget consumer, e.g. the bdr landing page)
+
+- **Stack:** React 18/19, `@assistant-ui/react` + `@assistant-ui/react-markdown`
+  (install latest, then **pin exact versions** — same pin discipline as blox).
+- **Runtime:** `useLocalRuntime` + a custom `ChatModelAdapter.run()` that (1)
+  lazily mints/refreshes the session token (stable 64-hex fingerprint persisted
+  in `localStorage`; re-mint on 401), (2) POSTs the chat turn, (3) returns
+  `message` as markdown text and stashes `data` for the action row + silent lead
+  collection. Full working adapter code is in the source handoff §6.2.
+- **`cta.action` wiring:** `book_call` → campaign's Calendly `cta.url` from the
+  campaign read (**currently `null`** on the first campaign — hide or fall back
+  to a contact prompt); `contact` → site contact form; `learn_more` → relevant
+  page; unknown action → render nothing. Keep booking behind one function — a
+  future backend tool-call will replace the `book_call` CTA with direct
+  auto-booking.
+- **Lead handling:** silently accumulate the lead fields across turns;
+  auto-submit to CRM when enough is present (e.g. `email` + `qualified: true`).
+
+**SAFETY (required):** render `message` only through the markdown renderer with
+raw HTML disallowed (never `dangerouslySetInnerHTML`); links allow only `https:`
+and same-origin relative (deny `javascript:`, `data:`, `http:`); `data` is
+untrusted — `suggestions` render as plain text, only the three known
+`cta.action` values are acted on; no `eval`, no dynamic component construction
+from `data`.
+
+## First live campaign (real values)
+
+- **campaign_id:** `43fdf2b6-7a5d-4e85-be6b-911f42aa787f` — "External Pen
+  Testing", org `True`, 3 documents / 3 pages, verified live 2026-08-21.
+
+## The `campaign:manage` API key (ingest) — VALUE NOT RECORDED HERE
+
+`POST /api/ai/campaigns` (ingest) is gated by an `X-API-Key` with scope
+`campaign:manage` (tenant True), **key_id `2c2a4389-272f-4f05-b36f-f9b6f3de033f`**.
+
+- **The key VALUE is deliberately not in this doc** (team rule: no secrets in
+  git). It lives in the **secret manager** and in the source handoff file.
+- The scope can only create/ingest campaigns — no data/agent/model/tenant-admin
+  access.
+- **The source handoff embeds the value in plaintext per an owner decision** —
+  the handoff itself says to **rotate this key (revoke key_id `2c2a4389-…`,
+  re-mint) before go-live**. Treat any copy of that file as secret-bearing.
+- New campaigns: ingest via that endpoint, or on the box via
+  `scripts/create_campaign_api_key.py` + `scripts/seed_campaign.py`.
+
+## Gotchas
+
+- **Presigned deck-image URLs EXPIRE (~7 days).** `image_url` is a presigned S3
+  URL because `CAMPAIGN_ASSET_CDN_BASE_URL` is currently unset — do not cache
+  long-term; re-fetch the campaign read on page load / image error. Once the
+  CloudFront+OAC base URL is set, these become stable CDN URLs.
+- **Rate limits are currently LIFTED (accepted risk, owner decision).**
+  Per-visitor limiting is effectively off while `TALOS_CHAT_TRUSTED_PROXY_COUNT`
+  is unset and XFF handling is unfixed. Do not revert until the owner revisits.
+  (The proper fix mirrors BDR's own trusted-XFF-position lesson — see
+  [web-funnel-app.md](web-funnel-app.md)'s rate-limiter gotchas.)
+- **`extra="forbid"` on the chat body** — any speculative extra field (a model
+  override, a temperature) is a 422, not ignored.
+- **Message list shape is strict:** alternate user/assistant, start and end with
+  `user`, max 30.
+- **`book_call` CTA can arrive while the campaign's Calendly URL is null** —
+  the widget must degrade gracefully (the first campaign currently has
+  `cta: null`).
+- **Never advance the prod DB ahead of the deployed image** —
+  `verify_tenant_schemas` blocks startup on a head mismatch and crash-loops the
+  fleet (`campaign_tables_v1` is operator-run per tenant DB before rollout).
+- **The `X-Internal-Service-Key` bypass in `handle_chat` must remain
+  internal-only** now that campaign traffic rides the same path.
+
+## Change history
+- 2026-08-24 — Initial doc: captured the consolidated AI-BDR campaign chat
+  handoff (backend contract at api.togaiq.com + frontend widget spec on
+  assistant-ui). Markdown + structured-data format settled over XML tags;
+  keyless browser auth via 15-min fingerprint-bound session tokens; silent
+  lead/qualification side-channel; first live campaign "External Pen Testing".
+  The `campaign:manage` key VALUE deliberately omitted (no secrets in git) —
+  key_id recorded, rotate-before-go-live flagged. (tcox)

package/knowledge/INDEX.md

@@ -28,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 7 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) — 10 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
+- **ai-bdr** (AI-BDR) — 11 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 12 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 10 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)

package/knowledge/sessions/2026-08-24-surface-missed-migrations-apeterson.md

@@ -0,0 +1,91 @@
+---
+type: session
+slug: surface-missed-migrations
+title: Recover surface-layer migrations missed in the first prod push
+author: apeterson
+repos: [dbchanges2, _underscore, api2, toga25-supply]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-08-24
+updated: 2026-08-24
+---
+
+# Session: surface-missed-migrations
+**Date:** 2026-08-24
+**Project/Repo:** dbchanges2 (+ _underscore, api2, toga25-supply) (2.0)
+**Task:** Find and re-land the surface-layer dbchanges2 migrations that were skipped in the 2026-08-21 first prod push of the Surface layer, and write cluster-safe prod ports for the ones that can never run on prod as originally authored.
+
+---
+
+## What WORKED
+
+- **Diagnosed the Quad Approve "PO entered" gate from data, not assumption.** Query on local `Client_Quad.SurfaceOverrides` returned only two `VISIBILITY_RULE` rows (elements 32, 124) and **zero** `ENABLED_RULE` rows; `SHOW COLUMNS ... LIKE 'attribute'` confirmed the ENUM already contained `VISIBILITY_RULE`/`ENABLED_RULE`. This ruled out the documented Quad ENUM-coercion trap and the junk-`attribute=''` scenario, leaving "the file simply never ran."
+- **`Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql` — applied locally, verified working.** Approve is now disabled when no PO is present on both the record-actions bar and the listing row menu, and the tooltip reads "Add a PO Number to Approve". Merged file contains four statements: two `ENABLED_RULE` inserts (surface 8/element 17, surface 3/element 29, `{"type":"poNumberEntered"}` in `c_longValue`) plus an `INSERT`+`UPDATE` pair on `MessageTranslations` messageId 25.
+- **Verified the inlined Core ids against live local Core** before trusting the port: query returned exactly `(surface 8, element 17)` and `(surface 3, element 29)` for `actionSlug = salesOrder.approve`. Also revealed element 17 carries a base `enabledRule` and element 29 does not.
+- **Cluster-safety audit of all four prod-port files passed.** A grep for foreign-database qualifiers in executable (non-comment) SQL across `Client_Quad`, `Client_Compass`, `Client_CompassCanada`, `Client_Nychh` 2026-08-24 files returned **zero** references outside each file's own database.
+- **Confirmed `Client_Nychh/2026-08-24` had already been applied locally** — `SELECT surfaceId, surfaceElementId FROM SurfaceOverrides WHERE attribute='CONFIG'` returned `40 / 120` with nothing at `41 / 125`.
+- **Confirmed Quad's decision-summary hides landed correctly** — elements 125, 131, 132 all at `IS_VISIBLE = '0'` locally.
+- **Traced the tooltip failure to the framework, by reading code.** `Surface.php:937` guards the `MessageTranslations` overlay on `$languageId > 0`; `V2.php:5741-5745` carries an explicit TODO that the JWT never populates `id.client.languageId`. Developer then found they were on a stale `_underscore` branch; switching branches fixed it locally.
+- **Found the missing Core file.** `Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql` re-lands `Core/2026-07-20e`, which never reached prod — elements 29/30 were left at `isVisible=0` by `2026-07-20d` for every tenant.
+- **Rewrote the comments on 9 migration files** to the `backend-php.md` standard (no prose preamble, one short `#` comment per statement). Preambles of 45-68 lines cut to 6-25. **No SQL altered** — verified by line/comment counts and a zero-hit grep for leftover `-- ---` banners.
+- **`/capture` published 5 doc UPDATEs** to the team KB (`PUSHED to _main`, validate OK, 410 docs indexed).
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Do NOT tell anyone to clear `~/toga/cache/surface_meta/*.json`.** I gave this instruction from a stale KB claim. It is wrong: `_underscore/Model/Core/Surface.php:55` states *"build the bundle fresh on every request — the frontend caches via React Query; the backend intentionally holds no surface cache"*, and the directory is empty, last modified 2026-08-21, with a `surface_meta_bak` sibling. There is no backend surface cache to clear.
+- **Do NOT tell anyone a hard reload clears the FE surface-meta cache.** It does not. `toga25-supply/src/App.tsx` wraps the app in `PersistQueryClientProvider` + `createSyncStoragePersister` writing to localStorage key `supply-chain-query-cache`, and `useFetchSurfaceMeta.ts` sets `staleTime`/`gcTime` to `Infinity`. A reload **restores** the stale bundle. Only **logout** clears it (`AuthContext.tsx:124-126` → `localStorage.clear()` then `queryClient.clear()`), or manually deleting that key.
+- **Do NOT conclude the missing `branch` key in `.ebextensions/git.sandbox-client.json` is a misconfiguration.** I claimed this was the root cause of sandbox running old framework code. It is wrong. `.ebextensions/git.php` resolves `$branchName = property_exists($git,'branch') ? $git->branch : ('_' . strtolower($env))` — omitting the key correctly derives `_sandbox-client` from the EB `ENVIRONMENT` variable. Removing it was intentional and correct.
+- **Do NOT conclude `_resolveLanguageId()` was never implemented, or that the knowledge base was wrong about it.** I asserted both, with three pieces of corroborating evidence (`Surface.php:54/73` reading `id.client.languageId` with `returnIfNotSet: 0`, a repo-wide grep returning zero matches, and the `V2.php` TODO). All three were accurate **for the branch that happened to be checked out**, and the conclusion was still wrong. `_resolveLanguageId` exists on `_sandbox-client`, `_sandbox-dev`, `surface-layer` and `origin/_beta`, merged into `_sandbox-client` on **2026-07-22** via `6809c6b9`. Because `_underscore` is pulled at deploy from a moving per-environment branch, always run `git branch --show-current` before declaring framework code absent.
+- **Do NOT propose changing `Surface.php` or `V2.php` to fix the `languageId` overlay.** I recommended this (option B: resolve a fallback from the client `Languages` row). It is unnecessary — the fix already exists and shipped over a month ago.
+- **Do NOT redact secrets with an ad-hoc shell one-liner.** I ran `sed 's/\("\(token\|password\)"...\)/.../gi'` over `.ebextensions/git.*.json` intending to mask the value. **BSD `sed` on macOS does not support `\|` alternation**, so the pattern never matched and the GitHub PAT printed in full into the transcript. Use the `Read` tool for credential-bearing files.
+
+## Not tried yet (candidates for next session)
+
+- Applying the four prod-port files to **sandbox-client**: `Core/2026-08-24`, `Client_Compass/2026-08-24`, `Client_CompassCanada/2026-08-24` (Quad's already ran there). Then to prod.
+- The three **pre-flight prod checks** drafted but never run against prod Core: verify inlined ids 17/24/29/31/120 resolve (and that 125 does **not** exist yet); verify `SELECT id, name FROM Roles WHERE name='Admin'` returns exactly one row in `Client_Compass` and `Client_CompassCanada`; check `SHOW WARNINGS` after the `INSERT IGNORE` Core reseed.
+- **Finding the executor's applied-file log.** The highest-leverage unfinished thread: the executor records which files it has applied ("won't replay `07-21a/b`"), so if that record is queryable, the whole missed-migration hunt becomes a list diff instead of per-file state inference. `SHOW TABLES LIKE '%hange%' / '%igration%' / '%cript%'` against Core was drafted but never run. **Start here** — it would make the remaining client-DB sweep exact.
+- The **per-client sweep** of the 6 client DBs (the last session swept Core only, 17 files, found 1 gap). No equivalent sweep has been done for `Client_Compass`, `Client_CompassCanada`, `Client_Quad`, `Client_Nychh`, `Client_Elite`, `Client_Prudential`.
+- **Enter PO modal from the listing row menu** — FE gap, not data. `EnterPoNumberModal` is mounted only inside `SalesOrderRecordModalLayout`/`SalesOrderView`, so it is unreachable from the listing row-action dispatch.
+- **NYCHH inventory topology behavior change** needs developer sign-off before shipping.
+- Deciding whether the **reserved-Core-id-literals rule** should be promoted from the two feature docs into `2.0/standards/backend-php.md` (an ELEVATED doc — needs review).
+- Renaming `Client_Nychh/2026-08-24 - Fix...` to add its missing `a` letter suffix (deliberately deferred — see Decisions).
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql` | Modified, applied local + sandbox | Merged the enable rule and the tooltip into one file; unqualified tables; comments trimmed. `08-24b` was created then deleted after merging. |
+| `dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql` | Modified (comments only), applied local | Not yet on sandbox or prod. |
+| `dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql` | Modified (comments only) | Applied to sandbox this session; not prod. |
+| `dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql` | Modified (comments only) | Applied to sandbox this session; not prod. |
+| `dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql` | Modified (comments only), applied local | Filename missing its `a` letter suffix. MUST ship with `Core/2026-08-21`. |
+| `dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql` | Modified (comments only) | Applied local + sandbox. |
+| `dbchanges2/Client_Compass/2026-08-21 - SalesOrderDecisionSummaryTotalConcat.sql` | Modified (comments only) | Applied local + sandbox. |
+| `dbchanges2/Client_CompassCanada/2026-08-21 - SalesOrderDecisionSummaryTotalConcat.sql` | Modified (comments only) | Applied local + sandbox. |
+| `dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql` | Modified (comments only) | Applied local + sandbox. Comment now notes the `NOT EXISTS` guard cannot correct a wrong value. |
+| `toga-tech/knowledge/` (5 docs) | Updated + pushed to `_main` | surface-resolver, surface-frontend, api2 branch doc, surface-layer-schema, nychh profile. |
+
+**Nothing is committed in `dbchanges2`** — all changes are working-tree only, on branch `TRUE-81190`.
+
+## Decisions made
+
+- **Merge the tooltip fix into `08-24a` rather than keep a separate `08-24b`.** Rationale: both were unapplied everywhere, same client, same feature (the gate and the tooltip explaining it). Rejected: two files, which would have needed independent tracking for no benefit.
+- **Handle the tooltip with `INSERT ... NOT EXISTS` *plus* `UPDATE`.** Rationale: prod has no row, local/beta has one with the older "Enter PO Details First" text; the pair converges on the correct value from either starting state. Rejected: insert-only, which would silently no-op on local.
+- **Leave `Client_Quad/2026-08-21`'s insert-only `NOT EXISTS` guard alone.** Rationale: it is already applied to local and sandbox, and the repo rule forbids editing an already-run migration. Verified all three elements hold the correct `'0'` value, so there is no live defect. If prod turns out to hold a wrong row, that becomes a new dated file.
+- **Do not rename `Client_Nychh/2026-08-24`** to add its missing letter suffix. Rationale: the executor tracks applied files by name, so renaming would present it as a new file and re-run it. It is idempotent so that would be harmless, but there is no upside.
+- **Keep two things when trimming the verbose comments:** the Core reseed's element id map (client override files hardcode those numbers) and the NYCHH ship-together warning. Rationale: both are expensive to rediscover and neither is inferable from the SQL.
+- **Keep the Admin `roleId` as a runtime lookup** in the Compass/CC ports rather than inlining it. Rationale: role ids are per-client and per-environment (Compass Admin=4, Compass Canada=5 locally) and `Roles` lives in the same database being written to, so the lookup is cluster-safe. Every statement is guarded on `@adminRoleId IS NOT NULL` so a missing role is a no-op rather than a bad write.
+
+## Blockers
+
+- **The GitHub PAT in `api2/.ebextensions/git.*.json` must be rotated.** It is committed across ~20 per-environment files and in git history, and received additional exposure this session via the failed-redaction incident above. Treat as compromised; rotate and move to SSM Parameter Store / EB environment properties. This is the one open action from this session that lives outside a file.
+- **NYCHH inventory topology change awaits developer sign-off**, and its fix cannot ship without `Core/2026-08-21` in the same release (or NYCHH's Assigned Manager breaks).
+- Not blocking, but unresolved: the sandbox tooltip was still showing the Core default at the point the session ended. Data was verified correct in sandbox (`MessageTranslations` messageId 25 = "Add a PO Number to Approve", `Languages` has `en` at id 1) and the `_sandbox-client` branch has carried `_resolveLanguageId` since 2026-07-22 — so the open question is whether that environment has been **redeployed** since, or whether the reading was taken from a persisted FE cache.
+
+## Exact next step
+
+> Log out of sandbox-client supply and log back in (this is the only thing that clears the persisted `supply-chain-query-cache` localStorage entry), then re-open a Quad order with no PO and read the `salesOrder.action.approve.disabled` value in the `/v2/surfaces/meta` response **in the Network tab**, not from cached state. If it still reads "Assign a Manager to Approve", check when the api2 sandbox-client environment last deployed — `_underscore` is cloned at deploy time, so an environment that has not deployed since 2026-07-22 is running framework code without `_resolveLanguageId()`.
+
+---
+_Saved by /session-save on 2026-08-24_

package/package.json

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