cito-mcp 0.1.0 → 0.2.2

package/README.md

@@ -1,30 +1,73 @@
 # cito-mcp
 
-Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) (LoL, Dota 2, CS2, COD, Fortnite, UFC, and more).
+Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
 
-**Zero per-endpoint code:** on boot the server fetches the live OpenAPI specs from the API and generates one MCP tool per operation (105 tools today from the global + LoL specs). When the API ships a new endpoint, it appears here automatically on the next spec refresh — restart to pick it up immediately.
+**Version:** `0.2.2` · **Node:** `>=20` · **Install:** `npx cito-mcp`
 
-## Requirements
+Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
 
-- Node.js >= 20
-- A Cito API key (`CITO_API_KEY`)
+---
 
-## Quickstart (Claude Code)
+## Philosophy: outcomes, not endpoints
+
+v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among thin path wrappers, invent IDs, and stitch multi-call UI screens themselves. That catalog was hard to select against and brittle across games.
+
+**v0.2 ships 15 hand-authored tools** that answer *jobs* instead of mirroring REST:
+
+| Job | Tool |
+| --- | --- |
+| What’s live right now? | `live_matches` |
+| What’s coming up? | `upcoming_schedule` |
+| Build a match card / recap | `match_summary` |
+| Deep timeline / live state | `match_details` |
+| Team page | `team_profile` |
+| Player / fighter form | `player_profile` |
+| Table / rankings | `standings` |
+| Pre-match briefing | `match_preview` |
+| Event / fight-night card | `event_card` |
+| Rivalry record | `head_to_head` |
+| Name → ID | `resolve_entity` / `search_entities` |
+
+Composites multi-fetch server-side, return a **stable JSON envelope**, and isolate partial failures in `partial[]` so one bad secondary section does not fail the whole page.
+
+**MCP is design-time / agent assistance.** Ship production backends with Cito REST + the user’s API key. Do not put multi-tenant traffic through this process.
+
+---
+
+## Install
+
+### One-liner (published package)
+
+```bash
+npx cito-mcp
+```
+
+Requires `CITO_API_KEY` in the environment (see [Environment](#environment)). Most hosts inject env via their MCP config rather than a bare shell.
+
+### Claude Code
+
+```bash
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- npx cito-mcp
+```
+
+Windows — if `npx` fails under Claude:
 
 ```bash
-claude mcp add cito -- env CITO_API_KEY=cito_your_key_here npx cito-mcp
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- cmd /c npx cito-mcp
 ```
 
-Or run it straight from a clone of this repo (no publish needed):
+From a local clone (development):
 
 ```bash
-cd mcp && npm install && npm run build
-claude mcp add cito -- env CITO_API_KEY=cito_your_key_here node "$PWD/dist/index.js"
+cd mcp
+npm install
+npm run build
+claude mcp add cito -e CITO_API_KEY=cito_your_key_here -- node "%CD%\dist\index.js"
 ```
 
-## Cursor / Windsurf
+### Cursor
 
-Add to your MCP config JSON (e.g. `~/.cursor/mcp.json`):
+Add to Cursor MCP settings (e.g. `.cursor/mcp.json` or Cursor Settings → MCP):
 
 ```json
 {
@@ -40,61 +83,370 @@ Add to your MCP config JSON (e.g. `~/.cursor/mcp.json`):
 }
 ```
 
-The server exits immediately with a clear stderr message if `CITO_API_KEY` is missing. The key is sent only as the `x-api-key` header to the API and is never logged.
+Windows local clone:
+
+```json
+{
+  "mcpServers": {
+    "cito": {
+      "command": "node",
+      "args": ["C:/Users/Owner/Projects/cito-api-scraper-windows/mcp/dist/index.js"],
+      "env": {
+        "CITO_API_KEY": "cito_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf / other MCP hosts
+
+Same shape as Cursor: `command` + `args` + `env.CITO_API_KEY`. Prefer `npx cito-mcp` so clients pick up published patches without a local install.
+
+The server **exits immediately** if `CITO_API_KEY` is missing. The key is sent only as the `x-api-key` header and is never logged.
+
+---
+
+## Environment
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `CITO_API_KEY` | **yes** | — | Cito API key → `x-api-key` on every upstream call |
+| `CITO_API_BASE` | no | `https://api.citoapi.com/api/v1` | Override base URL (staging / self-hosted) |
+
+---
+
+## Preferred tool order
+
+1. Unsure → `list_capabilities` (optional `api_health` for tier / included games)
+2. Name without ID → `resolve_entity` (chain) or `search_entities` (browse)
+3. Live / upcoming → `live_matches` / `upcoming_schedule`
+4. Match card → `match_summary` (then `match_details` if needed)
+5. Team / player pages → `team_profile` / `player_profile`
+6. Tables / rivalry / preview / event card → `standings` / `head_to_head` / `match_preview` / `event_card`
+7. Escape hatch → `call_api` (allowlisted paths only)
+
+**Never invent IDs** — resolve them or take them from live / schedule / search results.
+
+Mnemonic: **resolve → live/schedule → summary → deep**.
+
+---
+
+## Tool catalog (15)
+
+All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (the server name already brands the surface).
+
+| Tool | Outcome | When to use | When not to use | Key inputs |
+| --- | --- | --- | --- | --- |
+| `list_capabilities` | Catalog of tools, games, jobs, recipes (no network) | Session start; map UI screens to tools; filter by `game` / `job` | You already know the tool and have IDs | `game?`, `job?`, `q?`, `includeExamples?`, `includeRecipes?` |
+| `api_health` | Reachability, key validity, tier, rate limits, optional game probes | Once per session; after 401/403/RATE_LIMIT; entitlement checks | Fetching live scores or entity data | `includeGameProbes?` |
+| `resolve_entity` | Name → best typed id/slug (+ ranked candidates) | User named “T1”, “s1mple”, “IEM Cologne” without an ID; chaining into profiles | Already have a stable id/slug; large browse lists | `q`, `game?`, `type?`, `limit?` |
+| `search_entities` | Paginated entity browse/search for one game | Typeahead / pickers; “list teams matching…” | Single-name resolve for chaining; full profile pages | `game`, `q?`, `type?`, `limit?`, `cursor?`, `activeOnly?` |
+| `live_matches` | Live board (one game or all); CS2 uses `/cs2/live`; includes UFC | “What’s live?”; ops/dashboard strip | Upcoming fixtures; historical recaps | `game?` (`all` or omit), `limitPerGame?`, `includeLabelsOnly?` |
+| `upcoming_schedule` | Upcoming fixtures/events with filters | “What’s on this week?”; team next matches | Live-only boards; deep match recaps | `game`, `hours?`, `from?`, `to?`, `team?`, `league?`, `tournamentId?`, `limit?`, `cursor?` |
+| `match_summary` | Composite match card: score, performances, media stubs | Default match UI / recap after a known `matchId` | No matchId yet; pure pre-match → `match_preview`; deep timelines | `game`, `matchId`, `view?`, `includePlayerStats?`, `includeMedia?` |
+| `match_details` | Deep sections: timeline, live state, maps, advanced | Analyst dive; live in-game window; full demo list | First-pass live board; simple chat recaps | `game`, `matchId`, `gameId?`, `sections?`, `includeTimeline?`, `includeLiveState?`, `includeAdvanced?` |
+| `player_profile` | Player/fighter + form/trends/radar when available | “How is X playing?”; player page scaffold | Full roster → `team_profile`; unresolved name | `game`, `playerId` **or** `slug`, `recentLimit?`, `includeTrends?`, `view?`, `window?`, `role?` |
+| `team_profile` | Team/org + roster + recent form | Team page / “who is on this roster?” | UFC fighters → `player_profile`; unresolved name; pure tables | `game`, `teamId` **or** `slug`, `recentLimit?`, `includeFormer?`, `view?` |
+| `head_to_head` | Composed H2H (no first-class REST H2H) | Rivalry / series record; preview context | Single-side form only; live scores; standings | `game`, `sideA`, `sideB`, `entityType?`, `limit?`, `from?`, `to?` |
+| `standings` | League/event tables or world/division rankings | Playoff picture; UFC rankings; CDL / CS2 tables | Team form; live scores; match recaps | `game`, `scope?`, `leagueId?`, `tournamentId?`, `eventId?`, `season?`, `stage?`, `division?`, `limit?` |
+| `match_preview` | Pre-match briefing: sides, rosters/form, H2H stub | Upcoming deep link; pick’ems; preview cards | Completed recaps; deep live state | `game`, `matchId` **or** (`teamA` + `teamB`), `eventId?`, `includeH2H?`, `includeRosters?`, `recentLimit?` |
+| `event_card` | Event / fight-night card: identity, bout/match list, optional standings | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?` |
+| `call_api` | Allowlisted raw REST (`data.raw`) | Fortnite / long-tail paths; payload debugging | Any job covered by a curated tool | `path`, `method?`, `queryJson?`, `bodyJson?` |
+
+### Games
+
+| Game | Depth | Notes |
+| --- | --- | --- |
+| `lol` | deep | Team slugs; `lol-match-*`; no native global search |
+| `cs2` | deep | Prefixed ids; live path **`GET /cs2/live`**; trends / rankings |
+| `dota2` | thin | Numeric ids; radar; weak/no standings & roster endpoints |
+| `cod` | medium | Org slugs; CDL standings; UUID match ids |
+| `ufc` | medium | Fighter slugs; `boutId`; live + rankings |
+
+Fortnite: **`call_api` only** until promoted into the primary enum.
+
+### `call_api` allowlist
+
+Path must start with `/` and match one of:
+
+`/health` · `/lol` · `/cs2` · `/dota2` · `/cod` · `/ufc` · `/fortnite`
+
+Absolute URLs and `..` traversal → `PATH_NOT_ALLOWED`. Prefer curated tools for all standard jobs.
+
+---
+
+## Response envelope
+
+Every tool returns one JSON object:
+
+```json
+{
+  "ok": true,
+  "data": {},
+  "meta": {
+    "game": "cs2",
+    "source": "match_summary",
+    "fetchedAt": "2026-07-27T12:00:00.000Z",
+    "requestId": "mcp_…",
+    "tookMs": 120,
+    "upstreamCalls": 3,
+    "rateLimit": { "tier": "pro", "remaining": 54 }
+  },
+  "pagination": { "limit": 20, "hasMore": false, "nextCursor": null },
+  "partial": [],
+  "error": null
+}
+```
+
+| Condition | How to handle |
+| --- | --- |
+| `ok: false` | Tool-level failure; MCP `isError: true`; read `error.code` + `error.recover[]` |
+| `ok: true` with `partial[]` | Use successful sections; **do not** treat as total failure |
+| List tools | `data.items` + `pagination` (`limit`, `hasMore`, `nextCursor`, …) |
+
+**Error codes:** `VALIDATION` · `NOT_FOUND` · `UNSUPPORTED_GAME` · `UNAUTHORIZED` · `RATE_LIMIT` · `UPSTREAM` · `PATH_NOT_ALLOWED` · `NOT_IMPLEMENTED`
+
+**Ambiguity:** `resolve_entity` returns `ok: true` with `data.needsDisambiguation` + `data.candidates` — pick a candidate; do not wait for a hard error.
+
+Retry only when `error.retryable` is true (typically `RATE_LIMIT`, `UPSTREAM`).
+
+**Pagination:** default limit 20, max 50 (some tools clamp differently). Honor `pagination.hasMore` and pass `pagination.nextCursor` only — never invent cursors or reuse them after changing filters.
+
+---
+
+## Builder recipes
+
+Use these as agent playbooks when scaffolding apps. Prefer one composite per screen over N+1 thin GETs.
+
+### 1. Live scoreboard
+
+**Goal:** multi-game (or single-game) live strip with optional match drill-down.
+
+```
+1. api_health                          # optional — once per session
+2. live_matches { game: "all" }        # or "cs2" / "lol" / …
+3. For a selected row:
+   match_summary { game, matchId }     # default card
+   match_details { …, includeLiveState: true }  # only if needed
+```
+
+**UI map**
+
+| Screen region | Source |
+| --- | --- |
+| Live rows (label, score, status) | `live_matches` → `data.sections[].items` |
+| Expanded card | `match_summary` → `data.scoreline`, `playerPerformances`, `media` |
+| In-game window | `match_details` sections `liveState` / `timeline` |
+
+**Do not:** N+1 `match_details` for every live row; invent matchIds; use `upcoming_schedule` for live-only boards.
+
+### 2. Player profile page
+
+**Goal:** identity, team, recent form for a named player or fighter.
+
+```
+1. resolve_entity { q: "s1mple", game: "cs2", type: "player" }
+   # or type: "fighter" for UFC
+2. player_profile {
+     game,
+     playerId | slug,          # from resolve best/candidates
+     recentLimit: 10,
+     includeTrends: true,
+     view: "summary"
+   }
+3. Optional: head_to_head for rivalry context (fighters/teams)
+```
+
+**UI map**
+
+| Screen region | Source |
+| --- | --- |
+| Header / identity | `data.player` |
+| Current team | `data.currentTeam` |
+| Recent form list | `data.recentMatches` + `data.form` |
+| Career / radar | `data.career`, `data.radar`, `data.seasonStats` (when present) |
+
+**Do not:** invent playerIds; use `team_profile` for full rosters; skip resolve when the user only gave a display name.
 
-## How tool updates work (multi-spec)
+### 3. Event hub
 
-The server merges **multiple OpenAPI specs** at boot — the global spec does not cover every game:
+**Goal:** schedule strip + standings/rankings + match previews for a league, tournament, or event.
 
-- **Default sources**: the global spec (`$CITO_API_BASE/openapi.json`) + the LoL spec (`$CITO_API_BASE/lol/openapi.json`). Today: 71 + 34 = 105 generated tools.
-- **Opportunistic per-game specs**: at boot the server also probes `$CITO_API_BASE/{cod,fortnite,dota2,cs2,ufc}/openapi.json` **with your `x-api-key`** and merges any that return 200. 401/404s are skipped quietly (one stderr line each).
-- **Add or replace sources via env**:
-  - `CITO_OPENAPI_URLS` — comma-separated list, replaces the defaults entirely (e.g. `CITO_OPENAPI_URLS=https://api.citoapi.com/api/v1/openapi.json,https://api.citoapi.com/api/v1/cod/openapi.json`).
-  - `CITO_OPENAPI_URL` (singular) — single-spec override (legacy, still works).
-- **Per-spec base URLs**: each spec's `servers[0].url` is used as the base for its tools (the global spec's paths are relative to `/api/v1`; the LoL spec's paths already include `/api/v1/lol` and its servers entry is the bare origin — so `servers[0].url` + verbatim paths is correct for both). Escape hatch: `CITO_SPEC_BASE_<KEY>` (e.g. `CITO_SPEC_BASE_LOL=https://staging.example.com/api/v1`).
-- **Collisions**: merge is path/operation concatenation. On an `operationId` collision across specs, the later spec's tool is prefixed with its game key (`cito_lol_…`) and logged to stderr.
-- **No operationId?** Fallback names are derived from method + path (`get /api/v1/lol/live/{gameId}/stats` → `cito_getlollivebygameidstats`). The real LoL spec currently ships no operationIds, so all its tools use fallback names.
-- The last good specs are cached to `mcp/.spec-cache.json` (one merged file, per-source entries) — a failed fetch falls back to the cached copy per source.
-- Specs are refreshed every `CITO_SPEC_REFRESH_MINUTES` (default 60); tools are regenerated in place and clients are notified via `tools/list_changed`. **Restart the server to pick up brand-new endpoints immediately.**
-- Tool names: `cito_` + sanitized name. Descriptions preserve the spec's summaries and per-parameter docs.
-- All logs go to **stderr only** (stdout is the MCP channel).
+```
+1. list_capabilities { job: "schedule" }   # optional orientation
+2. upcoming_schedule {
+     game: "cs2",                          # or lol / cod / ufc / dota2
+     hours: 168,                           # or from/to ISO window
+     league | tournamentId | team          # scope filters as available
+   }
+3. standings {
+     game,
+     scope: "event" | "league" | "tournament" | "world" | "division",
+     eventId | leagueId | tournamentId | division | season
+   }
+4. For a featured upcoming match:
+   match_preview { game, matchId }         # or teamA + teamB
+5. When a match goes live / completes:
+   match_summary { game, matchId }
+```
+
+**UI map**
+
+| Screen region | Source |
+| --- | --- |
+| Upcoming list | `upcoming_schedule` → `data.items` |
+| Table / ranks | `standings` → `data.rows` |
+| Featured match briefing | `match_preview` → `sideA` / `sideB` / `h2h` / `talkingPoints` |
+| Live / completed card | `match_summary` |
 
-## Curated extras
+**Notes:** Dota standings may return `NOT_IMPLEMENTED` or sparse data — fall back to schedule + profiles. UFC event hubs lean on fighter slugs, `boutId`, and `standings` with `scope: "division"`.
 
-Hand-written, on top of the generated tools:
+### Other quick recipes (from `list_capabilities`)
 
-| Tool | Purpose |
+| Recipe id | Steps |
 | --- | --- |
-| `cito_live_overview` | One merged "what's live right now" across all games (`/lol/live`, `/dota2/matches/live`, `/cs2/matches/live`, `/cod/matches/live`): per-game count + first few match labels. Games that 4xx are skipped, not fatal. |
-| `cito_api_health` | Authenticated probe proving your key works: tries `$CITO_API_BASE/health`, falls back to `$CITO_API_BASE/lol/leagues`, reports which probe answered, plus rate-limit/tier headers when present. |
+| `live_ops_board` | `api_health` → `live_matches` → `match_summary` / `match_details` |
+| `team_page` | `resolve_entity { type: "team" }` → `team_profile` |
+| `match_center_completed` | schedule/live for `matchId` → `match_summary` → optional `match_details` |
+| `app_scaffold` | `list_capabilities` ∥ `api_health` → sample composites → **ship REST in production** |
+
+---
 
-Resources:
+## Resources
 
-- `cito://llms.txt` — the API's agent-context file, fetched on read.
-- `cito://openapi.json` — the current spec this server generated its tools from.
+| URI | Purpose |
+| --- | --- |
+| `cito://capabilities` | Static tool / game / workflow summary |
+| `cito://llms.txt` | Live product agent context (may 404 upstream) |
+| `cito://openapi.json` | Live public OpenAPI for **typed clients** — not for tool generation |
 
-## Behavior notes
+---
 
-- Path params are interpolated into the URL, query props become the query string, `body` becomes the JSON body.
-- Non-2xx responses are returned as-is with `isError: true` — agents can read the API's own error codes (quota, tier gates, 404s).
-- Responses over ~100KB are truncated with a note telling the agent to narrow with query parameters.
-- Adding new endpoints to the API = **zero MCP code**. The spec is the contract.
+## Transports
 
-## HTTP transport (optional)
+**stdio** is the default (Claude Code, Cursor, Windsurf).
 
-stdio is the default (what Claude Code / Cursor use). A stateless Streamable HTTP endpoint is available:
+Optional **stateless Streamable HTTP**:
 
 ```bash
 CITO_API_KEY=cito_your_key_here node dist/index.js --http 8787
 # → http://127.0.0.1:8787/mcp
 ```
 
+---
+
+## Migration from 0.1 (auto-generated tools)
+
+**Breaking change.** `0.1.x` loaded OpenAPI at boot and mass-generated ~100+ tools (`generateAllTools`), plus a couple of hard-coded helpers (e.g. `cito_live_overview`, `cito_api_health`). Agents selected among thin REST wrappers and often reimplemented composition client-side.
+
+| 0.1 pattern | 0.2 replacement |
+| --- | --- |
+| Generated per-path tools (`/cs2/matches/...`, etc.) | Outcome tools in the table above |
+| `cito_live_overview` / ad-hoc live probes | `live_matches` (fixed CS2 path `/cs2/live`; UFC included) |
+| `cito_api_health` | `api_health` |
+| OpenAPI-named tools with `cito_` noise | **15** `snake_case` names, no `cito_` prefix |
+| Raw HTTP-shaped responses | Stable envelope: `ok`, `data`, `meta`, `pagination`, `partial`, `error` |
+| Agent stitches roster + matches + H2H | `team_profile`, `player_profile`, `head_to_head`, `match_preview` |
+| Fortnite / niche paths as first-class tools | `call_api` allowlist |
+| Spec cache / boot network for tool list | Static catalog; `list_capabilities` is offline |
+
+**Action items for existing clients**
+
+1. Drop any hardcoded 0.1 tool names; rebind prompts to the 15-tool catalog.
+2. Always parse the envelope (`ok` / `partial` / `error.recover`) — do not assume bare REST JSON.
+3. Use `resolve_entity` before profile tools when you only have a display name.
+4. Prefer composites over reintroducing N+1 `call_api` loops.
+5. Bump config to `npx cito-mcp` (or rebuild from this package) and re-test live board + one profile + one match flow.
+
+There is **no compatibility shim** for 0.1 tool names in 0.2.
+
+---
+
 ## Development
 
 ```bash
 npm install
 npm run build     # tsc → dist/
-npm test          # node:test via tsx, no network
+npm test          # node:test via tsx, offline (no network)
+npm start         # node dist/index.js (requires CITO_API_KEY)
+```
+
+Source layout (authoritative tool registry: `src/tools/index.ts`):
+
+```
+src/
+  index.ts              # MCP wiring, resources, stdio / --http
+  client.ts             # fetchJson, auth, present, cursors
+  envelope.ts           # success / error envelopes, MCP isError
+  instructions.ts       # server instructions for agents
+  tools/
+    index.ts            # allTools (15)
+    meta.ts             # list_capabilities, api_health, call_api
+    resolve.ts          # resolve_entity, search_entities
+    live.ts             # live_matches, upcoming_schedule
+    match.ts            # match_summary, match_details
+    player.ts           # player_profile
+    team.ts             # team_profile, head_to_head
+    standings.ts        # standings
+    insight.ts          # match_preview, event_card
+    normalize.ts        # cross-game normalization
+    types.ts            # ToolDef, schemas
+```
+
+---
+
+## Publish notes
+
+Package: **`cito-mcp@0.2.2`**
+
+| Item | Value |
+| --- | --- |
+| npm name | `cito-mcp` |
+| bin | `cito-mcp` → `dist/index.js` |
+| published files | `dist/`, `README.md` (`package.json` `"files"`) |
+| engines | `node >= 20` |
+| runtime dependency | `@modelcontextprotocol/sdk` only |
+| prepublish | `npm run prepublishOnly` → `npm run build` |
+
+### Pre-publish checklist
+
+1. `npm test` — offline suite green.
+2. `npm run build` — clean `dist/`.
+3. Smoke against a real key (not in CI by default):
+   - `api_health`
+   - `live_matches`
+   - `resolve_entity` (e.g. T1 / s1mple)
+   - `match_summary` with a real `matchId` from live/schedule
+4. Confirm `package.json` version and README match the shipped tool list (15).
+5. `npm publish` from `mcp/` (or your release pipeline) with appropriate npm auth / access.
+
+### Install line for docs & marketing
+
+```bash
+claude mcp add cito -e CITO_API_KEY=cito_… -- npx cito-mcp
+```
+
+```json
+{ "command": "npx", "args": ["cito-mcp"], "env": { "CITO_API_KEY": "cito_…" } }
 ```
 
-Environment variables: `CITO_API_KEY` (required), `CITO_API_BASE` (default `https://api.citoapi.com/api/v1`), `CITO_OPENAPI_URLS` / `CITO_OPENAPI_URL` (spec source overrides), `CITO_SPEC_BASE_<KEY>` (per-spec base override), `CITO_SPEC_REFRESH_MINUTES` (default 60).
+### Semver expectations
+
+- **0.2.0** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
+- Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
+- Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
+
+---
+
+## Changelog (summary)
+
+### 0.2.0
+
+- **Breaking:** replaced OpenAPI mass-generated tools with **15 curated outcome tools**
+- Stable JSON envelope + MCP server instructions
+- Fixed CS2 live path (`/cs2/live`); UFC in live fan-out
+- Composites with `partial[]` recovery; `call_api` path allowlist
+- Resources: `cito://capabilities`, `cito://llms.txt`, `cito://openapi.json`
+
+See [`_workflow/CHANGELOG-0.2.md`](_workflow/CHANGELOG-0.2.md) for the full 0.2 write-up.