🙌 OpenHands: AI-Driven Development
feat(onboarding): show the Super Admin setup guide on enterprise backends (#17969)
Hiep Lefd093cd554ac
diff --git a/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx b/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsxnew file mode 100644index 0000000000..7176dc3c90--- /dev/null+++ b/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx@@ -0,0 +1,342 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { render, screen, waitFor } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { http, HttpResponse } from "msw";+import {+ __resetActiveStoreForTests,+ setActiveSelection,+ setRegisteredBackends,+} from "#/api/backend-registry/active-store";+import type { Backend } from "#/api/backend-registry/types";+import type { CloudSetupGuideSteps } from "#/api/cloud/types";+import SuperAdminSetupGuide from "#/components/features/setup-guide/super-admin-setup-guide";+import { NavigationProvider } from "#/context/navigation-context";+import { ActiveBackendProvider } from "#/contexts/active-backend-context";+import { I18nKey } from "#/i18n/declaration";+import { server } from "#/mocks/node";++const CLOUD_HOST = "https://ohe.example.com";+const GUIDE_ORG_ID = "org-1";++const cloudBackend: Backend = {+ id: "cloud-1",+ name: "OHE",+ host: CLOUD_HOST,+ apiKey: "",+ kind: "cloud",+};++const localBackend: Backend = {+ id: "local-1",+ name: "Local",+ host: "http://localhost:8000",+ apiKey: "local-key",+ kind: "local",+};++function guideState(steps: Partial<CloudSetupGuideSteps> = {}) {+ return {+ wizard_pending: false,+ guide_org_id: GUIDE_ORG_ID,+ guide_dismissed: false,+ guide_steps: {+ org_llm: false,+ mcp_server: false,+ automation: false,+ invite: false,+ ...steps,+ },+ };+}++/**+ * Serves `/me` and the setup state for the cloud host and counts the+ * requests, so cases can assert who asks the server for a guide.+ */+function serveSetupGuide({+ permissions = ["manage_super_admins"],+ setupState = () => HttpResponse.json(guideState()),+}: {+ permissions?: string[];+ setupState?: () => Response;+} = {}) {+ const requests = { me: 0, setupState: 0 };+ server.use(+ http.get("*/api/organizations/:orgId/me", ({ params }) => {+ requests.me += 1;+ return HttpResponse.json({+ org_id: params.orgId,+ user_id: "user-1",+ role: "owner",+ permissions,+ });+ }),+ http.get("*/api/admin/setup-state", () => {+ requests.setupState += 1;+ return setupState();+ }),+ );+ return requests;+}++function activateBackend(backend: Backend) {+ setRegisteredBackends([backend]);+ setActiveSelection({ backendId: backend.id, orgId: GUIDE_ORG_ID });+}++function renderGuide(currentPath = "/conversations") {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ const ui = (path: string) => (+ <QueryClientProvider client={queryClient}>+ <ActiveBackendProvider>+ <NavigationProvider+ value={{+ currentPath: path,+ conversationId: null,+ isNavigating: false,+ navigate: vi.fn(),+ }}+ >+ <SuperAdminSetupGuide />+ </NavigationProvider>+ </ActiveBackendProvider>+ </QueryClientProvider>+ );+ const view = render(ui(currentPath));+ return { navigateTo: (path: string) => view.rerender(ui(path)) };+}++async function expectNoGuide() {+ await expect(+ screen.findByTestId("super-admin-setup-guide", undefined, {+ timeout: 200,+ }),+ ).rejects.toThrow();+}++describe("SuperAdminSetupGuide", () => {+ beforeEach(() => {+ localStorage.clear();+ __resetActiveStoreForTests();+ });++ afterEach(() => {+ __resetActiveStoreForTests();+ });++ it("shows the first Super Admin the progress the server reports", async () => {+ activateBackend(cloudBackend);+ serveSetupGuide({+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),+ });++ renderGuide();++ expect(+ await screen.findByTestId("super-admin-setup-guide-panel"),+ ).toBeInTheDocument();+ expect(screen.getByText("1/4")).toBeInTheDocument();+ expect(screen.getByRole("progressbar")).toHaveAttribute(+ "aria-valuenow",+ "25",+ );+ });++ it("links each step to the page where it is done", async () => {+ activateBackend(cloudBackend);+ serveSetupGuide();++ renderGuide();++ await screen.findByTestId("super-admin-setup-guide-panel");+ expect(+ screen.getByTestId("super-admin-setup-guide-step-add-llm"),+ ).toHaveAttribute(+ "href",+ `${CLOUD_HOST}/settings/org-defaults?org=${GUIDE_ORG_ID}`,+ );+ expect(+ screen.getByTestId("super-admin-setup-guide-step-add-integration"),+ ).toHaveAttribute("href", "/mcp");+ expect(+ screen.getByTestId("super-admin-setup-guide-step-invite-users"),+ ).toHaveAttribute(+ "href",+ `${CLOUD_HOST}/settings/org-members?org=${GUIDE_ORG_ID}`,+ );+ expect(+ screen.getByTestId("super-admin-setup-guide-step-optional-saml"),+ ).toHaveAttribute("href", `${CLOUD_HOST}/super-admin/instance`);+ expect(+ screen.getByTestId("super-admin-setup-guide-step-first-automation"),+ ).toHaveAttribute("href", "/automations/templates");+ expect(screen.getByTestId("super-admin-setup-guide-page")).toHaveAttribute(+ "href",+ `${CLOUD_HOST}/super-admin/setup`,+ );+ });++ it("opens the next step from Start", async () => {+ activateBackend(cloudBackend);+ serveSetupGuide({+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),+ });++ renderGuide();++ expect(+ await screen.findByTestId("super-admin-setup-guide-start"),+ ).toHaveAttribute("href", "/automations/templates");+ });++ it("opens the Canvas MCP page from Start for the integration step", async () => {+ activateBackend(cloudBackend);+ serveSetupGuide({+ setupState: () =>+ HttpResponse.json(guideState({ org_llm: true, automation: true })),+ });++ renderGuide();++ expect(+ await screen.findByTestId("super-admin-setup-guide-start"),+ ).toHaveAttribute("href", "/mcp");+ });++ it("opens an enterprise step from Start on the guide's organization", async () => {+ activateBackend(cloudBackend);+ serveSetupGuide({+ setupState: () =>+ HttpResponse.json(+ guideState({ org_llm: true, automation: true, mcp_server: true }),+ ),+ });++ renderGuide();++ expect(+ await screen.findByTestId("super-admin-setup-guide-start"),+ ).toHaveAttribute(+ "href",+ `${CLOUD_HOST}/settings/org-members?org=${GUIDE_ORG_ID}`,+ );+ });++ it("closes the panel from Start, even on the next step's own page", async () => {+ activateBackend(cloudBackend);+ serveSetupGuide({+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),+ });+ const user = userEvent.setup();+ renderGuide("/automations/templates");++ await user.click(+ await screen.findByTestId("super-admin-setup-guide-start"),+ );++ expect(+ screen.queryByTestId("super-admin-setup-guide-panel"),+ ).not.toBeInTheDocument();+ expect(+ screen.getByTestId("super-admin-setup-guide-toggle"),+ ).toHaveAttribute("aria-expanded", "false");+ });++ it("re-reads progress when the admin moves to another page", async () => {+ activateBackend(cloudBackend);+ let state = guideState({ org_llm: true });+ serveSetupGuide({ setupState: () => HttpResponse.json(state) });+ const { navigateTo } = renderGuide("/automations/templates");+ expect(await screen.findByText("1/4")).toBeInTheDocument();++ state = guideState({ org_llm: true, automation: true });+ navigateTo("/automations/automation-1");++ expect(await screen.findByText("2/4")).toBeInTheDocument();+ });++ it("closes to the pill and opens again from it", async () => {+ const user = userEvent.setup();+ activateBackend(cloudBackend);+ serveSetupGuide();+ renderGuide();+ await screen.findByTestId("super-admin-setup-guide-panel");++ await user.click(+ screen.getByRole("button", { name: I18nKey.BUTTON$CLOSE }),+ );+ expect(+ screen.queryByTestId("super-admin-setup-guide-panel"),+ ).not.toBeInTheDocument();++ await user.click(screen.getByTestId("super-admin-setup-guide-toggle"));+ expect(+ screen.getByTestId("super-admin-setup-guide-panel"),+ ).toBeInTheDocument();+ });++ it("does not ask for the setup state for a user who is not a Super Admin", async () => {+ activateBackend(cloudBackend);+ const requests = serveSetupGuide({ permissions: ["view_automations"] });++ renderGuide();++ await waitFor(() => expect(requests.me).toBe(1));+ await expectNoGuide();+ expect(requests.setupState).toBe(0);+ });++ it.each([+ [+ "the caller is not the first Super Admin",+ () =>+ HttpResponse.json({+ wizard_pending: false,+ guide_org_id: null,+ guide_dismissed: false,+ guide_steps: null,+ }),+ ],+ [+ "the guide was dismissed",+ () => HttpResponse.json({ ...guideState(), guide_dismissed: true }),+ ],+ [+ "every step is done",+ () =>+ HttpResponse.json(+ guideState({+ org_llm: true,+ mcp_server: true,+ automation: true,+ invite: true,+ }),+ ),+ ],+ [+ "the server has the Super Admin feature off and serves its web page",+ () => HttpResponse.html("<!doctype html><html></html>"),+ ],+ ])("shows nothing when %s", async (_case, setupState) => {+ activateBackend(cloudBackend);+ const requests = serveSetupGuide({ setupState });++ renderGuide();++ await waitFor(() => expect(requests.setupState).toBeGreaterThan(0));+ await expectNoGuide();+ });++ it("never asks a local backend for a guide", async () => {+ activateBackend(localBackend);+ const requests = serveSetupGuide();++ renderGuide();++ await expectNoGuide();+ expect(requests).toEqual({ me: 0, setupState: 0 });+ });+});diff --git a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsxindex 46e3eadade..94db61b10d 100644--- a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx+++ b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx@@ -10,6 +10,15 @@ import {import { render, screen } from "@testing-library/react";import userEvent from "@testing-library/user-event";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { http, HttpResponse } from "msw";+import {+ __resetActiveStoreForTests,+ setActiveSelection,+ setRegisteredBackends,+} from "#/api/backend-registry/active-store";+import SuperAdminSetupGuide from "#/components/features/setup-guide/super-admin-setup-guide";+import { ActiveBackendProvider } from "#/contexts/active-backend-context";+import { server } from "#/mocks/node";import { ONBOARDING_COMPLETED_STORAGE_KEY } from "#/components/features/onboarding/use-onboarding-completion";import { SidebarOnboardingChecklist } from "#/components/features/sidebar/sidebar-onboarding-checklist";import {@@ -402,4 +411,99 @@ describe("SidebarOnboardingChecklist", () => {});});});++ describe("with the Super Admin setup guide", () => {+ function serveCloudUser(permissions: string[]) {+ server.use(+ http.get("*/api/organizations/:orgId/me", ({ params }) =>+ HttpResponse.json({+ org_id: params.orgId,+ user_id: "user-1",+ role: "owner",+ permissions,+ }),+ ),+ http.get("*/api/admin/setup-state", () =>+ HttpResponse.json({+ wizard_pending: false,+ guide_org_id: "org-1",+ guide_dismissed: false,+ guide_steps: {+ org_llm: false,+ mcp_server: false,+ automation: false,+ invite: false,+ },+ }),+ ),+ );+ }++ function renderOnCloud() {+ const navigation: NavigationContextValue = {+ currentPath: "/",+ conversationId: null,+ isNavigating: false,+ navigate: vi.fn(),+ };+ render(+ <QueryClientProvider+ client={+ new QueryClient({ defaultOptions: { queries: { retry: false } } })+ }+ >+ <ActiveBackendProvider>+ <NavigationProvider value={navigation}>+ <SidebarOnboardingChecklist collapsed={false} />+ <SuperAdminSetupGuide />+ </NavigationProvider>+ </ActiveBackendProvider>+ </QueryClientProvider>,+ );+ }++ beforeEach(() => {+ __resetActiveStoreForTests();+ setRegisteredBackends([+ {+ id: "cloud-1",+ name: "OHE",+ host: "https://ohe.example.com",+ apiKey: "",+ kind: "cloud",+ },+ ]);+ setActiveSelection({ backendId: "cloud-1", orgId: "org-1" });+ });++ afterEach(() => {+ __resetActiveStoreForTests();+ });++ it("steps aside while the setup guide is shown", async () => {+ serveCloudUser(["manage_super_admins"]);++ renderOnCloud();++ expect(+ await screen.findByTestId("super-admin-setup-guide"),+ ).toBeInTheDocument();+ expect(+ screen.queryByTestId("sidebar-onboarding-checklist"),+ ).not.toBeInTheDocument();+ });++ it("stays for cloud users who have no setup guide", async () => {+ serveCloudUser(["view_automations"]);++ renderOnCloud();++ expect(+ await screen.findByTestId("sidebar-onboarding-checklist"),+ ).toBeInTheDocument();+ expect(+ screen.queryByTestId("super-admin-setup-guide"),+ ).not.toBeInTheDocument();+ });+ });});diff --git a/__tests__/hooks/mutation/use-add-mcp-server.test.ts b/__tests__/hooks/mutation/use-add-mcp-server.test.tsindex 2b81b1e62c..7a4f727e97 100644--- a/__tests__/hooks/mutation/use-add-mcp-server.test.ts+++ b/__tests__/hooks/mutation/use-add-mcp-server.test.ts@@ -4,6 +4,7 @@ import { renderHook } from "@testing-library/react";import { beforeEach, describe, expect, it, vi } from "vitest";import SettingsService from "#/api/settings-service/settings-service.api";import { useAddMcpServer } from "#/hooks/mutation/use-add-mcp-server";+import { SUPER_ADMIN_SETUP_QUERY_KEYS } from "#/hooks/query/query-keys";const useSettingsMock = vi.fn();vi.mock("#/hooks/query/use-settings", () => ({@@ -87,6 +88,31 @@ describe("useAddMcpServer", () => {});});+ it("marks the Super Admin setup guide's progress stale after adding a server", async () => {+ vi.spyOn(SettingsService, "createMcpServer").mockResolvedValue(true);+ const client = new QueryClient({+ defaultOptions: {+ queries: { retry: false },+ mutations: { retry: false },+ },+ });+ const setupStateKey = SUPER_ADMIN_SETUP_QUERY_KEYS.state("cloud-1", 0);+ client.setQueryData(setupStateKey, { guide_steps: { mcp_server: false } });+ const { result } = renderHook(() => useAddMcpServer(), {+ wrapper: ({ children }: { children: React.ReactNode }) =>+ React.createElement(QueryClientProvider, { client }, children),+ });++ await result.current.mutateAsync({+ id: "",+ type: "shttp",+ name: "docs",+ url: "https://docs.example/mcp",+ });++ expect(client.getQueryState(setupStateKey)?.isInvalidated).toBe(true);+ });+it("fails instead of reporting a successful install before settings load", async () => {useSettingsMock.mockReturnValue({ data: undefined });const createSpy = vi.spyOn(SettingsService, "createMcpServer");diff --git a/src/api/cloud/setup-state-service.api.ts b/src/api/cloud/setup-state-service.api.tsnew file mode 100644index 0000000000..77af470691--- /dev/null+++ b/src/api/cloud/setup-state-service.api.ts@@ -0,0 +1,27 @@+import type { Backend } from "../backend-registry/types";+import { callCloudProxy } from "./proxy";+import type { CloudSetupState } from "./types";++/**+ * Fetch `GET /api/admin/setup-state`: the Super Admin setup guide's+ * organization, dismissal and server-derived step progress.+ *+ * Enterprise backends only mount the route while the Super Admin feature is+ * on; otherwise the path falls through to the web app and the response is+ * not JSON. Anything that is not an object is treated as "no guide".+ */+export async function getCloudSetupState(+ backend: Backend,+): Promise<CloudSetupState> {+ const data = await callCloudProxy<Partial<CloudSetupState> | string>({+ backend,+ method: "GET",+ path: "/api/admin/setup-state",+ });+ const state = typeof data === "object" && data !== null ? data : {};+ return {+ guide_org_id: state.guide_org_id ?? null,+ guide_dismissed: state.guide_dismissed ?? false,+ guide_steps: state.guide_steps ?? null,+ };+}diff --git a/src/api/cloud/types.ts b/src/api/cloud/types.tsindex 270e5ec73b..808b7ba575 100644--- a/src/api/cloud/types.ts+++ b/src/api/cloud/types.ts@@ -61,3 +61,25 @@ export interface CloudGitUser {name: string | null;email: string | null;}++/**+ * Server-derived Super Admin setup-guide steps, from+ * `GET /api/admin/setup-state` on an OpenHands Enterprise backend.+ */+export interface CloudSetupGuideSteps {+ org_llm: boolean;+ mcp_server: boolean;+ automation: boolean;+ invite: boolean;+}++/**+ * Subset of the enterprise setup-state the GUI reads. `guide_steps` is+ * non-null only for the first Super Admin while the guide has an+ * organization and has not been dismissed.+ */+export interface CloudSetupState {+ guide_org_id: string | null;+ guide_dismissed: boolean;+ guide_steps: CloudSetupGuideSteps | null;+}diff --git a/src/components/features/setup-guide/super-admin-setup-guide.constants.ts b/src/components/features/setup-guide/super-admin-setup-guide.constants.tsnew file mode 100644index 0000000000..13b1b938e0--- /dev/null+++ b/src/components/features/setup-guide/super-admin-setup-guide.constants.ts@@ -0,0 +1,90 @@+import type { CloudSetupGuideSteps } from "#/api/cloud/types";+import { I18nKey } from "#/i18n/declaration";+import { automationTemplatesPath } from "#/manifests/automation-interface";++/** Server permission held by instance Super Admins (`/me` `permissions`). */+export const MANAGE_SUPER_ADMINS_PERMISSION = "manage_super_admins";++/** The enterprise setup guide page, on the cloud host. */+export const SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH = "/super-admin/setup";++export type SuperAdminSetupStepId =+ | "add-llm"+ | "add-integration"+ | "first-automation"+ | "invite-users"+ | "optional-saml";++/**+ * What marks a step done: a server-derived flag from `guide_steps`, or+ * "optional" for a link that never counts toward progress.+ */+export type SuperAdminSetupStepCompletion =+ | keyof CloudSetupGuideSteps+ | "optional";++/**+ * Where a step opens: a page on the cloud host (`withOrg` adds the guide's+ * organization so enterprise settings open on it) or a Canvas route.+ */+export type SuperAdminSetupStepDestination =+ | { kind: "cloud"; path: string; withOrg: boolean }+ | { kind: "canvas"; path: string };++export interface SuperAdminSetupStep {+ id: SuperAdminSetupStepId;+ labelKey: I18nKey;+ completion: SuperAdminSetupStepCompletion;+ destination: SuperAdminSetupStepDestination;+}++/**+ * Mirrors the enterprise guide's steps and order so both apps show the same+ * progress. Steps that Canvas can do itself (automation templates, MCP+ * servers) open in Canvas; the rest open the enterprise app.+ */+export const SUPER_ADMIN_SETUP_STEPS: readonly SuperAdminSetupStep[] = [+ {+ id: "add-llm",+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_LLM,+ completion: "org_llm",+ destination: {+ kind: "cloud",+ path: "/settings/org-defaults",+ withOrg: true,+ },+ },+ {+ id: "first-automation",+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_AUTOMATION,+ completion: "automation",+ destination: { kind: "canvas", path: automationTemplatesPath() },+ },+ {+ id: "add-integration",+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_INTEGRATION,+ completion: "mcp_server",+ // Canvas's MCP page saves to the same cloud settings the step checks.+ destination: { kind: "canvas", path: "/mcp" },+ },+ {+ id: "invite-users",+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_INVITE,+ completion: "invite",+ destination: {+ kind: "cloud",+ path: "/settings/org-members",+ withOrg: true,+ },+ },+ {+ id: "optional-saml",+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_SAML,+ completion: "optional",+ destination: {+ kind: "cloud",+ path: "/super-admin/instance",+ withOrg: false,+ },+ },+];diff --git a/src/components/features/setup-guide/super-admin-setup-guide.tsx b/src/components/features/setup-guide/super-admin-setup-guide.tsxnew file mode 100644index 0000000000..ae77663994--- /dev/null+++ b/src/components/features/setup-guide/super-admin-setup-guide.tsx@@ -0,0 +1,249 @@+import { type ReactNode, useEffect, useState } from "react";+import { useTranslation } from "react-i18next";+import { ArrowUpRight, Check, ClipboardList, X } from "lucide-react";+import { getLockedCloudHost } from "#/api/agent-server-config";+import { NavigationLink } from "#/components/shared/navigation-link";+import { useNavigation } from "#/context/navigation-context";+import { useActiveBackend } from "#/contexts/active-backend-context";+import { I18nKey } from "#/i18n/declaration";+import { formControlButtonClassName } from "#/utils/form-control-classes";+import { cn } from "#/utils/utils";+import {+ SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH,+ type SuperAdminSetupStep,+} from "./super-admin-setup-guide.constants";+import { useSuperAdminSetupGuide } from "./use-super-admin-setup-guide";++const ICON_BUTTON_CLASS = cn(+ "inline-flex size-7 shrink-0 items-center justify-center rounded-md",+ "text-muted hover:bg-surface hover:text-contrast",+);++const STEP_ROW_CLASS =+ "flex w-full min-w-0 items-center gap-2.5 rounded-md px-2.5 py-1.5 hover:bg-surface";++// The enterprise guide's primary button: light on dark. Canvas's `primary`+// is its gold accent, so this uses `foreground` like the enterprise app.+const START_BUTTON_CLASS = cn(+ formControlButtonClassName,+ "w-full bg-foreground font-medium text-on-primary hover:opacity-80",+);++const START_TEST_ID = "super-admin-setup-guide-start";++/**+ * Floating lower-right setup guide for the enterprise Super Admin, matching+ * the guide in the OpenHands Enterprise app. Steps that live in the+ * enterprise app link back to it; progress is read from the server.+ */+export default function SuperAdminSetupGuide() {+ const { t } = useTranslation("openhands");+ const { currentPath } = useNavigation();+ const { backend } = useActiveBackend();+ const {+ steps,+ completedCount,+ totalCount,+ nextStep,+ guideOrgId,+ visible,+ refetch,+ } = useSuperAdminSetupGuide();+ const [open, setOpen] = useState(true);++ // Progress is read from the server, so re-read it as the admin moves around.+ useEffect(() => {+ if (visible) {+ refetch();+ }+ }, [currentPath, visible, refetch]);++ if (!visible) {+ return null;+ }++ const cloudHost = backend.host.replace(/\/+$/, "");+ // Locked-to-Cloud serves the canvas on the cloud host itself, so enterprise+ // pages open in this tab; standalone / Electron keep a new tab.+ const isLockedToCloud = getLockedCloudHost() !== null;+ const cloudLinkProps = {+ target: isLockedToCloud ? undefined : "_blank",+ rel: isLockedToCloud ? undefined : "noopener noreferrer",+ };+ const cloudUrl = (path: string, withOrg: boolean) =>+ withOrg && guideOrgId+ ? `${cloudHost}${path}?org=${encodeURIComponent(guideOrgId)}`+ : `${cloudHost}${path}`;+ // A step row and Start open the same page for a step.+ const renderStepLink = (+ step: SuperAdminSetupStep,+ testId: string,+ className: string,+ children: ReactNode,+ onClick?: () => void,+ ) =>+ step.destination.kind === "canvas" ? (+ <NavigationLink+ to={step.destination.path}+ data-testid={testId}+ className={className}+ onClick={onClick}+ >+ {children}+ </NavigationLink>+ ) : (+ <a+ href={cloudUrl(step.destination.path, step.destination.withOrg)}+ {...cloudLinkProps}+ data-testid={testId}+ className={className}+ onClick={onClick}+ >+ {children}+ </a>+ );++ const title = t(I18nKey.ONBOARDING$SETUP_GUIDE_TITLE);+ const progressPct = Math.round((completedCount / totalCount) * 100);++ return (+ <div+ className="fixed bottom-5 right-5 z-30 flex flex-col items-end gap-2"+ data-testid="super-admin-setup-guide"+ >+ {open ? (+ <div+ data-testid="super-admin-setup-guide-panel"+ className={cn(+ "flex w-80 flex-col gap-3 rounded-xl border border-border",+ "bg-surface-raised p-4 shadow-lg",+ )}+ >+ <div className="flex items-center justify-between gap-2">+ <p className="min-w-0 text-sm font-semibold text-content">+ {title}+ </p>+ <div className="flex shrink-0 items-center gap-0.5">+ <a+ href={cloudUrl(SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH, false)}+ {...cloudLinkProps}+ data-testid="super-admin-setup-guide-page"+ aria-label={title}+ title={title}+ className={ICON_BUTTON_CLASS}+ >+ <ArrowUpRight className="size-4" strokeWidth={2} aria-hidden />+ </a>+ <button+ type="button"+ aria-label={t(I18nKey.BUTTON$CLOSE)}+ className={ICON_BUTTON_CLASS}+ onClick={() => setOpen(false)}+ >+ <X className="size-4" strokeWidth={2} aria-hidden />+ </button>+ </div>+ </div>++ <div className="flex items-center gap-3">+ <div+ className="h-1.5 flex-1 overflow-hidden rounded-full bg-border"+ role="progressbar"+ aria-valuemin={0}+ aria-valuemax={100}+ aria-valuenow={progressPct}+ aria-label={title}+ >+ <div+ className="h-full rounded-full bg-foreground transition-all duration-300"+ style={{ width: `${progressPct}%` }}+ />+ </div>+ <span className="shrink-0 text-xs tabular-nums text-muted">+ {completedCount}/{totalCount}+ </span>+ </div>++ <ul className="flex flex-col gap-0.5">+ {steps.map((step) => {+ const label = (+ <>+ <span+ aria-hidden+ className={cn(+ "inline-flex size-4 shrink-0 items-center justify-center rounded-full border",+ step.done+ ? "border-foreground bg-foreground text-on-primary"+ : "border-border bg-transparent",+ )}+ >+ {step.done ? (+ <Check className="size-2.5" strokeWidth={3} />+ ) : null}+ </span>+ <span+ className={cn(+ "min-w-0 flex-1 truncate text-xs",+ step.done ? "text-muted line-through" : "text-content",+ )}+ >+ {t(step.labelKey)}+ </span>+ </>+ );+ const testId = `super-admin-setup-guide-step-${step.id}`;+ const rowClassName = cn(+ STEP_ROW_CLASS,+ nextStep?.id === step.id && "bg-surface",+ );+ return (+ <li key={step.id}>+ {renderStepLink(step, testId, rowClassName, label)}+ </li>+ );+ })}+ </ul>++ {nextStep ? (+ <div className="flex flex-col gap-2">+ <p+ className="text-xs text-muted"+ data-testid="super-admin-setup-guide-next"+ >+ {t(I18nKey.ONBOARDING$SETUP_GUIDE_NEXT, {+ step: t(nextStep.labelKey),+ })}+ </p>+ {/* Like the enterprise Start, close the panel before opening+ the step, so Start does something even when the admin is+ already on that step's page. */}+ {renderStepLink(+ nextStep,+ START_TEST_ID,+ START_BUTTON_CLASS,+ t(I18nKey.ONBOARDING$SETUP_GUIDE_START),+ () => setOpen(false),+ )}+ </div>+ ) : null}+ </div>+ ) : null}++ <button+ type="button"+ data-testid="super-admin-setup-guide-toggle"+ aria-label={title}+ aria-expanded={open}+ onClick={() => setOpen((current) => !current)}+ className={cn(+ "flex items-center gap-2 rounded-full border border-border",+ "bg-surface-raised px-3.5 py-2 text-sm font-medium text-content",+ "shadow-sm hover:bg-surface",+ )}+ >+ <ClipboardList className="size-4" strokeWidth={2} aria-hidden />+ {title}+ </button>+ </div>+ );+}diff --git a/src/components/features/setup-guide/use-super-admin-setup-guide.ts b/src/components/features/setup-guide/use-super-admin-setup-guide.tsnew file mode 100644index 0000000000..34f4877dde--- /dev/null+++ b/src/components/features/setup-guide/use-super-admin-setup-guide.ts@@ -0,0 +1,101 @@+import { useQuery } from "@tanstack/react-query";+import { getCloudOrganizationMe } from "#/api/cloud/organization-service.api";+import { getCloudSetupState } from "#/api/cloud/setup-state-service.api";+import type { CloudSetupGuideSteps } from "#/api/cloud/types";+import { useActiveBackend } from "#/contexts/active-backend-context";+import {+ CONFIG_CACHE_OPTIONS,+ SUPER_ADMIN_SETUP_QUERY_KEYS,+} from "#/hooks/query/query-keys";+import {+ MANAGE_SUPER_ADMINS_PERMISSION,+ SUPER_ADMIN_SETUP_STEPS,+ type SuperAdminSetupStep,+} from "./super-admin-setup-guide.constants";++export interface SuperAdminSetupStepState extends SuperAdminSetupStep {+ done: boolean;+}++const REQUIRED_STEPS = SUPER_ADMIN_SETUP_STEPS.filter(+ (step) => step.completion !== "optional",+);++function isStepDone(+ step: SuperAdminSetupStep,+ guideSteps: CloudSetupGuideSteps | null,+): boolean {+ if (!guideSteps || step.completion === "optional") {+ return false;+ }+ return guideSteps[step.completion];+}++/**+ * The enterprise Super Admin setup guide for the active cloud backend.+ *+ * Only instance Super Admins (per `/me` permissions) ask for the setup state,+ * and the server returns a guide only to the first Super Admin while it has+ * an organization and is not dismissed. Local backends never see it.+ */+export function useSuperAdminSetupGuide() {+ const { backend, orgId } = useActiveBackend();+ const isCloud = backend.kind === "cloud";++ // Same query as `useAutomationPermissions`, so no extra request is issued.+ // eslint-disable-next-line @tanstack/query/exhaustive-deps+ const meQuery = useQuery({+ queryKey: [+ "cloud-current-user",+ backend.id,+ orgId,+ backend.connectionRevision ?? 0,+ ],+ queryFn: () => getCloudOrganizationMe(orgId!, backend),+ enabled: isCloud && !!orgId,+ staleTime: 1000 * 60 * 5,+ retry: false,+ meta: { disableToast: true },+ });+ const isSuperAdmin =+ meQuery.data?.permissions?.includes(MANAGE_SUPER_ADMINS_PERMISSION) ===+ true;++ // eslint-disable-next-line @tanstack/query/exhaustive-deps+ const setupStateQuery = useQuery({+ queryKey: SUPER_ADMIN_SETUP_QUERY_KEYS.state(+ backend.id,+ backend.connectionRevision ?? 0,+ ),+ queryFn: () => getCloudSetupState(backend),+ enabled: isCloud && isSuperAdmin,+ ...CONFIG_CACHE_OPTIONS,+ retry: false,+ meta: { disableToast: true },+ });++ const setupState = isSuperAdmin ? setupStateQuery.data : undefined;+ const guideSteps = setupState?.guide_steps ?? null;+ const steps: SuperAdminSetupStepState[] = SUPER_ADMIN_SETUP_STEPS.map(+ (step) => ({ ...step, done: isStepDone(step, guideSteps) }),+ );+ const completedCount = REQUIRED_STEPS.filter((step) =>+ isStepDone(step, guideSteps),+ ).length;+ const nextStep =+ REQUIRED_STEPS.find((step) => !isStepDone(step, guideSteps)) ?? null;+ const guideOrgId = setupState?.guide_org_id ?? null;+ // Only the first Super Admin's guide has an organization; it stays until dismissed.+ const active = Boolean(guideOrgId) && !setupState?.guide_dismissed;++ return {+ steps,+ completedCount,+ totalCount: REQUIRED_STEPS.length,+ nextStep,+ guideOrgId,+ visible: active && nextStep !== null,+ isLoading: meQuery.isLoading || setupStateQuery.isLoading,+ refetch: setupStateQuery.refetch,+ };+}diff --git a/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts b/src/components/features/sidebar/use-sidebar-onboarding-checklist.tsindex 03376fca64..52b2111780 100644--- a/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts+++ b/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts@@ -1,5 +1,6 @@import { useEffect, useMemo, useState, useSyncExternalStore } from "react";import { useOnboardingCompletion } from "#/components/features/onboarding/use-onboarding-completion";+import { useSuperAdminSetupGuide } from "#/components/features/setup-guide/use-super-admin-setup-guide";import { useNavigation } from "#/context/navigation-context";import { useAutomations } from "#/hooks/query/use-automations";import { useAutomationHealth } from "#/hooks/query/use-automation-health";@@ -38,6 +39,7 @@ function hasConfiguredMcpServers(mcpConfig: unknown): boolean {export function useSidebarOnboardingChecklist() {const { isCompleted: onboardingCompleted } = useOnboardingCompletion();+ const setupGuide = useSuperAdminSetupGuide();const { currentPath } = useNavigation();const isDismissed = useSyncExternalStore(subscribeSidebarOnboardingChecklistDismissed,@@ -133,7 +135,13 @@ export function useSidebarOnboardingChecklist() {const completedCount = items.filter((item) => item.isComplete).length;const isAllComplete = completedCount === items.length;- const isVisible = onboardingCompleted && !isDismissed && !isAllComplete;+ // The Super Admin setup guide replaces this checklist while it is shown.+ const isVisible =+ onboardingCompleted &&+ !isDismissed &&+ !isAllComplete &&+ !setupGuide.isLoading &&+ !setupGuide.visible;const dismiss = () => {writeSidebarOnboardingChecklistDismissed(true);diff --git a/src/hooks/mutation/use-add-mcp-server.ts b/src/hooks/mutation/use-add-mcp-server.tsindex 5472de7c58..c597433c44 100644--- a/src/hooks/mutation/use-add-mcp-server.ts+++ b/src/hooks/mutation/use-add-mcp-server.ts@@ -7,7 +7,10 @@ import {parseMcpConfig,toCanonicalMcpServer,} from "#/utils/mcp-config";-import { SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";+import {+ SETTINGS_QUERY_KEYS,+ SUPER_ADMIN_SETUP_QUERY_KEYS,+} from "#/hooks/query/query-keys";// @spec MCP-001 — Sparse mutations preserve sibling serversexport function useAddMcpServer() {@@ -37,6 +40,11 @@ export function useAddMcpServer() {queryClient.invalidateQueries({queryKey: SETTINGS_QUERY_KEYS.personal(),});+ // The enterprise setup guide's "Add an integration" step counts MCP+ // servers, and adding one does not change the page that re-reads it.+ queryClient.invalidateQueries({+ queryKey: SUPER_ADMIN_SETUP_QUERY_KEYS.all,+ });},});}diff --git a/src/hooks/query/query-keys.ts b/src/hooks/query/query-keys.tsindex afa45d0259..d909e6ae3a 100644--- a/src/hooks/query/query-keys.ts+++ b/src/hooks/query/query-keys.ts@@ -95,6 +95,14 @@ export const CANVAS_EXTENSIONS_QUERY_KEYS = {] as const,} as const;+export const SUPER_ADMIN_SETUP_QUERY_KEYS = {+ /** Every backend's setup-guide state, for invalidation. */+ all: ["super-admin-setup-state"] as const,+ /** Enterprise Super Admin setup-guide state for a cloud backend. */+ state: (backendId: string, connectionRevision: number) =>+ ["super-admin-setup-state", backendId, connectionRevision] as const,+} as const;+export const SETUP_QUERY_KEYS = {/** What the deployment supports. The same answer for every setup entry. */capabilities: () => ["setup-capabilities"] as const,diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex b5e5bdda04..8416cda60c 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -43060,6 +43060,142 @@"uk": "Пропустити контрольний список «Початок роботи»","ca": "Omet la llista Per començar"},+ "ONBOARDING$SETUP_GUIDE_TITLE": {+ "en": "Setup guide",+ "ja": "セットアップガイド",+ "zh-CN": "设置指南",+ "zh-TW": "設定指南",+ "ko-KR": "설정 가이드",+ "no": "Oppsettsveiledning",+ "ar": "دليل الإعداد",+ "de": "Einrichtungsleitfaden",+ "fr": "Guide de configuration",+ "it": "Guida alla configurazione",+ "pt": "Guia de configuração",+ "es": "Guía de configuración",+ "ca": "Guia de configuració",+ "tr": "Kurulum rehberi",+ "uk": "Посібник із налаштування"+ },+ "ONBOARDING$SETUP_GUIDE_STEP_LLM": {+ "en": "Add an LLM",+ "ja": "LLM を追加",+ "zh-CN": "添加 LLM",+ "zh-TW": "新增 LLM",+ "ko-KR": "LLM 추가",+ "no": "Legg til en LLM",+ "ar": "إضافة نموذج LLM",+ "de": "LLM hinzufügen",+ "fr": "Ajouter un LLM",+ "it": "Aggiungi un LLM",+ "pt": "Adicionar um LLM",+ "es": "Añadir un LLM",+ "ca": "Afegeix un LLM",+ "tr": "Bir LLM ekleyin",+ "uk": "Додайте LLM"+ },+ "ONBOARDING$SETUP_GUIDE_STEP_INTEGRATION": {+ "en": "Add an integration",+ "ja": "連携を追加",+ "zh-CN": "添加集成",+ "zh-TW": "新增整合",+ "ko-KR": "통합 추가",+ "no": "Legg til en integrasjon",+ "ar": "إضافة تكامل",+ "de": "Integration hinzufügen",+ "fr": "Ajouter une intégration",+ "it": "Aggiungi un'integrazione",+ "pt": "Adicionar uma integração",+ "es": "Añadir una integración",+ "ca": "Afegeix una integració",+ "tr": "Bir entegrasyon ekleyin",+ "uk": "Додайте інтеграцію"+ },+ "ONBOARDING$SETUP_GUIDE_STEP_AUTOMATION": {+ "en": "Choose an automation template",+ "ja": "自動化テンプレートを選択",+ "zh-CN": "选择自动化模板",+ "zh-TW": "選擇自動化範本",+ "ko-KR": "자동화 템플릿 선택",+ "no": "Velg en automatiseringsmal",+ "ar": "اختر قالب أتمتة",+ "de": "Automatisierungsvorlage auswählen",+ "fr": "Choisir un modèle d'automatisation",+ "it": "Scegli un modello di automazione",+ "pt": "Escolher um modelo de automação",+ "es": "Elegir una plantilla de automatización",+ "ca": "Tria una plantilla d'automatització",+ "tr": "Bir otomasyon şablonu seçin",+ "uk": "Виберіть шаблон автоматизації"+ },+ "ONBOARDING$SETUP_GUIDE_STEP_INVITE": {+ "en": "Invite users",+ "ja": "ユーザーを招待",+ "zh-CN": "邀请用户",+ "zh-TW": "邀請使用者",+ "ko-KR": "사용자 초대",+ "no": "Inviter brukere",+ "ar": "دعوة المستخدمين",+ "de": "Benutzer einladen",+ "fr": "Inviter des utilisateurs",+ "it": "Invita utenti",+ "pt": "Convidar usuários",+ "es": "Invitar usuarios",+ "ca": "Convida usuaris",+ "tr": "Kullanıcıları davet edin",+ "uk": "Запросіть користувачів"+ },+ "ONBOARDING$SETUP_GUIDE_STEP_SAML": {+ "en": "Optional: SAML / instance",+ "ja": "任意: SAML / インスタンス",+ "zh-CN": "可选:SAML / 实例",+ "zh-TW": "選用:SAML / 執行個體",+ "ko-KR": "선택 사항: SAML / 인스턴스",+ "no": "Valgfritt: SAML / instans",+ "ar": "اختياري: SAML / المثيل",+ "de": "Optional: SAML / Instanz",+ "fr": "Facultatif : SAML / instance",+ "it": "Facoltativo: SAML / istanza",+ "pt": "Opcional: SAML / instância",+ "es": "Opcional: SAML / instancia",+ "ca": "Opcional: SAML / instància",+ "tr": "İsteğe bağlı: SAML / örnek",+ "uk": "Необов'язково: SAML / екземпляр"+ },+ "ONBOARDING$SETUP_GUIDE_NEXT": {+ "en": "Next: {{step}}",+ "ja": "次: {{step}}",+ "zh-CN": "下一步:{{step}}",+ "zh-TW": "下一步:{{step}}",+ "ko-KR": "다음: {{step}}",+ "no": "Neste: {{step}}",+ "ar": "التالي: {{step}}",+ "de": "Nächster Schritt: {{step}}",+ "fr": "Suivant : {{step}}",+ "it": "Prossimo: {{step}}",+ "pt": "Próximo: {{step}}",+ "es": "Siguiente: {{step}}",+ "ca": "Següent: {{step}}",+ "tr": "Sıradaki: {{step}}",+ "uk": "Далі: {{step}}"+ },+ "ONBOARDING$SETUP_GUIDE_START": {+ "en": "Start",+ "ja": "開始",+ "zh-CN": "开始",+ "zh-TW": "開始",+ "ko-KR": "시작",+ "no": "Start",+ "ar": "ابدأ",+ "de": "Starten",+ "fr": "Commencer",+ "it": "Inizia",+ "pt": "Começar",+ "es": "Empezar",+ "ca": "Comença",+ "tr": "Başla",+ "uk": "Почати"+ },"AUTOMATIONS$GIT_SYNC$NAV_BUTTON": {"en": "Git Sync","ja": "Git同期",diff --git a/src/routes/root-layout.tsx b/src/routes/root-layout.tsxindex da7a70c9ce..ed78969e8d 100644--- a/src/routes/root-layout.tsx+++ b/src/routes/root-layout.tsx@@ -41,6 +41,9 @@ const CommandMenu = React.lazy(() =>default: m.CommandMenu,})),);+const SuperAdminSetupGuide = React.lazy(+ () => import("#/components/features/setup-guide/super-admin-setup-guide"),+);export function ErrorBoundary() {const error = useRouteError();@@ -159,6 +162,9 @@ function MainAppContent() {<EnvironmentSwitchOverlay /><CommandMenu /></React.Suspense>+ <React.Suspense fallback={null}>+ <SuperAdminSetupGuide />+ </React.Suspense>{showOnboardingPreview ? <OnboardingHost /> : null}</SidebarMobileNavProvider></CanvasExtensionsRuntimeProvider>