Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
Give every synced page the address it is published at (#300)
Louis Amaudruzb0e7c545bfdd
diff --git a/docs/official/INDEX.md b/docs/official/INDEX.mdindex 3751fda25..c5f90a832 100644--- a/docs/official/INDEX.md+++ b/docs/official/INDEX.md@@ -6,73 +6,76 @@ The reader-facing Switch documentation, converted from the Mintlify source inGenerated by `just sync-docs`. Do not edit these files: change the source pagesin the docs repository and run the sync again.+Each page carries the address it is published at. Send people to that address+rather than to a path in this repository, which they cannot open.+## Overview-- [index](index.md)+- [index](index.md) — <https://docs.flintai.dev/flintai/switch>## 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)+- [getting-started/index](getting-started/index.md) — <https://docs.flintai.dev/flintai/switch/getting-started>+- [getting-started/install-switch-console](getting-started/install-switch-console.md) — <https://docs.flintai.dev/flintai/switch/getting-started/install-switch-console>+- [getting-started/add-a-server](getting-started/add-a-server.md) — <https://docs.flintai.dev/flintai/switch/getting-started/add-a-server>+- [getting-started/set-up-agent-providers](getting-started/set-up-agent-providers.md) — <https://docs.flintai.dev/flintai/switch/getting-started/set-up-agent-providers>+- [getting-started/onboard-your-agents](getting-started/onboard-your-agents.md) — <https://docs.flintai.dev/flintai/switch/getting-started/onboard-your-agents>+- [getting-started/create-a-room](getting-started/create-a-room.md) — <https://docs.flintai.dev/flintai/switch/getting-started/create-a-room>+- [getting-started/smoke-test](getting-started/smoke-test.md) — <https://docs.flintai.dev/flintai/switch/getting-started/smoke-test>## Deploy and connect-- [deploy/index](deploy/index.md)-- [deploy/host-remotely](deploy/host-remotely.md)-- [deploy/self-host](deploy/self-host.md)+- [deploy/index](deploy/index.md) — <https://docs.flintai.dev/flintai/switch/deploy>+- [deploy/host-remotely](deploy/host-remotely.md) — <https://docs.flintai.dev/flintai/switch/deploy/host-remotely>+- [deploy/self-host](deploy/self-host.md) — <https://docs.flintai.dev/flintai/switch/deploy/self-host>## 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/connect-agents/switch-console](deploy/connect-agents/switch-console.md) — <https://docs.flintai.dev/flintai/switch/deploy/connect-agents/switch-console>+- [deploy/connect-agents/standalone](deploy/connect-agents/standalone.md) — <https://docs.flintai.dev/flintai/switch/deploy/connect-agents/standalone>## 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)+- [deploy/messaging-apps/index](deploy/messaging-apps/index.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps>+- [deploy/messaging-apps/slack](deploy/messaging-apps/slack.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/slack>+- [deploy/messaging-apps/microsoft-teams](deploy/messaging-apps/microsoft-teams.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/microsoft-teams>+- [deploy/messaging-apps/mattermost](deploy/messaging-apps/mattermost.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/mattermost>+- [deploy/messaging-apps/discord](deploy/messaging-apps/discord.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/discord>+- [deploy/messaging-apps/telegram](deploy/messaging-apps/telegram.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/telegram>+- [deploy/messaging-apps/how-connections-work](deploy/messaging-apps/how-connections-work.md) — <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/how-connections-work>## 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)+- [using/index](using/index.md) — <https://docs.flintai.dev/flintai/switch/using>+- [using/mention-and-message](using/mention-and-message.md) — <https://docs.flintai.dev/flintai/switch/using/mention-and-message>+- [using/what-comes-back](using/what-comes-back.md) — <https://docs.flintai.dev/flintai/switch/using/what-comes-back>+- [using/rooms-and-agents](using/rooms-and-agents.md) — <https://docs.flintai.dev/flintai/switch/using/rooms-and-agents>+- [using/shared-context](using/shared-context.md) — <https://docs.flintai.dev/flintai/switch/using/shared-context>+- [using/hand-off-work](using/hand-off-work.md) — <https://docs.flintai.dev/flintai/switch/using/hand-off-work>+- [using/how-switch-works](using/how-switch-works.md) — <https://docs.flintai.dev/flintai/switch/using/how-switch-works>## 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)+- [building/index](building/index.md) — <https://docs.flintai.dev/flintai/switch/building>+- [building/payments-room](building/payments-room.md) — <https://docs.flintai.dev/flintai/switch/building/payments-room>+- [building/grow-into-an-organization](building/grow-into-an-organization.md) — <https://docs.flintai.dev/flintai/switch/building/grow-into-an-organization>## 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)+- [internals/index](internals/index.md) — <https://docs.flintai.dev/flintai/switch/internals>+- [internals/matrix-substrate](internals/matrix-substrate.md) — <https://docs.flintai.dev/flintai/switch/internals/matrix-substrate>+- [internals/collaboration-bridge](internals/collaboration-bridge.md) — <https://docs.flintai.dev/flintai/switch/internals/collaboration-bridge>+- [internals/agent-protocol](internals/agent-protocol.md) — <https://docs.flintai.dev/flintai/switch/internals/agent-protocol>+- [internals/connectors-and-runtime](internals/connectors-and-runtime.md) — <https://docs.flintai.dev/flintai/switch/internals/connectors-and-runtime>+- [internals/standalone-and-console](internals/standalone-and-console.md) — <https://docs.flintai.dev/flintai/switch/internals/standalone-and-console>+- [internals/life-of-a-message](internals/life-of-a-message.md) — <https://docs.flintai.dev/flintai/switch/internals/life-of-a-message>+- [internals/identity-and-access](internals/identity-and-access.md) — <https://docs.flintai.dev/flintai/switch/internals/identity-and-access>+- [internals/rooms-and-resources](internals/rooms-and-resources.md) — <https://docs.flintai.dev/flintai/switch/internals/rooms-and-resources>+- [internals/switch-console](internals/switch-console.md) — <https://docs.flintai.dev/flintai/switch/internals/switch-console>## Resources-- [resources/room-commands](resources/room-commands.md)-- [resources/troubleshooting](resources/troubleshooting.md)-- [resources/glossary](resources/glossary.md)+- [resources/room-commands](resources/room-commands.md) — <https://docs.flintai.dev/flintai/switch/resources/room-commands>+- [resources/troubleshooting](resources/troubleshooting.md) — <https://docs.flintai.dev/flintai/switch/resources/troubleshooting>+- [resources/glossary](resources/glossary.md) — <https://docs.flintai.dev/flintai/switch/resources/glossary>diff --git a/docs/official/building/grow-into-an-organization.md b/docs/official/building/grow-into-an-organization.mdindex 4891ae226..eb3bb7de5 100644--- a/docs/official/building/grow-into-an-organization.md+++ b/docs/official/building/grow-into-an-organization.md@@ -2,6 +2,8 @@_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_+Published at <https://docs.flintai.dev/flintai/switch/building/grow-into-an-organization> — link readers there, not to this file.+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.diff --git a/docs/official/building/index.md b/docs/official/building/index.mdindex 672c25ac0..52cfba102 100644--- a/docs/official/building/index.md+++ b/docs/official/building/index.md@@ -2,6 +2,8 @@_The building blocks you assemble a team of people and agents from — rooms, agents, roles and the material a room carries_+Published at <https://docs.flintai.dev/flintai/switch/building> — link readers there, not to this file.+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.diff --git a/docs/official/building/payments-room.md b/docs/official/building/payments-room.mdindex eca7598ae..c41fb9fcd 100644--- a/docs/official/building/payments-room.md+++ b/docs/official/building/payments-room.md@@ -2,6 +2,8 @@_Take one room from an empty channel to something a team can work in — instructions, material, jobs, and who's allowed to drive what_+Published at <https://docs.flintai.dev/flintai/switch/building/payments-room> — link readers there, not to this file.+## What we're buildingThe 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.diff --git a/docs/official/deploy/connect-agents/standalone.md b/docs/official/deploy/connect-agents/standalone.mdindex 4e85fb143..7d3e171a7 100644--- a/docs/official/deploy/connect-agents/standalone.md+++ b/docs/official/deploy/connect-agents/standalone.md@@ -2,6 +2,8 @@_Install the Switch connector yourself and register an agent from the command line, and what you give up by doing it that way_+Published at <https://docs.flintai.dev/flintai/switch/deploy/connect-agents/standalone> — link readers there, not to this file.+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).diff --git a/docs/official/deploy/connect-agents/switch-console.md b/docs/official/deploy/connect-agents/switch-console.mdindex 8a220abe4..fea14ae80 100644--- a/docs/official/deploy/connect-agents/switch-console.md+++ b/docs/official/deploy/connect-agents/switch-console.md@@ -2,6 +2,8 @@_The recommended way to put an agent in a room, and what Switch Console keeps doing for it afterwards_+Published at <https://docs.flintai.dev/flintai/switch/deploy/connect-agents/switch-console> — link readers there, not to this file.+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).diff --git a/docs/official/deploy/host-remotely.md b/docs/official/deploy/host-remotely.mdindex 1f7388a95..55b6fcc23 100644--- a/docs/official/deploy/host-remotely.md+++ b/docs/official/deploy/host-remotely.md@@ -2,6 +2,8 @@_Run a Switch server or an agent on a machine other than your own_+Published at <https://docs.flintai.dev/flintai/switch/deploy/host-remotely> — link readers there, not to this file.+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.diff --git a/docs/official/deploy/index.md b/docs/official/deploy/index.mdindex 00cd32d8c..33554f859 100644--- a/docs/official/deploy/index.md+++ b/docs/official/deploy/index.md@@ -2,6 +2,8 @@_Compare the ways to run a Switch server, and pick the one that fits your team_+Published at <https://docs.flintai.dev/flintai/switch/deploy> — link readers there, not to this file.+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.diff --git a/docs/official/deploy/messaging-apps/discord.md b/docs/official/deploy/messaging-apps/discord.mdindex 6e1aa15a7..b2f814b45 100644--- a/docs/official/deploy/messaging-apps/discord.md+++ b/docs/official/deploy/messaging-apps/discord.md@@ -2,6 +2,8 @@_Put your Switch agents in a Discord server, so a channel becomes a room_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/discord> — link readers there, not to this file.+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**.diff --git a/docs/official/deploy/messaging-apps/how-connections-work.md b/docs/official/deploy/messaging-apps/how-connections-work.mdindex 4e5557d39..55fbb5c15 100644--- a/docs/official/deploy/messaging-apps/how-connections-work.md+++ b/docs/official/deploy/messaging-apps/how-connections-work.md@@ -2,6 +2,8 @@_What a Switch connection does on every platform, and the things that differ once you pick one_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/how-connections-work> — link readers there, not to this file.+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.diff --git a/docs/official/deploy/messaging-apps/index.md b/docs/official/deploy/messaging-apps/index.mdindex 6a07a499e..ad6fa89bb 100644--- a/docs/official/deploy/messaging-apps/index.md+++ b/docs/official/deploy/messaging-apps/index.md@@ -2,6 +2,8 @@_Learn how to connect a Switch-compatible messaging app_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps> — link readers there, not to this file.+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.diff --git a/docs/official/deploy/messaging-apps/mattermost.md b/docs/official/deploy/messaging-apps/mattermost.mdindex 51fb04b0e..127278fc5 100644--- a/docs/official/deploy/messaging-apps/mattermost.md+++ b/docs/official/deploy/messaging-apps/mattermost.md@@ -2,6 +2,8 @@_Put your Switch agents in a Mattermost server, where each one gets a bot account of its own_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/mattermost> — link readers there, not to this file.+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**.diff --git a/docs/official/deploy/messaging-apps/microsoft-teams.md b/docs/official/deploy/messaging-apps/microsoft-teams.mdindex b2686221d..6005ccf73 100644--- a/docs/official/deploy/messaging-apps/microsoft-teams.md+++ b/docs/official/deploy/messaging-apps/microsoft-teams.md@@ -2,6 +2,8 @@_Put your Switch agents in a Teams tenant — the one platform that needs Switch publicly reachable_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/microsoft-teams> — link readers there, not to this file.+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.diff --git a/docs/official/deploy/messaging-apps/slack.md b/docs/official/deploy/messaging-apps/slack.mdindex 55c44051b..91ec5c4ce 100644--- a/docs/official/deploy/messaging-apps/slack.md+++ b/docs/official/deploy/messaging-apps/slack.md@@ -2,6 +2,8 @@_Put your Switch agents in a Slack workspace, so a channel becomes a room_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/slack> — link readers there, not to this file.+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.diff --git a/docs/official/deploy/messaging-apps/telegram.md b/docs/official/deploy/messaging-apps/telegram.mdindex 5ec707afb..4301c63b8 100644--- a/docs/official/deploy/messaging-apps/telegram.md+++ b/docs/official/deploy/messaging-apps/telegram.md@@ -2,6 +2,8 @@_Put your Switch agents in Telegram groups and channels, using one bot and one setting_+Published at <https://docs.flintai.dev/flintai/switch/deploy/messaging-apps/telegram> — link readers there, not to this file.+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**.diff --git a/docs/official/deploy/self-host.md b/docs/official/deploy/self-host.mdindex 6b0442e98..03e8c8198 100644--- a/docs/official/deploy/self-host.md+++ b/docs/official/deploy/self-host.md@@ -2,6 +2,8 @@_Deploy a Switch server yourself, then point Switch Console at it_+Published at <https://docs.flintai.dev/flintai/switch/deploy/self-host> — link readers there, not to this file.+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.diff --git a/docs/official/getting-started/add-a-server.md b/docs/official/getting-started/add-a-server.mdindex 7d690799d..692b63ef3 100644--- a/docs/official/getting-started/add-a-server.md+++ b/docs/official/getting-started/add-a-server.md@@ -2,6 +2,8 @@_Let Switch Console run a server for you, or point it at one that already exists_+Published at <https://docs.flintai.dev/flintai/switch/getting-started/add-a-server> — link readers there, not to this file.+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.diff --git a/docs/official/getting-started/create-a-room.md b/docs/official/getting-started/create-a-room.mdindex 549e33ade..052c1b6e1 100644--- a/docs/official/getting-started/create-a-room.md+++ b/docs/official/getting-started/create-a-room.md@@ -2,6 +2,8 @@_Make a room from scratch, or turn a channel your team already uses into one_+Published at <https://docs.flintai.dev/flintai/switch/getting-started/create-a-room> — link readers there, not to this file.+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.diff --git a/docs/official/getting-started/index.md b/docs/official/getting-started/index.mdindex df808acf3..dd97b3a1a 100644--- a/docs/official/getting-started/index.md+++ b/docs/official/getting-started/index.md@@ -2,6 +2,8 @@_Prepare to install and configure Switch Console_+Published at <https://docs.flintai.dev/flintai/switch/getting-started> — link readers there, not to this file.+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.diff --git a/docs/official/getting-started/install-switch-console.md b/docs/official/getting-started/install-switch-console.mdindex 096464561..55f6d4d82 100644--- a/docs/official/getting-started/install-switch-console.md+++ b/docs/official/getting-started/install-switch-console.md@@ -2,6 +2,8 @@_Install the desktop app that will help you set up and manage Switch_+Published at <https://docs.flintai.dev/flintai/switch/getting-started/install-switch-console> — link readers there, not to this file.+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**diff --git a/docs/official/getting-started/onboard-your-agents.md b/docs/official/getting-started/onboard-your-agents.mdindex de8f8c912..f0e523888 100644--- a/docs/official/getting-started/onboard-your-agents.md+++ b/docs/official/getting-started/onboard-your-agents.md@@ -2,6 +2,8 @@_Register an agent with your server so you can invite it into any room_+Published at <https://docs.flintai.dev/flintai/switch/getting-started/onboard-your-agents> — link readers there, not to this file.+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 startdiff --git a/docs/official/getting-started/set-up-agent-providers.md b/docs/official/getting-started/set-up-agent-providers.mdindex d1e3be2fa..573f1840a 100644--- a/docs/official/getting-started/set-up-agent-providers.md+++ b/docs/official/getting-started/set-up-agent-providers.md@@ -2,6 +2,8 @@_Make sure the agent providers you use are installed and can reach Switch_+Published at <https://docs.flintai.dev/flintai/switch/getting-started/set-up-agent-providers> — link readers there, not to this file.+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.diff --git a/docs/official/getting-started/smoke-test.md b/docs/official/getting-started/smoke-test.mdindex 9820e9342..62bf474cc 100644--- a/docs/official/getting-started/smoke-test.md+++ b/docs/official/getting-started/smoke-test.md@@ -2,6 +2,8 @@_Prove the installation works with one human, one agent, and one task_+Published at <https://docs.flintai.dev/flintai/switch/getting-started/smoke-test> — link readers there, not to this file.+**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:diff --git a/docs/official/index.md b/docs/official/index.mdindex 22dc28dc0..f7b19988e 100644--- a/docs/official/index.md+++ b/docs/official/index.md@@ -2,6 +2,8 @@_A governed workspace where people and agents share context, coordinate handoffs, and keep work moving over time_+Published at <https://docs.flintai.dev/flintai/switch> — link readers there, not to this file.+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.diff --git a/docs/official/internals/agent-protocol.md b/docs/official/internals/agent-protocol.mdindex 451dd2c3a..c3f77f5e5 100644--- a/docs/official/internals/agent-protocol.md+++ b/docs/official/internals/agent-protocol.md@@ -2,6 +2,8 @@_The wire protocol a Switch agent client implements — SSE down, HTTP up, every event frame and every operation_+Published at <https://docs.flintai.dev/flintai/switch/internals/agent-protocol> — link readers there, not to this file.+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 authdiff --git a/docs/official/internals/collaboration-bridge.md b/docs/official/internals/collaboration-bridge.mdindex a1b1c2ee6..88613b32c 100644--- a/docs/official/internals/collaboration-bridge.md+++ b/docs/official/internals/collaboration-bridge.md@@ -2,6 +2,8 @@_How Switch relays a messaging app into a Matrix room, and the contract you implement to add one it doesn't support_+Published at <https://docs.flintai.dev/flintai/switch/internals/collaboration-bridge> — link readers there, not to this file.+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.diff --git a/docs/official/internals/connectors-and-runtime.md b/docs/official/internals/connectors-and-runtime.mdindex cf2bdad2d..b5726dc29 100644--- a/docs/official/internals/connectors-and-runtime.md+++ b/docs/official/internals/connectors-and-runtime.md@@ -2,6 +2,8 @@_How a connector plugs an agent host into Switch, and what the local runtime process does_+Published at <https://docs.flintai.dev/flintai/switch/internals/connectors-and-runtime> — link readers there, not to this file.+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).diff --git a/docs/official/internals/identity-and-access.md b/docs/official/internals/identity-and-access.mdindex f074df30c..d44c455a7 100644--- a/docs/official/internals/identity-and-access.md+++ b/docs/official/internals/identity-and-access.md@@ -2,6 +2,8 @@_Authorization over resources, addressing policy over agents, and the identity claims that connect them_+Published at <https://docs.flintai.dev/flintai/switch/internals/identity-and-access> — link readers there, not to this file.+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.diff --git a/docs/official/internals/index.md b/docs/official/internals/index.mdindex 2dfc97d5b..f1a09cc8c 100644--- a/docs/official/internals/index.md+++ b/docs/official/internals/index.md@@ -2,6 +2,8 @@_The components of Switch, what each one is responsible for, and how they connect_+Published at <https://docs.flintai.dev/flintai/switch/internals> — link readers there, not to this file.+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.diff --git a/docs/official/internals/life-of-a-message.md b/docs/official/internals/life-of-a-message.mdindex dddcabd4f..6401ab3ee 100644--- a/docs/official/internals/life-of-a-message.md+++ b/docs/official/internals/life-of-a-message.md@@ -2,6 +2,8 @@_One message traced from a Slack channel to an agent and back, with the component responsible for each hop_+Published at <https://docs.flintai.dev/flintai/switch/internals/life-of-a-message> — link readers there, not to this file.+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 pathdiff --git a/docs/official/internals/matrix-substrate.md b/docs/official/internals/matrix-substrate.mdindex b7e456f1b..98dd64f0f 100644--- a/docs/official/internals/matrix-substrate.md+++ b/docs/official/internals/matrix-substrate.md@@ -2,6 +2,8 @@_How every participant becomes a Matrix client, how those clients sync and resume, and the events Switch layers on top_+Published at <https://docs.flintai.dev/flintai/switch/internals/matrix-substrate> — link readers there, not to this file.+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 accountdiff --git a/docs/official/internals/rooms-and-resources.md b/docs/official/internals/rooms-and-resources.mdindex 4b902750c..5eee8fcb8 100644--- a/docs/official/internals/rooms-and-resources.md+++ b/docs/official/internals/rooms-and-resources.md@@ -2,6 +2,8 @@_The developer's view of the resource model and the room lifecycle — what's scoped where, and the ordering that matters_+Published at <https://docs.flintai.dev/flintai/switch/internals/rooms-and-resources> — link readers there, not to this file.+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).diff --git a/docs/official/internals/standalone-and-console.md b/docs/official/internals/standalone-and-console.mdindex 15dd25a50..a5cee5d4d 100644--- a/docs/official/internals/standalone-and-console.md+++ b/docs/official/internals/standalone-and-console.md@@ -2,6 +2,8 @@_The two ways an agent gets connected: register it yourself, or let Switch Console do it_+Published at <https://docs.flintai.dev/flintai/switch/internals/standalone-and-console> — link readers there, not to this file.+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.diff --git a/docs/official/internals/switch-console.md b/docs/official/internals/switch-console.mdindex 15b7c5e2a..95fc8c91d 100644--- a/docs/official/internals/switch-console.md+++ b/docs/official/internals/switch-console.md@@ -2,6 +2,8 @@_The desktop app that starts agent sessions on demand, holds their local state, and reports what they can be told to do_+Published at <https://docs.flintai.dev/flintai/switch/internals/switch-console> — link readers there, not to this file.+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.diff --git a/docs/official/resources/glossary.md b/docs/official/resources/glossary.mdindex 72e0ca826..c30bfff49 100644--- a/docs/official/resources/glossary.md+++ b/docs/official/resources/glossary.md@@ -2,6 +2,8 @@_Switch terms and what they mean_+Published at <https://docs.flintai.dev/flintai/switch/resources/glossary> — link readers there, not to this file.+Switch borrows several words your messaging app already uses, and means somethingnarrower by most of them. This page is the one definition of each.diff --git a/docs/official/resources/room-commands.md b/docs/official/resources/room-commands.mdindex 66802f8b2..bffabc1d6 100644--- a/docs/official/resources/room-commands.md+++ b/docs/official/resources/room-commands.md@@ -2,6 +2,8 @@_Every command you can run in a Switch room, and when to reach for it_+Published at <https://docs.flintai.dev/flintai/switch/resources/room-commands> — link readers there, not to this file.+A command is a short instruction you type into the channel, and Switch acts onit directly. Use one to see what is in a room, bring an agent in, or take holdof an agent's session when it is stuck.diff --git a/docs/official/resources/troubleshooting.md b/docs/official/resources/troubleshooting.mdindex eb7763616..ad0ad72df 100644--- a/docs/official/resources/troubleshooting.md+++ b/docs/official/resources/troubleshooting.md@@ -2,6 +2,8 @@_Fast fixes for connecting, running an agent, and working in a room_+Published at <https://docs.flintai.dev/flintai/switch/resources/troubleshooting> — link readers there, not to this file.+**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**diff --git a/docs/official/using/hand-off-work.md b/docs/official/using/hand-off-work.mdindex 2dfc76e2f..198ff5790 100644--- a/docs/official/using/hand-off-work.md+++ b/docs/official/using/hand-off-work.md@@ -2,6 +2,8 @@_Address a function rather than a particular agent, and give work that outlives a message_+Published at <https://docs.flintai.dev/flintai/switch/using/hand-off-work> — link readers there, not to this file.+Most of this section is about a conversation. This page is about the work thatoutlives one: reaching whoever is doing a job without knowing who that is today,and handing over something you expect back later.diff --git a/docs/official/using/how-switch-works.md b/docs/official/using/how-switch-works.mdindex 774a14122..877f19da1 100644--- a/docs/official/using/how-switch-works.md+++ b/docs/official/using/how-switch-works.md@@ -2,6 +2,8 @@_The room, the agent, and the session — what each one is and which one answers you_+Published at <https://docs.flintai.dev/flintai/switch/using/how-switch-works> — link readers there, not to this file.+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 agentdiff --git a/docs/official/using/index.md b/docs/official/using/index.mdindex 179924ba5..84ef5c918 100644--- a/docs/official/using/index.md+++ b/docs/official/using/index.md@@ -2,6 +2,8 @@_What a Switch room is, and how it differs from any other group chat_+Published at <https://docs.flintai.dev/flintai/switch/using> — link readers there, not to this file.+**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 likediff --git a/docs/official/using/mention-and-message.md b/docs/official/using/mention-and-message.mdindex a9e1558d0..d949dd147 100644--- a/docs/official/using/mention-and-message.md+++ b/docs/official/using/mention-and-message.md@@ -2,6 +2,8 @@_Address an agent so it acts, practice the ways an address misses, and send a command_+Published at <https://docs.flintai.dev/flintai/switch/using/mention-and-message> — link readers there, not to this file.+**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.diff --git a/docs/official/using/rooms-and-agents.md b/docs/official/using/rooms-and-agents.mdindex e32e12979..df8090663 100644--- a/docs/official/using/rooms-and-agents.md+++ b/docs/official/using/rooms-and-agents.md@@ -2,6 +2,8 @@_See who is in a Switch room, give an agent a short name, and add people and agents to the room_+Published at <https://docs.flintai.dev/flintai/switch/using/rooms-and-agents> — link readers there, not to this file.+**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?diff --git a/docs/official/using/shared-context.md b/docs/official/using/shared-context.mdindex c7c4c3b7c..a247a6d3b 100644--- a/docs/official/using/shared-context.md+++ b/docs/official/using/shared-context.md@@ -2,6 +2,8 @@_Shared context is everything a room holds — documents, resources, and agents — and it compounds as the team works_+Published at <https://docs.flintai.dev/flintai/switch/using/shared-context> — link readers there, not to this file.+**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 knowsdiff --git a/docs/official/using/what-comes-back.md b/docs/official/using/what-comes-back.mdindex ee0d2daf0..d28fc3d3f 100644--- a/docs/official/using/what-comes-back.md+++ b/docs/official/using/what-comes-back.md@@ -2,6 +2,8 @@_Read what comes back — an answer, an unavailable reply, silence, or a refusal — and know what each one means_+Published at <https://docs.flintai.dev/flintai/switch/using/what-comes-back> — link readers there, not to this file.+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.diff --git a/scripts/sync_docs.py b/scripts/sync_docs.pyindex 71ea09cf4..4ad0cb5e1 100644--- a/scripts/sync_docs.py+++ b/scripts/sync_docs.py@@ -189,13 +189,21 @@ def render_inline(tag: str, a: dict[str, str], inner: str, from_dir: str = "") -return inner-def convert_page(source: Path, from_dir: str) -> str:+def published_url(page: str) -> str:+ """The address this page is served at, so a reader can be sent to it."""+ return f"{SITE_BASE}/{page.removesuffix('/index')}"+++def convert_page(source: Path, page: str, 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(+ f"Published at <{published_url(page)}> — link readers there, not to this file.\n"+ )parts.append(convert_body(rewrite_links(body, from_dir), from_dir))return "\n".join(parts)@@ -240,6 +248,9 @@ def write_index(dest: Path, entries: list[tuple[list[str], str]]) -> None:"Generated by `just sync-docs`. Do not edit these files: change the source pages","in the docs repository and run the sync again.","",+ "Each page carries the address it is published at. Send people to that address",+ "rather than to a path in this repository, which they cannot open.",+ "",]current: list[str] = []for trail, page in entries:@@ -247,7 +258,7 @@ def write_index(dest: Path, entries: list[tuple[list[str], str]]) -> None:current = traillines.extend(["", f"## {' › '.join(trail)}" if trail else "", ""])rel = page[len(SOURCE_PREFIX) :] or "index"- lines.append(f"- [{rel}]({rel}.md)")+ lines.append(f"- [{rel}]({rel}.md) — <{published_url(page)}>")(dest / "INDEX.md").write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")@@ -304,7 +315,7 @@ def main() -> int:target = dest / reltarget.parent.mkdir(parents=True, exist_ok=True)target.write_text(- convert_page(mdx, posixpath.dirname(rel)), encoding="utf-8"+ convert_page(mdx, page, posixpath.dirname(rel)), encoding="utf-8")written += 1