> For the complete documentation index, see [llms.txt](https://zumo.fusion.ac/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zumo.fusion.ac/documentation/core-concepts/concepts.md).

# Concepts

## Zumo and Zed

| Name     | Meaning                                                                                                                         |
| -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Zumo** | Competitive tracking platform and Discord bot. Issues `zk_*` keys and publishes leaderboard / Bedwars events (`botId: "zumo"`). |
| **Zed**  | Event hub at `https://zed.fusion.ac`. Socket.IO fan-out + HTTP for bots, replays, and MCPR.                                     |
| **Zinc** | Desktop app. Not documented here.                                                                                               |

As a developer you almost always talk to **Zed**, using a key issued by **Zumo**.

## Consumer key

* Format: `zk_...` (legacy `zp_*` may still exist)
* Must be `approved` and `enabled`
* Socket.IO: `auth: { key: 'zk_...' }` on namespace `/`
* HTTP: `API-Key: zk_...` header (except public MCPR download)

## Consume vs provide

* **consume**: events you may receive on `/`
* **provide**: events you may emit (`replayRequest` is checked against provide, not consume)

## Modes and lobbies

Lobby bots emit events with a shared envelope: `botId`, `mode`, `lobbyId`, `timestamp` (unix seconds). Optional connect filter: `query: { mode: 'duels' }`.

Replay lifecycle events usually use `mode: "replay"`, except **`replayFinished`**, where `mode` is the in-game mode (for example `"4v4"`). See [Mode filtering](/documentation/guides/mode-filtering.md).

## Lobby vs replay

| Track      | What you get                                                |
| ---------- | ----------------------------------------------------------- |
| **Lobby**  | Join/leave, chat, locraw, bot lifecycle from lobby watchers |
| **Replay** | Request recordings, progress, scrape result, MCPR download  |

## Categories

Fan-out payloads include `category`: `lobby`, `replay`, `temporaryLeaderboard`, `lifetimeLeaderboard`, `ban`, or `bedwars`.