toga-ai 1.0.483 → 1.0.485

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 40 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 36 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 37 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 20 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
@@ -39,7 +39,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
-- **claude** (Claude Harness) — 2 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
+- **claude** (Claude Harness) — 3 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
 
 ## Clients
 

package/knowledge/sessions/2026-07-30-TRUE-80487-Debug-Fix-Rate-WH-Warranty-mhammontree.md

@@ -0,0 +1,97 @@
+---
+type: session
+slug: TRUE-80487-Debug-Fix-Rate-WH-Warranty
+title: Rate Whole Home Warranty per-address dedup — root-caused "works in beta, fails in prod"
+author: mhammontree
+repos: [_underscore, toga2-view, dbchanges2, test]
+framework: "2.0"
+client: rate
+status: active
+created: 2026-07-30
+updated: 2026-07-30
+---
+
+# Session: TRUE-80487-Debug-Fix-Rate-WH-Warranty
+**Date:** 2026-07-30
+**Project/Repo:** _underscore / toga2-view / dbchanges2 / test (2.0)
+**Task:** Production troubleshooting of the Rate Whole Home Warranty per-address duplicate-purchase guard (TRUE-79533, already deployed), reported as "works in beta, not in production" — root-caused to three independent code defects, none of them a deployment gap.
+
+---
+
+## What WORKED
+
+- **Eliminated every deployment-gap hypothesis with hard evidence.** `_underscore` `_production` HEAD is `ba7eff66` (TRUE-79533 PR #661 merged 2026-07-29); `dbchanges2` `_main` is `138df5e` (PR #418). `git diff origin/_beta -- Model/Rate/Entitlement.php` returns **zero diff** — prod and beta run identical code.
+- **Confirmed all prod DB artifacts present.** `Core.RecordFields` id **2482** = `entitlements.serviceAddressId` registered; `Client_Rate.Entitlements.serviceAddressId` column + index exist; ACL grants present (`2482` → role 1 `isWritable=0`, mirroring `saleItemId` 1265; `addresses.id` field 41 → roles 1,2,3). `ApiPayloadInterceptors` in prod is **byte-identical to dev-sandbox** (id 4 = rec 191 PRE/POST `minDepth NULL`; id 2 = rec 191 POST/POST `minDepth 5`).
+- **ROOT CAUSE #1 — the backend guard has never executed, in any environment.** `isWholeHomeWarranty()` at `_underscore/Model/Rate/Entitlement.php:116-118` reads `$payload->saleItem->title`, but the real checkout payload sends `"saleItem":{"uuid":"3e14effa-0f78-4708-b338-60872a39aff3"}` with **no `title`**. `stripos('', 'warranty')` → false → `prePost` returns at line 58 before the guard runs. Evidence: beta payload for entitlement 106, `Logs_Rate.Api` id 48823 (dev-sandbox, 2026-07-27 11:41:15), verbatim.
+- **Proved it with beta's own data.** dev-sandbox has **three active WH entitlements at the same address** `1864 HIGH GROVE LN 60540`: `ET100057` (id 90, 2026-07-24), `ET100067` (id 100, **2026-07-27 10:10**), `ET100073` (id 106, **2026-07-27 11:41**) — two created on the very day the feature was marked "beta-verified". Plus two at `121 N LA SALLE ST 60602` (`ET100071`, `ET100072`). All same borrower `5686507f-a7b2-4fca-b007-dd3ae875e4bb`, all pinned, all active.
+- **Confirmed the guard's rejection message appears in NO log, in either environment, ever.** All 8 beta `POST /v2/entitlements` 400s are `EV-12` (reference errors) and one `EV-8` (`contractFulfillmentPreference`, 2026-07-15, pre-dating the PRE interceptor registration).
+- **ROOT CAUSE #2 — `state.code` vs `state.uuid`.** `prePost:66` reads `$address->state->code`, but the payload sends `"state":{"uuid":"94417b26-..."}`. Fixing #1 alone would make every WH purchase throw *"A valid service address is required"* — a false rejection on valid addresses. **Both must be fixed together.**
+- **ROOT CAUSE #3 — frontend availability check fails open AND is borrower-scoped.** `toga2-view/src/pages/ZipValidation/viewModels/useZipValidationViewModel.ts:135-139` — `const address = entitlement.serviceAddress; if (!address?.line1) return false;` and `serviceAddress` is derived only from the pin (`useActiveServices.ts:108`). Worse, `useActiveServices.ts:69-71` scopes the query `where: { and: [{ "Customers.c_borrowerId": { "=": borrowerId } }] }` — so it can **never** see another borrower's warranty, while the backend guard is explicitly global. Its code comment claims "same source as the backend guard's dedup join" — that comment is wrong; the backend uses `COALESCE(serviceAddressId, ContactAddresses.addressId)`, the frontend has no fallback.
+- **Verified the backend WOULD block, without paying.** Replicated `hasActiveWarrantyAtAddress()` SQL read-only against prod for `1864 HIGH GROVE LN / Naperville / 60540 / IL` → returns entitlement **43 (`ET100017`)**. So a real purchase reaches PayPal, the customer is charged, and *then* the entitlement POST is rejected.
+- **Confirmed the apartment-building exposure is real.** Property type lives only in router state / `sessionStorage` (`useCheckoutPageViewModel.ts:178-205`) and is **never sent to the API** — the purchase payload contains no `propertyType` / `isEligible`. `prePost:68-70` requires line1/city/state/zip but **not** `line2`. The `requireUnitNumber` flow (`ZipValidation.tsx:62-75`, `198-199`) is client-side only and bypassable. Live proof: beta `ET100073` carries `line2: "STE 500"` on a single-family home, while ids 90/100 at the same `line1` have no unit.
+- **Production data repaired by the developer and verified clean.** Three active WH warranties, all pinned + validated, both-or-neither invariant holds on all nine rows: 43 (`ET100017`) → addr 9 Naperville, 40 (`ET100014`) → addr 6 Nashua, 38 (`ET100012`) → addr 4 Wailuku. Subscription 22 (`ET100015`, Daniel Moran) closed out `isActive=0, dateCancelled='2026-06-03'`; address 7 `city` corrected `60657` → `Chicago`.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **"A migration is missing in production."** DISPROVEN. `Core.RecordFields` 2482 exists; `Client_Rate.Entitlements.serviceAddressId` column + index exist; both ACL grants landed. Do not re-audit `Core/2026-07-22a`, `Client/2026-07-22a`, `Client/2026-07-23a`, `Client_Rate/2026-07-23a`, `Client_Rate/2026-07-24a` — all applied.
+- **"TRUE-79251 merge damage deleted the WH helper methods."** DISPROVEN. `git diff origin/_beta -- Model/Rate/Entitlement.php` → zero diff. `PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` (line 32) and all three private helpers (`normalizedField` 107, `isWholeHomeWarranty` 116, `hasActiveWarrantyAtAddress` 137) present.
+- **"`_underscore` prod wasn't redeployed past the uuid-clobber fix `9c2e4b1c`."** DISPROVEN by the same zero diff + PR #661 merged.
+- **"`toga2-view` prod still sends `{depth:-1}` and starves `postPost`."** DISPROVEN. `genericApi.ts:54,68` only append `?depth=-1` when `returnPayloadDepth` is explicitly set; no checkout override. Diff vs `_beta` touches only GetSupport files.
+- **"Cross-cluster `Core.RecordFields` references from `Client*/` migration folders fail in prod."** DISPROVEN for this case. Despite prod splitting `prod-core` / `prod-client` / `prod-logs` / `prod-archive` onto separate clusters, the ACL grants landed correctly. ~20 long-standing ACL migrations use this same pattern. (Note: the `dbchanges2-cluster-isolation` hook was NOT found under `.claude/hooks/toga/` — separate follow-up, not this bug.)
+- **"The interceptor row is missing, inactive, or duplicated in prod."** DISPROVEN — prod rows are identical to dev-sandbox, same ids and uuids.
+- **"`POST /v2/entitlement-sales-orders` is the prod purchase path (record 257, no interceptor)."** DISPROVEN. It is only a bridge link: payload is `{"entitlement":{"uuid"},"salesOrder":{"uuid"}}`. It creates no entitlement and fires no interceptor.
+- **"Production simply hasn't processed a purchase since deploy, so there's nothing to debug."** TRUE as a fact (last `POST /v2/entitlements` in prod = 2026-07-10, two × 400 `EV-8`; newest `Entitlements` row 2026-06-15) but WRONG as a conclusion — the developer then reproduced the failure live through the UI. Do not stop at this observation.
+- **Query that hangs — do not run.** `SELECT ... FROM Logs_Rate.Api WHERE route LIKE '%address%'` timed out after **300s** (unindexed full scan on a ~12.7M-row table). Always constrain with the `dtStamp` index: `WHERE dtStamp >= '...' AND dtStamp < '...'`.
+- **Columns that do not exist (queries will error).** `Client_Rate.ApiPayloadInterceptors.phpMethod` — absent in prod (yet `Client_Rate/2025-12-10 - PostInterceptor.sql` inserts it, so that file is not re-runnable). `Client_Rate.Contacts.emailAddress` — does not exist. `Logs_Rate.Api.uri` — the column is `route`.
+- **Widening the frontend `useActiveServices` query to all borrowers.** REJECTED, do not do this — it would let any portal user read other customers' entitlements and addresses. A data-leak fix worse than the bug.
+
+## Not tried yet (candidates for next session)
+
+- Fix `isWholeHomeWarranty()` to resolve `saleItem.uuid` → item (fall back to payload `name` and/or `WH_SALE_ITEM_ID = 3`), matching the authority `hasActiveWarrantyAtAddress()` already uses in SQL.
+- Fix state resolution to accept `state.uuid` with `state.code` as fallback.
+- Normalize zip to first 5 digits in the dedup comparison (`Entitlement.php:161` is exact-match; frontend already truncates at `addressCompare.ts:22`). Untested risk: USPS returning `60540-9233` vs stored `60540`.
+- Normalize the unit designator before comparison so `STE 500` / `Suite 500` / `#500` / `Unit 500` collapse to one dwelling.
+- Build the server-side global pre-check: boolean-only scripted endpoint reusing `hasActiveWarrantyAtAddress()`, called from the availability step, deleting the frontend's local dedup. Needs a `dbchanges2` migration registering it in `Core.RecordScripts` **plus** the client ACL grant — note `validateAddress` (RecordScripts id 17) exists only in the live DB and NOT in `dbchanges2`, the exact parity trap to avoid.
+- Log one raw USPS / FedEx / UPS validation response for a known apartment vs a known single-family address, to settle field names empirically. `Fedex.php:417-421` already receives the full `attributes` object and reads only `Matched` / `Resolved`; `Ups.php:801-807` reads only `NoCandidatesIndicator` / `Candidate`.
+- Capture the USPS DPV "valid but secondary unit missing" signal into `validateAddress`'s normalized return with an explicit unknown state, and enforce in `prePost`.
+- Send and persist `propertyType` with the purchase so eligibility is enforced server-side rather than trusted from the browser.
+- Update `test/@Mark/Rate/verify_wholehome_per_address_guard.php` to use the REAL payload shape (uuid-only `saleItem`, uuid-only `state`). It currently passes 18/18 against a shape production never sends — this is why all three defects survived review.
+- Clean up beta duplicates: dev-sandbox entitlements 100, 105, 106.
+- Controlled prod WH purchase to exercise the untested `minDepth = 5` on the POST interceptor, and to test USPS "Suggested" (`60540-9233`) vs "You entered" (`60540`).
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `_underscore/Model/Rate/Entitlement.php` | **investigated, NOT modified** | Holds root causes #1 (line 116-118) and #2 (line 66). Also: raw SQL string concatenation at lines 371/375 violates the parameterized-query standard; accepted TOCTOU noted at 133-135. |
+| `toga2-view/src/pages/ZipValidation/viewModels/useZipValidationViewModel.ts` | **investigated, NOT modified** | Root cause #3 fail-open at 135-139. Misleading comment claims parity with backend join. |
+| `toga2-view/src/hooks/useActiveServices.ts` | **investigated, NOT modified** | Borrower-scoped `where` at 69-71; pin-only `serviceAddress` resolution at 108; silent EZ-2 degrade at 90. |
+| `toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts` | **investigated, NOT modified** | `propertyType` read from router state / sessionStorage (178-205), never sent to API. |
+| `_underscore/Model/Client/Address.php` | **investigated, NOT modified** | `validateAddress` waterfall USPS→FedEx→UPS (31-46); returns success + normalized fields only, no unit-required signal. |
+| `_underscore/Component/Library/Carriers/{Usps,Fedex,Ups}` | **investigated, NOT modified** | Signals available but discarded. NOTE: this is a namespace inside `_underscore`, NOT the 1.0 `library` repo. |
+| `test/@Mark/Rate/verify_wholehome_per_address_guard.php` | **not opened** | Passes 18/18 against the wrong payload shape. Needs rewrite. |
+| **Production `Client_Rate` data** | **CHANGED by developer, verified** | Ents 43→addr 9, 40→addr 6, 38→addr 4 pinned; those 3 addresses `isValidated=1`; subscription 22 closed `isActive=0, dateCancelled='2026-06-03'`; address 7 `city` → `Chicago`. No repo files changed this session. |
+
+## Decisions made
+
+- **Keep `dateEnd` OUT of the dedup predicate.** Rationale: the guard's contract is `isActive = 1 AND dateCancelled IS NULL`; adding `dateEnd` would let real duplicates through when a renewal hasn't rolled `dateEnd` forward yet. Rejected alternative: filter on `dateEnd`. Confirmed instance of the underlying problem: Kimberly Stearns (`ET100014`) has `dateEnd = 2026-06-01` yet was charged 2026-07-01 — renewals are not advancing `dateEnd`. **Separate ticket.**
+- **Do NOT widen the frontend query to all borrowers; move the check server-side instead.** Rationale: the frontend fundamentally cannot answer "does anyone have a warranty here?" without exposing other customers' data. A boolean-only endpoint reusing the existing helper makes availability and purchase the same code path, so they cannot drift.
+- **Skip the legacy-entitlement backfill migration.** Rationale: only two rows mattered and they were fixed by hand; once the server-side check ships, pinning is no longer required for dedup correctness. Migration would be pure data churn.
+- **Do not chase "dwelling type" from shipping carriers.** Rationale: postal data models deliverability, not property characteristics — no carrier returns single-family vs multi-unit. UPS `AddressClassification` / FedEx `classification` only give Residential vs Commercial, and an apartment building is "Residential". The actionable signal is USPS DPV "secondary unit required but missing". True dwelling type needs property data (assessor/parcel, or Melissa/Smarty-class vendor) — a procurement decision for Paulina + underwriting.
+- **Did NOT complete the PayPal test payment.** Rationale: the backend rejects *after* the charge; the read-only SQL replication already proved what the guard decides.
+- **Branch naming = bare ticket ID `TRUE-80487`.** Rationale: matches live convention in all four repos (`TRUE-78188`, `TRUE-78314`, `TRUE-79191`, `TRUE-79868`). The documented `fix/short-description` rule in the git-workflow standard is stale — flag for correction.
+- **Repo scope:** minimum `_underscore` + `test` (makes the global rejection actually work); add `dbchanges2` + `toga2-view` for the server-side pre-check. `api2` NOT needed (scripted endpoints are served by the V2 engine from `_underscore` models; registration is DB-side). Recommendation: branch all four — an unused branch is free, discovering a needed migration mid-sprint is not.
+- **Reframed the ticket premise.** "Works in beta, fails in prod" is false. Same code, same migrations, same interceptor rows. Beta only *appeared* to work because its test data satisfied both frontend preconditions by accident — a single test borrower, and data created after the pin shipped. Production satisfied neither.
+
+## Blockers
+
+- **Need the current dev branch name** to base the four `TRUE-80487` branches on. `_underscore` shows `_beta`; `toga2-view` shows both `_beta` and `_stage`. Developer said they are on "a different dev branch now" — unresolved.
+- **Need a product decision from Paulina: per-dwelling or per-building coverage?** Currently `123 Main St` and `123 Main St APT 2` are distinct addresses, so both can hold a warranty. This changes what the fix does. Sharpened by the finding that a *no-unit* purchase at a multi-unit address is indistinguishable from a single-family purchase and carries building-scale liability at single-home pricing.
+- **Need a scope decision:** does property-type / unit-required enforcement land in TRUE-80487, or a separate ticket? Materially larger than "one warranty per address" — it is "what counts as an insurable address". The gate fixes are independent of both blockers and can proceed regardless.
+
+## Exact next step
+
+> Create the `TRUE-80487` branch on `_underscore` (base = the dev branch the developer names), then fix `isWholeHomeWarranty()` at `_underscore/Model/Rate/Entitlement.php:116-118` to identify a WH purchase by resolving `saleItem.uuid` → `Items` (with payload `name` / `WH_SALE_ITEM_ID = 3` as fallbacks) **together with** the `state.uuid` → `code` resolution at line 66 — never one without the other, or every WH purchase throws "A valid service address is required". Then run `test/@Mark/Rate/verify_wholehome_per_address_guard.php` rewritten to the real payload shape (uuid-only `saleItem` and `state`), and confirm it FAILS on the current code before the fix and passes after.
+
+---
+_Saved by /session-save on 2026-07-30_

package/knowledge/standalone/apps/claude/INDEX.md

@@ -4,3 +4,4 @@
 |-----|---------|-------|
 | [Harness Distribution — How a knowledge.js Fix Reaches Teammates](workflows/harness-distribution.md) | There are **two copies** of `knowledge.js` on a developer's machine, and the skills use only one of them. | claude/scripts/install.js, claude/knowledge.js |
 | [Knowledge Base Publish / Push Pipeline](workflows/knowledge-publish-pipeline.md) | How `/capture` and `/session-save` get knowledge docs from your working tree into `agilantsolutions/claude` on `_main`. | claude/knowledge.js |
+| [MCP Tool Usage — "Talos" Means the Internal Knowledge Base, and Run Your Own SELECTs](workflows/mcp-tool-usage.md) | Two MCP connections are available in every session, and **Claude is expected to reach for them on its own judgement — nobody should have to say the word "MCP".* | claude/.claude/skills/kickoff/SKILL.md, claude/.claude/skills/capture/SKILL.md |

package/knowledge/standalone/apps/claude/workflows/mcp-tool-usage.md

@@ -0,0 +1,177 @@
+---
+title: MCP Tool Usage — "Talos" Means the Internal Knowledge Base, and Run Your Own SELECTs
+framework: "standalone"
+repo: claude
+project: Claude Harness
+client: shared
+type: workflow
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - claude/.claude/skills/kickoff/SKILL.md
+  - claude/.claude/skills/capture/SKILL.md
+related:
+  - standalone/apps/claude/workflows/harness-distribution.md
+  - standalone/apps/claude/workflows/knowledge-publish-pipeline.md
+  - 2.0/apps/talos/features/mcp-servers.md
+---
+
+## Summary
+
+Two MCP connections are available in every session, and **Claude is expected to reach for them on
+its own judgement — nobody should have to say the word "MCP".**
+
+1. **`claude.ai Internal Knowledgebase`** — the AWS Bedrock knowledge base of cleaned meeting
+   transcripts. **This is what the team means when they say "Talos."**
+2. **`toga-db`** — read-only MySQL access to every TOGA environment, production included.
+
+**Critical rules:** When a teammate says **"ask Talos"**, **"use Talos"**, or **"check Talos"**,
+that is an instruction to **search the Internal Knowledge Base MCP** — it is *not* a request to
+open, read, or reverse-engineer the `talos` repo. Only treat "Talos" as the codebase when the
+speaker explicitly frames it as the project ("the Talos repo", "Talos deployment", "the Talos
+agent code"). **Never ask a developer to go run a SELECT** — Claude has read access and must run
+its own. **Writes (INSERT/UPDATE/DELETE/DDL) are the developer's to execute** — the MCP is
+read-only by design, so hand them the statement. Use both connections proactively as part of
+normal research, unprompted.
+
+## The word "Talos" is overloaded — resolve it by context
+
+| A teammate says | They mean | What to do |
+|---|---|---|
+| "Ask Talos", "use Talos", "check Talos", "what does Talos say about…" | The **Internal Knowledge Base MCP** | `kb_search` — this is the default reading |
+| "the Talos repo", "Talos deployment", "the Talos agent", "the LangGraph agent", "TOGa IQ" | The **`talos` codebase** (2.0, Python/FastAPI) | Open `2.0/apps/talos/` knowledge and the repo |
+
+**Default to the MCP.** The overwhelming majority of spoken uses of "Talos" mean the knowledge
+base. Reverse-engineering the `talos` project because someone said "ask Talos" is a real failure
+mode — it burns a session answering the wrong question.
+
+Note the collision in this knowledge base itself: `2.0/apps/talos/features/mcp-servers.md`
+documents the MCP servers that the **talos project builds and hosts** (`clickup-mcp`,
+`toga-db-mcp`). That doc is about *building* those servers. This doc is about *using* the
+connections. They are different subjects.
+
+> Aside: the team has not settled whether "Talos" is an engine, a chatbot, or the umbrella AI
+> brand, nor whether it is written `Talos` or `TALOS` (see the 2026-07-16 *TOGA Tech Website
+> Review* transcript). Ambiguity about what Talos *is* as a brand is expected; ambiguity about
+> what "ask Talos" *means operationally* is not — it means the knowledge base.
+
+## Internal Knowledge Base MCP ("Talos")
+
+Cleaned, classified meeting transcripts loaded automatically within 5–10 minutes of a meeting
+ending. This is the record of **what people actually said and decided** — the complement to this
+knowledge base, which records **how the code works**.
+
+- **Scope:** account-wide there are 40 knowledge bases across 7 categories; the harness API key
+  currently reaches **1 category, `development-team` (34 KBs)**. Other categories (sales, HR,
+  legal, contact-center, tech-support, operations) exist but are outside the key's grant.
+- **Shape:** one KB per client bucket, documents at
+  `s3://togaiq/development-team/<client>/approved/YYYY-MM-DD - <Meeting Title>.txt`, each with an
+  `approved_at` date. Ranking blends semantic relevance with recency.
+- **Client names differ from `registry.json`.** The KB uses `compass-group` (not
+  `compass-usa`/`compass-canada`), `health-and-hospitals` (not `nychh`), `nyc-doe` (not `nycdoe`),
+  and carries buckets with no registry entry at all — `northwell`, `endeavor-health`, `casl`,
+  `lenovo`, `adyen`, `speedcast`, `rumc`, `uma`, `craftex`, `dunn`, `interfaith-ministries`,
+  `ford-foundation`, `alpha-omega-plastics`, `american-campus-communities`, `ninja-rmm`, plus
+  non-client buckets `general`, `ai`, `power-bi`, `warehouse`, `toga-desk`, `toga-technology`.
+  Always pick the `client` value from the `available_clients` list the tool returns.
+
+**When to reach for it without being asked:**
+
+- A teammate relays something said in a meeting and the terminology is unfamiliar or ambiguous.
+- A decision's *rationale* matters ("why did we do it this way?") — git history says what
+  changed, transcripts say why.
+- Business-side vocabulary that has no code footprint (see the terminology gotcha below).
+- Before concluding "there is no knowledge about X" — check here as well as the code KB.
+
+**Treat transcripts as evidence, not specification.** They record what was said in a room,
+including things later reversed. Cite the filename and `approved_at` date, prefer the most recent
+when chunks conflict, and let the code knowledge base win on questions of how something is
+actually built.
+
+### Terminology that lives only in transcripts
+
+These have no footprint in the code knowledge base, so a code-only search returns nothing:
+
+- **TechHub** — what **TOGa Commerce** is called on the Compass side.
+- **Mix** — the Compass-side equivalent platform. A request to update "TechHub and Mix" means
+  both teams make the same change.
+- **TOGa Retail** — internal-only platform for store-associated transactions; not in `registry.json`.
+- **Personas** — TOGa Supply's item-visibility mechanism (~39 of them; 1 = everyone, 4 = canteen,
+  12 = admin and sees everything, 33 = MacBook/Surface).
+- **OptimumDesk / Star Tech** — the ticketing system Talos integrates with for Office Depot.
+- **TOGA vs toga** — capital-A **TOGA** is the company; lowercase **toga** is the platform.
+
+## Database MCP (`toga-db`)
+
+Read-only MySQL across every environment. All 24 clusters were connected as of 2026-07-30.
+
+**Run SELECTs yourself, unprompted.** Do not ask a developer to run a query and paste results
+back — that wastes their time on something Claude can do directly. Query whenever it answers the
+question faster or more reliably than reading code: confirming a schema, checking whether a row
+exists, verifying a config value, sizing a table before proposing a migration, or grounding a
+claim in real data instead of an assumption.
+
+**Writes are the developer's job.** The MCP permits `SELECT`/`SHOW`/`DESCRIBE`/`EXPLAIN` only.
+For any `INSERT`/`UPDATE`/`DELETE`/DDL, write the statement out, say which environment and schema
+it targets, and hand it to the developer to execute.
+
+**Environments** — pass any alias; the server resolves it:
+
+| Group | Names | Naming scheme |
+|---|---|---|
+| V2 production | `prod` / `production` | `Core`, `Client_<id>`, `Archive_<id>`, `Logs_<id>` |
+| V1 production | `legacy` / `v1` | `Core`, `TOGA_<id>`, `TOGaLogs_<id>` |
+| Non-prod | `dev-sandbox`, `client-sandbox`, `client-{alpha,beta,gamma}`, `qa-{task,hotfix,alpha,beta,gamma}`, `qc-{task,hotfix,security,performance,alpha,beta,gamma}`, `stage`, `demo` | V2 naming |
+
+**Production is four separate clusters** — `prod-core`, `prod-client`, `prod-archive`,
+`prod-logs`. Every non-prod environment is a single all-in-one host holding all groups. This is
+the same split that makes cross-database joins work locally and fail in production (see
+`2.0/apps/dbchanges2/architecture.md`).
+
+**`local` is not this MCP.** If someone means their own machine's database, use the `mysql` CLI
+via shell, not `toga-db`.
+
+**Resolving a client name to its databases:** `Core.Clients.clientIdentifier` is the exact suffix
+used in `Client_<id>`, `Archive_<id>`, and `Logs_<id>`.
+
+```sql
+-- environment='prod', schema_name='Core'
+SELECT name, clientIdentifier FROM Clients WHERE name LIKE '%<keyword>%';
+```
+
+### Gotcha — the client roster is wider than `registry.json`, and identifiers are not guessable
+
+`Core.Clients` held **46 clients** on 2026-07-30 against 17 in `registry.json`. A client absent
+from the registry is normal, not an error — the registry tracks clients whose *code knowledge* has
+been captured, not the full book of business.
+
+Identifiers do not follow from the display name, so **look them up, never construct them**:
+
+| Display name | `clientIdentifier` | Trap |
+|---|---|---|
+| Compass Group | `Compass_Usa` | Carries an **underscore**, and "Compass Group" maps to the **USA** entity |
+| CompassCanada | `Compass_Canada` | Underscore again |
+| AIG | `Aig` | Title-case, not `AIG` |
+| Staples | `Staples` | A **separate client** from AIG, despite the registry title "AIG (Staples Protection Plan)" |
+| Growrks | `Growrk` | Display name is plural, identifier is not |
+| NYC Health + Hospitals | `Nychh` | |
+| Towfoundation | `Towfoundation` | |
+| Wiss, Janney, Elstner Associates, Inc. | `Wje` | |
+
+Schema names are **case-sensitive** — copy the exact value from `toga_list_schemas` or
+`Core.Clients`. `Client_Aig` works; `Client_AIG` and `client_aig` do not.
+
+## Applying this
+
+- **Never make a teammate name the tool.** "Which environment is that in?" is a fair question;
+  "please run this SELECT and paste the output" is not.
+- **Ask about environment only when it genuinely changes the answer** — and when the context makes
+  it obvious (a production incident, a client-specific bug), infer it and say which one was used.
+- **State the source.** For a query: the environment and schema. For the knowledge base: the
+  filename and its date. That lets the developer judge the evidence.
+- **Combine the three sources.** Code knowledge base → how it is built. Talos → what was decided
+  and why. Database → what is actually true right now.
+
+## Change history
+- 2026-07-30 — Created. Established that "ask/use Talos" means the Internal Knowledge Base MCP and not the `talos` repo; that Claude runs its own SELECTs unprompted while developers execute writes; and that both MCP connections are used proactively without being requested. Recorded the KB↔registry client-name divergence and the `Core.Clients` identifier traps (jcardinal)

package/package.json

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