toga-ai 1.0.482 → 1.0.484

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-bdr-live-call-status-and-callback-bug-tcox.md

@@ -0,0 +1,201 @@
+---
+type: session
+slug: bdr-live-call-status-and-callback-bug
+title: BDR funnel live call status + real summary email, and AI-BDR callback root cause
+author: tcox
+repos: [bdr, worker2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-30
+updated: 2026-07-30
+---
+
+# Session: bdr-live-call-status-and-callback-bug
+**Date:** 2026-07-30
+**Project/Repo:** bdr (2.0), plus a read-only worker2 investigation
+**Task:** Make the BDR funnel usable by anyone (remove the contact-reference gate), drive the Success screen from real call data instead of a timed simulation, send the call summary by real email, and then root-cause a production bug where a callback requested during an AI-BDR call never happens.
+
+---
+
+## What WORKED
+
+- **Contact-reference gate removed.** Deleted the `hasLead` submit-block and the
+  `phone.missingContactNotice` copy key from `src/flow/screens/CallNow.tsx`,
+  `src/flow/screens/Schedule.tsx`, `src/content/schema.ts`, `src/content/default.ts`.
+  Evidence: grep for `hasLead|missingContactNotice` across the repo returns zero matches;
+  design-parity audit against `C:\WWW\BDR\mockup` confirmed the removal restored mockup
+  parity (the mockup never had the notice).
+- **Vapi's own API confirmed as a working live call-status source.** `GET https://api.vapi.ai/call`
+  returned HTTP 200 with the org's calls. Verified field shape: `id, status, type, createdAt,
+  startedAt, endedAt, endedReason, summary, transcript, recordingUrl, customer, analysis,
+  messages, cost`. Status enum `queued|ringing|in-progress|forwarding|ended`. Timestamps are
+  ISO-8601 UTC with `Z`. **Key fact: `createdAt` = placed, `startedAt` = ANSWERED,
+  `endedAt` = hangup.** A real call showed `createdAt 18:53:08 / startedAt 18:53:18 /
+  endedAt 18:53:35, endedReason "voicemail"` — the 10s gap is ring time.
+- **Fixed the worker dispatcher reply-prefix bug** in `src/server/workerDialer.ts`. The worker
+  wraps every reply as `[<requestId>] Successfully Executed (<n> seconds): <json>`, so the old
+  `response.json()` always threw: it logged "immediate dial not placed" on every SUCCESSFUL
+  dial and discarded the response body. Now strips the prefix before parsing and returns a
+  typed `DialResult` carrying `vapiCallId` / `attemptId`. Evidence: regression test asserts a
+  dispatcher-wrapped success reply no longer logs the false warning.
+- **Live call lifecycle on the Success screen.** New `/api/call-status` route, `vapiCall.ts`
+  server reader, `useCallStatusViewModel` polling hook. Mapping: `queued`/`ringing` -> dialing
+  with NO talk timer; `in-progress`/`forwarding` with `startedAt` -> active, timer counted from
+  the ANSWER time with server-clock-offset correction; `ended` -> frozen true talk duration;
+  ended with no `startedAt` or a voicemail/no-answer/busy reason -> a distinct not-answered
+  state that shows no timer and suppresses the recap card. The old simulation is retained
+  verbatim as the fallback whenever status is unavailable.
+- **Post-hangup summary grace.** Vapi writes `summary` asynchronously after hangup, so the
+  first ended poll is usually `summary: null`. Added a bounded 30s / 2s-cadence grace that
+  keeps polling after ended until the real summary lands, with the screen already showing the
+  ended state. Frozen duration provably unchanged across the window (tested).
+- **Real email send of the call summary.** New `/api/share-summary` route + `src/server/mailer.ts`
+  (nodemailer) + shared `src/lib/summaryText.ts`, so the Copy button and the emailed body are
+  byte-identical by construction. The client may only supply recipient + campaign id + bounded
+  variant index + signed token; never body or subject text.
+- **mailto fallback removed entirely** (developer decision mid-session). `src/lib/shareMailto.ts`
+  and its test deleted; Send now only ever reaches sent or failed-with-retry.
+- **Security hardening after the CSO audit returned BLOCK** (it flagged an unauthenticated
+  arbitrary-recipient mailer). Applied: purpose-scoped HMAC tokens (`status` vs `share`), token
+  moved from the URL query string to an `x-status-token` header, a valid share token now
+  REQUIRED for every send, Content-Type and `sec-fetch-site` checks, strict recipient validation
+  (rejects angle-bracket display-name form, commas, all non-ASCII), SMTP `requireTLS` + TLS 1.2
+  + timeouts, `Cache-Control: no-store, private` on every envelope, exact ACL error-code matching
+  that fails CLOSED on an unknown 403, upstream AbortSignal timeouts, rejection of future-dated
+  token issuance. The Vapi call id travels only inside signed claims, never as a client param.
+- **Final verification:** `npx tsc --noEmit` clean, `npm run lint` clean, `npm test`
+  **306/306 passing across 20 files**.
+- **Credentials located and wired** (locations only): 2.0 SMTP settings are hardcoded constants
+  in `_underscore/Email.php` (SES us-west-2, port 587, TLS); the Vapi bearer credential is a
+  hardcoded constant in `worker2/Worker/Ai/Bdr/Vapi.php`. BDR consumes both as server-only env
+  vars `TOGA_SMTP_HOST/PORT/USER/PASS`, `TOGA_EMAIL_FROM`, `TOGA_VAPI_TOKEN` in the gitignored
+  `.env.local` (documented in `.env.example`).
+- **Two knowledge captures pushed:** `6ed04d3` (8 docs — live-call-status, the api2 v2 query
+  contract, and updates) and `968404e` (3 docs — the callback root cause, with `bala` added as
+  co-owner for handoff).
+- **Callback bug root-caused with empirical proof.** Extracted worker2's `convertDateTime` and
+  executed it on PHP 8.1.10: 22 of 32 realistic phrasings return null.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Reading `ContactAttempts` through api2 — HTTP 403 `EZ-1`, record-level block.** Re-verified
+  live on 2026-07-30 against `api.togahub.com` with the BDR client credential, on ALL variants:
+  nested `/contacts/{uuid}/contact-attempts`, flat `/contact-attempts`, both with and without an
+  explicit `fields=` list. Response is `data.contactAttempts: null`. The pending read-only ACL
+  grant has still NOT landed. Do not build anything against this resource until it does.
+- **Selecting `Contacts.id`** — `/contacts/{uuid}?fields=id` returns 403 `EZ-2` with
+  `identifiers.fields: ["id"]`. The client has no field grant on `Contacts.id`. Filter on
+  `Contacts.uuid` instead (api2 does not ACL-check `where`/`join`, only `fields`).
+- **Direct production database access from this laptop.** TCP 3306 to the
+  `*.client.database.togahub.com` writer host **times out** (VPN required). This machine also
+  has no mysql client, no PHP, and no Python (only the Windows Store stub). Do not plan work
+  that assumes direct SQL — hand the developer ready-to-run SQL with pre-flight reads instead.
+- **Reading the api2 auth token from `data.token`** — wrong path, the response has no such key.
+  The access token is at **`data.tokens.access`**.
+- **Sharing the raw Claude Code session transcript (`~/.claude/projects/c--WWW/<id>.jsonl`) for
+  handoff.** Verified it contains live credential VALUES in plaintext: SMTP password (5
+  occurrences), Vapi token (2), Toga client API secret (4), HubSpot access token (4). Use
+  `/session-save` + `/session-resume` and the knowledge docs for handoff instead.
+- **(worker2, the production bug) `convertDateTime` parsing natural-language callback times.**
+  22/32 phrasings return null on PHP 8.1.10. The trigger is the PREPOSITION/FILLER WORD, not
+  spelled-out numbers as previously recorded: `"10 minutes"` parses but `"in 10 minutes"` does
+  not; `"tomorrow 3pm"` parses but `"tomorrow at 3pm"` does not — and that is the exact example
+  the code comment claims works.
+
+## Not tried yet (candidates for next session)
+
+- A **live end-to-end call test** of the new UI. Not possible yet: campaign 2's `dateEnd` lapsed
+  on 2026-07-28 and the re-activation SQL had not been run at save time.
+- **Verifying a real SMTP send.** Credentials are wired but no successful delivery has been
+  observed; `TOGA_EMAIL_FROM=DevTeam@goagilant.com` may or may not be an SES-verified identity.
+- **Running Q1-Q5 from `2.0/apps/worker2/features/callback-scheduling.md`** against `Client_True`
+  to confirm the callback root cause with production data. Q1 is decisive.
+- **Fixing any of the worker2 callback defects** — this session was diagnosis only; no worker2
+  code was modified. bala is picking this up.
+- **Adding the `TOGA_*` env vars to the Amplify console** so the deployed site gets live status
+  and email (local `.env.local` only affects dev).
+- **Binding the email recipient to the contact's on-file address** — the stricter anti-abuse
+  option; currently a token holder can email an arbitrary recipient (accepted residual risk).
+- **Splitting BDR knowledge out of `2.0/apps/ai-bdr/` into its own `2.0/apps/bdr/` folder with an
+  `architecture.md`.** Flagged twice; an elevated call that needs a deliberate decision.
+
+## Current file state
+
+All BDR changes are **uncommitted on branch `TRUE-80435`** (working tree only — nothing was
+committed or pushed all session, per the git-workflow rule).
+
+| File | Status | Notes |
+|------|--------|-------|
+| `bdr src/flow/screens/CallNow.tsx` | modified | gate + notice removed; submit enables on the digit rule alone |
+| `bdr src/flow/screens/Schedule.tsx` | modified | same removal |
+| `bdr src/flow/screens/Success.tsx` | modified | live stages via a kind-keyed lookup; simulation path preserved verbatim |
+| `bdr src/flow/screens/CallSummary.tsx` | modified | async send with sending/sent/failed; real-summary rendering; no mailto |
+| `bdr src/flow/useCallStatusViewModel.ts` | new | poll loop + pure reducer, cadence, caps, summary grace |
+| `bdr src/flow/callStatusApi.ts` | new | client fetcher, sends the token in a header |
+| `bdr src/flow/shareSummaryApi.ts` | new | maps send outcomes to sent/unavailable/failed |
+| `bdr src/flow/leadActions.ts` | modified | returns a handle `{ok, uuid?, statusToken?, shareToken?}`; `simulated` flag |
+| `bdr src/flow/useAgentFlow.ts` | modified | stores the call handle under the submitGen guard |
+| `bdr src/flow/AgentFlowRoot.tsx` | modified | passes the handle to calling-mode Success only |
+| `bdr src/server/vapiCall.ts` | new | reads `GET api.vapi.ai/call/{id}`; maps to the CallStatus union |
+| `bdr src/server/callStatus.ts` | modified | ContactAttempts path retained as the (403) fallback |
+| `bdr src/server/statusToken.ts` | new | purpose-scoped HMAC, TTL, skew, optional `vapiCallId` claim |
+| `bdr src/server/mailer.ts` | new | nodemailer, requireTLS, timeouts, scrubbed logs |
+| `bdr src/server/workerDialer.ts` | modified | **prefix bug fixed**; returns `DialResult` with `vapiCallId` |
+| `bdr src/server/callbackService.ts` | modified | surfaces `vapiCallId` |
+| `bdr src/server/toga.ts` | modified | added `togaApiGetEnvelope` (needed to read EZ-1/EZ-2 out of a 403) |
+| `bdr src/lib/summaryText.ts` | new | single renderer shared by Copy and the email |
+| `bdr src/lib/emailFormat.ts` | new | strict recipient validation |
+| `bdr src/lib/callStatus.ts` | new | shared CallStatus union + header constant |
+| `bdr src/app/api/call-status/route.ts` | new | token-gated, never 500s, `no-store` |
+| `bdr src/app/api/share-summary/route.ts` | new | share-token required, server-built content only |
+| `bdr src/app/api/call-now/route.ts` | modified | mints both tokens with the `vapiCallId` claim |
+| `bdr src/lib/shareMailto.ts` | **deleted** | mailto fallback removed by developer decision |
+| `bdr src/content/schema.ts` + `default.ts` | modified | live-stage + send-state copy; notice key removed |
+| `bdr src/proxy.ts` | modified | matcher + limiters for the two new routes |
+| `bdr .env.example` | modified | documents SMTP + `TOGA_VAPI_TOKEN` |
+| `bdr .env.local` | modified | real values added locally (gitignored) |
+| `bdr package.json` | modified | added `nodemailer` + `@types/nodemailer` |
+| worker2 / _underscore / api2 | **unmodified** | read-only investigation only |
+
+## Decisions made
+
+- **Vapi's API is the live call-status source, not `ContactAttempts`.** Rationale: ContactAttempts
+  is 403-blocked AND structurally inferior — `dtStarted` is DIAL time, so it cannot distinguish
+  ringing from talking, and `dtStarted` is retroactively rewritten by the webhook. Vapi exposes
+  ringing vs answered vs ended plus a real summary. It stays the better source even after the
+  grant lands. Rejected: waiting for the ACL grant; continuing to simulate.
+- **The backend contract is unchanged for anonymous submits** (developer decision). The funnel
+  loads and accepts a phone number for anyone, but calls still only fire for campaign-linked
+  contacts, matching the original BDR backend. Rejected: server-side anonymous contact creation
+  (would have required a DNC pre-check that the 403 blocks anyway).
+- **The mailto fallback was removed entirely** (developer decision). Consequence, accepted: with
+  SMTP unconfigured the Send button can only reach the failed state.
+- **Token purpose-scoping and header transport**, adopted in response to the CSO BLOCK verdict.
+  Rejected: leaving one token to serve both read and send, and leaving it in the query string
+  (a 30-minute bearer capability over a named individual's call summary would land in access logs).
+- **Accepted residual risk:** a token holder can email the summary to any address they type
+  (preserves the share-with-a-colleague use case). The stricter alternative is on the not-tried list.
+- **BDR knowledge stays filed under `2.0/apps/ai-bdr/`** rather than restructuring mid-capture.
+
+## Blockers
+
+- **`ContactAttempts` read-only ACL grant still pending** (403 EZ-1). Blocks only the fallback
+  path — the Vapi path works without it. Note for whoever files it: the `c_*` fields are granted
+  through `AclCustomFieldPermissions`, a DIFFERENT table from the standard fields.
+- **Campaign 2 (`26.05 - AI BDR - Ryan Nitti`, id 2) `dateEnd` lapsed 2026-07-28**, so no calls
+  place at all until it is extended. SQL was handed to the developer; the production DB is not
+  reachable from this machine.
+- **No live end-to-end verification yet** of the call UI or a real email delivery.
+
+## Exact next step
+
+> In `Client_True`, run the campaign-2 re-activation pre-flight reads first (confirm the dialable
+> count on campaign 2 is 0 or 1 and that contact 248 has no open `ContactAttempts` row with
+> `dtEnded IS NULL`), then flip all campaign-2 contacts except 248 to `isOkayToCall = 0` and
+> extend `Campaigns.dateEnd`. Then restart `npm run dev` in `C:\WWW\BDR`, open the funnel from
+> the `?hsContactId=` link, tap Call Now, and confirm the Success screen shows Ringing with no
+> timer, the timer starting at 00:00 on answer, and Call ended with the real Vapi summary.
+
+---
+_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.482",
+  "version": "1.0.484",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",