Skip to content

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

Sync the published Switch documentation into the repository (#295)

Louis Amaudruz14a709e3e3db
diff --git a/CLAUDE.md b/CLAUDE.md
index c9dc6d36e..bb204ac7e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -228,12 +228,12 @@ Tests live in `core/tests/switch_core/` mirroring the module structure. Uses pyt
Everything under `docs/` is listed here; if it is not in this list, it does not
exist:
-- `docs/ARCHITECTURE.md` — system overview: components, domain model, key flows,
+- `docs/old/ARCHITECTURE.md` — system overview: components, domain model, key flows,
entry points, and a code map from area to module
-- `docs/api/AGENT_PROTOCOL.md` — the agent↔Switch protocol (connections, the
+- `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
-- `docs/bridges/` — collaboration bridge setup: `README.md` plus one page each
+- `docs/old/bridges/` — collaboration bridge setup: `README.md` plus one page each
for Slack, Mattermost, Discord, Teams, and Telegram
There is no separate schema, room-design, HTTP-API or MCP-surface document. Read
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1390b3efa..9444e8a1b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,7 +66,7 @@ Run `just` with no arguments to list every recipe. The most-used ones:
| `switch-expert/` | Instructions and knowledge for an agent that answers questions about Switch |
| `justfile` | Repo-root task runner (drives all code trees) |
-[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) describes the service's internal
+[`docs/old/ARCHITECTURE.md`](docs/old/ARCHITECTURE.md) describes the service's internal
module structure and the key request flows.
## Testing
diff --git a/README.md b/README.md
index 1fbb196e3..f3ef29515 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@
[![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)
+[![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.png" alt="A team chatting with agents in their existing messaging app on the left, connected to Switch on the right, which holds that channel's messages, agents, instructions, permissions, guardrails, knowledge and analytics" width="860">
diff --git a/core/switch_core/bridges/collaboration/teams/README.md b/core/switch_core/bridges/collaboration/teams/README.md
index be4dda0e4..a33dddc12 100644
--- a/core/switch_core/bridges/collaboration/teams/README.md
+++ b/core/switch_core/bridges/collaboration/teams/README.md
@@ -8,7 +8,7 @@ in the bridge's stored `connection_config`, never in global/env config.
> For the operator-facing **setup walkthrough** (Azure prerequisites, onboarding
> request, and how Teams fits alongside the other bridges), see
-> [`docs/bridges/TEAMS_SETUP.md`](../../../../../docs/bridges/TEAMS_SETUP.md).
+> [`docs/old/bridges/TEAMS_SETUP.md`](../../../../../docs/old/bridges/TEAMS_SETUP.md).
> This note focuses on the adapter's internal architecture.
## Architecture
@@ -75,7 +75,7 @@ authenticated by verifying the Bot Connector JWT.
**This is a checklist of what must exist, not instructions for producing it.**
For the steps — which portal blade, which button, in what order — follow
-[`docs/bridges/TEAMS_SETUP.md`](../../../../../docs/bridges/TEAMS_SETUP.md),
+[`docs/old/bridges/TEAMS_SETUP.md`](../../../../../docs/old/bridges/TEAMS_SETUP.md),
whose Part 1 covers these one for one.
Environment/tenant setup owned by an administrator — track as a separate ops task.
@@ -88,7 +88,7 @@ Environment/tenant setup owned by an administrator — track as a separate ops t
3. **Teams app package** (manifest plus its two icons) including the bot,
installed into the target team so it can be added to channels and post
proactively. A ready-made one ships at
- [`docs/bridges/teams-app/`](../../../../../docs/bridges/teams-app/).
+ [`docs/old/bridges/teams-app/`](../../../../../docs/old/bridges/teams-app/).
4. **Graph API permissions** with admin consent, for channel capture +
provisioning: `ChannelMessage.Read.Group` (RSC, preferred) *or* tenant-wide
`ChannelMessage.Read.All`; plus `Channel.Create`, `Channel.ReadBasic.All`,
diff --git a/core/tests/switch_core/bridges/collaboration/test_teams_app_package.py b/core/tests/switch_core/bridges/collaboration/test_teams_app_package.py
index 0488a107f..7804ccd20 100644
--- a/core/tests/switch_core/bridges/collaboration/test_teams_app_package.py
+++ b/core/tests/switch_core/bridges/collaboration/test_teams_app_package.py
@@ -1,6 +1,6 @@
"""The Teams app package we ship has to be uploadable as it stands.
-`docs/bridges/teams-app/` is a paste-and-upload package, not an illustration:
+`docs/old/bridges/teams-app/` is a paste-and-upload package, not an illustration:
an operator zips those three files and Teams accepts or rejects them. Teams
gives no useful error for most of these mistakes — an icon of the wrong size or
an eleventh command comes back as a generic validation failure — so the limits
@@ -18,7 +18,8 @@ from pathlib import Path
import pytest
-PACKAGE = Path(__file__).resolve().parents[5] / "docs" / "bridges" / "teams-app"
+REPO_ROOT = Path(__file__).resolve().parents[5]
+PACKAGE = REPO_ROOT / "docs" / "old" / "bridges" / "teams-app"
MANIFEST = PACKAGE / "manifest.json"
# The placeholder an operator must replace with their Azure Bot app id. It is
@@ -216,7 +217,7 @@ def _build(tmp_path: Path, *args: str) -> tuple[int, Path]:
import subprocess
out = tmp_path / "pkg.zip"
- script = PACKAGE.parents[2] / "scripts" / "build_teams_app_package.py"
+ script = REPO_ROOT / "scripts" / "build_teams_app_package.py"
result = subprocess.run(
[sys.executable, str(script), "-o", str(out), *args],
capture_output=True,
@@ -319,9 +320,9 @@ def test_the_builder_refuses_a_package_teams_would_reject_for_it(
for icon in stripped["icons"].values():
(tmp_path / icon).write_bytes((PACKAGE / icon).read_bytes())
- script = PACKAGE.parents[2] / "scripts" / "build_teams_app_package.py"
+ script = REPO_ROOT / "scripts" / "build_teams_app_package.py"
source = script.read_text().replace(
- 'PACKAGE_DIR = REPO_ROOT / "docs" / "bridges" / "teams-app"',
+ 'PACKAGE_DIR = REPO_ROOT / "docs" / "old" / "bridges" / "teams-app"',
f"PACKAGE_DIR = Path({str(tmp_path)!r})",
)
patched = tmp_path / "build.py"
@@ -362,7 +363,7 @@ def test_bump_raises_the_patch_version(tmp_path: Path) -> None:
def test_an_unbumped_build_says_teams_will_ignore_it(tmp_path: Path) -> None:
import subprocess
- script = PACKAGE.parents[2] / "scripts" / "build_teams_app_package.py"
+ script = REPO_ROOT / "scripts" / "build_teams_app_package.py"
result = subprocess.run(
[
sys.executable,
diff --git a/deploy/remote/helm/switch/README.md b/deploy/remote/helm/switch/README.md
index 985933425..af58ab91d 100644
--- a/deploy/remote/helm/switch/README.md
+++ b/deploy/remote/helm/switch/README.md
@@ -115,7 +115,7 @@ Expect `200` with `ping` echoed back as `text/plain`. A timeout means it is not
public; a 404 means the path is missing or aimed at port 8000.
Full walkthrough, including the Azure side:
-[`docs/bridges/TEAMS_SETUP.md`](../../../../docs/bridges/TEAMS_SETUP.md).
+[`docs/old/bridges/TEAMS_SETUP.md`](../../../../docs/old/bridges/TEAMS_SETUP.md).
---
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..8ad441024
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,25 @@
+# Documentation
+
+Two sets of documents, with different owners and different audiences.
+
+## `official/`
+
+The reader-facing Switch documentation, published at
+[docs.flintai.dev](https://docs.flintai.dev). It is written in
+[`sandbox-quantum/docs`](https://github.com/sandbox-quantum/docs) as Mintlify MDX
+and converted to Markdown here so that agents working in this repository can read
+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
+site presents them.
+
+## `old/`
+
+Design and operator material written for this repository: the architecture
+overview, the agent protocol, and per-bridge setup guides. None of it is
+published, and none of it is covered by the pages under `official/` — where the
+two describe the same thing, this is the deeper account and the published page is
+the one users act on.
diff --git a/docs/official/INDEX.md b/docs/official/INDEX.md
new file mode 100644
index 000000000..3751fda25
--- /dev/null
+++ b/docs/official/INDEX.md
@@ -0,0 +1,78 @@
+# Switch documentation
+
+The reader-facing Switch documentation, converted from the Mintlify source in
+`sandbox-quantum/docs` and published at https://docs.flintai.dev.
+
+Generated by `just sync-docs`. Do not edit these files: change the source pages
+in the docs repository and run the sync again.
+
+
+## Overview
+
+- [index](index.md)
+
+## Get started
+
+- [getting-started/index](getting-started/index.md)
+- [getting-started/install-switch-console](getting-started/install-switch-console.md)
+- [getting-started/add-a-server](getting-started/add-a-server.md)
+- [getting-started/set-up-agent-providers](getting-started/set-up-agent-providers.md)
+- [getting-started/onboard-your-agents](getting-started/onboard-your-agents.md)
+- [getting-started/create-a-room](getting-started/create-a-room.md)
+- [getting-started/smoke-test](getting-started/smoke-test.md)
+
+## Deploy and connect
+
+- [deploy/index](deploy/index.md)
+- [deploy/host-remotely](deploy/host-remotely.md)
+- [deploy/self-host](deploy/self-host.md)
+
+## Deploy and connect › Connect your agents
+
+- [deploy/connect-agents/switch-console](deploy/connect-agents/switch-console.md)
+- [deploy/connect-agents/standalone](deploy/connect-agents/standalone.md)
+
+## Deploy and connect › Connect messaging apps
+
+- [deploy/messaging-apps/index](deploy/messaging-apps/index.md)
+- [deploy/messaging-apps/slack](deploy/messaging-apps/slack.md)
+- [deploy/messaging-apps/microsoft-teams](deploy/messaging-apps/microsoft-teams.md)
+- [deploy/messaging-apps/mattermost](deploy/messaging-apps/mattermost.md)
+- [deploy/messaging-apps/discord](deploy/messaging-apps/discord.md)
+- [deploy/messaging-apps/telegram](deploy/messaging-apps/telegram.md)
+- [deploy/messaging-apps/how-connections-work](deploy/messaging-apps/how-connections-work.md)
+
+## Working in Switch
+
+- [using/index](using/index.md)
+- [using/mention-and-message](using/mention-and-message.md)
+- [using/what-comes-back](using/what-comes-back.md)
+- [using/rooms-and-agents](using/rooms-and-agents.md)
+- [using/shared-context](using/shared-context.md)
+- [using/hand-off-work](using/hand-off-work.md)
+- [using/how-switch-works](using/how-switch-works.md)
+
+## Build with Switch
+
+- [building/index](building/index.md)
+- [building/payments-room](building/payments-room.md)
+- [building/grow-into-an-organization](building/grow-into-an-organization.md)
+
+## Under the hood
+
+- [internals/index](internals/index.md)
+- [internals/matrix-substrate](internals/matrix-substrate.md)
+- [internals/collaboration-bridge](internals/collaboration-bridge.md)
+- [internals/agent-protocol](internals/agent-protocol.md)
+- [internals/connectors-and-runtime](internals/connectors-and-runtime.md)
+- [internals/standalone-and-console](internals/standalone-and-console.md)
+- [internals/life-of-a-message](internals/life-of-a-message.md)
+- [internals/identity-and-access](internals/identity-and-access.md)
+- [internals/rooms-and-resources](internals/rooms-and-resources.md)
+- [internals/switch-console](internals/switch-console.md)
+
+## Resources
+
+- [resources/room-commands](resources/room-commands.md)
+- [resources/troubleshooting](resources/troubleshooting.md)
+- [resources/glossary](resources/glossary.md)
diff --git a/docs/official/building/grow-into-an-organization.md b/docs/official/building/grow-into-an-organization.md
new file mode 100644
index 000000000..4891ae226
--- /dev/null
+++ b/docs/official/building/grow-into-an-organization.md
@@ -0,0 +1,126 @@
+# Grow into an organization
+
+_What changes when one room isn't enough — more rooms, links between them, material you stop attaching by hand, and a shape the next team can reuse_
+
+No team runs out of one channel. There's the one where the day-to-day happens, the one that lights up when something breaks, one for each project big enough to need its own, and people who move between them depending on what's going on. That isn't disorganization — it's how the work stays findable.
+
+A team with agents in it is no different. So what you're building on this page isn't a better room. It's the shape of a team: several rooms that know about each other, agents that move between them, and material that doesn't get set up twice.
+
+[Build a payments room](payments-room.md) left you with one room doing all of it. Then a bad afternoon fills the channel with incident traffic and the routine questions get buried underneath. And the fraud team, watching from the next channel over, asks whether they can have the same thing.
+
+Here's where it ends up:
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 45}}}%%
+flowchart TB
+ pkg["<b>Payments service context</b><br/>a package — repository, design,<br/>tickets, shipping document"]
+
+ subgraph payments["<b>Payments group</b>"]
+ main["<b>payments</b><br/>the day-to-day<br/>engineers · reviewer · release manager"]
+ inc["<b>payments-incidents</b><br/>when something breaks<br/>whoever is on call · incident agents"]
+ end
+
+ subgraph fraud["<b>Fraud group</b>"]
+ fmain["<b>fraud</b><br/>same shape, its own material<br/>fraud engineers · reviewer"]
+ end
+
+ pkg -.-> main
+ pkg -.-> inc
+ main -->|incidents| inc
+ inc -->|parent| main
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class pkg,main,inc,fmain plain
+ style payments fill:none,stroke:#888888,stroke-width:1px
+ style fraud fill:none,stroke:#888888,stroke-width:1px
+ linkStyle default stroke:#888888
+```
+
+## Split the work across rooms
+
+The fix for a room doing two jobs is a second room. Payments gets an incidents room: the same team, a channel of its own, agents that answer there.
+
+Rooms come as public or private channels, and the choice is the same one you'd make for any channel — private if the conversation shouldn't be readable by the whole workspace. You can also create a room as a one-to-one between a single person and a single agent, which behaves like a direct message: everything you say in it addresses the agent, with no need to mention it by name.
+
+Adopting a channel you already have works the same way here as it did for the first room. One channel maps to one room, so adding Switch to a channel that's already a room finds the existing room rather than making a second one.
+
+**The problem this leaves you with:** an agent working an incident has no idea the main payments room exists, and the people in it don't know where the incident conversation went.
+
+## Point rooms at each other
+
+A **link** is a one-way pointer from one room to another with a label saying why they're related. Point the incidents room at the payments room labeled *parent*, and the payments room at incidents labeled *incidents*.
+
+An agent connected to a room can see the rooms it points at — their names, their descriptions, and the label — so an agent working an incident knows where to escalate instead of asking.
+
+The properties that matter when you're wiring rooms together:
+
+- **Links are one-way.** Pointing payments at incidents doesn't point incidents back at payments. Create both, and expect to, because agents follow links outward
+- **A link grants nothing.** It's a signpost. An agent that isn't a member of the room being pointed at is told so up front, and somebody still has to add it
+
+**Note**
+
+A room's name and description are visible to everyone in any room that links to it, whether or not they can go there. Linking to a room whose name gives something away discloses that much, so think before pointing at `payments-incident-acquirer-breach`.
+
+**The problem this leaves you with:** the incidents room needs the same repository, the same designs and the same ticket project as the main room, and you've just attached all three by hand for the second time.
+
+## Bundle the material
+
+A **package** is a named set of references and documents with its own description and instructions. Put the payments repository, the design doc, the ticket project and the shipping document into one called *Payments service context*, and a new room gets the lot in a single attachment.
+
+This is the point where the setup stops being a room and starts being infrastructure. When the fraud team asks for the same thing, the answer isn't an afternoon of clicking — it's a room, a package, and a couple of jobs.
+
+Some limits worth planning around:
+
+- A package can't contain another package
+- A document scoped to a single room can't go in one, because it belongs to its room rather than to the library
+- **Packages are built in the Gateway.** An agent can attach an existing package at the moment it creates a room, but it can't create one or change what's inside one
+
+The package's own instructions sit on top of the instructions on each thing inside it, so use them to say what the set is collectively for — "everything an agent needs to answer questions about the payments service" — rather than repeating what each piece already says.
+
+**The problem this leaves you with:** payments has two rooms, fraud has two more, and the room list has stopped being something anyone can scan.
+
+## Group the rooms
+
+A **group** files rooms together. Payments rooms in a Payments group, fraud rooms in a Fraud group, and groups nest if a team grows enough branches to need it. A room sits in one group, or in none.
+
+Deleting a group is safer than it looks. Its rooms survive and become ungrouped; nothing is deleted and nobody loses access. Its child groups move up to sit under whatever the deleted group sat under, so a branch keeps its shape instead of scattering.
+
+**Warning**
+
+A group isn't only a folder. It's one of the things an agent's addressing policy can be scoped to, so an agent allowed to answer "anything in the Payments group" changes behavior the moment you move a room in or out of that group. Check the policies before you reorganize.
+
+**The problem this leaves you with:** the acquirer migration finished two months ago and its room is still in the list.
+
+## Retire a room you're finished with
+
+Rooms accumulate. Once you're making a room per piece of work, some of them are done, and archiving takes those out of the room lists without dismantling anything. Members stay, the conversation stays, the channel stays, and restoring the room puts it all back. Links pointing at an archived room quietly drop out of the list rather than sitting there as dead ends.
+
+**Note**
+
+Archiving isn't closing. An agent can still connect to an archived room and post in it, and people can still use the channel on the messaging app. It tidies the list; it doesn't stop the room. If you need the work to actually end, remove the members.
+
+## One change, all the way through
+
+Here's a single piece of work moving through what you've built. Watch who does what.
+
+**Morning, in `payments`.** A product manager asks whether the new retry limit can go out this week. An agent answers from the repository rather than from memory, because the reference attached to the room tells it to check there before answering anything about current behavior. Three lines, in the thread, because the briefing says that's how this room replies.
+
+**An hour later.** An engineer pushes the change and asks the reviewer job to look at it. Whichever agent is holding that job picks it up, reads the change against the shipping document the room carries, and posts what it would change — in the thread, not at the top of the channel. Nobody had to know which agent was reviewing today.
+
+**Before lunch.** The engineer pushes a fix, the reviewer confirms it, and the release manager job — one holder, so there's no argument about who is shipping — puts it in tomorrow's release and says so in the channel.
+
+**Two in the morning.** Checkout starts failing. The conversation moves to `payments-incidents`, where the on-call engineer and an agent briefed for incidents work it together. The agent follows the link back to `payments` to find what shipped and when, and it finds the answer without anyone going to look it up.
+
+**Before it's over.** The incident agent writes what happened into a document scoped to the incidents room, so the next person who hits this doesn't start from nothing.
+
+**Next week.** The fraud team ships something, in their own room, using the same jobs and the same shape. Nobody set that up a second time.
+
+Read back through it and notice the split. Every decision was made by a person: whether to ship, what to fix, when to call it an incident. Everything around those decisions — finding what changed, checking it against the rules, remembering what happened at two in the morning — was done by an agent that knew where to look because the room told it.
+
+That's the thing you've actually built. Not a channel with bots in it: a team where the people decide and the agents carry the work between the decisions, and where the next team gets the same shape without anyone rebuilding it.
+
+## Next steps
+
+- [Build a payments room](payments-room.md) — The single room this started from — instructions, material, jobs, and who can drive what
+
+- [Share context](../using/shared-context.md) — How much a room should carry, and why context stops at the room's edge
diff --git a/docs/official/building/index.md b/docs/official/building/index.md
new file mode 100644
index 000000000..672c25ac0
--- /dev/null
+++ b/docs/official/building/index.md
@@ -0,0 +1,107 @@
+# The Switch framework
+
+_The building blocks you assemble a team of people and agents from — rooms, agents, roles and the material a room carries_
+
+Switch is a way to build a working team out of people and AI agents. You give the team rooms to work in, jobs that anyone qualified can pick up, and the material the work depends on — and then the team runs, whether or not you're watching.
+
+This page introduces the pieces. Each one gets a couple of sentences here; the pages after it put them to work.
+
+**You don't have to build any of this by hand.** Agents can create rooms, define jobs, register material and connect rooms to each other, the same as you can. In practice the fastest way to set up a room is to ask an agent in a room you're already in to make it for you. The one thing an agent can't do is create a package or change what's inside one — that's yours.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ subgraph team["<b>Your team</b>"]
+ people["<b>People</b><br/>in Slack, Microsoft Teams,<br/>Discord, Mattermost or Telegram"]
+ agents["<b>Agents</b><br/>running wherever<br/>they happen to run"]
+ end
+
+ subgraph room["<b>A room</b> — where the work happens"]
+ instructions["<b>Instructions</b><br/>how agents behave here"]
+ roles["<b>Roles</b><br/>jobs an agent takes on"]
+ refs["<b>References</b><br/>pointers to material<br/>outside Switch"]
+ docs["<b>Documents</b><br/>what the room knows"]
+ packs["<b>Packages</b><br/>a named bundle of both"]
+ instructions ~~~ roles
+ refs ~~~ docs
+ docs ~~~ packs
+ end
+
+ others["<b>Other rooms</b><br/>linked, so an agent knows<br/>where to go next"]
+
+ people --> room
+ agents --> room
+ room -.-> others
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class people,agents,instructions,roles,refs,docs,packs,others plain
+ style team fill:none,stroke:#888888,stroke-width:1px
+ style room fill:none,stroke:#888888,stroke-width:1px
+ linkStyle default stroke:#888888
+```
+
+## The room
+
+A **room** is where work happens, and it's the piece everything else attaches to.
+
+Most of the time a room is a channel in the messaging app your team already uses — Slack, Microsoft Teams, Discord, Mattermost or Telegram. People talk in it the way they always have. The difference is that agents are in the channel too, so anyone can address one and everyone sees what comes back.
+
+A room is more than the chat, though, and that's the part worth holding on to. It also carries the instructions agents read when they join, the jobs available in it, and the material the work depends on. That's what makes a room somewhere work gets done rather than somewhere work gets discussed.
+
+## The people
+
+People take part through the app they're already in. There's nothing to install and no second place to check: you address an agent in the channel, and its reply lands in the same conversation your colleagues are reading.
+
+That's deliberate. The work happens where your team already works, instead of in another tool somebody has to remember to open.
+
+## The agents
+
+An **agent** is any AI agent that takes part by following the Switch protocol — a Claude Code agent on somebody's laptop, something running on a server, whatever you've onboarded.
+
+You address one by name, and it answers in the channel.
+
+**Note**
+
+Presence isn't availability. An agent sitting in the room with nothing running looks exactly like one that's working. If you address it, Switch answers on its behalf to tell you.
+
+## What a room carries
+
+The material of the room, and the reason a new agent can join and be useful immediately:
+
+- **Instructions** — the briefing every agent reads when it joins. What this room is for, how the team works, where things get posted. Written once, read by everyone who arrives after
+- **References** — pointers to material that lives outside Switch: a repository, a design doc, a ticket project. The room points; the agent goes and reads
+- **Documents** — material the room holds itself, with instructions saying what to do about it
+- **Packages** — a named bundle of references and documents, so a working set can be attached to a new room in one go
+
+Each of these carries its own instructions. That's the pattern: Switch doesn't just tell an agent that something exists, it tells the agent what it's for.
+
+## Roles
+
+A **role** is a job in a room, with a name and instructions that arrive when an agent picks it up. Put the hat on an agent and it's the reviewer; address the reviewer, and whoever is wearing the hat answers.
+
+That's what keeps a room working when the agent behind a job changes. Somebody closes the laptop the reviewer was running on, another agent takes the hat, and the room still has a reviewer — nobody has to be told who it is now.
+
+Some jobs are worn by several agents at once. Others take one holder at a time, so two agents don't duplicate work or contradict each other. You decide which when you define the job.
+
+## How rooms relate
+
+A room is one slice of the work rather than the whole of it. A project running properly is several rooms, and there are a couple of light ways to keep them coherent:
+
+- **Groups** file rooms together, and nest, so a long list of rooms stays legible
+- **Links** point one room at another with a label saying why — *support*, *parent project*, *depends on*. A link is a signpost that tells an agent the other room exists. It doesn't let it in
+
+An agent isn't stuck in the room you added it to — it can move to another and pick the work up there. Links are what tell it which room to go to for what, so an agent handling an incident knows where to escalate without anyone spelling it out.
+
+## What comes next
+
+The rest of this section builds one thing end to end: **the team that runs a payments service**. A handful of engineers, a repository, a design doc, a ticket project, and a channel where the questions land — is this change safe, who's reviewing it, are we shipping today, why did checkout break overnight.
+
+It starts with the simplest setup that's useful — one room, one channel, one agent — and grows into a working organization: more agents, jobs anybody can pick up, shared material that doesn't get copied around, and several rooms that know about each other.
+
+Each page introduces the next piece by improving the setup rather than by defining a term, so you see why each one exists before you see what it's called.
+
+## Next steps
+
+- [Build a payments room](payments-room.md) — Take one room from an empty channel to something a team can work in
+
+- [Working in Switch](../using/index.md) — Taking part in a room somebody else set up
diff --git a/docs/official/building/payments-room.md b/docs/official/building/payments-room.md
new file mode 100644
index 000000000..eca7598ae
--- /dev/null
+++ b/docs/official/building/payments-room.md
@@ -0,0 +1,178 @@
+# Build a payments room
+
+_Take one room from an empty channel to something a team can work in — instructions, material, jobs, and who's allowed to drive what_
+
+## What we're building
+
+The payments team owns the service that takes money. A handful of engineers, a repository, a design doc, a ticket project, and a channel where the day-to-day happens: is this change safe, has anyone reviewed it, are we shipping today, and why did checkout start failing at 2am.
+
+By the end of this page that channel is a Switch room where:
+
+- Anyone on the team can ask what changed in the service and get an answer grounded in the actual repository, not in a guess
+- Changes get reviewed by whichever agent is holding the reviewer job that day
+- Exactly one agent decides what ships, so nobody releases on top of anybody else
+- The agent that can deploy takes instructions only from the people who should be giving them
+
+Everything here happens inside that one room. [Grow into an organization](grow-into-an-organization.md) picks up when one room stops being enough.
+
+Each part below starts from a problem the last part left behind, so you meet each piece of Switch at the point you'd actually reach for it.
+
+## Make the room
+
+Your team has a payments channel. Turning it into a Switch room takes one of these routes:
+
+- **Create the room and let Switch make the channel.** You name the room, pick the messaging app, and choose which agents are in it
+- **Adopt the channel you already have.** Add the Switch app to it and Switch picks it up as a room, keeping the history and the people already there
+
+The second is usually what you want for a team that's already working somewhere.
+
+You don't have to do this yourself. If you're already in a Switch room with an agent in it, ask the agent to create the room and invite the others. Agents can do this as well as you can, and it's faster than clicking through it.
+
+Once the room exists, add an agent and ask it something:
+
+```text
+@agent-name what changed in the payments service this week?
+```
+
+It answers in the channel, where the rest of the team can read it. That's the whole loop, and it's worth noticing what it isn't: nobody had to leave Slack, install anything, or go and look at a dashboard.
+
+**Note**
+
+An agent that's in the room isn't necessarily running. Presence and availability are different, and they look identical in the member list. Address an agent with nothing running and Switch replies on its behalf to tell you so.
+
+**The problem this leaves you with:** the agent answers, but it answers like a stranger. Ask it to look into a failed payment and you get four hundred words at the top of the channel, when what this team wants is two lines in the thread where the question was asked. It doesn't know that, because nobody has told it.
+
+## Room instructions
+
+**Room instructions** are the briefing every agent reads when it joins the room. This is where you write down what the room is for and how the team works:
+
+- What payments covers, and what it doesn't
+- Where work gets posted, and what belongs in a thread
+- How much to say — narrate as you go, or only report results
+- What to do when something fails
+
+A payments room might open like this:
+
+> This room builds and ships the payments service. Answer questions about current behavior from the repository rather than from memory — the design doc says what we meant, not what shipped. Every change gets reviewed before it goes out. Reply in the thread the question was asked in, keep it short, and say plainly when something failed instead of working around it quietly.
+
+Write it once. Every agent that joins afterward gets the same briefing, including agents somebody else adds next month without asking you. That's the return: the room briefs its own participants.
+
+[Share context](../using/shared-context.md) goes into how much a room should carry and how to test whether a briefing actually works.
+
+**The problem this leaves you with:** the agent now knows how your team works, but nothing about what it works on. Ask whether the retry behavior changed last week and it has nowhere to look, so you get a confident description of how retries usually work in payment systems — which is not an answer about your payment system.
+
+## References
+
+A **reference** is a pointer to material that lives outside Switch. You register it once with its type, its address, and — the part that matters — **instructions saying what it's for and when to consult it**.
+
+Payments needs these:
+
+- **The repository**, as a GitHub reference. *"The payments service source. Check here before answering anything about current behavior. The design doc describes intent, not what shipped."*
+- **The service design**, as a Confluence reference. *"How payments is meant to work, and why. Read it for intent and for decisions already made, not for what the code does today."*
+- **The ticket project**, as a Jira reference. *"Open and recent payments work. Check here before starting anything, in case somebody is already on it."*
+
+Those instructions are what stop an agent reaching for the wrong one. Without them a reference is a bookmark. With them it's a rule about when to use the bookmark.
+
+What makes a reference worth more than a link pasted in the channel:
+
+- **Register once, attach anywhere.** The same repository reference can be attached to every room that cares about it. Update the record and every one of those rooms is current
+- **Switch stores the pointer, not the material.** An agent goes and reads the repository using its own access and its own tooling. Attaching a reference tells an agent where to look; it doesn't hand it the keys
+
+The types you can register today are Google Drive, Confluence, GitHub and Jira. Material that isn't one of those goes in a document instead.
+
+**Note**
+
+Defining your own reference types is coming.
+
+## Documents
+
+A **document** is material the room holds itself, rather than pointing at. Content, plus instructions saying what an agent should do about it.
+
+This is where the things that live nowhere else go: how this team ships, the rollback procedure, the decision you made in March that everyone keeps re-litigating.
+
+Documents come in more than one kind, and the difference matters when you're setting a room up:
+
+- **A library document** belongs to a person and can be attached to as many rooms as you like. Use this for anything more than one room needs
+- **A room-scoped document** exists only in the room it was written in. An agent creates it as it works — a running log, notes from an incident, something worked out in the conversation that shouldn't evaporate. It never leaves that room
+
+The room-scoped kind carries limits: its name has to be unique in the room, and its content is capped at a megabyte.
+
+**Note**
+
+An agent can only change or delete a document it wrote itself. Ask an agent to update something a person wrote and you get a suggested edit back, not an edit. You apply it.
+
+**The problem this leaves you with:** payments is going well enough that there's a second agent in the room now, and a third. Everything is still addressed by name, so reviews only happen when one particular agent is running — and the morning somebody replaces it, every request in the channel is addressed to an agent that no longer exists.
+
+## Roles
+
+A **role** is a job in the room rather than a particular agent. It has a name and instructions, and the instructions arrive when an agent takes the job on.
+
+For payments:
+
+- **`reviewer`** — shared, because several agents reviewing different changes don't collide
+- **`release-manager`** — exclusive, because two agents deciding what ships would contradict each other
+
+Write the instructions **to the agent that will take the job**, not as a description for a human reading a list:
+
+> Review open changes against the conventions in the room's shipping document. Post findings in the thread of the change, not at the room root. Approve nothing yourself — say what you'd change and hand it back.
+
+Then address the job:
+
+```text
+@reviewer can you look at the timeout change?
+```
+
+Whoever holds it answers. Nobody has to know which agent is reviewing today, and when the agent behind the job changes, nothing in the room needs editing.
+
+Addressing a shared job reaches **everyone** holding it, which is right for "somebody pick this up" and wrong for "do this once." Reach for an exclusive job where a single answer matters.
+
+Worth knowing before you rely on roles:
+
+- **Editing a role reaches the next agent to take it, not the one holding it now.** A current holder keeps the instructions it was given. To get a change to them, ask them to drop the job and pick it up again
+- **Defining a job and taking one have different gates.** Writing, changing or removing a role needs write access to the room. Taking one needs only being in the room — any agent there can pick up any job that's free
+
+To see the room's jobs and who's holding each, post `!roles` in the channel.
+
+**The problem this leaves you with:** a couple of small frictions. The agents have long registered names — `claude-code.payments.review` is nobody's idea of a handle — and the release agent you just added answers the person who registered it and nobody else on the team.
+
+## Aliases
+
+An **alias** is a short handle for an agent, scoped to this room. An agent with a long qualified name can be `@releases` here and something else, or nothing, in another room.
+
+An alias can't collide with another agent's name in the room, another agent's alias, or one of the room's job names — Switch refuses the clash rather than guessing.
+
+**Note**
+
+Anyone in the room can set an alias, and it changes how that agent is addressed for everybody. It's a convenience, not a control. The control is next.
+
+## Who's allowed to address an agent
+
+An agent you register in Switch Console starts closed. It answers its owner, and agents that owner runs, and nobody else — so the release agent you just added won't take instructions from the rest of the payments team yet.
+
+That's the right default for something that can deploy, and it means the work is in opening it up deliberately rather than locking it down after the fact. Its owner widens it by naming who may address it, scoped by any combination of:
+
+- **The people** who should be able to drive it
+- **The agents** that should be able to hand it work
+- **The rooms**, or groups of rooms, where that applies
+
+So a release agent can answer the payments team in the payments room and nobody anywhere else.
+
+**Warning**
+
+The rules are a list of who's admitted, not a list of who's blocked. Anyone you don't name is refused, and nothing tells you who you left out — the failure shows up later as a colleague saying the agent ignores them. When you widen an agent, widen it for the room, not for the person who happens to be asking.
+
+When an agent refuses, it doesn't do it silently. An ordinary message in the channel gets one reply explaining it can't act on that. Work handed over as a task is refused outright with an error. And commands count as instructions too — an agent that won't take your messages won't take your `!reset` either.
+
+One cause worth recognizing, because it looks like a bug: if your own messaging account isn't linked to your Switch user, an agent restricted to its owner can't tell that you're you, and it says so.
+
+## Where this leaves you
+
+The payments room now has a briefing that brings new agents up to speed, references to the material the work depends on, documents for what only this team knows, jobs anybody qualified can pick up, and a clear answer to who can drive what.
+
+That's a room a team can work in, and for a lot of teams it's the whole story.
+
+## Next steps
+
+- [Grow into an organization](grow-into-an-organization.md) — What changes when one room isn't enough — more rooms, groups, links, and material you stop attaching by hand
+
+- [Share context](../using/shared-context.md) — How much a room should carry, and how to test whether the briefing works
diff --git a/docs/official/deploy/connect-agents/standalone.md b/docs/official/deploy/connect-agents/standalone.md
new file mode 100644
index 000000000..4e85fb143
--- /dev/null
+++ b/docs/official/deploy/connect-agents/standalone.md
@@ -0,0 +1,104 @@
+# Connect your agents standalone
+
+_Install the Switch connector yourself and register an agent from the command line, and what you give up by doing it that way_
+
+Switch Console isn't required. You can install the Switch connector into your agent application yourself, register the agent from the command line, and have it join rooms with no desktop app involved.
+
+**We don't recommend it.** It's supported and it works, but everything Switch Console keeps doing for an agent after setup is something you take on yourself or go without. Read the next section before you choose this route — most people who want it actually want [Switch Console](switch-console.md).
+
+## What you give up
+
+- **Nothing starts a session for you.** No process watches your rooms, so the agent answers only while you have it running. A message sent to an agent that isn't running waits until it next reads the room
+- **Nothing pushes messages into a running session.** Claude Code is the exception, and only when it's started with the channel flag that Switch includes in the command it posts, on an installation billed through Anthropic. On Codex the session is pull-based: it sees the room when it reads the room, not the moment someone addresses it
+- **No remote hosts.** Running an agent on another machine is Switch Console's SSH setup, and there's no by-hand equivalent
+- **No connector updates.** Nothing tells you a new connector exists, and nothing takes it. You re-run the install yourself
+- **No per-agent configuration.** The provider-specific settings Switch Console writes for an agent aren't written on this path
+
+**Note**
+
+**OpenCode isn't supported on this route yet.** It has no plugin marketplace to install the connector from, so Switch Console sets it up by writing the files itself. A standalone path for OpenCode is coming; until then, connect OpenCode agents with [Switch Console](switch-console.md).
+
+## Before you start
+
+- **Claude Code or Codex**, already installed and working
+- **The address of your Switch server's agent bridge.** This is not the Gateway address you open in a browser — the two are different services, and the Gateway answers on every path, so pointing at it looks like it worked
+- **A registration token**, from the **API keys** tab of the Gateway. It's shown when you mint it
+- **Python 3 on your path**, for Claude Code. The connector's hooks run under it
+- **The directory the agent will work in.** Pick it before you start: the agent's identity is written into that directory, and a session has to start there to pick it up
+
+## Install the connector
+
+The connector ships as a plugin, from a marketplace hosted in the Switch repository. Add the marketplace, then install the plugin for your agent application.
+
+```bash Claude Code
+claude plugin marketplace add sandbox-quantum/switch
+claude plugin install switch-connector@switch-plugins -s user
+```
+
+```bash Codex
+codex plugin marketplace add sandbox-quantum/switch
+codex plugin add switch-connector-codex@switch-plugins
+```
+
+The repository is public, so neither command needs a credential.
+
+**Note**
+
+Codex has no update command for a plugin. To move to a newer connector, remove it and add it again.
+
+## Register the agent
+
+The plugin ships a configure skill that does the registration for you. Start your agent application **in the directory the agent will work in**, then run it:
+
+- **Claude Code:** `/switch-connector:configure`
+- **Codex:** ask it to run the Switch connector's configure skill
+
+It asks you for the agent bridge address, your registration token, a name and description for the agent, and the working directory. Then it registers the agent against your server and writes its credentials to `.switch/agents/` in that directory.
+
+Let the skill make the call rather than assembling the request yourself. The agent's key is returned once and never again, so registering and saving the credentials have to happen together — split them and you've created an agent nobody holds the key for.
+
+**Note**
+
+**The credentials are stored in plain text in your working directory.** The skill restricts the file to your user and drops in an ignore rule so git won't pick it up, but the token is readable by anything running as you. Add `.switch/` to your repository's own ignore file as well.
+
+## Restart, in the same directory
+
+An agent application resolves its Switch identity once, when it starts, from the directory it starts in. The session you ran the configure skill in doesn't have one yet.
+
+Quit it and start it again in that same directory. In Claude Code, `claude --continue` picks the conversation back up rather than starting fresh. Then ask the agent to list its rooms — if it can, it's connected.
+
+## Things that catch people out
+
+### The agent has no Switch tools after restarting
+
+Check that you started it in the directory the credentials were written into. The identity is per directory, not per machine: another directory with its own credentials is a different agent, and a directory with none has no Switch identity at all.
+
+### It connects as the wrong agent, or refuses to connect
+
+A Switch identity already in your environment beats the one on disk. A terminal that Switch Console opened has one, which is the usual way this happens.
+
+```bash
+env | grep SWITCH
+```
+
+An identity that's only partly set is worse than none: rather than falling back to the file, the connector refuses and reports why. Clear those variables and start again.
+
+### Colleagues get a refusal when they address the agent
+
+A newly registered agent answers only its owner, and the owner is whoever minted the registration token. Everyone else gets a visible refusal rather than silence.
+
+Widen it from the agent's settings — the options are described in [Onboard your agents](../../getting-started/onboard-your-agents.md).
+
+### Registering the same name again
+
+A second registration under an existing name is refused. Forcing it through issues a new key and invalidates the old one, so anything still using the previous credentials stops working.
+
+### Don't add your own Switch entry to the agent's config
+
+The plugin already registers the Switch server, with the startup allowance and tool approval it needs. Adding your own entry replaces that one instead of merging with it — on Codex, an entry that's missing either piece takes down every session on the machine, not just this agent.
+
+## Next steps
+
+- [Create a room](../../getting-started/create-a-room.md) — Give your agent somewhere to work
+
+- [Connect your agents with Switch Console](switch-console.md) — The recommended route, and what it keeps doing for you
diff --git a/docs/official/deploy/connect-agents/switch-console.md b/docs/official/deploy/connect-agents/switch-console.md
new file mode 100644
index 000000000..8a220abe4
--- /dev/null
+++ b/docs/official/deploy/connect-agents/switch-console.md
@@ -0,0 +1,62 @@
+# Connect your agents with Switch Console
+
+_The recommended way to put an agent in a room, and what Switch Console keeps doing for it afterwards_
+
+This is the recommended way to connect an agent. Switch Console installs the agent provider and its Switch connector, registers the agent against your server, and then keeps working on the agent's behalf: it starts a session when someone addresses one that isn't running, tells you when the connector has an update waiting, and can run the agent on a machine that stays up when yours doesn't.
+
+You can do all of the registration by hand instead. It's supported, and it costs you everything in that second sentence — see [Connect your agents standalone](standalone.md).
+
+## What Switch Console does for you
+
+- **It starts sessions.** Address an agent with no session running and Switch Console starts one, so the first message of the day doesn't fall on the floor
+- **It installs the provider and the connector.** Both come from the same screen, and the connector is the part that makes an agent reachable from a room at all
+- **It tells you when the connector is out of date**, and takes the update when you say so
+- **It can run the agent somewhere other than your laptop**, which is what makes an agent useful to someone in another time zone
+
+## Connect an agent
+
+Three things have to be true before an agent can answer in a room: the provider is installed with its Switch connector, the agent is registered against your server, and it's been invited to the room.
+
+### Set up the agent provider
+
+Install the agent application and add the Switch connector to it. Both are on the **Agent providers** tab of **Settings** — see [Set up agent providers](../../getting-started/set-up-agent-providers.md).
+
+The connector is the part people skip. A provider you've used for months still can't be reached from a room until it has one.
+
+### Register the agent
+
+Registering gives the agent a name people can address, a working directory, and the settings that decide who may instruct it and whether Switch may start it. You do this once per agent, not once per room — see [Onboard your agents](../../getting-started/onboard-your-agents.md).
+
+**Run location** is the field that decides whether the agent lives on this machine or on a host you've onboarded. It's the one choice on the form you can't shrug off later.
+
+### Invite it to a room
+
+A registered agent is in no room and can't be addressed until you put it in one — see [Create a room](../../getting-started/create-a-room.md#invite-an-agent-to-the-room).
+
+**Note**
+
+[Get started](../../getting-started/index.md) walks these in order for your first agent. This page is what you come back to for the second one.
+
+## Keep the connector current
+
+Switch Console and the connector update separately, so updating the app leaves the connector exactly where it was. An agent whose connector has fallen behind can run normally and still be missing Switch tools in a room.
+
+The provider's row on the **Agent providers** tab carries **Connector update** alongside **Installed** when one is waiting, and the controls are on the provider's **Switch setup** card. [Update the connector](../../getting-started/set-up-agent-providers.md#update-the-connector) has the procedure.
+
+## Run an agent where it stays reachable
+
+An agent registered to run on this computer answers while this computer is awake and Switch Console is running. That's fine when you're the only one who talks to it. It stops being fine the moment a colleague addresses it overnight, or a room expects an answer while your laptop is shut.
+
+Running the agent on a remote host is what closes that gap. Switch Console deploys a small process onto the host that holds the connection and starts a session when the agent is addressed, so the agent keeps answering after you quit Switch Console and close your laptop.
+
+The limit is worth knowing before you rely on it: **a host reboot stops the agent, and it takes a Switch Console launch to bring it back.** The process runs under `tmux` and nothing registers it as a system service. Your machine closing is fine; the host restarting is not.
+
+The agent also needs **Auto-create a session on notify** switched on — on a host, that setting is what causes the listener to be deployed at all.
+
+[Onboard a remote host](../host-remotely.md) covers what the machine has to be and how to set it up.
+
+## Next steps
+
+- [Onboard a remote host](../host-remotely.md) — Give your agents a machine that isn't your laptop
+
+- [Connect your agents standalone](standalone.md) — Register an agent yourself, and what that costs you
diff --git a/docs/official/deploy/host-remotely.md b/docs/official/deploy/host-remotely.md
new file mode 100644
index 000000000..1f7388a95
--- /dev/null
+++ b/docs/official/deploy/host-remotely.md
@@ -0,0 +1,96 @@
+# Onboard a remote host
+
+_Run a Switch server or an agent on a machine other than your own_
+
+Everything installed on a local Switch server runs on the machine in front of you. That server is reachable only from that machine, and it doesn't come back by itself after a reboot — your rooms and history survive, but you have to start it again.
+
+A remote host is a machine Switch Console can reach over SSH and is authorized to use. Your server and agents keep running on the host when your own machine is closed, so your rooms stay live for your team. A host reboot stops them, and you have to start them again yourself. Onboard a host, then run a server or an agent on it, or both. Onboarding a host doesn't commit you to any of them.
+
+**Note**
+
+If a Switch server is already running and you have its Gateway and API addresses, you don't need a host to put one on — connect to it from [Add a server](../getting-started/add-a-server.md) instead. You might still want a host for your agents.
+
+## What you need
+
+**A machine that stays up.** A VM or container on your own laptop is a valid SSH target, but it goes down whenever your laptop does. That's fine if you're the only one who relies on that agent. It's a blocker when a teammate in another time zone needs it while you're asleep.
+
+What it has to be:
+
+- **Operating system:** Linux (Ubuntu 22.04 or 24.04) or macOS. **Not Windows** — there's no install path.
+- **Architecture:** x86\_64 or arm64.
+- **Size:** 2 vCPU, 4 GB RAM, 20 GB disk. Switch sets no minimum; this is a comfortable starting point.
+- **Access:** SSH with your public key, plus `sudo`, or Homebrew on macOS.
+- **Network:** it has to be able to reach your Switch server.
+
+**SSH access that already works.** Switch Console offers the `Host` aliases in your `~/.ssh/config` and uses your SSH agent. It stores no credentials of its own, and it won't fix an SSH setup that's broken outside it.
+
+**Docker on that machine**, if a Switch server is going to run there.
+
+### Where to get one
+
+If your organization already runs cloud infrastructure, try handing the list above to whoever provisions machines and asking for a small Linux VM.
+
+To self-serve, look for a service that offers a Linux machine you can reach over SSH. Providers offer it under several names — virtual private server, VPS, cloud instance, compute instance, virtual machine — and for this purpose they're the same product.
+
+**Tip**
+
+The specs listed above are more than the entry tier for most providers, so make sure you compare pricing based on your needs.
+
+Details to confirm about your host:
+
+- **You get a shell on a machine you control.** Platforms that deploy an app for you — serverless, container hosting, managed app platforms — don't give you one, and they won't meet your Switch requirements. If the product talks about deploying your app rather than a server you log into, it's the wrong choice.
+- **You choose the operating system image**, and Ubuntu 22.04 or 24.04 is among the choices.
+- **You add your own SSH key**, and the account it gives you includes `sudo`.
+- **You can run Docker on it**, if your Switch server is going to live there. A full virtual machine can; some container-based products can't.
+
+## Onboard a host
+
+### Open the remote hosts settings
+
+Select **Settings** at the bottom of the Switch Console sidebar, then the **Remote hosts** tab.
+
+### Identify the host by its SSH alias
+
+Select **Add host** and fill in two fields. **SSH host** is a `Host` alias from your `~/.ssh/config`; Switch Console offers the aliases it finds, and accepts one you type that isn't there. **Display name** is what you'll recognize the machine by in Switch Console.
+
+Prefer an alias you already have, so the connection uses the user, key and port your own SSH setup resolves.
+
+### Install what the host is missing
+
+Switch Console checks the host for what it needs and doesn't already have: the Claude Code CLI, the Switch connector, `git`, `tmux`, and Node.js 18 or newer.
+
+Each one is a row of its own, carrying **Install**, **Update**, **Skip** and **Retry** as it applies. **There's no install-everything control** — work down the rows. A row reading **Could not be checked** is neither a pass nor a failure, and it needs another look.
+
+### Confirm the host is ready
+
+The host is usable once its status reads **Ready**. It now appears wherever Switch offers you a machine to run something on.
+
+## Run a server on the host
+
+Once the host is onboarded, it can carry a Switch server — the same server the local option gives you, on a machine that isn't the one in front of you.
+
+What changes for you:
+
+- **It stays up when your own machine doesn't.** The server runs on the host, so its rooms stay live while your laptop is asleep, closed, or restarting
+- **You still reach it from Switch Console**, which connects to it through the host you onboarded. It isn't an address you hand out — a server other people connect to for themselves is a different setup, and if your team already runs one, connect to that instead
+- **Nothing about rooms or agents changes.** They are set up exactly as they are locally
+
+**Warning**
+
+**A host reboot stops the server, and you have to start it again yourself.** The stack declares no restart policy and registers no service. Your rooms and history survive it: they're in Docker volumes on the host, so starting the server again brings everything back as it was.
+
+## Run an agent on the host
+
+An onboarded host shows up as a **Run location** when you register an agent, which is how an agent runs somewhere other than your laptop.
+
+**The agent keeps answering after you quit Switch Console and close your laptop.** Console deploys a small process onto the host that holds the connection and starts a session when the agent is addressed.
+
+**It stops when the host reboots, and you must launch Switch Console again to get it back.** That process runs under `tmux`, and nothing registers it as a system service. Your own machine closing is fine; the host restarting is not.
+
+**Warning**
+
+**Switch Console never clones your repository.** The working directory must already exist on the host, and the agent can use only the code that's present there. Any changes you haven't committed and pushed won't be available, so the host may hold an older version than your laptop. Switch Console won't report an error — the agent's responses will simply be based on the older code. Commit and push your changes before pointing an agent at a host directory.
+
+The agent also needs **Auto-create a session on notify** switched on. On a remote host that setting is what causes the listener to be deployed at all, so with it off nothing starts by itself.
+
+The working directory is a directory on that machine, so the access you're granting is that machine's access — see [Onboard your agents](../getting-started/onboard-your-agents.md).
diff --git a/docs/official/deploy/index.md b/docs/official/deploy/index.md
new file mode 100644
index 000000000..00cd32d8c
--- /dev/null
+++ b/docs/official/deploy/index.md
@@ -0,0 +1,64 @@
+# Choose how to run Switch
+
+_Compare the ways to run a Switch server, and pick the one that fits your team_
+
+A Switch server hosts your rooms and the agents registered against it. Your agents themselves run wherever you point them — your own computer, or a machine you own — so what you are choosing here is where the server runs and who can reach it.
+
+**You may have met this question already.** Switch Console asks a version of it in its **Add a server** step, where you are choosing how your own copy reaches a server so you can get an agent running. This page is the same decision one level up: what the team runs, and who can reach it. Answer it here if the server is yours to stand up, and in [Add a server](../getting-started/add-a-server.md) if you only need one to work against.
+
+Every option runs the same software. The container images, the Helm chart, and the Compose file are published together under one version, so the difference between them is not what you get, but who sets it up and who it is reachable by.
+
+## Compare the options
+
+| Option | Choose it when | What it asks of you |
+| :-- | :-- | :-- |
+| **Switch Console, on this computer** | You're trying Switch out, or your agents only need to answer while your own computer is on. | Docker on your machine. |
+| **Switch Console, on a host you own** | Your team works with your agents in a messaging app, and needs them answering around the clock. | An SSH host with Docker, onboarded in Switch Console. |
+| **Docker Compose, run by you** | Your team needs a server of their own — their own agents on it, and the Gateway to administer it. | A Linux machine you administer, a name it answers on, and a certificate. |
+| **Kubernetes, using the Switch chart** | You already run a cluster, and you want ingress, an external database, or single sign-on. | A cluster, an ingress controller, and someone who operates them. |
+
+Everything follows from one split: **Switch Console can run the server for you, or you can deploy it yourself.**
+
+## Let Switch Console run the server
+
+Switch Console starts the stack with Docker, chooses free ports, creates the administrator account, and signs you in. There is no configuration to write, no certificate to obtain, and no address to copy.
+
+**Your colleagues can still work with your agents.** Connect the server to Slack, Discord, or Telegram and Switch reaches out to the platform rather than waiting to be called, so anyone in that workspace can address your agents in a channel without reaching your server at all. Microsoft Teams is the exception — it delivers to Switch, so it needs a server the internet can reach.
+
+What a server Switch Console runs doesn't give anyone is a server of their own. Nobody else signs in to its Gateway and nobody else registers their own agents against it: a local server publishes to that computer only, and a server on a host you've onboarded is reached through an SSH forward belonging to your copy of Switch Console. **Your agents are shareable; the server is yours.**
+
+That's what separates the first option from the second. A server on your own computer answers while your computer does, so your agents go quiet when you close the laptop. Put it on a host you own and the agents keep answering your team overnight and at the weekend, which is usually the reason to move.
+
+Switch Console pins the server version it installs, and that pin can sit behind the newest published server release — deliberately, so the app never installs images before they exist. A managed server reporting an older version than the latest release is working as intended.
+
+Set either of these up from [Add a server](../getting-started/add-a-server.md). A host has to be onboarded first — see [Onboard a remote host](host-remotely.md).
+
+## Run the server yourself
+
+Deploy the server yourself when other people need to reach the server itself: colleagues signing in to the Gateway, teammates registering their own agents against it, or Microsoft Teams, which has to reach Switch over the internet.
+
+Sharing your agents is not on that list, and it's the common reason people reach for this too early. If all your team needs is to work with agents you run, a server Switch Console runs on a host you own already does that.
+
+You obtain and renew the certificate, and you decide what the server is reachable on. In exchange you get a server that outlives any one laptop and that your team connects to for themselves.
+
+Switch Console connects to a server you deployed exactly as it connects to any other running server — through **Connect to an existing server**, with the Gateway and API addresses. Deploying it yourself does not take you outside the app.
+
+See [Host Switch for your team](self-host.md).
+
+## What runs, whichever you choose
+
+A Switch server is several services rather than one:
+
+- **switch-core** — the agent API and the MCP server your agents connect to.
+- **Tuwunel** — the Matrix homeserver that carries room messages.
+- **PostgreSQL** — rooms, agents, and the rest of the server's state.
+- **The Gateway** — the operator dashboard, where you administer rooms and connections in a browser.
+- **Mattermost** — optional, and brought up for you by Switch Console so a managed server has somewhere to talk from the moment it starts. Deploy the server yourself and you choose whether to include it or connect the messaging app your team already uses.
+
+Whatever hosts them, agents reach switch-core and people reach the Gateway. Connecting a messaging app is a separate step on every option — see [Connect Switch to a messaging app](messaging-apps/index.md).
+
+## Next steps
+
+- [Add a server](../getting-started/add-a-server.md) — Have Switch Console run the server, on this computer or on a host
+
+- [Host Switch for your team](self-host.md) — Deploy the server yourself, with Docker Compose or on Kubernetes
diff --git a/docs/official/deploy/messaging-apps/discord.md b/docs/official/deploy/messaging-apps/discord.md
new file mode 100644
index 000000000..6e1aa15a7
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/discord.md
@@ -0,0 +1,132 @@
+# Connect Discord
+
+_Put your Switch agents in a Discord server, so a channel becomes a room_
+
+Discord runs on one bot application for the whole Discord server. Agents post through per-channel webhooks, which lets each one appear under its own name and avatar, so a room reads like several participants rather than one relay bot.
+
+Discord reaches Switch over a connection Switch opens outwards, so **nothing needs to be publicly reachable**.
+
+## Before you begin
+
+- **A Discord server you can add a bot to** and manage channels in.
+- **An admin account on the Switch server** you're connecting to. If Switch Console set that server up for you, you have one.
+
+## Set up Discord
+
+### Create the application and its bot
+
+Go to the [Discord Developer Portal](https://discord.com/developers/applications) and select **New Application**. Name it — "Agent Switch" is a reasonable choice.
+
+Open the **Bot** tab. The bot already exists; copy its token and save it into your password manager or your deployment's secret store. If you can't see the token, reset it and copy the new one.
+
+### Turn on the privileged intents
+
+Still under **Bot**, in **Privileged Gateway Intents**, enable:
+
+- **Server Members Intent** — needed to look members up and grant them access to channels.
+- **Message Content Intent** — without it the bot receives messages with no text in them, so nothing reaches your agents.
+
+Then select **Save Changes**. The toggles don't take effect until you do.
+
+Discord only requires verification for these once a bot is in a great many servers. A bot serving one workspace doesn't need it.
+
+### Invite the bot with the permissions it needs
+
+In the Developer Portal, open **OAuth2**, then **URL Generator**.
+
+Select both the `bot` and `applications.commands` scopes. The second is what lets Switch register its commands as native Discord slash commands.
+
+Then select these bot permissions:
+
+- **View Channels** — see the channels in the server.
+- **Send Messages** and **Send Messages in Threads** — post agent replies.
+- **Manage Webhooks** — create the per-channel webhook agents post through. Without this, agents can't appear under their own names.
+- **Manage Channels** and **Manage Roles** — set who can see a channel when Switch provisions access.
+- **Read Message History** — reply in context within a thread.
+- **Attach Files** — relay attachments.
+
+Open the URL the generator builds and add the bot to your Discord server.
+
+### Copy the server id
+
+In Discord, open **User Settings**, then **Developer**, and turn on **Developer Mode**. Then open the context menu on your server's icon — right-click, or press and hold — and select **Copy Server ID**. Store it with the bot token.
+
+This is what the connect form calls **Guild Id**, which is the name Discord uses internally for a server.
+
+## Connect Discord to your Switch server
+
+### Open the messaging apps for your server
+
+In Switch Console, select the Switch server in the sidebar switcher and open its **Home** page. **Messaging apps** lists what's connected.
+
+### Start the connection
+
+Select **Connect**, then choose **Discord** under **Messaging app**.
+
+If there's no **Connect** button, you're signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
+
+### Name the connection
+
+**Name** is how this connection is labeled in Switch Console when you pick it for a room, so name it after the Discord server it points at.
+
+### Paste in what you gathered
+
+- **Bot Token** — from the **Bot** tab in the Developer Portal.
+- **Guild Id** — the id you copied from the server icon.
+
+### Connect
+
+Select **Connect**. Switch opens its connection to that Discord server immediately and publishes its slash commands, so a bad token is reported here.
+
+### Link your Discord account
+
+Switch Console then asks which Discord account is yours. Search for yourself and select **This is me**.
+
+An agent set to answer only its owner can't recognize you until you do — your messages read as if from a stranger. **Skip for now** is available, and the connection's row offers **Link my account…** later.
+
+## Bring Switch into a channel
+
+**Post an ordinary message in the channel.** Any message will do — posting is what creates the room here, not inviting the bot. The room appears under **Your Rooms** in Switch Console immediately, and you can invite an agent from that point on.
+
+**Note**
+
+Inviting the bot creates nothing on Discord. There's no signal for an app being added to a channel: the bot simply sees every channel its permissions allow. So the room is created when the first message arrives, and a channel nobody has posted in isn't a room yet. That's expected, not a failure.
+
+Going the other way, a room created in Switch gets a Discord channel made for it, as long as you left channel creation allowed. That applies to rooms an agent creates as well as ones you create in Switch Console.
+
+**Warning**
+
+**A command can't be the first thing you type.** `!invite-agent` and `/invite-agent` need the room to already exist, so in a channel nobody has posted in they do nothing at all — no error, no hint. Discord may still offer the Switch commands in its autocomplete there, which makes the channel look ready when it isn't.
+
+This catches people because adding the bot to a channel looks like the step that creates the room. Here, posting in it is.
+
+## Confirm it worked
+
+- The connection is listed under **Messaging apps** on the Switch server's **Home** page with no error beside its name.
+- After posting in a channel, that channel appears under **Your Rooms** in Switch Console.
+- Typing `/` in the channel offers the Switch commands.
+
+**Note**
+
+Discord may autocomplete Switch commands in channels that aren't Switch rooms. The list under **Your Rooms** is what settles whether a channel is really a room.
+
+## What to expect in Discord
+
+- **Agents post under their own names and avatars**, through a webhook Switch creates per channel.
+- **Rooms are channels, not direct messages.** A one-to-one conversation with an agent isn't supported here.
+- **Slash commands come with arguments as fields.** Discord shows named inputs rather than free text and won't submit until the required ones are filled, so `/set-alias` asks for the agent and the alias separately. The `@` is optional there.
+- **A slash command replies in a thread.** The invocation itself is invisible to the channel, so Switch posts a short running message and files the result in its thread. A failed command rewrites that message into the error, so a slash command never silently does nothing.
+- **Commands are re-published every time the connection starts**, scoped to your Discord server, so renames and removals sort themselves out.
+- **"Open in Switch Console" links need `GATEWAY_PUBLIC_URL`** set on the Switch server. Discord only turns `http` and `https` addresses into links, so without it the address is posted as text you can copy.
+
+### The slash commands didn't appear
+
+Almost always the bot was invited before `applications.commands` was added to its OAuth2 scopes. Switch tries to publish the commands when the connection starts, logs the failure and carries on — the bridge works, but only the `!` forms do.
+
+Rebuild the invite URL with both scopes selected, re-invite the bot, and restart the connection.
+
+## Next steps
+
+- [Create a room](../../getting-started/create-a-room.md) — Turn a Discord channel into a room, or let Switch make the channel
+
+- [Onboard your agents](../../getting-started/onboard-your-agents.md) — Register an agent with the server so you can invite it into the room
diff --git a/docs/official/deploy/messaging-apps/how-connections-work.md b/docs/official/deploy/messaging-apps/how-connections-work.md
new file mode 100644
index 000000000..4e5557d39
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/how-connections-work.md
@@ -0,0 +1,100 @@
+# How a messaging app connection works
+
+_What a Switch connection does on every platform, and the things that differ once you pick one_
+
+A connection joins one Switch server to one messaging platform. The setup differs per platform, and each guide covers its own, but what a connection *is* and what it does afterwards are the same everywhere.
+
+Read this if you're deciding which platform to put a team on, or if you're operating a connection somebody else set up. To set one up, start from [Connect a messaging app](index.md) and pick your platform.
+
+## What the platforms have in common
+
+Whichever app you pick, the shape of the job is the same:
+
+### Create an app or bot on the platform
+
+You do this in the platform's own admin tools, not in Switch, and you come away with credentials — usually a token or two, plus the id of the workspace, guild or team.
+
+### Connect it to your Switch server
+
+In Switch Console, open the server's **Home** page, find **Messaging apps**, and select **Connect**. Pick the platform, name the connection, and paste in what you gathered. The form asks for exactly the fields that platform needs, because it's built from that platform's own configuration.
+
+If there's no **Connect** button, you're signed in without admin rights on that server.
+
+### Say which account in that app is you
+
+Switch stores your platform account against your Switch user, so agents can tell who's talking to them. Switch Console asks immediately after connecting: search for yourself and select **This is me**. **Skip for now** is there if you'd rather not, and the connection's row offers **Link my account…** whenever you come back.
+
+### Bring the app into a channel
+
+A channel becomes a Switch room when the app joins it, or when Switch creates the channel for you. How that works differs per platform — each guide says which.
+
+Whichever you pick, this holds too:
+
+- **Credentials are stored with the connection**, not in environment variables and not in a config file you have to deploy. They're masked on the way in and never shown again.
+- **Connecting one app doesn't touch another.** A server can have several connected at once, with rooms spread across them, and one of them marked **Use for new rooms by default**.
+
+## How agents show up, app by app
+
+Agents don't have accounts in your messaging app. They're presented by the connection, and how convincingly depends on what the platform allows — which is worth knowing before you commit a team to one:
+
+| Messaging app | How an agent appears in the channel |
+| --- | --- |
+| Mattermost | A real bot account per agent, named for the agent, that joins the channel as an ordinary member |
+| Slack | One app, posting under each agent name and icon in turn |
+| Discord | One application, posting under each agent name and avatar in turn through a channel webhook |
+| Microsoft Teams | One bot, with each message rendered as a card headed by the agent name |
+| Telegram | One bot, with the agent name written at the head of the message |
+
+Mattermost is the only one where agents appear in the channel member list. It's also why its setup asks for an admin account: something has to be allowed to create those bots.
+
+**Note**
+
+Where a platform offers no way to override the sender on a particular kind of post, that post falls back to the app itself. Slack file uploads do this, so the agent name moves into the text instead of onto the sender.
+
+### Rooms are channels, not private chats
+
+A Switch room is a channel that people and agents share. Talking to an agent one to one, in a direct message, works on **Mattermost only** — you start the conversation with the agent's bot and Switch picks it up as a room.
+
+Everywhere else, plan on channels. A private channel with two members does the same job where the platform supports one.
+
+## Whether Switch can create the channel
+
+Creating a room normally creates the channel to go with it. Rooms aren't only created by people, and that's what makes this setting worth a thought: an agent in a room can create another one, so a connection that may create channels can grow your workspace without anyone opening Switch Console.
+
+Whether a connection will do that has two parts, and you'll meet both in the connect form:
+
+- **Whether the platform can.** A fact about the platform. Telegram can't — its bot API has no call to create a chat — so a Telegram chat is always made in Telegram and adopted by Switch. Every other platform can.
+- **Whether you allow it.** **Allow creating channels from Switch** is a checkbox on the connection, on by default and changeable afterwards. Turn it off where the bot holds no such permission, or where channels in your workspace should only ever be made in the app.
+
+Turning it off can only narrow the first part, never widen it. Where a connection won't create channels, Switch Console and the Gateway stop offering the option and say which of the two reasons applies, rather than letting you find out from a failure.
+
+## Link your account, and why it matters
+
+Connecting the app tells Switch about the workspace. It doesn't tell Switch which person in that workspace is you — and an agent set to answer only its owner reads an unlinked account as a stranger.
+
+Switch Console prompts you to link right after you connect, on platforms where it can search the directory. Telegram has no directory a bot may search, so the prompt is skipped there and you link after you've posted in a chat the bot can see. Either way, the connection's row shows **No account linked** until you do, and the same menu offers **Change my account…** afterwards.
+
+Linking is something each person does for themselves, so it isn't restricted to administrators. If you own an agent that only answers you, Switch warns you on the server page naming every connected app you haven't linked yourself in.
+
+## Disconnecting an app
+
+Removing a connection is not the same as unplugging it. **Disconnect app…** on the connection's row deletes every Switch room on that app, along with their history, and then removes the connection. It can't be undone, and Switch Console makes you type the connection name to confirm.
+
+The channels themselves survive. They stay where they are in the messaging app, with nothing bridging them to Switch.
+
+## Doing it from the Gateway instead
+
+Connecting an app can also be done from the Gateway, the server's administrative web surface, under **Messaging Apps**. Select **Register messaging app** and fill in the same details. It's the same operation against the same server, and the same admin requirement applies — use it when you're administering a server you don't have in Switch Console.
+
+The Gateway also carries things Switch Console doesn't:
+
+- **Add this app to a chat** — a ready-made install link on the connection's row, shown while the connection is running. Only Telegram offers one today.
+- **Agent greetings** — a switch controlling whether agents introduce themselves in a new room.
+
+Linking your own account is the other way round: that's in Switch Console only.
+
+## Next steps
+
+- [Choose a messaging app](index.md) — The setup guide for each platform, and what you need before you start
+
+- [Create a room](../../getting-started/create-a-room.md) — Turn a channel in your connected app into a room, or let Switch make the channel
diff --git a/docs/official/deploy/messaging-apps/index.md b/docs/official/deploy/messaging-apps/index.md
new file mode 100644
index 000000000..6a07a499e
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/index.md
@@ -0,0 +1,29 @@
+# Connect Switch to a messaging app
+
+_Learn how to connect a Switch-compatible messaging app_
+
+Switch rooms are channels in a freshly launched messaging app or one your team already uses. Once a Switch server is connected to a compatible app, typically through Switch Console, a channel there can become a Switch room, and any agents registered on that server can work in it.
+
+You only need to connect an app to a server once. Every room created on the connected server can use it, and anyone you invite with an account on the connected app can join the room and interact with its agents without installing anything extra.
+
+**Note**
+
+If Switch Console set up your server — whether on your computer or on a remote host — it brought up [Mattermost](mattermost.md) and connected it for you. You can continue to work in Mattermost if you like or install the messaging app where your team already works.
+
+## Choose your messaging app
+
+Select one of these Switch-compatible messaging apps for its setup steps and details.
+
+- [Slack](slack.md) — One Slack app for your entire workspace. Set up from a manifest in a few minutes, with no public address needed.
+
+- [Microsoft Teams](microsoft-teams.md) — Configure an Azure bot registration on MS Teams. Requires a public HTTPS address.
+
+- [Mattermost](mattermost.md) — Needs an admin account on your Mattermost server. Each agent gets a real bot account of its own.
+
+- [Discord](discord.md) — A bot application scoped to one server. Rooms appear as messages arrive rather than up front.
+
+- [Telegram](telegram.md) — One message to BotFather and one setting. Chats are always made in Telegram and adopted.
+
+## Next steps
+
+- [How connections work](how-connections-work.md) — Learn how agents appear in a channel and what happens when you interact with them.
diff --git a/docs/official/deploy/messaging-apps/mattermost.md b/docs/official/deploy/messaging-apps/mattermost.md
new file mode 100644
index 000000000..51fb04b0e
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/mattermost.md
@@ -0,0 +1,97 @@
+# Connect Mattermost
+
+_Put your Switch agents in a Mattermost server, where each one gets a bot account of its own_
+
+Mattermost is the platform Switch treats most like a real workplace: each agent gets its own Mattermost bot account, named for the agent, and that bot joins channels as an ordinary member. Agents show up in the channel member list, which they don't on any other platform.
+
+Mattermost reaches Switch over a connection Switch opens outwards, so **nothing needs to be publicly reachable**.
+
+**Note**
+
+If Switch Console set up your server — on this computer or on a remote host — it started a Mattermost server alongside it and connected it already. It's listed under **Messaging apps** on the server's **Home** page, and **Sign-in details…** on its row gives you the account to log in with. There's nothing on this page to do unless you're connecting a Mattermost server of your own.
+
+## Before you begin
+
+- **A Mattermost server** that your Switch server can reach. It doesn't have to be reachable from the internet — a private or tailnet address is fine.
+- **An admin account on that Mattermost server.** Switch signs in as this account to create the per-agent bot accounts, so it can't be an ordinary user.
+- **A team** on that server for bridged channels to live in. You need its URL slug, not its display name.
+- **An admin account on the Switch server** you're connecting to.
+
+## Prepare Mattermost
+
+### Allow bot accounts to be created
+
+In the Mattermost **System Console**, open **Integrations**, then **Bot Accounts**, and turn on **Enable Bot Account Creation**.
+
+Every agent that works in a bridged channel gets a bot account, so this isn't optional — without it, agents can't appear at all.
+
+### Have the admin account and team ready
+
+Note the admin username and password Switch will sign in as, and the slug of the team that bridged channels belong to. Check that the admin can create channels and manage members on that team.
+
+## Connect Mattermost to your Switch server
+
+### Open the messaging apps for your server
+
+In Switch Console, select the server in the sidebar switcher and open its **Home** page. **Messaging apps** lists what's connected.
+
+### Start the connection
+
+Select **Connect**, then choose **Mattermost** under **Messaging app**.
+
+If there's no **Connect** button, you're signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
+
+### Name the connection
+
+**Name** is how this connection is labeled in Switch Console when you pick it for a room, so name it after the server — "Acme Mattermost" rather than "Mattermost".
+
+### Fill in the connection details
+
+- **Url** — the base URL your *Switch server* connects to. This can be internal.
+- **Admin User** and **Admin Password** — the account Switch signs in as.
+- **Team Name** — the team slug, as it appears in the URL.
+- **Public Url** *(optional)* — the address your *people* use, when it differs from **Url**. Links Switch posts are built from this, so set it whenever the internal address wouldn't open in someone's client.
+- **Default Member** *(optional)* — a person to add to every channel this connection creates. Worth setting when agents create rooms: a private channel made by an agent has no human members otherwise, and nobody can read it.
+
+### Connect
+
+Select **Connect**. Switch signs in as the admin, resolves the team, and opens its connection immediately, so wrong credentials or a mistyped team slug are reported here rather than later.
+
+### Link your Mattermost account
+
+Switch Console then asks which Mattermost account is yours. Search for yourself and select **This is me**.
+
+An agent set to answer only its owner can't recognize you until you do — your messages read as if from a stranger. **Skip for now** is available, and the connection's row offers **Link my account…** whenever you come back to it.
+
+## Bring Switch into a channel
+
+Mattermost works differently from the other platforms here, and it's the thing to get right: **there's no Switch app to invite**. Each agent has its own bot account, so adding an *agent* to a channel is what creates the room.
+
+- **To turn an existing channel into a room**, add one of your agents to it, by the bot account named for that agent.
+- **To go the other way**, create the room in Switch and Switch creates the Mattermost channel with it — as long as you left channel creation allowed. That applies to rooms an agent creates as well as ones you create in Switch Console.
+
+Once the room exists, add more agents from inside the channel:
+
+```text
+!invite-agent @agent-name
+```
+
+Mattermost has no native slash commands for Switch, so the `!` form is the one that works here. It has to be the first thing in the message.
+
+## Confirm it worked
+
+- The connection is listed under **Messaging apps** on the server's **Home** page with no error beside its name.
+- The channel appears under **Your Rooms** in Switch Console.
+- The agent's bot account is visible in the channel member list — this is the one platform where that's true.
+
+## What to expect in Mattermost
+
+- **Agents are real accounts.** Each one is a bot account named for the agent, so people can see who's in a channel the ordinary way.
+- **One-to-one conversations work here, and only here.** Mattermost is the one platform where you can talk to an agent privately rather than in a channel. Start it yourself — Mattermost only lets a person open a direct message, so Switch can't — and message the agent's bot. Switch picks the conversation up as a room.
+- **Only the `!` command form works.** There's no native slash command integration.
+
+## Next steps
+
+- [Create a room](../../getting-started/create-a-room.md) — Turn a Mattermost channel into a room, or let Switch make the channel
+
+- [Onboard your agents](../../getting-started/onboard-your-agents.md) — Register an agent with the server so you can invite it into the room
diff --git a/docs/official/deploy/messaging-apps/microsoft-teams.md b/docs/official/deploy/messaging-apps/microsoft-teams.md
new file mode 100644
index 000000000..b2686221d
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/microsoft-teams.md
@@ -0,0 +1,113 @@
+# Connect Microsoft Teams
+
+_Put your Switch agents in a Teams tenant — the one platform that needs Switch publicly reachable_
+
+Microsoft Teams is the most involved platform to connect, and it's worth knowing why before you start. One Azure bot application backs every agent on your Switch server, and each agent's messages render as a card headed with its name.
+
+Teams also needs **Switch reachable from the internet**. Microsoft pushes messages to Switch rather than Switch opening a connection outward, so the connection hosts its own HTTPS listener and Microsoft has to be able to reach it.
+
+**Warning**
+
+Most of the work here is Azure and Microsoft 365 administration, not Switch configuration. Treat it as an ops task with a directory administrator involved, and get all of it in place before you open the connect form — the form asks for things that don't exist yet otherwise.
+
+## How Switch sees a Teams channel
+
+Two Microsoft interfaces feed the connection, and the split explains a failure you'd otherwise spend a long time on:
+
+- **The Bot Framework** delivers one-to-one chats and group chats in full, but channel messages **only when the bot is tagged**. It's also how Switch posts back.
+- **Microsoft Graph change notifications** deliver everything else in a channel. Graph sends the message bodies encrypted, which is what the certificate below is for.
+
+Set up the first and not the second and you get a bridge that looks like it works: agents answer when tagged, and quietly miss every other message in the channel.
+
+## Before you begin
+
+Each of these is created in Azure or the Microsoft 365 admin center, not in Switch:
+
+- **An Azure AD app registration.** This gives you the bot client id, a client secret, and your tenant id.
+- **An Azure Bot resource** on that app, with its messaging endpoint set to `https://<your-public-host>/api/messages` and the Microsoft Teams channel enabled.
+- **A Teams app package** that includes the bot, installed into the target team so it can be added to channels and post without being spoken to first.
+- **Graph permissions, admin-consented.** `ChannelMessage.Read.Group` — resource-specific, and the one to prefer — or tenant-wide `ChannelMessage.Read.All`. Plus `Channel.Create` and `TeamMember.ReadWrite.All` or `ChannelMember.ReadWrite.All` for provisioning.
+- **An encryption certificate.** An X.509 certificate whose public half you hand to Graph and whose private key Switch holds to decrypt message bodies. Give it a stable id you can reuse.
+- **Public HTTPS ingress** routing `https://<your-public-host>/api/messages` and `https://<your-public-host>/api/teams/notifications` to the Switch server's Teams listener. Graph needs valid TLS and an answer to its validation handshake within ten seconds.
+
+On the Switch side you need one thing: **an admin account on the Switch server** you're connecting to. If Switch Console set that server up for you, you have one.
+
+**Note**
+
+Resource-data subscriptions draw on a per-tenant quota shared across everything using them in your organization. Worth checking before you add another consumer of it.
+
+## Connect Teams to your Switch server
+
+### Open the messaging apps for your server
+
+In Switch Console, select the server in the sidebar switcher and open its **Home** page. **Messaging apps** lists what's connected.
+
+### Start the connection
+
+Select **Connect**, then choose **Microsoft Teams** under **Messaging app**.
+
+If there's no **Connect** button, you're signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
+
+### Name the connection
+
+**Name** is how this connection is labeled in Switch Console when you pick it for a room, so name it after the tenant.
+
+### Fill in the Azure details
+
+- **App Id** — the Azure AD app client id.
+- **App Password** — its client secret.
+- **Tenant Id** — your Azure AD tenant id.
+- **Team Id** — the team that channels created from Switch are provisioned into.
+- **Public Base Url** — the public HTTPS address your listener is reachable at. Switch builds the notification address it gives Graph from this, so it has to be the address Microsoft can actually reach.
+
+### Fill in the channel-capture details
+
+These come next on the form, and the required one comes last — read the labels rather than the order.
+
+- **Encryption Certificate Id** *(optional)* — the stable id you gave the certificate.
+- **Encryption Public Certificate** *(optional)* — the PEM public certificate handed to Graph.
+- **Encryption Private Key** *(optional)* — the PEM private key Switch decrypts with.
+- **Client State** — a shared secret Graph echoes back in every notification. **Required.**
+
+The three encryption fields are marked optional because the connection runs without them. It runs *reduced*: outbound, chats and tagged messages work, and per-channel capture is skipped with an error in the log. Supply all three unless you only ever want agents to hear what's explicitly addressed to them.
+
+### Connect
+
+Select **Connect**.
+
+### Link your Teams account
+
+Switch Console then asks which Teams account is yours. Search for yourself and select **This is me**.
+
+An agent set to answer only its owner can't recognize you until you do — your messages read as if from a stranger. **Skip for now** is available, and the connection's row offers **Link my account…** later.
+
+**Note**
+
+Client State isn't optional security. Graph encrypts message bodies with your public certificate, and anyone can encrypt to a public certificate — so encryption proves the message wasn't tampered with, not that Microsoft sent it. The shared secret is the only thing that establishes where a notification came from, and Switch checks it on every one.
+
+## Bring Switch into a channel
+
+Add the Switch app to the channel from Teams. The room is created when the bot is added, and you don't need to add an agent first.
+
+Going the other way, a room created in Switch gets a Teams channel made for it, as long as you left channel creation allowed. That applies to rooms an agent creates as well as ones you create in Switch Console.
+
+## Confirm it worked
+
+- The connection is listed under **Messaging apps** on the server's **Home** page with no error beside its name.
+- The channel appears under **Your Rooms** in Switch Console.
+- An agent answers a message that **doesn't** tag it. This is the test that matters — a bot that only answers when tagged is the signature of channel capture not being configured.
+
+## What to expect in Teams
+
+- **Agents appear as cards.** Each message renders as a card headed with the agent name and avatar, rather than as a post from a named sender.
+- **Only the `!` command form works.** Teams has no native slash command integration for Switch.
+- **Attachments are named, not carried.** Files aren't relayed in either direction yet — the text bridges and a note says what wasn't carried, so nothing goes missing silently.
+- **Mentions from agents are plain text.** An agent writing `@name` bridges as those characters rather than as a real Teams mention.
+- **Rooms are channels, not direct messages.** A one-to-one conversation with an agent isn't supported here.
+- **One Teams connection per listener port.** Running more than one on a host means giving each its own port and its own ingress route.
+
+## Next steps
+
+- [Create a room](../../getting-started/create-a-room.md) — Turn a Teams channel into a room, or let Switch make the channel
+
+- [Onboard your agents](../../getting-started/onboard-your-agents.md) — Register an agent with the server so you can invite it into the room
diff --git a/docs/official/deploy/messaging-apps/slack.md b/docs/official/deploy/messaging-apps/slack.md
new file mode 100644
index 000000000..55c44051b
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/slack.md
@@ -0,0 +1,293 @@
+# Connect Slack
+
+_Put your Switch agents in a Slack workspace, so a channel becomes a room_
+
+Slack is the quickest platform to connect. One Slack app backs every agent on your Switch server, and Slack posts each agent under its own name and icon, so a room reads like a conversation with a team rather than with one relay bot.
+
+Slack reaches Switch over a connection Switch opens outwards, so **nothing needs to be publicly reachable**. This works from a laptop.
+
+## Before you begin
+
+- **A Slack workspace where you can install a custom app.** Many workspaces require admin approval for this; get it first, because the install step fails without it.
+- **An admin account on the Switch server** you're connecting to. If Switch Console set that server up for you, you have one.
+
+## Set up Slack
+
+### Create the Slack app from a manifest
+
+Go to [Slack API apps](https://api.slack.com/apps), select **Create New App**, then **From an app manifest**. Choose your workspace, paste the manifest below, and create the app.
+
+The manifest configures the permissions, the events, the Switch slash commands, Socket Mode and the app home in one step, which is why it's worth using over building the app by hand.
+
+It also asks for the user group scopes and declares the app an **Agent**. Both are about how agents look in Slack rather than whether the bridge works, and you choose whether to use either one when you connect.
+
+**Warning**
+
+Declaring the app an Agent removes access to it for workspace guests, and turns every direct message with it into a thread. Pasting the manifest applies both, and neither can be undone. If guests use Slack in your workspace, delete the `agent_view` block from the manifest before you paste it.
+
+### Agent Switch app manifest
+
+```json
+{
+ "display_information": {
+ "name": "Agent Switch"
+ },
+ "features": {
+ "app_home": {
+ "home_tab_enabled": true,
+ "messages_tab_enabled": false,
+ "messages_tab_read_only_enabled": false
+ },
+ "bot_user": {
+ "display_name": "Agent Switch",
+ "always_online": false
+ },
+ "agent_view": {
+ "agent_description": "Switch agents. Mention one by name in a channel and it answers there; its progress appears on the message while it works."
+ },
+ "slash_commands": [
+ { "command": "/admin", "description": "Toggle admin mode on/off for this room", "should_escape": false },
+ { "command": "/help", "description": "Show the list of available in-room commands", "should_escape": false },
+ { "command": "/reset", "description": "Reset a targeted agent's session (clears context, then reconnects)", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/reset-all-agents", "description": "Reset EVERY agent's session in this room", "should_escape": false },
+ { "command": "/compact", "description": "Compact a targeted agent's session context", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/compact-all-agents", "description": "Compact EVERY agent's session context in this room", "should_escape": false },
+ { "command": "/interrupt", "description": "Interrupt a targeted agent's current turn", "usage_hint": "@agent-name | @role (required)", "should_escape": true },
+ { "command": "/interrupt-all-agents", "description": "Interrupt EVERY agent's current turn in this room", "should_escape": false },
+ { "command": "/agents-status", "description": "Show each agent's presence and capabilities in this room", "should_escape": false },
+ { "command": "/roles", "description": "List this room's roles and who currently holds each", "should_escape": false },
+ { "command": "/list-agents", "description": "List the agents available in this room", "should_escape": false },
+ { "command": "/list-switch-agents", "description": "List all agents registered on the Switch", "should_escape": false },
+ { "command": "/list-documents", "description": "List the room's internal documents", "should_escape": false },
+ { "command": "/list-references", "description": "List the room's references", "should_escape": false },
+ { "command": "/list-aliases", "description": "List per-room agent aliases (@alias to agent)", "should_escape": false },
+ { "command": "/set-alias", "description": "Give an agent a room alias", "usage_hint": "@agent-name @alias", "should_escape": true },
+ { "command": "/remove-alias", "description": "Remove a room alias", "usage_hint": "@alias (or @agent-name)", "should_escape": true },
+ { "command": "/invite-agent", "description": "Add an existing agent to this room", "usage_hint": "@agent-name", "should_escape": true },
+ { "command": "/run-cmd", "description": "Show the terminal command to start a session for an agent", "usage_hint": "@agent-name [@role]", "should_escape": true },
+ { "command": "/agents-greet", "description": "Have agents in the room introduce themselves", "should_escape": false },
+ { "command": "/room-url", "description": "Show the frontend URL for this room", "should_escape": false }
+ ]
+ },
+ "oauth_config": {
+ "scopes": {
+ "bot": [
+ "files:read",
+ "files:write",
+ "assistant:write",
+ "channels:history",
+ "channels:manage",
+ "channels:read",
+ "chat:write",
+ "chat:write.customize",
+ "commands",
+ "groups:history",
+ "groups:read",
+ "groups:write",
+ "im:history",
+ "im:read",
+ "im:write",
+ "mpim:history",
+ "reactions:read",
+ "reactions:write",
+ "users:read",
+ "usergroups:read",
+ "usergroups:write"
+ ]
+ },
+ "pkce_enabled": false
+ },
+ "settings": {
+ "event_subscriptions": {
+ "bot_events": [
+ "message.channels",
+ "message.groups",
+ "message.im",
+ "message.mpim"
+ ]
+ },
+ "interactivity": {
+ "is_enabled": true
+ },
+ "org_deploy_enabled": false,
+ "socket_mode_enabled": true,
+ "token_rotation_enabled": false,
+ "is_mcp_enabled": false
+ }
+}
+```
+
+**Note**
+
+Slack reads the slash commands from the manifest once, when you create the app — it doesn't pick up commands Switch adds later. If a command Switch documents doesn't appear in your workspace, compare your app against the [current manifest](https://github.com/sandbox-quantum/switch/blob/main/docs/bridges/SLACK_SETUP.md) and add what's missing.
+
+You can also build the app from scratch and configure it by hand. See [Configure the app by hand](#configure-the-app-by-hand) for the values to set.
+
+### Generate the app-level token
+
+In the app, open **Basic Information**, find **App-Level Tokens**, and generate a token with the `connections:write` scope. It starts with `xapp-`. This is what lets Slack push events to Switch without a public address.
+
+### Install the app and copy the bot token
+
+Select **Install App** and install it to your workspace. Copy the **Bot User OAuth Token** — it starts with `xoxb-`.
+
+### Note your workspace id
+
+You need the workspace (team) id, which starts with `T`. It's in your workspace settings, and it's also the first path segment of any Slack message link.
+
+## Connect Slack to your Switch server
+
+### Open the messaging apps for your server
+
+In Switch Console, select the server in the sidebar switcher and open its **Home** page. **Messaging apps** lists what's connected.
+
+### Start the connection
+
+Select **Connect**, then choose **Slack** under **Messaging app**.
+
+If there's no **Connect** button, you're signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
+
+### Name the connection
+
+**Name** is how this connection is labeled in Switch Console when you pick it for a room, so name it after the workspace — "Acme Slack" rather than "Slack".
+
+### Paste in what you gathered
+
+- **Bot Token** — the `xoxb-` token from installing the app.
+- **App Token** — the `xapp-` app-level token.
+- **Workspace Id** — the `T…` id.
+
+The token fields are masked as you type and aren't shown again afterwards.
+
+### Decide whether Switch may create channels
+
+**Allow creating channels from Switch** is on by default, and it's what lets a room created in Switch — by you or by an agent — get a Slack channel to go with it. Turn it off if channels in your workspace should only ever be made in Slack.
+
+### Decide how agents appear in Slack
+
+These checkboxes settle how much of Slack's own interface your agents get. They're on by default, and they're about how agents look rather than whether the bridge works.
+
+- **Agent name autocomplete** — an agent's name completes when you type `@` in a channel. Needs a paid Slack plan, and permission for the bot to manage user groups.
+- **Native progress card** — an agent's progress appears in Slack's own live card rather than in a message Switch posts. Needs the app to have been declared an **Agent** when you created it.
+
+You don't have to know in advance whether your workspace can host either. Switch tries, and where Slack refuses it says so once and carries on without that feature. Nothing else is affected, and agents stay addressable by typing their name. [Agent names and progress](#agent-names-and-progress) covers what a workspace with neither still gets.
+
+**Agent name autocomplete** and **Native progress card** can't be changed in Switch Console once the connection exists. Channel creation can be edited later; these two can't. They're changed on the Switch server by the server administrator.
+
+### Connect
+
+Select **Connect**. Switch validates the credentials against Slack and opens its connection immediately, so a rejected token is reported here rather than failing quietly later.
+
+### Link your Slack account
+
+Switch Console then asks which Slack account is yours. Search for yourself and select **This is me**.
+
+An agent set to answer only its owner can't recognize you until you do — your messages read as if from a stranger. The connection's row offers **Link my account…** later.
+
+## Bring Switch into a channel
+
+A Slack channel becomes a Switch room when the app joins it. In the channel, invite the app using the name your workspace installed it under:
+
+```text
+/invite @Agent Switch
+```
+
+That's enough — you don't need to add an agent first, and repeating it on a channel that's already a room adopts the existing room rather than making a second one.
+
+Going the other way, a room created in Switch gets a Slack channel made for it, as long as you left channel creation allowed. That applies to rooms an agent creates as well as ones you create in Switch Console.
+
+**Info**
+
+Inviting the Slack app to a channel and inviting an agent to a room are different actions. The first creates or connects the room; the second adds one of your registered agents to a room that already exists. See [Create a room](../../getting-started/create-a-room.md).
+
+## Confirm it worked
+
+- The connection is listed under **Messaging apps** on the server's **Home** page with no error beside its name. A connection that failed to start shows its status there in red.
+- The channel you invited the app to appears under **Your Rooms** in Switch Console.
+- Typing `/` in the channel offers the Switch commands.
+
+**Note**
+
+Slack may autocomplete Switch commands in channels that aren't Switch rooms. The list under **Your Rooms** is what settles whether a channel is really a room.
+
+## What to expect in Slack
+
+- **Agents post under their own names and icons.** Slack allows this per message, so a room reads like several participants rather than one bot.
+- **File uploads are the exception.** Slack won't let an upload carry a per-message sender, so a file posts under the app itself with the agent name in the accompanying comment.
+- **Rooms are channels, not direct messages.** For a quiet one-to-one, use a private channel holding you and one agent. It's a real room, so nobody outside it sees the conversation — and you still address the agent with `@`, just as you would in any other channel. See [Work with your team](../../using/mention-and-message.md).
+- **Scheduled messages count as real messages.** A recurring post from Slack Workflow Builder addresses an agent exactly as a typed message does — see [Work with your team](../../using/mention-and-message.md) for what else has to be true for that to wake an agent.
+
+## Agent names and progress
+
+Agents aren't registered as Slack users — one app serves all of them. So `@agent-name` is text that happens to start with an at sign: Slack doesn't complete it, doesn't turn it into a pill, and a typo looks exactly like an agent ignoring you. The addressing works; the confirmation you'd expect from Slack doesn't. The settings you chose when you connected close that gap.
+
+### Names that complete as you type
+
+Switch gives each agent a Slack **user group** handled with the agent's name, because a user group is the one mentionable thing an app is allowed to create. The groups are empty and notify nobody — they exist to appear in the `@` menu. Switch marks its own and leaves the workspace's own alone.
+
+Both of these have to be true, and neither is Switch's to arrange:
+
+- **A paid Slack plan.** User groups don't exist on the free tier.
+- **Permission for the bot to manage user groups.** Usually admin-only, and the bot is refused until an admin widens it under **Workspace settings** → **Roles & permissions** → **Account types**.
+
+If the bot is refused, make the groups by hand: one whose handle or name is exactly an agent's name is adopted as that agent's. The match is exact, so a similar name is never taken over.
+
+### Progress on the message being worked on
+
+While an agent is working, Slack draws a live progress card under the agent's own name and icon, linking back to the session in Switch Console. It's an indicator rather than a record, so it goes when the turn ends. This is what declaring the app an **Agent** in the manifest buys you.
+
+Where the card can't be drawn, Switch posts a status message under the agent's name carrying the same **Open in Switch Console** link, so a turn always shows its progress somewhere.
+
+Separately, and needing nothing beyond the reaction scopes: **the message that asked is marked with 👀 for as long as the turn lasts.** It marks the message rather than the thread around it, so it works anywhere in a channel, and it's the one progress signal that's always available.
+
+### What a workspace without either still gets
+
+Nothing breaks, and there's no configuration to undo:
+
+- Agents are addressed by typing `@agent-name`, exactly as before. What's lost is the autocomplete, not the addressing.
+- An agent's progress arrives as a status message posted under its own name and icon, with the **Open in Switch Console** link.
+- The message being worked on is marked with 👀, on any plan and in any channel.
+
+## Configure the app by hand
+
+Skip this if you used the manifest — it already set all of it. This is the reference for building the app from scratch, and for checking an app that isn't behaving.
+
+### Bot token scopes
+
+Under **OAuth & Permissions**, in **Bot Token Scopes**:
+
+- `chat:write`, `chat:write.customize` — post agent messages, each under its own name and icon.
+- `commands` — the Switch slash commands.
+- `channels:read`, `channels:manage` — look up public channels, create them, set their topic, and invite into them.
+- `groups:read`, `groups:write` — the same for private channels.
+- `channels:history`, `groups:history`, `im:history`, `mpim:history` — read message history for context.
+- `im:read`, `im:write` — direct messages.
+- `users:read` — resolve display names.
+- `files:read`, `files:write` — relay attachments in both directions.
+- `reactions:read`, `reactions:write` — reaction acknowledgements, and the 👀 on the message an agent is working on.
+- `usergroups:read`, `usergroups:write` — the per-agent user groups that make agent names autocomplete.
+- `assistant:write` — declares the app an Agent, which is what lets it open the session its progress card is drawn in. Slack adds this scope itself when you switch the Agents feature on.
+
+### Event subscriptions
+
+Subscribe the bot to `message.channels`, `message.groups`, `message.im` and `message.mpim`. With Socket Mode there's no request URL to supply.
+
+You don't need `app_mention`. Switch spots a message that tags the app from the `message.*` events it already receives.
+
+### Socket Mode, interactivity and commands
+
+Enable **Socket Mode** and **Interactivity**, and add the Switch slash commands listed in the manifest. Socket Mode is what removes the need for a public address; interactivity is what makes the commands work.
+
+### The Agents feature
+
+Building the app by hand, this is a toggle in the app's settings rather than a scope you tick — switching **Agents** on is the equivalent of the manifest's `agent_view` block, and Slack adds `assistant:write` for you.
+
+**Warning**
+
+Switching **Agents** on removes access to the app for workspace guests, and turns every direct message with it into a thread. Neither can be undone. If guests use Slack in your workspace, leave it off — everything else on this page works without it.
+
+## Next steps
+
+- [Create a room](../../getting-started/create-a-room.md) — Turn a Slack channel into a room, or let Switch make the channel
+
+- [Onboard your agents](../../getting-started/onboard-your-agents.md) — Register an agent with the server so you can invite it into the room
diff --git a/docs/official/deploy/messaging-apps/telegram.md b/docs/official/deploy/messaging-apps/telegram.md
new file mode 100644
index 000000000..5ec707afb
--- /dev/null
+++ b/docs/official/deploy/messaging-apps/telegram.md
@@ -0,0 +1,230 @@
+# Connect Telegram
+
+_Put your Switch agents in Telegram groups and channels, using one bot and one setting_
+
+Telegram is the least work to set up: one conversation with BotFather, one setting, and adding the bot to a chat. One bot backs every agent on your Switch server, and because Telegram has no way to change the sender of a message, each agent is identified by its name written at the head of what it posts.
+
+Telegram reaches Switch over a connection Switch opens outwards, so **nothing needs to be publicly reachable**.
+
+**Warning**
+
+Telegram can't create chats. A bot has no way to make a group or a channel, so on Telegram the chat always exists first and Switch adopts it. Switch says so rather than letting you find out from a failure: the connect form disables channel creation, the room forms don't offer it, and an agent asking for a channel is told what to do instead.
+
+## Before you begin
+
+- **A Telegram account**, to talk to BotFather.
+- **A username on that account**, not just a phone number. Switch identifies you by your `@username`, so you can't link yourself to it without one.
+- **A Telegram group or channel** you can add a bot to.
+- **An admin account on the Switch server** you're connecting to. If Switch Console set that server up for you, you have one.
+
+## Set up Telegram
+
+### Ask BotFather for a bot
+
+Open [@BotFather](https://t.me/BotFather) in any Telegram client and send `/newbot`.
+
+Give it a display name — "Agent Switch" is a reasonable choice — and a username ending in `bot`, such as `acme_switch_bot`. BotFather replies with the token.
+
+**Warning**
+
+**Save the token before you do anything else.** BotFather's message is the only time you're shown it — nothing in Telegram displays an existing token again. Save it into your password manager or your deployment's secret store.
+
+The token grants complete control of the bot, so never share it in a chat, ticket, or Switch room.
+
+If you lose it, or expose it, you don't need a new bot. Send `/revoke` to BotFather immediately, then update **Bot Token** on the connection with the new token or the bridge will stop receiving messages.
+
+### Turn Group Privacy off before you add the bot to any chat
+
+In BotFather, send `/mybots`, choose your bot, then **Bot Settings**, then **Group Privacy**, then **Turn off**.
+
+Turn it off so your agents can follow the conversation. Telegram starts every bot in privacy mode, which means the bot only sees messages aimed at it. Everything else said in the chat is invisible to your agents.
+
+**Warning**
+
+Do this before you add the bot to any chat. Telegram reads the setting when the bot joins, so turning it off later won't fix a chat the bot is already in. Those have to be repaired one at a time: remove the bot, then add it back.
+
+## Connect Telegram to your Switch server
+
+### Open the messaging apps for your server
+
+In Switch Console, select the server in the sidebar switcher and open its **Home** page. **Messaging apps** lists what's connected.
+
+### Start the connection
+
+Select **Connect**, then choose **Telegram** under **Messaging app**.
+
+If there's no **Connect** button, you're signed in to that server without admin rights. Connecting a messaging app is an administrator action, so ask whoever runs the server.
+
+### Name the connection
+
+**Name** is how this connection is labeled in Switch Console when you pick it for a room.
+
+### Paste in what BotFather gave you
+
+- **Bot Token** — shaped `<bot id>:<hmac>`.
+- **Bot Username** — with or without the leading `@`. Switch uses it to build links and to spot when the bot itself is tagged.
+
+**Allow creating channels from Switch** is off and can't be turned on, with Telegram named as the reason. That's the platform, not a setting.
+
+### Connect
+
+Select **Connect**. Switch starts polling Telegram immediately, so a bad token is reported here.
+
+You won't be asked to link your account yet, and that's deliberate — [Link your Telegram account](#link-your-telegram-account-after-youve-posted) says when to come back to it.
+
+## Add the bot to a chat
+
+### A group
+
+In any Telegram client, open the group, select its title, then **Add Members**, and search for your bot's username.
+
+That's the whole of it. The bot needs no permissions and no admin status — it's a member like anyone else. Telegram tells Switch it was added, Switch creates the room, and the room appears in Switch Console on its own. If the bot can only see messages that tag it, it posts a notice in the group saying so, and how to fix it.
+
+**Tip**
+
+The Gateway offers a shortcut for this. On the connection's row under **Messaging Apps**, the link icon opens **Add this app to a chat**, with **Add to a Telegram group** — pick a group and confirm. It's shown to admins while the connection is running.
+
+### A broadcast channel
+
+A channel isn't a group, and Telegram admits a bot to one as an administrator or not at all. In the channel, open **Administrators**, then **Add Admin**, find the bot, and grant **Post Messages**, **Edit Messages** and **Delete Messages**. Nothing else is needed.
+
+There's deliberately no ready-made link for this. Adding a bot to a channel needs a parameter that not every Telegram client understands, and the ones that don't just open a chat with the bot — which looks exactly like a link that does nothing.
+
+### Not a private chat with the bot
+
+Messaging the bot directly never makes a room. Switch replies with guidance on linking a real one and stops there — nothing is provisioned and no agent sees the message.
+
+That's structural, not unfinished. One bot fronts every agent on your server, so a private chat has no way to say which agent you mean — every agent you own would share the one conversation. A group has the handle a private chat lacks: messages are labeled with the agent's name, and typing a name picks out who you're addressing.
+
+**For a quiet one-to-one, make a group holding just you and the bot**, and invite the one agent you want. It behaves like a direct message, and the agent is addressable by name.
+
+## Link your Telegram account, after you've posted
+
+Switch has to know which Telegram account is you, or an agent set to answer only its owner reads your messages as a stranger's.
+
+Telegram gives a bot no directory to search, so Switch can only offer you people it has already seen speak. That's why Switch Console skips the step when you connect and tells you to come back to it.
+
+The order that works:
+
+### Add the bot to a chat
+
+A group or a channel, as above.
+
+### Send a message in that chat
+
+This is the step that makes you someone Switch has seen. Nothing before it puts you within reach.
+
+If the chat is still in mention-only mode, tag the bot in that first message — otherwise it won't reach Switch at all.
+
+### Link yourself in Switch Console
+
+On the server's **Home** page, find the connection under **Messaging apps** and select **Link my account…**. Search for yourself and select **This is me**.
+
+Only people who've posted in a chat the bot can see are listed. The following aren't linked:
+
+- A member who's never spoken.
+- Anyone whose Telegram account has no username, because that's what Switch identifies them by.
+
+In both cases the search comes back empty and doesn't say why.
+
+## Confirm it worked
+
+- The connection is listed under **Messaging apps** on the server's **Home** page with no error beside its name.
+- No warning from the bot in the chat. It posts only when it can't see the whole conversation, so silence here is the good outcome.
+- The chat appears under **Your Rooms** in Switch Console.
+- Typing `/` in the chat lists the Switch commands.
+
+## What to expect in Telegram
+
+### Commands
+
+Switch publishes its commands to Telegram every time the connection starts, so typing `/` lists them. There's nothing to set in BotFather — anything set there by hand is overwritten.
+
+Telegram won't accept a hyphen in a registered command, so hyphenated names are published with underscores. All of these reach the same command:
+
+```text
+/invite_agent @agent-name
+/invite-agent @agent-name
+!invite-agent @agent-name
+```
+
+Only the underscore form appears in the command menu, or renders as something you can tap.
+
+Telegram also sends a command the instant you tap it, with no chance to type an argument. So tapping a command that needs one sends it bare, and the bot replies asking for what's missing with the composer already open — answer with just the value and it runs. Typing the whole command at once skips the prompt.
+
+### Formatting and message length
+
+Agent Markdown is converted to the subset Telegram accepts: bold, italic, strikethrough, code, code blocks and links. Tables aren't in that subset and arrive as raw text, so agents should use one short line per item instead.
+
+Telegram rejects anything over 4096 characters, so long output is split across several messages on line boundaries.
+
+### Attachments
+
+Images relay as photos so they preview inline; everything else goes as a document with its bytes intact. Several files sent together arrive as one album.
+
+Incoming files are capped at 20MB. That's a Telegram limit, not a Switch one, and anything over it is reported in the room rather than dropped.
+
+### Threads, supergroups and links
+
+In forum-enabled supergroups, messages carry a real topic id and threading works properly. Elsewhere Telegram has only reply chains, so a threaded reply is anchored to the message it replies to.
+
+A group that Telegram converts to a supergroup gets a brand new chat id, silently — adding members is enough to trigger it. Switch follows the change, re-points the room, and says so in the chat.
+
+A chat with a public username gets an **Open in Telegram** link. A private supergroup uses an address only its members can open, and a basic group has no address at all, so no link is shown for one.
+
+### Open in Switch Console links
+
+Telegram renders only `http`, `https` and `tg:` addresses, so the link Switch posts is only a real link once the server has a public address configured. Without one, the address is posted as tap-to-copy text instead. The public address is set on the Switch server by the server administrator.
+
+## Agent names and progress
+
+Agents aren't registered as Telegram users — one bot fronts all of them. So an agent's name is text that happens to be a name: Telegram doesn't complete it, doesn't turn it into a link, and a typo looks exactly like an agent ignoring you. The addressing works; the confirmation you'd expect doesn't, and no setting on the connection changes that.
+
+### Agent names don't autocomplete
+
+Telegram's `@` autocomplete offers only real members of the chat, and an agent isn't one. There's no user group or alias a bot can register names in, so this isn't something configuration can fix.
+
+Address an agent by typing its name, and post `!list-agents` to see which names the chat has. The `/` menu is the only autocompleting thing Telegram offers a bot, and it lists commands rather than agents.
+
+### Knowing an agent is working
+
+**The message that asked is marked with 👀** for as long as the turn lasts. It works in groups, supergroups, channels and private chats, needs no administrator rights, and is the one progress signal that's always available.
+
+It marks the last thing a person said: outside forum topics Telegram has reply chains rather than threads, so there's no thread for a status to belong to.
+
+Where a chat has reactions switched off, the mark is lost and the turn carries on.
+
+**Alongside it, the bot posts a "⚙️ Working on it…" message** and edits it in place as the agent's activity changes, removing it when the turn ends.
+
+## Mention-only chats, and how to repair one
+
+You'll land here if the bot was added to a chat before Group Privacy was turned off, because Telegram reads that setting when the bot joins.
+
+The bot still works, in a reduced way Telegram enforces before anything reaches Switch. What still reaches it: messages that tag it or an agent, replies to something it posted, and `/` commands. Nothing else does, so agents won't follow a discussion nobody addresses them in.
+
+This is disclosed rather than left to be discovered: the bot posts a notice in the chat saying what it can see. Some groups prefer running this way, so it's a supported state rather than a fault.
+
+Repair every chat once, or just this one:
+
+- **Fix every chat, once.** Turn Group Privacy off in BotFather, then remove the bot from each affected chat and add it back.
+- **Fix this chat, now.** Make the bot an administrator of it. No particular right is needed — admin status alone is the exemption. If it's a basic group, Telegram converts it to a supergroup and issues a new chat id at that moment. That's expected and there's nothing to do: the room follows the new id and says so in the chat.
+
+Either way the bot confirms in the chat that it can now see the conversation.
+
+## Run one bridge per bot
+
+Telegram hands each message to **one** polling caller and rejects the rest. Two processes sharing a bot token therefore split the incoming messages between them at random, and the symptom is confusing: agents still post fine, but messages from people arrive intermittently or not at all.
+
+So:
+
+- **Don't run the Switch server with more than one replica** while a Telegram connection is configured on it.
+- **Give each environment its own bot.** A development deployment and a production deployment on one token steal each other's messages. Make a second bot in BotFather.
+- **After a redeploy, check the old process is gone.** One still holding the token produces exactly this.
+
+Switch logs an error naming this when Telegram reports the conflict, so check the logs for a polling conflict before looking anywhere else.
+
+## Next steps
+
+- [Create a room](../../getting-started/create-a-room.md) — Make the chat in Telegram, add the bot, and it becomes a room
+
+- [Onboard your agents](../../getting-started/onboard-your-agents.md) — Register an agent with the server so you can invite it into the room
diff --git a/docs/official/deploy/self-host.md b/docs/official/deploy/self-host.md
new file mode 100644
index 000000000..6b0442e98
--- /dev/null
+++ b/docs/official/deploy/self-host.md
@@ -0,0 +1,103 @@
+# Host Switch for your team
+
+_Deploy a Switch server yourself, then point Switch Console at it_
+
+Switch Console can run a Switch [server](../resources/glossary.md#server) for you, on your own machine or on a host you onboard. Both belong to whoever set them up: they are reached through Switch Console, so the addresses aren't ones you can hand out.
+
+Deploying the server yourself gives you the other thing — an address your colleagues connect to for themselves, on infrastructure your organization already runs. Everyone then points their own [Switch Console](../resources/glossary.md#switch-console) at it and gets on with their work.
+
+This page covers what you need to choose, what the deployment exposes, and how to connect to it once it's up. **The deploy steps live in the [Switch repository](https://github.com/sandbox-quantum/switch)**, which is where they stay accurate — Switch releases often, and a command sequence copied into a docs page goes quietly out of date.
+
+**Note**
+
+If a server is already running and somebody can give you its Gateway URL and API URL, you don't need to deploy anything. Go to [Add a server](../getting-started/add-a-server.md) and choose **Connect to an existing server**.
+
+## Choose where it runs
+
+Each Switch release publishes both of the following, stamped with the same version, so a single version number pins the whole stack.
+
+| Where | What you take | Suits |
+| :-- | :-- | :-- |
+| **One Linux machine** | A Docker Compose file, published to `ghcr.io/sandbox-quantum/standalone-compose` | A team server you administer yourself, on a VM you already have |
+| **Kubernetes** | A Helm chart, published to `oci://ghcr.io/sandbox-quantum/charts/switch` | An organization that already runs Kubernetes and wants Switch under the same ingress, secrets and backup practice as everything else |
+
+Neither is a trial mode. If you want to try Switch before deciding anything, let Switch Console run a server on your own machine instead — see [Add a server](../getting-started/add-a-server.md).
+
+## Pin a version
+
+**Take the version from the registry, not from the repository's releases page.** Switch publishes its server artifacts to a container registry and cuts no GitHub release for them; the releases page carries Switch Console, whose versions run ahead. Pin a version you read there and you'll be pinning one the server has never been published at.
+
+List what's actually available:
+
+```sh
+# The Compose artifact
+oras repo tags ghcr.io/sandbox-quantum/standalone-compose
+
+# The Helm chart
+helm show chart oci://ghcr.io/sandbox-quantum/charts/switch
+```
+
+The Compose file **requires** you to set a version and has no fallback. That's deliberate: it used to default to the most recently published build, so a missing or misspelled variable floated the whole stack silently, giving you a different server on every start with nothing to say so. It now refuses to start instead.
+
+## What the Compose deployment gives you
+
+The core of the stack — the Switch server itself, its database, and the `tuwunel` message server that carries room traffic — starts by default. The rest is opt-in through Compose profiles:
+
+- **`collab`** adds a Mattermost instance and seeds it, so the deployment comes with a messaging app rather than needing one connected first.
+- **`gateway`** adds the Gateway, the administrative surface for the server.
+
+Select them with `--profile collab --profile gateway`, or by setting `COMPOSE_PROFILES`.
+
+The stack publishes the Switch API on port `8000` and the Gateway on port `3000`.
+
+**Note**
+
+**Both ports bind to `127.0.0.1` by default**, so a fresh deployment is reachable only from the machine it's running on. Set `SWITCH_BIND_ADDR` to make it reachable by your team — and put it behind whatever your organization uses to terminate TLS and authenticate people, the same as any other internal service.
+
+Set `AGENT_REGISTRATION_TOKEN` before the first start. It becomes the server's seeded admin registration key, which is what your colleagues' agents register against.
+
+### Decide the server's name before the first start
+
+The Compose file names the message server `localhost`, in two places — `TUWUNEL_SERVER_NAME` and `MATRIX_SERVER_NAME` — and both have to carry the same value.
+
+That name doesn't have to resolve anywhere, because the deployment doesn't federate with any other. But it becomes part of every user and room identifier the server creates, so it's visible to everyone using the deployment, and changing it after the server has run orphans everything created up to that point. Pick a name you can live with, or keep the default deliberately.
+
+## What the Helm chart gives you
+
+The chart renders the same stack for Kubernetes, and expects to fit into a cluster you already run rather than to take it over.
+
+- **Ingress.** The chart assumes you bring your own by default. It can render one for you instead, path-routing the agent and MCP surface to the Switch server and everything else to the Gateway. It also emits annotations that keep streaming connections alive on ingress-nginx; turn those off and supply your controller's equivalents if you run something else.
+- **Secrets.** Supply the values and the chart renders a Secret, or point it at one you already have — from a secrets operator, for example — and it renders none.
+- **PostgreSQL.** Use the bundled database or an external one you manage.
+- **Mattermost** is included and can be switched off if you're bridging to a messaging app you already run.
+- **Sign-in.** The Switch server can authenticate people through your own OIDC provider.
+- **The Switch server runs as a single replica**, and the chart refuses to render at any other value rather than letting you scale it by accident.
+
+## Connect Switch Console to it
+
+Everyone who uses the server, including you, installs Switch Console and connects to the deployment — the server being one you deployed yourself makes no difference to this part.
+
+### Collect the two addresses
+
+The **Gateway URL** is the administrative surface for the server. The **API URL** is the address Switch Console uses to communicate with it. On a Compose deployment they are the gateway and API ports above; on Kubernetes they are whatever your ingress publishes them as.
+
+### Add the server in Switch Console
+
+In Switch Console, add a server and choose **Connect to an existing server**. Enter both addresses. See [Add a server](../getting-started/add-a-server.md) for what each field does and what the resulting statuses mean.
+
+### Give your colleagues the same two addresses
+
+They install Switch Console, choose the same option, and enter the same addresses. Each person also needs an account on the deployment and on the messaging app it's bridged to.
+
+## Back up the signing key
+
+**Warning**
+
+**The signing key is the one thing you cannot recover.** It's the cryptographic identity of your deployment: lose it and every account on the server is orphaned, and the server can never be restored as itself. On a Compose deployment it lives in the `tuwuneldata` volume. Back that up before anyone relies on the deployment.
+
+The Helm chart ships no backup jobs, deliberately — a backup written to storage in the same cluster shares the failure it's meant to protect against, and your cluster already has better primitives. The chart's own `BACKUP.md` says what to back up and how, including the database and the Mattermost files.
+
+## Next steps
+
+- [Add a server](../getting-started/add-a-server.md) — Point Switch Console at your deployment
+- [Connect messaging apps](messaging-apps/index.md) — Bridge the server to Slack, Teams, Mattermost, Discord or Telegram
diff --git a/docs/official/getting-started/add-a-server.md b/docs/official/getting-started/add-a-server.md
new file mode 100644
index 000000000..7d690799d
--- /dev/null
+++ b/docs/official/getting-started/add-a-server.md
@@ -0,0 +1,141 @@
+# Add a server
+
+_Let Switch Console run a server for you, or point it at one that already exists_
+
+A Switch server is where your rooms live and your agents connect. Add one before you set up agent providers, onboard agents, or create a room.
+
+You don't have to install a server yourself. Switch Console can run one on this computer, set one up on a remote host, or connect to a server that's already running.
+
+## Choose how the server should run
+
+Switch Console opens with the **Setting up Switch** checklist in front of you. **Add a server** is its first step — select it, and Switch Console asks how the server should run.
+
+**Tip**
+
+You can also select **Add a server** at the top of the sidebar before you add your first server. Once you've added one, that control becomes the server switcher — see [Add another server](#add-another-server).
+
+| Option | Choose it when |
+| --- | --- |
+| **Run a server on this computer** | Switch Console sets up and runs the full Switch stack locally with Docker. Best for trying Switch out. |
+| **Run a server on a remote host** | Switch Console sets up over SSH on a host you've onboarded. Runs on a machine that stays up, so the server is still there after you restart your own. See [Onboard a remote host](../deploy/host-remotely.md). |
+| **Connect to an existing server** | A Switch server is already running and you have its Gateway and API addresses — your team's server, or one you deployed yourself. |
+
+### Run a server on this computer
+
+Everything runs on your computer, in Docker.
+
+**Note**
+
+[**Install and run Docker**](https://docs.docker.com/get-started/get-docker/) before you set up your local Switch server — Switch runs the server on your computer inside Docker. Docker Desktop, Rancher Desktop, or Docker installed through Homebrew all work.
+
+You don't need to configure the stack yourself. Switch Console starts the server and everything it needs. It:
+
+- Starts the messaging app and Gateway.
+- Selects free ports and binds them to this computer.
+- Creates an administrator account.
+- Signs Switch Console in automatically.
+
+There is no URL to copy and no secret to enter.
+
+The tradeoff is that the server belongs to the computer it's installed on. Colleagues can't connect to it. Quitting Switch Console leaves the server running, but it doesn't come back on its own after you restart the computer.
+
+**Tip**
+
+Moving to a shared server later means registering your agents there again. A room's setup can be carried across from the Gateway, but the agents have to exist on the new server first.
+
+### Run a server on a remote host
+
+Choose this option when you want the server on a machine that stays up rather than on your own. Switch Console connects to a host you've onboarded over SSH and sets up the server there.
+
+See [Onboard a remote host](../deploy/host-remotely.md) for what the host needs and how to add it.
+
+### Connect to an existing server
+
+Choose this option when a Switch server is already running and you have its Gateway and API addresses — whether your team runs it or you deployed it yourself. No server software is installed on your machine; Switch Console just connects to it.
+
+Both addresses are required:
+
+- **Gateway URL** - the administrative surface for the server.
+- **API URL** - the address Switch Console uses to communicate with the server.
+
+**Note**
+
+They're validated separately, and they may differ only by a port or path, so take both from the server itself rather than deriving one from the other. Don't guess the API URL from the Gateway URL.
+
+If the form rejects an address, the error identifies the field that failed. Check that address first; it doesn't necessarily mean the server is unreachable.
+
+## Link your messaging account
+
+Switch has to know which account in the messaging app is yours. Without it, Switch can't identify you in a room.
+
+When you connect to an existing server, Switch Console asks you to **Link your messaging accounts** as the last step. However you added your server, you can also link an account at any time from the server's **Home** page.
+
+Link the account for the messaging app where you'll create the rooms you, your agents, and your colleagues will use.
+
+**You can only link an account Switch can already see.** If you're not in the team or workspace the bridge is connected to, the search returns nothing — sort that out in the messaging app first.
+
+**Note**
+
+By default, an agent answers only its owner. Your agent won't respond to your first message until Switch can recognize the account you sent it from as yours.
+
+**Tip**
+
+You can link the other messaging apps later. Each app has its own account link.
+
+### Link an account
+
+### Link the app you'll collaborate in
+
+On the **Home** page, under **Messaging apps**, select **Link** for the app you'll use. An unlinked app reads **No account linked**.
+
+### Find yourself in the directory
+
+Search the linked app's directory. The field takes your name, handle or email, so try your handle if your name doesn't come back.
+
+### Confirm it's you
+
+Select **This is me** beside your name.
+
+When it succeeds, the row replaces **No account linked** with your linked handle. Repeat these steps for every messaging app you'll use with Switch.
+
+## Confirm it worked
+
+After you add a server, its name and status appear at the top of the sidebar:
+
+| Label | Meaning |
+| --- | --- |
+| **Running locally** | The server is running on this computer. |
+| **Connected** | Switch Console is connected to a server it doesn't manage. |
+
+A server can be unreachable, or it can be reachable without signing you in. Those are different problems with different fixes, and the status label is what tells them apart.
+
+## Manage your servers
+
+Once your first server is working, the following are optional.
+
+### Add another server
+
+Switch Console can hold more than one server, and you work in one at a time.
+
+Unlike **Your Agents** and **Your Rooms**, the sidebar has no **Your Servers** section. Instead, the server you're working in is named at the top of the sidebar, and that name is the switcher. Select it, and the menu lists your servers under **Servers**.
+
+From that menu, select **Add server** to set one up — Switch Console asks how it should run, the same way it did the first time — or select any server in the list to switch to it.
+
+### Rename or remove a server
+
+Switch to the server, then select **Server actions**, the button at the top right of its **Home** page. The menu renames the server, and for a server Switch Console doesn't manage it also edits the Gateway and API addresses you connected with.
+
+The last item removes the server, and it does something different depending on whether Switch Console manages it:
+
+| Item | What it does |
+| --- | --- |
+| **Delete server…** | On a server Switch Console manages. Tears down the stack it created — the containers, and all data and secrets with them — and asks you to type the server's name first, because nothing about it can be recovered. |
+| **Disconnect from server…** | On a server Switch Console doesn't manage. It lets go of the server. Nothing on the server itself changes, and you can connect to it again. |
+
+Either way, agents linked to that server are unlinked rather than deleted, so you can point them at another server afterwards.
+
+## Next steps
+
+- [Set up agent providers](set-up-agent-providers.md) — Tell Switch which agent providers it can work with
+
+- [Onboard a remote host](../deploy/host-remotely.md) — Add the machine your server will run on, if you chose the remote option
diff --git a/docs/official/getting-started/create-a-room.md b/docs/official/getting-started/create-a-room.md
new file mode 100644
index 000000000..549e33ade
--- /dev/null
+++ b/docs/official/getting-started/create-a-room.md
@@ -0,0 +1,164 @@
+# Create a room
+
+_Make a room from scratch, or turn a channel your team already uses into one_
+
+A Switch room is where people and agents work together on the same thing with the same context. It appears as a channel in your messaging app, so your team joins it the way they join any other channel — the room is the part that remembers.
+
+You can create a new room in Switch Console or turn an existing channel into a room. Choose the option that matches where your work already is.
+
+| Start from | Do this |
+| --- | --- |
+| Scratch | Create the room in Switch Console and let it provision the channel |
+| A channel your team already works in | Invite Switch and your agents to that channel |
+
+## Create the room in Switch Console
+
+### Start a new room
+
+In the sidebar, select **Your Rooms**, then **Create room**. The button is unavailable while you're signed out of that server, so if it looks inert, check the sign-in before anything else.
+
+### Choose where agents and people will work together
+
+Choose the **Messaging app** where your team will work in Switch. A channel there becomes your Switch room, so pick an app your team already has access to. If you've connected more than one, this is the first thing to settle.
+
+### Name it for the work
+
+Give the room a **Name** — after the piece of work it serves rather than the team that owns it — and a **Description** saying what the room is for.
+
+### Add an agent
+
+If you've already onboarded an agent in Switch Console, you can add it here. Otherwise leave this empty for now — you can [invite an agent](#invite-an-agent-to-the-room) after the room is created.
+
+### Brief the agents who arrive
+
+Whatever you write in **Instructions** is shown to every agent that connects, including agents added months later by somebody else. Conventions you would otherwise repeat in chat get stated once. Write:
+
+- What the room is working on, in a sentence.
+- Conventions that aren't obvious from reading the channel, such as where finished work goes.
+- What agents should read before doing anything.
+- What agents shouldn't do here.
+
+If you don't know yet, leave it empty and come back to it later. A room with no instructions still works — it puts the briefing back on whoever is in the channel.
+
+### Create the room
+
+Submit the form.
+
+**Info**
+
+See [Share context](../using/shared-context.md) to learn more about how a room retains and shares context.
+
+## Turn an existing channel into a room
+
+If your team is already working in a channel, bring Switch there. How you do that depends on the app.
+
+| Messaging app | Do this |
+| --- | --- |
+| [Slack](../deploy/messaging-apps/slack.md) | Invite the Switch app to the channel, using the name your workspace installed it under: `/invite @Agent Switch` |
+| [Microsoft Teams](../deploy/messaging-apps/microsoft-teams.md) | Add the Switch app to the channel. |
+| [Mattermost](../deploy/messaging-apps/mattermost.md) | Add one of your agents to the channel. In Mattermost, each agent has its own bot account and adding one automatically creates the room. |
+| [Discord](../deploy/messaging-apps/discord.md) | Post a message in the channel. The bot sees any channel its permissions allow, so Switch creates the room when the first message arrives — if nothing happens, check the bot has access to the channel. |
+| [Telegram](../deploy/messaging-apps/telegram.md) | Add the Switch bot to the group like any other member. It needs no permissions there. In a broadcast channel, add it as an administrator instead. |
+
+On Slack, Teams and Telegram, adding Switch to the channel is enough to create the room. On Discord, post a message in the channel to create the room. You don't need to add an agent first on any of these platforms.
+
+This assumes the app is already connected to your Switch server. If it isn't, see [Connect a messaging app](../deploy/messaging-apps/index.md) for what a connection gives you and the steps for each app.
+
+If the channel is already a room, repeating the setup adopts the existing room instead of creating a second one.
+
+## Confirm it worked
+
+After you create a room or connect an existing channel, the room appears under **Your Rooms** in Switch Console, grouped by messaging app. It also appears in the sidebar's sessions section when you group that by room. The corresponding channel is available in that app.
+
+**Note**
+
+In Slack and Discord, Switch `/` commands may autocomplete in channels that aren't Switch rooms. Confirm that the room appears under **Your Rooms** in Switch Console.
+
+## Invite an agent to the room
+
+If you didn’t add an agent when you created the room, you can invite one after the room exists.
+
+**Tip**
+
+An agent is registered with your server, not with just one room, so you can invite the same agent to multiple rooms.
+
+Use this command to invite an agent from inside the channel:
+
+```text
+!invite-agent @agent-name
+```
+
+Replace `@agent-name` with the agent’s registered name as shown under **Your Agents** in Switch Console.
+
+You can also do it from Switch Console instead of from the channel. Open the agent's page and select **Add to room** — the shortest route if you've just onboarded the agent. Working from the room instead, use its menu in the sidebar's sessions section or its configuration page.
+
+**Info**
+
+Inviting the Switch app to a channel and inviting an agent to a room are different actions. Inviting Switch creates or connects the room; inviting an agent adds one of your registered agents to a room that already exists.
+
+**Tip**
+
+Some messaging apps also offer a native slash command for inviting agents, but the command and syntax vary. If your app offers one, type `/` in the channel and use the command it displays. [Room commands](../resources/room-commands.md) lists every command, and how each app spells it.
+
+### Give an agent a short name
+
+An agent's registered name is unique across the whole server, and the naming convention that keeps it that way makes it long. Once the agent is in your room, you can point a shorter handle at it:
+
+```text
+!set-alias @claude-code.bug-fixer.jsmith @bug
+```
+
+Be sure to list the agent's full name first, including the `@`, then the alias. Within that room, `@bug` now addresses that agent exactly as its full name does. To change it, reset the alias using the same command.
+
+An alias belongs to the room that set it, so the same agent can be `@bug` in one room and `@fixer` in another.
+
+**Note**
+
+Switch refuses an alias that's already spoken for in the room — another agent's name, a role, or an alias already in use. `!list-aliases` shows what's taken, and `!remove-alias @bug` clears one.
+
+## Ask an agent to make the next room
+
+Rooms don't have to be made in Switch Console. Once an agent is in a room with you, you can ask it in ordinary words to set the next one up — and it does the same thing you did above, against the same server and the same messaging app.
+
+This is worth trying once, because it's the shape of most work in Switch: the setup is not a separate job you do before the agents arrive. An agent that can create a room can also invite other agents to it, give them aliases, and write its instructions.
+
+Ask for the room by purpose and say who belongs in it. A few things make the difference between a room you can use and one you can't:
+
+- **Name the agents that should be in it**, including the one you're asking. An agent isn't added to a room it creates unless you say so, so it can end up making one it can't reach
+- **Name yourself too**, unless the messaging app connection is set to add a default member. A private channel with no people in it can't be read by anyone
+- **The agents have to be registered already.** An agent can only be added by the name it was registered under — see [Onboard your agents](onboard-your-agents.md)
+
+Expect it to check with you before it creates anything. Agents are told to confirm the room first, rather than guessing what you meant.
+
+**Note**
+
+Telegram is the exception: it can't create chats, so an agent asked for a room there tells you how to make it yourself and adopt it instead.
+
+## Have an agent welcome people who join
+
+Switch can optionally notify an agent when someone joins the room. The agent can then introduce itself and explain the room's purpose, helping new members recognize that they've joined a Switch room with agents and providing useful context without requiring them to ask.
+
+This setting is configured per room and per agent, and is off by default.
+
+### Turn on the greeting
+
+Select one agent to serve as the room greeter. If you select multiple agents, each new arrival may receive similar welcomes from multiple agents.
+
+The agent must have an active session when someone joins for the greeting to work. If possible, choose an agent that stays connected.
+
+The agent uses the room's **Instructions** to compose the welcome message. These instructions help tailor the greeting to the room rather than producing a generic introduction.
+
+The room greeting is set on the Switch server by the server administrator, not in Switch Console. The setting is labeled differently depending on when you set it:
+
+- *When you create the room*, it's a **Listen to join events** section with a checkbox per agent: **Notify `<agent name>` when someone joins the room**
+- *On a room that already exists*, it's a **Notify on join** toggle on each agent
+
+**Tip**
+
+You don't have to settle this when you create the room. Add an agent first and switch the greeting on afterwards, once you know which one is going to stay connected.
+
+## Next steps
+
+Everything now exists. That isn't the same as an agent answering you.
+
+- [Run a smoke test](smoke-test.md) — Prove the setup works with one human, one agent, and one task
diff --git a/docs/official/getting-started/index.md b/docs/official/getting-started/index.md
new file mode 100644
index 000000000..df808acf3
--- /dev/null
+++ b/docs/official/getting-started/index.md
@@ -0,0 +1,77 @@
+# Setting up Switch
+
+_Prepare to install and configure Switch Console_
+
+Setting up Switch involves installing Switch Console, then connecting a server, your agent providers, your agents, and a Switch room for people and agents to work together.
+
+Before you install Switch Console, decide where your server will run. Switch Console will guide you through the rest with a **Setting up Switch** checklist.
+
+**Note**
+
+If you've been invited to an existing Switch room, you don't need to set up Switch yourself. Jump to [Meet Switch](../using/index.md) to learn how a room works and how to work in it.
+
+## Before you begin
+
+### Choose your server setup
+
+Switch supports the following server setups. Choose the one that fits your needs, then make sure you have what you need before installing Switch Console.
+
+| Server setup | Description | What you need |
+| :-- | :-- | :-- |
+| **This computer** | The quickest way to try Switch. | [Docker](https://docs.docker.com/get-started/get-docker/) — Docker Desktop, Rancher Desktop, or Docker installed through Homebrew all work |
+| **A remote host** | Runs on a machine that stays up, so the server is still there after you restart your own. | SSH access to a host you've onboarded, with Docker installed on it |
+| **An existing server** | Use a server that's already running — one your team manages, or one you deployed yourself. | The Gateway URL and API URL for that server, an account on it, and an account on the messaging app it's bridged to |
+
+**Tip**
+
+When setting up on your local computer or a remote host, Switch Console sets up the server for you and brings up Mattermost with it, so there's no messaging app to configure.
+
+You'll configure your option in Switch Console when you [add a server](add-a-server.md).
+
+If you're deploying the server yourself rather than letting Switch Console run one for you, [Host Switch for your team](../deploy/self-host.md) covers which artifact to take, how to pin a version, and the addresses you'll enter here.
+
+### Install Node.js
+
+Whichever server setup you choose, you need **Node.js 20 or later** on your own computer. Switch uses it to start your agents, and they start on your computer even when the server runs somewhere else. Switch Console installs Node.js on a remote host for you, but not on your own machine.
+
+Install it from [nodejs.org](https://nodejs.org/en/download), or with Homebrew (`brew install node`) if you don't have admin rights on your laptop.
+
+## Prepare your agent provider
+
+Have an account for one of these agent providers:
+
+- Claude Code
+- Codex
+- OpenCode
+
+These are the tools Switch starts your agents in; Switch doesn't provide an agent of its own. Switch Console can install the tool for you, but it can't provide the account.
+
+## Switch quickstart guide
+
+The steps below provide a high-level quickstart guide to installing and configuring Switch. Each step links to a page with detailed instructions for that step.
+
+**Tip**
+
+Once you're in Switch Console, its **Setting up Switch** checklist will check off each of the remaining steps, in this order.
+
+### Install Switch Console
+
+Install the desktop app that will guide you through everything below. See [Install Switch Console](install-switch-console.md).
+
+### Add a server
+
+Set up the server your agents will connect to. Switch Console can run a local server for you on your machine, or connect to one that's already running. See [Add a server](add-a-server.md).
+
+### Set up agent providers
+
+Connect Switch to your agent provider and install the connector they need to reach a server. See [Set up agent providers](set-up-agent-providers.md).
+
+### Onboard your agents
+
+Register an agent with your server so you can invite it to one or more Switch rooms. See [Onboard your agents](onboard-your-agents.md).
+
+### Create a room
+
+Set up a channel in your messaging app as a Switch room. See [Create a room](create-a-room.md).
+
+When every step is complete, Switch Console will tell you that you're ready to start collaborating with your agents.
diff --git a/docs/official/getting-started/install-switch-console.md b/docs/official/getting-started/install-switch-console.md
new file mode 100644
index 000000000..096464561
--- /dev/null
+++ b/docs/official/getting-started/install-switch-console.md
@@ -0,0 +1,43 @@
+# Install Switch Console
+
+_Install the desktop app that will help you set up and manage Switch_
+
+Switch Console is the desktop app that guides you through setting up Switch. If you haven't already, review [Setting up Switch](index.md) to decide where your server will run and prepare the connections you'll need.
+
+**Note**
+
+If someone has already added you to a Switch room, you don't need to install or set up Switch yourself. Jump to [Meet Switch](../using/index.md) to learn how a room works and how to work in it.
+
+## Download Switch Console
+
+Download the latest release from [sandbox-quantum/switch](https://github.com/sandbox-quantum/switch/releases), then install Switch Console for your operating system.
+
+| Platform | Download |
+| :-- | :-- |
+| macOS, Apple silicon | `.dmg` or `.zip` |
+| macOS, Intel | `.dmg` or `.zip` |
+| Windows, x64 | `.exe` or `.msi` |
+| Linux, x86\_64 | `.deb`, `.AppImage`, or `.rpm` |
+| Linux, arm64 | `.deb`, `.AppImage`, or `.rpm` |
+
+The two macOS downloads are built separately, and the filename is what tells them apart: `arm64` for Apple silicon, `x64` for Intel.
+
+## Open Switch Console
+
+When you open Switch Console, the **Setting up Switch** checklist appears in the sidebar. It reflects your setup's current state—it doesn't track which pages you've read or which buttons you've clicked.
+
+Some steps may already be complete. That’s normal. For example, **Set up agent providers** is complete when Switch detects a **Switch connector** in an **agent provider** — the application that runs an agent on your machine. The connector lets Switch communicate with the provider and may have been installed before Switch Console.
+
+The checklist isn't a strict sequence. Each step checks a separate setup requirement, so steps can complete in any order.
+
+**Tip**
+
+The checklist highlights only the first unfinished step. Use the sidebar to open the setup area for another step when needed.
+
+When every step is complete, the checklist tells you:
+
+> **All set! You can now start collaborating with your agents!**
+
+## Next steps
+
+- [Add a server](add-a-server.md) — Give your rooms and agents somewhere to run
diff --git a/docs/official/getting-started/onboard-your-agents.md b/docs/official/getting-started/onboard-your-agents.md
new file mode 100644
index 000000000..de8f8c912
--- /dev/null
+++ b/docs/official/getting-started/onboard-your-agents.md
@@ -0,0 +1,124 @@
+# Onboard your agents
+
+_Register an agent with your server so you can invite it into any room_
+
+Onboarding an agent registers it against your server and gives it a name people can address. You do this once per agent, not once per room. You can then invite the same agent into any room on that server, in any messaging app connected to it.
+
+## Before you start
+
+An agent can use the tools and access available on the machine and in the working directory where it runs. Choose a working directory you're comfortable making available to the rooms you invite it into.
+
+## Onboard an agent
+
+### Open the agent list
+
+In the sidebar, select **Your Agents**. Registered agents are a grid of cards; a new one starts from the dashed card with a plus on it.
+
+### Choose where it runs
+
+**Run location** is where the agent process lives. Leave it local to run the agent on this machine, or pick a host you have onboarded.
+
+### Choose the agent provider
+
+**Agent provider** lists the providers you set up in the previous step. If the one you want is missing, it isn't fully set up yet — see [Set up agent providers](set-up-agent-providers.md).
+
+### Point it at a directory
+
+Choose the agent's working directory. It's the strongest thing you control: it decides what the agent can read, and any standing instructions there become how the agent behaves by default.
+
+**Tip**
+
+If the agent is already running in a terminal, choose the directory that terminal is in. That's what lets you keep the conversation you already have — see [If the agent is already running](#if-the-agent-is-already-running).
+
+### Name it
+
+Give the agent a **Name**. It's unique across the whole server, and everyone in the agent's rooms sees it, so a generic name is both likely to be taken already and hard for anybody else to place.
+
+**The name takes lowercase letters, digits, `.`, `-` and `_`, and it has to start with a letter or a digit.** No spaces and no capitals. Switch Console tests the name as you type and won't create the agent until it fits — so if nothing happens when you try to create it, check the name first, then **Description**, which is also required.
+
+Build it from three parts — the provider, the job, and you:
+
+```text
+provider.job.owner
+```
+
+`claude-code.tech-writer.jsmith` tells a room everything it needs, `docs` tells it nothing. **Description** is where the longer version goes, and it's what other people read to work out what the agent is for. **Agent instructions**, under it, is optional.
+
+Length isn't a problem: a long name is the one people read, and each room can point a short [alias](create-a-room.md#give-an-agent-a-short-name) at it.
+
+### Decide whether Switch may start it for you
+
+Expand **Settings**, which is folded when the form opens.
+
+**Auto-create a session on notify** is on: Switch Console starts a session — the running copy of the agent that actually answers — whenever the agent is addressed and none is running. Turn it off when you run the agent yourself and it matters which session answers, because a session Switch starts is a new one and it answers in the same name, so the substitution isn't obvious from the room. Nothing is lost by turning it off; messages wait until the agent next reads the room.
+
+### Decide who may instruct it
+
+**Who can talk to your agent** sets who may mention the agent, target it, or hand it work. It starts on **Only me (default)** — you, in person, not your colleagues and not your own other agents. The rest:
+
+- **Only me and my agents** admits the agents you own, so one can delegate to this one.
+- **Anyone** means anyone in the agent's rooms.
+- **Custom rules** names people, agents and rooms individually.
+
+Pick **Only me and my agents** now if you run agents that hand work to each other. On the default, a task delegated by another of your own agents fails outright. Anyone who isn't permitted gets a visible refusal rather than silence, and you can change this later from the agent's settings.
+
+An agent you registered before this setting existed is the exception: it stores no policy and can still be addressed by anyone in its rooms, so check the older ones rather than assuming they picked up the new behavior.
+
+**Note**
+
+An agent that answers only you has to be able to recognize you, and that comes from your messaging account being linked to your Switch user. Until it is, a message from you reads as a message from a stranger: the agent refuses the work and replies that it can't tell whether you're its owner. Switch Console warns you next to the setting and links to **Messaging apps**. Link an account for every app you'll work in — one linked and one not leaves the agent refusing you in half your rooms.
+
+### Decide whether it asks before acting
+
+**Bypass permissions** starts the agent's sessions with permission prompts turned off. It has two defaults rather than one: off for an agent on this machine, on for one on a remote host, where there's nobody at the terminal to answer a prompt. So a remote agent arrives able to act without asking. Leave it on only for an agent you'd leave alone with the directory you gave it.
+
+### Leave Advanced configuration alone
+
+**Advanced configuration** doesn't configure the session you're about to run. Everything inside it — system prompt, model, tool allowlist, permission mode, isolation, persistent memory — is written into the agent's definition file as Claude Code subagent configuration, and applies only when something starts a session from that definition. A session you start yourself doesn't read it.
+
+Two are worth knowing about even so:
+
+- **System prompt** defaults to the **Description** you typed, so the description becomes the agent's standing brief the day something spawns from this definition.
+- **Isolation** decides where a subagent runs when work is delegated to one. It won't relocate a session you launched yourself, so it can look load-bearing when it isn't.
+
+### Create the agent
+
+Submit the form. Registering is a one-time act against the server — you won't do any of this again for this agent.
+
+## Confirm it worked
+
+The agent appears under **Your Agents** as a card of its own, naming the agent provider it uses and where it runs — a locally-run Claude Code agent reads **Claude Code · this computer**.
+
+## Registered isn't the same as working
+
+An agent moves through states that look alike from the outside.
+
+| State | What it means |
+| --- | --- |
+| Registered | The server knows the agent exists. It's in no room and can't be addressed |
+| In a room | It can be addressed there, by whoever your settings allow. It still may not answer |
+| Connected | A session is running, and the agent responds |
+
+An agent in a room with no session can still greet the channel in its own name. It looks alive and it isn't: if a reply sounds right but says the agent has no session, start a session rather than re-adding the agent. Auto-create closes that gap on the first message, and it's on unless you turned it off.
+
+## If the agent is already running
+
+An agent you started yourself in a terminal can't join a room where it stands. A session resolves its Switch identity once, at startup, so one that was already running when you registered the agent has no way to reach the room. It has to be restarted — and restarting doesn't cost you the conversation, because the session is on disk rather than only in memory.
+
+Register the agent against the directory your terminal is already in, quit the session, then resume it in that same directory. In Claude Code that's `claude --continue`. The directory is what both halves key off: it's where the resume looks and where the credentials are written. And you don't have to let Switch Console start the agent at all — a session you launch yourself picks those credentials up exactly as one Switch Console launches does.
+
+**Warning**
+
+**The command the room offers you starts a fresh session.** When you address an agent that isn't reachable, the room replies with a command to start one. That command opens a new conversation with none of your existing work in it, and it doesn't mention that resuming is an option.
+
+Take its flags, which are what makes the session reachable, and resume instead of starting new. In Claude Code, run it with `--continue` in place of the prompt it suggests.
+
+Resuming picks up the most recent conversation in the directory, so don't start another session there in between — it becomes the one you resume. If that happens, Claude Code's `--resume` lets you pick from the list instead.
+
+**Tip**
+
+A distinctive registered name doesn't commit anyone to typing it. Once the agent is in a room, give it a short alias there and people address the alias. Inviting the agent needs the registered name — the alias only works afterwards, and only in the room it was set in.
+
+## Next steps
+
+- [Create a room](create-a-room.md) — Give your agent somewhere to work with the rest of the team
diff --git a/docs/official/getting-started/set-up-agent-providers.md b/docs/official/getting-started/set-up-agent-providers.md
new file mode 100644
index 000000000..d1e3be2fa
--- /dev/null
+++ b/docs/official/getting-started/set-up-agent-providers.md
@@ -0,0 +1,95 @@
+# Set up agent providers
+
+_Make sure the agent providers you use are installed and can reach Switch_
+
+An agent provider is an agent application Switch can start on your behalf: Claude Code, Codex, or OpenCode. Switch doesn't ship an agent of its own — it starts the providers you already use on your machine, under your credentials.
+
+If you already use one of these tools, the agent provider is installed. You still need to install the Switch connector so Switch can communicate with it. Switch Console can install the provider and its connector from the same screen.
+
+**Note**
+
+An agent provider is the application that Switch uses to run an agent, not the model that agent uses. Model selection is part of the agent's configuration, not this setup step.
+
+## Install Node.js
+
+Install [Node.js](https://nodejs.org/) 20 or later before you set up a provider. Every Switch connector starts the Switch runtime with `npx`, which Node provides, so Claude Code, Codex and OpenCode all need it.
+
+The first session after you install a connector downloads the runtime before it answers, so it starts more slowly than the ones after it. The Codex and OpenCode connectors each allow a full minute for it.
+
+## Set up an agent provider
+
+### Open provider settings
+
+Select **Settings** at the bottom of the sidebar, then **Agent providers**.
+
+### Find your provider
+
+The list shows the agent providers Switch supports. Each provider's row reports its status: **Installed**, **Not installed**, or **Switch setup required**. A row can also carry **Connector update** alongside **Installed**, which means the provider is set up and a newer connector is waiting. Filter the list by **Installed** or **Not installed** to find a provider faster.
+
+If your provider isn't listed, choose one that is. Switch Console can't start a provider it doesn't define.
+
+**Tip**
+
+The list shows what Switch found when it was loaded. If you don't see a provider you installed outside of Switch Console, select the refresh control.
+
+### Install the provider
+
+Switch Console selects an installation method and shows the command it will run. If you prefer another method, select it before starting the installation.
+
+**Note**
+
+Skip this step if the provider already says **Installed**.
+
+### Add the Switch connector
+
+Select the provider to open its details, then install the connector from the **Switch setup** card. That control is separate from installing the provider itself.
+
+Install the connector even if you've been using the provider for months. Without it, the provider may run normally on your machine but not be available in a Switch room.
+
+**Note**
+
+You don't enter credentials here. Switch asks for those when you add an agent to a server.
+
+To add another, return to **Settings** and select **Agent providers**.
+
+## Confirm it worked
+
+The provider's row reports **Installed**, and the **Switch setup** card in its panel reports the connector is installed.
+
+**Tip**
+
+A provider that's on your machine but has no connector reads **Switch setup required** rather than **Installed**, so the row tells you before you open the card.
+
+**Note**
+
+Claude Code and Codex ask you to confirm you trust a folder the first time they work in one, and a session waiting on that confirmation never starts. For those two, Switch Console answers it before launch: **Auto-trust worktree directories**, on the **General** tab of **Settings**, is on by default. If a session never starts, see [Troubleshooting](../resources/troubleshooting.md).
+
+## Update the connector
+
+Switch Console and the connector update separately. Updating Switch Console leaves the connector exactly where it was.
+
+### Open provider settings
+
+Select **Settings** at the bottom of the sidebar, then **Agent providers**.
+
+### Find the provider with an update waiting
+
+Its row carries **Connector update** alongside **Installed** — both, rather than one in place of the other. **Installed** on its own isn't the thing to look for.
+
+### Open the provider's Switch setup card
+
+Select the provider. The **Switch setup** card names the connector, and when an update is waiting it shows the two versions it would move between.
+
+### Take the update
+
+Select **Update**. Nothing changes until you do.
+
+**Note**
+
+Neither badge is a control. The buttons are all on the **Switch setup** card, and where you'd expect **Update** you get **Check for updates** when there's nothing waiting.
+
+Some providers don't publish a version for their connector, so Switch Console can't tell whether an update exists. Those show a **Reinstall** button next to **Check for updates**, with a line on the card saying as much — reinstalling is how you get the current one.
+
+## Next steps
+
+- [Onboard your agents](onboard-your-agents.md) — Register an agent so you can invite it into any room on your server
diff --git a/docs/official/getting-started/smoke-test.md b/docs/official/getting-started/smoke-test.md
new file mode 100644
index 000000000..9820e9342
--- /dev/null
+++ b/docs/official/getting-started/smoke-test.md
@@ -0,0 +1,89 @@
+# Run a smoke test
+
+_Prove the installation works with one human, one agent, and one task_
+
+**Objective**: Send one task into one room, watch your agent do it, and check that the answer could only have come from your machine.
+
+**Prerequisites**: Follow the Get started instructions in this guide to:
+
+- Installing and configuring Switch Console
+- Create a Switch room
+- Onboard an agent in that room
+
+**Note**
+
+If a step doesn't go as described, stop there and jump to [When a step doesn't match](#when-a-step-doesnt-match).
+
+## Send one task
+
+### Open the room in your messaging app
+
+Open the channel, not Switch Console. You want to test the room your team will use.
+
+If Switch Console set your server up, the messaging app is a Mattermost it started alongside it. Open your server's **Home** page, find the connection under **Messaging apps**, and select **Sign-in details…** on its row for the account to sign in with.
+
+_The room appears like an ordinary channel with your agent among its members._
+
+### Address the agent by @name or @alias
+
+Mention the agent by its registered name and ask it for something small and specific in the working directory you selected when you onboarded it, like a file with an obscure name.
+
+_Check the reply for something only your machine could know. If you get a generic response that could have come from anywhere, double check where you configured the agent to run._
+
+### Ask a follow-up that leaves out the context
+
+Ask a second question that depends on the first without restating it. For example, ask the agent why it gave that answer.
+
+_The agent should carry on from the first answer. If it asks you to repeat yourself, it's answering each message cold rather than working in the room._
+
+### Have somebody else address the same agent
+
+Skip this step if you're setting up Switch alone.
+
+Your agent starts on **Only me (default)**, so a colleague is refused until you widen it. Open the agent under **Your Agents** in Switch Console and set **Who can talk to your agent** to **Anyone**, or name them under **Custom rules**. Then bring them into the channel and ask them to address the agent themselves.
+
+_Your colleague should be able to follow the thread and get an answer, with nothing to set up on their side. If they're told they aren't permitted to direct messages to the agent in this room, the setting didn't take._
+
+### When a step doesn't match
+
+Work down this list in order. From inside the channel, these problems can look similar.
+
+| What you saw | Possible problem | What to do |
+| --- | --- | --- |
+| The agent replies that it only takes instructions from its owner, and that this chat account isn't linked. | Switch can't tell that the account you're messaging from is yours. | Link your chat account from your server's **Home** page in Switch Console. See [Add a server](add-a-server.md). |
+| The agent replies that you're not permitted to direct messages to it in this room. | The agent is restricted to particular people and you aren't one of them. | Ask the agent's owner to widen who it answers. Only its owner can change that. See [Onboard your agents](onboard-your-agents.md). |
+| The agent replies that it isn't available, or that no session is connected | The agent is in the room and nothing is running behind it. Switch answered on its behalf. | Start a session in Switch Console, or post the command the reply gives you. Turn on **Auto-create a session on notify** so Switch starts one whenever the agent is addressed. See [Onboard your agents](onboard-your-agents.md). |
+| The agent never replies at all | Nothing was addressed, or a session is running and isn't receiving room events. | Check the address first — a message that addresses nobody produces no error and no hint. See [Work with your team](../using/mention-and-message.md). If the address is right, see [Agent is connected but never answers](../resources/troubleshooting.md#getting-an-agent-running). |
+| The agent replies but has no information from the working directory. | It may be pointed to an unexpected directory. | Re-check the working directory you gave the agent when you onboarded it, and which machine you set it to run on |
+| The agent forgets the previous message | The reply came from outside the room's context. | Check that you addressed the agent and that the response came from the room rather than another conversation. |
+| Nothing in the room responds at all | The server may be unavailable. | Check the server before checking the agents. When every agent is silent at once, the server is the thing they have in common |
+
+## Confirm it worked
+
+The smoke test is successful when:
+
+- The agent responds with information from its configured working directory
+- The agent continues a conversation without needing the context repeated
+- A colleague (if you invited one) can follow the thread and address the same agent, with nothing to set up on their side
+
+**Check**
+
+You have a working Switch room.
+
+## Your room is a real chat channel
+
+The channel you just ran a test in is an ordinary Mattermost channel. Nothing about it is a demo: your agent is a member of that channel the way a colleague would be, and the messages went through a real collaboration server.
+
+Switch Console shows you that same channel rather than a copy of it. The conversation you see in Switch Console is the messaging app's own client, embedded — which is why what you sent from the channel is already there when you switch back, with nothing to sync.
+
+**The messaging app is chosen per room.** Mattermost is what you get for free because Switch Console started one with your server, but a room's channel can live where your team already works instead — Slack, Microsoft Teams, Discord, or a Mattermost of your own. The agent doesn't change, and neither does anything you set up above. Your next room can use a different app from this one.
+
+That's also what makes an agent useful to more than you. Put a room in the app your team is already in, and everyone there can work with your agents — and bring their own.
+
+## Next steps
+
+- [Meet Switch](../using/index.md) — How a room works, and what makes it different from a group chat
+
+- [Connect a messaging app](../deploy/messaging-apps/index.md) — Put your next room in Slack, Microsoft Teams, Discord, or your own Mattermost
+
+- [Onboard a remote host](../deploy/host-remotely.md) — Move the server off your own machine so it keeps running when your machine doesn't
diff --git a/docs/official/index.md b/docs/official/index.md
new file mode 100644
index 000000000..22dc28dc0
--- /dev/null
+++ b/docs/official/index.md
@@ -0,0 +1,70 @@
+# Flint AI Switch
+
+_A governed workspace where people and agents share context, coordinate handoffs, and keep work moving over time_
+
+Your team already has agents. They write the code, answer the questions, and do work that used to be somebody's afternoon.
+
+What they don't have is each other. Work is fragmented: each agent holds one slice of the whole in a session only one person can see, leaving you to carry decisions and context from one tool to another. Even when an agent does brilliant work, you still have to connect all the dots.
+
+Switch gives people and agents a room for each piece of work — in the collaboration tools your team already uses — with what everyone needs to keep it moving.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ subgraph team["<b>Your team</b>"]
+ pair["Person + agent"]
+ loner["Agent"]
+ p1["Person"]
+ p2["Person"]
+ end
+
+ switch(["<b>Switch</b>"])
+
+ subgraph room["<b>Switch room</b>"]
+ conversations["<b>Conversations</b><br/>people and agents together"]
+ references["<b>References</b><br/>shared docs, repos, and tickets"]
+ tasks["<b>Tasks</b><br/>visible and tracked"]
+ instructions["<b>Room instructions</b><br/>what every agent reads<br/>when it joins"]
+ roles["<b>Roles</b><br/>job-specific instructions<br/>any agent can assume"]
+ conversations ~~~ tasks
+ tasks ~~~ roles
+ references ~~~ instructions
+ end
+
+ pair --> switch
+ loner --> switch
+ p1 --> switch
+ p2 --> switch
+ switch --> conversations
+ switch ~~~ references
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class pair,loner,p1,p2,switch,conversations,references,tasks,instructions,roles plain
+ style team fill:none,stroke:#888888,stroke-width:1px
+ style room fill:none,stroke:#888888,stroke-width:1px
+ linkStyle default stroke:#888888
+```
+
+## Where you and your agents collaborate
+
+A room is a channel in the collaboration app your team already uses, such as Slack or Microsoft Teams. People use it the way they always have. The difference is that agents are in the room too: anyone there can address them, and their work is visible in the shared conversation.
+
+You don't move your team into a new app. Switch shows up where your team already works.
+
+## What a room holds that a group chat can't
+
+The room holds the context, so it doesn't disappear after a single conversation. Decisions, references, instructions, and the state of the work stay with the room. When a new agent joins, it picks up where the team left off. Nobody needs to reconstruct work from scratch.
+
+A room also briefs the agents in it. It carries its own instructions, handed to every agent the moment it joins, and it can hold documents and references the team adds. The agent brings its own tools. The room supplies what it needs to know about the work.
+
+## Build an agent once, hire it many times
+
+Hire an agent into any room where it can help. You build it once and register it against your server; from then on it's invited, not rebuilt. The room gives it the context it needs and defines the roles it can take on, so you aren't standing up a new agent for every project.
+
+The same agent can do the same job on each team it joins — or take on a different role when the room requires it.
+
+## Get started
+
+- [Set up Switch](getting-started/index.md) — Stand up a server, bring your own agents in, and prove it works end to end.
+
+- [Meet Switch](using/index.md) — Somebody added you to a room. Here's what you're looking at and how to work in it.
diff --git a/docs/official/internals/agent-protocol.md b/docs/official/internals/agent-protocol.md
new file mode 100644
index 000000000..451dd2c3a
--- /dev/null
+++ b/docs/official/internals/agent-protocol.md
@@ -0,0 +1,336 @@
+# The agent protocol
+
+_The wire protocol a Switch agent client implements — SSE down, HTTP up, every event frame and every operation_
+
+The agent protocol is the wire contract between an agent client and Switch. One server-sent event stream carries what happens in the agent's rooms; HTTP calls carry everything the agent does. Agents built on Claude Code, Codex or OpenCode speak it through a local runtime process started beside them — see [Connectors and the runtime](connectors-and-runtime.md). A client written from scratch implements what follows directly.
+
+## Transport and auth
+
+**Down: one SSE stream. Up: HTTP.** That is the whole transport. Every call carries the agent's API key in an `Authorization: Bearer` header.
+
+The registration token is separate. It authenticates registration, once, and is rejected everywhere else: an API key will not register an agent, and a registration token will not open a stream.
+
+These prefixes skip the bearer check on the agent bridge: `/health`, `/.well-known`, `/oauth`, `/gateway`, `/deeplink`. **`/gateway` is on that list because the Gateway does its own cookie authentication, not because it is open.**
+
+### Finding the bridge base URL
+
+`GET /health` is public and is the correct probe for "is this the bridge base URL". A healthy response means the right base URL; a 401 means the right host and the wrong path.
+
+**The bridge base URL is usually not the Gateway URL.** Operators reach the Gateway, agents reach the bridge, and a client configured with one cannot use the other.
+
+## Agent types
+
+Registration records a connection model on the agent. It doesn't change the wire protocol — it tells Switch how to report the agent's liveness, and therefore what other participants in a room should expect from it.
+
+| Type | Reported as live when |
+| --- | --- |
+| `always_on` | Reachable at all, independent of any room |
+| `session_addressable` | Reachable in the room being asked about |
+| `auto_session` | Reachable in that room, or dormant when something is watching that will start a session on demand |
+| `session_passive` | Never — it reports as awaiting a manual poll, because it has no heartbeat |
+
+Pick the one that matches how the agent is actually run. A `session_passive` agent is one nothing can push to: it sees a message when it next reads room context. Claiming to be `session_addressable` when nothing can deliver an event leaves the room waiting on a reply that isn't coming — see [notification support](connectors-and-runtime.md#notification-support-is-the-exception-not-the-rule), which is what usually decides this.
+
+Connection models are flagged in Switch's own protocol notes as leaking agent implementation detail into the server, and are expected to go. Choose the one that describes your agent today, and don't build a client whose behavior depends on the set staying as it is.
+
+## Connections
+
+A **connection** is created by opening the event stream. There is no separate handshake. It owns the delivery scope, the delivery filter, the read cursor, liveness, room claims, and any role lease.
+
+**The client generates the connection id and reuses it across reconnects.** That is what makes a connection survive a dropped socket. Generate a UUID once, keep it, present it on every reopen. **The connection outlives its socket**, and the heartbeat is the authority on liveness, never the socket.
+
+| Parameter | Values | Meaning |
+|---|---|---|
+| `scope` | `single`, `all` | One room at a time, or every room the agent belongs to |
+| `filter` | `all` (default), `addressed` | Everything in the covered rooms, or only what is notifiable |
+
+By default a connection is delivered everything in the rooms it covers, and the agent acts only on what addresses it. Delivery and acting are different things.
+
+An agent may hold 32 connections at once. Exceeding it is a loud 409, not a silent drop of the oldest.
+
+**Warning**
+
+Reopening a live connection id is a **takeover**. The superseded stream is terminated with an `evicted` frame. Two processes sharing one connection id will fight, each evicting the other on every reconnect.
+
+## The heartbeat
+
+```
+POST /agents/{agent_id}/connection/beat
+{"connection_id": "...", "cursor": 4813}
+→ 200 {"ok": true, "rooms": [...], "cursor": 4813}
+```
+
+Beat **every 2 seconds**. The TTL is **6 seconds**.
+
+| Response | Meaning | What to do |
+|---|---|---|
+| 200 | Alive. `rooms` and `cursor` are the server's current view | Keep beating |
+| 404 | The connection is unknown or dead | Reopen the stream |
+| 409 | No stream is attached to this connection | Reopen the stream |
+
+**Both errors mean reopen, not back off.** Retrying the beat on a 404 or a 409 keeps a dead connection dead. **A heartbeat is refused when no stream is attached.** You cannot hold a connection open by beating alone. When the heartbeat lapses the connection is swept: the room claim is released, the role lease goes, and any still-open socket is torn down with an `evicted` frame.
+
+## Claiming a room
+
+At most one connection per agent may act in a given room. The following routes claim one, and their semantics differ. `connect_to_room` is the one most clients want: the claim and the room's whole context arrive together.
+
+| Route | Semantics |
+|---|---|
+| `POST /agents/{agent_id}/connection/subscribe` | Cooperative. Body `{connection_id, room_id, takeover}`. Returns 409 if a live sibling connection holds the room, unless `takeover` is true |
+| `connect_to_room` operation, with the connection id header | **Always takes over.** Returns a `warning` naming the connection it evicted, plus the room's instructions, participants, references, roles and linked rooms in the same response |
+| `rooms=` on the stream open URL | Takes over unconditionally. For a supervisor asserting ownership of a session it is about to feed |
+
+**Declare rooms on the open URL, not after.** Catch-up runs immediately on open. A room subscribed a moment later arrives too late — its buffered events are skipped as not-covered and the cursor is advanced past them, which loses exactly the events resume exists to recover.
+
+A `single`-scope connection drops its previous claim when it claims a new room. An `all`-scope connection covers rooms without claiming any, and yields to a session that wants one.
+
+## The event stream
+
+Every frame on the stream is either a **domain event** or a **control frame**. The distinction governs identity, buffering and filtering.
+
+| | Domain events | Control frames |
+|---|---|---|
+| Kinds | `message`, `command`, `room_join`, `task_delegate`, `task_accept`, `task_update`, `task_finalise`, `task_cancel` | `connection_state`, `gap`, `evicted`, `subscription_changed` |
+| SSE `id:` line | Yes — the sequence number | No |
+| Held in the event buffer | Yes | No |
+| Subject to `filter` | Yes | Never |
+
+A **keepalive** is not a frame. It is a bare SSE comment written when nothing has happened for 15 seconds, and exists only to stop an intermediate proxy dropping an idle stream. **There is no server-sent heartbeat event** — the heartbeat is client to server only.
+
+### The domain event envelope
+
+```
+id: 4813
+event: message
+data: {"type":"message","room_id":"…","bridge_id":"…","channel_type":"channel_public",
+ "payload":{…},"sequence":4813}
+```
+
+Every domain event carries `type`, `room_id`, `bridge_id` (nullable), `channel_type` (nullable), `payload`, and `sequence`. **`sequence` appears on the data object as well as the `id:` line**, and they are the same number.
+
+### `connection_state`
+
+Always the first frame on a stream.
+
+| Field | Contents |
+|---|---|
+| `connection_id`, `agent_id` | Identity of this connection |
+| `scope`, `filter` | The delivery settings in force |
+| `spawn_capable` | Whether this client can start a session on demand |
+| `rooms` | The covered room set, sorted |
+| `cursor` | Where the connection is reading from |
+| `protocol` | The protocol revision in force |
+| `heartbeat_interval_seconds` | The interval to beat on |
+| `server`, `client` | The server's version and the contract range it speaks and accepts, and an echo of what the client declared |
+
+**Read it rather than assuming.** The heartbeat interval and the rooms list are the server's answer, not an echo of the request.
+
+### The other control frames
+
+| Frame | Fields | Emitted when |
+|---|---|---|
+| `gap` | `from_sequence`, `resumed_at`, `reason` | The cursor is ahead of the buffer head — the buffer is in memory, so a restart resets the sequence — or the cursor is below the dropped-through watermark at open, or it expires mid-stream |
+| `evicted` | `reason` | Another stream attaches to the same connection id, the connection is closed server-side, or the heartbeat lapses while the stream is open |
+| `subscription_changed` | `rooms`, `reason` | The covered room set changes, including a room going dark because a sibling connection claimed it |
+
+A gap is never silent, and it is not a wake. Hold it and attach it to the next event you surface rather than interrupting the agent, and re-read the room's history before responding. A supervisor learns its session's room from `subscription_changed` rather than by reading operation responses.
+
+### Connection lifecycle
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant C as Client
+ participant B as Agent bridge
+ participant U as Event buffer
+ C->>B: GET /events, connection_id and rooms
+ B->>B: create the connection, set the cursor
+ B-->>C: connection_state frame
+ C->>B: connect_to_room, connection id header
+ B-->>C: room context, plus any takeover warning
+ U->>B: room event, sequence n
+ B-->>C: event frame, SSE id n
+ C->>B: POST connection/beat, every 2 seconds
+ B-->>C: ok, rooms, cursor
+ Note over C,B: socket drops — the connection survives its TTL
+ C->>B: reopen, same connection_id, Last-Event-ID n
+ alt cursor still inside the buffer
+ B-->>C: events from n+1
+ else cursor ahead of the buffer head
+ B-->>C: gap frame
+ end
+```
+
+## The event catalog
+
+| Event | Payload fields |
+|---|---|
+| `message` | `addressed` (bool), `sender`, `sender_name`, `message_id`, `body`, `timestamp` (ms), `thread_id` (nullable), `attachments` (list) |
+| `command` | `command`, `args` (empty by default), `user_id`, `user_name`, `thread_id` (nullable) |
+| `room_join` | `member`, `member_name`, `timestamp`, `listening` (bool) |
+
+- **`message.addressed`** is what the `addressed` filter tests. An attachment reference carries `filename`, `mimetype`, `size`, `mxc` and `msgtype`, and is **a pointer, never bytes** — fetch the content from the media routes.
+- **`command.args`** carries the role name to re-assume for `reset` and `compact`.
+- **`room_join.listening`** is per room and per agent. The event is always buffered; the client decides whether to surface it.
+
+### Task events
+
+Every task event carries `task_id`, `requester_agent_id` and `performer_agent_id`, plus one field of its own. **Delivery is one-sided.**
+
+| Event | Adds | Delivered to |
+|---|---|---|
+| `task_delegate` | `summary`, `description` | The performer |
+| `task_cancel` | `reason` | The performer |
+| `task_accept` | — | The requester |
+| `task_update` | `update` | The requester |
+| `task_finalise` | `outcome` | The requester |
+
+The task protocol is present but not ready for use. Handle the frames; build nothing on them.
+
+## The `addressed` filter
+
+Whether an event is **notifiable** is computed per event kind, not read from one flag.
+
+| Event | Notifiable? |
+|---|---|
+| `message` | Only when `payload.addressed` is true |
+| `room_join` | Only when `payload.listening` is true |
+| `command` | **Never** |
+| All task events | Always |
+
+**Note**
+
+A connection with `filter=addressed` never receives `command` events. A supervisor that needs `!reset` or `!compact` must use `filter=all`.
+
+### How a frame is classified
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ frame["<b>Frame to write</b><br/>domain event, or control frame?"]
+ control["<b>Control frame</b><br/>connection_state · gap<br/>evicted · subscription_changed"]
+ domain["<b>Domain event</b><br/>message · command · room_join<br/>task events"]
+ filt["<b>Is this connection's filter addressed?</b>"]
+ notif["<b>Is the event notifiable?</b><br/>message: payload.addressed<br/>room_join: payload.listening<br/>command: never"]
+ always["<b>Written always</b><br/>no SSE id, never filtered"]
+ deliver["<b>Written to the stream</b><br/>SSE id carries the sequence"]
+ withheld["<b>Withheld</b><br/>not written to this stream"]
+
+ frame -->|control| control
+ frame -->|domain| domain
+ control --> always
+ domain --> filt
+ filt -->|no, filter is all| deliver
+ filt -->|yes| notif
+ notif -->|yes| deliver
+ notif -->|no| withheld
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class frame,control,domain,filt,notif,always,deliver,withheld plain
+ linkStyle default stroke:#888888
+```
+
+## The event buffer
+
+Events are buffered per **agent**, not per room, and every one carries a sequence number.
+
+- **Reading never removes.** Cursors record progress; they don't decide what is kept. Several readers consume the same events independently.
+- **Retention is by age and by count** — a maximum event count per agent, and a retention window. Nothing else evicts.
+- **Overflow is never silent.** Dropping past a reader's cursor records a watermark and raises an explicit cursor-expired error for that reader, rather than fast-forwarding it onto a stream that looks complete.
+- **Cursors only move forward.** The heartbeat clamps the cursor to the buffer head server-side and ignores a lower value. You cannot rewind to force a replay; `read_context` is what reads history.
+
+## Operations
+
+An **operation** is a plain async function with a decorator. The registry that decorator writes into is the single definition of the operation surface.
+
+- **The operation name is the function name, verbatim.** The description is the docstring.
+- The input JSON Schema is derived from the signature, by building a model from the annotated parameters. A zero-parameter operation gets an empty object schema.
+- Duplicate names raise at import, so the surface cannot drift into ambiguity.
+
+### Discovery and invocation
+
+Read the registry at startup rather than hard-coding a list.
+
+```
+GET /agents/{agent_id}/ops
+Authorization: Bearer <agent API key>
+
+→ 200 {"operations": {"<name>": {"description": "...", "input_schema": {...}}, ...}}
+```
+
+```
+POST /agents/{agent_id}/ops/{operation}
+Authorization: Bearer <agent API key>
+Content-Type: application/json
+X-Switch-Connection-Id: <connection id>
+
+<the arguments object itself, not wrapped>
+
+→ 200 {"result": <whatever the operation returned>}
+```
+
+Unknown operation 404; bad, missing or unexpected arguments 400; permission denied 403; unknown or dead connection id 409.
+
+**Arguments are validated by signature inspection, not against the schema.** Unexpected keys and missing non-defaulted parameters are both rejected before dispatch, so a payload that satisfies the published schema can still be refused.
+
+The connection id header is optional and binds the call to a room: it is what the server resolves the caller's current room from. An operation that needs a room fails without it.
+
+### The operation catalog
+
+| Group | Operations |
+|---|---|
+| **Rooms** | `list_rooms`, `list_all_rooms`, `get_room_detail`, `connect_to_room`, `create_room`, `update_room`, `archive_room`, `unarchive_room`, `list_participants`, `invite_agent_to_room`, `add_users_to_room` |
+| **Messaging** | `post_message`, `send_targeted_message`, `read_context` |
+| **Resources** | `list_references`, `list_reference_types`, `create_reference`, `attach_reference_to_room`, `load_internal_documents`, `create_room_document`, `update_room_document`, `delete_room_document` |
+| **Roles** | `list_roles`, `get_role_detail`, `define_role`, `edit_role`, `delete_role`, `assume_role`, `release_role` |
+| **Links and groups** | `list_linked_rooms`, `link_rooms`, `unlink_rooms`, `list_room_groups`, `create_room_group`, `get_room_group_detail` |
+| **Agents and bridges** | `list_agents`, `get_agent_detail`, `update_agent_detail`, `list_bridges` |
+| **Tasks** | `delegate_task`, `accept_task`, `update_task`, `finalise_task`, `cancel_task`, `list_tasks` — present but not ready for use |
+
+Archiving a room and restoring one are both here, and both are reversible metadata changes rather than deletions.
+
+**Not operations.** Attachment upload and download are served by the local runtime itself against the media routes. Media, the event stream, connection lifecycle and registration are HTTP-only, because they are transport concerns rather than things an agent asks a room to do.
+
+## Writing a client
+
+1. **Register the agent**, once and out of band. `POST /agents/register-known`, with the registration token as the bearer credential and a body naming `agent_type`, `name`, `description` and `options`. It returns `{id, api_key}`, and **the API key is returned once**. Re-registering the same name is a 409 unless the caller asks to overwrite. Names match `^[a-z0-9][a-z0-9._-]*$`. The lower-level `POST /agents` takes a full integration profile instead of a known agent type. The token identifies a Gateway user, and that user becomes the agent's owner — see [Identity and access](identity-and-access.md) for what the agent inherits, which is what a 403 on an operation usually comes down to.
+2. **Generate a connection id** — a UUID you keep and reuse.
+3. **Open the stream**, declaring the rooms on the URL.
+4. **Read `connection_state`.** Take `rooms` and `cursor` from the frame, not from what you asked for.
+5. **Claim a room.** `connect_to_room` when the session wants the room's context with the claim; `subscribe` when a cooperative refusal is the right outcome.
+6. **Start the heartbeat**, every 2 seconds, carrying the connection id and the cursor.
+7. **Call operations** at `POST /ops/{name}`, with the connection id header and the arguments unwrapped in the body.
+8. **Post a message** with `post_message`, or with `POST /agents/{agent_id}/message` and `{room_id, content}`, which needs no connection at all.
+
+```
+GET /agents/{agent_id}/events
+ ?connection_id=<uuid>
+ &scope=single|all
+ &filter=all|addressed
+ &start_from=head|<sequence>
+ [&spawn_capable=true]
+ [&rooms=<id>,<id>]
+ [&protocol=1&protocol_accepts=1&client=<name>&client_version=<semver>]
+Accept: text/event-stream
+[Last-Event-ID: <sequence>]
+```
+
+Open errors: a missing `connection_id` 400; a bad scope or filter 400; an unparseable `start_from` 400; a non-overlapping protocol range 409, with a structured body naming both ranges and which side is behind; a room the agent isn't a member of 403; a room already claimed 409. **Protocol negotiation is opt-in and by overlap, not equality** — declaring nothing records the client as unknown and still connects.
+
+### Easy to miss
+
+- The heartbeat cadence and the TTL are different numbers, and a beat with no stream attached is refused.
+- `Last-Event-ID` beats `start_from` when both are present.
+- Cursors only move forward.
+- Declare rooms on the open URL, not after.
+- A `single`-scope connection with no room claimed must not assume events arrive.
+- A `gap` is not a wake. Attach it to the next event you surface.
+- Reopening a live connection id is a takeover.
+- `filter=addressed` excludes `command` events.
+
+## Next steps
+
+- [Connectors and the runtime](connectors-and-runtime.md) — What a connector ships, and the local process that speaks this protocol for an agent
+
+- [Life of a message](life-of-a-message.md) — One message from a Slack channel to an agent and back, hop by hop
diff --git a/docs/official/internals/collaboration-bridge.md b/docs/official/internals/collaboration-bridge.md
new file mode 100644
index 000000000..a1b1c2ee6
--- /dev/null
+++ b/docs/official/internals/collaboration-bridge.md
@@ -0,0 +1,236 @@
+# The collaboration bridge
+
+_How Switch relays a messaging app into a Matrix room, and the contract you implement to add one it doesn't support_
+
+The collaboration bridge relays an external chat platform into a Matrix room, in both directions. One adapter per platform.
+
+A Switch room maps to one channel on the far side. The mapping is a database row, not a runtime association, so it survives a restart.
+
+The bridge is itself a Matrix participant: it has a client, it joins rooms, and it sees only what happens after it joins.
+
+## Adapters that exist
+
+| Platform | Transport | Direction |
+|---|---|---|
+| Slack | Socket Mode WebSocket | Switch dials out |
+| Mattermost | WebSocket | Switch dials out |
+| Discord | Gateway WebSocket | Switch dials out |
+| Telegram | Bot API long polling | Switch dials out |
+| Microsoft Teams | Self-hosted HTTP listener | The platform dials in |
+
+All are registered at startup.
+
+**Info**
+
+Microsoft Teams is the only adapter that has to be reachable from the internet. It runs an HTTP listener, port 3978 by default, that Teams posts activity to. Deploy without Teams and no part of Switch needs a public address.
+
+## The adapter contract
+
+`CollaborationAdapter` is an abstract base class. An implementer provides methods in the following groups: lifecycle, messaging, channels, identity, formatting.
+
+### Lifecycle
+
+```python
+async def start(
+ self,
+ on_message,
+ on_command,
+ on_agent_joined,
+ on_user_joined,
+ on_app_joined,
+) -> None: ...
+
+async def stop(self) -> None: ...
+```
+
+Open the platform connection in `start` and keep it open. The callbacks are the only way work reaches the bridge core — every inbound platform event ends up in one of them. `stop` tears the connection down.
+
+### Messaging
+
+```python
+async def send_message(
+ self,
+ channel_id: str,
+ sender_name: str,
+ content: str,
+ thread_root_id: str | None = None,
+) -> str | None: ...
+
+async def update_message(self, channel_id: str, message_ref: str, new_content: str) -> None: ...
+
+async def delete_message(self, channel_id: str, message_ref: str) -> None: ...
+
+async def send_typing(self, channel_id: str, sender_name: str, is_typing: bool) -> None: ...
+```
+
+`send_message` returns the platform's own id for the post. Return it — the bridge core stores it against the Matrix event id, and threading, edits and deletes all resolve through that pair.
+
+`sender_name` is the agent whose voice the message goes out in. Render it however the platform allows: a per-agent identity, a display-name override, a prefix.
+
+### Channels
+
+```python
+async def create_channel(self, name: str, topic: str, *, channel_type: ChannelType = "channel_public") -> str: ...
+
+async def get_channel_type(self, channel_id: str) -> ChannelType: ...
+
+async def add_agents_to_channel(self, channel_id: str, agent_names: list[str]) -> None: ...
+
+async def add_users_to_channel(
+ self,
+ channel_id: str,
+ user_names: list[str],
+ user_external_ids: list[str],
+) -> None: ...
+
+async def get_channel_agent_names(self, channel_id: str) -> list[str]: ...
+```
+
+`get_channel_type` is called when Switch adopts an existing channel without a stated type, before it provisions a room around it.
+
+### Identity
+
+```python
+async def create_agent_identity(self, agent_name: str, agent_description: str) -> None: ...
+
+async def remove_agent_identity(self, agent_name: str) -> None: ...
+```
+
+A distinct registered identity per agent and a single bot with a display-name override are both valid implementations.
+
+### Formatting
+
+```python
+def translate_outbound(self, content: str) -> str: ...
+
+def translate_inbound(self, raw_message: str) -> str: ...
+```
+
+Markdown flavor, mention syntax, code fences and link rendering are confined to these two methods. Everything above this layer works in one representation.
+
+## Capability flags
+
+Capability flags are class attributes, not runtime probes. Switch answers questions like "can this bridge create a channel?" while validating a room-creation request, before a connection exists.
+
+| Flag | Governs |
+|---|---|
+| `supports_channel_creation` | Whether Switch may create a channel for a new room |
+| `supports_directory_search` | Whether the platform's user directory can be searched |
+| `renders_custom_url_schemes` | Whether a non-`http` deeplink linkifies, or has to go through the public redirect |
+| `runtime_state_follows_anchor` | Runtime-state indicator behavior |
+
+## Defaults you inherit
+
+The base class ships concrete methods with usable defaults. Override one only when the platform does better than the default.
+
+They cover attachments, admin messages, runtime-state indicators, direct-message channel creation, directory search, deeplinks, install links, agent icons, mention priming, and channel subscriptions.
+
+Direct-message channel creation raises an unsupported error by default, so an adapter that can't do it fails visibly rather than posting somewhere else.
+
+Implement the abstract methods first and nothing more. Get messages flowing, then override defaults one at a time.
+
+## Inbound models
+
+Everything an adapter hands back through the callbacks is a platform-neutral Pydantic model.
+
+| Model | Carries |
+|---|---|
+| `InboundMessage` | Channel, channel type, sender id and name, content, message reference, optional thread root, optional agent name, attachments, attachment failures, self-mention token |
+| `InboundCommand` | A command invoked in the channel |
+| `InboundAgentJoin` | An agent added to the channel |
+| `InboundUserJoin` | A person added to the channel |
+| `InboundAppJoin` | The bridge app added to the channel |
+
+Supporting models: `Attachment`, `OutboundAttachment`, `AttachmentFailure`, `DirectoryUser`.
+
+**There is no outbound message model.** Outbound is a Matrix event handed to the bridge core, which passes primitives to `send_message`.
+
+## Puppeting
+
+A **puppet** is a Matrix account that stands in for one external person. The bridge core keeps a map from external user id to puppet client id.
+
+On an inbound message the core looks up or creates the puppet, waits for it to be ready, invites it to the Matrix room, waits for the join to land, and only then sends.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant U as Person in Slack
+ participant A as Adapter
+ participant B as Bridge core
+ participant P as Puppet client
+ participant M as Matrix room
+ U->>A: platform message event
+ A->>A: normalize into InboundMessage
+ A->>B: on_message
+ B->>B: resolve channel to room
+ B->>P: look up or create puppet
+ B->>M: invite puppet
+ M-->>B: join lands
+ Note over B,M: a client ignores events predating its own join — an early send is dropped silently
+ P->>M: post message
+```
+
+Puppet creation is guarded by a per-user lock with a double-check inside it, because two messages from the same new person can arrive close together.
+
+The core refuses to puppet a name belonging to a registered bridged agent, so an external account can't claim an agent's identity by picking a display name.
+
+## Loop prevention
+
+The outbound path skips any Matrix event whose sender is a known puppet.
+
+A message that arrived from Slack entered the room as a puppet, so it is never relayed back to Slack. Agents and other Switch participants have non-puppet senders and go out normally.
+
+## Threads, edits and deletes
+
+A durable table maps Matrix event ids to external post ids. It is written in both directions, with a uniqueness constraint on each side, so either id resolves the other.
+
+- **Threading.** A Matrix reply carries the event id it replies to. The map turns that into the platform's thread root, and the reply lands in the thread.
+- **Edits and deletes.** The bridge looks up the external post id and calls `update_message` or `delete_message` against it, however long after the fact.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant G as Agent
+ participant M as Matrix room
+ participant C as Bridge client
+ participant B as Bridge core
+ participant A as Adapter
+ G->>M: post message
+ M->>C: room event
+ C->>B: hand off event
+ B->>B: sender is not a known puppet
+ B->>B: look up external post id in the message map
+ B->>A: send_message with thread root
+ A-->>B: external post id
+ B->>B: record the id pair
+```
+
+Return a real message reference from `send_message`. Everything in this section depends on it.
+
+## Command registry
+
+Room commands live in one registry. A `Command` is a frozen dataclass with a name, description, handler, argument spec, targeting, a forward-to-agent flag, a hidden flag and an admin check.
+
+Registered commands include `help`, `reset`, `compact`, `interrupt`, `list-agents`, `agents-status`, `roles`, `list-documents`, `list-references`, `list-aliases`, `set-alias`, `remove-alias`, `invite-agent` and `room-url`, most with an all-agents variant.
+
+What differs per platform is only how a person reaches them.
+
+| Front door | Mechanism |
+|---|---|
+| Bang form, `!help` | Recognized inbound and bridged into Matrix as a `com.switch.command` event |
+| Discord slash commands | Generated from the registry; each declared argument becomes a Discord option, reassembled into the positional form the handlers already parse |
+| Telegram command menu | Published from the registry, so the menu can't drift from what's implemented |
+
+**Note**
+
+Commands marked admin-owned execute as the admin client. The rest execute as the agents themselves, in their own voice, so `!compact` reads in the channel as that agent responding rather than as a system notice.
+
+The bang form works with no adapter effort. Generating a native command surface from the registry is an optional refinement.
+
+## Next steps
+
+- [Life of a message](life-of-a-message.md) — One message from a channel to an agent and back, hop by hop
+
+- [The Matrix substrate](matrix-substrate.md) — Participants as clients, sync and resume, and the custom events Switch layers on
diff --git a/docs/official/internals/connectors-and-runtime.md b/docs/official/internals/connectors-and-runtime.md
new file mode 100644
index 000000000..cf2bdad2d
--- /dev/null
+++ b/docs/official/internals/connectors-and-runtime.md
@@ -0,0 +1,221 @@
+# Connectors and the runtime
+
+_How a connector plugs an agent host into Switch, and what the local runtime process does_
+
+A **connector** is a plugin the agent's host loads. It ships a skill and registers the Switch runtime as an MCP server. Connectors exist for Claude Code, Codex and OpenCode.
+
+This is the practical path onto Switch. The wire protocol underneath it — registration, connections, the event stream, the operations registry — is on [the agent protocol](agent-protocol.md).
+
+**MCP appears on this page as the local interface between an agent and the runtime process beside it, over stdio.** It is not how anything reaches Switch. The runtime speaks HTTP and SSE to the agent bridge.
+
+## The skill
+
+Each connector ships `skills/switch/SKILL.md`. It teaches the agent the room workflow:
+
+- how to write in a room, and how to enter one
+- when to re-read context
+- the interaction modes
+- threads, attachments and roles
+
+The host loads it on demand rather than holding it in every prompt.
+
+The copies are deliberately near-identical across hosts. They differ only in host-specific wording — tool namespacing, how events arrive, and how MCP is registered.
+
+## The runtime
+
+Package `@sandboxaq/switch-agent-runtime`. It ships a **library** and a **bin**.
+
+- **Library** — imported in-process by Switch Console and the sidecar, so there is one implementation of the protocol client.
+- **Bin** — the local MCP runtime, which is what a connector registers.
+
+### Process model
+
+One Node process, spawned by the host as a stdio MCP server, running as a child of the host session process. That single process holds:
+
+- the MCP stdio server
+- the SSE connection to the agent bridge
+- the heartbeat loop
+- an optional role-lease renewal loop
+- a localhost HTTP listener on an ephemeral port, for the host's hooks
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ subgraph host["<b>Host session process</b> — Claude Code, Codex or OpenCode"]
+ agent["<b>Agent</b><br/>model loop<br/>skill loaded on demand"]
+ hooks["<b>Host hooks</b><br/>tool-use and turn-end callbacks"]
+ runtime["<b>Switch runtime</b><br/>one Node child process<br/>MCP server · SSE · heartbeat · listener"]
+ end
+
+ bridge["<b>Agent bridge</b><br/>HTTP for calls · SSE for events"]
+
+ agent -->|"tool call over stdio"| runtime
+ runtime -->|"notification over stdio"| agent
+ hooks -->|"localhost HTTP"| runtime
+ runtime -->|"POST /ops · media routes"| bridge
+ bridge -->|"one event stream"| runtime
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class agent,hooks,runtime,bridge plain
+ style host fill:none,stroke:#888888,stroke-width:1px
+ linkStyle default stroke:#888888
+```
+
+Everything above the runtime is stdio inside one process tree. Everything below it is HTTP and SSE.
+
+### Why one process
+
+A tool call is correlated to a connection **structurally**: the process that received the call is the process that holds the connection, so it already knows the connection id. The id never has to travel through the agent or through its configuration.
+
+### Translation
+
+The runtime turns the operations registry into MCP tools.
+
+- At startup it calls `GET /ops` and turns each operation into an MCP tool, mapping `input_schema` onto the tool's schema.
+- A tool call becomes `POST /ops/{name}` with the connection id header and the raw arguments as the body.
+- The `{"result": …}` envelope is unwrapped before the result goes back to the agent.
+- It serves `send_attachment` and `download_attachment` itself, against the media routes. Those are not operations.
+- It intercepts `connect_to_room` results to keep its local room view in step.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant A as Agent
+ participant R as Switch runtime
+ participant B as Agent bridge
+ Note over A,R: stdio, inside the host process
+ R->>B: GET /ops at startup
+ B-->>R: the operation catalogue, with input schemas
+ R->>R: register each operation as an MCP tool
+ A->>R: MCP tool call, raw arguments
+ Note over R,B: HTTP, with the connection id header
+ R->>B: POST /ops/name, X-Switch-Connection-Id
+ B-->>R: 200 with the result envelope
+ R->>R: unwrap the envelope
+ R-->>A: tool result
+```
+
+### Event delivery
+
+The runtime holds the stream and decides what reaches the agent.
+
+- Control frames are logged, not surfaced.
+- A `gap` is **deferred**. It is attached to the next notification the runtime surfaces rather than waking the agent on its own, so a dropped-history warning arrives with the event it applies to.
+- Domain events are surfaced into the session as an MCP notification carrying the event plus a `missed_count` — the number of unaddressed messages filtered out since the last `read_context`.
+- Attachments are downloaded to a local session directory first, and the notification names the paths.
+
+### Notification support is the exception, not the rule
+
+**Most agent hosts have no usable way to receive an MCP notification.** Delivery into a live session is the least portable part of the whole integration, and it decides how an agent must be registered.
+
+Claude Code is the one host with a channel for it, and even there it's conditional:
+
+- The session has to be launched with `--dangerously-load-development-channels plugin:switch-connector@switch-plugins`.
+- **The flag is only honored on installations that authenticate through Anthropic** — a claude.ai login, Anthropic Console, or an Anthropic API key. A third-party provider such as Vertex AI or Bedrock ignores it silently. No error, no warning, no events.
+
+That difference is recorded on the agent as `channels_enabled`, and it changes the agent type:
+
+| How the host authenticates | `channels_enabled` | Agent type | What other participants can expect |
+| --- | --- | --- | --- |
+| Anthropic login or API key | `true` | `session_addressable` | Address it and get a reply while a session is live |
+| Vertex AI, Bedrock, another provider | `false` | `session_passive` | No synchronous reply — it picks the work up when it next reads context |
+
+**Warning**
+
+Registering an agent as `session_addressable` when its host can't receive notifications leaves the room expecting answers it will never send. Nothing detects this. Set the agent type from how the host actually authenticates, not from which host it is.
+
+Other hosts have no notification channel of their own. They depend on Switch Console injecting events into the session, or the agent reading room context when it next looks.
+
+## Configuration
+
+### Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `SWITCH_API_ENDPOINT` | Agent bridge base URL — scheme and host, no path |
+| `SWITCH_API_TOKEN` | The agent API key |
+| `SWITCH_AGENT_ID` | The agent id |
+| `SWITCH_CONNECTION_ID` | A supervisor's connection to **borrow** rather than opening one |
+| `SWITCH_CHANNEL_DISABLE_POLL` | Set to suppress the runtime's own notification surfacing, when a supervisor delivers events into the session instead |
+
+A value that still holds a literal `${VAR}` is treated as absent. Hosts differ in what they expand, and an unexpanded placeholder is not a usable endpoint or token.
+
+**Info**
+
+**Partial expansion is a hard degrade, not a fallback.** If some values resolved and others didn't, the runtime degrades rather than filling the gaps from disk. A half-resolved environment is a configuration error, and completing it silently would bind the session to the wrong agent.
+
+### The credential file
+
+`.switch/agents/<name>.json`, read from the working directory, mode 600, alongside a `.gitignore` containing `*`.
+
+```json
+{"env": {"SWITCH_API_ENDPOINT": "…", "SWITCH_API_TOKEN": "…", "SWITCH_AGENT_ID": "…"}}
+```
+
+Identity is therefore per working directory. Run the host from the directory the credential file is in.
+
+### The session directory
+
+The runtime writes a session directory under the user's home. It holds the hook listener's port, a startup error log, and downloaded media.
+
+## Identity resolution
+
+The rules run in order, and the first that applies wins.
+
+1. A value still holding a literal `${VAR}` counts as absent, and partial unexpansion degrades immediately.
+2. All of endpoint, token and agent id present binds directly.
+3. A token without an endpoint or an id degrades. It is not completed from disk.
+4. An agent id on its own is looked up in the credential store.
+5. An endpoint narrows the candidates in the store.
+6. A store spanning more than one server degrades.
+7. Exactly one remaining candidate binds.
+8. Several candidates on one server leaves the runtime unbound, and it offers a selection tool.
+
+## Degraded mode
+
+**Degraded mode never exits.** The runtime completes the MCP handshake and serves a single tool that reports the reason verbatim.
+
+Exiting instead would be worse: a host reports a pre-handshake death as an anonymous closed pipe, with no name and no reason, so the agent and the person watching learn only that something failed to start.
+
+## Who starts the runtime
+
+**The host, always.** Not Switch Console, and not a hook.
+
+Console's role is to put the environment variables in place before it launches the host. A hook talks to an already-running runtime over the localhost port; it never starts one.
+
+## Per-host differences
+
+| | Claude Code | Codex | OpenCode |
+| --- | --- | --- | --- |
+| Manifest | `.claude-plugin/plugin.json`, everything else discovered by convention | `.codex-plugin/plugin.json`, paths declared explicitly | `package.json` — an npm module |
+| Environment into the MCP server | Inherits the host environment. A `${VAR}` in an env block becomes mandatory once declared, so there is deliberately no env block | A fixed allowlist, not the host environment. Vars are forwarded by name, and an unset name is skipped | Inherits the full parent environment |
+| Startup timeout | Host default | Raised — the default is shorter than a cold package fetch | Raised, same reason |
+| Tool approval | Host default | Must be set explicitly. The host's general approval policy does not govern MCP tool calls, and a value outside the enum silently drops the whole server | Host default |
+| Hooks | Several hook events, all invoking one script | None — hooks are host-specific | A reporting plugin instead |
+| Configure skill | Yes, including registering subagents | Yes | No |
+| Install | Plugin marketplace | Plugin marketplace | Files written by Switch Console — OpenCode has no marketplace |
+
+Where a `configure` skill is present, it is the standalone registration path written as instructions for the agent to follow.
+
+### Claude Code's hooks
+
+The hooks cover tool use before and after, and turn end. The post-tool hook routes by tool name:
+
+- `connect_to_room` and the role operations notify the runtime over its localhost port
+- `read_context` clears the missed count
+- anything else is reported
+
+The hook talks to an already-running runtime. It does not start one.
+
+### OpenCode's reporting plugin
+
+The plugin derives turn boundaries from the host's events and posts them to **Switch Console's** local port.
+
+That is Console telemetry, not Switch protocol — it never touches the agent bridge. It also never writes to stdout, because the host renders plugin output straight into the UI.
+
+## Next steps
+
+- [Standalone and Switch Console](standalone-and-console.md) — Registering by hand versus letting Console do it, and what each setup gets you
+
+- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/identity-and-access.md b/docs/official/internals/identity-and-access.md
new file mode 100644
index 000000000..f074df30c
--- /dev/null
+++ b/docs/official/internals/identity-and-access.md
@@ -0,0 +1,157 @@
+# Identity and access
+
+_Authorization over resources, addressing policy over agents, and the identity claims that connect them_
+
+Switch answers the following access questions in separate places, with separate data.
+
+- **Authorization** asks *may this user touch this resource*. It covers references, documents, packages and rooms.
+- **Addressing** asks *may this sender make this agent respond*. It covers `@name` mentions, aliases, roles, targeted messages and delegated tasks.
+
+Neither answer implies the other. A person entitled to read a room may still get nothing back when they name an agent in it, and an agent may answer someone who can't open a document that agent owns.
+
+## Entry points
+
+`switch-core` is [one process with several doors](index.md). Each accepts its own credential.
+
+| Entry point | What it accepts |
+| --- | --- |
+| Agent bridge API, `/agents/*` | Bearer agent API key. Registration is the exception: it presents a registration token, and the user that token identifies becomes the agent's owner |
+| Event stream, `/agents/{id}/events` | Bearer agent API key |
+| Agent operations | Bearer agent API key |
+| Gateway, `/gateway/*` | Session cookie carrying a JWT |
+| Gateway login, config, OIDC login and callback | Unauthenticated by nature — they're how you get a session |
+| `GET /health` | Public |
+| `GET /deeplink/session` | Public |
+| Platform ingress | The messaging platform's own credential, on the connection the collaboration bridge holds |
+
+The agent-facing surface is the HTTP API plus the SSE stream. A connector's local runtime presents Switch operations to an agent as MCP tools, but it reaches Switch over that same HTTP and SSE surface.
+
+## Unauthenticated prefixes
+
+The agent bridge skips its bearer-token check on the following prefixes: `/health`, `/.well-known`, `/oauth`, `/gateway` and `/deeplink`.
+
+**Note**
+
+`/gateway` is on that list because the Gateway authenticates its own requests with a session cookie, **not** because the Gateway is open. The bearer-token middleware steps aside so the cookie check can run.
+
+## Gateway sign-in
+
+The Gateway serves operators, through either a browser or Switch Console, over ordinary web session mechanics.
+
+- A successful login sets an HS256 JWT in a session cookie marked `httponly` and `samesite=lax`, expiring after 24 hours.
+- OIDC login is optional. When configured, the round trip uses a separate short-lived cookie, distinct from the session cookie it produces.
+- Every user carries a role. `admin` is a global bypass, not a bundle of grants — it short-circuits the check below rather than satisfying it.
+
+## The authorization chokepoint
+
+Every resource decision goes through one module. It is pure policy: no I/O, no database access, no queries. It takes a user and a resource and returns a verdict, so the answer to "who can delete this" lives in exactly one place and tests with plain values.
+
+**The subject of every decision is a user.** Not an agent, not a session, not a connection. Everything else resolves to a user before the check runs.
+
+The resource side is structural. Anything carrying an owner plus read and write visibility satisfies the policy — references, library documents, packages and rooms all qualify by having those fields, with no base class and no registration step.
+
+### Decision order
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ admin["<b>Is the principal an admin?</b>"]
+ owner["<b>Is the principal the owner?</b>"]
+ del["<b>Is the action delete?</b>"]
+ vis["<b>Does the action's visibility<br/>say public?</b>"]
+ allow["<b>Allow</b>"]
+ deny["<b>Deny</b>"]
+
+ admin -- yes --> allow
+ admin -- no --> owner
+ owner -- yes --> allow
+ owner -- no --> del
+ del -- yes --> deny
+ del -- no --> vis
+ vis -- yes --> allow
+ vis -- no --> deny
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class admin,owner,del,vis,allow,deny plain
+ linkStyle default stroke:#888888
+```
+
+`read` consults public read visibility; `write` consults public write visibility.
+
+The following properties of that ordering are load-bearing:
+
+- **`delete` is owner-or-admin only, and is never reachable through visibility.** No visibility setting lets a non-owner delete a resource. Making something world-writable is a decision about its contents, not about whether it continues to exist.
+- **Write-public implies read-public**, and the pairing is validated where visibility is set rather than assumed where it's checked. A resource can't end up writable by everyone and readable by nobody.
+
+The Gateway carries a matching room-access check mirroring the protocol layer's, so a human going through the dashboard and an agent going through the bridge are held to the same rule.
+
+### Agents inherit their owner
+
+**An agent inherits exactly its owner's permissions.** An agent-initiated request resolves to the agent's owner, and every check above then runs against that user. An agent is not a principal with its own grants.
+
+Widening what an agent can reach means widening what its owner can reach.
+
+The corollary is a diagnostic. An agent with no owner resolves to a principal that owns nothing: it passes no ownership check and clears no admin bypass, so it reaches public resources and only public resources. An ownerless agent that's blind to a library everyone else can see is behaving as designed.
+
+## Addressing policy
+
+An agent's addressing policy is a set of rules, evaluated against the sender and the room rather than against a resource. A rule scopes the following dimensions:
+
+- **`rooms`** — the room the message was sent in.
+- **`room_groups`** — the group that room belongs to. Moving a room between groups can change which agents answer in it.
+- **`users`** — matched when the sender is a human.
+- **`agents`** — matched when the sender is another agent.
+
+The following subjects are symbolic, resolving at evaluation time rather than naming anyone:
+
+- **`owner`** — the agent's owner, whoever that currently is.
+- **`owner_agents`** — any agent owned by that same person.
+
+Each dimension is `*` for any, a list for those named, or an empty list for none. A sender is exactly one kind, human or agent, so "people only" is a human list of `*` alongside an empty agent list.
+
+A rule admits an attempt when the room matches **and** the group matches **and** the sender matches on its own kind. Addressing is permitted when **any** rule admits it, so rules widen rather than narrow each other.
+
+### Precedence
+
+- **No rules at all means open.** Agents registered before addressing policies existed were deliberately left permissive.
+- **Once there's any rule, everything not admitted is denied.** Adding the first rule flips the agent from open to closed, a larger change than adding the second.
+- **A newly registered agent starts owner-only.** New agents don't inherit the permissive default.
+
+Policies are set from the Gateway by the agent's owner or an admin. They aren't agent-facing, so an agent can't widen its own.
+
+## Identity claims
+
+A **claim** links a platform account to a Switch user. Addressing rules name Switch users; a message from Slack arrives from a Slack account, and the claim connects the two.
+
+The relationship is deliberately many-to-many. An exclusive claim would let whoever claimed an account first lock everyone else out of it permanently, with no recovery that doesn't involve an operator.
+
+**An unclaimed platform account matches nobody** — not the owner, not a listed user, not `owner_agents`. As far as policy is concerned it is a non-user, not an unknown user.
+
+**Tip**
+
+A newly registered agent starts owner-only, and an owner-only agent can't recognize its own owner until that owner links their messaging account. The agent ignores the person who created it, the setup looks correct, and the missing piece is the claim.
+
+## Asymmetric refusal
+
+Refusal takes a different form per action, by design.
+
+- **A message** from a sender who isn't admitted is demoted to ordinary room chatter, and the agent posts one reply saying it can't act on it. The refusal is visible in the room rather than silent.
+- **Commands** are gated the same way. Naming the agent draws a reply; a room-wide command draws a quiet decline, so a room full of agents doesn't announce a refusal each.
+- **A targeted message** reports a per-target `not_permitted` status rather than failing the call. Addressing several agents at once doesn't fail because one declined.
+- **Delegating a task** raises an error instead. A task is a row somebody is expected to work, so a demotion would leave a delegation that looks accepted and never moves.
+
+Conversational refusals stay conversational and visible. Refusals that would otherwise create dangling state are raised as errors.
+
+## Event scoping
+
+Addressing decides what an agent may act on. Membership decides what it is shown.
+
+An agent receives events only for rooms it belongs to, and **membership is checked per subscribe** rather than once when the connection opens.
+
+Cross-room resource access is validated server-side. When an agent asks to load documents, the service checks each one is attached to the room the agent is asking from. That check runs behind the resource manager's request-and-response round trip through the room, so the caller can't skip it — it isn't a direct read the agent performs, it's a request a server-side participant services.
+
+## Next steps
+
+- [Rooms and resources](rooms-and-resources.md) — The resource library, ownership and visibility in practice, and how a room gets built
+
+- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/index.md b/docs/official/internals/index.md
new file mode 100644
index 000000000..2dfc97d5b
--- /dev/null
+++ b/docs/official/internals/index.md
@@ -0,0 +1,104 @@
+# How Switch is built
+
+_The components of Switch, what each one is responsible for, and how they connect_
+
+Switch is a service that puts people and AI agents in the same room, on top of a Matrix message bus. This section covers its components, the contracts between them, and the parts of the design that aren't obvious from the outside.
+
+Read it if you're writing an adapter for a new messaging app, connecting an agent that has no connector yet, or working on Switch itself.
+
+## Components
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ people["<b>People</b><br/>in Slack, Discord, Mattermost,<br/>Telegram or Microsoft Teams"]
+ agents["<b>Agents</b><br/>a connector runtime beside each one,<br/>speaking HTTP and SSE"]
+ operators["<b>Operators</b><br/>in a browser or Switch Console"]
+
+ subgraph core["<b>switch-core</b>"]
+ direction LR
+ collab["<b>Collaboration bridge</b><br/>an adapter per app<br/>puppets · threads · commands"]
+ agentbridge["<b>Agent bridge</b><br/>HTTP · SSE · the event buffer<br/>the operations registry"]
+ gateway["<b>Gateway</b><br/>the operator API"]
+ end
+
+ matrix["<b>Matrix homeserver</b><br/>the message bus — every participant is a client on it"]
+ store["<b>PostgreSQL</b><br/>rooms · agents · resources · identities · mappings"]
+
+ people --> collab
+ agents --> agentbridge
+ operators --> gateway
+ collab --> matrix
+ agentbridge --> matrix
+ gateway --> store
+ matrix --> store
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class people,agents,operators,collab,agentbridge,gateway,matrix,store plain
+ style core fill:none,stroke:#888888,stroke-width:1px
+ linkStyle default stroke:#888888
+```
+
+Each population reaches Switch through a component of its own. None of them addresses the others directly. Everything below the top row turns all of them into participants in the same Matrix room.
+
+| Component | Responsibility |
+| --- | --- |
+| **Collaboration bridge** | Relays between an external chat platform and a Matrix room. One adapter per platform. |
+| **Agent bridge** | The HTTP and SSE surface agents connect to. Owns registration, connections, the event buffer and the operations registry. |
+| **Gateway** | The operator API, serving a browser or Switch Console over a session cookie. |
+| **Matrix homeserver** | The message bus. Tuwunel, running beside `switch-core`. |
+| **PostgreSQL** | Switch's own state: rooms, agents, the resource library, identity mappings, message correlation. |
+
+`switch-core` is one service. The agent bridge is the root application, the Gateway is mounted underneath it, and `/health` sits on the root.
+
+## How agents connect
+
+The agent bridge speaks **HTTP and SSE**. HTTP for calls, one SSE stream for events. That is the whole of [the agent protocol](agent-protocol.md).
+
+Agents built on Claude Code, Codex or OpenCode use a **connector**, which starts a small runtime process beside the agent. The runtime:
+
+- exposes Switch operations to the agent as local MCP tools over stdio
+- translates each tool call into an HTTP request against the agent bridge
+- holds the SSE connection and pushes room events into the session
+
+The agent sees MCP tools. The thing talking to Switch is the runtime, over HTTP and SSE. A client written from scratch skips the runtime and calls the agent bridge directly. [Connectors and the runtime](connectors-and-runtime.md) covers what a connector ships and how the runtime works; [Standalone and Switch Console](standalone-and-console.md) covers the two ways an agent gets connected in the first place.
+
+## Matrix as the substrate
+
+Every room in Switch is a room on a Matrix homeserver. Nobody signs in to it and it isn't a user-facing feature.
+
+What Matrix supplies:
+
+- **Rooms and membership.** Who is in a room and who may post are questions Matrix already answers.
+- **Durable, replayable history.** A reconnecting client catches up from the homeserver.
+- **Symmetric participants.** A message from a person and a message from an agent are the same kind of event from the same kind of sender.
+
+Every participant has a real Matrix account: each agent, each system actor, and each person talking from a messaging app. A person in Slack is represented by a **puppet** account that posts on their behalf.
+
+The consequence is that addressing, membership, permissions and history are implemented once, against Matrix participants, rather than once per population. The cost lands in the collaboration bridge.
+
+## State
+
+| Store | Holds |
+| --- | --- |
+| PostgreSQL | Rooms and metadata, registered agents, the resource library, identity mappings, role leases, message correlation |
+| Matrix homeserver | Room events, membership, each client's sync position |
+| Switch Console | A local database on the machine it runs on, for sessions and local configuration |
+
+Switch Console's database is not a cache of the server's. Neither is evidence for what the other contains.
+
+Query logic lives in per-entity store modules. The models carry no queries.
+
+## Versions and contracts
+
+The repository declares a registry of artifact versions and wire-contract revisions. Each component states which revision of a contract it speaks and which it accepts, so a mismatch between a connector and a server is a checkable fact rather than an unexplained failure.
+
+## Next steps
+
+- [Life of a message](life-of-a-message.md) — One message from a Slack channel to an agent and back, hop by hop
+
+- [The Matrix substrate](matrix-substrate.md) — Participants as clients, sync and resume, and the custom events Switch layers on
+
+- [The collaboration bridge](collaboration-bridge.md) — The adapter contract, and what it takes to support a new messaging app
+
+- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/life-of-a-message.md b/docs/official/internals/life-of-a-message.md
new file mode 100644
index 000000000..dddcabd4f
--- /dev/null
+++ b/docs/official/internals/life-of-a-message.md
@@ -0,0 +1,81 @@
+# Life of a message
+
+_One message traced from a Slack channel to an agent and back, with the component responsible for each hop_
+
+A message posted in a Slack channel reaches an agent as an ordinary Matrix room event. The reply returns along the same path in reverse.
+
+## The path
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant P as Person in Slack
+ participant SA as Slack adapter
+ participant BC as Bridge core
+ participant MX as Matrix room
+ participant AC as Agent client
+ participant AG as Agent
+ P->>SA: message event, over the connection Switch dialed out
+ SA->>BC: normalized into the inbound model
+ BC->>MX: invite the puppet, wait for the join
+ Note over BC,MX: a client ignores events that predate its own join
+ BC->>MX: puppet posts the message
+ MX->>AC: event through sync
+ AC->>AC: addressed? name, alias, role, policy
+ AC->>AG: sequenced in the buffer, pushed over SSE
+ Note over AC,AG: delivery is not acting
+ AG->>MX: reply, through the agent bridge over HTTP
+ MX->>BC: bridge client sees the reply
+ BC->>SA: puppet senders skipped, correlation resolved
+ SA->>P: reply in the channel thread
+```
+
+1. **Slack pushes the message.** It arrives on the connection the adapter dialed out when the bridge started. No inbound port is involved.
+2. **The adapter normalizes it.** Platform formatting becomes the neutral inbound model: channel and channel type, sender id and name, content, message reference, optional thread root, attachments. Everything past this point is written against that model. See [the collaboration bridge](collaboration-bridge.md).
+3. **The bridge core prepares the puppet.** It maps the channel to its Matrix room, looks up or creates the sender's puppet account, invites it, and waits for the join to land.
+4. **The puppet posts the message.** It is now an ordinary event from an ordinary room member. See [the Matrix substrate](matrix-substrate.md).
+5. **The agent's Matrix client picks it up through sync.** Each client runs its own sync loop against the homeserver.
+6. **Addressing is decided.** By name, by an alias the agent holds in this room, or by a role it holds. The [addressing policy](identity-and-access.md) decides whether this sender may make this agent respond.
+7. **The event is buffered and streamed.** It is appended to the agent's sequenced buffer and pushed down the open SSE stream. Each frame carries its sequence number as the SSE id, so a reconnect resumes with `Last-Event-ID`. See [the agent protocol](agent-protocol.md).
+8. **The agent replies.** It posts into the same Matrix room through the agent bridge over HTTP. A connector-hosted agent calls its local runtime, which makes that request.
+9. **The bridge client sees the reply.** It is a member of the room, so the reply reaches it like any other event.
+10. **The bridge core routes it out.** Known puppet senders are skipped, and the correlation table resolves the external post to reply under.
+11. **The adapter posts it in the channel.** In the agent's name, in the right thread.
+
+## The join wait
+
+A Matrix client ignores events that predate its own join. The bridge core invites the puppet and waits for the join to land before sending, because a message sent in the gap is filtered out at the far end without raising anything.
+
+The same rule applies wherever Switch adds a participant that has to see what happens next. Room creation invites the bridge client before any agent for this reason.
+
+## Delivery is not acting
+
+A connection using the default filter is delivered every event in the rooms it covers, whether or not any of it names the agent. Step 6 decides whether the agent acts, not what reaches it.
+
+An agent that sets its filter to `addressed` narrows delivery as well, and stops seeing the conversation around it.
+
+## Loop prevention
+
+The outbound path skips any Matrix event whose sender is a known puppet. Without it, a message relayed in from Slack is relayed straight back out to Slack.
+
+## Thread correlation
+
+A durable table maps Matrix event ids to external post ids, written in both directions with a uniqueness constraint on each side, so either id resolves the other. It is what puts a reply in the right thread, and what makes a later edit or delete land on the right post.
+
+## Other platforms
+
+Nothing on the path is specific to Slack. Swap the adapter and it holds for Discord, Mattermost, Telegram and Microsoft Teams. Teams runs a self-hosted inbound HTTP listener; the others dial out.
+
+## Adding a platform or an agent
+
+| Change | What it takes |
+| --- | --- |
+| **A new messaging platform** | Implement the adapter contract: start and stop, send, update and delete, channel and identity operations, inbound and outbound translation. Declare the capability flags. No agent-side change. |
+| **A new agent** | Speak HTTP and SSE against the agent bridge: register, open the event stream, call operations. Nothing about the messaging platform reaches it. |
+
+## Next steps
+
+- [Identity and access](identity-and-access.md) — Who a request resolves to, what an agent inherits from its owner, and how addressing is decided
+
+- [Rooms and resources](rooms-and-resources.md) — Room creation in order, groups and links, and the resource library agents can attach and write
diff --git a/docs/official/internals/matrix-substrate.md b/docs/official/internals/matrix-substrate.md
new file mode 100644
index 000000000..b7e456f1b
--- /dev/null
+++ b/docs/official/internals/matrix-substrate.md
@@ -0,0 +1,119 @@
+# The Matrix substrate
+
+_How every participant becomes a Matrix client, how those clients sync and resume, and the events Switch layers on top_
+
+Every Switch room is a room on a Matrix homeserver. The homeserver is Tuwunel, running beside `switch-core`. Nobody signs in to it directly, and it is not a user-facing feature.
+
+## Every participant is a real account
+
+Each agent, each system actor, and each person talking from a messaging app has its own Matrix account on the homeserver and its own row in the `clients` table. There is no lightweight virtual-member concept.
+
+A person in Slack is represented by a **puppet** account that posts on their behalf. At the transport layer there is no human-versus-agent distinction, because everyone in the room is a Matrix client.
+
+Creating a client mints an id, derives a Matrix localpart, registers the account on the homeserver, and persists the row. The localpart takes one of the following shapes:
+
+```
+switch-<type>-<short id> a per-participant account
+switch-<type> a system actor, one per instance
+```
+
+## Client types
+
+A type decides what a client is for — which rooms it is invited to, what it does with what it sees. It does not change how the client talks.
+
+| Type | Role in a room |
+| --- | --- |
+| `agent` | A registered agent. One account per agent, joined to every room that agent belongs to. |
+| `user` | A person participating in a room. |
+| `bridge` | The collaboration bridge's own presence in a room. |
+| `resource_manager` | The participant that services resource requests sent into the room. |
+| `admin` | The account Switch speaks as in its own voice, such as admin-owned command output. |
+
+Room membership is tracked in `client_rooms`. Joining a room is an ordinary Matrix invitation, which managed clients accept automatically.
+
+## The sync loop
+
+Each client runs its own `sync_forever` loop against the homeserver with a 30-second timeout, inside a retry loop with exponential backoff. A homeserver blip costs a reconnect, not a dead participant.
+
+Callbacks are registered for the following: text messages, media, reactions, membership changes, invitations, and unknown events. Unknown events are how Switch's own custom types arrive, since the Matrix client library doesn't know them.
+
+## Resume, not re-login
+
+The client row carries the access token, the device id, and the last sync batch token. The batch token is written as sync progresses — throttled, so a busy room doesn't produce a write storm — and forced at login and on a clean stop.
+
+A restart is not a fresh start. The client restores its stored session, resumes the existing Matrix device instead of logging in and creating another one, and syncs from the batch token it last recorded.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant P as switch-core
+ participant C as Client
+ participant DB as clients row
+ participant HS as Homeserver
+ P->>C: process starts, construct client
+ C->>DB: read access token, device id, batch token
+ DB-->>C: stored session
+ C->>HS: restore session on the stored device
+ C->>HS: sync since the stored batch token
+ HS-->>C: everything recorded since that token
+ Note over C,HS: events predating the client's join are filtered out
+ C->>DB: persist the new batch token as sync progresses
+```
+
+Messages that arrived while the process was down are still delivered, because the homeserver held them.
+
+Resume covers the Matrix position only. The agent bridge's event buffer is a separate mechanism with its own sequence numbers, held in memory, so a connection's place in it does not survive a restart — the bridge reports a gap to the reader instead of pretending the stream is complete.
+
+## Pre-join events are filtered
+
+**A client ignores events that predate its own join.** Inviting a client to a room does nothing on its own. Until the join lands, anything posted in that room is, for that client, something that happened before it existed.
+
+Wherever Switch needs a client to see what happens next, it waits for the join rather than trusting the invitation:
+
+- Room creation invites the bridge client **first**, before any agent. A message sent before the bridge joins is a pre-join event for the bridge and never reaches the external channel.
+- The collaboration bridge creates or looks up a puppet on an inbound message, invites it, waits for the join to land, and only then sends.
+
+**Note**
+
+Sending before a join lands does not raise an error. The event is filtered and the message is lost silently. If you add a participant and immediately do something you expect it to observe, wait for the join. This comes up again in [the collaboration bridge](collaboration-bridge.md).
+
+## The `com.switch.*` events
+
+Ordinary conversation is ordinary Matrix: text messages, media, reactions. Everything Switch adds is a custom event type under the `com.switch.` namespace, delivered through the unknown-event callback.
+
+| Event type | Carries |
+| --- | --- |
+| `com.switch.command` | A room command, such as the bridged form of a `!` command typed in a messaging app. |
+| `com.switch.agent.runtime_state` | What a live agent session is doing, and what it can be told to do. |
+| `com.switch.permission.request`, `com.switch.permission.response` | A permission round trip in the room. |
+| `com.switch.resource.*` | The resource manager's request-and-response pairs: loading documents and references, and creating, updating or deleting room-scoped documents. |
+| `com.switch.task.*` | The task protocol. Present in the wire format, not yet in use — don't build against it. |
+
+Resource operations are round trips through a server-side participant rather than direct writes, so the check that a document belongs to the room asking for it happens on the server.
+
+### Content markers
+
+These are not event types. They are flags carried on otherwise ordinary events:
+
+- `com.switch.attachment_group`
+- `com.switch.admin`
+- `com.switch.auto_reply`
+
+## Multi-file attachments
+
+Matrix has no native multi-attachment message: a media event carries one file. Messaging platforms allow several files in one post.
+
+Switch sends one media event per file. Every event in the batch carries a shared `com.switch.attachment_group` marker with a group id, the file's index, and the total. The receiving side coalesces the group back into one logical message.
+
+Outbound, the relay buffers a group and flushes it as a single post, so an external channel gets one message with several files rather than a burst. Incomplete groups have their own flush path, so a group missing a file yields the files that did arrive instead of waiting forever.
+
+**Tip**
+
+If you're writing an adapter, treat the group marker as the unit of work. Handling media events one at a time will function and will look wrong in every channel it touches.
+
+## Next steps
+
+- [The collaboration bridge](collaboration-bridge.md) — Puppets, threads and commands — and why the join wait matters there most
+
+- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/rooms-and-resources.md b/docs/official/internals/rooms-and-resources.md
new file mode 100644
index 000000000..4b902750c
--- /dev/null
+++ b/docs/official/internals/rooms-and-resources.md
@@ -0,0 +1,176 @@
+# Rooms and resources
+
+_The developer's view of the resource model and the room lifecycle — what's scoped where, and the ordering that matters_
+
+A Switch room carries metadata, a position in a group tree, links to other rooms, roles its members can hold, and attached resources drawn from a library that exists outside any one room. This page covers where each of those is scoped, who owns it, what enforces what, and the order operations run in.
+
+For what a reference or a document is *for*, see [Share context](../using/shared-context.md).
+
+**Note**
+
+**Terminology hazard.** In the repository, "artifacts" means release versions and wire contracts — the declared registry of what each component ships and which contract revisions it speaks. It has nothing to do with the attachable resource library. The Gateway calls that library **Resources**, and so does this page.
+
+## The resource model
+
+Everything attachable is either **library-wide** — it exists independent of any room and can attach to many — or **room-scoped** — it's part of one room and is deleted with it.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ pkg["<b>Package</b><br/>a named bundle"]
+ ref["<b>Reference</b><br/>type · address · instructions"]
+ libdoc["<b>Library document</b><br/>attachable to many rooms"]
+ room["<b>Room</b>"]
+ rsdoc["<b>Room-scoped document</b><br/>lives and dies with the room"]
+ role["<b>Room role</b><br/>and per-room aliases"]
+ group["<b>Room group</b><br/>at most one per room"]
+ other["<b>Another room</b>"]
+
+ pkg -->|contains| ref
+ pkg -->|contains| libdoc
+ ref -->|attaches to| room
+ libdoc -->|attaches to| room
+ pkg -->|attaches to| room
+ room -->|scopes| rsdoc
+ room -->|defines| role
+ room -->|sits in| group
+ room -->|links to| other
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class pkg,ref,libdoc,room,rsdoc,role,group,other plain
+ linkStyle default stroke:#888888
+```
+
+| Concept | Scope | Ownership | Attaches to |
+|---|---|---|---|
+| **Reference** | Library-wide | Owner required, with independent read and write visibility | Rooms and packages |
+| **Library document** | Library-wide | Owner, with read and write visibility | Rooms and packages |
+| **Room-scoped document** | One room, deleted with it | Owner, plus the agent that created it | Its own room only |
+| **Package** | Library-wide bundle | Owner required, with visibility | Rooms; contains references and documents |
+| **Room group** | A tree, through an optional parent | No visibility model | A room belongs to at most one group |
+| **Room link** | Directed, with a free-text label | — | One room to another; a room can't link to itself |
+| **Room role** | Per room, name unique within it | — | Assumable by any room member |
+| **Role lease** | The current holder | — | One lease per agent, heartbeat-based |
+| **Alias** | Per room and agent | — | A short handle that addresses the agent in that room |
+
+### Reference types
+
+A reference records a type, an address and instructions. The types are a closed set: Google Drive, Confluence, GitHub, Jira. There's no open type field for a new integration.
+
+### Room-scoped documents
+
+Room-scoped documents are the agent-writable kind. A room-scoped document is deleted with its room, records the agent that created it, and has a name unique within that room.
+
+An agent can change or delete only a document it created. Authorship is enforced, not advisory.
+
+Create, update and delete are not direct database writes from the caller's side. Each is a request-and-response round trip over the message bus, serviced by the resource manager client, so the check that the document belongs to the room being asked from runs server-side rather than being trusted to the caller.
+
+### Room groups
+
+A group is a tree node with an optional parent. A room belongs to at most one group.
+
+Deleting a group doesn't delete rooms. Its rooms become ungrouped, and its child groups are moved up to sit under whatever the deleted group sat under.
+
+**Warning**
+
+Groups scope addressing rules, so **moving a room between groups can change which agents will answer in it**. A rule that admitted a sender in the old group may not admit them in the new one, and a responsive agent can go quiet with nothing else changed. Treat a group move as a permissions change.
+
+### Role leases
+
+A lease is keyed to the agent and is room-agnostic: an agent holds at most one lease globally, whatever room the role lives in.
+
+Leases are heartbeat-based. A stale lease is logically free, and no reaper process sweeps it up, so the stored row alone never tells you a lease is dead — code that reads one has to check freshness itself.
+
+## Gateway and agent surfaces
+
+Almost everything here is reachable from either side: from the Gateway with a cookie session, as a human operator, and as an agent operation invoked over HTTP. References, library documents, room-scoped documents, room groups, room links and roles all have both, backed by the same operations registry.
+
+Packages are the exception. **Creating a package and editing its contents are Gateway-only.** An agent can attach an existing package to a room it's creating; it can't assemble one or change what's inside.
+
+The ecosystem graph and the room-link graph are Gateway-only aggregations built for the dashboard.
+
+## Creating a room, in order
+
+Room creation touches PostgreSQL, the Matrix homeserver and an external chat platform. The order is deliberate, and some of it exists to prevent specific bugs.
+
+### Validate everything first
+
+The attachments and the group id are validated before anything is provisioned, so a request naming a reference that doesn't exist fails while it's still free to fail — no orphaned Matrix room, no stray external channel to clean up.
+
+### Resolve the participants
+
+The named agents are resolved, along with which of them should receive join events in this room.
+
+### Resolve the bridge
+
+The room gets a named bridge, or no bridge at all if it's internal-only, or the instance default. A default bridge that's configured but not running **raises** here rather than quietly producing a room with no route out to a chat platform.
+
+### Settle the external channel
+
+If the room is adopting an existing channel and the caller didn't state its type, the adapter is asked what type it is. If a new channel is being created, the operator's channel-creation switch is checked first, and then the adapter creates it.
+
+### Mark the channel as provisioning
+
+Creating a channel makes the bot auto-join it, and that join arrives back as an inbound event before the room mapping is committed. Without the mark, the inbound handler doesn't see the uncommitted mapping, concludes the channel is unknown, and creates a second Switch room for the same channel.
+
+### Create the Matrix room
+
+The room on the homeserver is created. Everything after this point takes membership in it.
+
+### Persist in one transaction
+
+The room row, its group, its agents, its roles and its seeded aliases are written and committed together, so the durable state either exists completely or not at all.
+
+### Register the mapping, and always clear the mark
+
+The channel-to-room mapping is registered and the provisioning mark is cleared in a `finally`, so a failure above doesn't leave the channel permanently marked as provisioning.
+
+### Invite the bridge client before any agent
+
+The bridge client is invited ahead of every agent, because a Matrix client ignores events that predate its own join. A message posted before the bridge joins is filtered as a pre-join event and never reaches the external channel — the room looks alive from inside Switch and silent from Slack.
+
+### Populate the external channel
+
+The agents and users are added on the platform side, so the channel's membership matches the room's.
+
+### Invite the remaining participants
+
+The agent clients and the system clients are invited together, and then the membership rows are persisted and committed. Membership is ordinary Matrix invitation, which managed clients auto-accept.
+
+### Attach references, packages and links
+
+Attachment failures are collected per item rather than aborting the operation, so a bad reference costs you that attachment and not the room.
+
+Rooms can also be created from a YAML definition through the Gateway, which runs this sequence rather than a parallel one.
+
+## Room lifecycle
+
+- **Update** changes metadata, instructions, group membership and the agent list.
+- **Delete** removes the room and everything scoped to it, including its room-scoped documents.
+- **Archive** sets a reversible metadata-only flag. The Matrix room, the mapping and the membership stay as they were, and restoring the room brings it back without rerunning the provisioning sequence.
+- **Membership changes** add or remove agents and users after the fact, on the same invitation model as creation.
+- **Moving a room to a different bridge** re-points it at another external chat connection.
+
+## The durable model
+
+Switch's own state lives in PostgreSQL beside `switch-core`. The tables that carry rooms and resources:
+
+- `rooms` — the Matrix room plus Switch metadata: bridge, external channel, channel type, instructions, group, owner, visibility, archive flag
+- `room_groups` and `room_links` — the tree, and the directed graph over it
+- `room_agents` — which agents are in a room, carrying the alias and the join-event flag
+- `room_roles` and `role_leases` — roles defined per room, and who currently holds one
+- `references`, `documents`, `packages` and their association tables — the library and what it's attached to
+- `agents` — name, description, integration profile, owner, optional parent agent for subagents, addressing policy
+- `clients` and `client_rooms` — one Matrix account per participant, with its sync state, and the rooms it's in
+- `collaboration_bridges` — a configured external chat connection; at most one is the default
+- `bridge_message_map` — the Matrix-to-external correlation, written in both directions
+- `external_users` and `external_user_claims` — platform identity to puppet client, and the claims linking a platform account to a Switch user
+- `agent_sessions` and `agent_runtime_states` — reachability and transport-to-room binding, and what a live session is doing
+
+Query logic lives in per-entity store modules. The model classes carry no queries. Schema changes are managed with Alembic.
+
+## Next steps
+
+- [Identity and access](identity-and-access.md) — Ownership, what an agent inherits from its owner, and who's allowed to make it respond
+
+- [Share context](../using/shared-context.md) — What references and documents are for, from a user's point of view
diff --git a/docs/official/internals/standalone-and-console.md b/docs/official/internals/standalone-and-console.md
new file mode 100644
index 000000000..15dd25a50
--- /dev/null
+++ b/docs/official/internals/standalone-and-console.md
@@ -0,0 +1,162 @@
+# Standalone and Switch Console
+
+_The two ways an agent gets connected: register it yourself, or let Switch Console do it_
+
+An agent reaches Switch either **standalone** or through **Switch Console**. Both use the same wire protocol, the same credential file shape and path, the same environment variable names, and the same runtime package.
+
+What differs is who registers the agent, who opens the connection, who surfaces events into the session, and whether anything starts a session on demand.
+
+## What differs
+
+| | Standalone | Switch Console |
+| --- | --- | --- |
+| **Registration** | A registration token you mint, then `POST /agents/register-known` | Console registers with your signed-in session |
+| **Who opens the connection** | The runtime opens its own | Console opens it first and hands the session `SWITCH_CONNECTION_ID` to borrow |
+| **Who surfaces events** | The runtime, as MCP notifications into the session | Console injects them into the session pane, with the runtime silenced |
+| **Sessions started on demand** | No. Nothing is watching | Yes. A watcher spawns a session when an agent is addressed with none live |
+
+Everything else — the credential file, the environment variable names, the runtime package, the protocol on the wire — is the same in both.
+
+## Standalone
+
+### Confirm the bridge base URL
+
+`GET /health` is public and is the correct probe for "is this the agent bridge".
+
+**The bridge base URL is usually not the Gateway URL.** A 401 from a probe means right host, wrong path: you reached the server but not the agent bridge.
+
+### Register the agent
+
+Mint a registration token from the Gateway. The user it identifies becomes the agent's owner, and an agent inherits exactly its owner's permissions.
+
+Present the token as the bearer credential on the registration call:
+
+```
+POST /agents/register-known
+Authorization: Bearer …
+Content-Type: application/json
+
+{"agent_type": "…", "name": "…", "description": "…", "options": {…}}
+→ 200 {"id": "…", "api_key": "…"}
+```
+
+- **The API key is returned once.** Write it down in the same step that receives it.
+- Agent names match `^[a-z0-9][a-z0-9._-]*$`.
+- Registering a name that already exists is a 409 unless the caller asks to overwrite. An overwrite rotates the key, so anything holding the old one stops working.
+
+`POST /agents` is the lower-level route. It takes a full integration profile instead of a known agent type, and is what you use for a host that isn't one of the built-in types.
+
+### Write the credential file
+
+Write `.switch/agents/` plus the agent name and `.json` into the directory the session will run from:
+
+```json
+{"env": {"SWITCH_API_ENDPOINT": "…", "SWITCH_API_TOKEN": "…", "SWITCH_AGENT_ID": "…"}}
+```
+
+The file is mode 600, alongside a `.gitignore` containing `*`. [Connectors and the runtime](connectors-and-runtime.md) covers how the runtime resolves identity from it.
+
+### Run the host
+
+Start the agent host **from that directory**. The runtime reads the credential file from its working directory, so the directory is the identity.
+
+## Switch Console
+
+Console does the same steps without a token, and keeps the connection for itself.
+
+- **Registration** uses your signed-in session rather than a registration token.
+- **The credential file** is the same file, in the same place, with the same shape.
+- **For Claude Code** it also writes a host settings file carrying the endpoint and the agent id — deliberately **not** the token, which stays in the credential file alone.
+- **The connection** is opened by Console, before the host launches. Console passes `SWITCH_CONNECTION_ID` into the host's environment and the runtime borrows that connection instead of opening one.
+- **Event surfacing** is Console's. It sets `SWITCH_CHANNEL_DISABLE_POLL` so the runtime doesn't also surface events, and injects them into the session pane itself.
+
+### The connection id is derived, not random
+
+Console derives the connection id from the session id rather than generating a fresh one.
+
+A pane reads `SWITCH_CONNECTION_ID` once, at startup, and holds that value for the life of the session. Randomize the id and a Console restart produces a new one, stranding every pane still pointing at the old connection. Deriving it from the session id means the restarted supervisor lands on the same connection the pane is already using.
+
+### Starting sessions on demand
+
+A watcher inside Console follows room activity for the agents it manages and starts a session when an addressed agent has no live one. That is the behavior standalone has no equivalent for. [Switch Console](switch-console.md) covers the watcher, the sidecar, and Console's own local state.
+
+**Note**
+
+The host starts the runtime in both setups. Console never spawns it directly — Console's job is to put the environment variables in place and then launch the host.
+
+## Startup sequences
+
+### Standalone startup
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant O as Operator
+ participant G as Gateway
+ participant B as Agent bridge
+ participant H as Agent host
+ participant R as Switch runtime
+ O->>G: mint a registration token
+ G-->>O: token
+ O->>B: POST /agents/register-known
+ B-->>O: agent id and API key
+ O->>O: write the credential file into the working directory
+ O->>H: run the host from that directory
+ H->>R: spawn the runtime as a stdio MCP server
+ R->>R: read the credential file
+ R->>B: open the stream with its own connection id
+ R->>B: claim the room
+ Note over R,B: The runtime owns the connection and surfaces events itself
+```
+
+### Console startup
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant C as Switch Console
+ participant B as Agent bridge
+ participant H as Agent host
+ participant R as Switch runtime
+ participant P as Session pane
+ C->>B: register with the signed-in session
+ B-->>C: agent id and API key
+ C->>C: write the credential file, and host settings for Claude Code
+ C->>B: open the stream with a connection id derived from the session id
+ C->>H: launch the host with SWITCH_CONNECTION_ID in the environment
+ H->>R: spawn the runtime as a stdio MCP server
+ R->>B: borrow the connection instead of opening one
+ R->>B: claim the room
+ B-->>C: room events on the stream Console holds
+ C->>P: inject the event into the session pane
+ Note over C,R: Console owns the connection and the runtime's own surfacing is off
+```
+
+## Environment variables
+
+| Variable | Meaning | Who sets it |
+| --- | --- | --- |
+| `SWITCH_API_ENDPOINT` | Agent bridge base URL — scheme and host, no path | Either, usually via the credential file |
+| `SWITCH_API_TOKEN` | The agent API key | Either, usually via the credential file |
+| `SWITCH_AGENT_ID` | The agent id | Either, usually via the credential file |
+| `SWITCH_CONNECTION_ID` | A supervisor's connection to **borrow** rather than opening one | Console only |
+| `SWITCH_CHANNEL_DISABLE_POLL` | Suppresses the runtime's own notification surfacing | Console only |
+
+**Note**
+
+**Setting the endpoint, the token and the agent id in the environment silently beats the credential file.** The runtime binds to what the environment says and never reads the file. A stale export in a shell profile is enough to run a session as the wrong agent, or against the wrong server, with nothing in the output saying so.
+
+## What standalone doesn't get
+
+- **No session spawning on demand.** Nothing is watching for an addressed agent with no live session, so the session has to already be running.
+- **No per-agent model or instruction overrides.** The host runs with whatever it is configured with.
+- **Identity is per working directory, not per machine.** The credential file is read from where the host was started, so the same machine can run different agents from different directories, and the wrong directory is a different agent.
+- **On most hosts the session is pull-based.** The runtime still receives events and still holds the stream, but nothing surfaces them into the session, so the agent sees them when it next reads context. Claude Code is the exception, and only when it authenticates through Anthropic and the session is launched with the development-channels flag. [Connectors and the runtime](connectors-and-runtime.md) covers what that changes, including the agent type you must register.
+
+## Next steps
+
+- [Switch Console](switch-console.md) — The desktop app that starts sessions on demand and holds their local state
+
+- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
diff --git a/docs/official/internals/switch-console.md b/docs/official/internals/switch-console.md
new file mode 100644
index 000000000..15b7c5e2a
--- /dev/null
+++ b/docs/official/internals/switch-console.md
@@ -0,0 +1,136 @@
+# Switch Console and the agent runtime
+
+_The desktop app that starts agent sessions on demand, holds their local state, and reports what they can be told to do_
+
+Switch Console is the desktop app that runs agent sessions on the machine those agents live on. It watches for room activity addressed to an agent it manages, and starts a session when that agent has no live one. That is what lets a mention in Slack reach a working agent with nobody having opened Console first.
+
+Nothing on the server does this. `switch-core` knows a message arrived and which agent it addressed, but a session is a process on a machine belonging to someone else and no server reaches across the network to start one.
+
+Console is an Electron app, developed in a monorepo alongside the rest of Switch. It is a fork; attribution for what it forked is in its repository.
+
+## Process shape
+
+| Part | Holds |
+| --- | --- |
+| **Main** | App lifecycle, the RPC controllers the UI calls into, the domain services behind them, the local database, terminal orchestration, updates |
+| **Preload** | A context bridge exposing a narrow, explicit API to the renderer |
+| **Renderer** | The React UI |
+| **Shared** | The agent provider registry and the types both sides agree on |
+| **Sidecar** | A headless on-host process, not an Electron one |
+
+The sidecar exists because Console is a window on a laptop and laptops close. Work that has to outlive the app runs in a process on the host that doesn't depend on Electron being alive.
+
+## Its own database
+
+Console keeps a local SQLite database on the machine it runs on. It is not a cache of the server's PostgreSQL and not a subset of it.
+
+Console's store holds sessions, local configuration, provider settings and the session-to-room binding. The server's holds rooms, agents, the resource library, identity mappings and runtime state.
+
+**Note**
+
+Neither database is evidence for what the other contains. Both have a notion of a room and a notion of an agent, and they don't mean the same thing by either — Console's is scoped to what this installation manages on this machine, the server's to the whole deployment. A room Console has never heard of is a normal room.
+
+## Starting a session on demand
+
+A watcher inside Console follows room activity for the agents it manages. A message that addresses an agent with no live session starts one.
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
+sequenceDiagram
+ autonumber
+ participant P as Person in Slack
+ participant S as switch-core
+ participant C as Console watcher
+ participant V as Agent provider
+ participant R as Session runtime
+ P->>S: mentions the agent in a channel
+ S->>S: no live session for that agent in that room
+ C->>S: notices the room activity
+ C->>V: start a session
+ V->>R: session comes up
+ R->>S: connects to the agent bridge, claims the room
+ Note over C,R: Nobody opened Console or started this session by hand
+ S->>R: delivers the addressed message
+ R->>S: agent answers into the room
+ S->>P: reply reaches Slack
+```
+
+The session's runtime is the connector process that runs beside the agent and speaks HTTP and SSE to the agent bridge. It holds the event stream and claims the room the message arrived in.
+
+### A separate implementation per host
+
+The sidecar carries its own implementation of on-demand start for remote hosts. Local and remote are independent implementations of one behavior.
+
+Fixing on-demand start in Console does not fix it on a remote host. A difference in behavior between a local agent and a hosted one is a plausible symptom of the pair drifting apart, so treat a change to either as an open question about the other.
+
+An agent that didn't answer is usually a question about the machine. The server did its part when the message was addressed. What happens next needs a Console or a sidecar alive beside the agent, configured to start sessions for it.
+
+## Binding a session to a room
+
+In Console's local model, a session's room is a row keyed by the session, cascading on delete. Remove the session and the binding goes with it. A session is associated with at most one room at a time.
+
+**Info**
+
+This is Console's storage model, not the room model the rest of Switch presents. The user-facing documentation describes a session as *attending* a room and able to leave it for another. Both are accurate about their own layer: a single current room in Console's table is what attending one room at a time looks like from the desktop app's side.
+
+## The agent provider registry
+
+The shared layer holds a registry of agent providers. A provider entry records how to launch a given coding agent and what that agent can be asked to do once it is live.
+
+The registry sits in shared rather than in main because the renderer needs the same facts to decide what to offer that main needs to drive a session. Split them and the UI offers a control the runtime can't honor.
+
+## Injecting a prompt
+
+Some providers expose an API for starting a session but none for handing a running session a new prompt. Once the provider's terminal UI is up, the only input it accepts is keystrokes. Console types the prompt in.
+
+- **Locally** — Console writes into the session's pseudo terminal.
+- **On a remote host** — Console writes through a terminal multiplexer, which is what keeps the session addressable after Console disconnects.
+
+A session that is still starting has no sink ready for keystrokes. When the sink isn't ready the caller defers the prompt instead of writing it, so the text can't land in a shell prompt or vanish mid-redraw.
+
+## Managed and external servers
+
+Console talks to a Switch server it manages itself or to one it doesn't.
+
+| Mode | What it means |
+| --- | --- |
+| **Managed** | Console owns the server's lifecycle. Local-server mode ships a pinned `switch-core` build, so the app and the server it starts are a matched pair rather than whatever is installed. |
+| **External** | Console connects to a server that already exists and somebody else runs. Console is a client and nothing more. |
+
+Some features are offered only in the managed case, because they need a server Console can reason about.
+
+## The inline pane
+
+When the server is managed and the room's messaging platform supports embedding, Console renders the room's conversation inside the app. Otherwise it falls back to a deeplink that opens the conversation in the platform's own client.
+
+Live embeds are capped. Past the ceiling, further rooms fall back to the deeplink — each live embed is a real client, and an unbounded number of them is an unbounded number of connections held open by a desktop app.
+
+## Reporting runtime state back
+
+Console posts its sessions' runtime state to the server. The server records what each live session is doing and what it can currently be told to do: whether it can be reset, compacted or interrupted.
+
+That is what room commands read. When somebody runs a command against an agent from Slack, the server checks reported state rather than guessing, and declines a command the session can't honor.
+
+Freshness is bounded by Console's ability to report. A session whose Console has gone away stops updating, and the server's picture of it is a last-known one.
+
+## Deeplinks
+
+Console registers a custom URL scheme, so a link opens a specific room or session directly in the app.
+
+Many messaging platforms linkify only schemes they recognize, and a raw custom scheme arrives as unclickable text. Switch also serves a public HTTP redirect that resolves to the same destination: the platform linkifies the HTTP address, and the redirect hands off to the custom scheme.
+
+## On a remote host
+
+The remote lifecycle is documented in full on [Onboard a remote host](../deploy/host-remotely.md). Restated here, unchanged:
+
+- A host reboot stops both the server and the agent listener on it.
+- Nothing declares a restart policy and nothing registers a service unit.
+- Launching Console again is what brings the agent back.
+
+Your own machine closing is fine — that is what the sidecar is for. The host restarting is not, and nothing in the product today makes it self-healing.
+
+## Next steps
+
+- [The agent protocol](agent-protocol.md) — Registration, connections, the event stream, and the operations registry
+
+- [Onboard a remote host](../deploy/host-remotely.md) — Run a Switch server or an agent on a machine other than your own
diff --git a/docs/official/resources/glossary.md b/docs/official/resources/glossary.md
new file mode 100644
index 000000000..72e0ca826
--- /dev/null
+++ b/docs/official/resources/glossary.md
@@ -0,0 +1,161 @@
+# Glossary
+
+_Switch terms and what they mean_
+
+Switch borrows several words your messaging app already uses, and means something
+narrower by most of them. This page is the one definition of each.
+
+## Agent
+
+An agent is an AI assistant somebody set up and invited into a room. It's
+registered once against the [server](#server), not created inside a room, so the
+same agent can be invited into as many rooms as it's needed in.
+
+An agent stays a member of a room whether or not anyone is running it. Presence in
+the room isn't evidence that anything is listening — what answers is a
+[session](#session).
+
+## Agent provider
+
+An agent provider is a tool that runs agents and that Switch can start for you:
+Claude Code, Codex, or OpenCode. It's the tool that runs the agent,
+not the model behind it — which model an agent uses is that agent's own
+configuration.
+
+Switch reaches a provider through a [connector](#connector) installed into it. See
+[Set up agent providers](../getting-started/set-up-agent-providers.md).
+
+## Alias
+
+An alias is a shorter name for an agent inside one room. It isn't a rename — the
+agent keeps its registered name everywhere else, other rooms are unaffected, and
+both names work as addresses in the room where you set it. See
+[Meet your team](../using/rooms-and-agents.md).
+
+## Connection
+
+A connection joins one Switch [server](#server) to one messaging platform. It's
+what makes a channel in the messaging app your team already uses also a
+[room](#room): messages cross in both directions, and people added to the channel
+are picked up as members of the room.
+
+You'll also see it called a bridge, and a room described as bridged to a channel.
+Same thing. See
+[How connections work](../deploy/messaging-apps/how-connections-work.md).
+
+## Connector
+
+The connector is the piece Switch installs into an [agent provider](#agent-provider)
+so that provider can appear in a room. Without it, the tool runs perfectly well on
+your machine and never appears in one.
+
+The connector lives in the provider's own configuration rather than in Switch
+Console, so it can already be installed on a machine where you've only just
+installed the Console. See
+[Install Switch Console](../getting-started/install-switch-console.md).
+
+## Reference
+
+A reference is a shared resource the room points at, with its own type,
+description, and instructions for using it. Use a reference for something the room
+needs to reach, and a [room document](#room-document) for what the room knows.
+
+A reference is registered once against your server and attached to as many rooms as
+you want, so you maintain it in one place. See
+[Share context](../using/shared-context.md).
+
+## Role
+
+A role is an address with a brief attached. Whoever holds it answers to it, and the
+brief tells them how the room expects that job to be done — so the room keeps
+working when the agent behind the job changes. Addressing a role reaches its
+current holder, which means you can ask the reviewer for a review without knowing
+which agent is reviewing this week.
+
+**A role changes how an agent works, not what it is allowed to do.** What an agent
+may reach comes from the person who owns it, and taking a role doesn't widen it.
+
+Any agent in the room can take a role, and a role belongs to a single room. A shared
+role can be held by more than one participant at once. An exclusive role is a lease —
+one holder at a time, held for as long as that holder's session is running. The lease is
+released a few seconds after the session stops, so a role can't be left locked by an
+agent that has gone away. A participant holds one role at a time,
+and that limit spans rooms, so a role taken in another room blocks a new one here.
+
+Held isn't the same as reachable. A lease follows its holder, so a session that moves
+to another room keeps the role it took in the first one — a role can have a live,
+healthy holder who is looking somewhere else entirely. See
+[Hand off work](../using/hand-off-work.md).
+
+## Room
+
+A room is where one piece of work lives — people and agents working on the same
+thing with the same context. It's [bridged](#connection) to a channel in the messaging
+app your team already uses, so joining the channel puts you in the room.
+
+A room isn't where a team lives. A server runs many of them, often one per feature
+or per bug.
+
+## Room document
+
+A room document is knowledge the room holds, written down. It carries content — the
+material itself — and instructions saying what an agent should do about it, along
+with a name, a description, and separate read and write visibility.
+
+Separating content from instructions is what makes a document work. A document with
+content and no instructions is a file nobody was told to open. See
+[Share context](../using/shared-context.md).
+
+## Room instructions
+
+Room instructions are what every agent reads when it joins a room. They hold the
+context for any agent added later by you or anyone else, so the room's conventions
+get stated once instead of repeated in chat and missed.
+
+Room instructions are per-room. A [reference](#reference) or a
+[room document](#room-document) is the better home for anything that has to say the
+same thing in more than one room. See
+[Meet Switch](../using/index.md).
+
+## Server
+
+A Switch server is where your rooms live and your agents connect. Every agent is
+registered once against a server, and the server holds the registry. See
+[Add a server](../getting-started/add-a-server.md).
+
+## Session
+
+A session is a running instance of an agent, started in an
+[agent provider](#agent-provider) on somebody's machine or on a server. It attends a
+room rather than belonging to one, and can leave for another. The agent is in the
+room; the session is what reads your message and replies.
+
+A session lasts as long as the program behind it keeps running and keeps checking
+in. Close the terminal, quit the agent, or let the machine sleep and it ends within
+seconds. A brief network drop doesn't end it — a session that reconnects quickly
+keeps its place in the room and any role it was holding.
+
+Address an agent with no session attending the room and you still get a reply, but
+Switch writes it on the agent's behalf to say the agent isn't available. See
+[Know whether it worked](../using/what-comes-back.md).
+
+## Switch Console
+
+Switch Console is the desktop app you install to set up and run Switch — adding
+your server, setting up agent providers, onboarding your agents, and starting
+sessions for them. See
+[Install Switch Console](../getting-started/install-switch-console.md).
+
+## Task
+
+A task is work handed to an agent that you expect back later, tracked through a
+lifecycle — accepted, worked, finalized — rather than answered in the channel and
+gone. A question is answered or it isn't and you can see which; a task has a life of
+its own, and part of that life happens where you can't see it. See
+[Hand off work](../using/hand-off-work.md).
+
+## Workspace
+
+Not a Switch term. In Slack a workspace is the whole organization, which is a much
+larger thing than anything Switch names — the unit of work in Switch is the
+[room](#room).
diff --git a/docs/official/resources/room-commands.md b/docs/official/resources/room-commands.md
new file mode 100644
index 000000000..66802f8b2
--- /dev/null
+++ b/docs/official/resources/room-commands.md
@@ -0,0 +1,221 @@
+# Room commands
+
+_Every command you can run in a Switch room, and when to reach for it_
+
+A command is a short instruction you type into the channel, and Switch acts on
+it directly. Use one to see what is in a room, bring an agent in, or take hold
+of an agent's session when it is stuck.
+
+## Run a command
+
+Start the message with `!`:
+
+```text
+!list-agents
+```
+
+Switch tests the first character of your message. A command mentioned part-way
+through a sentence is ordinary text, and nothing happens — no error, no hint.
+
+**Note**
+
+On Microsoft Teams, mention the Switch bot before the command unless your
+administrator has set up channel subscriptions — without either, Teams never
+delivers the message. Switch drops the mention before reading the `!`, so
+everything else on this page is typed the same way.
+
+**Warning**
+
+Backticks don't make a command inert. Switch reads the message text, so a
+command you paste into a room to show somebody runs like any other one — and
+some of the commands below clear an agent's context.
+
+---
+
+## See what's in a room
+
+Switch answers each of these itself. None of them takes an argument.
+
+```text
+# Every command Switch accepts, with a line describing each
+!help
+
+# The agents in this room
+!list-agents
+
+# Each agent's presence, and what it can do
+!agents-status
+
+# This room's roles, and who currently holds each
+!roles
+
+# The room's agent aliases
+!list-aliases
+
+# The room's internal documents
+!list-documents
+
+# The room's references
+!list-references
+
+# This room's URL
+!room-url
+
+# Every agent registered on the server
+!list-switch-agents
+```
+
+**Note**
+
+`!agents-status` is not `!status`. Slack reserves `/status` for itself, so the
+command could not be registered under that name.
+
+`!help` lists every command Switch has, including ones a particular agent can't
+carry out. Whether an agent supports `!interrupt`, `!compact` or `!reset` is
+decided when you run one, not when the list is printed.
+
+To find the name of an agent you want to invite, use **Your Agents** in Switch
+Console rather than `!list-switch-agents`.
+
+---
+
+## Bring an agent in, and give it a shorter name
+
+Switch answers these itself too.
+
+```text
+# Add an agent already registered on the server to this room
+!invite-agent @agent-name
+
+# Give that agent a short name to use in this room
+!set-alias @agent-name @alias
+
+# Clear an alias — the agent's own name also works here
+!remove-alias @alias
+```
+
+Each takes its arguments in the order shown, and each one is required.
+
+An alias belongs to the room that set it, so the same agent can go by one name
+here and another somewhere else. See
+[Create a room](../getting-started/create-a-room.md) for what an alias
+can be called and what Switch refuses.
+
+---
+
+## Take hold of an agent's session
+
+Your agents answer these in their own voice, rather than Switch answering for
+them. Wherever one takes an agent's name, a [role](glossary.md#role)
+works in its place, and the command acts on whichever session is holding that
+role.
+
+### !run-cmd
+
+Shows the terminal command that starts a session for an agent, connected to this
+room. Nothing starts until somebody runs what it prints.
+
+```text
+# The start command for one agent
+!run-cmd @agent-name
+
+# The start command for whichever session holds a role
+!run-cmd @role
+
+# Start the agent in a role, taken as it connects
+!run-cmd @agent-name @role
+
+# The start command for every agent in the room
+!run-cmd
+```
+
+| Argument | Required | Description |
+|---|---|---|
+| `@agent-name` | No | The agent to show the start command for. Leave it out and every agent in the room answers with its own |
+| `@role` | No | A role for that agent to take as it connects. Give it second — a role on its own is read as the agent |
+
+### !interrupt
+
+Stops what an agent is doing now.
+
+```text
+!interrupt @agent-name
+```
+
+### !compact
+
+Compacts an agent's session context.
+
+```text
+!compact @agent-name
+```
+
+### !reset
+
+Clears an agent's context and reconnects it.
+
+```text
+!reset @agent-name
+```
+
+### !agents-greet
+
+Asks the agents here to introduce themselves.
+
+```text
+!agents-greet
+```
+
+### Acting on every agent at once
+
+Interrupt, compact and reset each have a separate all-agents form:
+
+```text
+!interrupt-all-agents
+!compact-all-agents
+!reset-all-agents
+```
+
+`!reset @agent-name` requires a target. Send `!reset` with no name and it
+addresses nobody, so you cannot clear the whole room by mistyping — clearing
+everyone is a command you have to name. `!interrupt` and `!compact` work the
+same way.
+
+---
+
+## Slash commands
+
+**Note**
+
+Slash command availability varies by messaging app and by that app's
+configuration. `!` works in every app Switch bridges, which is why it's the
+form this page teaches.
+
+Some apps also publish Switch commands as native slash commands, so they
+autocomplete as you type:
+
+| Messaging app | Slash commands | How to type them |
+| --- | --- | --- |
+| Discord | All of them | `/invite-agent agent:agent-name` — each argument is its own named field |
+| Telegram | All of them, in the command menu | `/invite_agent @agent-name` — underscores, because a Telegram command can't contain a hyphen |
+| Slack | The ones your Slack app declares | `/invite-agent @agent-name`, reading the same as the `!` form |
+| Microsoft Teams | None | `!invite-agent @agent-name`, with the Switch bot mentioned first — see above |
+| Mattermost | None | `!invite-agent @agent-name` |
+
+Both prefixes reach the same command. A slash form is a convenience on the apps
+that offer one, never a second set of things to learn — so type `/` and take
+what your app offers you, rather than a spelling copied from anywhere else.
+
+---
+
+## Where the answer appears
+
+A command's result comes back as a reply in the same thread as the command, not
+at the top of the channel. Run one inside a thread and the answer stays there
+with it.
+
+## Next steps
+
+- [Work with your team](../using/mention-and-message.md) — Address an agent so it hears you, and practice the ways an address can miss
+
+- [Troubleshooting](troubleshooting.md) — What to check when an agent is silent, or a room isn't behaving
diff --git a/docs/official/resources/troubleshooting.md b/docs/official/resources/troubleshooting.md
new file mode 100644
index 000000000..eb7763616
--- /dev/null
+++ b/docs/official/resources/troubleshooting.md
@@ -0,0 +1,153 @@
+# Troubleshooting
+
+_Fast fixes for connecting, running an agent, and working in a room_
+
+**If an agent didn't answer you at all, check the address first.** A message with no `@`, or with the name misspelled, reaches nobody and produces no error and no hint. [Work with your team](../using/mention-and-message.md) covers what counts as an address.
+
+**Note**
+
+Switch Console has a version, and the Switch connector installed into each agent provider has its own. They look alike and move independently, so "update Switch" is ambiguous. Each fix names the one it means.
+
+## Connecting to a server
+
+### Which address is wrong?
+
+The form asks for two addresses — a Gateway URL and an API URL — and checks them separately, so either one can be wrong on its own. They often differ only in port or path, which is exactly what makes a guessed second value look like a working one.
+
+Both addresses come from the server administrator. Don't derive one from the other. Only a malformed address is flagged against its field. One that's well formed but wrong is accepted without complaint: a bad Gateway URL surfaces later as the server being unreachable, and a bad API URL isn't checked at all, so it surfaces when an agent can't reach the server. See [Add a server](../getting-started/add-a-server.md).
+
+### Server unreachable
+
+You get the same message whether the address is wrong or the server is genuinely down, so it sends people to investigate a server that turns out to be fine. Confirm both addresses first, and only then go looking at the server.
+
+**Note**
+
+Opening the Gateway in a browser doesn't prove Switch Console can reach it. The web app uses the browser's own connection, so it can look perfectly healthy while Switch Console times out.
+
+## Signing in and staying connected
+
+### Room names turned into identifiers
+
+You're signed out. Your agents are still listed, and so is any room a live session is in — by identifier rather than by name, which is usually the first thing you notice.
+
+Switch Console does say so, in several places at once: the server's status label reads **Signed out**, its Home page reads **Not signed in**, and the sidebar carries a `Sign in to <server> to see its rooms` bar with a **Sign in** link. **Your Rooms** is empty with the same line.
+
+Sign in again from the server. Whether that's a password or single sign-on depends on how your server was set up.
+
+### Every room stops responding
+
+Usually a network change the desktop client didn't follow — a VPN reconnect is one. Your sign-in stays valid and the Gateway still answers, so nothing else looks wrong.
+
+It recovers on its own, usually within about a minute of the network coming back. Restarting Switch Console fixes it now.
+
+## Getting an agent running
+
+### Switch Console says the session did not start
+
+Switch Console raises **Session did not start** when a session never reports itself. It's most likely waiting on a confirmation from the agent provider's own command line.
+
+**Open that session's terminal and answer what's on it.** That's the only route. The session never started, so there's no agent in the room to ask, and Switch Console can't answer the prompt on your behalf.
+
+If what's waiting there isn't a prompt but a message naming your agent as not found, see **Agent not found on launch** below instead.
+
+**Read the message as a guess, not a diagnosis.** It names two possible causes — a workspace-trust confirmation or a permissions one — and commits to neither, because Switch Console can see only that nothing came back. Folder trust is the common one, but a permissions prompt looks identical from Switch Console's side and needs the same thing from you.
+
+**Check the auto-trust setting if this keeps happening.** Select **Settings** at the bottom of the sidebar, then the **General** tab. **Auto-trust worktree directories** is on by default, and it writes the trust entry for Claude Code and Codex before the session launches.
+
+### Session starts with no Switch tools
+
+**The Switch connector was never installed into that agent provider.** The provider is installed and the agent is registered, and the session gives no error at any point: it starts normally, joins no room, and inviting the agent has no visible effect.
+
+The connector is reported separately from the provider, and the provider's row already says so — it reads **Switch setup required**. Select **Settings**, then **Agent providers**, then the provider — the **Switch setup** card there has an install control of its own. Install the connector, then start the session again. See [Set up agent providers](../getting-started/set-up-agent-providers.md).
+
+When a session starts and nothing appears in the room, check this before anything else, because it's a step people reasonably believe they already did. Switch Console's own add-agent flow won't offer a provider that has no connector, so an agent in this state was usually registered somewhere else.
+
+### Agent not found on launch
+
+The message names your agent as not found and then lists Claude Code's own built-in subagents. None of them are Switch agents, and nothing in the message mentions Switch.
+
+Switch Console starts a Claude Code agent as a Claude Code subagent of the same name, so Claude Code needs a matching definition at `.claude/agents/` in the agent's working directory, named for the registered Switch agent. An agent added through Switch Console's own add-agent flow has one. An agent registered any other way does not: the configure skill registering the main agent, the Gateway's **Register Agent** dialog, or an agent adopted from an identity file under `.switch/agents/` in the working directory.
+
+Create that file, with the `name` in its frontmatter matching the registered agent name character for character.
+
+Starting the same agent by hand succeeds, which is what makes this read as Switch Console being unreliable rather than as a missing file. The command a room posts when you address an unreachable agent doesn't name a subagent, so it works in the same directory seconds later.
+
+### Auto-create agent never wakes up
+
+Same cause as **Agent not found on launch**, with nothing at all to see. **Auto-create a session on notify** starts sessions through the same path, so every automatic wake fails the same way: the agent never answers, and no error surfaces anywhere you'd look. Turning the setting on to rouse an agent that won't wake therefore appears to do nothing.
+
+Create the definition file described in that entry.
+
+### Agent is connected but never answers
+
+**A session did start, and it can't hear the room.** It can be connected, healthy, holding all its context — and never receive a single mention, because nothing is pushing room events to it. Nothing looks wrong from either side; the agent simply never answers.
+
+Real-time delivery has to be switched on for the session, and Switch Console knows how: when an agent isn't reachable, the room posts the command that starts it correctly. **Start the agent with the command the room gives you** rather than one you've composed yourself. But that command starts a *new* session — if the one that can't hear you is full of your work, take its flags and resume instead. See [If the agent is already running](../getting-started/onboard-your-agents.md#if-the-agent-is-already-running).
+
+**Note**
+
+Real-time delivery depends on how the agent is authenticated. Claude Code signed in through Anthropic — subscription, Console, or API key — can receive pushed events. An installation running against a managed model service such as Vertex AI or Bedrock cannot, and is registered as an agent that reads the room when it next looks. That agent isn't broken: reach it with delegated work, or expect a reply when it next reads. Auto-create still works, but the session it starts reads the room the same way.
+
+### 404 from a package registry
+
+The Switch connector is most likely reaching for a package where it used to live, from before Switch became a public repository. It's the connector that's out of date rather than Switch Console, and the two update separately.
+
+Update Switch Console first, then select **Settings**, then **Agent providers**. **A row with a connector update waiting reads Connector update alongside Installed**, so **Installed** on its own isn't the thing to look for. The update is yours to accept and nothing moves until you take it — updating Switch Console leaves an old connector exactly where it was.
+
+## Talking to an agent in a room
+
+### An agent says a person isn't in the room
+
+They probably are. Switch identifies people by the account handle from your
+messaging app, and an agent matches the name you give it against that handle
+character for character. The short name everyone uses in the channel matches
+nothing — and the answer comes back as a fact about the room rather than as a
+name it couldn't find, so it reads as the person being absent.
+
+**Try the person's full first and last name with a dot between them.** That is
+the form most workspaces hand out, and it is rarely the name anyone uses in the
+channel.
+
+**If that fails, ask the agent to list the room's participants.** That settles
+whether they're there and hands you the exact string, because the names it
+gives back are the ones it matches on.
+
+Your messaging app is what makes this hard to guess, since it leads with the
+display name and shows the handle rarely or not at all. See
+[Meet your team](../using/rooms-and-agents.md).
+
+### An agent refuses your message
+
+An agent can be configured to take instructions only from certain people. Anyone else gets a visible refusal rather than silence, so this is a permission answer rather than a broken address, and re-sending won't help.
+
+Three replies come from this, and they're worded closely enough to run together:
+
+1. The agent takes instructions only from its owner, and it can't tell whether that's you, because this chat account isn't linked to a Switch user.
+2. You aren't permitted to direct messages to it in this room, because its operator restricted who can address it.
+3. An agent needs your input, but nobody in the room is linked to its owner, so the request reaches no one. Nothing was refused here — the agent simply can't get to you.
+
+**The first and third have the same fix: link your messaging account to your Switch user, in the server's Home section.** The second one isn't yours to fix — the agent's owner has to widen who may address it.
+
+That distinction is the point. Read the second as the first, and you'll link an account that was never the problem and be no further forward.
+
+**Note**
+
+A new agent takes instructions only from its owner unless someone changes that, and the account-linking prompt can be skipped when you add a server. Skip it, register an agent, address it — and your own new agent refuses you, at the moment you were trying to confirm it works.
+
+[Know whether it worked](../using/what-comes-back.md) explains the refusals; [Add a server](../getting-started/add-a-server.md) covers the linking prompt.
+
+## Handing off work
+
+### A task shows one line, then nothing
+
+The opening line is posted the moment the work is handed over, before anything checks whether the performer is running, so it appears even for an agent with no session behind it. Nothing takes it back afterwards: canceling posts nothing at all, and finishing posts the outcome as a separate message at the top of the channel, away from the line it belongs to.
+
+So a task that finished in a minute can still read as running, and a task nobody ever accepted looks exactly like one in progress.
+
+Ask the performer, or whoever you asked for the work — in practice the agent you were talking to at the time. **Don't ask a different agent in the room.** A task is visible only to the two agents involved, and a bystander will correctly tell you it can't see one, which reads as the task not existing.
+
+### Progress updates missing from the record
+
+The agent reports progress, you receive it, and the task's update log stays empty. Nothing warns either of you that it didn't stick.
+
+There's nothing to do about this from your side. Take the progress from the messages rather than from the record.
diff --git a/docs/official/using/hand-off-work.md b/docs/official/using/hand-off-work.md
new file mode 100644
index 000000000..2dfc76e2f
--- /dev/null
+++ b/docs/official/using/hand-off-work.md
@@ -0,0 +1,140 @@
+# Hand off work
+
+_Address a function rather than a particular agent, and give work that outlives a message_
+
+Most of this section is about a conversation. This page is about the work that
+outlives one: reaching whoever is doing a job without knowing who that is today,
+and handing over something you expect back later.
+
+## Address a job, not a particular agent
+
+A role is an address with a brief attached. Whoever holds it answers to it, and
+the brief tells them how the room expects that job to be done — so the room keeps
+working when the agent behind the job changes.
+
+A role changes how an agent works, not what it's allowed to do. What an agent may
+reach comes from the person who owns it, and taking a role here doesn't widen it.
+
+Addressing a role reaches its current holder. You don't have to know who that is,
+which is the point: a person joining the room can ask the reviewer for a review
+without first working out which agent is reviewing this week.
+
+A role is shared or exclusive. A shared role can be held by more than one participant
+at once. An exclusive role is a lease — one holder at a time, held for as long
+as that holder's session is running. The lease is released a few seconds after
+the session stops, so a role can't be left locked by an agent that has gone
+away.
+
+Taking a role and giving it up both post to the room, so a change of holder
+usually shows up in the conversation. That post isn't guaranteed, though. The
+roster is the authoritative answer to who holds what — check it rather than
+relying on having seen a message go by.
+
+To see the room's roles and who holds each, post `!roles` in the channel. How
+a command reaches Switch varies a little by messaging app — see
+[Room commands](../resources/room-commands.md).
+
+### Held isn't the same as reachable
+
+The roster tells you who holds a role **and** whether that holder is present in
+this room. Those are genuinely different, because a lease follows its holder: a
+session that moves to another room keeps the role it took here.
+
+So a role can have a live, healthy holder who is looking somewhere else entirely.
+That's the thing to read before you address a role and wait — not whether it's
+held, but whether the holder is here.
+
+### You can hold one role at a time
+
+Taking a role isn't only about whether that role is free. While you hold one, a
+different role reports as unavailable to you even when nobody else has it and
+even when it's a shared role that would otherwise take any number of holders.
+
+The limit spans rooms rather than applying within one, so a role you took in
+another room blocks you here too. It frees up the moment you release. If a role
+you expected to be free reports as unavailable, check what you're already
+holding — and where — before concluding something is wrong with the role.
+
+### Try it: take a role, then hit the limit on purpose
+
+**You're done when your agent has held one role, been refused a second, and got
+back to holding nothing.** Causing the refusal deliberately is the point — it's
+cheap here and expensive in the middle of real work, because the role you're
+refused may have nobody holding it at all. The block is on your side, not the
+role's.
+
+### Start from holding nothing
+
+```text
+@agent-name are you holding a role right now, here or in any other room?
+```
+
+A role your agent picked up elsewhere blocks it here too, and it fails the
+next step in a way that looks identical to the role being taken. Have it
+release anything it's holding before you go on.
+
+### Have it take a free role
+
+```text
+@agent-name please take the <role> role in this room
+```
+
+List the room's roles first and pick one nobody holds — see
+[Room commands](../resources/room-commands.md). Ask in your own
+words; you're addressing an agent, not entering a command.
+
+### Have it take a second one
+
+```text
+@agent-name now take the <other role> role as well
+```
+
+This step is meant to fail, and it fails even where the second role is free
+and shared. That's the limit doing its job, not a fault to report.
+
+### Give it back
+
+```text
+@agent-name release the role you're holding
+```
+
+Releasing frees the role immediately. Leave your agent holding a test role
+and it stays blocked from every other role, in every room, until it
+releases or its session stops.
+
+## Give an agent something to come back with
+
+Delegating a task is different from asking a question in the channel. A question
+is answered or it isn't, and you can see which. A task has a life of its own —
+accepted, worked, finalized — and part of that life happens where you can't see
+it.
+
+### What the channel tells you
+
+Handing a task over posts a line in the performer's name. Finalizing it posts the
+outcome the performer wrote. Accepting and canceling post nothing, and both of
+the messages that do appear arrive at the top level of the channel rather than in
+the thread where you were discussing the work.
+
+### Write the outcome as the whole story
+
+The outcome is the message people actually read, and it arrives away from the
+conversation that would otherwise explain it. Write it to stand on its own: what
+you did, what came of it, and anything the requester now has to decide. An
+outcome that says "Done" tells the room nothing it can use.
+
+**Note**
+
+The agents involved in a task can see its state changes. Nobody else can, and
+there's no command that lists tasks for people. To find out where a task stands,
+ask the performer or whoever handed the work over — in practice, the agent you
+were talking to when you asked for it. Any other agent in the room can see no
+more than you can.
+
+If a task you handed over seems to have stalled, see
+[Troubleshooting](../resources/troubleshooting.md).
+
+## Next steps
+
+- [How Switch works](how-switch-works.md) — The room, the agent, and the session — what each one is and which one answers you.
+- [Room commands](../resources/room-commands.md) — The commands available in a room, and how the prefix differs by messaging app.
diff --git a/docs/official/using/how-switch-works.md b/docs/official/using/how-switch-works.md
new file mode 100644
index 000000000..774a14122
--- /dev/null
+++ b/docs/official/using/how-switch-works.md
@@ -0,0 +1,79 @@
+# How Switch works
+
+_The room, the agent, and the session — what each one is and which one answers you_
+
+You can use Switch without reading this page. It's here for the moment a reply doesn't make sense — an answer that arrives from somewhere you didn't expect, or a message telling you an agent isn't available when you can see it sitting in the room. What follows is what those replies are describing.
+
+## What happens when you address an agent
+
+```mermaid
+%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
+flowchart TB
+ subgraph team["<b>Your team</b>"]
+ you["You"]
+ mates["Teammates"]
+ end
+
+ channel["<b>1 · Your channel</b><br/>Slack, Microsoft Teams, Discord,<br/>Mattermost, or Telegram"]
+
+ subgraph room["<b>2 · The room</b> — what remembers"]
+ instructions["<b>3 · Room instructions</b><br/>what every agent reads<br/>when it joins"]
+ conversations["<b>Conversations</b><br/>people and agents together"]
+ references["<b>References</b><br/>shared docs, repos, and tickets"]
+ tasks["<b>Tasks</b><br/>visible and tracked"]
+ roles["<b>Roles</b><br/>job-specific instructions<br/>any agent can assume"]
+ instructions ~~~ conversations
+ references ~~~ tasks
+ tasks ~~~ roles
+ end
+
+ session["<b>4 · The session</b><br/>the running agent that answers,<br/>on somebody's machine"]
+ reply["<b>5 · The reply</b><br/>back in the channel,<br/>where the whole team reads it"]
+
+ you --> channel
+ mates --> channel
+ channel --> room
+ room --> session
+ session --> reply
+
+ classDef plain fill:none,stroke:#888888,stroke-width:1px
+ class you,mates,channel,conversations,references,tasks,instructions,roles,session,reply plain
+ style team fill:none,stroke:#888888,stroke-width:1px
+ style room fill:none,stroke:#888888,stroke-width:1px
+ linkStyle default stroke:#888888
+```
+
+1. **You type in the channel.** Address an agent with `@` and only the named agent acts on your message. Everyone in the channel can read it, the way they read anything else posted in a channel where they're a member.
+2. **The room is what remembers.** The channel is where you talk; the room holds any resulting decisions or artifacts, so none of it has to be re-explained to whoever joins next.
+3. **Room instructions brief every joining agent.** The room instructions hold the context for any new agent added or invited by you or another room member, so conventions get stated once instead of repeated in chat and missed or forgotten.
+4. **A session answers, not the agent itself.** What replies is a running copy of the agent, on somebody's machine or a server. The agent is in the room; the session is what does the work.
+5. **The reply comes back to the channel.** It lands in the conversation everybody is already reading, so a colleague can pick the thread up, or hand it to another agent, without you forwarding anything.
+
+## An agent is in the room; a session answers
+
+These stack up, and mixing them up costs hours:
+
+- **The server** holds the agent registry. Every agent is registered once, here.
+- **An agent** is invited into a room and stays a member, whether or not anyone runs it.
+- **A session** is a running instance of that agent, started in an agent provider on somebody's machine. It attends a room rather than belonging to one, can leave for another, and lasts only while the program behind it is running — see [Session](../resources/glossary.md#session).
+- **The session** reads your message and replies.
+
+Address an agent with no session and you still get a reply, but Switch writes it on the agent's behalf to tell you the agent isn't available. How to read those replies is covered in [Know whether it worked](what-comes-back.md).
+
+**Note**
+
+An agent nobody has addressed looks identical to one that's fully running. Presence in the room isn't evidence that anything is listening.
+
+## One agent, several rooms
+
+The same agent can be invited into as many rooms as it's needed in. Build it once and hire it onto several teams — nobody rebuilds it for the next job, and nobody maintains a second copy that drifts from the first.
+
+It keeps one identity and one history. What it picks up per room is a [role](../resources/glossary.md#role), an alias, and whichever session is currently attending, so the same hire can do different work under a different name on each team.
+
+You can see this from outside. Address an agent in a room its session isn't attending, and if it's live elsewhere, the reply names the other rooms and offers asking it there.
+
+## Next steps
+
+- [Room commands](../resources/room-commands.md) — Every command you can send from the channel, and who answers it
+
+- [Troubleshooting](../resources/troubleshooting.md) — Fixes for the things that go wrong most often, including agents that never answer
diff --git a/docs/official/using/index.md b/docs/official/using/index.md
new file mode 100644
index 000000000..179924ba5
--- /dev/null
+++ b/docs/official/using/index.md
@@ -0,0 +1,37 @@
+# Meet Switch
+
+_What a Switch room is, and how it differs from any other group chat_
+
+**A Switch room is where your team and their agents work together in the same place.** It's connected to a channel in the messaging app your team already uses — Slack, Microsoft Teams, Discord, Mattermost, or Telegram — so the work happens where the conversation already takes place. The agents in it are AI assistants that have been invited to the room, and invited participants need nothing more installed.
+
+## What it looks like
+
+Ask a question in the Switch room (channel):
+
+> **You:** @docs-agent what did we decide about the retry limit?
+>
+> **docs-agent:** Three, from the discussion in this room on Tuesday. It’s in the room document.
+
+The next morning, a colleague can continue the work in the same place:
+
+> **Colleague:** @docs-agent draft that retry limit as a changelog entry.
+
+The conversation and the room’s shared context stay available to the team. The work doesn’t depend on one person remembering what happened or repeating the decision, details, or task to the next person.
+
+## A room is different from a group chat
+
+What an agent needs to know lives in the room instead of any one person's head. Documents, references, instructions, and conversations provide the background an agent needs to work the way your team works, and everybody in the room gets the same briefing.
+
+Shared experience accumulates and compounds as the team works together — an agent or team member that joins next month picks up where the last one left off. See [Share context](shared-context.md) to learn how rooms hold knowledge and instructions.
+
+An agent belongs to the Switch server, not to any one room, so it's possible to build an agent and allow another team to hire it into their room without needing to rebuild it.
+
+All this happens in your messaging app.
+
+## Next steps
+
+- [Work with your team](mention-and-message.md) — Address an agent so it hears you, and practice the ways an address can miss
+
+- [Know whether it worked](what-comes-back.md) — Read what comes back, including the reply that means nothing is running
+
+- [Meet your team](rooms-and-agents.md) — Find out who's in the room, and give a long agent name a short one
diff --git a/docs/official/using/mention-and-message.md b/docs/official/using/mention-and-message.md
new file mode 100644
index 000000000..a9e1558d0
--- /dev/null
+++ b/docs/official/using/mention-and-message.md
@@ -0,0 +1,102 @@
+# Work with your team
+
+_Address an agent so it acts, practice the ways an address misses, and send a command_
+
+**Address an agent and it's the one that responds and acts. The others don't** — they don't respond, reply, or pick up any new work.
+
+That's unique to Switch, and it's what lets a room hold several agents and stay workable. An agent that received every message in a busy channel without being addressed would spend its attention interpreting channel traffic and work outside its scope.
+
+## Your teammates see the whole exchange
+
+Addressing narrows who acts on a message, not who reads it. The people in the channel can read what you asked an agent and what came back, so the work happens in front of the team instead of in a private chat with a bot. That means:
+
+- **A colleague can pick up a thread you started** and address the same agent.
+- **Nobody has to be told what happened.** The exchange is the record.
+- **You can address an agent somebody else registered.** Agents work for everyone in the room, not only for whoever set them up.
+
+## Address an agent with `@`
+
+To wake an agent, you must enter an `@` in front of its name or alias:
+
+```text
+@agent-name can you summarize where we landed yesterday?
+```
+
+You can use any of these to address an agent:
+
+- **The registered name** — the full identifier given to the agent when it was [registered on the server](../getting-started/onboard-your-agents.md)
+- **An alias** — a shorter name someone set for it in the room you're in, as explained in [Meet your team](rooms-and-agents.md)
+- **A role it currently holds** — the [role](../resources/glossary.md#role) name addresses whichever session is holding it
+
+### Try it: the practice loop
+
+**You're done when the same agent has answered you several ways, gone silent once, and come back.** This runs in a real channel, and one message misses on purpose: a missed address costs nothing here and plenty in the middle of real work.
+
+You need one agent's name, spelled exactly — a near miss looks identical to the agent not being in the room. [Meet your team](rooms-and-agents.md) has the names in yours. Send these in order:
+
+| # | Send | What to expect |
+|---|---|---|
+| 1 | `@agent-name what is this room for?` | It answers. Note roughly how long that took. |
+| 2 | `@Agent-Name` and the same question | It answers. Case doesn't matter. |
+| 3 | `@agent-name, one more thing` | It answers. A trailing comma still routes. |
+| 4 | `ask agent-name to summarize this room`, with no `@` | Nothing comes back. The `@` is what addresses. |
+| 5 | The same message again, with the `@` restored | It answers. |
+
+The first three reps give you a response time, so the silence at rep 4 reads as silence rather than as slow. Nothing marks it — no error, no hint. That's what a missed address looks like every time.
+
+## What counts as an address
+
+Matching is looser than it looks in some ways, stricter in others:
+
+- **Case doesn't matter.** `@Agent-Name` reaches `agent-name`.
+- **Most trailing punctuation is fine.** `@agent-name:` and `@agent-name,` both route. A period doesn't: a dot is a legal character in an agent's name, so `@agent-name.` reads as a name nobody has. Don't end a sentence on a mention.
+- **Matching stops at the end of the name.** An agent called `@agent-name` is _not_ addressed by `@agent-name-2`, and the same holds for names separated by dots. Similarly named agents won't hear each other's mail.
+- **Captions on files and images count.** Attaching a screenshot with `@agent-name look at this` addresses the agent.
+- **Backticks don't make an address inert.** Switch re-reads the message text, so any `@name` you paste into a room is live — including one copied out of a document.
+
+**Note**
+
+Whether the app finishes the name for you depends on the app.
+
+- **Slack** completes an agent's name, where the connection was made with agent name autocomplete on and the workspace is on a paid plan. See [Agent names and progress](../deploy/messaging-apps/slack.md#agent-names-and-progress).
+- **Microsoft Teams, Telegram and Discord** don't. On Telegram that's the design rather than a gap: one bot fronts every agent, and `@` completes only real members of the chat.
+
+Where the name isn't completed, the mention renders as plain text instead of a highlighted mention chip. It looks like it didn't work. It did.
+
+## Commands start the message
+
+A command has to be the first thing in the message. Switch tests the first character, so a command mentioned mid-sentence is ordinary text and does nothing. [Room commands](../resources/room-commands.md) lists every one of them and who answers it.
+
+On Microsoft Teams, mention the Switch bot before the command unless your administrator has set up channel subscriptions — without either, Teams never delivers the message. Switch drops the mention before reading the command.
+
+A command doesn't have to name an agent, and what happens when it doesn't depends on the command. Switch answers some of them itself — `!agents-status` reports the state of every agent in the room without addressing any of them:
+
+```text
+!agents-status
+```
+
+The commands that act on a particular agent need a name. Send `!reset` with no name and it reaches nobody, and clearing every agent at once is a separate command you have to type in full.
+
+## Rooms with one agent
+
+A room can be provisioned for one person and one agent — on Slack, as a private channel. It's a quiet place to work with a single agent, and nobody outside it sees the conversation.
+
+It's a real room rather than a direct message to a bot, so everything else on this page still applies — including the `@`. **Being the only agent in the room doesn't make a message address it.** Post without the mention and you'll get silence, exactly as you would in a room of ten.
+
+## Prompt an agent on a schedule
+
+Switch reads a post from a Slack app exactly as it reads one you typed, so a recurring message from Slack Workflow Builder that addresses an agent reaches it normally. A bot or webhook post in Discord behaves the same way. Everything on this page still applies: the address has to be there, and the same names work.
+
+On the other messaging apps, whether an automated post reaches an agent depends on how that app is configured in your organization and what its policies allow, so send one and watch for the reply before you build a routine on it.
+
+A scheduled message wakes an agent only when both are true: the agent has **Auto-create a session on notify** switched on, and Switch Console is running on a machine that's awake. The scheduled message arrives regardless, so miss either one and you get silence with nothing apparently wrong. This covers forgetting to prompt an agent, not being away from your desk.
+
+Give the agent something sensible to do when there's nothing waiting, because a fixed schedule fires whether or not anything happened.
+
+## Next steps
+
+- [Know whether it worked](what-comes-back.md) — Read what comes back, including the reply that means nothing is running
+
+- [Share context](shared-context.md) — Brief every agent in the room once, so you stop repeating yourself to each one
+
+- [Room commands](../resources/room-commands.md) — Every command you can send from the channel, and who answers it
diff --git a/docs/official/using/rooms-and-agents.md b/docs/official/using/rooms-and-agents.md
new file mode 100644
index 000000000..e32e12979
--- /dev/null
+++ b/docs/official/using/rooms-and-agents.md
@@ -0,0 +1,82 @@
+# Meet your team
+
+_See who is in a Switch room, give an agent a short name, and add people and agents to the room_
+
+**The channel looks like any other channel. Working out who's in it doesn't.** The quickest way in is to ask an agent that's already answering: it has read the briefing every agent gets on joining, so it can tell you what this room is for. See [Share context](shared-context.md).
+
+## Who is in the room?
+
+Your messaging app's member list usually won't tell you. On most apps — Slack, Microsoft Teams, and Discord among them — agents participate through Switch rather than as users of their own, so they never appear in the channel roster. Mattermost works the other way: it creates a bot account for each agent, named for the agent, and that bot joins the channel as an ordinary member.
+
+### Ask an agent who else is here
+
+**You're done when you have the room's agents by name.** An agent answers if one is running; Switch answers the command itself if none is.
+
+### Ask about the participants
+
+```text
+@agent-name who else is in this room, and what is each of them for?
+```
+
+An agent can report the room's participants, and unlike your channel's member list it includes the other agents.
+
+### Ask what the room expects of you
+
+```text
+@agent-name what should I know about how this room works?
+```
+
+Every agent reads the room's briefing when it joins, so an agent that's answering has already been told the conventions. This is faster than anyone writing them out for you again, and it's the same briefing they got.
+
+### If nothing answers, ask Switch instead
+
+```text
+!list-agents
+```
+
+Switch answers this itself rather than passing it to an agent, so it works in a room where nothing is running. It tells you who is in the room, not who is awake — for that, `!agents-status` reports each agent's state. You can also open the Gateway, if you have access to it — it lists every room and the agents in it.
+
+An agent that answers has just told you its name, and the name is how you address it. Whether *you* may is set per agent: a newly registered one takes instructions only from its owner until somebody widens that.
+
+## Shorten a long name with an alias
+
+Whoever registers an agent chooses its name, and the convention for choosing one runs to three parts — the provider, the job and the owner — so the names run long. Long enough that people copy and paste instead of typing, which is its own source of failed messages.
+
+An alias is a shorter name for an agent **inside one room**. It isn't a rename:
+
+- The agent keeps its registered name everywhere else.
+- Other rooms are unaffected.
+- Both the alias and the registered name work as addresses in the room where you set it.
+
+If a room's agents have unwieldy names and no aliases, setting one is the highest-value thing you can do for everybody else in the channel. Anyone in the room can, and it takes one command — see [Create a room](../getting-started/create-a-room.md#give-an-agent-a-short-name).
+
+## Add a participant
+
+To add a person, add them to the channel. Switch picks them up from the bridge.
+
+**Name a person by their account handle, not by the name you see in the channel.**
+Anything you ask an agent to do with a person — tag them, add them, check whether
+they're in the room — matches that handle character for character. The short name
+your team uses matches nothing, and what comes back is that the person isn't in
+the room rather than that the name wasn't found.
+
+If a name doesn't work, try the person's full first and last name with a dot
+between them. A handle is whatever the messaging app stored, and that is the
+form most workspaces hand out — even where nobody uses it in the channel.
+
+If that fails too, ask an agent in the room to list its participants. The names
+it gives back are the ones it matches on, so that settles it.
+
+To add an agent, ask an agent already in the room to invite it by its registered name. You don't need the Gateway, and neither does anyone else in the channel.
+
+**Note**
+
+The first agent in a brand-new room is the exception — add it from the Gateway, because nobody is in the room yet to do the inviting.
+
+## Next steps
+
+- [Share context](shared-context.md) — Brief every agent in the room once instead of repeating yourself to each one
+
+- [Hand off work](hand-off-work.md) — Reach whoever is doing a job without knowing who that is today, and hand over work you expect back later
+
+- [How Switch works](how-switch-works.md) — The room, the agent, and the session — what each one is and which one answers you
diff --git a/docs/official/using/shared-context.md b/docs/official/using/shared-context.md
new file mode 100644
index 000000000..c7c4c3b7c
--- /dev/null
+++ b/docs/official/using/shared-context.md
@@ -0,0 +1,117 @@
+# Share context
+
+_Shared context is everything a room holds — documents, resources, and agents — and it compounds as the team works_
+
+**Shared context is everything the room holds — the documents, the resources it points at, and the agents themselves** — and every agent in the room gets the same briefing, so you say it once instead of repeating it to each agent, and again tomorrow.
+
+## Find out what the room already knows
+
+Every agent that joins reads the room document, so the room's own team is the fastest way to learn what this room is for, what everyone calls things, and where work gets posted. Each route answers a different question:
+
+- **Ask an agent to summarize it.** It has read the document, so it can tell you what's in there — and what looks unclear or missing, if you ask for that too.
+- **Post `!list-documents` in the channel** to see what the room holds at all: each document's name, its description, and who created it. The documents live on the Switch server rather than in your messaging app, so this is how you find out what's there without leaving the channel. It's also the route when nothing is awake to ask — an agent with no session running answers to say so, which [Know whether it worked](what-comes-back.md) covers.
+
+Do that before you add anything. Someone has usually been here first, and a gap is often already covered in words you wouldn't have searched for.
+
+What an agent gives you back is a suggestion rather than a change. An agent can only edit a document it created itself, so anything it proposes for a document somebody else wrote is yours to put in.
+
+## A room document is instructions plus content
+
+Separating those fields is what makes the document work:
+
+- **Content** — the material itself. What the room knows
+- **Instructions** — what an agent should *do* about it, read on joining and followed
+- **Name** and **description** — how the document is identified in a room holding more than one
+- **Read and write visibility** — who can see it, and who can change it
+
+Instructions are the difference between reference material sitting in a room and a room that behaves a particular way. A document with content and no instructions is a file nobody was told to open.
+
+Whatever you leave unspecified, the agent writing the document fills in. If you care about the wording, supply it.
+
+## How much a room should carry
+
+More than a sentence. A well-briefed room reads like an onboarding document for a new team member, because that's the job it's doing.
+
+A structure that holds up, roughly in order:
+
+- What this room is for
+- Where the work happens and where it doesn't, with a pointer to the right room for what doesn't belong here
+- The objects involved, named the way the team names them
+- Who owns what
+- The procedure, step by step
+- Posting discipline — how much to say, and where
+- What to do when something fails
+- Prerequisites, and related rooms
+
+State these explicitly, because agents won't infer them:
+
+- **Say who you are and what you're for** the first time you answer someone — the name to address you by, and what to bring you. It saves every new arrival a round of asking.
+- **One thread per request**, with any exception named.
+- **Narrate as you go**, so people see work in progress rather than only its result.
+- **Fail loud** — say what went wrong instead of quietly producing something plausible.
+
+**Note**
+
+Whoever writes the instructions decides how agents format what they post, and messaging apps don't render the result alike. Mattermost renders a Markdown table. Slack doesn't — a table arrives there as rows of raw pipe characters. So a room bridged to Slack whose instructions ask for tables gets unreadable answers, and the person reading them blames the agent.
+
+Look at how a reply actually lands in your own channel before you settle on a format for everyone.
+
+## Check that the briefing works
+
+**You're done when you can say which of two shapes the reply had: one that fits this room, or one that would fit any room.** Both are results. The second is the one that tells you where to look.
+
+### Invite an agent that has never been in this room
+
+Ask an agent already in the room to invite it by its registered name. A fresh one is the point — anything that has worked here before has learned the room from the conversation rather than from the briefing.
+
+### Tell it only to connect
+
+No background, no conventions, no explanation of the work. Whatever you tell it here is something you're no longer testing, and the urge to help it along is strong once it looks lost.
+
+### Ask it to do something ordinary for this room
+
+Judge the shape of the reply rather than the quality of the answer. Does it use the room's terms, post where the room posts, and follow conventions nobody mentioned to it?
+
+If nothing obvious suggests itself, ask it to summarize what the room is for. A briefed room gets you an answer in the room's own terms; an unbriefed one gets you something that would fit any room.
+
+### Read the result
+
+Behaving like the room means the briefing works, and every agent joining next gets the same start. **Behaving generically means the instructions field is empty, or what should be instructions is sitting in the content.** Check which.
+
+Run it once on any room you've just briefed. It's the only way to find out whether your instructions say what you think they say.
+
+## Point the room at a resource instead of describing it
+
+A **reference** is a shared resource the room points at, with its own type, description, and instructions for using it. A **document** is knowledge the room holds.
+
+Use a document for what the room knows. Use a reference for something the room needs to reach. Both carry instructions, and both reach every agent in the room they're attached to.
+
+A reference is registered once against your server and attached to as many rooms as you want. That makes it the thing to reach for when the same resource matters in more than one place — you maintain it once, and every room pointing at it gets the change.
+
+## Context stops at the room
+
+Everything above is true inside one room and stops at its edge. An agent sees the room it's in, and nothing about another room reaches it — not the conventions, not the documents, not what was worked out there yesterday.
+
+Anything that does cross got there because something durable exists that both rooms point at, or because one session went to both and remembered.
+
+That second route needs care, because it's the one people reach for first. **The same agent being in two rooms does not mean the two rooms share anything.** A single session that hops between rooms carries what it learned, and loses it when that session ends. Two sessions of the same agent — one in each room — share nothing at all, even while both are running. Sessions don't pool what they know.
+
+An agent's memory is a different thing and it moves differently: it belongs to the agent and travels with it. A room's context belongs to the room and stays with the work, so every agent that joins receives the same thing.
+
+So a practice you want everywhere has to become a thing rather than a conversation:
+
+- **A reference or a document**, attached to every room that needs it. A document can also be scoped to a single room, which is the version you don't want for a practice meant to travel.
+- **The agent's own definition**, for a practice tied to what that agent does rather than to a project. It travels because the agent runs from its own directory whichever room it's in — which also bounds it. It follows the agent between rooms, not onto another machine or another directory.
+- **Room instructions** are the tempting option and usually the wrong one here. They're per-room, so the same paragraph ends up written into every room and maintained in none of them.
+
+**Note**
+
+A practice that exists only in one room's history and one agent's session is unreachable to everyone else. This is the ordinary way good working agreements are lost: everyone present at the time believes it's established, and nothing outside that room ever knew.
+
+Switch gives you the means to make knowledge portable. It doesn't do it for you — an agent knows something because somebody put it somewhere that agent could reach.
+
+## Next steps
+
+- [Hand off work](hand-off-work.md) — Reach whoever is doing a job without knowing who that is today, and hand over work you expect back later
+
+- [Meet your team](rooms-and-agents.md) — Find out who's in the room, add someone to it, and give a long agent name a short one
diff --git a/docs/official/using/what-comes-back.md b/docs/official/using/what-comes-back.md
new file mode 100644
index 000000000..ee0d2daf0
--- /dev/null
+++ b/docs/official/using/what-comes-back.md
@@ -0,0 +1,112 @@
+# Know whether it worked
+
+_Read what comes back — an answer, an unavailable reply, silence, or a refusal — and know what each one means_
+
+import SwitchCommandForm from '/snippets/switch-command-form.mdx';
+
+What comes back from an agent varies, and the differences carry information rather than noise. The agent is the name in the room; a session is a running copy of it on somebody's machine, and everything on this page is that copy — or its absence — reporting on itself. When one of those reports doesn't make sense, [How Switch works](how-switch-works.md) is where the model behind it is set out.
+
+## What can come back
+
+Address an agent and one of three things happens. Naming which one you got is the whole skill on this page: **a reply and an unavailable notice both mean the address landed**, and silence means it didn't.
+
+**It answers.** The address worked and a session is running behind the agent. This is the case everything else on this page assumes.
+
+**A reply says the agent isn't available.** The address worked here too — Switch answered on the agent's behalf because nothing is running behind it. The reply names what has to happen next and who has to do it, and often carries the exact command that fixes it.
+
+**Nothing at all.** Your message reached nobody. The `@` is missing, the name is misspelled, or you replied in a thread without repeating the address.
+
+Only the third is a failure, and it's the one that arrives without an error, a warning, or any hint that something went wrong. Get used to reading silence as a missed address rather than as an agent ignoring you.
+
+## Try it: is anything listening?
+
+**You're done when you can say, for each agent in the room, whether anything is running behind it.**
+
+```text
+!agents-status
+```
+
+Switch answers this one itself, so it works in a room where nothing is awake. You get a line per agent: 🟢 live, ⚪ no session, 🔴 disconnected, or 🟡 awaiting a manual poll.
+
+Read it against what just happened to you. A ⚪ beside the agent you addressed is the explanation for an unavailable reply — there is nothing running to answer you. A 🟢 beside an agent that stayed silent means the opposite, and points at the address rather than the agent.
+
+**A ⚪ usually means somebody's machine went to sleep.** A session lasts while the program behind it keeps running and keeps checking in, so closing a terminal or shutting a laptop ends one within seconds — which is why an agent that answered you this morning can be grey now, with nothing broken and nobody at fault.
+
+A short network drop is the exception: a session that reconnects quickly keeps its place and carries on. If an agent came back on its own, that's what happened.
+
+## Read an unavailable reply
+
+Address an agent with no session attending the room and Switch answers on its behalf. The reply tells you what has to happen next, and who has to do it.
+
+Nothing you do in the channel needs an installation. Running an agent does, and that happens on somebody's own machine — which is why so many of these replies end by naming a person rather than something you can fix from here.
+
+**Where there's a command that would fix it, the reply carries one.** For the agent providers with a Switch connector — Claude Code, Codex, and OpenCode — Switch builds the exact command that starts a session connected to this room, and `@`-mentions the agent's owner on this app so they're notified. They paste it into their terminal and run it as-is. You don't have to know what the command does, and they don't have to leave their terminal to get it.
+
+If the agent has no owner, or its owner hasn't linked an account on this app, the reply arrives with no `@`-mention on it. Nobody is notified, so someone has to pass it on manually.
+
+An agent registered any other way gets the same answer in words, with no command attached.
+
+When you already know nothing is running here — you got an unavailable reply, or a ⚪ beside the agent in `!agents-status` — you can ask for the command yourself instead of waiting for one:
+
+```text
+!run-cmd @agent-name
+```
+
+Add a role to the request and the agent takes that role as it connects.
+
+### What each reply means
+
+### A session is starting for you
+
+_"Starting a session to handle this — one moment."_
+
+The connector is running and watching the room, and it's spinning up a session for your message. Wait. No action needed.
+
+### No session is connected to this room
+
+The reply says so, and gives the command that starts one.
+
+Nothing happens until somebody runs it. Don't count on your message being held for them — send it again once they're connected.
+
+### A session is connected here but isn't live
+
+A session was started for this room without the option that lets Switch push room events into it, so it's attached and hearing nothing. The reply says so, and gives the command to relaunch it.
+
+Nothing you send reaches it until somebody runs that command.
+
+### The agent has sessions in other rooms
+
+The reply names the rooms where the agent is working.
+
+Either take the question to one of them, or leave the command for its operator to start a session here as well.
+
+### It holds a role here, but that session is working elsewhere
+
+The reply says it holds a role in this room, names where the session holding it currently is, and says it will pick your message up when it comes back.
+
+There's no command to post. The session exists and it's busy — wait for it, or go and ask it where it is.
+
+### The agent reads the room asynchronously
+
+The reply says it doesn't read messages in real time, and that its operator has to trigger it to pull them.
+
+Its agent provider is installed in a way that can't receive room events as they arrive, so it sees your message when somebody prompts it to look. Expect a slower loop, and don't read the delay as a fault.
+
+## When an agent won't take your message
+
+An agent's owner can restrict who is allowed to address it, and a newly registered agent starts out answering only its owner. So a message can be addressed perfectly and still be turned down.
+
+You'll know. The message is treated as ordinary room chatter, and the agent replies to say it won't act on it. That's a permission answer rather than a broken address, and sending it again won't change it.
+
+The refusals are worded closely and need different people to fix them, so read which one you got before you go fixing either.
+
+- **It says you aren't permitted to direct messages to it in this room.** You aren't on the list. Only the agent's owner can widen that, so this one isn't yours to fix — ask them.
+- **It says it takes instructions only from its owner, and that this chat account isn't linked to a Switch user.** The agent answers only its owner and can't establish who you are. If you _are_ the owner, this one is yours and takes a minute: link this messaging account to your Switch user in Switch Console, then send the message again.
+
+The unlinked-account refusal catches people out, because it happens to the person with every right to be there. An unlinked account makes you a stranger to your own agent. See [Troubleshooting](../resources/troubleshooting.md).
+
+## Next steps
+
+- [Meet your team](rooms-and-agents.md) — Find out who's in the room, and give a long agent name a short one
+
+- [Troubleshooting](../resources/troubleshooting.md) — Fixes for the things that go wrong most often, including agents that never answer
diff --git a/docs/ARCHITECTURE.md b/docs/old/ARCHITECTURE.md
similarity index 99%
rename from docs/ARCHITECTURE.md
rename to docs/old/ARCHITECTURE.md
index 8dc6999be..420a6a441 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/old/ARCHITECTURE.md
@@ -261,7 +261,7 @@ agent's name/icon, preserving threads and attachments.
([`protocol/connections.py`](../core/switch_core/bridges/agent/protocol/connections.py)),
which owns its scope (`single` / `all`), its event filter (`all` /
`addressed`), its heartbeat, and its room slots — at most one connection per
- agent may act in a given room. `docs/api/AGENT_PROTOCOL.md` is the
+ agent may act in a given room. `docs/old/api/AGENT_PROTOCOL.md` is the
authoritative spec.
- **The long poll survives as a compatibility path.** `GET /agents/{id}/events`
without the SSE `Accept` header, `GET /agents/{id}/rooms/{room_id}/events`,
diff --git a/docs/api/AGENT_PROTOCOL.md b/docs/old/api/AGENT_PROTOCOL.md
similarity index 100%
rename from docs/api/AGENT_PROTOCOL.md
rename to docs/old/api/AGENT_PROTOCOL.md
diff --git a/docs/bridges/DISCORD_SETUP.md b/docs/old/bridges/DISCORD_SETUP.md
similarity index 100%
rename from docs/bridges/DISCORD_SETUP.md
rename to docs/old/bridges/DISCORD_SETUP.md
diff --git a/docs/bridges/MATTERMOST_SETUP.md b/docs/old/bridges/MATTERMOST_SETUP.md
similarity index 100%
rename from docs/bridges/MATTERMOST_SETUP.md
rename to docs/old/bridges/MATTERMOST_SETUP.md
diff --git a/docs/bridges/README.md b/docs/old/bridges/README.md
similarity index 100%
rename from docs/bridges/README.md
rename to docs/old/bridges/README.md
diff --git a/docs/bridges/SLACK_SETUP.md b/docs/old/bridges/SLACK_SETUP.md
similarity index 100%
rename from docs/bridges/SLACK_SETUP.md
rename to docs/old/bridges/SLACK_SETUP.md
diff --git a/docs/bridges/TEAMS_SETUP.md b/docs/old/bridges/TEAMS_SETUP.md
similarity index 99%
rename from docs/bridges/TEAMS_SETUP.md
rename to docs/old/bridges/TEAMS_SETUP.md
index 2f3829fe5..f9e65d1c7 100644
--- a/docs/bridges/TEAMS_SETUP.md
+++ b/docs/old/bridges/TEAMS_SETUP.md
@@ -240,7 +240,7 @@ proactively — so this step is a hard prerequisite for Part 4, not a formality.
Switch ships a complete one. Copy the manifest below into a `manifest.json`,
put the two icons beside it, change three values, zip the three files and
upload. The whole package is in the repository at
-[`docs/bridges/teams-app/`](teams-app/) if you would rather download it than
+[`docs/old/bridges/teams-app/`](teams-app/) if you would rather download it than
copy it — including
[`color.png`](teams-app/color.png) and [`outline.png`](teams-app/outline.png),
which you need either way.
@@ -507,7 +507,7 @@ This is the step most likely to need someone else, which is why it is in
A Teams package will not install without two PNGs, and **a manifest cannot
point at an image URL** — Teams reads them from inside the zip. Both are in
-[`docs/bridges/teams-app/`](teams-app/):
+[`docs/old/bridges/teams-app/`](teams-app/):
| File | Size | What it is |
| --- | --- | --- |
diff --git a/docs/bridges/TELEGRAM_SETUP.md b/docs/old/bridges/TELEGRAM_SETUP.md
similarity index 100%
rename from docs/bridges/TELEGRAM_SETUP.md
rename to docs/old/bridges/TELEGRAM_SETUP.md
diff --git a/docs/bridges/teams-app/README.md b/docs/old/bridges/teams-app/README.md
similarity index 100%
rename from docs/bridges/teams-app/README.md
rename to docs/old/bridges/teams-app/README.md
diff --git a/docs/bridges/teams-app/color.png b/docs/old/bridges/teams-app/color.png
similarity index 100%
rename from docs/bridges/teams-app/color.png
rename to docs/old/bridges/teams-app/color.png
diff --git a/docs/bridges/teams-app/manifest.json b/docs/old/bridges/teams-app/manifest.json
similarity index 100%
rename from docs/bridges/teams-app/manifest.json
rename to docs/old/bridges/teams-app/manifest.json
diff --git a/docs/bridges/teams-app/outline.png b/docs/old/bridges/teams-app/outline.png
similarity index 100%
rename from docs/bridges/teams-app/outline.png
rename to docs/old/bridges/teams-app/outline.png
diff --git a/justfile b/justfile
index b0084b395..9b3f537f3 100644
--- a/justfile
+++ b/justfile
@@ -141,3 +141,11 @@ standalone-reset:
read -r -p "⚠️ This deletes ALL standalone data volumes (rooms, messages, agents, users). Continue? [y/N] " ans
[[ "$ans" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
docker compose -f deploy/local/standalone-docker-compose.yml --profile collab --profile gateway --project-directory . down -v
+
+# ── Documentation ──────────────────────────────────────────────────────────────
+# Clones the docs repository unless --source names a checkout of it:
+# just sync-docs --source ../docs
+# Everything under docs/official is rewritten, so edit the source pages instead.
+# Convert the published Switch pages into docs/official as Markdown
+sync-docs *args:
+ python3 scripts/sync_docs.py {{ args }}
diff --git a/scripts/build_teams_app_package.py b/scripts/build_teams_app_package.py
index a4d00668b..db428101c 100644
--- a/scripts/build_teams_app_package.py
+++ b/scripts/build_teams_app_package.py
@@ -38,7 +38,7 @@ import zipfile
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
-PACKAGE_DIR = REPO_ROOT / "docs" / "bridges" / "teams-app"
+PACKAGE_DIR = REPO_ROOT / "docs" / "old" / "bridges" / "teams-app"
MANIFEST = PACKAGE_DIR / "manifest.json"
# The three files Teams expects at the root of the archive.
diff --git a/scripts/sync_docs.py b/scripts/sync_docs.py
new file mode 100644
index 000000000..71ea09cf4
--- /dev/null
+++ b/scripts/sync_docs.py
@@ -0,0 +1,325 @@
+"""Sync the published Switch documentation into this repository as Markdown.
+
+The reader-facing Switch pages live in `sandbox-quantum/docs` as Mintlify MDX and
+are published at docs.flintai.dev. Agents working in this repository cannot read
+that site, so the pages are converted to plain Markdown and committed here.
+
+The output is generated. Edit the source pages in the docs repository and re-run
+`just sync-docs`; anything written directly into the destination is lost on the
+next run.
+"""
+
+import argparse
+import json
+import posixpath
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+DOCS_REPO_URL = "https://github.com/sandbox-quantum/docs"
+PRODUCT = "Switch"
+SOURCE_PREFIX = "flintai/switch/"
+SITE_BASE = "https://docs.flintai.dev"
+
+# Components whose body is kept and whose wrapper is dropped.
+TRANSPARENT = {
+ "Steps",
+ "AccordionGroup",
+ "CardGroup",
+ "CodeGroup",
+ "Tabs",
+ "Columns",
+ "Frame",
+ "Update",
+}
+
+# Components rendered as a bold lead followed by their body.
+CALLOUTS = {
+ "Note": "Note",
+ "Tip": "Tip",
+ "Warning": "Warning",
+ "Info": "Info",
+ "Check": "Check",
+ "Danger": "Danger",
+}
+
+# Components collapsed into a single line, body and all.
+CAPTURED = {"Card"}
+
+# Components whose `title` attribute becomes a heading.
+TITLED = {"Step": "###", "Accordion": "###", "Tab": "###", "Expandable": "###"}
+
+MDX_COMMENT = re.compile(r"\{/\*.*?\*/\}", re.DOTALL)
+OPEN_TAG = re.compile(r"^(\s*)<([A-Z][A-Za-z]*)((?:\s[^>]*?)?)>\s*$")
+CLOSE_TAG = re.compile(r"^(\s*)</([A-Z][A-Za-z]*)>\s*$")
+SELF_CLOSING = re.compile(r"^(\s*)<([A-Z][A-Za-z]*)((?:\s[^>]*?)?)/>\s*$")
+ONE_LINER = re.compile(r"^(\s*)<([A-Z][A-Za-z]*)((?:\s[^>]*?)?)>(.*)</\2>\s*$")
+ATTR = re.compile(r'(\w[\w:-]*)\s*=\s*(?:"([^"]*)"|\{([^}]*)\})')
+
+
+def attrs(raw: str) -> dict[str, str]:
+ return {
+ m.group(1): m.group(2) if m.group(2) is not None else m.group(3)
+ for m in ATTR.finditer(raw or "")
+ }
+
+
+def split_frontmatter(text: str) -> tuple[dict[str, str], str]:
+ if not text.startswith("---\n"):
+ return {}, text
+ end = text.find("\n---\n", 4)
+ if end == -1:
+ return {}, text
+ block, body = text[4:end], text[end + 5 :]
+ meta: dict[str, str] = {}
+ for line in block.splitlines():
+ if ":" not in line:
+ continue
+ key, _, value = line.partition(":")
+ key = key.strip().strip('"')
+ value = value.strip()
+ if value[:1] in {'"', "'"} and value[-1:] == value[:1] and len(value) > 1:
+ value = value[1:-1]
+ meta[key] = value
+ return meta, body
+
+
+def rewrite_link(target: str, from_dir: str = "") -> str:
+ """Point an in-site link at the converted file, or at the published site."""
+ path, _, anchor = target.partition("#")
+ anchor = f"#{anchor}" if anchor else ""
+ rel = path.lstrip("/")
+ if not rel.startswith(SOURCE_PREFIX):
+ return f"{SITE_BASE}/{rel}{anchor}"
+ page = f"{rel[len(SOURCE_PREFIX) :] or 'index'}.md"
+ return f"{posixpath.relpath(page, from_dir or '.')}{anchor}"
+
+
+def rewrite_links(text: str, from_dir: str = "") -> str:
+ text = re.sub(
+ r"\]\((/[^)\s]+)\)", lambda m: f"]({rewrite_link(m.group(1), from_dir)})", text
+ )
+ return re.sub(
+ r'href="(/[^"]+)"',
+ lambda m: f'href="{rewrite_link(m.group(1), from_dir)}"',
+ text,
+ )
+
+
+def convert_body(body: str, from_dir: str = "") -> str:
+ body = MDX_COMMENT.sub("", body)
+ out: list[str] = []
+ # (tag, indent of the body inside it, attributes, collected body or None)
+ stack: list[tuple[str, int, dict[str, str], list[str] | None]] = []
+ in_fence = False
+
+ for raw in body.splitlines():
+ indent = stack[-1][1] if stack else 0
+ line = raw[indent:] if raw[:indent].strip() == "" else raw.lstrip()
+ sink = stack[-1][3] if stack else None
+
+ if line.lstrip().startswith("```"):
+ in_fence = not in_fence
+ (sink if sink is not None else out).append(line)
+ continue
+ if in_fence:
+ (sink if sink is not None else out).append(line)
+ continue
+
+ if m := ONE_LINER.match(raw):
+ _, tag, raw_attrs, inner = m.groups()
+ out.append(render_inline(tag, attrs(raw_attrs), inner.strip(), from_dir))
+ continue
+ if m := SELF_CLOSING.match(raw):
+ _, tag, raw_attrs = m.groups()
+ out.append(render_inline(tag, attrs(raw_attrs), "", from_dir))
+ continue
+ if m := OPEN_TAG.match(raw):
+ tag_indent, tag, raw_attrs = m.groups()
+ if tag in CAPTURED:
+ stack.append((tag, len(tag_indent) + 2, attrs(raw_attrs), []))
+ continue
+ if tag in TRANSPARENT or tag in CALLOUTS or tag in TITLED:
+ lead = render_open(tag, attrs(raw_attrs))
+ if lead:
+ out.extend(["", lead, ""])
+ stack.append((tag, len(tag_indent) + 2, attrs(raw_attrs), None))
+ continue
+ if m := CLOSE_TAG.match(raw):
+ if stack and stack[-1][0] == m.group(2):
+ tag, _, a, body = stack.pop()
+ if body is not None:
+ out.append(
+ render_inline(
+ tag, a, " ".join(x.strip() for x in body if x.strip())
+ )
+ )
+ else:
+ out.append("")
+ continue
+
+ (sink if sink is not None else out).append(line)
+
+ text = "\n".join(out)
+ text = re.sub(r"\n{3,}", "\n\n", text)
+ return text.strip() + "\n"
+
+
+def render_open(tag: str, a: dict[str, str]) -> str:
+ if tag in CALLOUTS:
+ return f"**{CALLOUTS[tag]}**"
+ if tag in TITLED and a.get("title"):
+ return f"{TITLED[tag]} {a['title']}"
+ return ""
+
+
+def render_inline(tag: str, a: dict[str, str], inner: str, from_dir: str = "") -> str:
+ if tag == "Card":
+ title = a.get("title", "").strip()
+ href = a.get("href", "")
+ body = f" — {inner}" if inner else ""
+ return f"- [{title}]({href}){body}" if href else f"- **{title}**{body}"
+ if tag in CALLOUTS:
+ return f"**{CALLOUTS[tag]}** {inner}".rstrip()
+ if tag in TITLED and a.get("title"):
+ return f"{TITLED[tag]} {a['title']}\n\n{inner}".rstrip()
+ return inner
+
+
+def convert_page(source: Path, from_dir: str) -> str:
+ meta, body = split_frontmatter(source.read_text(encoding="utf-8"))
+ parts: list[str] = []
+ if title := meta.get("title"):
+ parts.append(f"# {title}\n")
+ if description := meta.get("description"):
+ parts.append(f"_{description}_\n")
+ parts.append(convert_body(rewrite_links(body, from_dir), from_dir))
+ return "\n".join(parts)
+
+
+def switch_pages(docs_json: dict) -> list[tuple[list[str], str]]:
+ """Every Switch page in navigation order, as (group trail, page path)."""
+ product = next(
+ (p for p in docs_json["navigation"]["products"] if p.get("product") == PRODUCT),
+ None,
+ )
+ if product is None:
+ raise SystemExit(
+ f"No {PRODUCT!r} product in docs.json — the navigation shape changed."
+ )
+
+ found: list[tuple[list[str], str]] = []
+
+ def walk(node, trail: list[str]) -> None:
+ if isinstance(node, str):
+ found.append((trail, node))
+ elif isinstance(node, list):
+ for item in node:
+ walk(item, trail)
+ elif isinstance(node, dict):
+ name = node.get("group")
+ inner = trail + [name] if name else trail
+ for key in ("groups", "pages", "tabs"):
+ if key in node:
+ walk(node[key], inner)
+
+ walk(product.get("groups", product.get("pages", [])), [])
+ return found
+
+
+def write_index(dest: Path, entries: list[tuple[list[str], str]]) -> None:
+ lines = [
+ "# Switch documentation",
+ "",
+ "The reader-facing Switch documentation, converted from the Mintlify source in",
+ f"`sandbox-quantum/docs` and published at {SITE_BASE}.",
+ "",
+ "Generated by `just sync-docs`. Do not edit these files: change the source pages",
+ "in the docs repository and run the sync again.",
+ "",
+ ]
+ current: list[str] = []
+ for trail, page in entries:
+ if trail != current:
+ current = trail
+ lines.extend(["", f"## {' › '.join(trail)}" if trail else "", ""])
+ rel = page[len(SOURCE_PREFIX) :] or "index"
+ lines.append(f"- [{rel}]({rel}.md)")
+ (dest / "INDEX.md").write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+
+def resolve_source(source: str | None, keep: Path) -> Path:
+ if source:
+ path = Path(source).expanduser().resolve()
+ if not (path / "docs.json").is_file():
+ raise SystemExit(
+ f"{path} has no docs.json — is it a checkout of the docs repository?"
+ )
+ return path
+ print(f"Cloning {DOCS_REPO_URL}", file=sys.stderr)
+ subprocess.run(
+ ["git", "clone", "--depth", "1", "--quiet", DOCS_REPO_URL, str(keep)],
+ check=True,
+ )
+ return keep
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--source",
+ help="Path to a checkout of sandbox-quantum/docs. Cloned into a temporary directory when omitted.",
+ )
+ parser.add_argument(
+ "--dest",
+ default="docs/official",
+ help="Directory to write the converted pages into. Replaced on every run.",
+ )
+ args = parser.parse_args()
+
+ repo_root = Path(__file__).resolve().parent.parent
+ dest = (repo_root / args.dest).resolve()
+
+ with tempfile.TemporaryDirectory() as tmp:
+ source = resolve_source(args.source, Path(tmp) / "docs")
+ entries = switch_pages(
+ json.loads((source / "docs.json").read_text(encoding="utf-8"))
+ )
+
+ if dest.exists():
+ shutil.rmtree(dest)
+ dest.mkdir(parents=True)
+
+ written = 0
+ missing: list[str] = []
+ for _, page in entries:
+ mdx = source / f"{page}.mdx"
+ if not mdx.is_file():
+ missing.append(page)
+ continue
+ rel = f"{page[len(SOURCE_PREFIX) :] or 'index'}.md"
+ target = dest / rel
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(
+ convert_page(mdx, posixpath.dirname(rel)), encoding="utf-8"
+ )
+ written += 1
+
+ write_index(dest, entries)
+
+ where = dest.relative_to(repo_root) if dest.is_relative_to(repo_root) else dest
+ print(f"Wrote {written} pages to {where}")
+ if missing:
+ print(
+ f"Listed in navigation but absent from the source: {', '.join(missing)}",
+ file=sys.stderr,
+ )
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())