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
feat(docs): point every docs link at the published documentation site (CHOO-2313) (#273)
Louis Amaudruz2e2addf077b2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0ff4a8e50..122b46037 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -44,6 +44,10 @@ version of their own to them without also giving them a release of their own.### [Unreleased]+#### Changed+- The gateway's **Docs** button opens the published documentation at+ `docs.flintai.dev` rather than the GitHub repository (CHOO-2313).+### [0.18.0] - 2026-08-21#### Added@@ -687,6 +691,20 @@ version of their own to them without also giving them a release of their own.### [Unreleased]+#### Changed+- Every **Docs** affordance opens the published documentation at+ `docs.flintai.dev` instead of the GitHub repository, deep-linked to the page+ that answers the question: the sidebar and app-menu Docs entries and the+ Settings Docs tab go to getting-started, the remote-hosts hint and the+ hosting cards to *Host remotely*, the messaging-app cards to *Messaging+ apps*, and the Rooms card to *Rooms and agents*. The welcome footer's GitHub+ link keeps pointing at the repository (CHOO-2313).+- The "How to set up {Platform}" link on the connect-messaging-app form opens+ the platform's published setup page — Slack, Mattermost, Discord, Microsoft+ Teams or Telegram — rather than the repository's markdown, with the+ messaging-apps index as the fallback for an unrecognised platform+ (CHOO-2313, unblocking CHOO-2269).+### [0.28.0] - 2026-08-21#### Addeddiff --git a/README.md b/README.mdindex 925261809..1fbac749d 100644--- a/README.md+++ b/README.md@@ -9,7 +9,7 @@**Create organizations where AI agents and humans work side by side.**[](LICENSE)-[](docs/)+[](https://docs.flintai.dev/flintai/switch/getting-started)[](CONTRIBUTING.md)</div>@@ -177,6 +177,18 @@ Module layout under `core/switch_core/`:The operator dashboard frontend lives in [`gateway/`](gateway/)(Node/Vite, served via nginx).+## Documentation++User-facing documentation is published at+**[docs.flintai.dev](https://docs.flintai.dev/flintai/switch/getting-started)** —+installing Switch Console, adding a server, onboarding agents, creating rooms,+[connecting a messaging app](https://docs.flintai.dev/flintai/switch/deploy/messaging-apps)+and [hosting remotely](https://docs.flintai.dev/flintai/switch/deploy/host-remotely).++Design and protocol references for contributors live in [`docs/`](docs/):+[`ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the system overview and+[`api/AGENT_PROTOCOL.md`](docs/api/AGENT_PROTOCOL.md) for the agent protocol.+## Repository layout| Path | Contents |diff --git a/console/README.md b/console/README.mdindex 5a8aadd0d..b7d7a9eb5 100644--- a/console/README.md+++ b/console/README.md@@ -5,6 +5,10 @@ coding-agent sessions that participate in [Agent Switch](../README.md) — whichrooms an agent belongs to, its configuration (working directory, identity),and the scheduling that starts and drives its sessions.-> **Note:** a full install guide and user documentation are coming as part of-> the docs effort. For now, see [`console/AGENTS.md`](AGENTS.md) for developer-> notes on working in the app.+## Documentation++- [Install Switch Console](https://docs.flintai.dev/flintai/switch/getting-started/install-switch-console)+ — the published install guide.+- [Setting up Switch](https://docs.flintai.dev/flintai/switch/getting-started) —+ user documentation for the whole product.+- [`console/AGENTS.md`](AGENTS.md) — developer notes on working in the app.diff --git a/console/apps/switch-console-desktop/src/renderer/features/onboarding/onboarding-checklist.tsx b/console/apps/switch-console-desktop/src/renderer/features/onboarding/onboarding-checklist.tsxindex 255be26a6..6cbd0e78d 100644--- a/console/apps/switch-console-desktop/src/renderer/features/onboarding/onboarding-checklist.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/onboarding/onboarding-checklist.tsx@@ -4,7 +4,11 @@ import { openExternalUrl } from '@renderer/lib/open-external';import { SectionLabel } from '@renderer/lib/ui/label';import { cn } from '@renderer/utils/utils';import type { OnboardingStep, OnboardingStepId } from '@shared/core/onboarding/checklist';-import { SWITCH_CONSOLE_DOCS_URL } from '@shared/urls';+import {+ SWITCH_DOCS_MESSAGING_APPS_URL,+ SWITCH_DOCS_REMOTE_HOSTING_URL,+ SWITCH_DOCS_ROOMS_URL,+} from '@shared/urls';/*** The first-run setup checklist (CHOO-2022), in two shapes:@@ -18,26 +22,22 @@ import { SWITCH_CONSOLE_DOCS_URL } from '@shared/urls';* land on the welcome screen.*/-/**- * Where "Learn more" points, for now. These are placeholders agreed with the- * dev on CHOO-2022: the docs site does not exist yet, so all three go to the- * repository README rather than to a dead page. Repoint them when it does.- */+/** Where "Learn more" points. Mirrors the welcome screen's shelf. */const LEARN_MORE_LINKS: { label: string; linkText: string; url: string }[] = [{label: 'Remote or cloud ',linkText: 'hosting',- url: SWITCH_CONSOLE_DOCS_URL,+ url: SWITCH_DOCS_REMOTE_HOSTING_URL,},{label: 'Connect to ',linkText: 'messaging apps',- url: SWITCH_CONSOLE_DOCS_URL,+ url: SWITCH_DOCS_MESSAGING_APPS_URL,},{label: 'Best ways to use ',linkText: 'Rooms',- url: SWITCH_CONSOLE_DOCS_URL,+ url: SWITCH_DOCS_ROOMS_URL,},];diff --git a/console/apps/switch-console-desktop/src/renderer/features/onboarding/welcome-learn-more.tsx b/console/apps/switch-console-desktop/src/renderer/features/onboarding/welcome-learn-more.tsxindex f6ff8ed1f..0dc8e65e5 100644--- a/console/apps/switch-console-desktop/src/renderer/features/onboarding/welcome-learn-more.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/onboarding/welcome-learn-more.tsx@@ -1,19 +1,19 @@import { ArrowUpRight } from 'lucide-react';import { openExternalUrl } from '@renderer/lib/open-external';import { SectionLabel } from '@renderer/lib/ui/label';-import { SWITCH_CONSOLE_DOCS_URL } from '@shared/urls';+import {+ SWITCH_CONSOLE_DOCS_URL,+ SWITCH_CONSOLE_REPO_URL,+ SWITCH_DOCS_MESSAGING_APPS_URL,+ SWITCH_DOCS_REMOTE_HOSTING_URL,+ SWITCH_DOCS_ROOMS_URL,+} from '@shared/urls';-/**- * The welcome screen's "Learn more" shelf (CHOO-2022).- *- * Every card points at the repository README for now — the docs site does not- * exist yet, and a card that opens nothing is worse than one that opens the- * README. Give each its own URL when there is one.- */+/** The welcome screen's "Learn more" shelf (CHOO-2022). */const LEARN_MORE_CARDS: { title: string; url: string }[] = [- { title: 'Hosting Switch on a SSH device or a cloud', url: SWITCH_CONSOLE_DOCS_URL },- { title: 'Connecting to message apps', url: SWITCH_CONSOLE_DOCS_URL },- { title: 'Best ways to use Rooms', url: SWITCH_CONSOLE_DOCS_URL },+ { title: 'Hosting Switch on a SSH device or a cloud', url: SWITCH_DOCS_REMOTE_HOSTING_URL },+ { title: 'Connecting to message apps', url: SWITCH_DOCS_MESSAGING_APPS_URL },+ { title: 'Best ways to use Rooms', url: SWITCH_DOCS_ROOMS_URL },];export function WelcomeLearnMore() {@@ -69,7 +69,7 @@ export function WelcomeFooter() {<buttontype="button"className="hover:text-foreground"- onClick={() => openExternalUrl(SWITCH_CONSOLE_DOCS_URL, 'Could not open the repository')}+ onClick={() => openExternalUrl(SWITCH_CONSOLE_REPO_URL, 'Could not open the repository')}>GitHub</button>diff --git a/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/views/remote-hosts-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/views/remote-hosts-view.tsxindex fed7407ad..dd3783789 100644--- a/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/views/remote-hosts-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/views/remote-hosts-view.tsx@@ -29,14 +29,12 @@ import { ToggleGroup, ToggleGroupItem } from '@renderer/lib/ui/toggle-group';import { log } from '@renderer/utils/logger';import { deriveHostStatus, type HostStatus } from '@shared/core/remote-hosts/host-status';import type { HostSetupPlan } from '@shared/core/remote-hosts/setup';+import { SWITCH_DOCS_REMOTE_HOSTING_URL } from '@shared/urls';import { hostReachabilityStore } from '../host-reachability-store';import { useAllHostSetupPlans } from '../setup/use-host-setup';export const REMOTE_HOSTS_QUERY_KEY = ['remote-hosts'];-/** Same destination as the Docs tab in Settings, until a cloud-hosting page exists to point at. */-const CLOUD_HOSTING_DOC_URL = 'https://github.com/sandbox-quantum/switch';-type HostFilter = 'all' | 'ready' | 'attention';type RemoteHost = { sshHost: string; name: string };@@ -171,7 +169,10 @@ export const RemoteHostsSettingsPage = observer(function RemoteHostsSettingsPagetype="button"className="cursor-pointer underline underline-offset-2 hover:text-foreground"onClick={() =>- void openExternalUrl(CLOUD_HOSTING_DOC_URL, 'Could not open the documentation')+ void openExternalUrl(+ SWITCH_DOCS_REMOTE_HOSTING_URL,+ 'Could not open the documentation'+ )}>doc for cloud hosting ↗︎diff --git a/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx b/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsxindex 2a3e4126a..596b75d80 100644--- a/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx@@ -3,6 +3,7 @@ import { RemoteHostsSettingsPage } from '@renderer/features/remote-hosts/views/rimport { PageHeader } from '@renderer/lib/components/page-header';import { PageContent, PageLayout, PageSidebarMenu } from '@renderer/lib/components/page-layout';import { openExternalUrl } from '@renderer/lib/open-external';+import { SWITCH_CONSOLE_DOCS_URL } from '@shared/urls';import { AgentsSettingsPage } from '../agents-page/AgentsSettingsPage';import NotificationSettingsCard from './NotificationSettingsCard';import { OnboardingChecklistRow } from './OnboardingSettingsRow';@@ -101,10 +102,7 @@ export function SettingsPage({onTabChange: (tab: SettingsPageTab) => void;}) {const handleDocsClick = useCallback(() => {- void openExternalUrl(- 'https://github.com/sandbox-quantum/switch',- 'Could not open the documentation'- );+ void openExternalUrl(SWITCH_CONSOLE_DOCS_URL, 'Could not open the documentation');}, []);const tabs: Array<{diff --git a/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.test.ts b/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.test.tsindex 9459a0827..26dd52315 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.test.ts+++ b/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.test.ts@@ -2,6 +2,7 @@ import { existsSync, readdirSync } from 'node:fs';import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, it } from 'vitest';+import { SWITCH_DOCS_MESSAGING_APPS_URL } from '@shared/urls';import { hasBridgeIcon } from './bridge-icon';import { bridgePlatformLabel, bridgeSetupDocsUrl } from './bridge-platform';@@ -13,9 +14,6 @@ const BRIDGE_ICON_DIR = join('../../../assets/images/bridges');-/** Repo root, for checking the setup guides the docs links point at. */-const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../../../../../..');-describe('bridgePlatformLabel', () => {it('names each platform the way its own docs do', () => {expect(bridgePlatformLabel('slack')).toBe('Slack');@@ -38,23 +36,23 @@ describe('bridgePlatformLabel', () => {});describe('bridgeSetupDocsUrl', () => {- it('points at the per-platform setup guide', () => {- expect(bridgeSetupDocsUrl('slack')).toMatch(/docs\/bridges\/SLACK_SETUP\.md$/);- expect(bridgeSetupDocsUrl('teams')).toMatch(/docs\/bridges\/TEAMS_SETUP\.md$/);+ it('points at the per-platform page on the documentation site', () => {+ expect(bridgeSetupDocsUrl('slack')).toBe(`${SWITCH_DOCS_MESSAGING_APPS_URL}/slack`);+ // `teams` is published under its full name, so the bridge key is not a+ // usable slug — the one mapping in here that is not the identity.+ expect(bridgeSetupDocsUrl('teams')).toBe(`${SWITCH_DOCS_MESSAGING_APPS_URL}/microsoft-teams`);});it('falls back to the index rather than a dead link', () => {- expect(bridgeSetupDocsUrl('zulip')).toMatch(/docs\/bridges\/README\.md$/);+ expect(bridgeSetupDocsUrl('zulip')).toBe(SWITCH_DOCS_MESSAGING_APPS_URL);});- it.each(BRIDGE_TYPES)('the guide linked for %s exists in the repo', (type) => {- // The links are repo paths for now, so a renamed or moved guide should- // fail here rather than 404 for a user mid-setup.- const path = bridgeSetupDocsUrl(type).replace(- 'https://github.com/sandbox-quantum/switch/blob/main/',- ''- );- expect(existsSync(join(REPO_ROOT, path))).toBe(true);+ it.each(BRIDGE_TYPES)('%s has its own page rather than the index', (type) => {+ // Falling back is right for a bridge type this build has never heard of,+ // but silently doing it for one we ship is a mapping we forgot to add.+ const url = bridgeSetupDocsUrl(type);+ expect(url).not.toBe(SWITCH_DOCS_MESSAGING_APPS_URL);+ expect(url.startsWith(`${SWITCH_DOCS_MESSAGING_APPS_URL}/`)).toBe(true);});});diff --git a/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.ts b/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.tsindex b95d3aa1a..d08a0accb 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.ts+++ b/console/apps/switch-console-desktop/src/renderer/lib/components/bridge-platform.ts@@ -1,3 +1,5 @@+import { SWITCH_DOCS_MESSAGING_APPS_URL } from '@shared/urls';+/*** Display names and setup guides for collaboration bridge platforms, keyed by* the gateway's `bridge_type`.@@ -24,23 +26,20 @@ export function bridgePlatformLabel(bridgeType: string | null | undefined): strireturn PLATFORM_LABELS[bridgeType] ?? bridgeType;}-/** Where the setup guides live. */-const DOCS_BASE = 'https://github.com/sandbox-quantum/switch/blob/main/docs/bridges';-/*** Per-platform setup guide, for the "how do I get these credentials" link on* the attach form.*- * These point at the repository's own markdown on `main`, which is a stopgap:- * they are expected to move to published documentation, so they are collected- * here rather than spread through the JSX — changing them later is one edit.+ * The slugs are the documentation site's, not the bridge keys: `teams` is+ * published as `microsoft-teams`. Collected here rather than spread through the+ * JSX so the mapping is checkable in one place.*/const PLATFORM_DOCS: Record<string, string> = {- slack: `${DOCS_BASE}/SLACK_SETUP.md`,- mattermost: `${DOCS_BASE}/MATTERMOST_SETUP.md`,- discord: `${DOCS_BASE}/DISCORD_SETUP.md`,- teams: `${DOCS_BASE}/TEAMS_SETUP.md`,- telegram: `${DOCS_BASE}/TELEGRAM_SETUP.md`,+ slack: `${SWITCH_DOCS_MESSAGING_APPS_URL}/slack`,+ mattermost: `${SWITCH_DOCS_MESSAGING_APPS_URL}/mattermost`,+ discord: `${SWITCH_DOCS_MESSAGING_APPS_URL}/discord`,+ teams: `${SWITCH_DOCS_MESSAGING_APPS_URL}/microsoft-teams`,+ telegram: `${SWITCH_DOCS_MESSAGING_APPS_URL}/telegram`,};/**@@ -49,5 +48,5 @@ const PLATFORM_DOCS: Record<string, string> = {* a link that lands somewhere useful instead of a 404.*/export function bridgeSetupDocsUrl(bridgeType: string): string {- return PLATFORM_DOCS[bridgeType] ?? `${DOCS_BASE}/README.md`;+ return PLATFORM_DOCS[bridgeType] ?? SWITCH_DOCS_MESSAGING_APPS_URL;}diff --git a/console/apps/switch-console-desktop/src/shared/urls.ts b/console/apps/switch-console-desktop/src/shared/urls.tsindex 4392aa951..9b49947cf 100644--- a/console/apps/switch-console-desktop/src/shared/urls.ts+++ b/console/apps/switch-console-desktop/src/shared/urls.ts@@ -1,4 +1,7 @@-export const SWITCH_CONSOLE_RELEASES_URL = 'https://github.com/sandbox-quantum/switch/releases';+/** The source repository. Not documentation — see {@link SWITCH_CONSOLE_DOCS_URL}. */+export const SWITCH_CONSOLE_REPO_URL = 'https://github.com/sandbox-quantum/switch';++export const SWITCH_CONSOLE_RELEASES_URL = `${SWITCH_CONSOLE_REPO_URL}/releases`;const SWITCH_CONSOLE_RELEASES_API_URL ='https://api.github.com/repos/sandbox-quantum/switch/releases';@@ -24,7 +27,17 @@ export function switchConsoleReleaseUrl(version: string | undefined): string {export function switchConsoleReleaseApiUrl(version: string): string {return `${SWITCH_CONSOLE_RELEASES_API_URL}/tags/${switchConsoleReleaseTag(version)}`;}-export const SWITCH_CONSOLE_DOCS_URL = 'https://github.com/sandbox-quantum/switch';-export const SWITCH_CONSOLE_ISSUES_URL = 'https://github.com/sandbox-quantum/switch/issues';-export const SWITCH_CONSOLE_ISSUES_NEW_URL =- 'https://github.com/sandbox-quantum/switch/issues/new/choose';+/**+ * The published documentation site. Deep-link to the page that answers the+ * question at hand; {@link SWITCH_CONSOLE_DOCS_URL} is the entry point for a+ * bare "Docs" affordance that is not about anything in particular.+ */+const SWITCH_DOCS_BASE = 'https://docs.flintai.dev/flintai/switch';++export const SWITCH_CONSOLE_DOCS_URL = `${SWITCH_DOCS_BASE}/getting-started`;+export const SWITCH_DOCS_REMOTE_HOSTING_URL = `${SWITCH_DOCS_BASE}/deploy/host-remotely`;+export const SWITCH_DOCS_MESSAGING_APPS_URL = `${SWITCH_DOCS_BASE}/deploy/messaging-apps`;+export const SWITCH_DOCS_ROOMS_URL = `${SWITCH_DOCS_BASE}/using/rooms-and-agents`;++export const SWITCH_CONSOLE_ISSUES_URL = `${SWITCH_CONSOLE_REPO_URL}/issues`;+export const SWITCH_CONSOLE_ISSUES_NEW_URL = `${SWITCH_CONSOLE_REPO_URL}/issues/new/choose`;diff --git a/gateway/README.md b/gateway/README.mdindex 5f945f07c..ec70b8922 100644--- a/gateway/README.md+++ b/gateway/README.md@@ -19,4 +19,7 @@ a copy of `hoot.css` plus that command. The formatting conventions Hoot isprescriptive about (dates, numbers, empty values, identifiers) live in`src/theme/hootFormat.ts`.-> **Note:** full documentation is coming as part of the docs effort.+## Documentation++User-facing documentation for Switch is published at+[docs.flintai.dev](https://docs.flintai.dev/flintai/switch/getting-started).diff --git a/gateway/src/layout/TopBar.tsx b/gateway/src/layout/TopBar.tsxindex 39ffbf1af..5e7ba07a4 100644--- a/gateway/src/layout/TopBar.tsx+++ b/gateway/src/layout/TopBar.tsx@@ -12,7 +12,7 @@ const SECTION_LABELS: [prefix: string, label: string][] = [["/users", "Users"],];-const DOCS_URL = "https://github.com/sandbox-quantum/switch";+const DOCS_URL = "https://docs.flintai.dev/flintai/switch/getting-started";export default function TopBar() {const { pathname } = useLocation();