Skip to content

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

feat(docs): point every docs link at the published documentation site (CHOO-2313) (#273)

Louis Amaudruz2e2addf077b2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
#### Added
diff --git a/README.md b/README.md
index 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: 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)](docs/)
+[![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)
</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.md
index 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) — which
rooms 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.tsx
index 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.tsx
index 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() {
<button
type="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.tsx
index 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 RemoteHostsSettingsPage
type="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.tsx
index 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/r
import { 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.ts
index 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.ts
index 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): stri
return 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.ts
index 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.md
index 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 is
prescriptive 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.tsx
index 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();