Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Fix doc drift and a case collision in docs/official (#302)

Abel Dantas1f4cd9c2b28f
diff --git a/CLAUDE.md b/CLAUDE.md
index bb204ac7e..c82923f76 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,7 @@ history — a later commit cannot take it back. Keep internal detail out of it:
## Project Overview
-Switch is an AI agent orchestration and governance platform. It onboards, orchestrates, and secures third-party AI agents using Matrix (Tuwunel) as the internal message bus. Agents register via the Agent Bridge API and communicate through Matrix rooms with room-scoped protection, observability, and collaboration bridges to external platforms (Slack, Mattermost, Discord, Teams, Telegram).
+Switch is an AI agent orchestration and governance platform. It onboards, orchestrates, and secures third-party AI agents using Matrix (Tuwunel) as the internal message bus. Agents register via the Agent Bridge API and communicate through Matrix rooms, with collaboration bridges to external platforms (Slack, Mattermost, Discord, Teams, Telegram).
The target architecture is documented in `docs/`.
@@ -76,14 +76,12 @@ just test -k "test_name" # run specific test
- `models.py` — SQLAlchemy table definitions
- `stores/` — query methods and domain-specific data access
- `migrations/` — Alembic migrations (`env.py`, `versions/`)
-- `rooms/` — Room lifecycle, configuration, provisioning
-- `clients/` — Matrix clients (agent, user, resource manager, observe)
+- `room_service.py` / `rooms_yaml.py` — Room lifecycle, configuration, provisioning
+- `clients/` — Matrix clients (agent, user, admin, bridge, resource manager)
- `bridges/` — External integrations
- `agent/` — Agent Bridge (HTTP API, MCP server, server-side connectors)
- `collaboration/` — Collaboration Bridge (Slack, Mattermost, Discord, Teams, Telegram adapters)
- - `observe/` — Observe Bridge (event sinks)
- `resource/` — Resource Bridge (platform resource management)
-- `protect/` — Protection pipeline (checks, protect bridge, API)
- `gateway/` — Management API for the frontend
**Key patterns:**
@@ -114,8 +112,7 @@ and each ships its own copy of the Switch room-workflow skill at
`env_vars` and Codex forwards them **by name** from its own environment — no
expansion, and no secret in the file. An unset name is simply not forwarded,
which is why the list can include the Switch Console-only variables without
- breaking a standalone session (the Claude connector cannot do this: `${VAR}`
- expansion makes every declared variable mandatory).
+ breaking a standalone session.
The plugin's `.mcp.json` also carries `default_tools_approval_mode =
"approve"`, so the Switch tools never prompt. It has to live there rather than
@@ -226,10 +223,14 @@ Tests live in `core/tests/switch_core/` mirroring the module structure. Uses pyt
## Reference Documentation
-Everything under `docs/` is listed here; if it is not in this list, it does not
-exist:
-- `docs/old/ARCHITECTURE.md` — system overview: components, domain model, key flows,
- entry points, and a code map from area to module
+- `docs/official/` — the published user-facing documentation
+ (docs.flintai.dev) synced into the repo. Generated — edit the source in the
+ docs repository, never here. Start at `docs/README.md` for how the sync
+ works; `docs/official/internals/` covers architecture and the agent
+ protocol for readers of this repo.
+- `docs/old/ARCHITECTURE.md` — historical system overview: components, domain
+ model, key flows, entry points, and a code map. Predates the docs sync and
+ may lag the tree.
- `docs/old/api/AGENT_PROTOCOL.md` — the agent↔Switch protocol (connections, the
event stream, room slots, failure handling). Authoritative where it and
`ARCHITECTURE.md` overlap
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9444e8a1b..a7155e08d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,7 +29,7 @@ hot-reload while developing: `just run` (switch-core on `:8000`) and
`just down`, or `just reset` to also wipe the volumes.
If you only want to see Switch running rather than develop against it, the
-standalone stack in the [README](README.md#quickstart) is a shorter path.
+standalone stack in the [README](README.md#getting-started) is a shorter path.
## Common commands
@@ -62,7 +62,7 @@ Run `just` with no arguments to list every recipe. The most-used ones:
| `console/` | The Switch Console desktop app |
| `connectors/` | Agent connectors (`claude-code-plugin`, `codex-plugin`, `opencode-plugin`) |
| `deploy/` | Deployment assets — Docker Compose stacks (`local/`), the Helm chart (`remote/`) and shared images |
-| `docs/` | Architecture, agent protocol and bridge setup references |
+| `docs/` | `official/` — the published documentation synced into the repo (generated, edit the docs repository); `old/` — internal architecture, protocol and bridge references |
| `switch-expert/` | Instructions and knowledge for an agent that answers questions about Switch |
| `justfile` | Repo-root task runner (drives all code trees) |
diff --git a/README.md b/README.md
index f18e5ce72..8203b2ad2 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@
[![License: Apache 2.0 + Commons Clause](https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-blue)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-read-FF895E)](https://docs.flintai.dev/flintai/switch/getting-started)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
+[![Release](https://img.shields.io/github/v/release/sandbox-quantum/switch?label=release&color=FF895E)](https://github.com/sandbox-quantum/switch/releases)
+[![CI](https://github.com/sandbox-quantum/switch/actions/workflows/pr-ci.yml/badge.svg)](https://github.com/sandbox-quantum/switch/actions/workflows/pr-ci.yml)
[![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/zGQQQbSQx)
<img src="assets/switch-overview.jpg" alt="Switch on the left, holding a channel's messages and knowledge, its workflows and org design, its permissions and guardrails, its analytics, and the agent frameworks it runs; connected on the right to a chat channel where people and agents talk, with Slack, Microsoft Teams, Discord and Telegram above it" width="860">
@@ -186,7 +188,7 @@ Read [hosting remotely](https://docs.flintai.dev/flintai/switch/deploy/host-remo
### Switch Core
<div align="center">
- <img src="assets/switch-architecture.png" alt="Switch Core sits between human messaging apps and AI agents: a collaboration bridge relays Slack, Teams, Discord and Telegram; an agent bridge serves the HTTP API and MCP server to agents; both meet at a Tuwunel Matrix homeserver, with a room service, gateway API, PostgreSQL and the operator dashboard alongside" width="800">
+ <img src="assets/switch-architecture.png" alt="Switch Core sits between human messaging apps and AI agents: a collaboration bridge relays Slack, Teams, Discord, Telegram and Mattermost; an agent bridge serves the HTTP API and MCP server to agents; both meet at a Tuwunel Matrix homeserver, with a room service, gateway API, PostgreSQL and the operator dashboard alongside" width="800">
</div>
Switch Core is the infrastructure that joins your agents and your collaboration
@@ -205,7 +207,8 @@ manage and connect CLI-based agents.
**Collaboration Bridge.** Each chat platform connects through its own adapter,
with its own transport: Socket Mode for Slack, an HTTP listener for Teams, the
-gateway websocket for Discord, long polling for Telegram. It relays both ways,
+gateway websocket for Discord, long polling for Telegram, a websocket for
+Mattermost. It relays both ways,
maps each channel to a room, and gives every agent its own name and avatar in
the channel.
diff --git a/connectors/claude-code-plugin/skills/configure/SKILL.md b/connectors/claude-code-plugin/skills/configure/SKILL.md
index 7fad677c5..195175291 100644
--- a/connectors/claude-code-plugin/skills/configure/SKILL.md
+++ b/connectors/claude-code-plugin/skills/configure/SKILL.md
@@ -834,7 +834,7 @@ subagent while it has no live session, so the user doesn't have to memorise it.
Be straight with the user; do not imply parity.
**Works:** the full Switch tool surface (including `send_attachment` /
-`download_attachment`), room participation, threads, tasks, roles, moderation,
+`download_attachment`), room participation, threads, roles, moderation,
tool mediation and event reporting via the plugin's hooks, and the offline run
command Switch posts. **Pushed inbound events also work** — unlike the Codex
connector — provided the session is launched with
diff --git a/connectors/codex-plugin/README.md b/connectors/codex-plugin/README.md
index f943154fd..f1b4cbcee 100644
--- a/connectors/codex-plugin/README.md
+++ b/connectors/codex-plugin/README.md
@@ -57,8 +57,7 @@ depends on them:
server could not ship here at all.)
- **An unset name is simply not forwarded.** So the list can name
Switch Console-only variables (`SWITCH_CONNECTION_ID`) without breaking a
- session that has none of them. The Claude connector cannot do this: `${VAR}`
- expansion makes every declared variable mandatory.
+ session that has none of them.
`startup_timeout_sec` is raised from Codex's 10s default because a host that has
never run the runtime can exceed it on the `npx` fetch alone, and a timeout
@@ -146,7 +145,7 @@ server, which is precisely why the runtime learned to find them itself.
Works: the full Switch tool surface (including `send_attachment` /
`download_attachment` — neither is gated on which process owns the connection),
-room participation, tasks, roles, moderation, and the offline run command.
+room participation, roles, moderation, and the offline run command.
Does not: **inbound events are not pushed into the session.** Switch Console reads
the session's event connection and injects `[Switch] …` lines into its pane;
diff --git a/connectors/codex-plugin/skills/configure/SKILL.md b/connectors/codex-plugin/skills/configure/SKILL.md
index db7bc2120..6efd0c645 100644
--- a/connectors/codex-plugin/skills/configure/SKILL.md
+++ b/connectors/codex-plugin/skills/configure/SKILL.md
@@ -18,7 +18,7 @@ the standalone path is deliberately not feature-complete.
## What this skill does and does not touch
-The plugin already ships the MCP server: `.mcp.json` declares `mcp_servers.switch`
+The plugin already ships the MCP server: `.mcp.json` declares `mcpServers.switch`
with the runtime, its version pin, `startup_timeout_sec`, and
`default_tools_approval_mode: "approve"`. **Leave that alone.**
@@ -430,7 +430,7 @@ way they leak into logs and screenshots.
Be straight with the user; do not imply parity.
**Works:** the full Switch tool surface (including `send_attachment` /
-`download_attachment`), room participation, threads, tasks, roles, moderation,
+`download_attachment`), room participation, threads, roles, moderation,
and the offline run command Switch posts — which is a bare
`cd "<repo_dir>" && codex "connect to switch room <name> — if you are asked which agent you are, you are <agent_name>"`, so it works
as written provided `repo_dir` is where the store lives.
diff --git a/console/AGENTS.md b/console/AGENTS.md
index 86c148783..1e7a13ee8 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -569,9 +569,9 @@ forgotten and someone will debug a build they think is newer than it is.
| Artifact | Version lives in | Bump when |
|---|---|---|
| Remote sidecar | `src/sidecar/sidecar-version.ts` | any behaviour change; **major only** on a client↔sidecar wire break (ready line, endpoint shapes, shared on-disk layout) |
-| Claude Code plugin | `connectors/claude-code-plugin/.claude-plugin/plugin.json` | any change to the plugin — installs will not pick it up otherwise |
-| Codex plugin | `connectors/codex-plugin/.codex-plugin/plugin.json` | any change to the plugin (the room-workflow and `configure` skills, and its own `.mcp.json`) — installs will not pick it up otherwise |
-| OpenCode connector | `connectors/opencode-plugin/package.json` | any change to the connector. Nothing fetches it — Switch Console writes it — so the number is for humans reading a diff rather than for an installer, and `just artifacts-check` fails if it disagrees with `artifacts.yaml` |
+| Claude Code plugin | `../connectors/claude-code-plugin/.claude-plugin/plugin.json` | any change to the plugin — installs will not pick it up otherwise |
+| Codex plugin | `../connectors/codex-plugin/.codex-plugin/plugin.json` | any change to the plugin (the room-workflow and `configure` skills, and its own `.mcp.json`) — installs will not pick it up otherwise |
+| OpenCode connector | `../connectors/opencode-plugin/package.json` | any change to the connector. Nothing fetches it — Switch Console writes it — so the number is for humans reading a diff rather than for an installer, and `just artifacts-check` fails if it disagrees with `artifacts.yaml` |
| Agent runtime package | `packages/switch-agent-runtime/package.json` | any change; it is published, and the marketplace connectors' `.mcp.json` pin the version sessions actually run. An agent type whose connector the app writes rather than installs is pinned by `SWITCH_AGENT_RUNTIME_PIN` in `packages/plugins/src/distribution.ts`, which `connectors/opencode-plugin/opencode.json` must match. `runtime-pin.test.ts` and `connector-assets.test.ts` fail if any of them disagree |
"Non-trivial" means anything a user could observe: behaviour, protocol, wiring,
diff --git a/docs/README.md b/docs/README.md
index 8ad441024..dd9f8acb6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,7 +13,7 @@ what users are told.
**Generated — do not edit.** Change the source pages in the docs repository, then
run `just sync-docs`. Every file under `official/` is rewritten on each run, so
an edit made here is lost without warning. Start at
-[`official/INDEX.md`](official/INDEX.md), which lists the pages in the order the
+[`official/TOC.md`](official/TOC.md), which lists the pages in the order the
site presents them.
## `old/`
diff --git a/docs/official/INDEX.md b/docs/official/TOC.md
similarity index 100%
rename from docs/official/INDEX.md
rename to docs/official/TOC.md
diff --git a/scripts/sync_docs.py b/scripts/sync_docs.py
index 4ad0cb5e1..a1419ad66 100644
--- a/scripts/sync_docs.py
+++ b/scripts/sync_docs.py
@@ -259,7 +259,7 @@ def write_index(dest: Path, entries: list[tuple[list[str], str]]) -> None:
lines.extend(["", f"## {' › '.join(trail)}" if trail else "", ""])
rel = page[len(SOURCE_PREFIX) :] or "index"
lines.append(f"- [{rel}]({rel}.md) — <{published_url(page)}>")
- (dest / "INDEX.md").write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+ (dest / "TOC.md").write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
def resolve_source(source: str | None, keep: Path) -> Path: