chore: final nits

Author: didinele

apps/website/src/app/dashboard/_components/DashboardLinkErrorNotice.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { useEffect, useRef } from 'react';
+import { pushErrorBanner } from '@/api/errorBanner';
+
+const MESSAGES = {
+	expired: 'That /dashboard link expired (links only last 2 minutes) - run /dashboard again for a new one.',
+	used: 'That /dashboard link has already been used - run /dashboard again for a new one.',
+	forbidden: "You don't have permission to manage that server.",
+	unavailable: 'Something went wrong opening that /dashboard link. Please try again in a moment.',
+} as const;
+
+/**
+ * Surfaces `GET /v3/auth/dashboard`'s (`services/api/src/routes/auth/dashboardLink.ts`) failure bounces --
+ * it 302s here with `?dashboard_link_error=...` rather than a JSON body, since the exchange happens outside
+ * any page the user is looking at. Renders nothing itself; pushes a dismissible toast (`ErrorBanner`, mounted
+ * globally in `Providers`) and strips the query param so a refresh doesn't re-fire it.
+ */
+export function DashboardLinkErrorNotice() {
+	const searchParams = useSearchParams();
+	const router = useRouter();
+	const pathname = usePathname();
+	const handled = useRef(false);
+
+	const error = searchParams.get('dashboard_link_error');
+
+	useEffect(() => {
+		if (!error || handled.current) {
+			return;
+		}
+
+		handled.current = true;
+		pushErrorBanner(error in MESSAGES ? MESSAGES[error as keyof typeof MESSAGES] : MESSAGES.unavailable);
+		router.replace(pathname);
+	}, [error, pathname, router]);
+
+	return null;
+}

apps/website/src/app/dashboard/page.tsx

@@ -1,4 +1,5 @@
 import type { Metadata } from 'next';
+import { DashboardLinkErrorNotice } from './_components/DashboardLinkErrorNotice';
 import { GuildList } from './_components/GuildList';
 import { RefreshGuildsButton } from './_components/RefreshGuildsButton';
 import { Heading } from '@/components/common/Heading';
@@ -11,6 +12,7 @@ export const metadata: Metadata = {
 export default function DashboardPage() {
 	return (
 		<>
+			<DashboardLinkErrorNotice />
 			<div className="flex flex-col [&>*:not(:first-of-type)]:mt-8 [&>*]:first-of-type:mb-4">
 				<div className="flex flex-col items-start justify-between gap-4 md:flex-row md:items-center">
 					<Heading subtitle="Select or add a community to manage." title="Configure bots" />

docs/roadmap/01-architecture.md

@@ -191,15 +191,16 @@ command — identical on every bot, registered automatically by `createBotClient
 to one guild, rather than a token authorizing one specific action. Past the exchange there is a single auth code
 path: a scoped session flows through exactly the same `isAuthed` logic as a real OAuth session.
 
-- **`/dashboard open`**: mints a short-lived (~2 min), single-use `DashboardLinkTokenData` JWT (`{ kind:
-'dashboard-link', sub, guildId, jti, iat }`, `packages/private/backend-core/src/lib/dashboardSession.ts`) and
-  replies ephemerally with a spoilered link to `GET {API_URL}/v3/auth/dashboard?token=...` — the link points at the
-  API, not the dashboard, so the token is only ever in the URL for that one initial request; the exchange consumes
-  it and 302s to a clean `/dashboard/:guildId` URL with nothing in it, unlike the token itself ending up in the
-  dashboard's own address bar for the whole visit the way the old grant tokens did. The reply text warns that the
-  link expires in 2 minutes and is single-use, the session it grants lasts 30 minutes with full guild-manager
-  access to that one guild, and — if the user is already logged in normally in that browser — opening it will
-  replace their session. `/dashboard revoke` ends every live scoped session for the caller in that guild
+- **`/dashboard open`**: mints a short-lived (~2 min), best-effort-single-use (see the claim-durability note below)
+  `DashboardLinkTokenData` JWT (`{ kind: 'dashboard-link', sub, guildId, jti, iat }`,
+  `packages/private/backend-core/src/lib/dashboardSession.ts`) and replies ephemerally with a spoilered link to
+  `GET {API_URL}/v3/auth/dashboard?token=...` — the link points at the API, not the dashboard, so the token is
+  only ever in the URL for that one initial request; the exchange consumes it and 302s to a clean
+  `/dashboard/:guildId` URL with nothing in it, unlike the token itself ending up in the dashboard's own address
+  bar for the whole visit the way the old grant tokens did. The reply text warns that the link expires in 2
+  minutes and is meant to be used once, the session it grants lasts 30 minutes with full guild-manager access to
+  that one guild, and — if the user is already logged in normally in that browser — opening it will replace their
+  session. `/dashboard revoke` ends every live scoped session for the caller in that guild
   (`revokeDashboardSessionsFor`).
 - **Exchange** (`services/api/src/routes/auth/dashboardLink.ts`, no `isAuthed` — there's no session yet):
   verifies + atomically claims the link token (`claimDashboardLinkToken`, `SET ... NX`, same one-time-use pattern