From bc87ba641b2caddb66e9d5aa42725154a10bd894 Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Thu, 12 Mar 2026 19:59:35 -0700
Subject: [PATCH 1/7] Add onboarding status to Project model and implement
 related database migrations

- Introduced `onboardingStatus` field to the Project model with a default value of "completed".
- Created migration scripts to add the new column and validate its values against predefined statuses.
- Updated relevant queries and components to handle the new onboarding status in project creation and updates.
- Enhanced tests to ensure proper functionality of the onboarding status feature.
---
 .../migration.sql                             |   16 +
 .../tests/default-and-constraint.ts           |   50 +
 .../migration.sql                             |    2 +
 .../tests/constraint-is-validated.ts          |   13 +
 apps/backend/prisma/schema.prisma             |    1 +
 apps/backend/src/lib/projects.tsx             |   17 +
 .../new-project/page-client.tsx               | 1835 +++++++++++++++--
 .../projects/page-client.tsx                  |   95 +-
 .../dashboard/src/components/project-card.tsx |   36 +-
 .../api/v1/internal/projects.test.ts          |   12 +
 claude/CLAUDE-KNOWLEDGE.md                    |   12 +
 .../src/interface/crud/projects.ts            |    2 +
 packages/stack-shared/src/schema-fields.ts    |   16 +
 .../apps/implementations/admin-app-impl.ts    |    1 +
 .../src/lib/stack-app/projects/index.ts       |    4 +
 15 files changed, 1952 insertions(+), 160 deletions(-)
 create mode 100644 apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/migration.sql
 create mode 100644 apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts
 create mode 100644 apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/migration.sql
 create mode 100644 apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/tests/constraint-is-validated.ts

diff --git a/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/migration.sql b/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/migration.sql
new file mode 100644
index 0000000000..e238be468d
--- /dev/null
+++ b/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/migration.sql
@@ -0,0 +1,16 @@
+ALTER TABLE "Project"
+ADD COLUMN "onboardingStatus" TEXT NOT NULL DEFAULT 'completed';
+
+ALTER TABLE "Project"
+ADD CONSTRAINT "Project_onboardingStatus_valid"
+CHECK (
+  "onboardingStatus" IN (
+    'config_choice',
+    'apps_selection',
+    'auth_setup',
+    'domain_setup',
+    'email_theme_setup',
+    'payments_setup',
+    'completed'
+  )
+) NOT VALID;
diff --git a/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts b/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts
new file mode 100644
index 0000000000..047748b946
--- /dev/null
+++ b/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts
@@ -0,0 +1,50 @@
+import { randomUUID } from "crypto";
+import type { Sql } from "postgres";
+import { expect } from "vitest";
+
+export const preMigration = async (sql: Sql) => {
+  const projectId = `test-${randomUUID()}`;
+  await sql`
+    INSERT INTO "Project" ("id", "createdAt", "updatedAt", "displayName", "description", "isProductionMode")
+    VALUES (${projectId}, NOW(), NOW(), 'Onboarding Test', '', false)
+  `;
+  return { projectId };
+};
+
+export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof preMigration>>) => {
+  const rows = await sql`
+    SELECT "onboardingStatus"
+    FROM "Project"
+    WHERE "id" = ${ctx.projectId}
+  `;
+  expect(rows).toHaveLength(1);
+  expect(rows[0].onboardingStatus).toBe("completed");
+
+  const validProjectId = `test-${randomUUID()}`;
+  await sql`
+    INSERT INTO "Project" (
+      "id",
+      "createdAt",
+      "updatedAt",
+      "displayName",
+      "description",
+      "isProductionMode",
+      "onboardingStatus"
+    )
+    VALUES (${validProjectId}, NOW(), NOW(), 'Valid Status Project', '', false, 'auth_setup')
+  `;
+
+  const invalidProjectId = `test-${randomUUID()}`;
+  await expect(sql`
+    INSERT INTO "Project" (
+      "id",
+      "createdAt",
+      "updatedAt",
+      "displayName",
+      "description",
+      "isProductionMode",
+      "onboardingStatus"
+    )
+    VALUES (${invalidProjectId}, NOW(), NOW(), 'Invalid Status Project', '', false, 'invalid_status')
+  `).rejects.toThrow(/Project_onboardingStatus_valid/);
+};
diff --git a/apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/migration.sql b/apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/migration.sql
new file mode 100644
index 0000000000..4454dcd782
--- /dev/null
+++ b/apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/migration.sql
@@ -0,0 +1,2 @@
+ALTER TABLE "Project"
+VALIDATE CONSTRAINT "Project_onboardingStatus_valid";
diff --git a/apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/tests/constraint-is-validated.ts b/apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/tests/constraint-is-validated.ts
new file mode 100644
index 0000000000..90c7ff5d45
--- /dev/null
+++ b/apps/backend/prisma/migrations/20260312000001_validate_project_onboarding_status_constraint/tests/constraint-is-validated.ts
@@ -0,0 +1,13 @@
+import type { Sql } from "postgres";
+import { expect } from "vitest";
+
+export const postMigration = async (sql: Sql) => {
+  const rows = await sql`
+    SELECT "convalidated"
+    FROM "pg_constraint"
+    WHERE "conname" = 'Project_onboardingStatus_valid'
+  `;
+
+  expect(rows).toHaveLength(1);
+  expect(rows[0].convalidated).toBe(true);
+};
diff --git a/apps/backend/prisma/schema.prisma b/apps/backend/prisma/schema.prisma
index 17760a2430..0d408ff0ba 100644
--- a/apps/backend/prisma/schema.prisma
+++ b/apps/backend/prisma/schema.prisma
@@ -26,6 +26,7 @@ model Project {
   description      String  @default("")
   isProductionMode Boolean
   ownerTeamId      String? @db.Uuid
+  onboardingStatus String  @default("completed")
 
   logoUrl             String?
   logoFullUrl         String?
diff --git a/apps/backend/src/lib/projects.tsx b/apps/backend/src/lib/projects.tsx
index 78b6db54a1..52a0bcb5c7 100644
--- a/apps/backend/src/lib/projects.tsx
+++ b/apps/backend/src/lib/projects.tsx
@@ -66,6 +66,7 @@ export function getProjectQuery(projectId: string): RawQuery<Promise<Omit<Projec
         created_at_millis: new Date(row.createdAt + "Z").getTime(),
         is_production_mode: row.isProductionMode,
         owner_team_id: row.ownerTeamId,
+        onboarding_status: row.onboardingStatus,
       };
     },
   };
@@ -119,6 +120,14 @@ export async function createOrUpdateProjectWithLegacyConfig(
         },
       });
 
+      if (options.data.onboarding_status !== undefined) {
+        await tx.$executeRaw`
+          UPDATE "Project"
+          SET "onboardingStatus" = ${options.data.onboarding_status}
+          WHERE "id" = ${project.id}
+        `;
+      }
+
       await tx.tenancy.create({
         data: {
           projectId: project.id,
@@ -152,6 +161,14 @@ export async function createOrUpdateProjectWithLegacyConfig(
           logoFullDarkModeUrl: logoUrls['logo_full_dark_mode_url'],
         },
       });
+
+      if (options.data.onboarding_status !== undefined) {
+        await tx.$executeRaw`
+          UPDATE "Project"
+          SET "onboardingStatus" = ${options.data.onboarding_status}
+          WHERE "id" = ${project.id}
+        `;
+      }
       branchId = options.branchId;
     }
 
diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
index ff12f51813..4b1dd8841b 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
@@ -1,59 +1,1507 @@
 'use client';
-import { FieldLabel, InputField, SwitchListField } from "@/components/form-fields";
+
+import { AppIcon } from "@/components/app-square";
 import { useRouter } from "@/components/router";
-import { yupResolver } from "@hookform/resolvers/yup";
+import { DesignAlert } from "@/components/design-components/alert";
+import { DesignBadge } from "@/components/design-components/badge";
+import { DesignButton } from "@/components/design-components/button";
+import { DesignCard } from "@/components/design-components/card";
+import { DesignInput } from "@/components/design-components/input";
+import { DesignSelectorDropdown } from "@/components/design-components/select";
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  Button,
+  BrowserFrame,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Label,
+  Spinner,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Switch,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+  Typography,
+  cn,
+} from "@/components/ui";
 import { getPublicEnvVar } from "@/lib/env";
-import { AuthPage, TeamSwitcher, useUser } from "@stackframe/stack";
-import { allProviders } from "@stackframe/stack-shared/dist/utils/oauth";
+import { useUpdateConfig } from "@/lib/config-update";
+import { stackAppInternalsSymbol } from "@/lib/stack-app-internals";
+import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  ArrowsClockwiseIcon,
+  ChartBarIcon,
+  CheckCircleIcon,
+  CircleIcon,
+  GlobeIcon,
+  LightningIcon,
+  LinkBreakIcon,
+  PlusCircleIcon,
+  ShieldIcon,
+  StripeLogoIcon,
+  WalletIcon,
+  WarningCircleIcon,
+  WebhooksLogoIcon,
+} from "@phosphor-icons/react";
+import { AdminOwnedProject, AuthPage, useStackApp, useUser } from "@stackframe/stack";
+import { previewTemplateSource } from "@stackframe/stack-shared/dist/helpers/emails";
+import { ALL_APPS, type AppId } from "@stackframe/stack-shared/dist/apps/apps-config";
 import { runAsynchronouslyWithAlert, wait } from "@stackframe/stack-shared/dist/utils/promises";
-import { BrowserFrame, Button, Form, FormControl, FormField, FormItem, FormMessage, Separator, Typography } from "@/components/ui";
+import { allProviders } from "@stackframe/stack-shared/dist/utils/oauth";
+import { stringCompare } from "@stackframe/stack-shared/dist/utils/strings";
+import { generateUuid } from "@stackframe/stack-shared/dist/utils/uuids";
 import { useSearchParams } from "next/navigation";
-import { useState } from "react";
-import { useForm } from "react-hook-form";
-import * as yup from "yup";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+const PROJECT_ONBOARDING_STATUSES = [
+  "config_choice",
+  "apps_selection",
+  "auth_setup",
+  "domain_setup",
+  "email_theme_setup",
+  "payments_setup",
+  "completed",
+] as const;
+
+type ProjectOnboardingStatus = (typeof PROJECT_ONBOARDING_STATUSES)[number];
+
+type SignInMethod = "credential" | "magicLink" | "passkey" | "google" | "github" | "microsoft";
+
+const SIGN_IN_METHODS: Array<{ id: SignInMethod, label: string }> = [
+  { id: "credential", label: "Email & password" },
+  { id: "magicLink", label: "Magic link / OTP" },
+  { id: "passkey", label: "Passkey" },
+  { id: "google", label: "Google" },
+  { id: "github", label: "GitHub" },
+  { id: "microsoft", label: "Microsoft" },
+];
+
+const REQUIRED_APP_IDS: AppId[] = ["authentication", "emails"];
+const PRIMARY_APP_IDS: AppId[] = ["authentication", "emails", "payments", "analytics"];
+const ALL_APP_IDS = Object.keys(ALL_APPS) as AppId[];
+
+type StackAppInternals = {
+  sendRequest: (path: string, requestOptions: RequestInit, requestType?: "client" | "server" | "admin") => Promise<Response>,
+  refreshOwnedProjects: () => Promise<void>,
+};
+
+type TimelineStep = {
+  id: ProjectOnboardingStatus,
+  label: string,
+};
+
+const PAYMENT_COUNTRY_OPTIONS = [
+  { value: "US", label: "United States" },
+  { value: "OTHER", label: "Other" },
+] as const;
+
+function isStackAppInternals(value: unknown): value is StackAppInternals {
+  return (
+    value != null
+    && typeof value === "object"
+    && "sendRequest" in value
+    && typeof value.sendRequest === "function"
+    && "refreshOwnedProjects" in value
+    && typeof value.refreshOwnedProjects === "function"
+  );
+}
+
+function getStackAppInternals(appValue: unknown): StackAppInternals {
+  if (appValue == null || typeof appValue !== "object") {
+    throw new Error("The Stack app instance is unavailable.");
+  }
+
+  const internals = Reflect.get(appValue, stackAppInternalsSymbol);
+  if (!isStackAppInternals(internals)) {
+    throw new Error("The Stack client app cannot send internal requests.");
+  }
+
+  return internals;
+}
+
+function isProjectOnboardingStatus(value: unknown): value is ProjectOnboardingStatus {
+  return typeof value === "string" && PROJECT_ONBOARDING_STATUSES.some((status) => status === value);
+}
+
+function orderedAppIds() {
+  const primarySet = new Set(PRIMARY_APP_IDS);
+  const secondary = ALL_APP_IDS.filter((appId) => !primarySet.has(appId)).sort((a, b) => {
+    return stringCompare(ALL_APPS[a].displayName, ALL_APPS[b].displayName);
+  });
+  return [...PRIMARY_APP_IDS, ...secondary];
+}
+
+function normalizeTrustedDomain(input: string): string {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error("Trusted domain must be a valid URL.");
+  }
+
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error("Trusted domain must start with http:// or https://.");
+  }
+
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function buildTimeline(includePayments: boolean): TimelineStep[] {
+  const timeline: TimelineStep[] = [
+    { id: "config_choice", label: "Config" },
+    { id: "apps_selection", label: "Apps" },
+    { id: "auth_setup", label: "Auth" },
+    { id: "domain_setup", label: "Domains" },
+    { id: "email_theme_setup", label: "Email Theme" },
+  ];
+
+  if (includePayments) {
+    timeline.push({ id: "payments_setup", label: "Payments" });
+  }
+
+  timeline.push({ id: "completed", label: "Finish" });
+  return timeline;
+}
+
+function deriveInitialSignInMethods(project: AdminOwnedProject): Set<SignInMethod> {
+  const config = project.config;
+  const methods = new Set<SignInMethod>([
+    "credential",
+    "magicLink",
+    "google",
+    "github",
+  ]);
+
+  if (config.credentialEnabled) {
+    methods.add("credential");
+  }
+  if (config.magicLinkEnabled) {
+    methods.add("magicLink");
+  }
+  if (config.passkeyEnabled) {
+    methods.add("passkey");
+  }
+
+  for (const provider of config.oauthProviders) {
+    if (provider.id === "google" || provider.id === "github" || provider.id === "microsoft") {
+      methods.add(provider.id);
+    }
+  }
+
+  return methods;
+}
+
+function deriveInitialApps(config: ReturnType<AdminOwnedProject["useConfig"]>): Set<AppId> {
+  const enabledApps = new Set<AppId>();
+
+  for (const appId of ALL_APP_IDS) {
+    if (config.apps.installed[appId]?.enabled) {
+      enabledApps.add(appId);
+    }
+  }
+
+  if (enabledApps.size === 0) {
+    for (const primaryAppId of PRIMARY_APP_IDS) {
+      enabledApps.add(primaryAppId);
+    }
+  }
+
+  for (const requiredAppId of REQUIRED_APP_IDS) {
+    enabledApps.add(requiredAppId);
+  }
+
+  return enabledApps;
+}
+
+function getStepIndex(steps: TimelineStep[], stepId: ProjectOnboardingStatus) {
+  return steps.findIndex((step) => step.id === stepId);
+}
+
+function OnboardingTimeline(props: {
+  steps: TimelineStep[],
+  currentStep: ProjectOnboardingStatus,
+  onStepClick?: (step: ProjectOnboardingStatus) => void,
+  disabled?: boolean,
+}) {
+  const currentIndex = props.steps.findIndex((step) => step.id === props.currentStep);
+
+  return (
+    <div className="w-full overflow-x-auto pb-1">
+      <div className="flex min-w-max items-center justify-center gap-2">
+        {props.steps.map((step, index) => {
+          const isComplete = index < currentIndex;
+          const isCurrent = index === currentIndex;
+          const isClickable = isComplete && !props.disabled && props.onStepClick != null;
+          const circleClassName = isComplete
+            ? "bg-green-500 text-white"
+            : isCurrent
+              ? "bg-blue-600 text-white"
+              : "bg-muted text-muted-foreground";
+
+          return (
+            <div className="flex items-center gap-2" key={step.id}>
+              {isClickable ? (
+                <button
+                  type="button"
+                  className="flex items-center gap-2 rounded-full border bg-background px-3 py-1.5 transition-colors duration-150 hover:transition-none hover:border-foreground/25 hover:bg-foreground/[0.03]"
+                  onClick={() => props.onStepClick?.(step.id)}
+                >
+                  <div
+                    className={cn(
+                      "flex h-6 w-6 items-center justify-center rounded-full text-xs font-semibold",
+                      circleClassName
+                    )}
+                  >
+                    <CheckCircleIcon className="h-4 w-4" />
+                  </div>
+                  <span className={cn("text-sm", isCurrent ? "font-semibold text-foreground" : "text-muted-foreground")}>{step.label}</span>
+                </button>
+              ) : (
+                <div className="flex items-center gap-2 rounded-full border bg-background px-3 py-1.5">
+                  <div
+                    className={cn(
+                      "flex h-6 w-6 items-center justify-center rounded-full text-xs font-semibold",
+                      circleClassName
+                    )}
+                  >
+                    {isComplete ? <CheckCircleIcon className="h-4 w-4" /> : index + 1}
+                  </div>
+                  <span className={cn("text-sm", isCurrent ? "font-semibold text-foreground" : "text-muted-foreground")}>{step.label}</span>
+                </div>
+              )}
+              {index < props.steps.length - 1 && <div className="h-px w-8 bg-border" />}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function appStageBadgeColor(stage: (typeof ALL_APPS)[AppId]["stage"]) {
+  if (stage === "alpha") {
+    return "orange";
+  }
+  if (stage === "beta") {
+    return "blue";
+  }
+  return null;
+}
+
+function appStageLabel(stage: (typeof ALL_APPS)[AppId]["stage"]) {
+  if (stage === "alpha") {
+    return "Alpha";
+  }
+  if (stage === "beta") {
+    return "Beta";
+  }
+  return null;
+}
+
+function OnboardingAppCard(props: {
+  appId: AppId,
+  selected: boolean,
+  required: boolean,
+  primary: boolean,
+  disabled?: boolean,
+  onToggle: () => void,
+}) {
+  const app = ALL_APPS[props.appId];
+  const stageBadgeColor = appStageBadgeColor(app.stage);
+  const stageLabel = appStageLabel(app.stage);
+
+  return (
+    <Tooltip delayDuration={0}>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          onClick={props.onToggle}
+          disabled={props.disabled}
+          className={cn(
+            "group relative w-full overflow-hidden rounded-2xl border transition-[transform,background-color,border-color,box-shadow] duration-150 hover:transition-none",
+            props.primary ? "min-h-[136px] px-4 py-4" : "min-h-[108px] px-3 py-3",
+            props.selected
+              ? "border-blue-500/45 bg-blue-500/[0.05] shadow-[0_8px_24px_rgba(59,130,246,0.08)]"
+              : "border-border bg-background/80 hover:border-foreground/20 hover:bg-foreground/[0.03]",
+            "active:scale-[0.99]",
+          )}
+        >
+          <div className="absolute inset-0 bg-gradient-to-br from-transparent via-transparent to-blue-500/[0.03] opacity-0 transition-opacity duration-150 group-hover:opacity-100 group-hover:transition-none" />
+          {props.selected && (
+            <div className="absolute right-3 top-3 z-10 flex h-6 w-6 items-center justify-center rounded-full bg-green-500 text-white shadow-sm">
+              <CheckCircleIcon className="h-4 w-4" weight="fill" />
+            </div>
+          )}
+          {props.primary ? (
+            <div className="relative flex h-full flex-col items-center justify-center gap-3 text-center">
+              <div className="flex w-full items-center justify-center">
+                <div className="scale-[0.72] rounded-2xl">
+                  <AppIcon appId={props.appId} enabled={props.selected} />
+                </div>
+              </div>
+
+              <div className="w-full space-y-2">
+                <div className="flex items-center justify-center gap-2">
+                  <Typography className="text-base font-semibold leading-tight">
+                    {app.displayName}
+                  </Typography>
+                </div>
+                <div className="flex min-h-6 items-center justify-center gap-2">
+                  {props.required && (
+                    <DesignBadge label="Required" color="green" size="sm" />
+                  )}
+                  {!props.required && stageBadgeColor && stageLabel && (
+                    <DesignBadge
+                      label={stageLabel}
+                      color={stageBadgeColor}
+                      size="sm"
+                    />
+                  )}
+                </div>
+              </div>
+            </div>
+          ) : (
+            <div className="relative flex h-full flex-col items-center justify-center gap-2 text-center">
+              <div className="shrink-0 scale-[0.56]">
+                <AppIcon appId={props.appId} enabled={props.selected} />
+              </div>
+              <div className="min-w-0 space-y-1">
+                <div className="flex items-center justify-center gap-1.5">
+                  <Typography className="truncate text-[11px] font-medium leading-tight">
+                    {app.displayName}
+                  </Typography>
+                </div>
+                <div className="flex min-h-5 items-center justify-center gap-1.5">
+                  {props.required && (
+                    <DesignBadge label="Required" color="green" size="sm" />
+                  )}
+                  {!props.required && stageBadgeColor && stageLabel && (
+                    <DesignBadge
+                      label={stageLabel}
+                      color={stageBadgeColor}
+                      size="sm"
+                    />
+                  )}
+                </div>
+              </div>
+            </div>
+          )}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent
+        side="top"
+        className="z-50 max-w-xs rounded-2xl border border-white/[0.08] bg-background/95 p-4 backdrop-blur-xl"
+      >
+        <div className="space-y-2">
+          <div className="flex items-center gap-2">
+            <Typography className="text-sm font-semibold">{app.displayName}</Typography>
+            {stageBadgeColor && (
+              <DesignBadge
+                label={app.stage === "alpha" ? "Alpha" : "Beta"}
+                color={stageBadgeColor}
+                size="sm"
+              />
+            )}
+          </div>
+          <Typography variant="secondary" className="text-xs leading-relaxed">
+            {app.subtitle}
+          </Typography>
+        </div>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function OnboardingEmailThemePreview(props: {
+  adminApp: AdminOwnedProject["app"],
+  themeId: string,
+}) {
+  const previewHtml = props.adminApp.useEmailPreview({
+    themeId: props.themeId,
+    templateTsxSource: previewTemplateSource,
+  });
+
+  const inertPreviewHtml = previewHtml ? `${previewHtml}
+    <script>
+      document.addEventListener('click', function(e) {
+        var target = e.target;
+        while (target && target.tagName !== 'A') {
+          target = target.parentNode;
+        }
+        if (target && target.tagName === 'A') {
+          e.preventDefault();
+          e.stopPropagation();
+        }
+      }, true);
+    </script>
+  ` : previewHtml;
+
+  return (
+    <iframe
+      srcDoc={inertPreviewHtml}
+      className="pointer-events-none h-full w-full border-0"
+      title="Email theme preview"
+    />
+  );
+}
+
+function ModeNotImplementedCard(props: { onBack: () => void }) {
+  return (
+    <DesignCard
+      className="w-full"
+      title="Link Existing Config"
+      subtitle="This feature has not been implemented yet."
+      icon={LinkBreakIcon}
+      gradient="default"
+      glassmorphic
+      contentClassName="flex min-h-[420px] flex-col justify-between gap-6"
+    >
+      <DesignAlert
+        variant="warning"
+        title="Not available yet"
+        description="Linking an existing config into the onboarding flow is on the roadmap. You can go back and continue with Create New."
+        glassmorphic
+      />
+      <div className="mt-6 flex justify-end">
+        <DesignButton variant="outline" className="rounded-xl" onClick={props.onBack}>
+          Go Back
+        </DesignButton>
+      </div>
+    </DesignCard>
+  );
+}
+
+function ProjectOnboardingWizard(props: {
+  project: AdminOwnedProject,
+  status: ProjectOnboardingStatus,
+  mode: string | null,
+  setMode: (mode: string | null) => void,
+  setStatus: (status: ProjectOnboardingStatus) => Promise<void>,
+  onComplete: () => void,
+}) {
+  const router = useRouter();
+  const { project, status, setMode, setStatus, onComplete } = props;
+  const completeConfig = project.useConfig();
+  const updateConfig = useUpdateConfig();
+  const setProjectOnboardingStatus = setStatus;
+  const finishProjectOnboarding = onComplete;
+  const [saving, setSaving] = useState(false);
+  const [selectedApps, setSelectedApps] = useState<Set<AppId>>(() => deriveInitialApps(completeConfig));
+  const [signInMethods, setSignInMethods] = useState<Set<SignInMethod>>(() => deriveInitialSignInMethods(project));
+  const [trustedDomain, setTrustedDomain] = useState("");
+  const [domainHandlerPath, setDomainHandlerPath] = useState("/handler");
+  const [managedSubdomain, setManagedSubdomain] = useState("");
+  const [managedSenderLocalPart, setManagedSenderLocalPart] = useState("");
+  const [managedDomainSetupStatus, setManagedDomainSetupStatus] = useState<string | null>(null);
+  const [requiredAppsNotice, setRequiredAppsNotice] = useState<string | null>(null);
+  const [selectedEmailThemeId, setSelectedEmailThemeId] = useState(completeConfig.emails.selectedThemeId);
+  const [selectedPaymentsCountry, setSelectedPaymentsCountry] = useState("US");
+  const [selectedConfigChoice, setSelectedConfigChoice] = useState<"create-new" | "link-existing">("create-new");
+  const previousProjectId = useRef<string | null>(null);
+
+  const runWithSaving = useCallback(async (fn: () => Promise<void>) => {
+    setSaving(true);
+    try {
+      await fn();
+    } finally {
+      setSaving(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (previousProjectId.current === project.id) {
+      return;
+    }
+    previousProjectId.current = project.id;
+
+    setSelectedApps(deriveInitialApps(completeConfig));
+    setSignInMethods(deriveInitialSignInMethods(project));
+
+    const trustedDomains = Object.values(completeConfig.domains.trustedDomains)
+      .filter((entry) => entry.baseUrl != null)
+      .map((entry) => ({ baseUrl: entry.baseUrl, handlerPath: entry.handlerPath }));
+
+    if (trustedDomains[0]) {
+      setTrustedDomain(trustedDomains[0].baseUrl ?? "");
+      setDomainHandlerPath(trustedDomains[0].handlerPath ?? "/handler");
+    } else {
+      setTrustedDomain("");
+      setDomainHandlerPath("/handler");
+    }
+
+    const serverConfig = completeConfig.emails.server;
+    setManagedSubdomain(serverConfig.managedSubdomain ?? "");
+    setManagedSenderLocalPart(serverConfig.managedSenderLocalPart ?? "");
+    setSelectedEmailThemeId(completeConfig.emails.selectedThemeId);
+    setManagedDomainSetupStatus(null);
+    setRequiredAppsNotice(null);
+    setSelectedConfigChoice("create-new");
+  }, [completeConfig, project, project.id]);
+
+  const emailThemes = project.app.useEmailThemes();
+  const includePayments = selectedApps.has("payments") || status === "payments_setup" || completeConfig.apps.installed.payments?.enabled === true;
+  const timelineSteps = useMemo(() => buildTimeline(includePayments), [includePayments]);
+  const currentTimelineIndex = useMemo(() => getStepIndex(timelineSteps, status), [status, timelineSteps]);
+
+  const handleTimelineStepClick = useCallback((step: ProjectOnboardingStatus) => {
+    const targetIndex = getStepIndex(timelineSteps, step);
+    if (targetIndex < 0 || targetIndex >= currentTimelineIndex) {
+      return;
+    }
+
+    runAsynchronouslyWithAlert(async () => {
+      if (step === "config_choice") {
+        setMode(null);
+      }
+      await setStatus(step);
+    });
+  }, [currentTimelineIndex, setMode, setStatus, timelineSteps]);
+
+  const authPreviewProject = useMemo(() => {
+    return {
+      id: project.id,
+      config: {
+        signUpEnabled: true,
+        credentialEnabled: signInMethods.has("credential"),
+        magicLinkEnabled: signInMethods.has("magicLink"),
+        passkeyEnabled: signInMethods.has("passkey"),
+        oauthProviders: (allProviders as readonly string[])
+          .filter((providerId) => signInMethods.has(providerId as SignInMethod))
+          .map((providerId) => ({ id: providerId, type: "shared" as const })),
+      },
+    };
+  }, [project.id, signInMethods]);
+
+  const toggleSignInMethod = (method: SignInMethod, enabled: boolean) => {
+    setSignInMethods((previous) => {
+      const next = new Set(previous);
+      if (enabled) {
+        next.add(method);
+      } else {
+        next.delete(method);
+      }
+      return next;
+    });
+  };
+
+  const toggleApp = (appId: AppId) => {
+    setSelectedApps((previous) => {
+      const next = new Set(previous);
+      if (REQUIRED_APP_IDS.includes(appId)) {
+        if (next.has(appId)) {
+          setRequiredAppsNotice(`${ALL_APPS[appId].displayName} is required during onboarding and can't be turned off.`);
+        }
+        next.add(appId);
+        return next;
+      }
+
+      setRequiredAppsNotice(null);
+      if (next.has(appId)) {
+        next.delete(appId);
+      } else {
+        next.add(appId);
+      }
+      return next;
+    });
+  };
+
+  const finalizeOnboarding = useCallback(async () => {
+    await runWithSaving(async () => {
+      await setProjectOnboardingStatus("completed");
+      finishProjectOnboarding();
+    });
+  }, [finishProjectOnboarding, runWithSaving, setProjectOnboardingStatus]);
+
+  if (props.status === "config_choice" && props.mode === "link-existing") {
+    return (
+      <div className="mx-auto flex w-full max-w-7xl flex-1 flex-col min-h-0 space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="config_choice"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <div className="flex min-h-0 flex-1 flex-col">
+          <ModeNotImplementedCard onBack={() => { props.setMode(null); setSelectedConfigChoice("create-new"); }} />
+        </div>
+      </div>
+    );
+  }
+
+  if (props.status === "config_choice") {
+    const createNewSelected = selectedConfigChoice === "create-new";
+    const linkExistingSelected = selectedConfigChoice === "link-existing";
+
+    return (
+      <div className="mx-auto flex w-full max-w-7xl flex-1 flex-col min-h-0 space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="config_choice"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <DesignCard
+          className="flex min-h-0 flex-1 flex-col w-full"
+          title="Choose How You Want To Start"
+          subtitle="Create a fresh Stack Auth config, or link an existing config file."
+          icon={LightningIcon}
+          gradient="blue"
+          glassmorphic
+          contentClassName="flex min-h-[calc(100vh-220px)] flex-1 flex-col gap-6"
+          actions={
+            <DesignButton
+              className="rounded-xl"
+              loading={saving}
+              onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                if (selectedConfigChoice === "create-new") {
+                  await props.setStatus("apps_selection");
+                } else if (selectedConfigChoice === "link-existing") {
+                  props.setMode("link-existing");
+                }
+              }))}
+            >
+              Next
+            </DesignButton>
+          }
+        >
+          <div className="grid min-h-[280px] flex-1 gap-4 md:grid-cols-2">
+            <button
+              type="button"
+              className={cn(
+                "group relative flex min-h-[260px] flex-col items-center justify-center gap-4 rounded-3xl border p-6 text-center transition-colors duration-150 hover:transition-none",
+                createNewSelected
+                  ? "border-blue-500/45 bg-blue-500/[0.06] shadow-[0_8px_24px_rgba(59,130,246,0.08)]"
+                  : "border-black/[0.08] bg-background/70 hover:bg-foreground/[0.03] dark:border-white/[0.08]",
+              )}
+              onClick={() => setSelectedConfigChoice("create-new")}
+              disabled={saving}
+            >
+              {createNewSelected && (
+                <div className="absolute right-4 top-4 z-10 flex h-7 w-7 items-center justify-center rounded-full bg-green-500 text-white shadow-sm">
+                  <CheckCircleIcon className="h-4 w-4" weight="fill" />
+                </div>
+              )}
+              <div className="flex flex-col items-center gap-4 text-center">
+                <div
+                  className={cn(
+                    "w-fit rounded-xl p-2",
+                    createNewSelected ? "bg-blue-500/10 text-blue-600" : "bg-foreground/[0.05] text-muted-foreground",
+                  )}
+                >
+                  <LightningIcon className="h-6 w-6" />
+                </div>
+                <div className="space-y-2">
+                  <Typography type="h3">Create New</Typography>
+                  <Typography variant="secondary">Start from curated defaults and configure apps step-by-step.</Typography>
+                </div>
+              </div>
+            </button>
+
+            <button
+              type="button"
+              className={cn(
+                "group relative flex min-h-[260px] flex-col items-center justify-center gap-4 rounded-3xl border p-6 text-center transition-colors duration-150 hover:transition-none",
+                linkExistingSelected
+                  ? "border-blue-500/45 bg-blue-500/[0.06] shadow-[0_8px_24px_rgba(59,130,246,0.08)]"
+                  : "border-black/[0.08] bg-background/70 hover:bg-foreground/[0.03] dark:border-white/[0.08]",
+              )}
+              onClick={() => setSelectedConfigChoice("link-existing")}
+              disabled={saving}
+            >
+              {linkExistingSelected && (
+                <div className="absolute right-4 top-4 z-10 flex h-7 w-7 items-center justify-center rounded-full bg-green-500 text-white shadow-sm">
+                  <CheckCircleIcon className="h-4 w-4" weight="fill" />
+                </div>
+              )}
+              <div className="flex flex-col items-center gap-4 text-center">
+                <div
+                  className={cn(
+                    "w-fit rounded-xl p-2",
+                    linkExistingSelected ? "bg-blue-500/10 text-blue-600" : "bg-foreground/[0.05] text-muted-foreground",
+                  )}
+                >
+                  <LinkBreakIcon className="h-6 w-6" />
+                </div>
+                <div className="space-y-2">
+                  <Typography type="h3">Link Existing Config</Typography>
+                  <Typography variant="secondary">Bring an existing config into this project.</Typography>
+                </div>
+              </div>
+            </button>
+          </div>
+        </DesignCard>
+      </div>
+    );
+  }
+
+  if (props.status === "apps_selection") {
+    const orderedIds = orderedAppIds();
+    const primaryAppIds = orderedIds.filter((appId) => PRIMARY_APP_IDS.includes(appId));
+    const secondaryAppIds = orderedIds.filter((appId) => !PRIMARY_APP_IDS.includes(appId));
+
+    return (
+      <div className="mx-auto w-full max-w-7xl space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="apps_selection"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <DesignCard
+          className="w-full"
+          title="Select Apps"
+          subtitle="Authentication, Emails, Payments, and Analytics are selected by default. Authentication and Emails are required."
+          icon={LightningIcon}
+          gradient="cyan"
+          glassmorphic
+          contentClassName="space-y-6"
+          actions={
+            <DesignButton
+              className="rounded-xl"
+              loading={saving}
+              onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                const appConfigUpdates = Object.fromEntries(
+                  ALL_APP_IDS.map((appId) => [
+                    `apps.installed.${appId}.enabled`,
+                    selectedApps.has(appId),
+                  ])
+                );
+
+                const configUpdated = await updateConfig({
+                  adminApp: props.project.app,
+                  configUpdate: appConfigUpdates,
+                  pushable: true,
+                });
+                if (!configUpdated) {
+                  return;
+                }
+                await props.setStatus("auth_setup");
+              }))}
+            >
+              Next
+            </DesignButton>
+          }
+        >
+          <TooltipProvider delayDuration={0}>
+            <div className="space-y-6">
+              {requiredAppsNotice && (
+                <DesignAlert
+                  variant="info"
+                  title="Required app"
+                  description={requiredAppsNotice}
+                  glassmorphic
+                />
+              )}
+
+              <div className="mx-auto max-w-2xl space-y-2 text-center">
+                <Typography className="text-xl font-semibold tracking-tight text-foreground sm:text-2xl">
+                  Select apps
+                </Typography>
+                <Typography variant="secondary" className="text-sm">
+                  Start with the core Stack Auth apps now. You can enable or disable the rest later.
+                </Typography>
+              </div>
+
+              <div className="mx-auto w-full max-w-5xl space-y-4">
+                <div className="flex items-center justify-center">
+                  <DesignBadge label="Core apps" color="blue" size="sm" />
+                </div>
+                <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+                  {primaryAppIds.map((appId) => (
+                    <OnboardingAppCard
+                      key={appId}
+                      appId={appId}
+                      selected={selectedApps.has(appId)}
+                      required={REQUIRED_APP_IDS.includes(appId)}
+                      primary
+                      disabled={saving}
+                      onToggle={() => toggleApp(appId)}
+                    />
+                  ))}
+                </div>
+              </div>
 
-export const projectFormSchema = yup.object({
-  displayName: yup.string().min(1, "Display name is required").defined().nonEmpty("Display name is required"),
-  signInMethods: yup.array(yup.string().oneOf(["credential", "magicLink", "passkey"].concat(allProviders)).defined())
-    .min(1, "At least one sign-in method is required")
-    .defined("At least one sign-in method is required"),
-  teamId: yup.string().uuid().defined("Team is required"),
-});
+              <div className="space-y-4">
+                <div className="flex items-center gap-3">
+                  <Typography className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                    More apps
+                  </Typography>
+                </div>
+                <div
+                  className="grid gap-3"
+                  style={{ gridTemplateColumns: "repeat(auto-fill, minmax(150px, 1fr))" }}
+                >
+                  {secondaryAppIds.map((appId) => (
+                    <OnboardingAppCard
+                      key={appId}
+                      appId={appId}
+                      selected={selectedApps.has(appId)}
+                      required={REQUIRED_APP_IDS.includes(appId)}
+                      primary={false}
+                      disabled={saving}
+                      onToggle={() => toggleApp(appId)}
+                    />
+                  ))}
+                </div>
+              </div>
+
+              <Typography variant="secondary" className="text-xs">
+                Core apps are ready by default, and required apps stay enabled through onboarding.
+              </Typography>
+            </div>
+          </TooltipProvider>
+        </DesignCard>
+      </div>
+    );
+  }
+
+  if (props.status === "auth_setup") {
+    return (
+      <div className="mx-auto w-full max-w-7xl space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="auth_setup"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <DesignCard
+          className="w-full"
+          title="Configure Authentication"
+          subtitle="Choose sign-in methods and preview your sign-in page."
+          icon={CheckCircleIcon}
+          gradient="blue"
+          glassmorphic
+          contentClassName="flex min-h-[520px] flex-col gap-6"
+          actions={
+            <DesignButton
+              className="rounded-xl"
+              loading={saving}
+              onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                if (signInMethods.size === 0) {
+                  throw new Error("Select at least one sign-in method before continuing.");
+                }
+
+                const authMethodsUpdated = await updateConfig({
+                  adminApp: props.project.app,
+                  configUpdate: {
+                    "auth.password.allowSignIn": signInMethods.has("credential"),
+                    "auth.otp.allowSignIn": signInMethods.has("magicLink"),
+                    "auth.passkey.allowSignIn": signInMethods.has("passkey"),
+                  },
+                  pushable: true,
+                });
+
+                if (!authMethodsUpdated) {
+                  return;
+                }
+
+                const providersUpdated = await updateConfig({
+                  adminApp: props.project.app,
+                  configUpdate: {
+                    "auth.oauth.providers.google": signInMethods.has("google") ? {
+                      type: "google",
+                      isShared: true,
+                      allowSignIn: true,
+                      allowConnectedAccounts: true,
+                    } : null,
+                    "auth.oauth.providers.github": signInMethods.has("github") ? {
+                      type: "github",
+                      isShared: true,
+                      allowSignIn: true,
+                      allowConnectedAccounts: true,
+                    } : null,
+                    "auth.oauth.providers.microsoft": signInMethods.has("microsoft") ? {
+                      type: "microsoft",
+                      isShared: true,
+                      allowSignIn: true,
+                      allowConnectedAccounts: true,
+                    } : null,
+                  },
+                  pushable: false,
+                });
+
+                if (!providersUpdated) {
+                  return;
+                }
+
+                await props.setStatus("domain_setup");
+              }))}
+            >
+              Next
+            </DesignButton>
+          }
+        >
+          <div className="grid flex-1 overflow-hidden rounded-2xl border border-black/[0.08] bg-background/70 dark:border-white/[0.08] xl:grid-cols-[minmax(0,2fr)_minmax(0,3fr)]">
+            <div className="flex items-center justify-center px-6 py-8">
+              <div className="w-full max-w-[280px] space-y-5">
+                <div className="space-y-2">
+                  <Typography type="h3">Sign-in methods</Typography>
+                  <Typography variant="secondary" className="text-sm">
+                    More sign-in methods are available on the dashboard later.
+                  </Typography>
+                </div>
+
+                <div className="rounded-2xl border border-black/[0.08] bg-background/80 dark:border-white/[0.08]">
+                  {SIGN_IN_METHODS.map((method, index) => {
+                    const checked = signInMethods.has(method.id);
+                    return (
+                      <label
+                        key={method.id}
+                        className={cn(
+                          "flex items-center justify-between gap-4 px-4 py-3",
+                          index !== SIGN_IN_METHODS.length - 1 && "border-b border-black/[0.06] dark:border-white/[0.06]",
+                        )}
+                      >
+                        <span className="text-sm">{method.label}</span>
+                        <Switch
+                          checked={checked}
+                          onCheckedChange={(nextChecked) => toggleSignInMethod(method.id, nextChecked)}
+                        />
+                      </label>
+                    );
+                  })}
+                </div>
+              </div>
+            </div>
+
+            <div className="hidden items-center justify-center bg-zinc-300 px-2 py-8 dark:bg-zinc-800 md:flex lg:px-4">
+              <div className="flex w-full max-w-[1480px] items-center justify-center">
+                <BrowserFrame url="your-website.com/signin" className="w-full">
+                  <div className="flex min-h-[420px] items-center justify-center px-6 py-8">
+                    <div className="pointer-events-none relative flex w-full items-center justify-center" inert>
+                      <div className="absolute inset-0 z-10 bg-transparent" />
+                      <AuthPage type="sign-in" mockProject={authPreviewProject} />
+                    </div>
+                  </div>
+                </BrowserFrame>
+              </div>
+            </div>
+          </div>
+        </DesignCard>
+      </div>
+    );
+  }
 
-type ProjectFormValues = yup.InferType<typeof projectFormSchema>
+  if (props.status === "domain_setup") {
+    return (
+      <div className="mx-auto w-full max-w-6xl space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="domain_setup"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <DesignCard
+          title="Domain Connector"
+          subtitle="Set trusted domains and optionally prepare managed email sending with a subdomain."
+          icon={GlobeIcon}
+          gradient="default"
+          glassmorphic
+          actions={
+            <DesignButton
+              className="rounded-xl"
+              loading={saving}
+              onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                const normalizedTrustedDomain = normalizeTrustedDomain(trustedDomain);
+                if (normalizedTrustedDomain.length > 0) {
+                  if (!domainHandlerPath.startsWith("/")) {
+                    throw new Error("Handler path must start with /.");
+                  }
+
+                  const configUpdated = await updateConfig({
+                    adminApp: props.project.app,
+                    configUpdate: {
+                      [`domains.trustedDomains.${generateUuid()}`]: {
+                        baseUrl: normalizedTrustedDomain,
+                        handlerPath: domainHandlerPath,
+                      },
+                    },
+                    pushable: true,
+                  });
+                  if (!configUpdated) {
+                    return;
+                  }
+                }
+
+                await props.setStatus("email_theme_setup");
+              }))}
+            >
+              Add later
+            </DesignButton>
+          }
+        >
+          <div className="space-y-5">
+            <div className="space-y-3">
+              <Label htmlFor="trusted-domain">Trusted domain</Label>
+              <DesignInput
+                id="trusted-domain"
+                value={trustedDomain}
+                onChange={(event) => setTrustedDomain(event.target.value)}
+                placeholder="https://app.example.com"
+              />
+              <Label htmlFor="domain-handler-path">Handler path</Label>
+              <DesignInput
+                id="domain-handler-path"
+                value={domainHandlerPath}
+                onChange={(event) => setDomainHandlerPath(event.target.value)}
+                placeholder="/handler"
+              />
+            </div>
+
+            <div className="rounded-xl border border-border p-4 space-y-3">
+              <Typography type="h4">Managed Email Domain (Optional)</Typography>
+              <Label htmlFor="managed-subdomain">Subdomain</Label>
+              <DesignInput
+                id="managed-subdomain"
+                value={managedSubdomain}
+                onChange={(event) => setManagedSubdomain(event.target.value)}
+                placeholder="mail.example.com"
+              />
+              <Label htmlFor="managed-sender-local-part">Sender local-part</Label>
+              <DesignInput
+                id="managed-sender-local-part"
+                value={managedSenderLocalPart}
+                onChange={(event) => setManagedSenderLocalPart(event.target.value)}
+                placeholder="noreply"
+              />
+
+              <div className="flex justify-start">
+                <DesignButton
+                  className="rounded-xl"
+                  variant="outline"
+                  loading={saving}
+                  onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                    if (managedSubdomain.trim().length === 0 || managedSenderLocalPart.trim().length === 0) {
+                      throw new Error("Enter both subdomain and sender local-part to configure managed email.");
+                    }
+
+                    const setupResult = await props.project.app.setupManagedEmailProvider({
+                      subdomain: managedSubdomain.trim(),
+                      senderLocalPart: managedSenderLocalPart.trim(),
+                    });
+                    setManagedDomainSetupStatus(`Managed email setup created. Status: ${setupResult.status}.`);
+                  }))}
+                >
+                  Configure Managed Email
+                </DesignButton>
+              </div>
+            </div>
+
+            {managedDomainSetupStatus && (
+              <DesignAlert
+                variant="success"
+                title="Managed email setup"
+                description={managedDomainSetupStatus}
+                glassmorphic
+              />
+            )}
+          </div>
+        </DesignCard>
+      </div>
+    );
+  }
+
+  if (props.status === "email_theme_setup") {
+    return (
+      <div className="mx-auto w-full max-w-7xl space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="email_theme_setup"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <DesignCard
+          className="w-full"
+          title="Select Email Theme"
+          subtitle="Choose from existing themes. You can continue without changing the default theme."
+          icon={CheckCircleIcon}
+          gradient="purple"
+          glassmorphic
+          contentClassName="flex min-h-[520px] flex-col gap-6"
+          actions={
+            <DesignButton
+              className="rounded-xl"
+              loading={saving}
+              onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                if (selectedEmailThemeId !== completeConfig.emails.selectedThemeId) {
+                  const configUpdated = await updateConfig({
+                    adminApp: props.project.app,
+                    configUpdate: {
+                      "emails.selectedThemeId": selectedEmailThemeId,
+                    },
+                    pushable: true,
+                  });
+                  if (!configUpdated) {
+                    return;
+                  }
+                }
+
+                if (includePayments) {
+                  await props.setStatus("payments_setup");
+                } else {
+                  await props.setStatus("completed");
+                    props.onComplete();
+                }
+              }))}
+            >
+              {includePayments ? "Next" : "Finish"}
+            </DesignButton>
+          }
+        >
+          <div className="flex-1 space-y-4">
+            {emailThemes.length === 0 && (
+              <DesignAlert
+                variant="warning"
+                title="No themes found"
+                description="Theme selection is temporarily unavailable. You can still continue."
+                glassmorphic
+              />
+            )}
+
+            <div className="grid gap-4 lg:grid-cols-3">
+              {emailThemes.map((theme) => {
+                const isSelected = selectedEmailThemeId === theme.id;
+                return (
+                  <button
+                    key={theme.id}
+                    type="button"
+                    onClick={() => setSelectedEmailThemeId(theme.id)}
+                    className={cn(
+                      "group relative overflow-hidden rounded-3xl border text-left transition-[border-color,background-color,box-shadow] duration-150 hover:transition-none",
+                      isSelected
+                        ? "border-blue-500/45 bg-blue-500/[0.06] shadow-[0_8px_24px_rgba(59,130,246,0.08)]"
+                        : "border-border bg-background/70 hover:border-foreground/20 hover:bg-foreground/[0.03]",
+                    )}
+                  >
+                    {isSelected && (
+                      <div className="absolute right-4 top-4 z-10 flex h-7 w-7 items-center justify-center rounded-full bg-green-500 text-white shadow-sm">
+                        <CheckCircleIcon className="h-4 w-4" weight="fill" />
+                      </div>
+                    )}
+                    <div className="aspect-[4/3] overflow-hidden border-b border-border bg-background">
+                      <div style={{ transform: "scale(0.5)", transformOrigin: "top left", width: "200%", height: "200%" }}>
+                        <OnboardingEmailThemePreview adminApp={props.project.app} themeId={theme.id} />
+                      </div>
+                    </div>
+                    <div className="flex items-center justify-between gap-3 p-4">
+                      <Typography type="h4">{theme.displayName}</Typography>
+                    </div>
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        </DesignCard>
+      </div>
+    );
+  }
+
+  if (props.status === "payments_setup") {
+    return (
+      <div className="mx-auto w-full max-w-6xl space-y-5 px-4 py-6 md:px-8">
+        <OnboardingTimeline
+          steps={timelineSteps}
+          currentStep="payments_setup"
+          onStepClick={handleTimelineStepClick}
+          disabled={saving}
+        />
+        <DesignCard
+          className="w-full"
+          title="Payments Onboarding"
+          subtitle="Use the same Stripe setup flow as the Payments app. Payments is currently supported in the United States only."
+          icon={StripeLogoIcon}
+          gradient="orange"
+          glassmorphic
+          contentClassName="flex min-h-[420px] flex-col gap-6"
+          actions={
+            <div className="flex flex-wrap items-center justify-end gap-2">
+              {selectedPaymentsCountry !== "US" && (
+                <DesignButton
+                  className="rounded-xl"
+                  variant="outline"
+                  onClick={() => setSelectedPaymentsCountry("US")}
+                >
+                  <ArrowLeftIcon className="mr-2 h-4 w-4" />
+                  Back
+                </DesignButton>
+              )}
+              <DesignButton
+                className="rounded-xl"
+                variant="outline"
+                loading={saving}
+                onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                  await props.project.app.setupPayments();
+                  await finalizeOnboarding();
+                }))}
+              >
+                Do This Later
+              </DesignButton>
+              {selectedPaymentsCountry === "US" && (
+                <DesignButton
+                  className="rounded-xl"
+                  loading={saving}
+                  onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
+                    const setup = await props.project.app.setupPayments();
+                    window.location.href = setup.url;
+                  }))}
+                >
+                  Continue Onboarding
+                </DesignButton>
+              )}
+            </div>
+          }
+        >
+          <div className="flex-1 space-y-6">
+            <div className="mx-auto max-w-sm">
+              <div className="rounded-3xl border border-border bg-background/70 p-8 text-center">
+                <div className="mx-auto mb-4 grid h-12 w-12 place-items-center rounded-full bg-primary/10 text-primary">
+                  <WalletIcon className="h-6 w-6" />
+                </div>
+                <Typography type="h3" className="mb-4">Setup Payments</Typography>
+                <Typography type="p" variant="secondary" className="mt-2">
+                  Let your users pay seamlessly and securely.
+                </Typography>
+                <ul className="mt-6 grid gap-3 text-left text-sm text-muted-foreground">
+                  <li className="flex items-center gap-2">
+                    <WebhooksLogoIcon className="h-4 w-4 text-primary" />
+                    <span>No webhooks or syncing</span>
+                  </li>
+                  <li className="flex items-center gap-2">
+                    <ArrowsClockwiseIcon className="h-4 w-4 text-primary" />
+                    <span>One-time and recurring</span>
+                  </li>
+                  <li className="flex items-center gap-2">
+                    <ChartBarIcon className="h-4 w-4 text-primary" />
+                    <span>Usage-based billing</span>
+                  </li>
+                </ul>
+                <div className="mt-8 space-y-3 text-left">
+                  <Label htmlFor="payments-country">Country of residence</Label>
+                  <Select value={selectedPaymentsCountry} onValueChange={setSelectedPaymentsCountry}>
+                    <SelectTrigger id="payments-country" className="w-full">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {PAYMENT_COUNTRY_OPTIONS.map((country) => (
+                        <SelectItem key={country.value} value={country.value}>
+                          {country.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
+                <div className="mt-4 flex items-center justify-center gap-2 text-xs text-muted-foreground">
+                  <ShieldIcon className="h-3.5 w-3.5" />
+                  <span>Powered by Stripe</span>
+                </div>
+              </div>
+            </div>
+
+            {selectedPaymentsCountry === "US" ? (
+              <DesignAlert
+                variant="info"
+                title="Payments is available in your country!"
+                description="You will be redirected to Stripe, our partner for payment processing, to connect your bank account. Or, you can do this later and stay in test transactions for now."
+                glassmorphic
+              />
+            ) : (
+              <DesignAlert
+                variant="warning"
+                title="Payments is not available in your country yet"
+                description="Stack Auth Payments is currently only available in the United States."
+                glassmorphic
+              />
+            )}
+          </div>
+        </DesignCard>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto w-full max-w-6xl px-4 py-6 md:px-8">
+      <Alert>
+        <WarningCircleIcon className="h-4 w-4" />
+        <AlertTitle>Unknown onboarding step</AlertTitle>
+        <AlertDescription>
+          This project has an unknown onboarding state. Open the project directly and continue from the dashboard.
+        </AlertDescription>
+      </Alert>
+      <div className="mt-4 flex justify-end">
+        <Button onClick={() => router.push(`/projects/${encodeURIComponent(props.project.id)}`)}>Open Project</Button>
+      </div>
+    </div>
+  );
+}
 
 export default function PageClient() {
+  const app = useStackApp();
+  const appInternals = useMemo(() => getStackAppInternals(app), [app]);
   const user = useUser({ or: 'redirect', projectIdMustMatch: "internal" });
-  const isLocalEmulator = getPublicEnvVar("NEXT_PUBLIC_STACK_IS_LOCAL_EMULATOR") === "true";
-  const [loading, setLoading] = useState(false);
+  const teams = user.useTeams();
+  const projects = user.useOwnedProjects();
   const router = useRouter();
   const searchParams = useSearchParams();
-  const displayName = searchParams.get("display_name");
+  const isLocalEmulator = getPublicEnvVar("NEXT_PUBLIC_STACK_IS_LOCAL_EMULATOR") === "true";
 
-  const defaultValues: Partial<ProjectFormValues> = {
-    displayName: displayName || "",
-    signInMethods: ["credential", "google", "github"],
-    teamId: user.selectedTeam?.id,
-  };
+  const selectedProjectId = searchParams.get("project_id");
+  const displayNameFromSearch = searchParams.get("display_name");
+  const redirectToNeonConfirmWith = searchParams.get("redirect_to_neon_confirm_with");
+  const redirectToConfirmWith = searchParams.get("redirect_to_confirm_with");
+  const mode = searchParams.get("mode");
 
-  const form = useForm<ProjectFormValues>({
-    resolver: yupResolver<ProjectFormValues>(projectFormSchema),
-    defaultValues,
-    mode: "onChange",
-  });
+  const [projectStatuses, setProjectStatuses] = useState<Map<string, ProjectOnboardingStatus>>(new Map());
+  const [loadingStatuses, setLoadingStatuses] = useState(true);
+  const [projectName, setProjectName] = useState(displayNameFromSearch ?? "");
+  const [selectedTeamId, setSelectedTeamId] = useState<string | null>(null);
+  const [creatingTeam, setCreatingTeam] = useState(false);
+  const [creatingProject, setCreatingProject] = useState(false);
+  const [isCreateProjectOpen, setIsCreateProjectOpen] = useState(true);
+  const [isCreateTeamOpen, setIsCreateTeamOpen] = useState(false);
+  const [newTeamName, setNewTeamName] = useState("");
 
-  const mockProject = {
-    id: "id",
-    config: {
-      signUpEnabled: true,
-      credentialEnabled: form.watch("signInMethods").includes("credential"),
-      magicLinkEnabled: form.watch("signInMethods").includes("magicLink"),
-      passkeyEnabled: form.watch("signInMethods").includes("passkey"),
-      oauthProviders: form.watch('signInMethods').filter((method) => ["google", "github", "microsoft"].includes(method)).map(provider => ({ id: provider, type: 'shared' })),
+  useEffect(() => {
+    if (selectedTeamId != null) {
+      return;
     }
-  };
 
-  const redirectToNeonConfirmWith = searchParams.get("redirect_to_neon_confirm_with");
+    if (user.selectedTeam != null) {
+      setSelectedTeamId(user.selectedTeam.id);
+      return;
+    }
+
+    const firstTeam = teams.at(0);
+    if (firstTeam !== undefined) {
+      setSelectedTeamId(firstTeam.id);
+    }
+  }, [selectedTeamId, teams, user.selectedTeam]);
+
+  const updateSearchParams = useCallback((updates: Record<string, string | null>) => {
+    const params = new URLSearchParams(searchParams.toString());
+
+    for (const [key, value] of Object.entries(updates)) {
+      if (value == null || value.length === 0) {
+        params.delete(key);
+      } else {
+        params.set(key, value);
+      }
+    }
+
+    const query = params.toString();
+    router.replace(query.length > 0 ? `/new-project?${query}` : "/new-project");
+  }, [router, searchParams]);
+
+  useEffect(() => {
+    let cancelled = false;
+    runAsynchronouslyWithAlert(async () => {
+      setLoadingStatuses(true);
+      try {
+        const response = await appInternals.sendRequest("/internal/projects", {}, "client");
+        if (!response.ok) {
+          throw new Error(`Failed to load projects: ${response.status} ${await response.text()}`);
+        }
+
+        const body = await response.json();
+        if (body == null || typeof body !== "object" || !("items" in body) || !Array.isArray(body.items)) {
+          throw new Error("Project list endpoint returned an invalid response.");
+        }
+
+        const statusMap = new Map<string, ProjectOnboardingStatus>();
+        for (const item of body.items) {
+          if (item == null || typeof item !== "object" || !("id" in item) || typeof item.id !== "string") {
+            continue;
+          }
+
+          const onboardingStatus = "onboarding_status" in item ? item.onboarding_status : undefined;
+          statusMap.set(item.id, isProjectOnboardingStatus(onboardingStatus) ? onboardingStatus : "completed");
+        }
+
+        if (!cancelled) {
+          setProjectStatuses(statusMap);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoadingStatuses(false);
+        }
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [appInternals, projects.length]);
+
+  const selectedProject = useMemo(() => {
+    if (selectedProjectId == null) {
+      return null;
+    }
+    return projects.find((project) => project.id === selectedProjectId) ?? null;
+  }, [projects, selectedProjectId]);
+
+  const selectedProjectStatus = useMemo(() => {
+    if (selectedProjectId == null) {
+      return null;
+    }
+    return projectStatuses.get(selectedProjectId) ?? "completed";
+  }, [projectStatuses, selectedProjectId]);
+
+  useEffect(() => {
+    if (selectedProject == null || loadingStatuses || selectedProjectStatus !== "completed") {
+      return;
+    }
+
+    router.replace(`/projects/${encodeURIComponent(selectedProject.id)}`);
+  }, [loadingStatuses, router, selectedProject, selectedProjectStatus]);
+
+  const setSelectedProjectStatus = async (project: AdminOwnedProject, status: ProjectOnboardingStatus) => {
+    const projectInternals = getStackAppInternals(project.app);
+
+    const response = await projectInternals.sendRequest(
+      "/internal/projects/current",
+      {
+        method: "PATCH",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ onboarding_status: status }),
+      },
+      "admin",
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to update onboarding status: ${response.status} ${await response.text()}`);
+    }
+
+    setProjectStatuses((previous) => {
+      const next = new Map(previous);
+      next.set(project.id, status);
+      return next;
+    });
+
+    await appInternals.refreshOwnedProjects();
+  };
 
   if (isLocalEmulator) {
     return (
@@ -76,116 +1524,223 @@ export default function PageClient() {
     );
   }
 
-  const onSubmit = async (values: ProjectFormValues, e?: React.BaseSyntheticEvent) => {
-    e?.preventDefault();
-    setLoading(true);
-    let newProject;
-    try {
-      newProject = await user.createProject({
-        displayName: values.displayName,
-        teamId: values.teamId,
-        config: {
-          credentialEnabled: values.signInMethods.includes("credential"),
-          magicLinkEnabled: values.signInMethods.includes("magicLink"),
-          passkeyEnabled: values.signInMethods.includes("passkey"),
-          oauthProviders: (["google", "facebook", "github", "microsoft"] as const).map(provider => ({
-            id: provider,
-            enabled: values.signInMethods.includes(provider),
-            type: 'shared'
-          } as const)).filter(({ enabled }) => enabled),
-        }
-      });
-
-      if (redirectToNeonConfirmWith) {
-        const confirmSearchParams = new URLSearchParams(redirectToNeonConfirmWith);
-        confirmSearchParams.set("default_selected_project_id", newProject.id);
-        router.push('/integrations/neon/confirm?' + confirmSearchParams.toString());
-      } else {
-        router.push('/projects/' + encodeURIComponent(newProject.id));
-      }
-      await wait(2000);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-
-  return (
-    <div className="w-full flex-grow flex items-center justify-center">
-      <div className="w-full md:w-1/2 p-4">
-        <div className='max-w-xs m-auto'>
-          <div className="flex justify-center mb-4">
-            <Typography type='h2'>Create a new project</Typography>
-          </div>
+  if (loadingStatuses && selectedProjectId != null) {
+    return (
+      <div className="flex w-full flex-grow items-center justify-center">
+        <Spinner size={24} />
+      </div>
+    );
+  }
 
-          <Form {...form}>
-            <form onSubmit={e => runAsynchronouslyWithAlert(form.handleSubmit(onSubmit)(e))} className="space-y-4">
-
-              <InputField required control={form.control} name="displayName" label="Display Name" placeholder="My Project" />
-
-              <FormField
-                control={form.control}
-                name="teamId"
-                render={({ field }) => (
-                  <FormItem>
-                    <label className="flex flex-col gap-2">
-                      <FieldLabel required={true}>Team</FieldLabel>
-                      <FormControl>
-                        <TeamSwitcher
-                          triggerClassName="max-w-full"
-                          teamId={field.value}
-                          onChange={async (team) => {
-                            field.onChange(team.id);
-                          }}
-                        />
-                      </FormControl>
-                      <FormMessage />
-                    </label>
-                  </FormItem>
-                )}
-              />
+  if (selectedProjectId != null && selectedProject == null) {
+    return (
+      <div className="w-full flex-grow flex items-center justify-center p-4">
+        <Card className="w-full max-w-xl">
+          <CardHeader>
+            <CardTitle>Project not found</CardTitle>
+            <CardDescription>We could not find the project in your account.</CardDescription>
+          </CardHeader>
+          <CardContent className="flex justify-end">
+            <Button variant="outline" onClick={() => router.push("/projects")}>Go to Projects</Button>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
 
-              <SwitchListField
-                control={form.control}
-                name="signInMethods"
-                label="Sign-In Methods"
-                options={[
-                  { value: "credential", label: "Email password" },
-                  { value: "magicLink", label: "Magic link/OTP" },
-                  { value: "passkey", label: "Passkey" },
-                  { value: "google", label: "Google" },
-                  { value: "github", label: "GitHub" },
-                  { value: "microsoft", label: "Microsoft" },
-                ]}
-                info="More sign-in methods are available on the dashboard later."
-              />
+  if (selectedProject != null && !loadingStatuses && selectedProjectStatus === "completed") {
+    return (
+      <div className="flex w-full flex-grow items-center justify-center">
+        <Spinner size={24} />
+      </div>
+    );
+  }
 
-              <div className="flex justify-center">
-                <Button loading={loading} type="submit">
-                  {redirectToNeonConfirmWith ? "Create & Connect Project" : "Create Project"}
-                </Button>
+  if (selectedProject == null) {
+    return (
+      <div className="flex w-full flex-grow items-center justify-center">
+        <Dialog
+          open={isCreateProjectOpen}
+          onOpenChange={(open) => {
+            setIsCreateProjectOpen(open);
+            if (!open) {
+              router.push("/projects");
+            }
+          }}
+        >
+          <DialogContent
+            className="overflow-hidden border-0 bg-white/90 p-0 shadow-2xl backdrop-blur-xl ring-1 ring-black/[0.06] dark:bg-background/75 dark:ring-white/[0.08] sm:max-w-[720px] sm:rounded-3xl"
+            overlayProps={{ className: "bg-black/70 backdrop-blur-[2px]" }}
+            noCloseButton
+          >
+            <DialogHeader className="border-b border-black/[0.08] px-6 py-6 text-left dark:border-white/[0.08]">
+              <div className="flex items-center gap-3">
+                <div className="rounded-2xl bg-blue-500/10 p-2.5 text-blue-600 dark:bg-blue-500/15 dark:text-blue-400">
+                  <PlusCircleIcon className="h-5 w-5" />
+                </div>
+                <div className="space-y-1">
+                  <DialogTitle className="text-xl font-semibold tracking-tight">Create a new project</DialogTitle>
+                </div>
               </div>
-            </form>
-          </Form>
-        </div>
-      </div>
+              <DialogDescription>
+                Start by naming your project and choosing the team that will own it.
+              </DialogDescription>
+            </DialogHeader>
 
-      <div className="w-1/2 self-stretch py-4 px-4 lg:px-20 bg-zinc-300 dark:bg-zinc-800 hidden md:flex items-center">
-        <div className="w-full">
-          <BrowserFrame url="your-website.com/signin">
-            <div className="flex flex-col items-center justify-center min-h-[400px]">
-              <div className='w-full sm:max-w-xs m-auto scale-90 pointer-events-none' inert>
-                {/* a transparent cover that prevents the card from being clicked, even when pointer-events is overridden */}
-                <div className="absolute inset-0 bg-transparent z-10"></div>
-                <AuthPage
-                  type="sign-in"
-                  mockProject={mockProject}
+            <div className="space-y-5 px-6 py-6">
+              <div className="space-y-2">
+                <Label htmlFor="project-name">Project name</Label>
+                <DesignInput
+                  id="project-name"
+                  value={projectName}
+                  onChange={(event) => setProjectName(event.target.value)}
+                  placeholder="My Project"
                 />
               </div>
+
+              <div className="space-y-2">
+                <Label htmlFor="team-id">Team</Label>
+                <div className="grid gap-2 sm:grid-cols-[minmax(0,1fr)_auto]">
+                  <DesignSelectorDropdown
+                    value={selectedTeamId ?? ""}
+                    onValueChange={setSelectedTeamId}
+                    placeholder="Select a team"
+                    size="md"
+                    className="w-full"
+                    options={teams.map((team) => ({ value: team.id, label: team.displayName }))}
+                  />
+                  <DesignButton variant="outline" onClick={() => setIsCreateTeamOpen(true)} className="rounded-xl sm:min-w-[152px]">
+                    <PlusCircleIcon className="mr-2 h-4 w-4" />
+                    Create Team
+                  </DesignButton>
+                </div>
+              </div>
             </div>
-          </BrowserFrame>
-        </div>
+
+            <DialogFooter className="border-t border-black/[0.08] px-6 py-4 dark:border-white/[0.08] sm:justify-end sm:space-x-2">
+              <DesignButton variant="outline" className="rounded-xl" onClick={() => router.push("/projects")} disabled={creatingProject}>
+                Cancel
+              </DesignButton>
+              <DesignButton
+                className="rounded-xl"
+                loading={creatingProject}
+                onClick={() => runAsynchronouslyWithAlert(async () => {
+                  const trimmedProjectName = projectName.trim();
+                  if (trimmedProjectName.length === 0) {
+                    throw new Error("Project name is required.");
+                  }
+
+                  const firstTeam = teams.at(0);
+                  const teamId = selectedTeamId ?? user.selectedTeam?.id ?? firstTeam?.id;
+                  if (teamId === undefined) {
+                    throw new Error("Select a team before creating the project.");
+                  }
+
+                  setCreatingProject(true);
+                  try {
+                    const newProject = await user.createProject({
+                      displayName: trimmedProjectName,
+                      teamId,
+                    });
+
+                    await setSelectedProjectStatus(newProject, "config_choice");
+
+                    if (redirectToNeonConfirmWith != null) {
+                      const confirmSearchParams = new URLSearchParams(redirectToNeonConfirmWith);
+                      confirmSearchParams.set("default_selected_project_id", newProject.id);
+                      router.push(`/integrations/neon/confirm?${confirmSearchParams.toString()}`);
+                      await wait(2000);
+                      return;
+                    }
+
+                    if (redirectToConfirmWith != null) {
+                      const confirmSearchParams = new URLSearchParams(redirectToConfirmWith);
+                      confirmSearchParams.set("default_selected_project_id", newProject.id);
+                      router.push(`/integrations/custom/confirm?${confirmSearchParams.toString()}`);
+                      await wait(2000);
+                      return;
+                    }
+
+                    updateSearchParams({
+                      project_id: newProject.id,
+                      mode: null,
+                    });
+                  } finally {
+                    setCreatingProject(false);
+                  }
+                })}
+              >
+                Create Project
+              </DesignButton>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+
+        <Dialog open={isCreateTeamOpen} onOpenChange={setIsCreateTeamOpen}>
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Create Team</DialogTitle>
+              <DialogDescription>This team will be available immediately for project ownership.</DialogDescription>
+            </DialogHeader>
+
+            <div className="space-y-2">
+              <Label htmlFor="new-team-name">Team name</Label>
+              <DesignInput
+                id="new-team-name"
+                value={newTeamName}
+                onChange={(event) => setNewTeamName(event.target.value)}
+                placeholder="Acme Team"
+              />
+            </div>
+
+            <DialogFooter>
+              <DesignButton variant="outline" className="rounded-xl" onClick={() => setIsCreateTeamOpen(false)} disabled={creatingTeam}>
+                Cancel
+              </DesignButton>
+              <DesignButton
+                className="rounded-xl"
+                loading={creatingTeam}
+                onClick={() => runAsynchronouslyWithAlert(async () => {
+                  const trimmedTeamName = newTeamName.trim();
+                  if (trimmedTeamName.length === 0) {
+                    throw new Error("Team name is required.");
+                  }
+
+                  setCreatingTeam(true);
+                  try {
+                    const createdTeam = await user.createTeam({
+                      displayName: trimmedTeamName,
+                    });
+                    await user.setSelectedTeam(createdTeam.id);
+                    setSelectedTeamId(createdTeam.id);
+                    setNewTeamName("");
+                    setIsCreateTeamOpen(false);
+                  } finally {
+                    setCreatingTeam(false);
+                  }
+                })}
+              >
+                Create Team
+              </DesignButton>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
       </div>
+    );
+  }
+
+  return (
+    <div className="flex w-full flex-grow justify-center">
+      <ProjectOnboardingWizard
+        project={selectedProject}
+        status={selectedProjectStatus ?? "config_choice"}
+        mode={mode}
+        setMode={(nextMode) => updateSearchParams({ mode: nextMode })}
+        setStatus={(nextStatus) => setSelectedProjectStatus(selectedProject, nextStatus)}
+        onComplete={() => {
+          router.push(`/projects/${encodeURIComponent(selectedProject.id)}`);
+        }}
+      />
     </div>
   );
 }
diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx
index bba64dfb16..0e4d504159 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx
@@ -22,6 +22,18 @@ type StackAppInternals = {
   refreshOwnedProjects: () => Promise<void>,
 };
 
+const PROJECT_ONBOARDING_STATUSES = [
+  "config_choice",
+  "apps_selection",
+  "auth_setup",
+  "domain_setup",
+  "email_theme_setup",
+  "payments_setup",
+  "completed",
+] as const;
+
+type ProjectOnboardingStatus = (typeof PROJECT_ONBOARDING_STATUSES)[number];
+
 function isStackAppInternals(value: unknown): value is StackAppInternals {
   return (
     value != null &&
@@ -33,8 +45,26 @@ function isStackAppInternals(value: unknown): value is StackAppInternals {
   );
 }
 
+function getStackAppInternals(appValue: unknown): StackAppInternals {
+  if (appValue == null || typeof appValue !== "object") {
+    throw new Error("The Stack app instance is unavailable.");
+  }
+
+  const internals = Reflect.get(appValue, stackAppInternalsSymbol);
+  if (!isStackAppInternals(internals)) {
+    throw new Error("The Stack client app cannot send internal requests.");
+  }
+
+  return internals;
+}
+
+function isProjectOnboardingStatus(value: unknown): value is ProjectOnboardingStatus {
+  return typeof value === "string" && PROJECT_ONBOARDING_STATUSES.some((status) => status === value);
+}
+
 export default function PageClient() {
   const app = useStackApp();
+  const appInternals = useMemo(() => getStackAppInternals(app), [app]);
   const user = useUser({ or: 'redirect', projectIdMustMatch: "internal" });
   const rawProjects = user.useOwnedProjects();
   const teams = user.useTeams();
@@ -44,6 +74,8 @@ export default function PageClient() {
   const [openConfigFileDialog, setOpenConfigFileDialog] = useState(false);
   const [absoluteConfigFilePath, setAbsoluteConfigFilePath] = useState("");
   const [openingConfigFile, setOpeningConfigFile] = useState(false);
+  const [projectStatuses, setProjectStatuses] = useState<Map<string, ProjectOnboardingStatus>>(new Map());
+  const [loadingProjectStatuses, setLoadingProjectStatuses] = useState(true);
   const router = useRouter();
 
   useEffect(() => {
@@ -52,6 +84,46 @@ export default function PageClient() {
     }
   }, [isLocalEmulator, router, rawProjects]);
 
+  useEffect(() => {
+    let cancelled = false;
+    runAsynchronously(async () => {
+      setLoadingProjectStatuses(true);
+      try {
+        const response = await appInternals.sendRequest("/internal/projects", {}, "client");
+        if (!response.ok) {
+          throw new Error(`Failed to load projects: ${response.status} ${await response.text()}`);
+        }
+
+        const body = await response.json();
+        if (body == null || typeof body !== "object" || !("items" in body) || !Array.isArray(body.items)) {
+          throw new Error("Project list endpoint returned an invalid response.");
+        }
+
+        const statusMap = new Map<string, ProjectOnboardingStatus>();
+        for (const item of body.items) {
+          if (item == null || typeof item !== "object" || !("id" in item) || typeof item.id !== "string") {
+            continue;
+          }
+
+          const onboardingStatus = "onboarding_status" in item ? item.onboarding_status : undefined;
+          statusMap.set(item.id, isProjectOnboardingStatus(onboardingStatus) ? onboardingStatus : "completed");
+        }
+
+        if (!cancelled) {
+          setProjectStatuses(statusMap);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoadingProjectStatuses(false);
+        }
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [appInternals, rawProjects.length]);
+
   const handleOpenConfigFile = async () => {
     const trimmedPath = absoluteConfigFilePath.trim();
     if (trimmedPath.length === 0) {
@@ -67,11 +139,6 @@ export default function PageClient() {
 
     setOpeningConfigFile(true);
     try {
-      const appInternals = Reflect.get(app, stackAppInternalsSymbol);
-      if (!isStackAppInternals(appInternals)) {
-        throw new Error("The Stack client app cannot send internal requests.");
-      }
-
       const response = await appInternals.sendRequest(
         "/internal/local-emulator/project",
         {
@@ -240,9 +307,21 @@ export default function PageClient() {
               )}
             </div>
             <div className="grid gap-4 grid-cols-1 sm:grid-cols-2 md:grid-cols-3 xl:grid-cols-4">
-              {projects.map((project) => (
-                <ProjectCard key={project.id} project={project} />
-              ))}
+              {projects.map((project) => {
+                const onboardingStatus = projectStatuses.get(project.id) ?? "completed";
+                const projectHref = onboardingStatus === "completed"
+                  ? `/projects/${encodeURIComponent(project.id)}`
+                  : `/new-project?project_id=${encodeURIComponent(project.id)}`;
+
+                return (
+                  <ProjectCard
+                    key={project.id}
+                    project={project}
+                    href={projectHref}
+                    showIncompleteBadge={!loadingProjectStatuses && onboardingStatus !== "completed"}
+                  />
+                );
+              })}
             </div>
           </div>
         );
diff --git a/apps/dashboard/src/components/project-card.tsx b/apps/dashboard/src/components/project-card.tsx
index 4d46a5e040..22619e0816 100644
--- a/apps/dashboard/src/components/project-card.tsx
+++ b/apps/dashboard/src/components/project-card.tsx
@@ -1,26 +1,38 @@
 'use client';
 import { Link } from "@/components/link";
+import { DesignBadge } from "@/components/design-components/badge";
+import { DesignCard } from "@/components/design-components/card";
 import { useFromNow } from '@/hooks/use-from-now';
 import { AdminProject } from '@stackframe/stack';
 import { urlString } from "@stackframe/stack-shared/dist/utils/urls";
-import { Card, CardDescription, CardFooter, CardHeader, CardTitle, Typography } from '@/components/ui';
+import { FolderOpenIcon } from "@phosphor-icons/react";
+import { Typography } from '@/components/ui';
 
-export function ProjectCard({ project }: { project: AdminProject }) {
-  const createdAt = useFromNow(project.createdAt);
+export function ProjectCard(props: {
+  project: AdminProject,
+  href?: string,
+  showIncompleteBadge?: boolean,
+}) {
+  const createdAt = useFromNow(props.project.createdAt);
+  const href = props.href ?? urlString`/projects/${props.project.id}`;
 
   return (
-    <Link href={urlString`/projects/${project.id}`}>
-      <Card className='flex flex-col justify-between h-full'>
-        <CardHeader>
-          <CardTitle className="normal-case truncate">{project.displayName}</CardTitle>
-          <CardDescription>{project.description}</CardDescription>
-        </CardHeader>
-        <CardFooter className="flex justify-end mt-2">
+    <Link href={href}>
+      <DesignCard
+        title={props.project.displayName}
+        icon={FolderOpenIcon}
+        subtitle={props.project.description || "No description yet"}
+        className="h-full"
+        gradient={props.showIncompleteBadge ? "orange" : "default"}
+        glassmorphic
+        actions={props.showIncompleteBadge ? <DesignBadge label="Setup incomplete" color="orange" size="sm" /> : null}
+      >
+        <div className="flex justify-end">
           <Typography type='label' variant='secondary'>
             {createdAt}
           </Typography>
-        </CardFooter>
-      </Card>
+        </div>
+      </DesignCard>
     </Link>
   );
 }
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts
index 40bac3524c..cd1272d389 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts
@@ -100,6 +100,7 @@ it("creates a new project", async ({ expect }) => {
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -156,6 +157,7 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -214,6 +216,7 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -263,6 +266,7 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -326,6 +330,7 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -391,6 +396,7 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -439,6 +445,7 @@ it("lists the current projects after creating a new project", async ({ expect })
             "logo_full_url": null,
             "logo_url": null,
             "owner_team_id": "<stripped UUID>",
+            "onboarding_status": "completed",
           },
         ],
       },
@@ -493,6 +500,7 @@ it("verifies email_theme update persists", async ({ expect }) => {
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -536,6 +544,7 @@ it("verifies email_theme update persists", async ({ expect }) => {
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -589,6 +598,7 @@ it("updates trusted domains without modifying allow_localhost", async ({ expect
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -645,6 +655,7 @@ it("updates trusted domains without modifying allow_localhost", async ({ expect
         "logo_full_url": null,
         "logo_url": null,
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -718,6 +729,7 @@ it("lets user update logo_url to a valid image", async ({ expect }) => {
         "logo_full_url": null,
         "logo_url": "http://localhost:<$NEXT_PUBLIC_STACK_PORT_PREFIX>21/stack-storage/project-logos/<stripped UUID>.png",
         "owner_team_id": "<stripped UUID>",
+        "onboarding_status": "completed",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
diff --git a/claude/CLAUDE-KNOWLEDGE.md b/claude/CLAUDE-KNOWLEDGE.md
index 970c8dd4ea..819ef45ce9 100644
--- a/claude/CLAUDE-KNOWLEDGE.md
+++ b/claude/CLAUDE-KNOWLEDGE.md
@@ -78,3 +78,15 @@ Q: What is the reliable way to lint a single dashboard file in this monorepo?
 A: Run lint from `apps/dashboard` directly (for example `pnpm lint -- "src/app/(main)/(protected)/projects/[projectId]/(overview)/line-chart.tsx"`), because running root `pnpm lint -- <file>` fans out through Turbo packages where that path does not exist.
 Q: How should unsubscribe-link e2e tests avoid breakage from email theme/layout changes?
 A: In `apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts`, avoid snapshotting the entire rendered HTML for transactional emails; assert stable behavior instead (email content present and `/api/v1/emails/unsubscribe-link` absent) so cosmetic wrapper/style changes do not fail the test.
+
+Q: How should dashboard pages update project config values?
+A: Do not call `project.updateConfig(...)` directly from dashboard pages; lint enforces using `useUpdateConfig()` from `apps/dashboard/src/lib/config-update.tsx` so pushable-config confirmation flows are handled consistently.
+
+Q: How can the dashboard find resumable onboarding state without SDK type changes?
+A: Query `/internal/projects` via `stackAppInternalsSymbol` and read each project's `onboarding_status`; this avoids relying on `AdminOwnedProject` fields that may lag until generated package copies are rebuilt.
+
+Q: How should the new-project onboarding page avoid React's "Cannot update a component while rendering a different component" router error?
+A: In `apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx`, never call `router.replace(...)` during render when an onboarding project is already completed; move that redirect into a `useEffect` and render a plain spinner while the redirect is in progress.
+
+Q: What is the expected lightweight loading state when reopening an in-progress onboarding project?
+A: On `apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx`, the "loading onboarding" state should be just a centered `Spinner` with no card chrome or explanatory copy.
diff --git a/packages/stack-shared/src/interface/crud/projects.ts b/packages/stack-shared/src/interface/crud/projects.ts
index d7238bf747..02bb1b68c2 100644
--- a/packages/stack-shared/src/interface/crud/projects.ts
+++ b/packages/stack-shared/src/interface/crud/projects.ts
@@ -73,6 +73,7 @@ export const projectsCrudAdminReadSchema = yupObject({
   created_at_millis: schemaFields.projectCreatedAtMillisSchema.defined(),
   is_production_mode: schemaFields.projectIsProductionModeSchema.defined(),
   owner_team_id: schemaFields.yupString().nullable().defined(),
+  onboarding_status: schemaFields.projectOnboardingStatusSchema.defined(),
   /** @deprecated */
   config: yupObject({
     allow_localhost: schemaFields.projectAllowLocalhostSchema.defined(),
@@ -124,6 +125,7 @@ export const projectsCrudAdminUpdateSchema = yupObject({
   logo_dark_mode_url: schemaFields.projectLogoDarkModeUrlSchema.nullable().optional(),
   logo_full_dark_mode_url: schemaFields.projectLogoFullDarkModeUrlSchema.nullable().optional(),
   is_production_mode: schemaFields.projectIsProductionModeSchema.optional(),
+  onboarding_status: schemaFields.projectOnboardingStatusSchema.optional(),
   /** @deprecated */
   config: yupObject({
     sign_up_enabled: schemaFields.projectSignUpEnabledSchema.optional(),
diff --git a/packages/stack-shared/src/schema-fields.ts b/packages/stack-shared/src/schema-fields.ts
index e1da1c5e75..e54d115311 100644
--- a/packages/stack-shared/src/schema-fields.ts
+++ b/packages/stack-shared/src/schema-fields.ts
@@ -546,6 +546,22 @@ export const projectLogoFullDarkModeUrlSchema = urlSchema.max(MAX_IMAGE_SIZE_BAS
 export const projectDescriptionSchema = yupString().nullable().meta({ openapiField: { description: 'A human readable description of the project', exampleValue: 'A music streaming service' } });
 export const projectCreatedAtMillisSchema = yupNumber().meta({ openapiField: { description: _createdAtMillisDescription('project'), exampleValue: 1630000000000 } });
 export const projectIsProductionModeSchema = yupBoolean().meta({ openapiField: { description: 'Whether the project is in production mode', exampleValue: true } });
+export const projectOnboardingStatusValues = [
+  "config_choice",
+  "apps_selection",
+  "auth_setup",
+  "domain_setup",
+  "email_theme_setup",
+  "payments_setup",
+  "completed",
+] as const;
+export type ProjectOnboardingStatus = typeof projectOnboardingStatusValues[number];
+export const projectOnboardingStatusSchema = yupString().oneOf(projectOnboardingStatusValues).meta({
+  openapiField: {
+    description: "The current dashboard onboarding stage for this project.",
+    exampleValue: "config_choice",
+  },
+});
 // Project config
 export const projectConfigIdSchema = yupString().meta({ openapiField: { description: _idDescription('project config'), exampleValue: 'd09201f0-54f5-40bd-89ff-6d1815ddad24' } });
 export const projectAllowLocalhostSchema = yupBoolean().meta({ openapiField: { description: 'Whether localhost is allowed as a domain for this project. Should only be allowed in development mode', exampleValue: true } });
diff --git a/packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts b/packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts
index e939e0897f..e6c4146acb 100644
--- a/packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts
+++ b/packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts
@@ -175,6 +175,7 @@ export class _StackAdminAppImplIncomplete<HasTokenStore extends boolean, Project
       createdAt: new Date(data.created_at_millis),
       isProductionMode: data.is_production_mode,
       ownerTeamId: data.owner_team_id,
+      onboardingStatus: data.onboarding_status,
       logoUrl: data.logo_url,
       logoFullUrl: data.logo_full_url,
       logoDarkModeUrl: data.logo_dark_mode_url,
diff --git a/packages/template/src/lib/stack-app/projects/index.ts b/packages/template/src/lib/stack-app/projects/index.ts
index ca0ae2a3ab..1888adf17e 100644
--- a/packages/template/src/lib/stack-app/projects/index.ts
+++ b/packages/template/src/lib/stack-app/projects/index.ts
@@ -1,5 +1,6 @@
 import { ProductionModeError } from "@stackframe/stack-shared/dist/helpers/production-mode";
 import { AdminUserProjectsCrud, ProjectsCrud } from "@stackframe/stack-shared/dist/interface/crud/projects";
+import { ProjectOnboardingStatus } from "@stackframe/stack-shared/dist/schema-fields";
 
 import { CompleteConfig, EnvironmentConfigNormalizedOverride, EnvironmentConfigOverrideOverride } from "@stackframe/stack-shared/dist/config/schema";
 import { StackAdminApp } from "../apps/interfaces/admin-app";
@@ -35,6 +36,7 @@ export type AdminProject = {
   readonly createdAt: Date,
   readonly isProductionMode: boolean,
   readonly ownerTeamId: string | null,
+  readonly onboardingStatus: ProjectOnboardingStatus,
   readonly logoUrl: string | null | undefined,
   readonly logoFullUrl: string | null | undefined,
   readonly logoDarkModeUrl: string | null | undefined,
@@ -143,6 +145,7 @@ export type AdminProjectUpdateOptions = {
   displayName?: string,
   description?: string,
   isProductionMode?: boolean,
+  onboardingStatus?: ProjectOnboardingStatus,
   /**
    * Updates `project.requirePublishableClientKey` in the project-level config override.
    */
@@ -158,6 +161,7 @@ export function adminProjectUpdateOptionsToCrud(options: AdminProjectUpdateOptio
     display_name: options.displayName,
     description: options.description,
     is_production_mode: options.isProductionMode,
+    onboarding_status: options.onboardingStatus,
     logo_url: options.logoUrl,
     logo_full_url: options.logoFullUrl,
     logo_dark_mode_url: options.logoDarkModeUrl,

From 6657a2f40d759f91939f736a526e8dd7e97dc49a Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Thu, 12 Mar 2026 22:17:40 -0700
Subject: [PATCH 2/7] Refactor Project Onboarding Wizard: Remove domain setup
 step and update status transitions

- Removed the "Domains" step from the onboarding timeline.
- Enhanced error handling for missing base URL in trusted domains.
- Updated status transitions to skip directly from "domain_setup" to "email_theme_setup".
- Refactored UI components for better readability and maintainability.
---
 .../new-project/page-client.tsx               | 145 ++++--------------
 1 file changed, 26 insertions(+), 119 deletions(-)

diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
index 4b1dd8841b..e44de60232 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
@@ -173,7 +173,6 @@ function buildTimeline(includePayments: boolean): TimelineStep[] {
     { id: "config_choice", label: "Config" },
     { id: "apps_selection", label: "Apps" },
     { id: "auth_setup", label: "Auth" },
-    { id: "domain_setup", label: "Domains" },
     { id: "email_theme_setup", label: "Email Theme" },
   ];
 
@@ -544,8 +543,12 @@ function ProjectOnboardingWizard(props: {
       .map((entry) => ({ baseUrl: entry.baseUrl, handlerPath: entry.handlerPath }));
 
     if (trustedDomains[0]) {
-      setTrustedDomain(trustedDomains[0].baseUrl ?? "");
-      setDomainHandlerPath(trustedDomains[0].handlerPath ?? "/handler");
+      const trustedDomainEntry = trustedDomains[0];
+      if (trustedDomainEntry.baseUrl == null) {
+        throw new Error("Invariant violated: trusted domain entry is missing a baseUrl.");
+      }
+      setTrustedDomain(trustedDomainEntry.baseUrl);
+      setDomainHandlerPath(trustedDomainEntry.handlerPath);
     } else {
       setTrustedDomain("");
       setDomainHandlerPath("/handler");
@@ -579,6 +582,16 @@ function ProjectOnboardingWizard(props: {
     });
   }, [currentTimelineIndex, setMode, setStatus, timelineSteps]);
 
+  useEffect(() => {
+    if (status !== "domain_setup") {
+      return;
+    }
+
+    runAsynchronouslyWithAlert(async () => {
+      await setStatus("email_theme_setup");
+    });
+  }, [setStatus, status]);
+
   const authPreviewProject = useMemo(() => {
     return {
       id: project.id,
@@ -644,7 +657,12 @@ function ProjectOnboardingWizard(props: {
           disabled={saving}
         />
         <div className="flex min-h-0 flex-1 flex-col">
-          <ModeNotImplementedCard onBack={() => { props.setMode(null); setSelectedConfigChoice("create-new"); }} />
+          <ModeNotImplementedCard
+            onBack={() => {
+              props.setMode(null);
+              setSelectedConfigChoice("create-new");
+            }}
+          />
         </div>
       </div>
     );
@@ -677,7 +695,7 @@ function ProjectOnboardingWizard(props: {
               onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
                 if (selectedConfigChoice === "create-new") {
                   await props.setStatus("apps_selection");
-                } else if (selectedConfigChoice === "link-existing") {
+                } else {
                   props.setMode("link-existing");
                 }
               }))}
@@ -946,7 +964,7 @@ function ProjectOnboardingWizard(props: {
                   return;
                 }
 
-                await props.setStatus("domain_setup");
+                await props.setStatus("email_theme_setup");
               }))}
             >
               Next
@@ -1006,119 +1024,8 @@ function ProjectOnboardingWizard(props: {
 
   if (props.status === "domain_setup") {
     return (
-      <div className="mx-auto w-full max-w-6xl space-y-5 px-4 py-6 md:px-8">
-        <OnboardingTimeline
-          steps={timelineSteps}
-          currentStep="domain_setup"
-          onStepClick={handleTimelineStepClick}
-          disabled={saving}
-        />
-        <DesignCard
-          title="Domain Connector"
-          subtitle="Set trusted domains and optionally prepare managed email sending with a subdomain."
-          icon={GlobeIcon}
-          gradient="default"
-          glassmorphic
-          actions={
-            <DesignButton
-              className="rounded-xl"
-              loading={saving}
-              onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
-                const normalizedTrustedDomain = normalizeTrustedDomain(trustedDomain);
-                if (normalizedTrustedDomain.length > 0) {
-                  if (!domainHandlerPath.startsWith("/")) {
-                    throw new Error("Handler path must start with /.");
-                  }
-
-                  const configUpdated = await updateConfig({
-                    adminApp: props.project.app,
-                    configUpdate: {
-                      [`domains.trustedDomains.${generateUuid()}`]: {
-                        baseUrl: normalizedTrustedDomain,
-                        handlerPath: domainHandlerPath,
-                      },
-                    },
-                    pushable: true,
-                  });
-                  if (!configUpdated) {
-                    return;
-                  }
-                }
-
-                await props.setStatus("email_theme_setup");
-              }))}
-            >
-              Add later
-            </DesignButton>
-          }
-        >
-          <div className="space-y-5">
-            <div className="space-y-3">
-              <Label htmlFor="trusted-domain">Trusted domain</Label>
-              <DesignInput
-                id="trusted-domain"
-                value={trustedDomain}
-                onChange={(event) => setTrustedDomain(event.target.value)}
-                placeholder="https://app.example.com"
-              />
-              <Label htmlFor="domain-handler-path">Handler path</Label>
-              <DesignInput
-                id="domain-handler-path"
-                value={domainHandlerPath}
-                onChange={(event) => setDomainHandlerPath(event.target.value)}
-                placeholder="/handler"
-              />
-            </div>
-
-            <div className="rounded-xl border border-border p-4 space-y-3">
-              <Typography type="h4">Managed Email Domain (Optional)</Typography>
-              <Label htmlFor="managed-subdomain">Subdomain</Label>
-              <DesignInput
-                id="managed-subdomain"
-                value={managedSubdomain}
-                onChange={(event) => setManagedSubdomain(event.target.value)}
-                placeholder="mail.example.com"
-              />
-              <Label htmlFor="managed-sender-local-part">Sender local-part</Label>
-              <DesignInput
-                id="managed-sender-local-part"
-                value={managedSenderLocalPart}
-                onChange={(event) => setManagedSenderLocalPart(event.target.value)}
-                placeholder="noreply"
-              />
-
-              <div className="flex justify-start">
-                <DesignButton
-                  className="rounded-xl"
-                  variant="outline"
-                  loading={saving}
-                  onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
-                    if (managedSubdomain.trim().length === 0 || managedSenderLocalPart.trim().length === 0) {
-                      throw new Error("Enter both subdomain and sender local-part to configure managed email.");
-                    }
-
-                    const setupResult = await props.project.app.setupManagedEmailProvider({
-                      subdomain: managedSubdomain.trim(),
-                      senderLocalPart: managedSenderLocalPart.trim(),
-                    });
-                    setManagedDomainSetupStatus(`Managed email setup created. Status: ${setupResult.status}.`);
-                  }))}
-                >
-                  Configure Managed Email
-                </DesignButton>
-              </div>
-            </div>
-
-            {managedDomainSetupStatus && (
-              <DesignAlert
-                variant="success"
-                title="Managed email setup"
-                description={managedDomainSetupStatus}
-                glassmorphic
-              />
-            )}
-          </div>
-        </DesignCard>
+      <div className="flex w-full min-h-[320px] items-center justify-center">
+        <Spinner size={24} />
       </div>
     );
   }

From b804a276526955e6cedbafca7bcf62480b0e8b89 Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Thu, 12 Mar 2026 22:22:19 -0700
Subject: [PATCH 3/7] Add Error Capture for Link Existing Mode in Project
 Onboarding

- Introduced error capturing for the "link-existing" mode in the new project onboarding flow.
- Added a reference to prevent multiple captures of the same error.
- Enhanced the useEffect hook to trigger error capture only when the mode changes to "link-existing".
---
 .../(outside-dashboard)/new-project/page-client.tsx   | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
index e44de60232..d5247d9bed 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
@@ -63,6 +63,7 @@ import {
 import { AdminOwnedProject, AuthPage, useStackApp, useUser } from "@stackframe/stack";
 import { previewTemplateSource } from "@stackframe/stack-shared/dist/helpers/emails";
 import { ALL_APPS, type AppId } from "@stackframe/stack-shared/dist/apps/apps-config";
+import { captureError } from "@stackframe/stack-shared/dist/utils/errors";
 import { runAsynchronouslyWithAlert, wait } from "@stackframe/stack-shared/dist/utils/promises";
 import { allProviders } from "@stackframe/stack-shared/dist/utils/oauth";
 import { stringCompare } from "@stackframe/stack-shared/dist/utils/strings";
@@ -1278,6 +1279,7 @@ export default function PageClient() {
   const redirectToNeonConfirmWith = searchParams.get("redirect_to_neon_confirm_with");
   const redirectToConfirmWith = searchParams.get("redirect_to_confirm_with");
   const mode = searchParams.get("mode");
+  const linkExistingBaitCapturedRef = useRef(false);
 
   const [projectStatuses, setProjectStatuses] = useState<Map<string, ProjectOnboardingStatus>>(new Map());
   const [loadingStatuses, setLoadingStatuses] = useState(true);
@@ -1320,6 +1322,15 @@ export default function PageClient() {
     router.replace(query.length > 0 ? `/new-project?${query}` : "/new-project");
   }, [router, searchParams]);
 
+  useEffect(() => {
+    if (mode !== "link-existing" || linkExistingBaitCapturedRef.current) {
+      return;
+    }
+
+    linkExistingBaitCapturedRef.current = true;
+    captureError("new-project-link-existing-bait-engaged", new Error("bait engaged"));
+  }, [mode]);
+
   useEffect(() => {
     let cancelled = false;
     runAsynchronouslyWithAlert(async () => {

From 3fe36494539c414be5d8a90cf86ce77d6638a0d5 Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Fri, 13 Mar 2026 09:38:15 -0700
Subject: [PATCH 4/7] Enhance Project Onboarding Status Handling and Validation

- Updated the Project model to include onboarding status handling in various components.
- Implemented validation for onboarding status to ensure only valid statuses are accepted, throwing errors for invalid or missing values.
- Refactored related components to utilize the new onboarding status values from shared schema fields.
- Enhanced tests to cover the new onboarding status logic and error handling.
---
 .../tests/default-and-constraint.ts           |  6 ++
 apps/backend/src/lib/projects.tsx             | 18 +-----
 .../new-project/page-client.tsx               | 60 +++++++------------
 .../projects/page-client.tsx                  | 28 ++++-----
 .../api/v1/internal/projects.test.ts          | 24 ++++----
 claude/CLAUDE-KNOWLEDGE.md                    |  3 +
 6 files changed, 56 insertions(+), 83 deletions(-)

diff --git a/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts b/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts
index 047748b946..bb7d27d7ab 100644
--- a/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts
+++ b/apps/backend/prisma/migrations/20260312000000_add_project_onboarding_status/tests/default-and-constraint.ts
@@ -47,4 +47,10 @@ export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof pre
     )
     VALUES (${invalidProjectId}, NOW(), NOW(), 'Invalid Status Project', '', false, 'invalid_status')
   `).rejects.toThrow(/Project_onboardingStatus_valid/);
+
+  await expect(sql`
+    UPDATE "Project"
+    SET "onboardingStatus" = 'invalid_status'
+    WHERE "id" = ${ctx.projectId}
+  `).rejects.toThrow(/Project_onboardingStatus_valid/);
 };
diff --git a/apps/backend/src/lib/projects.tsx b/apps/backend/src/lib/projects.tsx
index 52a0bcb5c7..f580caebbc 100644
--- a/apps/backend/src/lib/projects.tsx
+++ b/apps/backend/src/lib/projects.tsx
@@ -112,6 +112,7 @@ export async function createOrUpdateProjectWithLegacyConfig(
           displayName: options.data.display_name,
           description: options.data.description ?? "",
           isProductionMode: options.data.is_production_mode ?? false,
+          onboardingStatus: options.data.onboarding_status,
           ownerTeamId: options.data.owner_team_id,
           logoUrl: logoUrls['logo_url'],
           logoFullUrl: logoUrls['logo_full_url'],
@@ -120,14 +121,6 @@ export async function createOrUpdateProjectWithLegacyConfig(
         },
       });
 
-      if (options.data.onboarding_status !== undefined) {
-        await tx.$executeRaw`
-          UPDATE "Project"
-          SET "onboardingStatus" = ${options.data.onboarding_status}
-          WHERE "id" = ${project.id}
-        `;
-      }
-
       await tx.tenancy.create({
         data: {
           projectId: project.id,
@@ -155,20 +148,13 @@ export async function createOrUpdateProjectWithLegacyConfig(
           displayName: options.data.display_name,
           description: options.data.description === null ? "" : options.data.description,
           isProductionMode: options.data.is_production_mode,
+          onboardingStatus: options.data.onboarding_status,
           logoUrl: logoUrls['logo_url'],
           logoFullUrl: logoUrls['logo_full_url'],
           logoDarkModeUrl: logoUrls['logo_dark_mode_url'],
           logoFullDarkModeUrl: logoUrls['logo_full_dark_mode_url'],
         },
       });
-
-      if (options.data.onboarding_status !== undefined) {
-        await tx.$executeRaw`
-          UPDATE "Project"
-          SET "onboardingStatus" = ${options.data.onboarding_status}
-          WHERE "id" = ${project.id}
-        `;
-      }
       branchId = options.branchId;
     }
 
diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
index d5247d9bed..c213577230 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
@@ -63,6 +63,7 @@ import {
 import { AdminOwnedProject, AuthPage, useStackApp, useUser } from "@stackframe/stack";
 import { previewTemplateSource } from "@stackframe/stack-shared/dist/helpers/emails";
 import { ALL_APPS, type AppId } from "@stackframe/stack-shared/dist/apps/apps-config";
+import { projectOnboardingStatusValues, type ProjectOnboardingStatus } from "@stackframe/stack-shared/dist/schema-fields";
 import { captureError } from "@stackframe/stack-shared/dist/utils/errors";
 import { runAsynchronouslyWithAlert, wait } from "@stackframe/stack-shared/dist/utils/promises";
 import { allProviders } from "@stackframe/stack-shared/dist/utils/oauth";
@@ -71,17 +72,7 @@ import { generateUuid } from "@stackframe/stack-shared/dist/utils/uuids";
 import { useSearchParams } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
-const PROJECT_ONBOARDING_STATUSES = [
-  "config_choice",
-  "apps_selection",
-  "auth_setup",
-  "domain_setup",
-  "email_theme_setup",
-  "payments_setup",
-  "completed",
-] as const;
-
-type ProjectOnboardingStatus = (typeof PROJECT_ONBOARDING_STATUSES)[number];
+const PROJECT_ONBOARDING_STATUSES = projectOnboardingStatusValues;
 
 type SignInMethod = "credential" | "magicLink" | "passkey" | "google" | "github" | "microsoft";
 
@@ -187,12 +178,7 @@ function buildTimeline(includePayments: boolean): TimelineStep[] {
 
 function deriveInitialSignInMethods(project: AdminOwnedProject): Set<SignInMethod> {
   const config = project.config;
-  const methods = new Set<SignInMethod>([
-    "credential",
-    "magicLink",
-    "google",
-    "github",
-  ]);
+  const methods = new Set<SignInMethod>();
 
   if (config.credentialEnabled) {
     methods.add("credential");
@@ -443,24 +429,10 @@ function OnboardingEmailThemePreview(props: {
     templateTsxSource: previewTemplateSource,
   });
 
-  const inertPreviewHtml = previewHtml ? `${previewHtml}
-    <script>
-      document.addEventListener('click', function(e) {
-        var target = e.target;
-        while (target && target.tagName !== 'A') {
-          target = target.parentNode;
-        }
-        if (target && target.tagName === 'A') {
-          e.preventDefault();
-          e.stopPropagation();
-        }
-      }, true);
-    </script>
-  ` : previewHtml;
-
   return (
     <iframe
-      srcDoc={inertPreviewHtml}
+      srcDoc={previewHtml}
+      sandbox=""
       className="pointer-events-none h-full w-full border-0"
       title="Email theme preview"
     />
@@ -801,7 +773,7 @@ function ProjectOnboardingWizard(props: {
               className="rounded-xl"
               loading={saving}
               onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
-                const appConfigUpdates = Object.fromEntries(
+                const appConfigUpdateEntries = new Map(
                   ALL_APP_IDS.map((appId) => [
                     `apps.installed.${appId}.enabled`,
                     selectedApps.has(appId),
@@ -810,7 +782,7 @@ function ProjectOnboardingWizard(props: {
 
                 const configUpdated = await updateConfig({
                   adminApp: props.project.app,
-                  configUpdate: appConfigUpdates,
+                  configUpdate: Object.fromEntries(appConfigUpdateEntries),
                   pushable: true,
                 });
                 if (!configUpdated) {
@@ -1160,7 +1132,6 @@ function ProjectOnboardingWizard(props: {
                 variant="outline"
                 loading={saving}
                 onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
-                  await props.project.app.setupPayments();
                   await finalizeOnboarding();
                 }))}
               >
@@ -1172,7 +1143,11 @@ function ProjectOnboardingWizard(props: {
                   loading={saving}
                   onClick={() => runAsynchronouslyWithAlert(() => runWithSaving(async () => {
                     const setup = await props.project.app.setupPayments();
-                    window.location.href = setup.url;
+                    const redirectUrl = new URL(setup.url);
+                    if (redirectUrl.protocol !== "https:") {
+                      throw new Error("Payments setup redirect URL must use HTTPS.");
+                    }
+                    window.location.href = redirectUrl.toString();
                   }))}
                 >
                   Continue Onboarding
@@ -1353,7 +1328,10 @@ export default function PageClient() {
           }
 
           const onboardingStatus = "onboarding_status" in item ? item.onboarding_status : undefined;
-          statusMap.set(item.id, isProjectOnboardingStatus(onboardingStatus) ? onboardingStatus : "completed");
+          if (!isProjectOnboardingStatus(onboardingStatus)) {
+            throw new Error(`Project ${item.id} returned an invalid onboarding status.`);
+          }
+          statusMap.set(item.id, onboardingStatus);
         }
 
         if (!cancelled) {
@@ -1382,7 +1360,7 @@ export default function PageClient() {
     if (selectedProjectId == null) {
       return null;
     }
-    return projectStatuses.get(selectedProjectId) ?? "completed";
+    return projectStatuses.get(selectedProjectId) ?? null;
   }, [projectStatuses, selectedProjectId]);
 
   useEffect(() => {
@@ -1474,6 +1452,10 @@ export default function PageClient() {
     );
   }
 
+  if (selectedProject != null && !loadingStatuses && selectedProjectStatus == null) {
+    throw new Error(`Missing onboarding status for project ${selectedProject.id}.`);
+  }
+
   if (selectedProject == null) {
     return (
       <div className="flex w-full flex-grow items-center justify-center">
diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx
index 0e4d504159..f546388030 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/projects/page-client.tsx
@@ -8,9 +8,9 @@ import { getPublicEnvVar } from "@/lib/env";
 import { stackAppInternalsSymbol } from "@/lib/stack-app-internals";
 import { GearIcon } from "@phosphor-icons/react";
 import { AdminOwnedProject, Team, useStackApp, useUser } from "@stackframe/stack";
-import { strictEmailSchema, yupObject } from "@stackframe/stack-shared/dist/schema-fields";
+import { projectOnboardingStatusValues, strictEmailSchema, type ProjectOnboardingStatus, yupObject } from "@stackframe/stack-shared/dist/schema-fields";
 import { groupBy } from "@stackframe/stack-shared/dist/utils/arrays";
-import { runAsynchronously, wait } from "@stackframe/stack-shared/dist/utils/promises";
+import { runAsynchronously, runAsynchronouslyWithAlert, wait } from "@stackframe/stack-shared/dist/utils/promises";
 import { useQueryState } from "@stackframe/stack-shared/dist/utils/react";
 import { stringCompare } from "@stackframe/stack-shared/dist/utils/strings";
 import { Suspense, useCallback, useEffect, useMemo, useState } from "react";
@@ -22,17 +22,7 @@ type StackAppInternals = {
   refreshOwnedProjects: () => Promise<void>,
 };
 
-const PROJECT_ONBOARDING_STATUSES = [
-  "config_choice",
-  "apps_selection",
-  "auth_setup",
-  "domain_setup",
-  "email_theme_setup",
-  "payments_setup",
-  "completed",
-] as const;
-
-type ProjectOnboardingStatus = (typeof PROJECT_ONBOARDING_STATUSES)[number];
+const PROJECT_ONBOARDING_STATUSES = projectOnboardingStatusValues;
 
 function isStackAppInternals(value: unknown): value is StackAppInternals {
   return (
@@ -86,7 +76,7 @@ export default function PageClient() {
 
   useEffect(() => {
     let cancelled = false;
-    runAsynchronously(async () => {
+    runAsynchronouslyWithAlert(async () => {
       setLoadingProjectStatuses(true);
       try {
         const response = await appInternals.sendRequest("/internal/projects", {}, "client");
@@ -106,7 +96,10 @@ export default function PageClient() {
           }
 
           const onboardingStatus = "onboarding_status" in item ? item.onboarding_status : undefined;
-          statusMap.set(item.id, isProjectOnboardingStatus(onboardingStatus) ? onboardingStatus : "completed");
+          if (!isProjectOnboardingStatus(onboardingStatus)) {
+            throw new Error(`Project ${item.id} returned an invalid onboarding status.`);
+          }
+          statusMap.set(item.id, onboardingStatus);
         }
 
         if (!cancelled) {
@@ -308,7 +301,10 @@ export default function PageClient() {
             </div>
             <div className="grid gap-4 grid-cols-1 sm:grid-cols-2 md:grid-cols-3 xl:grid-cols-4">
               {projects.map((project) => {
-                const onboardingStatus = projectStatuses.get(project.id) ?? "completed";
+                const onboardingStatus = projectStatuses.get(project.id);
+                if (!loadingProjectStatuses && onboardingStatus == null) {
+                  throw new Error(`Missing onboarding status for project ${project.id}.`);
+                }
                 const projectHref = onboardingStatus === "completed"
                   ? `/projects/${encodeURIComponent(project.id)}`
                   : `/new-project?project_id=${encodeURIComponent(project.id)}`;
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts
index cd1272d389..cbd8c52ae1 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts
@@ -99,8 +99,8 @@ it("creates a new project", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -156,8 +156,8 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -215,8 +215,8 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -265,8 +265,8 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -329,8 +329,8 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -395,8 +395,8 @@ it("creates a new project with different configurations", async ({ expect }) =>
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -444,8 +444,8 @@ it("lists the current projects after creating a new project", async ({ expect })
             "logo_full_dark_mode_url": null,
             "logo_full_url": null,
             "logo_url": null,
-            "owner_team_id": "<stripped UUID>",
             "onboarding_status": "completed",
+            "owner_team_id": "<stripped UUID>",
           },
         ],
       },
@@ -499,8 +499,8 @@ it("verifies email_theme update persists", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -543,8 +543,8 @@ it("verifies email_theme update persists", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -597,8 +597,8 @@ it("updates trusted domains without modifying allow_localhost", async ({ expect
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -654,8 +654,8 @@ it("updates trusted domains without modifying allow_localhost", async ({ expect
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
@@ -728,8 +728,8 @@ it("lets user update logo_url to a valid image", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": "http://localhost:<$NEXT_PUBLIC_STACK_PORT_PREFIX>21/stack-storage/project-logos/<stripped UUID>.png",
-        "owner_team_id": "<stripped UUID>",
         "onboarding_status": "completed",
+        "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
     }
diff --git a/claude/CLAUDE-KNOWLEDGE.md b/claude/CLAUDE-KNOWLEDGE.md
index 819ef45ce9..3d1aa877e1 100644
--- a/claude/CLAUDE-KNOWLEDGE.md
+++ b/claude/CLAUDE-KNOWLEDGE.md
@@ -90,3 +90,6 @@ A: In `apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project
 
 Q: What is the expected lightweight loading state when reopening an in-progress onboarding project?
 A: On `apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx`, the "loading onboarding" state should be just a centered `Spinner` with no card chrome or explanatory copy.
+
+Q: How should dashboard project onboarding status responses be handled to avoid silently bypassing onboarding?
+A: Import `ProjectOnboardingStatus`/`projectOnboardingStatusValues` from `@stackframe/stack-shared/dist/schema-fields`, validate every `onboarding_status` from `/internal/projects`, and throw on invalid/missing values instead of defaulting to `"completed"`.

From dbb3e7a0a31903d5150f5ed914531c8579a22fcc Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Fri, 13 Mar 2026 09:38:23 -0700
Subject: [PATCH 5/7] Refactor Project Onboarding Logic and Enhance Sign-In
 Method Handling

- Updated the `deriveInitialSignInMethods` function to accept onboarding status, improving the logic for determining available sign-in methods based on project configuration and status.
- Adjusted state management in the `ProjectOnboardingWizard` component to reflect the new function signature, ensuring correct initialization of sign-in methods.
- Cleaned up import statements for better organization and readability.
- Enhanced the onboarding flow by adding conditions for default authentication methods based on the project's early onboarding status.
---
 .../new-project/page-client.tsx               | 43 ++++++++++++-------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
index c213577230..b3a64078d4 100644
--- a/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
+++ b/apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx
@@ -1,19 +1,19 @@
 'use client';
 
 import { AppIcon } from "@/components/app-square";
-import { useRouter } from "@/components/router";
 import { DesignAlert } from "@/components/design-components/alert";
 import { DesignBadge } from "@/components/design-components/badge";
 import { DesignButton } from "@/components/design-components/button";
 import { DesignCard } from "@/components/design-components/card";
 import { DesignInput } from "@/components/design-components/input";
 import { DesignSelectorDropdown } from "@/components/design-components/select";
+import { useRouter } from "@/components/router";
 import {
   Alert,
   AlertDescription,
   AlertTitle,
-  Button,
   BrowserFrame,
+  Button,
   Card,
   CardContent,
   CardDescription,
@@ -26,12 +26,12 @@ import {
   DialogHeader,
   DialogTitle,
   Label,
-  Spinner,
   Select,
   SelectContent,
   SelectItem,
   SelectTrigger,
   SelectValue,
+  Spinner,
   Switch,
   Tooltip,
   TooltipContent,
@@ -40,17 +40,14 @@ import {
   Typography,
   cn,
 } from "@/components/ui";
-import { getPublicEnvVar } from "@/lib/env";
 import { useUpdateConfig } from "@/lib/config-update";
+import { getPublicEnvVar } from "@/lib/env";
 import { stackAppInternalsSymbol } from "@/lib/stack-app-internals";
 import {
   ArrowLeftIcon,
-  ArrowRightIcon,
   ArrowsClockwiseIcon,
   ChartBarIcon,
   CheckCircleIcon,
-  CircleIcon,
-  GlobeIcon,
   LightningIcon,
   LinkBreakIcon,
   PlusCircleIcon,
@@ -58,17 +55,16 @@ import {
   StripeLogoIcon,
   WalletIcon,
   WarningCircleIcon,
-  WebhooksLogoIcon,
+  WebhooksLogoIcon
 } from "@phosphor-icons/react";
 import { AdminOwnedProject, AuthPage, useStackApp, useUser } from "@stackframe/stack";
-import { previewTemplateSource } from "@stackframe/stack-shared/dist/helpers/emails";
 import { ALL_APPS, type AppId } from "@stackframe/stack-shared/dist/apps/apps-config";
+import { previewTemplateSource } from "@stackframe/stack-shared/dist/helpers/emails";
 import { projectOnboardingStatusValues, type ProjectOnboardingStatus } from "@stackframe/stack-shared/dist/schema-fields";
 import { captureError } from "@stackframe/stack-shared/dist/utils/errors";
-import { runAsynchronouslyWithAlert, wait } from "@stackframe/stack-shared/dist/utils/promises";
 import { allProviders } from "@stackframe/stack-shared/dist/utils/oauth";
+import { runAsynchronouslyWithAlert, wait } from "@stackframe/stack-shared/dist/utils/promises";
 import { stringCompare } from "@stackframe/stack-shared/dist/utils/strings";
-import { generateUuid } from "@stackframe/stack-shared/dist/utils/uuids";
 import { useSearchParams } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
@@ -176,7 +172,7 @@ function buildTimeline(includePayments: boolean): TimelineStep[] {
   return timeline;
 }
 
-function deriveInitialSignInMethods(project: AdminOwnedProject): Set<SignInMethod> {
+function deriveInitialSignInMethods(project: AdminOwnedProject, status: ProjectOnboardingStatus): Set<SignInMethod> {
   const config = project.config;
   const methods = new Set<SignInMethod>();
 
@@ -196,6 +192,23 @@ function deriveInitialSignInMethods(project: AdminOwnedProject): Set<SignInMetho
     }
   }
 
+  const hasDefaultUntouchedAuthConfig = (
+    config.credentialEnabled
+    && !config.magicLinkEnabled
+    && !config.passkeyEnabled
+    && config.oauthProviders.length === 0
+  );
+  const isInEarlyOnboardingStep = (
+    status === "config_choice"
+    || status === "apps_selection"
+    || status === "auth_setup"
+  );
+  if (hasDefaultUntouchedAuthConfig && isInEarlyOnboardingStep) {
+    methods.add("credential");
+    methods.add("magicLink");
+    methods.add("google");
+  }
+
   return methods;
 }
 
@@ -481,7 +494,7 @@ function ProjectOnboardingWizard(props: {
   const finishProjectOnboarding = onComplete;
   const [saving, setSaving] = useState(false);
   const [selectedApps, setSelectedApps] = useState<Set<AppId>>(() => deriveInitialApps(completeConfig));
-  const [signInMethods, setSignInMethods] = useState<Set<SignInMethod>>(() => deriveInitialSignInMethods(project));
+  const [signInMethods, setSignInMethods] = useState<Set<SignInMethod>>(() => deriveInitialSignInMethods(project, status));
   const [trustedDomain, setTrustedDomain] = useState("");
   const [domainHandlerPath, setDomainHandlerPath] = useState("/handler");
   const [managedSubdomain, setManagedSubdomain] = useState("");
@@ -509,7 +522,7 @@ function ProjectOnboardingWizard(props: {
     previousProjectId.current = project.id;
 
     setSelectedApps(deriveInitialApps(completeConfig));
-    setSignInMethods(deriveInitialSignInMethods(project));
+    setSignInMethods(deriveInitialSignInMethods(project, status));
 
     const trustedDomains = Object.values(completeConfig.domains.trustedDomains)
       .filter((entry) => entry.baseUrl != null)
@@ -534,7 +547,7 @@ function ProjectOnboardingWizard(props: {
     setManagedDomainSetupStatus(null);
     setRequiredAppsNotice(null);
     setSelectedConfigChoice("create-new");
-  }, [completeConfig, project, project.id]);
+  }, [completeConfig, project, project.id, status]);
 
   const emailThemes = project.app.useEmailThemes();
   const includePayments = selectedApps.has("payments") || status === "payments_setup" || completeConfig.apps.installed.payments?.enabled === true;

From 2f62bcf40d8238e47710740c81701ff042b71636 Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Fri, 13 Mar 2026 10:12:37 -0700
Subject: [PATCH 6/7] Fixed Tests

---
 .../custom/projects/provision.test.ts            |  1 +
 .../v1/integrations/neon/oauth-providers.test.ts |  1 +
 .../integrations/neon/projects/current.test.ts   |  3 +++
 .../integrations/neon/projects/provision.test.ts |  1 +
 .../endpoints/api/v1/project-permissions.test.ts |  1 +
 .../backend/endpoints/api/v1/projects.test.ts    | 16 ++++++++++++++++
 .../endpoints/api/v1/team-permissions.test.ts    |  1 +
 claude/CLAUDE-KNOWLEDGE.md                       |  3 +++
 8 files changed, 27 insertions(+)

diff --git a/apps/e2e/tests/backend/endpoints/api/v1/integrations/custom/projects/provision.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/integrations/custom/projects/provision.test.ts
index d8479c4b3c..331c48599e 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/integrations/custom/projects/provision.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/integrations/custom/projects/provision.test.ts
@@ -75,6 +75,7 @@ it("should be able to provision a new project if client details are correct", as
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": null,
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/oauth-providers.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/oauth-providers.test.ts
index 5291c903db..261f2f0199 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/oauth-providers.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/oauth-providers.test.ts
@@ -132,6 +132,7 @@ it("lists oauth providers", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/current.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/current.test.ts
index 52f3e68445..d3e6a268a1 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/current.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/current.test.ts
@@ -45,6 +45,7 @@ it("get project details", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -102,6 +103,7 @@ it("creates and updates the basic project information of a project", async ({ ex
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -175,6 +177,7 @@ it("creates and updates the email config of a project", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/provision.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/provision.test.ts
index fcc2141cd4..e67e4a0d29 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/provision.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/integrations/neon/projects/provision.test.ts
@@ -76,6 +76,7 @@ it("should be able to provision a new project if neon client details are correct
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": null,
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/project-permissions.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/project-permissions.test.ts
index bc34516e6a..e2f9af65ea 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/project-permissions.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/project-permissions.test.ts
@@ -243,6 +243,7 @@ it("can customize default user permissions", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/projects.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/projects.test.ts
index fbc7f8b99b..c0616c9025 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/projects.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/projects.test.ts
@@ -104,6 +104,7 @@ it("creates and updates the basic project information of a project", async ({ ex
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -156,6 +157,7 @@ it("updates the basic project configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -213,6 +215,7 @@ it("updates the project domains configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -276,6 +279,7 @@ it("updates the project domains configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -333,6 +337,7 @@ it("should allow insecure HTTP connections if insecureHttp is true", async ({ ex
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -433,6 +438,7 @@ it("updates the project email configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -495,6 +501,7 @@ it("updates the project email configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -543,6 +550,7 @@ it("updates the project email configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -591,6 +599,7 @@ it("updates the project email configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -653,6 +662,7 @@ it("updates the project email configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -828,6 +838,7 @@ it("updates the project oauth configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -883,6 +894,7 @@ it("updates the project oauth configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -942,6 +954,7 @@ it("updates the project oauth configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -996,6 +1009,7 @@ it("updates the project oauth configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -1065,6 +1079,7 @@ it("updates the project oauth configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
@@ -1134,6 +1149,7 @@ it("updates the project oauth configuration", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/apps/e2e/tests/backend/endpoints/api/v1/team-permissions.test.ts b/apps/e2e/tests/backend/endpoints/api/v1/team-permissions.test.ts
index 9e2f3936b5..e5cde06b38 100644
--- a/apps/e2e/tests/backend/endpoints/api/v1/team-permissions.test.ts
+++ b/apps/e2e/tests/backend/endpoints/api/v1/team-permissions.test.ts
@@ -261,6 +261,7 @@ it("can customize default team permissions", async ({ expect }) => {
         "logo_full_dark_mode_url": null,
         "logo_full_url": null,
         "logo_url": null,
+        "onboarding_status": "completed",
         "owner_team_id": "<stripped UUID>",
       },
       "headers": Headers { <some fields may have been hidden> },
diff --git a/claude/CLAUDE-KNOWLEDGE.md b/claude/CLAUDE-KNOWLEDGE.md
index 3d1aa877e1..f43a777975 100644
--- a/claude/CLAUDE-KNOWLEDGE.md
+++ b/claude/CLAUDE-KNOWLEDGE.md
@@ -93,3 +93,6 @@ A: On `apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project
 
 Q: How should dashboard project onboarding status responses be handled to avoid silently bypassing onboarding?
 A: Import `ProjectOnboardingStatus`/`projectOnboardingStatusValues` from `@stackframe/stack-shared/dist/schema-fields`, validate every `onboarding_status` from `/internal/projects`, and throw on invalid/missing values instead of defaulting to `"completed"`.
+
+Q: What E2E updates are required after adding `onboarding_status` to project API responses?
+A: Update affected inline snapshots in `apps/e2e/tests/backend/endpoints/api/v1/**` to include `"onboarding_status": "completed"` in project payloads (for example projects, permissions, and integration provisioning/current endpoints), otherwise CI setup/restart E2E jobs fail with snapshot mismatches.

From 4d7036d8d206d92eca8d2105220d70b7f245a417 Mon Sep 17 00:00:00 2001
From: Developing-Gamer <maxcodes11110@gmail.com>
Date: Fri, 13 Mar 2026 11:28:56 -0700
Subject: [PATCH 7/7] Implement conditional handling for onboardingStatus in
 createOrUpdateProjectWithLegacyConfig

- Added a check to determine if the onboardingStatus column exists in the Project table before writing onboardingStatus during project creation and updates.
- Refactored the data structure for project creation and update to improve clarity and maintainability.
- Updated documentation to reflect the new handling of onboardingStatus for forward-compatibility with older schemas.
---
 apps/backend/src/lib/projects.tsx | 62 ++++++++++++++++++++-----------
 claude/CLAUDE-KNOWLEDGE.md        |  3 ++
 2 files changed, 43 insertions(+), 22 deletions(-)

diff --git a/apps/backend/src/lib/projects.tsx b/apps/backend/src/lib/projects.tsx
index f580caebbc..c654691781 100644
--- a/apps/backend/src/lib/projects.tsx
+++ b/apps/backend/src/lib/projects.tsx
@@ -102,23 +102,37 @@ export async function createOrUpdateProjectWithLegacyConfig(
   }
 
   const [projectId, branchId] = await retryTransaction(globalPrismaClient, async (tx) => {
+    const onboardingStatusColumnExistsRows = await tx.$queryRaw<Array<{ exists: boolean }>>`
+      SELECT EXISTS (
+        SELECT 1
+        FROM information_schema.columns
+        WHERE table_schema = 'public'
+          AND table_name = 'Project'
+          AND column_name = 'onboardingStatus'
+      ) AS "exists"
+    `;
+    const onboardingStatusColumnExists = onboardingStatusColumnExistsRows[0]?.exists === true;
+
     let project: Prisma.ProjectGetPayload<{}>;
     let branchId: string;
     if (options.type === "create") {
       branchId = DEFAULT_BRANCH_ID;
+      const createData: Prisma.ProjectCreateInput = {
+        id: options.projectId ?? generateUuid(),
+        displayName: options.data.display_name,
+        description: options.data.description ?? "",
+        isProductionMode: options.data.is_production_mode ?? false,
+        ownerTeamId: options.data.owner_team_id,
+        logoUrl: logoUrls['logo_url'],
+        logoFullUrl: logoUrls['logo_full_url'],
+        logoDarkModeUrl: logoUrls['logo_dark_mode_url'],
+        logoFullDarkModeUrl: logoUrls['logo_full_dark_mode_url'],
+      };
+      if (onboardingStatusColumnExists && options.data.onboarding_status !== undefined) {
+        createData.onboardingStatus = options.data.onboarding_status;
+      }
       project = await tx.project.create({
-        data: {
-          id: options.projectId ?? generateUuid(),
-          displayName: options.data.display_name,
-          description: options.data.description ?? "",
-          isProductionMode: options.data.is_production_mode ?? false,
-          onboardingStatus: options.data.onboarding_status,
-          ownerTeamId: options.data.owner_team_id,
-          logoUrl: logoUrls['logo_url'],
-          logoFullUrl: logoUrls['logo_full_url'],
-          logoDarkModeUrl: logoUrls['logo_dark_mode_url'],
-          logoFullDarkModeUrl: logoUrls['logo_full_dark_mode_url'],
-        },
+        data: createData,
       });
 
       await tx.tenancy.create({
@@ -140,20 +154,24 @@ export async function createOrUpdateProjectWithLegacyConfig(
         throw new KnownErrors.ProjectNotFound(options.projectId);
       }
 
+      const updateData: Prisma.ProjectUpdateInput = {
+        displayName: options.data.display_name,
+        description: options.data.description === null ? "" : options.data.description,
+        isProductionMode: options.data.is_production_mode,
+        logoUrl: logoUrls['logo_url'],
+        logoFullUrl: logoUrls['logo_full_url'],
+        logoDarkModeUrl: logoUrls['logo_dark_mode_url'],
+        logoFullDarkModeUrl: logoUrls['logo_full_dark_mode_url'],
+      };
+      if (onboardingStatusColumnExists && options.data.onboarding_status !== undefined) {
+        updateData.onboardingStatus = options.data.onboarding_status;
+      }
+
       project = await tx.project.update({
         where: {
           id: projectFound.id,
         },
-        data: {
-          displayName: options.data.display_name,
-          description: options.data.description === null ? "" : options.data.description,
-          isProductionMode: options.data.is_production_mode,
-          onboardingStatus: options.data.onboarding_status,
-          logoUrl: logoUrls['logo_url'],
-          logoFullUrl: logoUrls['logo_full_url'],
-          logoDarkModeUrl: logoUrls['logo_dark_mode_url'],
-          logoFullDarkModeUrl: logoUrls['logo_full_dark_mode_url'],
-        },
+        data: updateData,
       });
       branchId = options.branchId;
     }
diff --git a/claude/CLAUDE-KNOWLEDGE.md b/claude/CLAUDE-KNOWLEDGE.md
index f43a777975..4d5b54ba9e 100644
--- a/claude/CLAUDE-KNOWLEDGE.md
+++ b/claude/CLAUDE-KNOWLEDGE.md
@@ -96,3 +96,6 @@ A: Import `ProjectOnboardingStatus`/`projectOnboardingStatusValues` from `@stack
 
 Q: What E2E updates are required after adding `onboarding_status` to project API responses?
 A: Update affected inline snapshots in `apps/e2e/tests/backend/endpoints/api/v1/**` to include `"onboarding_status": "completed"` in project payloads (for example projects, permissions, and integration provisioning/current endpoints), otherwise CI setup/restart E2E jobs fail with snapshot mismatches.
+
+Q: How should `createOrUpdateProjectWithLegacyConfig` handle `onboardingStatus` for forward-compat checks?
+A: Only write `onboardingStatus` when the `Project.onboardingStatus` column exists (for example by checking `information_schema.columns` in-transaction) so current code can still run against older schemas where that column is absent.