toga-ai 1.0.483 → 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/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.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",