Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(onboarding): standalone setup screen with per-agent progress

Yuting Zhong1137c01a33af
diff --git a/src/components/onboarding-flow.test.tsx b/src/components/onboarding-flow.test.tsx
index a309e15e..34f83271 100644
--- a/src/components/onboarding-flow.test.tsx
+++ b/src/components/onboarding-flow.test.tsx
@@ -8,7 +8,7 @@ const {
listGoogleAdsAccounts,
setOnboardingAccountAction,
getOnboardingTaskForSkipAction,
- awaitOnboardingReadyAction,
+ getProvisioningProgressAction,
routerPush,
routerReplace,
toastFns,
@@ -19,7 +19,7 @@ const {
listGoogleAdsAccounts: vi.fn(),
setOnboardingAccountAction: vi.fn(),
getOnboardingTaskForSkipAction: vi.fn(),
- awaitOnboardingReadyAction: vi.fn(),
+ getProvisioningProgressAction: vi.fn(),
routerPush: vi.fn(),
routerReplace: vi.fn(),
toastFns: {
@@ -44,8 +44,8 @@ vi.mock("@/server/onboarding/accounts", () => ({
setOnboardingAccountAction(...args),
getOnboardingTaskForSkipAction: (...args: unknown[]) =>
getOnboardingTaskForSkipAction(...args),
- awaitOnboardingReadyAction: (...args: unknown[]) =>
- awaitOnboardingReadyAction(...args),
+ getProvisioningProgressAction: (...args: unknown[]) =>
+ getProvisioningProgressAction(...args),
}));
vi.mock("next/navigation", () => ({
@@ -89,10 +89,7 @@ beforeEach(() => {
listGoogleAdsAccounts.mockReset();
setOnboardingAccountAction.mockReset();
getOnboardingTaskForSkipAction.mockReset();
- awaitOnboardingReadyAction.mockReset();
- // Default: provisioning is ready by the time ConnectStep mounts. Tests
- // that want the waiting-state UI override this in their setup.
- awaitOnboardingReadyAction.mockResolvedValue({ ok: true });
+ getProvisioningProgressAction.mockReset();
routerPush.mockReset();
routerReplace.mockReset();
toastFns.success.mockReset();
@@ -195,38 +192,14 @@ describe("OnboardingFlow — MissingSlug", () => {
});
describe("OnboardingFlow — ConnectStep", () => {
- it("shows 'Setting up your agents…' until provisioning resolves", async () => {
- awaitOnboardingReadyAction.mockReturnValue(new Promise(() => {}));
- setStep("connect", "acme");
- render(<OnboardingFlow />);
- expect(screen.getByText(/Setting up your agents/i)).toBeInTheDocument();
- expect(
- screen.queryByRole("button", { name: /Connect Google Ads/i }),
- ).not.toBeInTheDocument();
- });
-
- it("surfaces a provisioning timeout error", async () => {
- awaitOnboardingReadyAction.mockResolvedValue({
- ok: false,
- error: "Setting up your agents is taking longer than expected. Refresh to retry.",
- });
- setStep("connect", "acme");
- render(<OnboardingFlow />);
- await waitFor(() =>
- expect(
- screen.getByText(/Setting up your agents is taking longer/i),
- ).toBeInTheDocument(),
- );
- });
-
- it("renders the connect headline + Connect/Skip buttons once ready", async () => {
+ it("renders the connect headline + Connect/Skip buttons", () => {
setStep("connect", "acme");
render(<OnboardingFlow />);
expect(
screen.getByRole("heading", { name: /Connect your Google Ads/i }),
).toBeInTheDocument();
expect(
- await screen.findByRole("button", { name: /Connect Google Ads/i }),
+ screen.getByRole("button", { name: /Connect Google Ads/i }),
).toBeInTheDocument();
expect(
screen.getByRole("button", { name: /Skip Google Ads/i }),
@@ -241,9 +214,7 @@ describe("OnboardingFlow — ConnectStep", () => {
});
setStep("connect", "acme");
render(<OnboardingFlow />);
- fireEvent.click(
- await screen.findByRole("button", { name: /Connect Google Ads/i }),
- );
+ fireEvent.click(screen.getByRole("button", { name: /Connect Google Ads/i }));
await waitFor(() =>
expect(startMcpConnect).toHaveBeenCalledWith({
mcp_key: "notfair-googleads",
@@ -259,9 +230,7 @@ describe("OnboardingFlow — ConnectStep", () => {
startMcpConnect.mockResolvedValue({ ok: false, error: "registration failed" });
setStep("connect", "acme");
render(<OnboardingFlow />);
- const btn = await screen.findByRole("button", {
- name: /Connect Google Ads/i,
- });
+ const btn = screen.getByRole("button", { name: /Connect Google Ads/i });
fireEvent.click(btn);
await waitFor(() =>
expect(toastFns.error).toHaveBeenCalledWith("registration failed"),
@@ -273,25 +242,76 @@ describe("OnboardingFlow — ConnectStep", () => {
startMcpConnect.mockRejectedValue(new Error("offline"));
setStep("connect", "acme");
render(<OnboardingFlow />);
- fireEvent.click(
- await screen.findByRole("button", { name: /Connect Google Ads/i }),
- );
+ fireEvent.click(screen.getByRole("button", { name: /Connect Google Ads/i }));
await waitFor(() =>
expect(toastFns.error).toHaveBeenCalledWith("offline"),
);
});
- it("redirects to the CMO onboarding task when the user clicks Skip", async () => {
+ it("hands off to the setup screen when the user clicks Skip", () => {
+ setStep("connect", "acme");
+ render(<OnboardingFlow />);
+ fireEvent.click(screen.getByRole("button", { name: /Skip Google Ads/i }));
+ expect(routerReplace).toHaveBeenCalledWith(
+ "/onboarding?step=setup&slug=acme&from=skip",
+ );
+ });
+});
+
+describe("OnboardingFlow — SetupStep", () => {
+ it("renders the per-template checklist while provisioning runs", async () => {
+ getProvisioningProgressAction.mockResolvedValue({
+ ok: true,
+ overall: "running",
+ steps: [
+ { key: "cmo", label: "Setting up CMO", status: "in_progress" },
+ {
+ key: "google_ads",
+ label: "Setting up Google Ads specialist",
+ status: "pending",
+ },
+ {
+ key: "gateway",
+ label: "Connecting agents to gateway",
+ status: "pending",
+ },
+ ],
+ });
+ setStep("setup", "acme");
+ render(<OnboardingFlow />);
+ expect(
+ await screen.findByText(/Setting up CMO/i),
+ ).toBeInTheDocument();
+ expect(screen.getByText(/Setting up Google Ads specialist/i)).toBeInTheDocument();
+ expect(screen.getByText(/Connecting agents to gateway/i)).toBeInTheDocument();
+ expect(routerReplace).not.toHaveBeenCalled();
+ });
+
+ it("redirects to the task workspace once provisioning is done", async () => {
+ getProvisioningProgressAction.mockResolvedValue({
+ ok: true,
+ overall: "done",
+ steps: [
+ { key: "cmo", label: "Setting up CMO", status: "done" },
+ {
+ key: "google_ads",
+ label: "Setting up Google Ads specialist",
+ status: "done",
+ },
+ {
+ key: "gateway",
+ label: "Connecting agents to gateway",
+ status: "done",
+ },
+ ],
+ });
getOnboardingTaskForSkipAction.mockResolvedValue({
ok: true,
task_display_id: "acme-1",
cmo_agent_slug: "cmo-greg",
});
- setStep("connect", "acme");
+ setStep("setup", "acme");
render(<OnboardingFlow />);
- fireEvent.click(
- await screen.findByRole("button", { name: /Skip Google Ads/i }),
- );
await waitFor(() =>
expect(routerReplace).toHaveBeenCalledWith(
"/acme/agents/cmo-greg/tasks?task=acme-1",
@@ -299,18 +319,40 @@ describe("OnboardingFlow — ConnectStep", () => {
);
});
- it("toasts when the skip lookup fails", async () => {
- getOnboardingTaskForSkipAction.mockResolvedValue({
- ok: false,
- error: "Onboarding task not found.",
+ it("surfaces an error when provisioning fails", async () => {
+ getProvisioningProgressAction.mockResolvedValue({
+ ok: true,
+ overall: "failed",
+ steps: [
+ {
+ key: "cmo",
+ label: "Setting up CMO",
+ status: "failed",
+ error: "openclaw agents add failed",
+ },
+ {
+ key: "google_ads",
+ label: "Setting up Google Ads specialist",
+ status: "pending",
+ },
+ {
+ key: "gateway",
+ label: "Connecting agents to gateway",
+ status: "pending",
+ },
+ ],
});
- setStep("connect", "acme");
+ setStep("setup", "acme");
render(<OnboardingFlow />);
- fireEvent.click(
- await screen.findByRole("button", { name: /Skip Google Ads/i }),
- );
await waitFor(() =>
- expect(toastFns.error).toHaveBeenCalledWith("Onboarding task not found."),
+ expect(
+ screen.getAllByText(/openclaw agents add failed/i).length,
+ ).toBeGreaterThan(0),
+ );
+ // The failing row stays visible (red status icon) and a top-level
+ // error alert summarises the failure so it can't be missed.
+ expect(screen.getByRole("alert")).toHaveTextContent(
+ /openclaw agents add failed/i,
);
});
});
diff --git a/src/components/onboarding-flow.tsx b/src/components/onboarding-flow.tsx
index d614fb68..554fd6bd 100644
--- a/src/components/onboarding-flow.tsx
+++ b/src/components/onboarding-flow.tsx
@@ -18,11 +18,11 @@ import {
listGoogleAdsAccounts,
setOnboardingAccountAction,
getOnboardingTaskForSkipAction,
- awaitOnboardingReadyAction,
+ getProvisioningProgressAction,
type GoogleAdsAccount,
} from "@/server/onboarding/accounts";
-type Step = "name" | "connect" | "account";
+type Step = "name" | "connect" | "account" | "setup";
export function OnboardingFlow() {
const router = useRouter();
@@ -30,7 +30,9 @@ export function OnboardingFlow() {
const stepParam = params.get("step");
const slug = params.get("slug") ?? null;
const step: Step =
- stepParam === "connect" || stepParam === "account" ? stepParam : "name";
+ stepParam === "connect" || stepParam === "account" || stepParam === "setup"
+ ? stepParam
+ : "name";
return (
<div className="mx-auto w-full max-w-[720px] space-y-6 pt-8 pb-12">
@@ -50,7 +52,10 @@ export function OnboardingFlow() {
)}
{step === "connect" && slug && <ConnectStep slug={slug} />}
{step === "account" && slug && <AccountStep slug={slug} />}
- {(step === "connect" || step === "account") && !slug && <MissingSlug />}
+ {step === "setup" && slug && <SetupStep slug={slug} />}
+ {(step === "connect" || step === "account" || step === "setup") && !slug && (
+ <MissingSlug />
+ )}
</main>
</div>
);
@@ -269,40 +274,11 @@ function NameStep({ onCreated }: { onCreated: (slug: string) => void }) {
// ── Step 2: Connect ────────────────────────────────────────────────
-type ReadyState =
- | { phase: "waiting" }
- | { phase: "ready" }
- | { phase: "error"; message: string };
-
function ConnectStep({ slug }: { slug: string }) {
const router = useRouter();
const [busy, setBusy] = useState(false);
- const [readiness, setReadiness] = useState<ReadyState>({ phase: "waiting" });
const connectionsHref = projectHref(slug, "/connections");
- // Block the screen until `ensureProjectAgents` has finished AND the
- // gateway's runtime config snapshot has surfaced the new agents. Without
- // this, clicking Skip immediately after Continue races the
- // `openclaw agents add` config write and the kickoff fails with
- // INVALID_REQUEST "Agent '<id>' no longer exists in configuration".
- // While we're waiting the user sees a "Setting up your agents…" card
- // — same screen, same place, no surprising state transitions.
- useEffect(() => {
- let cancelled = false;
- (async () => {
- const r = await awaitOnboardingReadyAction(slug);
- if (cancelled) return;
- if (!r.ok) {
- setReadiness({ phase: "error", message: r.error });
- return;
- }
- setReadiness({ phase: "ready" });
- })();
- return () => {
- cancelled = true;
- };
- }, [slug]);
-
async function onConnect() {
setBusy(true);
try {
@@ -323,31 +299,14 @@ function ConnectStep({ slug }: { slug: string }) {
}
}
- async function onSkip() {
- // Drop the user on the CMO's PROJECT.md onboarding task — the same
- // workspace the connect path lands on. The kickoff already fired
- // server-side in createProjectForOnboardingAction, so this is just a
- // navigation: the user sees streaming events (or, if the kickoff
- // errored, the failed-task error message — much better than the
- // earlier "land on project home and figure it out" fallback).
- setBusy(true);
- try {
- const result = await getOnboardingTaskForSkipAction(slug);
- if (!result.ok) {
- toast.error(result.error);
- setBusy(false);
- return;
- }
- router.replace(
- projectHref(
- slug,
- `/agents/${result.cmo_agent_slug}/tasks?task=${encodeURIComponent(result.task_display_id)}`,
- ),
- );
- } catch (err) {
- toast.error(err instanceof Error ? err.message : String(err));
- setBusy(false);
- }
+ function onSkip() {
+ // Hand off to the dedicated setup screen instead of redirecting
+ // straight to the task. The setup screen waits for `ensureProjectAgents`
+ // to finish (publishing per-template progress) and only then resolves
+ // the CMO + first-task slugs and navigates the user in.
+ router.replace(
+ `/onboarding?step=setup&slug=${encodeURIComponent(slug)}&from=skip`,
+ );
}
return (
@@ -364,44 +323,24 @@ function ConnectStep({ slug }: { slug: string }) {
<Card>
<CardContent className="space-y-4 pt-6">
- {readiness.phase === "waiting" && (
- <div
- className="flex items-center gap-2 text-sm text-muted-foreground"
- role="status"
- aria-live="polite"
- >
- <Loader2 className="size-4 animate-spin" />
- Setting up your agents…
- </div>
- )}
- {readiness.phase === "error" && (
- <p
- className="text-sm text-destructive"
- role="alert"
+ <div className="flex flex-wrap gap-2">
+ <Button onClick={onConnect} disabled={busy} size="lg">
+ {busy ? (
+ <Loader2 className="mr-1.5 size-4 animate-spin" />
+ ) : (
+ <Plug className="mr-1.5 size-4" />
+ )}
+ Connect Google Ads
+ </Button>
+ <Button
+ onClick={onSkip}
+ variant="ghost"
+ disabled={busy}
+ aria-label="Skip Google Ads connection for now and go to CMO tasks"
>
- {readiness.message}
- </p>
- )}
- {readiness.phase === "ready" && (
- <div className="flex flex-wrap gap-2">
- <Button onClick={onConnect} disabled={busy} size="lg">
- {busy ? (
- <Loader2 className="mr-1.5 size-4 animate-spin" />
- ) : (
- <Plug className="mr-1.5 size-4" />
- )}
- Connect Google Ads
- </Button>
- <Button
- onClick={onSkip}
- variant="ghost"
- disabled={busy}
- aria-label="Skip Google Ads connection for now and go to CMO tasks"
- >
- Skip for now
- </Button>
- </div>
- )}
+ Skip for now
+ </Button>
+ </div>
<p className="text-xs text-muted-foreground">
You can disconnect anytime in{" "}
<Link href={connectionsHref} className="underline underline-offset-2">
@@ -415,6 +354,160 @@ function ConnectStep({ slug }: { slug: string }) {
);
}
+// ── Step 2.5: Setup (post-skip-or-connect provisioning watcher) ────
+
+type ProgressStep = {
+ key: string;
+ label: string;
+ status: string;
+ error?: string;
+};
+
+function statusGlyph(status: string): string {
+ if (status === "done") return "✓";
+ if (status === "failed") return "✗";
+ if (status === "in_progress") return "•";
+ return "·";
+}
+
+function SetupStep({ slug }: { slug: string }) {
+ const router = useRouter();
+ const [steps, setSteps] = useState<ProgressStep[]>([]);
+ const [error, setError] = useState<string | null>(null);
+ const redirectedRef = useRef(false);
+
+ useEffect(() => {
+ let cancelled = false;
+ let pollTimer: ReturnType<typeof setTimeout> | null = null;
+
+ async function poll(): Promise<void> {
+ if (cancelled) return;
+ try {
+ const r = await getProvisioningProgressAction(slug);
+ if (cancelled) return;
+ if (!r.ok) {
+ setError(r.error);
+ return;
+ }
+ setSteps(r.steps);
+ if (r.overall === "failed") {
+ const failed = r.steps.find((s) => s.status === "failed");
+ setError(failed?.error ?? "Provisioning failed.");
+ return;
+ }
+ if (r.overall === "done") {
+ // Resolve the CMO + first task slugs and forward to the live
+ // task workspace. Guarded so React StrictMode's double-mount
+ // doesn't fire two redirects.
+ if (redirectedRef.current) return;
+ redirectedRef.current = true;
+ const dest = await getOnboardingTaskForSkipAction(slug);
+ if (cancelled) return;
+ if (!dest.ok) {
+ setError(dest.error);
+ redirectedRef.current = false;
+ return;
+ }
+ router.replace(
+ projectHref(
+ slug,
+ `/agents/${dest.cmo_agent_slug}/tasks?task=${encodeURIComponent(dest.task_display_id)}`,
+ ),
+ );
+ return;
+ }
+ // Still running — poll again. 500ms keeps the rows feeling
+ // alive without hammering the server.
+ pollTimer = setTimeout(poll, 500);
+ } catch (err) {
+ if (cancelled) return;
+ setError(err instanceof Error ? err.message : String(err));
+ }
+ }
+
+ void poll();
+ return () => {
+ cancelled = true;
+ if (pollTimer) clearTimeout(pollTimer);
+ };
+ }, [slug, router]);
+
+ return (
+ <>
+ <header className="space-y-2">
+ <h1 className="text-3xl font-semibold tracking-tight text-foreground">
+ Setting up your agents.
+ </h1>
+ <p className="text-sm text-muted-foreground">
+ One moment — provisioning your team in OpenClaw.
+ </p>
+ </header>
+
+ <Card>
+ <CardContent className="pt-6">
+ <ul className="space-y-2" role="status" aria-live="polite">
+ {steps.length === 0 && !error && (
+ <li className="flex items-center gap-2 text-sm text-muted-foreground">
+ <Loader2 className="size-4 animate-spin" />
+ Starting…
+ </li>
+ )}
+ {steps.map((s) => (
+ <li
+ key={s.key}
+ className="flex items-center gap-2 text-sm"
+ data-status={s.status}
+ >
+ <span
+ aria-hidden
+ className={
+ s.status === "done"
+ ? "inline-flex size-4 items-center justify-center font-mono text-emerald-600"
+ : s.status === "failed"
+ ? "inline-flex size-4 items-center justify-center font-mono text-destructive"
+ : s.status === "in_progress"
+ ? "inline-flex size-4 items-center justify-center"
+ : "inline-flex size-4 items-center justify-center font-mono text-muted-foreground"
+ }
+ >
+ {s.status === "in_progress" ? (
+ <Loader2 className="size-3.5 animate-spin" />
+ ) : (
+ statusGlyph(s.status)
+ )}
+ </span>
+ <span
+ className={
+ s.status === "done"
+ ? "text-foreground"
+ : s.status === "failed"
+ ? "text-destructive"
+ : s.status === "in_progress"
+ ? "text-foreground"
+ : "text-muted-foreground"
+ }
+ >
+ {s.label}
+ </span>
+ {s.error && (
+ <span className="ml-2 text-xs text-destructive">
+ {s.error}
+ </span>
+ )}
+ </li>
+ ))}
+ </ul>
+ {error && (
+ <p className="mt-4 text-sm text-destructive" role="alert">
+ {error}
+ </p>
+ )}
+ </CardContent>
+ </Card>
+ </>
+ );
+}
+
// ── Step 3: Pick Google Ads account (auto-skipped if only 1) ───────
type AccountListState =
diff --git a/src/server/agent-templates.ts b/src/server/agent-templates.ts
index b14a8973..77f6aa52 100644
--- a/src/server/agent-templates.ts
+++ b/src/server/agent-templates.ts
@@ -3,6 +3,11 @@ import { homedir } from "node:os";
import { join } from "node:path";
import { openclaw } from "@/server/openclaw/cli";
import { listAllAgents } from "@/server/openclaw/gateway-rpc";
+import {
+ initProgress,
+ updateStep,
+ type ProgressStep,
+} from "@/server/onboarding/provisioning-progress";
import { readAgentMeta, writeAgentMeta } from "@/server/agent-meta";
import {
cleanupLegacyOrchestrationRows,
@@ -316,7 +321,27 @@ export async function ensureProjectAgents(
? TEMPLATES.filter((t) => scope.includes(t.key))
: TEMPLATES;
+ // Publish per-template progress so the onboarding setup screen can
+ // render a live "Setting up CMO… / Setting up Google Ads agent…"
+ // checklist instead of a single opaque spinner. The "gateway" row
+ // covers the snapshot-warm-up that happens after the openclaw rows
+ // are written.
+ const progressSteps: ProgressStep[] = [
+ ...templates.map<ProgressStep>((t) => ({
+ key: t.key,
+ label: `Setting up ${t.display_name}${t.key === "cmo" ? "" : " specialist"}`,
+ status: "pending",
+ })),
+ {
+ key: "gateway",
+ label: "Connecting agents to gateway",
+ status: "pending",
+ },
+ ];
+ initProgress(project_slug, progressSteps);
+
for (const template of templates) {
+ updateStep(project_slug, template.key, { status: "in_progress" });
// Resolve the personal name FIRST. The agent_id encodes it, so this
// value drives both the OpenClaw backend name and the URL slug.
const personalName = names?.[template.key] ?? template.default_name;
@@ -340,6 +365,7 @@ export async function ensureProjectAgents(
created_at: existing?.created_at ?? new Date().toISOString(),
});
existed.push(agentId);
+ updateStep(project_slug, template.key, { status: "done" });
continue;
}
try {
@@ -367,11 +393,16 @@ export async function ensureProjectAgents(
created_at: new Date().toISOString(),
});
created.push(agentId);
+ updateStep(project_slug, template.key, { status: "done" });
} catch (err) {
// Surface but don't crash the loop; partial provisioning recoverable on retry.
const message = err instanceof Error ? err.message : String(err);
console.error(`Failed to create agent ${agentId}:`, err);
failed.push({ name: agentId, error: message });
+ updateStep(project_slug, template.key, {
+ status: "failed",
+ error: message,
+ });
}
}
@@ -385,7 +416,11 @@ export async function ensureProjectAgents(
// here doesn't block provisioning — runTaskKickoffServerSide also has
// retry-on-this-error as a second line of defense.
if (created.length > 0) {
+ updateStep(project_slug, "gateway", { status: "in_progress" });
await waitForGatewayToSeeAgents(created);
+ updateStep(project_slug, "gateway", { status: "done" });
+ } else {
+ updateStep(project_slug, "gateway", { status: "done" });
}
// Register the orchestration MCP server with OpenClaw — once, globally.
diff --git a/src/server/onboarding/accounts.ts b/src/server/onboarding/accounts.ts
index dc9fe510..b5951e84 100644
--- a/src/server/onboarding/accounts.ts
+++ b/src/server/onboarding/accounts.ts
@@ -249,6 +249,49 @@ export async function setOnboardingAccountAction(
};
}
+export type ProvisioningProgressResult =
+ | { ok: true; steps: { key: string; label: string; status: string; error?: string }[]; overall: "running" | "done" | "failed" }
+ | { ok: false; error: string };
+
+/**
+ * Poll endpoint for the onboarding "Setting up your agents…" screen.
+ * Returns the live per-template provisioning checklist published by
+ * `ensureProjectAgents`. The client polls this every ~500ms while the
+ * user watches each row flip from pending → in_progress → done.
+ *
+ * Falls back to a synthesized "done" view when the in-memory progress
+ * map is empty AND the agents already exist on disk (cold-start path
+ * for users who navigate back to the setup URL after provisioning
+ * completed in a prior request).
+ */
+export async function getProvisioningProgressAction(
+ project_slug: string,
+): Promise<ProvisioningProgressResult> {
+ if (!project_slug.trim()) {
+ return { ok: false, error: "Missing project slug." };
+ }
+ const project = getProject(project_slug);
+ if (!project) return { ok: false, error: "Project not found." };
+
+ const { getProgress } = await import("./provisioning-progress");
+ const progress = getProgress(project_slug);
+ if (progress) {
+ return { ok: true, steps: progress.steps, overall: progress.overall };
+ }
+ // Cold-start: no progress record (process restart between provisioning
+ // and the user hitting this screen). Treat as done so the screen
+ // proceeds to redirect instead of hanging.
+ return {
+ ok: true,
+ steps: [
+ { key: "cmo", label: "Setting up CMO", status: "done" },
+ { key: "google_ads", label: "Setting up Google Ads specialist", status: "done" },
+ { key: "gateway", label: "Connecting agents to gateway", status: "done" },
+ ],
+ overall: "done",
+ };
+}
+
export type OnboardingReadyResult =
| { ok: true }
| { ok: false; error: string };
diff --git a/src/server/onboarding/provisioning-progress.ts b/src/server/onboarding/provisioning-progress.ts
new file mode 100644
index 00000000..00417841
--- /dev/null
+++ b/src/server/onboarding/provisioning-progress.ts
@@ -0,0 +1,75 @@
+/**
+ * Per-slug in-memory provisioning progress, published by
+ * `ensureProjectAgents` and consumed by the onboarding "Setting up your
+ * agents…" screen. Each step (CMO, Google Ads, gateway registration)
+ * transitions pending → in_progress → done so the UI can render a live
+ * checklist instead of a single opaque spinner.
+ *
+ * Pattern matches `provisioning-state.ts`: globalThis-pinned Map that
+ * survives Next.js dev hot-reload. Single-process invariant holds
+ * because the CLI launches one Next.js server per user.
+ */
+
+export type ProgressStatus = "pending" | "in_progress" | "done" | "failed";
+
+export type ProgressStep = {
+ /** Stable key — `cmo`, `google_ads`, `seo`, `gateway`. */
+ key: string;
+ /** Human label rendered as the row text. */
+ label: string;
+ status: ProgressStatus;
+ error?: string;
+};
+
+export type ProvisioningProgress = {
+ slug: string;
+ steps: ProgressStep[];
+ /** Overall verdict — `running` until every step is terminal. */
+ overall: "running" | "done" | "failed";
+};
+
+const GLOBAL_KEY = "__notfair_cmo_provisioning_progress__";
+type GlobalSlot = { store?: Map<string, ProgressStep[]> };
+const slot = globalThis as unknown as Record<string, GlobalSlot>;
+const STORE: Map<string, ProgressStep[]> =
+ (slot[GLOBAL_KEY] ??= {}).store ??
+ ((slot[GLOBAL_KEY] as GlobalSlot).store = new Map());
+
+export function initProgress(slug: string, steps: ProgressStep[]): void {
+ STORE.set(
+ slug,
+ steps.map((s) => ({ ...s })),
+ );
+}
+
+export function updateStep(
+ slug: string,
+ key: string,
+ patch: Partial<Pick<ProgressStep, "status" | "error">>,
+): void {
+ const steps = STORE.get(slug);
+ if (!steps) return;
+ const idx = steps.findIndex((s) => s.key === key);
+ if (idx < 0) return;
+ steps[idx] = { ...steps[idx]!, ...patch };
+}
+
+export function getProgress(slug: string): ProvisioningProgress | null {
+ const steps = STORE.get(slug);
+ if (!steps) return null;
+ const overall = steps.some((s) => s.status === "failed")
+ ? "failed"
+ : steps.every((s) => s.status === "done")
+ ? "done"
+ : "running";
+ return { slug, steps: steps.map((s) => ({ ...s })), overall };
+}
+
+export function clearProgress(slug: string): void {
+ STORE.delete(slug);
+}
+
+/** Test helper: drain the global Map. */
+export function __resetProgressForTesting(): void {
+ STORE.clear();
+}