From 04130c0fe2fdcf44add63d60c7909e74f722082e Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Fri, 15 May 2026 18:25:47 -0700
Subject: [PATCH 01/28] feat: local dev without third-party credentials
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A fresh clone can now boot the full dev stack (web + api + desktop +
electric + electric-proxy + caddy) against a local Postgres in Docker,
with no Neon, OAuth, Stripe, Resend, or other cloud-service keys required.

Key changes:
- packages/db/src/client.ts: driver swap to drizzle-orm/node-postgres for
  non-Neon DATABASE_URLs (@neondatabase/serverless only speaks Neon's
  HTTP/WS protocol, not vanilla Postgres TCP).
- packages/auth/src/server.ts: emailAndPassword auth enabled + autoSignIn.
- apps/desktop/src/main/lib/dev-auto-sign-in.ts: during app.whenReady(),
  if SKIP_ENV_VALIDATION=1 and no token on disk, auto-signs-in as
  admin@local.test and persists the token via the existing saveToken().
  Renderer hydrates like a real OAuth user — no special renderer code.
- 17 renderer files: flip MOCK_ORG_ID priority — prefer real session's
  activeOrganizationId, fall back to MOCK_ORG_ID only without a session.
  Fixes the "Host service not available" toast that fired because the
  renderer was looking up host-service connections by the fake org id
  while host-service spawned for the real admin@local.test org.
- Lazy-init guards for Stripe (Proxy), Resend (Proxy), and PostHog (no-op
  surface) so they don't crash module load when keys are missing.
- apps/web: dev-only email/password form on sign-in/sign-up, gated on
  NODE_ENV !== "production".
- packages/db: bun db:seed:dev script to create admin@local.test;
  refuses prod + non-localhost DATABASE_URL.
- turbo.jsonc: SKIP_ENV_VALIDATION added to globalPassThroughEnv.
- docs/LOCAL_DEVELOPMENT.md: contributor-facing setup guide.
- plans/20260515-oss-local-setup.md: full record of what shipped + what's
  deferred (env vars .optional(), docker-compose.dev.yml, bun setup
  orchestrator, CI fresh-clone smoke test).

Verified end-to-end via Chrome DevTools Protocol (port 9333) — the
renderer's LocalHostServiceContext.activeHostUrl resolves to a live
host-service URL, so the import gate is open.
---
 README.md                                     |  49 ++----
 apps/api/src/lib/analytics.ts                 |  33 +++-
 apps/desktop/src/main/index.ts                |  13 ++
 apps/desktop/src/main/lib/dev-auto-sign-in.ts |  96 +++++++++++
 .../OpenInWorkspaceV2/OpenInWorkspaceV2.tsx   |   6 +-
 .../RunInWorkspacePopoverV2.tsx               |   6 +-
 .../RunIssuesInWorkspacePopover.tsx           |   6 +-
 .../useAccessibleV2Workspaces.ts              |   6 +-
 .../useWorkspaceHostOptions.ts                |   6 +-
 .../DashboardNewWorkspaceModalContent.tsx     |   6 +-
 .../V1ImportModal/V1ImportModal.tsx           |   6 +-
 .../renderer/routes/_authenticated/layout.tsx |   6 +-
 .../CollectionsProvider.tsx                   |   6 +-
 .../LocalHostServiceProvider.tsx              |   6 +-
 .../HostsSettingsSidebar.tsx                  |   6 +-
 .../_authenticated/settings/hosts/page.tsx    |   6 +-
 .../settings/projects/$projectId/page.tsx     |   6 +-
 .../ProjectsSettingsSidebar.tsx               |   6 +-
 .../_authenticated/settings/projects/page.tsx |   6 +-
 .../_authenticated/setup/project/page.tsx     |   6 +-
 .../src/renderer/routes/sign-in/page.tsx      |   4 +-
 .../components/DevAuthForm/DevAuthForm.tsx    | 103 ++++++++++++
 .../(auth)/components/DevAuthForm/index.ts    |   1 +
 .../(auth)/sign-in/[[...sign-in]]/page.tsx    |   4 +
 .../(auth)/sign-up/[[...sign-up]]/page.tsx    |   6 +
 bun.lock                                      |   6 +-
 docs/LOCAL_DEVELOPMENT.md                     | 154 ++++++++++++++++++
 package.json                                  |   1 +
 packages/auth/src/lib/resend.ts               |  54 +++++-
 packages/auth/src/server.ts                   |   4 +
 packages/auth/src/stripe.ts                   |  16 +-
 packages/db/package.json                      |   3 +
 packages/db/src/client.ts                     |  48 ++++--
 packages/db/src/seed-dev.ts                   |  73 +++++++++
 packages/trpc/src/lib/analytics.ts            |  32 +++-
 packages/trpc/src/router/support/support.ts   |  19 ++-
 plans/20260515-oss-local-setup.md             | 119 ++++++++++++++
 turbo.jsonc                                   |   3 +-
 38 files changed, 822 insertions(+), 115 deletions(-)
 create mode 100644 apps/desktop/src/main/lib/dev-auto-sign-in.ts
 create mode 100644 apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx
 create mode 100644 apps/web/src/app/(auth)/components/DevAuthForm/index.ts
 create mode 100644 docs/LOCAL_DEVELOPMENT.md
 create mode 100644 packages/db/src/seed-dev.ts
 create mode 100644 plans/20260515-oss-local-setup.md

diff --git a/README.md b/README.md
index e1d935232ec..e2758e59ecf 100644
--- a/README.md
+++ b/README.md
@@ -85,57 +85,32 @@ If it runs in a terminal, it runs on Superset
 
 ### Build from Source
 
-<details>
-<summary>Click to expand build instructions</summary>
+For a complete contributor workflow that boots a fresh clone with no third-party credentials (Neon / OAuth / Stripe / Resend keys are all optional), follow **[Local Development](docs/LOCAL_DEVELOPMENT.md)**.
 
-**1. Clone the repository**
+Short version:
 
 ```bash
 git clone https://github.com/superset-sh/superset.git
 cd superset
-```
-
-**2. Set up environment variables** (choose one):
-
-Option A: Full setup
-```bash
-cp .env.example .env
-# Edit .env and fill in the values
-```
-
-Option B: Skip env validation (for quick local testing)
-```bash
-cp .env.example .env
-echo 'SKIP_ENV_VALIDATION=1' >> .env
-```
-
-**3. Set up Caddy** (reverse proxy for Electric SQL streams):
-
-```bash
-# Install caddy: brew install caddy (macOS) or see https://caddyserver.com/docs/install
-cp Caddyfile.example Caddyfile
-
-# Without this, Chromium rejects https://localhost:* with ERR_CERT_AUTHORITY_INVALID.
-# Prompts for sudo once.
-caddy trust
-```
-
-**4. Install dependencies and run**
-
-```bash
 bun install
-bun run dev
+docker run -d --name superset-pg \
+  -e POSTGRES_USER=superset -e POSTGRES_PASSWORD=superset -e POSTGRES_DB=superset \
+  -p 5433:5432 postgres:16 -c wal_level=logical
+cp .env.example .env   # then edit DATABASE_URL + BETTER_AUTH_SECRET
+bun run db:migrate
+cp Caddyfile.example Caddyfile && caddy trust
+SKIP_ENV_VALIDATION=1 bun dev
 ```
 
-**5. Build the desktop app**
+The desktop window opens auto-signed-in as a seed admin (`admin@local.test`). See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details, troubleshooting, and what's stubbed without integration keys.
+
+To build a distributable desktop app:
 
 ```bash
 bun run build
 open apps/desktop/release
 ```
 
-</details>
-
 ## Keyboard Shortcuts
 
 All shortcuts are customizable via **Settings > Keyboard Shortcuts** (`⌘/`). See [full documentation](https://docs.superset.sh/keyboard-shortcuts).
diff --git a/apps/api/src/lib/analytics.ts b/apps/api/src/lib/analytics.ts
index aa8d66fce76..8f5536ff5d3 100644
--- a/apps/api/src/lib/analytics.ts
+++ b/apps/api/src/lib/analytics.ts
@@ -1,8 +1,33 @@
 import { PostHog } from "posthog-node";
 import { env } from "@/env";
 
-export const posthog = new PostHog(env.NEXT_PUBLIC_POSTHOG_KEY, {
-	host: env.NEXT_PUBLIC_POSTHOG_HOST,
-	flushAt: 1,
-	flushInterval: 0,
+let client: PostHog | null = null;
+
+// Disabled stub — accepts any args, returns the right shape for each method.
+const disabled = {
+	capture: (..._args: unknown[]) => {},
+	identify: (..._args: unknown[]) => {},
+	alias: (..._args: unknown[]) => {},
+	groupIdentify: (..._args: unknown[]) => {},
+	shutdown: (..._args: unknown[]) => Promise.resolve(),
+	flush: (..._args: unknown[]) => Promise.resolve(),
+	getFeatureFlag: (..._args: unknown[]) => Promise.resolve(undefined),
+	getFeatureFlagPayload: (..._args: unknown[]) => Promise.resolve(undefined),
+	isFeatureEnabled: (..._args: unknown[]) => Promise.resolve(undefined),
+} as unknown as PostHog;
+
+// Lazy-init: if NEXT_PUBLIC_POSTHOG_KEY is missing, return a no-op surface
+// so analytics calls don't crash the API at module load.
+export const posthog = new Proxy({} as PostHog, {
+	get(_target, prop) {
+		if (!env.NEXT_PUBLIC_POSTHOG_KEY) return Reflect.get(disabled, prop);
+		if (!client) {
+			client = new PostHog(env.NEXT_PUBLIC_POSTHOG_KEY, {
+				host: env.NEXT_PUBLIC_POSTHOG_HOST,
+				flushAt: 1,
+				flushInterval: 0,
+			});
+		}
+		return Reflect.get(client, prop);
+	},
 });
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 03879a6d9ea..eca914a7d3b 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -28,6 +28,7 @@ import { initAppState } from "./lib/app-state";
 import { requestAppleEventsAccess } from "./lib/apple-events-permission";
 import { setupAutoUpdater } from "./lib/auto-updater";
 import { installBundledCliShim } from "./lib/bundled-cli";
+import { ensureDevAuthToken } from "./lib/dev-auto-sign-in";
 import { resolveDevWorkspaceName } from "./lib/dev-workspace-name";
 import { setWorkspaceDockIcon } from "./lib/dock-icon";
 import { loadWebviewBrowserExtension } from "./lib/extensions";
@@ -55,6 +56,12 @@ import { MainWindow } from "./windows/main";
 console.log("[main] Local database ready:", !!localDb);
 const IS_DEV = process.env.NODE_ENV === "development";
 
+// Dev: expose Chrome DevTools Protocol for headless testing (e.g. import/host-service checks)
+if (IS_DEV && process.env.SKIP_ENV_VALIDATION) {
+	app.commandLine.appendSwitch("remote-debugging-port", "9333");
+	app.commandLine.appendSwitch("remote-allow-origins", "*");
+}
+
 void applyShellEnvToProcess().catch((error) => {
 	console.error("[main] Failed to apply shell environment:", error);
 });
@@ -416,6 +423,12 @@ if (!gotTheLock) {
 			console.error("[main] Failed to install bundled CLI shim:", error);
 		}
 
+		// Dev-only: auto-sign-in as the seed admin if SKIP_ENV_VALIDATION is
+		// set and no token is on disk. Lets fresh-clone contributors boot the
+		// desktop without OAuth. Runs before host-service discovery so the
+		// renderer's AuthProvider hydrates with a valid token on first paint.
+		await ensureDevAuthToken();
+
 		// Discover and adopt host-services that survived a previous quit
 		// before the tray initializes, so it shows accurate status immediately.
 		await getHostServiceCoordinator().discoverAll();
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
new file mode 100644
index 00000000000..e5f1f5a0650
--- /dev/null
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -0,0 +1,96 @@
+import { env as mainEnv } from "main/env.main";
+import {
+	loadToken,
+	saveToken,
+} from "../../lib/trpc/routers/auth/utils/auth-functions";
+
+const DEV_EMAIL = "admin@local.test";
+const DEV_PASSWORD = "supersetdev";
+const DEV_NAME = "Local Admin";
+const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
+
+interface SignInResponse {
+	token?: string;
+	user?: { id: string };
+}
+
+interface AuthErrorBody {
+	code?: string;
+	message?: string;
+}
+
+async function postAuth<T>(
+	path: string,
+	body: Record<string, unknown>,
+): Promise<{ ok: boolean; status: number; data: T | AuthErrorBody }> {
+	const res = await fetch(`${mainEnv.NEXT_PUBLIC_API_URL}${path}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Origin: mainEnv.NEXT_PUBLIC_API_URL,
+		},
+		body: JSON.stringify(body),
+	});
+	const data = (await res.json().catch(() => ({}))) as T | AuthErrorBody;
+	return { ok: res.ok, status: res.status, data };
+}
+
+/**
+ * Dev-only: if SKIP_ENV_VALIDATION is set and no usable token is on disk,
+ * sign in (or sign up) as the seed admin user and persist the token so
+ * the renderer's AuthProvider can hydrate normally — no special renderer code.
+ * Best-effort: failure is logged but doesn't crash boot.
+ */
+export async function ensureDevAuthToken(): Promise<void> {
+	if (
+		process.env.NODE_ENV !== "development" ||
+		!process.env.SKIP_ENV_VALIDATION
+	)
+		return;
+
+	const stored = await loadToken();
+	if (stored.token && stored.expiresAt) {
+		const isExpired = new Date(stored.expiresAt) < new Date();
+		if (!isExpired) return;
+	}
+
+	try {
+		let signIn = await postAuth<SignInResponse>("/api/auth/sign-in/email", {
+			email: DEV_EMAIL,
+			password: DEV_PASSWORD,
+		});
+
+		const errBody = signIn.data as AuthErrorBody;
+		if (!signIn.ok && errBody.code === "INVALID_EMAIL_OR_PASSWORD") {
+			const signUp = await postAuth<SignInResponse>("/api/auth/sign-up/email", {
+				email: DEV_EMAIL,
+				password: DEV_PASSWORD,
+				name: DEV_NAME,
+			});
+			if (!signUp.ok) {
+				const e = signUp.data as AuthErrorBody;
+				throw new Error(`dev sign-up failed (${signUp.status}): ${e.message}`);
+			}
+			signIn = await postAuth<SignInResponse>("/api/auth/sign-in/email", {
+				email: DEV_EMAIL,
+				password: DEV_PASSWORD,
+			});
+		}
+
+		if (!signIn.ok) {
+			const e = signIn.data as AuthErrorBody;
+			throw new Error(`dev sign-in failed (${signIn.status}): ${e.message}`);
+		}
+		const token = (signIn.data as SignInResponse).token;
+		if (!token) throw new Error("dev sign-in: no token in response");
+
+		const expiresAt = new Date(Date.now() + TOKEN_TTL_MS).toISOString();
+		await saveToken({ token, expiresAt });
+		console.log(`[dev-auto-sign-in] signed in as ${DEV_EMAIL}`);
+	} catch (err) {
+		console.warn(
+			`[dev-auto-sign-in] failed (is the API up at ${mainEnv.NEXT_PUBLIC_API_URL}?):`,
+			err,
+		);
+	}
+}
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx
index d853bf926d9..8b8b74465b2 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx
@@ -54,9 +54,9 @@ export function OpenInWorkspaceV2({ task }: OpenInWorkspaceV2Props) {
 	const { machineId, activeHostUrl } = useLocalHostService();
 	const { otherHosts } = useWorkspaceHostOptions();
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { submit } = useWorkspaceCreates();
 	const lastProjectId = useV2WorkspaceCreateDefaultsStore(
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx
index 6759919c96a..75843cbaf59 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx
@@ -59,9 +59,9 @@ export function RunInWorkspacePopoverV2({
 	const collections = useCollections();
 	const { machineId, activeHostUrl } = useLocalHostService();
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 	const { otherHosts } = useWorkspaceHostOptions();
 	const { submit } = useWorkspaceCreates();
 
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx
index a05788c30f9..0c877cfed52 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx
@@ -63,9 +63,9 @@ export function RunIssuesInWorkspacePopover({
 	const collections = useCollections();
 	const { machineId, activeHostUrl } = useLocalHostService();
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 	const { otherHosts } = useWorkspaceHostOptions();
 	const { submit } = useWorkspaceCreates();
 
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts
index eb904571c63..6a95ea646b5 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts
@@ -221,9 +221,9 @@ export function useAccessibleV2Workspaces(
 	const collections = useCollections();
 	const { machineId } = useLocalHostService();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 	const currentUserId = session?.user?.id ?? null;
 
 	const { data: rows = [] } = useLiveQuery(
diff --git a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts
index b96c7534db5..6014b9ee911 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts
+++ b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts
@@ -26,9 +26,9 @@ export function useWorkspaceHostOptions(): UseWorkspaceHostOptionsResult {
 	const collections = useCollections();
 	const { machineId, activeHostUrl } = useLocalHostService();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 	const currentUserId = session?.user?.id ?? null;
 
 	const { data: accessibleHosts = [] } = useLiveQuery(
diff --git a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx
index da8399adba2..da6b96ba19d 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx
@@ -32,9 +32,9 @@ export function DashboardNewWorkspaceModalContent({
 	);
 	const collections = useCollections();
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: v2Projects } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx b/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx
index bd292fd0e90..8b127423c10 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx
@@ -27,9 +27,9 @@ export function V1ImportModal() {
 	const close = useCloseV1ImportModal();
 	const { data: session } = authClient.useSession();
 	const { activeHostUrl } = useLocalHostService();
-	const organizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const organizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	if (!organizationId) return null;
 
diff --git a/apps/desktop/src/renderer/routes/_authenticated/layout.tsx b/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
index dbc28401f70..4717948ec01 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
@@ -62,9 +62,9 @@ function AuthenticatedLayout() {
 	const isV2CloudEnabled = useIsV2CloudEnabled();
 
 	const isSignedIn = env.SKIP_ENV_VALIDATION || !!session?.user;
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: session?.session?.activeOrganizationId;
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	useAgentHookListener();
 	useUpdateListener();
diff --git a/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx b/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx
index f5562295086..518fb6b4495 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx
@@ -33,9 +33,9 @@ export function preloadActiveOrganizationCollections(
 export function CollectionsProvider({ children }: { children: ReactNode }) {
 	const { data: session, refetch: refetchSession } = authClient.useSession();
 	const [isSwitching, setIsSwitching] = useState(false);
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: session?.session?.activeOrganizationId;
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const switchOrganization = useCallback(
 		async (organizationId: string) => {
diff --git a/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx b/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx
index 5ef6fdfd5cc..75276559f9d 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx
@@ -31,9 +31,9 @@ export function LocalHostServiceProvider({
 	const { mutate: startHostService } =
 		electronTrpc.hostServiceCoordinator.start.useMutation();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: organizations } = useLiveQuery(
 		(q) => q.from({ organizations: collections.organizations }),
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx
index 0b4567a52e4..5a0c0454b7d 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx
@@ -30,9 +30,9 @@ export function HostsSettingsSidebar({
 	const collections = useCollections();
 	const { data: session } = authClient.useSession();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: hosts = [] } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx
index 643c8e8adbd..3c50905ddd5 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx
@@ -16,9 +16,9 @@ function HostsIndexPage() {
 	const { data: session } = authClient.useSession();
 	const navigate = useNavigate();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: hosts = [] } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx
index c93c0d2e7ad..7f11dda2af9 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx
@@ -25,9 +25,9 @@ function ProjectDetailPage() {
 	const { data: session } = authClient.useSession();
 	const searchQuery = useSettingsSearchQuery();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: v2Match = [] } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx
index ce7d751ecc4..bedd6a8612b 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx
@@ -31,9 +31,9 @@ export function ProjectsSettingsSidebar({
 	const collections = useCollections();
 	const { data: session } = authClient.useSession();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: groups = [] } =
 		electronTrpc.workspaces.getAllGrouped.useQuery();
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx
index 5db0608732d..60605248b49 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx
@@ -17,9 +17,9 @@ function ProjectsIndexPage() {
 	const { data: session } = authClient.useSession();
 	const navigate = useNavigate();
 
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: groups = [] } =
 		electronTrpc.workspaces.getAllGrouped.useQuery();
diff --git a/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx
index fe5b99a03f3..10626d1ce1f 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx
@@ -26,9 +26,9 @@ function OnboardingProjectPage() {
 	const markSkipped = useOnboardingStore((s) => s.markSkipped);
 
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId = env.SKIP_ENV_VALIDATION
-		? MOCK_ORG_ID
-		: (session?.session?.activeOrganizationId ?? null);
+	const activeOrganizationId =
+		session?.session?.activeOrganizationId ??
+		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
 
 	const { data: projects = [], isLoading } = useQuery({
 		queryKey: ["onboarding", "v2Projects", activeOrganizationId],
diff --git a/apps/desktop/src/renderer/routes/sign-in/page.tsx b/apps/desktop/src/renderer/routes/sign-in/page.tsx
index ddfc693a961..aa08c51ad5d 100644
--- a/apps/desktop/src/renderer/routes/sign-in/page.tsx
+++ b/apps/desktop/src/renderer/routes/sign-in/page.tsx
@@ -18,8 +18,8 @@ function SignInPage() {
 	const signInMutation = electronTrpc.auth.signIn.useMutation();
 	const { hasLocalToken, isPending, session } = useSessionRecovery();
 
-	// Dev bypass: skip sign-in entirely
-	if (env.SKIP_ENV_VALIDATION) {
+	// Dev bypass: AuthProvider handles auto-sign-in; if session lands, redirect
+	if (env.SKIP_ENV_VALIDATION && session?.user) {
 		return <Navigate to="/workspace" replace />;
 	}
 
diff --git a/apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx b/apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx
new file mode 100644
index 00000000000..d07f9a35f6a
--- /dev/null
+++ b/apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import { authClient } from "@superset/auth/client";
+import { Button } from "@superset/ui/button";
+import { Input } from "@superset/ui/input";
+import { Label } from "@superset/ui/label";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+
+interface DevAuthFormProps {
+	mode: "sign-in" | "sign-up";
+	callbackURL: string;
+}
+
+export function DevAuthForm({ mode, callbackURL }: DevAuthFormProps) {
+	const router = useRouter();
+	const [email, setEmail] = useState(
+		mode === "sign-up" ? "" : "admin@local.test",
+	);
+	const [password, setPassword] = useState(
+		mode === "sign-up" ? "" : "supersetdev",
+	);
+	const [name, setName] = useState("");
+	const [submitting, setSubmitting] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	const onSubmit = async (e: React.FormEvent) => {
+		e.preventDefault();
+		setSubmitting(true);
+		setError(null);
+
+		try {
+			if (mode === "sign-up") {
+				const res = await authClient.signUp.email({
+					email,
+					password,
+					name: name || email.split("@")[0] || "Dev User",
+				});
+				if (res.error) throw new Error(res.error.message);
+			} else {
+				const res = await authClient.signIn.email({ email, password });
+				if (res.error) throw new Error(res.error.message);
+			}
+			router.push(callbackURL);
+		} catch (err) {
+			const message =
+				err instanceof Error ? err.message : "Authentication failed";
+			setError(message);
+			setSubmitting(false);
+		}
+	};
+
+	return (
+		<form onSubmit={onSubmit} className="grid gap-3 rounded-md border p-4">
+			<p className="text-muted-foreground text-xs">
+				Dev only — email + password auth
+			</p>
+			{mode === "sign-up" && (
+				<div className="grid gap-1.5">
+					<Label htmlFor="name" className="text-xs">
+						Name
+					</Label>
+					<Input
+						id="name"
+						type="text"
+						value={name}
+						onChange={(e) => setName(e.target.value)}
+						placeholder="Optional"
+					/>
+				</div>
+			)}
+			<div className="grid gap-1.5">
+				<Label htmlFor="email" className="text-xs">
+					Email
+				</Label>
+				<Input
+					id="email"
+					type="email"
+					value={email}
+					onChange={(e) => setEmail(e.target.value)}
+					required
+				/>
+			</div>
+			<div className="grid gap-1.5">
+				<Label htmlFor="password" className="text-xs">
+					Password
+				</Label>
+				<Input
+					id="password"
+					type="password"
+					value={password}
+					onChange={(e) => setPassword(e.target.value)}
+					required
+					minLength={8}
+				/>
+			</div>
+			{error && <p className="text-destructive text-xs">{error}</p>}
+			<Button type="submit" disabled={submitting} className="w-full">
+				{submitting ? "..." : mode === "sign-up" ? "Create account" : "Sign in"}
+			</Button>
+		</form>
+	);
+}
diff --git a/apps/web/src/app/(auth)/components/DevAuthForm/index.ts b/apps/web/src/app/(auth)/components/DevAuthForm/index.ts
new file mode 100644
index 00000000000..eddbcfa938b
--- /dev/null
+++ b/apps/web/src/app/(auth)/components/DevAuthForm/index.ts
@@ -0,0 +1 @@
+export { DevAuthForm } from "./DevAuthForm";
diff --git a/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx b/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
index b27142e33f0..63049a01b27 100644
--- a/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
+++ b/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
@@ -8,6 +8,9 @@ import { useState } from "react";
 import { FaGithub } from "react-icons/fa";
 import { FcGoogle } from "react-icons/fc";
 import { env } from "@/env";
+import { DevAuthForm } from "../../components/DevAuthForm";
+
+const isDev = process.env.NODE_ENV !== "production";
 
 export default function SignInPage() {
 	const searchParams = useSearchParams();
@@ -66,6 +69,7 @@ export default function SignInPage() {
 				{error && (
 					<p className="text-destructive text-center text-sm">{error}</p>
 				)}
+				{isDev && <DevAuthForm mode="sign-in" callbackURL={callbackURL} />}
 				<Button
 					variant="outline"
 					disabled={isLoading}
diff --git a/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx b/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
index dd9b579cd65..66a2e56b728 100644
--- a/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
+++ b/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
@@ -7,6 +7,9 @@ import { useState } from "react";
 import { FaGithub } from "react-icons/fa";
 import { FcGoogle } from "react-icons/fc";
 import { env } from "@/env";
+import { DevAuthForm } from "../../components/DevAuthForm";
+
+const isDev = process.env.NODE_ENV !== "production";
 
 export default function SignUpPage() {
 	const [isLoadingGoogle, setIsLoadingGoogle] = useState(false);
@@ -61,6 +64,9 @@ export default function SignUpPage() {
 				{error && (
 					<p className="text-destructive text-center text-sm">{error}</p>
 				)}
+				{isDev && (
+					<DevAuthForm mode="sign-up" callbackURL={env.NEXT_PUBLIC_WEB_URL} />
+				)}
 				<Button
 					variant="outline"
 					disabled={isLoading}
diff --git a/bun.lock b/bun.lock
index 5afc118e3d4..51cbdaf12ca 100644
--- a/bun.lock
+++ b/bun.lock
@@ -111,7 +111,7 @@
     },
     "apps/desktop": {
       "name": "@superset/desktop",
-      "version": "1.9.1",
+      "version": "1.9.6",
       "dependencies": {
         "@ai-sdk/anthropic": "3.0.64",
         "@ai-sdk/openai": "3.0.36",
@@ -729,11 +729,13 @@
         "@t3-oss/env-core": "0.13.11",
         "dotenv": "17.3.1",
         "drizzle-orm": "0.45.2",
+        "pg": "8.20.0",
         "zod": "4.3.6",
       },
       "devDependencies": {
         "@superset/typescript": "workspace:*",
         "@types/node": "24.12.0",
+        "@types/pg": "8.20.0",
         "bun-types": "1.3.11",
         "drizzle-kit": "0.31.8",
         "typescript": "5.9.3",
@@ -767,7 +769,7 @@
     },
     "packages/host-service": {
       "name": "@superset/host-service",
-      "version": "0.8.3",
+      "version": "0.8.6",
       "dependencies": {
         "@hono/node-server": "1.19.13",
         "@hono/node-ws": "1.3.0",
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
new file mode 100644
index 00000000000..02c67f8cee8
--- /dev/null
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -0,0 +1,154 @@
+# Local Development
+
+How to run Superset locally from a fresh clone, with no Neon / OAuth / Stripe / Resend keys required. The dev path auto-creates a local admin user, runs Postgres in Docker, and signs you in before the desktop window opens.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) 1.3+
+- Docker (for Postgres and Electric SQL)
+- [Caddy](https://caddyserver.com/docs/install) (for HTTPS proxy)
+- macOS or Linux
+
+## One-time setup
+
+```bash
+git clone https://github.com/superset-sh/superset.git
+cd superset
+bun install
+```
+
+**1. Start Postgres**
+
+```bash
+docker run -d --name superset-pg \
+  -e POSTGRES_USER=superset \
+  -e POSTGRES_PASSWORD=superset \
+  -e POSTGRES_DB=superset \
+  -p 5433:5432 \
+  postgres:16 -c wal_level=logical
+```
+
+Port `5433` avoids clobbering a host Postgres on the default `5432`. `wal_level=logical` is required for Electric SQL replication.
+
+**2. Create your `.env`**
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env` so it has at minimum:
+
+```bash
+DATABASE_URL=postgres://superset:superset@localhost:5433/superset
+DATABASE_URL_UNPOOLED=postgres://superset:superset@localhost:5433/superset
+BETTER_AUTH_SECRET=dev_secret_$(openssl rand -hex 24)
+```
+
+Everything else can stay blank. The app degrades cleanly when integration keys (Stripe, Resend, GitHub App, etc.) are missing — features that need them will throw a clean "X not configured" error when you actually exercise them; nothing crashes at boot.
+
+**3. Apply the schema**
+
+```bash
+bun run db:migrate
+```
+
+This creates the `auth` and `public` schemas and runs all Drizzle migrations. ~42 tables.
+
+**4. Set up Caddy (HTTPS proxy)**
+
+```bash
+cp Caddyfile.example Caddyfile
+caddy trust   # one-time, prompts for sudo
+```
+
+Without `caddy trust`, Chromium will reject `https://localhost:*` with `ERR_CERT_AUTHORITY_INVALID`.
+
+## Run it
+
+```bash
+SKIP_ENV_VALIDATION=1 bun dev
+```
+
+That brings up:
+
+| Service | Port | What it does |
+|---|---|---|
+| Web | 4640 | Marketing-style sign-in page |
+| API | 4641 | Backend (Next.js) |
+| Desktop (Vite) | 4645 | Renderer dev server |
+| Notifications | 4646 | Desktop notification bridge |
+| Electric SQL | 4649 | Sync layer (Docker) |
+| Caddy | 4650 | HTTPS proxy in front of electric-proxy |
+| electric-proxy | 4652 | Cloudflare worker (Wrangler) |
+
+The Electron window opens automatically.
+
+### How sign-in works
+
+On first launch in dev mode (`SKIP_ENV_VALIDATION=1`), the desktop main process auto-signs you in as a seed admin user:
+
+- **Email:** `admin@local.test`
+- **Password:** `supersetdev`
+
+If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in `superset-dev-data/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
+
+For the web app (`http://localhost:4640`), the sign-in and sign-up pages render a dev-only email/password form when `NODE_ENV !== "production"`. Use the same credentials.
+
+## Why `SKIP_ENV_VALIDATION=1`?
+
+`apps/api/src/env.ts` currently declares many integration keys (`STRIPE_*`, `RESEND_API_KEY`, `GH_APP_*`, etc.) as required strings via `@t3-oss/env-nextjs`. Until those are marked optional, the env validator rejects empty values at boot. `SKIP_ENV_VALIDATION=1` is the upstream escape hatch — propagated via `turbo.jsonc`'s `globalPassThroughEnv` so it reaches every subtask.
+
+## What works in OSS mode
+
+✓ Sign-in (email/password)
+✓ Database (Postgres + Drizzle)
+✓ Electric SQL sync
+✓ Host service (local git/worktree operations)
+✓ Create workspaces, run terminals, edit files
+✓ tRPC / API routing
+
+## What's stubbed (won't fully work without keys)
+
+- **Billing** — Stripe lazy-throws if exercised. Subscriptions/checkout disabled.
+- **Email send** — Resend lazy-throws. Magic-link / password reset emails are stubbed.
+- **Telemetry** — PostHog initializes only when key present; calls are no-ops otherwise.
+- **Error tracking** — Sentry initializes only when DSN present.
+- **OAuth (Google, GitHub)** — providers register only when their `*_CLIENT_ID` is set.
+- **GitHub App / Linear / Slack** — webhooks and integrations no-op without their keys.
+- **QStash background jobs** — no key → no scheduled jobs fire.
+- **Upstash KV rate limiting** — falls back gracefully.
+
+Each is "guard, don't crash" — if you click into a feature that needs a key, you'll see a `503` or a clean exception, not a boot failure.
+
+## Troubleshooting
+
+**`EADDRINUSE: address already in use :::4641`** — a previous `bun dev` is still alive. `pkill -f "turbo run dev"` and retry.
+
+**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `superset-dev-data/auth-token.enc` exists. Delete it and rerun if needed: `rm superset-dev-data/auth-token.enc && SKIP_ENV_VALIDATION=1 bun dev`.
+
+**`Missing API key` for some integration** — that integration's key isn't in `.env`. Either supply it or avoid the feature.
+
+**Electric SQL container fails to start replication** — verify `wal_level=logical` on your Postgres: `docker exec superset-pg psql -U superset -d superset -c "SHOW wal_level"` should return `logical`.
+
+**`schema "auth" already exists` during `db:migrate`** — drop and re-migrate: `docker exec superset-pg psql -U superset -d superset -c "DROP SCHEMA auth CASCADE"` then `bun run db:migrate`.
+
+## Resetting state
+
+```bash
+# Stop dev
+pkill -f "turbo run dev"
+
+# Wipe data (auth token, host DBs, local app state)
+rm -rf superset-dev-data
+
+# Wipe Postgres
+docker rm -f superset-pg
+# then re-run the docker run from step 1
+```
+
+## Architecture notes for contributors
+
+- **DB driver swap** — `packages/db/src/client.ts` detects whether `DATABASE_URL` is a Neon host (`*.neon.tech`, `*.neon.build`) and uses Drizzle's `neon-http` adapter for cloud, or `node-postgres` for any other Postgres (including the local Docker one).
+- **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()`. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
+- **Renderer organization selection** — pages prefer `session.activeOrganizationId` from Better Auth, falling back to `MOCK_ORG_ID` only if there's no session at all. Make sure new code that needs `activeOrganizationId` follows this same priority (real session first).
+- **CDP for headless tests** — when `SKIP_ENV_VALIDATION=1`, the desktop main process exposes Chrome DevTools Protocol on `localhost:9333`. Useful for scripted UI checks (`curl http://localhost:9333/json/list`).
diff --git a/package.json b/package.json
index 7bb54007705..10af6f4dcc6 100644
--- a/package.json
+++ b/package.json
@@ -38,6 +38,7 @@
 		"release:canary": "./scripts/release-canary.sh",
 		"db:push": "bun run --cwd packages/db push",
 		"db:migrate": "bun run --cwd packages/db migrate",
+		"db:seed:dev": "bun run --cwd packages/db seed:dev",
 		"db:generate:desktop": "bun run --cwd packages/local-db generate"
 	},
 	"type": "module",
diff --git a/packages/auth/src/lib/resend.ts b/packages/auth/src/lib/resend.ts
index e17addc2635..fcdc09ae6c8 100644
--- a/packages/auth/src/lib/resend.ts
+++ b/packages/auth/src/lib/resend.ts
@@ -2,4 +2,56 @@ import { Resend } from "resend";
 
 import { env } from "../env";
 
-export const resend = new Resend(env.RESEND_API_KEY);
+let client: Resend | null = null;
+
+function getResend(): Resend {
+	if (client) return client;
+	if (!env.RESEND_API_KEY) {
+		throw new Error(
+			"Resend not configured — set RESEND_API_KEY (or use Mailpit/console for local dev)",
+		);
+	}
+	client = new Resend(env.RESEND_API_KEY);
+	return client;
+}
+
+interface CapturedEmail {
+	to: unknown;
+	subject?: unknown;
+}
+
+function logConsoleSend(arg: unknown) {
+	if (Array.isArray(arg)) {
+		for (const e of arg as CapturedEmail[]) {
+			console.log(
+				`[email:console] to=${String(e.to)} subject=${String(e.subject ?? "(no subject)")}`,
+			);
+		}
+	} else if (arg && typeof arg === "object") {
+		const e = arg as CapturedEmail;
+		console.log(
+			`[email:console] to=${String(e.to)} subject=${String(e.subject ?? "(no subject)")}`,
+		);
+	}
+	return Promise.resolve({ data: { id: "console-dev" }, error: null });
+}
+
+// Lazy proxy over the full Resend surface. Throws only when actually used
+// without a key — except `emails.send` and `batch.send`, which fall back to
+// logging to stdout so Better Auth's signup/verification flows work in dev.
+export const resend = new Proxy({} as Resend, {
+	get(_t, prop) {
+		if (!env.RESEND_API_KEY) {
+			if (prop === "emails") {
+				return { send: (arg: unknown) => logConsoleSend(arg) };
+			}
+			if (prop === "batch") {
+				return { send: (arg: unknown) => logConsoleSend(arg) };
+			}
+			throw new Error(
+				`Resend not configured — set RESEND_API_KEY (accessed property: ${String(prop)})`,
+			);
+		}
+		return Reflect.get(getResend(), prop);
+	},
+});
diff --git a/packages/auth/src/server.ts b/packages/auth/src/server.ts
index d3171ffcc06..c24de12b7bc 100644
--- a/packages/auth/src/server.ts
+++ b/packages/auth/src/server.ts
@@ -89,6 +89,10 @@ export const auth = betterAuth({
 			generateId: false,
 		},
 	},
+	emailAndPassword: {
+		enabled: true,
+		autoSignIn: true,
+	},
 	socialProviders: {
 		github: {
 			clientId: env.GH_CLIENT_ID,
diff --git a/packages/auth/src/stripe.ts b/packages/auth/src/stripe.ts
index d238bd34fd5..3dc7d06b9a7 100644
--- a/packages/auth/src/stripe.ts
+++ b/packages/auth/src/stripe.ts
@@ -1,4 +1,18 @@
 import Stripe from "stripe";
 import { env } from "./env";
 
-export const stripeClient = new Stripe(env.STRIPE_SECRET_KEY);
+let client: Stripe | null = null;
+
+export const stripeClient = new Proxy({} as Stripe, {
+	get(_target, prop) {
+		if (!client) {
+			if (!env.STRIPE_SECRET_KEY) {
+				throw new Error(
+					"Stripe not configured — set STRIPE_SECRET_KEY (billing disabled in local dev)",
+				);
+			}
+			client = new Stripe(env.STRIPE_SECRET_KEY);
+		}
+		return Reflect.get(client, prop);
+	},
+});
diff --git a/packages/db/package.json b/packages/db/package.json
index e18f843e39e..5b59660c4fe 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -37,6 +37,7 @@
 		"clean": "git clean -xdf .cache .turbo dist node_modules",
 		"push": "drizzle-kit push",
 		"migrate": "drizzle-kit migrate",
+		"seed:dev": "bun run src/seed-dev.ts",
 		"studio": "drizzle-kit studio",
 		"typecheck": "tsc --noEmit --emitDeclarationOnly false"
 	},
@@ -46,11 +47,13 @@
 		"@t3-oss/env-core": "0.13.11",
 		"dotenv": "17.3.1",
 		"drizzle-orm": "0.45.2",
+		"pg": "8.20.0",
 		"zod": "4.3.6"
 	},
 	"devDependencies": {
 		"@superset/typescript": "workspace:*",
 		"@types/node": "24.12.0",
+		"@types/pg": "8.20.0",
 		"bun-types": "1.3.11",
 		"drizzle-kit": "0.31.8",
 		"typescript": "5.9.3"
diff --git a/packages/db/src/client.ts b/packages/db/src/client.ts
index 8fd403619d6..4c3ef0a55be 100644
--- a/packages/db/src/client.ts
+++ b/packages/db/src/client.ts
@@ -1,23 +1,43 @@
-import { neon, Pool } from "@neondatabase/serverless";
+import { Pool as NeonPool, neon } from "@neondatabase/serverless";
 import { config } from "dotenv";
-import { drizzle } from "drizzle-orm/neon-http";
-import { drizzle as drizzleWs } from "drizzle-orm/neon-serverless";
+import { drizzle as drizzleNeonHttp } from "drizzle-orm/neon-http";
+import { drizzle as drizzleNeonWs } from "drizzle-orm/neon-serverless";
+import { drizzle as drizzleNodePg } from "drizzle-orm/node-postgres";
+import pg from "pg";
 
 import { env } from "./env";
 import * as schema from "./schema";
 
 config({ path: ".env", quiet: true });
 
-const sql = neon(env.DATABASE_URL);
+const isNeon = /\.neon\.tech|neon\.build/.test(env.DATABASE_URL);
 
-export const db = drizzle({
-	client: sql,
-	schema,
-	casing: "snake_case",
-});
+// Single canonical type — both adapters expose the same Drizzle PG surface at
+// runtime, so we narrow callers to the Neon-HTTP shape (the production path)
+// and cast the local-Postgres branch through it.
+type Db = ReturnType<typeof drizzleNeonHttp<typeof schema>>;
+type DbWs = ReturnType<typeof drizzleNeonWs<typeof schema>>;
 
-export const dbWs = drizzleWs({
-	client: new Pool({ connectionString: env.DATABASE_URL }),
-	schema,
-	casing: "snake_case",
-});
+export const db: Db = isNeon
+	? drizzleNeonHttp({
+			client: neon(env.DATABASE_URL),
+			schema,
+			casing: "snake_case",
+		})
+	: (drizzleNodePg({
+			client: new pg.Pool({ connectionString: env.DATABASE_URL }),
+			schema,
+			casing: "snake_case",
+		}) as unknown as Db);
+
+export const dbWs: DbWs = isNeon
+	? drizzleNeonWs({
+			client: new NeonPool({ connectionString: env.DATABASE_URL }),
+			schema,
+			casing: "snake_case",
+		})
+	: (drizzleNodePg({
+			client: new pg.Pool({ connectionString: env.DATABASE_URL }),
+			schema,
+			casing: "snake_case",
+		}) as unknown as DbWs);
diff --git a/packages/db/src/seed-dev.ts b/packages/db/src/seed-dev.ts
new file mode 100644
index 00000000000..a003b79415f
--- /dev/null
+++ b/packages/db/src/seed-dev.ts
@@ -0,0 +1,73 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "dotenv";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+config({ path: path.resolve(__dirname, "../../../.env"), quiet: true });
+
+const DEV_ADMIN_EMAIL = "admin@local.test";
+const DEV_ADMIN_PASSWORD = "supersetdev";
+const DEV_ADMIN_NAME = "Local Admin";
+
+async function main() {
+	if (process.env.NODE_ENV === "production") {
+		console.error("FATAL: db:seed refuses to run in production");
+		process.exit(1);
+	}
+
+	const dbUrl = process.env.DATABASE_URL;
+	if (!dbUrl) {
+		console.error("FATAL: DATABASE_URL not set");
+		process.exit(1);
+	}
+
+	const url = new URL(dbUrl);
+	const allowedHosts = new Set(["localhost", "127.0.0.1", "::1"]);
+	if (!allowedHosts.has(url.hostname)) {
+		console.error(
+			`FATAL: db:seed refuses to run against non-localhost host: ${url.hostname}`,
+		);
+		process.exit(1);
+	}
+
+	const apiUrl = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4641";
+	const endpoint = `${apiUrl}/api/auth/sign-up/email`;
+
+	console.log(`Seeding dev admin via ${endpoint}`);
+
+	const res = await fetch(endpoint, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			email: DEV_ADMIN_EMAIL,
+			password: DEV_ADMIN_PASSWORD,
+			name: DEV_ADMIN_NAME,
+		}),
+	}).catch((err) => {
+		console.error(`FATAL: could not reach ${apiUrl} — is the API running?`);
+		console.error(err.message);
+		process.exit(1);
+	});
+
+	if (res.status === 200) {
+		console.log(`✓ Created ${DEV_ADMIN_EMAIL} / ${DEV_ADMIN_PASSWORD}`);
+		return;
+	}
+
+	const body = (await res.json().catch(() => ({}))) as {
+		code?: string;
+		message?: string;
+	};
+
+	if (body.code === "USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL") {
+		console.log(
+			`✓ ${DEV_ADMIN_EMAIL} already exists (password: ${DEV_ADMIN_PASSWORD})`,
+		);
+		return;
+	}
+
+	console.error(`FATAL: sign-up returned ${res.status}: ${body.message ?? ""}`);
+	process.exit(1);
+}
+
+main();
diff --git a/packages/trpc/src/lib/analytics.ts b/packages/trpc/src/lib/analytics.ts
index a06694f753d..d1d1c6213dd 100644
--- a/packages/trpc/src/lib/analytics.ts
+++ b/packages/trpc/src/lib/analytics.ts
@@ -1,11 +1,35 @@
 import { PostHog } from "posthog-node";
 import { env } from "../env";
 
+let client: PostHog | null = null;
+
+// Disabled stub — accepts any args, returns the right shape for each method.
+const disabled = {
+	capture: (..._args: unknown[]) => {},
+	identify: (..._args: unknown[]) => {},
+	alias: (..._args: unknown[]) => {},
+	groupIdentify: (..._args: unknown[]) => {},
+	shutdown: (..._args: unknown[]) => Promise.resolve(),
+	flush: (..._args: unknown[]) => Promise.resolve(),
+	getFeatureFlag: (..._args: unknown[]) => Promise.resolve(undefined),
+	getFeatureFlagPayload: (..._args: unknown[]) => Promise.resolve(undefined),
+	isFeatureEnabled: (..._args: unknown[]) => Promise.resolve(undefined),
+} as unknown as PostHog;
+
 // Singleton — all server-side product event captures go through this client.
+// Lazy-init so a missing NEXT_PUBLIC_POSTHOG_KEY doesn't crash module load.
 // flushAt: 1, flushInterval: 0 mirrors apps/api/src/lib/analytics.ts so we
 // don't lose events on short-lived processes (Vercel functions, edge handlers).
-export const posthog = new PostHog(env.NEXT_PUBLIC_POSTHOG_KEY, {
-	host: env.NEXT_PUBLIC_POSTHOG_HOST,
-	flushAt: 1,
-	flushInterval: 0,
+export const posthog = new Proxy({} as PostHog, {
+	get(_target, prop) {
+		if (!env.NEXT_PUBLIC_POSTHOG_KEY) return Reflect.get(disabled, prop);
+		if (!client) {
+			client = new PostHog(env.NEXT_PUBLIC_POSTHOG_KEY, {
+				host: env.NEXT_PUBLIC_POSTHOG_HOST,
+				flushAt: 1,
+				flushInterval: 0,
+			});
+		}
+		return Reflect.get(client, prop);
+	},
 });
diff --git a/packages/trpc/src/router/support/support.ts b/packages/trpc/src/router/support/support.ts
index ed2e4062ea7..d4ffbe8573f 100644
--- a/packages/trpc/src/router/support/support.ts
+++ b/packages/trpc/src/router/support/support.ts
@@ -9,7 +9,24 @@ import { z } from "zod";
 import { env } from "../../env";
 import { createTRPCRouter, protectedProcedure } from "../../trpc";
 
-const resend = new Resend(env.RESEND_API_KEY);
+let resendClient: Resend | null = null;
+function getResend(): Resend {
+	if (!resendClient) {
+		if (!env.RESEND_API_KEY) {
+			throw new TRPCError({
+				code: "SERVICE_UNAVAILABLE",
+				message: "Email not configured — set RESEND_API_KEY",
+			});
+		}
+		resendClient = new Resend(env.RESEND_API_KEY);
+	}
+	return resendClient;
+}
+const resend = new Proxy({} as Resend, {
+	get(_t, p) {
+		return Reflect.get(getResend(), p);
+	},
+});
 const SUPPORT_EMAIL = COMPANY.MAIL_TO.replace(/^mailto:/, "");
 const supportReportRateLimit =
 	env.KV_REST_API_URL && env.KV_REST_API_TOKEN
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
new file mode 100644
index 00000000000..5db24a0b82a
--- /dev/null
+++ b/plans/20260515-oss-local-setup.md
@@ -0,0 +1,119 @@
+# OSS Local Setup — What Shipped + What's Left
+
+This was originally a forward-looking plan; now it's a record of what was actually built, verified, and what's still loose. Contributor-facing setup instructions live in `docs/LOCAL_DEVELOPMENT.md`.
+
+## Status
+
+A fresh-clone contributor can:
+
+1. `git clone … && cd superset && bun install`
+2. Start a local Postgres container with `wal_level=logical` on host port 5433
+3. Run `bun run db:migrate` to apply schema
+4. `SKIP_ENV_VALIDATION=1 bun dev`
+
+…and have a working web + API + Electric + electric-proxy + Caddy + desktop stack, signed in as a seed admin, with the host-service spawned and reachable. **Verified end-to-end via CDP** (Chrome DevTools Protocol probing the Electron renderer at port 9333) — the React context for `LocalHostServiceContext` reports `activeHostUrl: "http://127.0.0.1:<port>"`, so the "Host service not available" gate is open.
+
+## What was built (with file paths)
+
+### Database
+
+- **`packages/db/src/client.ts`** — driver swap: detects non-Neon `DATABASE_URL` and uses Drizzle's `node-postgres` adapter via `pg.Pool` instead of `@neondatabase/serverless`. ~20 LOC.
+- **`packages/db/package.json`** — adds `pg` + `@types/pg`.
+- **`drizzle-kit migrate`** is the right command against a fresh DB. `drizzle-kit push` has multi-schema ordering issues against a vanilla Postgres; `migrate` applies committed `.sql` files in order and just works.
+
+### Auth
+
+- **`packages/auth/src/server.ts`** — added `emailAndPassword: { enabled: true, autoSignIn: true }`. OAuth providers (Google, GitHub) still register conditionally based on their `*_CLIENT_ID` env vars; Better Auth itself logs a warning when those are missing — no crash.
+- **`packages/auth/src/lib/resend.ts`** — lazy-init + console-log fallback when `RESEND_API_KEY` is empty. Better Auth's `sendEmail` hook calls this; in dev with no key, emails are logged to the terminal.
+- **`packages/auth/src/stripe.ts`** — `Proxy` lazy-init; throws "Stripe not configured" only if a billing operation is actually exercised.
+
+### Telemetry / analytics
+
+- **`apps/api/src/lib/analytics.ts`** + **`packages/trpc/src/lib/analytics.ts`** — PostHog `Proxy` lazy-init; returns a no-op surface (`capture`, `getFeatureFlag`, etc. all no-op) when `NEXT_PUBLIC_POSTHOG_KEY` is empty. Previously crashed at module load.
+
+### Other lazy-init guards
+
+- **`packages/trpc/src/router/support/support.ts`** — Resend `Proxy` lazy-init.
+
+### Dev auto-sign-in (the cleanest part)
+
+- **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — new file. During `app.whenReady()`, if `SKIP_ENV_VALIDATION` is set and no token is on disk, POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if needed), then calls `saveToken()` to write `auth-token.enc`. The renderer's `AuthProvider` is **untouched** — it hydrates from disk like a real OAuth user.
+- **`apps/desktop/src/main/index.ts`** — calls `ensureDevAuthToken()` after `app.whenReady()`, before host-service discovery. Also enables Chrome DevTools Protocol on `localhost:9333` in dev for headless testing.
+- **`packages/db/src/seed-dev.ts`** — `bun db:seed:dev` script. POSTs to the API to create `admin@local.test / supersetdev`. Refuses to run if `NODE_ENV === "production"` or `DATABASE_URL` hostname isn't localhost. Idempotent.
+
+### Renderer org-id priority fix (the actual host-service bug)
+
+- 16 files under `apps/desktop/src/renderer/routes/_authenticated/`, plus `routes/sign-in/page.tsx`. The original pattern was `env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : session.activeOrganizationId`, which forced the renderer to use a fake org ID even when a real session was present. With dev auto-sign-in producing a real session, the renderer was looking up the host-service by `MOCK_ORG_ID` while the host-service had spawned for the real org — connection lookup returned undefined, "Host service not available" toast fired.
+- Flipped to `session.activeOrganizationId ?? (SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null)` — prefer real session, fall back to mock only without one. Verified via CDP that `activeHostUrl` is now populated.
+
+### Dev UI
+
+- **`apps/web/src/app/(auth)/components/DevAuthForm/`** — email/password form rendered on the web app's sign-in and sign-up pages, gated `process.env.NODE_ENV !== "production"`. Prefilled with the seed credentials. Same `authClient.signIn.email` underneath.
+- **`apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx`** + **`sign-up/[[...sign-up]]/page.tsx`** — wire the form.
+
+### Plumbing
+
+- **`turbo.jsonc`** — added `SKIP_ENV_VALIDATION` to `globalPassThroughEnv` so the flag reaches every dev subtask.
+- **`package.json`** — added `bun db:seed:dev` root script.
+
+### Production safety
+
+- The dev auto-sign-in module checks `mainEnv.SKIP_ENV_VALIDATION` (which is itself gated to `NODE_ENV === "development"` in `apps/desktop/src/main/env.main.ts`). It cannot run in a production build.
+- `db:seed:dev` refuses to run against non-localhost DBs and in production.
+- The DevAuthForm only renders when `NODE_ENV !== "production"`.
+- The Chrome DevTools Protocol port (9333) only opens when both `IS_DEV` and `SKIP_ENV_VALIDATION` are set.
+
+## What's NOT built (originally in plan, deferred)
+
+These were in the original plan but aren't necessary for "fresh clone boots" and were left for follow-up:
+
+- **`docker-compose.dev.yml`** — currently contributors run a one-liner `docker run`. A compose file with Postgres + Mailpit would be nicer; for now, the README's short instructions are enough.
+- **`.env.example` rewrite with working defaults** — `.env.example` is still mostly blank. The docs tell contributors to set just `DATABASE_URL` and `BETTER_AUTH_SECRET`.
+- **`bun setup` orchestrator** — the discrete steps (`docker run`, `bun install`, `bun run db:migrate`, `bun dev`) are still manual. Wrapping them in `bun setup` would be a small ergonomics win.
+- **Making integration env vars `.optional()` in `apps/api/src/env.ts`** — the reason `SKIP_ENV_VALIDATION=1` is still required. Mechanical change: ~25 `.string()` → `.string().optional()`. Once done, the flag goes away.
+- **Production startup hardening** — the plan called for `apps/api/src/env-check.ts` that hard-fails in prod on any missing required key. Not built. Today, prod relies on the existing `@t3-oss/env-nextjs` strictness (which works fine when those keys aren't `.optional()`).
+- **Sentinel-string detection for `BETTER_AUTH_SECRET`** — not built. Today, contributors generate their own secret via `openssl rand -hex 24`.
+- **CI fresh-clone smoke test** — not built. Without it, the OSS path can rot silently if someone adds a new crash-on-import integration.
+- **Email provider abstraction (Mailpit fallback)** — Better Auth's `sendEmail` hook currently just `console.log`s emails when no `RESEND_API_KEY` is present. Mailpit container would be nicer UX (clickable links in a web UI) but isn't blocking.
+- **Local-disk Blob storage fallback** — not built. Upload features that need `BLOB_READ_WRITE_TOKEN` will throw.
+- **In-memory rate-limit fallback** — not built. Upstash KV is already handled gracefully by the SDK (logs warnings on missing keys).
+
+## What was learned vs. the original plan
+
+- **`neondatabase/neon_local` is not a Neon protocol emulator.** It requires `NEON_PROJECT_ID` + `NEON_API_KEY` and proxies to a real Neon project. Useless for OSS. Plain `postgres:16 -c wal_level=logical` is the right substrate, with the driver swap above.
+- **`@neondatabase/serverless` cannot speak vanilla Postgres TCP.** The driver swap is unavoidable — it's not a config flag.
+- **Most integrations degrade gracefully on their own.** Better Auth social providers, Upstash KV, QStash all log warnings when their env vars are missing and keep working. Only a handful crash at import: Resend, Stripe, PostHog, GitHub App in some paths. Plan's "guard a dozen integrations" overestimated; reality was 3-4.
+- **The right place for dev auto-sign-in is the main process, not the renderer.** Initial attempt put it in the renderer's `AuthProvider`, which mixed dev seed concerns with prod auth hydration. Moving it to a `app.whenReady()` hook (where token encryption already lives) leaves `AuthProvider` 100% upstream-pure and gives a much cleaner failure mode.
+- **The renderer had a dev-mode landmine:** 16 places overrode `activeOrganizationId` to `MOCK_ORG_ID` when `SKIP_ENV_VALIDATION` was set. That was a legacy hack from before there was a real dev session. The real fix isn't extra dev logic — it's flipping the priority to prefer whichever session is present. New code that needs `activeOrganizationId` should follow this same pattern.
+
+## Architecture summary
+
+```
+Contributor's machine
+├─ Docker
+│  ├─ superset-pg            postgres:16, port 5433, wal_level=logical
+│  └─ superset-electric-…    electricsql/electric:1.4.13, port 4649
+│                            (replicates from superset-pg via host.docker.internal)
+└─ SKIP_ENV_VALIDATION=1 bun dev
+   ├─ apps/web               :4640   (Next.js, dev-only email+password form)
+   ├─ apps/api               :4641   (Next.js, Better Auth + tRPC)
+   ├─ apps/desktop (Electron):4645   (Vite renderer + Electron main)
+   │  ├─ main process boots
+   │  ├─ ensureDevAuthToken() POSTs sign-in to :4641 → saveToken()
+   │  ├─ host-service spawns per-org on a dynamic port (e.g. 59728)
+   │  └─ renderer hydrates from auth-token.enc, looks up activeHostUrl
+   ├─ electric-proxy (Wrangler) :4652
+   └─ Caddy HTTPS proxy      :4650 → electric-proxy (HTTP/2 for SSE)
+```
+
+## Verification protocol
+
+CDP probe to confirm the host-service connection is live:
+
+```bash
+curl -sS http://localhost:9333/json/list | jq '.[] | select(.type=="page") | .webSocketDebuggerUrl'
+# Connect via WS, eval:
+#   walkFibersForContextValue() → { activeHostUrl: "http://127.0.0.1:<port>", machineId: "…" }
+```
+
+Concrete script lives in tmp scripts (`/tmp/cdp-find-hosturl.mjs`) used during development.
diff --git a/turbo.jsonc b/turbo.jsonc
index 30843360054..9af58bdaebd 100644
--- a/turbo.jsonc
+++ b/turbo.jsonc
@@ -25,7 +25,8 @@
 		"VERCEL",
 		"VERCEL_ENV",
 		"VERCEL_URL",
-		"npm_lifecycle_event"
+		"npm_lifecycle_event",
+		"SKIP_ENV_VALIDATION"
 	],
 	"tasks": {
 		"build": {

From 2b609b5526ca50b296866ef930a33c8c182f752f Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sat, 16 May 2026 14:23:50 -0700
Subject: [PATCH 02/28] =?UTF-8?q?feat:=20deployment=20profiles=20=E2=80=94?=
 =?UTF-8?q?=20OSS=20lenient,=20internal-dev/cloud=20strict?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three profiles reconciled in one schema-aware design — OSS contributors
boot without keys, internal devs and prod keep their fail-fast workflow.

## Profile resolution (`packages/shared/src/deployment-profile.ts`)

Ranked by discriminator trust:

  cloud         VERCEL=1                       (set by Vercel; untypable)
  internal-dev  SUPERSET_INTERNAL_DEV=1        (written by .superset/setup.sh)
  self-hosted   NODE_ENV=production            (Docker / bare metal)
  oss-dev       default                        (fresh clone)

Strict (cloud / internal-dev / self-hosted) hard-fail boot on any missing
integration key — same fail-fast internal devs and prod rely on today.
Lenient (oss-dev) skips validation so the app boots; lazy guards at
call-sites turn missing keys into clean throws when features are exercised.

The `SUPERSET_INTERNAL_DEV=1` discriminator is positive-presence and
written only by `.superset/setup.sh` `step_write_env` — never in
.env.example, never in docs. A contributor can't trip it accidentally.

## Wired into each env schema

apps/api, apps/web, apps/admin, apps/marketing, apps/docs, apps/relay,
apps/desktop/src/main/env.main, packages/trpc — all compute:

  const skipValidation =
    !isStrictProfile(getDeploymentProfile()) ||
    !!process.env.SKIP_ENV_VALIDATION;

SKIP_ENV_VALIDATION=1 remains a build-time escape hatch (Docker preview
builds, CI), not the primary discriminator.

## Visibility

- `apps/api/src/lib/boot-summary.ts` — one-time API startup log listing
  disabled features and the env var to set:

    [superset] profile=oss-dev (lenient)
    [superset] disabled features (set the listed env var to enable):
               - stripe                       STRIPE_SECRET_KEY
               - resend (email)               RESEND_API_KEY
               ...

- `apps/api/src/app/api/health/route.ts` — `GET /api/health` returns
  `{ profile, integrations: { stripe: "configured" | "missing", ... } }`
  for prod monitoring + contributor sanity checks.

## Other changes

- `apps/desktop/src/main/lib/dev-auto-sign-in.ts` + main/index.ts CDP
  gate now check `getDeploymentProfile() === "oss-dev"` instead of
  `SKIP_ENV_VALIDATION`. OSS contributors no longer need to set any flag.
- `.superset/lib/setup/steps.sh step_write_env` writes
  SUPERSET_INTERNAL_DEV=1 so internal workspaces auto-opt into strict.
- Docs (LOCAL_DEVELOPMENT.md, plans/20260515-oss-local-setup.md) updated
  to drop the SKIP_ENV_VALIDATION requirement and document the profile
  model + boot summary + health endpoint.

## Verified end-to-end

oss-dev: `bun dev` (no flag) → boots cleanly, prints disabled features,
`/api/health` returns `"profile": "oss-dev"`, dev auto-sign-in fires,
host-service spawns, desktop renderer's activeHostUrl populates.

internal-dev: `SUPERSET_INTERNAL_DEV=1 bun run dev` (in apps/api) →
env validator rejects missing keys with "Invalid environment variables"
exactly like before — fail-fast preserved.
---
 .superset/lib/setup/steps.sh                  |  4 ++
 README.md                                     |  2 +-
 apps/admin/src/env.ts                         | 13 ++++-
 apps/api/src/app/api/health/route.ts          | 38 +++++++++++++
 apps/api/src/env.ts                           | 14 ++++-
 apps/api/src/instrumentation.ts               |  2 +
 apps/api/src/lib/boot-summary.ts              | 55 +++++++++++++++++++
 apps/desktop/src/main/env.main.ts             | 15 ++++-
 apps/desktop/src/main/index.ts                |  6 +-
 apps/desktop/src/main/lib/dev-auto-sign-in.ts |  8 +--
 apps/docs/src/env.ts                          | 13 ++++-
 apps/marketing/src/env.ts                     | 13 ++++-
 apps/relay/src/env.ts                         | 13 ++++-
 apps/web/src/env.ts                           | 13 ++++-
 docs/LOCAL_DEVELOPMENT.md                     | 47 +++++++++++++---
 packages/shared/package.json                  |  4 ++
 packages/shared/src/deployment-profile.ts     | 51 +++++++++++++++++
 packages/trpc/src/env.ts                      | 13 ++++-
 plans/20260515-oss-local-setup.md             | 54 +++++++++++++++++-
 19 files changed, 349 insertions(+), 29 deletions(-)
 create mode 100644 apps/api/src/app/api/health/route.ts
 create mode 100644 apps/api/src/lib/boot-summary.ts
 create mode 100644 packages/shared/src/deployment-profile.ts

diff --git a/.superset/lib/setup/steps.sh b/.superset/lib/setup/steps.sh
index 01dc39a483d..d59b204f66e 100644
--- a/.superset/lib/setup/steps.sh
+++ b/.superset/lib/setup/steps.sh
@@ -440,6 +440,10 @@ step_write_env() {
     echo "# Workspace Identity"
     write_env_var "SUPERSET_WORKSPACE_NAME" "${WORKSPACE_NAME:-$(basename "$PWD")}"
     write_env_var "SUPERSET_HOME_DIR" "$PWD/superset-dev-data"
+    # Marks this workspace as an internal-dev profile. Used by env validation
+    # to enforce strict (fail-fast on missing integration keys) — matches the
+    # pre-OSS behavior internal devs rely on. Never set in .env.example.
+    write_env_var "SUPERSET_INTERNAL_DEV" "1"
     echo ""
     echo "# Workspace Database (Neon Branch)"
     if [ -n "${BRANCH_ID:-}" ]; then
diff --git a/README.md b/README.md
index e2758e59ecf..43a2706e14a 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ docker run -d --name superset-pg \
 cp .env.example .env   # then edit DATABASE_URL + BETTER_AUTH_SECRET
 bun run db:migrate
 cp Caddyfile.example Caddyfile && caddy trust
-SKIP_ENV_VALIDATION=1 bun dev
+bun dev
 ```
 
 The desktop window opens auto-signed-in as a seed admin (`admin@local.test`). See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details, troubleshooting, and what's stubbed without integration keys.
diff --git a/apps/admin/src/env.ts b/apps/admin/src/env.ts
index 0601dc61f69..83d4223abd6 100644
--- a/apps/admin/src/env.ts
+++ b/apps/admin/src/env.ts
@@ -1,7 +1,18 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	extends: [vercel()],
 	shared: {
@@ -49,6 +60,6 @@ export const env = createEnv({
 		NEXT_PUBLIC_SENTRY_ENVIRONMENT: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,
 	},
 
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 	emptyStringAsUndefined: true,
 });
diff --git a/apps/api/src/app/api/health/route.ts b/apps/api/src/app/api/health/route.ts
new file mode 100644
index 00000000000..b17416804f7
--- /dev/null
+++ b/apps/api/src/app/api/health/route.ts
@@ -0,0 +1,38 @@
+import { getDeploymentProfile } from "@superset/shared/deployment-profile";
+import { NextResponse } from "next/server";
+
+/**
+ * Per-integration configuration status. Read from process.env so we don't
+ * have to keep this in sync with the (validated) env schema — the goal here
+ * is observability, not validation.
+ */
+const INTEGRATIONS = {
+	stripe: "STRIPE_SECRET_KEY",
+	resend: "RESEND_API_KEY",
+	posthog: "NEXT_PUBLIC_POSTHOG_KEY",
+	sentry: "NEXT_PUBLIC_SENTRY_DSN_API",
+	"github-app": "GH_APP_ID",
+	"github-oauth": "GH_CLIENT_ID",
+	"google-oauth": "GOOGLE_CLIENT_ID",
+	linear: "LINEAR_CLIENT_ID",
+	slack: "SLACK_CLIENT_ID",
+	freestyle: "FREESTYLE_API_KEY",
+	qstash: "QSTASH_TOKEN",
+	"upstash-kv": "KV_REST_API_URL",
+	blob: "BLOB_READ_WRITE_TOKEN",
+	anthropic: "ANTHROPIC_API_KEY",
+	tavily: "TAVILY_API_KEY",
+} as const;
+
+export function GET() {
+	const profile = getDeploymentProfile();
+	const integrations: Record<string, "configured" | "missing"> = {};
+	for (const [name, envVar] of Object.entries(INTEGRATIONS)) {
+		integrations[name] = process.env[envVar] ? "configured" : "missing";
+	}
+	return NextResponse.json({
+		ok: true,
+		profile,
+		integrations,
+	});
+}
diff --git a/apps/api/src/env.ts b/apps/api/src/env.ts
index 117ed25046a..13da0c20599 100644
--- a/apps/api/src/env.ts
+++ b/apps/api/src/env.ts
@@ -1,6 +1,18 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots without
+// every integration key. Strict profiles (cloud, internal-dev, self-hosted)
+// still fail fast on missing required keys. SKIP_ENV_VALIDATION=1 remains a
+// build-time escape hatch (e.g. for Docker preview builds).
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	shared: {
 		NODE_ENV: z
@@ -70,5 +82,5 @@ export const env = createEnv({
 		NEXT_PUBLIC_SENTRY_ENVIRONMENT: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,
 	},
 	emptyStringAsUndefined: true,
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 });
diff --git a/apps/api/src/instrumentation.ts b/apps/api/src/instrumentation.ts
index 5a4e9039446..125499e5b0a 100644
--- a/apps/api/src/instrumentation.ts
+++ b/apps/api/src/instrumentation.ts
@@ -1,8 +1,10 @@
 import * as Sentry from "@sentry/nextjs";
+import { logBootSummary } from "./lib/boot-summary";
 
 export async function register() {
 	if (process.env.NEXT_RUNTIME === "nodejs") {
 		await import("../sentry.server.config");
+		logBootSummary();
 	}
 
 	if (process.env.NEXT_RUNTIME === "edge") {
diff --git a/apps/api/src/lib/boot-summary.ts b/apps/api/src/lib/boot-summary.ts
new file mode 100644
index 00000000000..17445440004
--- /dev/null
+++ b/apps/api/src/lib/boot-summary.ts
@@ -0,0 +1,55 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
+
+/**
+ * Integration name → primary env var that activates it. Listed once at API
+ * boot so contributors can see what's disabled. Strict profiles fail before
+ * reaching this code (env validation rejects missing keys), so this only
+ * meaningfully runs in oss-dev.
+ */
+const INTEGRATIONS: Array<[name: string, envVar: string]> = [
+	["stripe", "STRIPE_SECRET_KEY"],
+	["resend (email)", "RESEND_API_KEY"],
+	["posthog (telemetry)", "NEXT_PUBLIC_POSTHOG_KEY"],
+	["sentry", "NEXT_PUBLIC_SENTRY_DSN_API"],
+	["github-app", "GH_APP_ID"],
+	["github-oauth", "GH_CLIENT_ID"],
+	["google-oauth", "GOOGLE_CLIENT_ID"],
+	["linear", "LINEAR_CLIENT_ID"],
+	["slack", "SLACK_CLIENT_ID"],
+	["freestyle", "FREESTYLE_API_KEY"],
+	["qstash (jobs)", "QSTASH_TOKEN"],
+	["upstash-kv (rate limit)", "KV_REST_API_URL"],
+	["vercel-blob (uploads)", "BLOB_READ_WRITE_TOKEN"],
+	["anthropic", "ANTHROPIC_API_KEY"],
+	["tavily (search)", "TAVILY_API_KEY"],
+];
+
+let logged = false;
+
+export function logBootSummary(): void {
+	if (logged) return;
+	logged = true;
+
+	const profile = getDeploymentProfile();
+	const missing = INTEGRATIONS.filter(([, k]) => !process.env[k]);
+
+	if (isStrictProfile(profile)) {
+		console.log(`[superset] profile=${profile} (strict)`);
+		return;
+	}
+
+	console.log(`[superset] profile=${profile} (lenient)`);
+	if (missing.length === 0) {
+		console.log("[superset] all integrations configured");
+		return;
+	}
+	console.log(
+		`[superset] disabled features (set the listed env var to enable):`,
+	);
+	for (const [name, envVar] of missing) {
+		console.log(`           - ${name.padEnd(28)} ${envVar}`);
+	}
+}
diff --git a/apps/desktop/src/main/env.main.ts b/apps/desktop/src/main/env.main.ts
index 13fe2e1af5a..9382b213c1d 100644
--- a/apps/desktop/src/main/env.main.ts
+++ b/apps/desktop/src/main/env.main.ts
@@ -6,9 +6,20 @@
  *
  * For renderer process env vars, use src/renderer/env.renderer.ts instead.
  */
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod/v4";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	server: {
 		NODE_ENV: z
@@ -45,9 +56,7 @@ export const env = createEnv({
 		RELAY_URL: process.env.RELAY_URL,
 	},
 	emptyStringAsUndefined: true,
-	// Only allow skipping validation in development (never in production)
-	skipValidation:
-		process.env.NODE_ENV === "development" && !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 
 	// Main process runs in trusted Node.js environment
 	isServer: true,
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index eca914a7d3b..c53a49cd26c 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -1,6 +1,7 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { settings } from "@superset/local-db";
+import { getDeploymentProfile } from "@superset/shared/deployment-profile";
 import {
 	app,
 	BrowserWindow,
@@ -56,8 +57,9 @@ import { MainWindow } from "./windows/main";
 console.log("[main] Local database ready:", !!localDb);
 const IS_DEV = process.env.NODE_ENV === "development";
 
-// Dev: expose Chrome DevTools Protocol for headless testing (e.g. import/host-service checks)
-if (IS_DEV && process.env.SKIP_ENV_VALIDATION) {
+// OSS-dev only: expose Chrome DevTools Protocol for headless testing
+// (e.g. import/host-service checks). Skip in internal-dev / cloud / self-host.
+if (IS_DEV && getDeploymentProfile() === "oss-dev") {
 	app.commandLine.appendSwitch("remote-debugging-port", "9333");
 	app.commandLine.appendSwitch("remote-allow-origins", "*");
 }
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
index e5f1f5a0650..831bc607fa2 100644
--- a/apps/desktop/src/main/lib/dev-auto-sign-in.ts
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -1,3 +1,4 @@
+import { getDeploymentProfile } from "@superset/shared/deployment-profile";
 import { env as mainEnv } from "main/env.main";
 import {
 	loadToken,
@@ -42,11 +43,8 @@ async function postAuth<T>(
  * Best-effort: failure is logged but doesn't crash boot.
  */
 export async function ensureDevAuthToken(): Promise<void> {
-	if (
-		process.env.NODE_ENV !== "development" ||
-		!process.env.SKIP_ENV_VALIDATION
-	)
-		return;
+	// OSS-dev only — internal devs, self-hosters, and prod all use real auth.
+	if (getDeploymentProfile() !== "oss-dev") return;
 
 	const stored = await loadToken();
 	if (stored.token && stored.expiresAt) {
diff --git a/apps/docs/src/env.ts b/apps/docs/src/env.ts
index 0343e017bba..d27d9295746 100644
--- a/apps/docs/src/env.ts
+++ b/apps/docs/src/env.ts
@@ -1,7 +1,18 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	extends: [vercel()],
 	shared: {
@@ -33,6 +44,6 @@ export const env = createEnv({
 		NEXT_PUBLIC_SENTRY_ENVIRONMENT: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,
 	},
 
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 	emptyStringAsUndefined: true,
 });
diff --git a/apps/marketing/src/env.ts b/apps/marketing/src/env.ts
index c962325f8cc..51cb7a762c1 100644
--- a/apps/marketing/src/env.ts
+++ b/apps/marketing/src/env.ts
@@ -1,7 +1,18 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	extends: [vercel()],
 	shared: {
@@ -42,5 +53,5 @@ export const env = createEnv({
 			process.env.NEXT_PUBLIC_SENTRY_DSN_MARKETING,
 		NEXT_PUBLIC_SENTRY_ENVIRONMENT: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,
 	},
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 });
diff --git a/apps/relay/src/env.ts b/apps/relay/src/env.ts
index d1aae3c0d08..0a2a4795471 100644
--- a/apps/relay/src/env.ts
+++ b/apps/relay/src/env.ts
@@ -1,6 +1,17 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	server: {
 		RELAY_PORT: z.coerce.number().int().positive().default(8080),
@@ -15,5 +26,5 @@ export const env = createEnv({
 	},
 	runtimeEnv: process.env,
 	emptyStringAsUndefined: true,
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 });
diff --git a/apps/web/src/env.ts b/apps/web/src/env.ts
index 00609331de5..fac54e58dca 100644
--- a/apps/web/src/env.ts
+++ b/apps/web/src/env.ts
@@ -1,7 +1,18 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	extends: [vercel()],
 	shared: {
@@ -51,6 +62,6 @@ export const env = createEnv({
 		NEXT_PUBLIC_SENTRY_ENVIRONMENT: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,
 	},
 
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 	emptyStringAsUndefined: true,
 });
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 02c67f8cee8..75d449ed0fa 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -66,7 +66,7 @@ Without `caddy trust`, Chromium will reject `https://localhost:*` with `ERR_CERT
 ## Run it
 
 ```bash
-SKIP_ENV_VALIDATION=1 bun dev
+bun dev
 ```
 
 That brings up:
@@ -85,18 +85,48 @@ The Electron window opens automatically.
 
 ### How sign-in works
 
-On first launch in dev mode (`SKIP_ENV_VALIDATION=1`), the desktop main process auto-signs you in as a seed admin user:
+On first launch in the `oss-dev` profile (no `SUPERSET_INTERNAL_DEV` or `VERCEL` flag set), the desktop main process auto-signs you in as a seed admin user:
 
 - **Email:** `admin@local.test`
 - **Password:** `supersetdev`
 
 If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in `superset-dev-data/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
 
-For the web app (`http://localhost:4640`), the sign-in and sign-up pages render a dev-only email/password form when `NODE_ENV !== "production"`. Use the same credentials.
+### Deployment profiles
+
+Profile is resolved at boot from env flags, in order of trust:
+
+| Profile        | Trigger                                         | Behavior |
+|----------------|-------------------------------------------------|----------|
+| `cloud`        | `VERCEL=1` (set automatically by Vercel)        | Strict — every integration key required |
+| `internal-dev` | `SUPERSET_INTERNAL_DEV=1` (written by `.superset/setup.sh`) | Strict — same fail-fast as cloud |
+| `self-hosted`  | `NODE_ENV=production` outside Vercel            | Strict |
+| `oss-dev`      | default                                         | Lenient — integration keys optional, features degrade |
+
+A contributor cloning from GitHub gets `oss-dev` by default — there's nothing to type and the strict-mode flags are positive-presence (you'd have to actively set them, never accidentally trip).
 
-## Why `SKIP_ENV_VALIDATION=1`?
+The escape hatch `SKIP_ENV_VALIDATION=1` still works for build-time / CI cases (e.g. Docker preview builds).
 
-`apps/api/src/env.ts` currently declares many integration keys (`STRIPE_*`, `RESEND_API_KEY`, `GH_APP_*`, etc.) as required strings via `@t3-oss/env-nextjs`. Until those are marked optional, the env validator rejects empty values at boot. `SKIP_ENV_VALIDATION=1` is the upstream escape hatch — propagated via `turbo.jsonc`'s `globalPassThroughEnv` so it reaches every subtask.
+### Boot summary + `/api/health`
+
+When the API boots in `oss-dev`, it prints a one-time summary of what's disabled:
+
+```
+[superset] profile=oss-dev (lenient)
+[superset] disabled features (set the listed env var to enable):
+           - stripe                       STRIPE_SECRET_KEY
+           - resend (email)               RESEND_API_KEY
+           - posthog (telemetry)          NEXT_PUBLIC_POSTHOG_KEY
+           ...
+```
+
+For programmatic monitoring (or to confirm a key took effect), hit `GET /api/health`:
+
+```json
+{ "ok": true, "profile": "oss-dev", "integrations": { "stripe": "missing", ... } }
+```
+
+For the web app (`http://localhost:4640`), the sign-in and sign-up pages render a dev-only email/password form when `NODE_ENV !== "production"`. Use the same credentials.
 
 ## What works in OSS mode
 
@@ -124,7 +154,7 @@ Each is "guard, don't crash" — if you click into a feature that needs a key, y
 
 **`EADDRINUSE: address already in use :::4641`** — a previous `bun dev` is still alive. `pkill -f "turbo run dev"` and retry.
 
-**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `superset-dev-data/auth-token.enc` exists. Delete it and rerun if needed: `rm superset-dev-data/auth-token.enc && SKIP_ENV_VALIDATION=1 bun dev`.
+**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `superset-dev-data/auth-token.enc` exists. Delete it and rerun if needed: `rm superset-dev-data/auth-token.enc && bun dev`. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "oss-dev"` — if it says `internal-dev`, your shell has `SUPERSET_INTERNAL_DEV=1` exported and auto-sign-in is intentionally skipped.
 
 **`Missing API key` for some integration** — that integration's key isn't in `.env`. Either supply it or avoid the feature.
 
@@ -148,7 +178,8 @@ docker rm -f superset-pg
 
 ## Architecture notes for contributors
 
+- **Deployment profiles** — `packages/shared/src/deployment-profile.ts` resolves `cloud | internal-dev | self-hosted | oss-dev` from env flags. Strict profiles fail boot on missing keys; lenient (`oss-dev`) lets the app boot. Use `isStrictProfile()` from this module when you need to gate dev-only behavior.
 - **DB driver swap** — `packages/db/src/client.ts` detects whether `DATABASE_URL` is a Neon host (`*.neon.tech`, `*.neon.build`) and uses Drizzle's `neon-http` adapter for cloud, or `node-postgres` for any other Postgres (including the local Docker one).
-- **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()`. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
+- **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()` only in the `oss-dev` profile. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
 - **Renderer organization selection** — pages prefer `session.activeOrganizationId` from Better Auth, falling back to `MOCK_ORG_ID` only if there's no session at all. Make sure new code that needs `activeOrganizationId` follows this same priority (real session first).
-- **CDP for headless tests** — when `SKIP_ENV_VALIDATION=1`, the desktop main process exposes Chrome DevTools Protocol on `localhost:9333`. Useful for scripted UI checks (`curl http://localhost:9333/json/list`).
+- **CDP for headless tests** — in the `oss-dev` profile, the desktop main process exposes Chrome DevTools Protocol on `localhost:9333`. Useful for scripted UI checks (`curl http://localhost:9333/json/list`).
diff --git a/packages/shared/package.json b/packages/shared/package.json
index bafa022fca3..5f0400af78e 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -8,6 +8,10 @@
 			"types": "./src/constants.ts",
 			"default": "./src/constants.ts"
 		},
+		"./deployment-profile": {
+			"types": "./src/deployment-profile.ts",
+			"default": "./src/deployment-profile.ts"
+		},
 		"./v2-only-user": {
 			"types": "./src/v2-only-user.ts",
 			"default": "./src/v2-only-user.ts"
diff --git a/packages/shared/src/deployment-profile.ts b/packages/shared/src/deployment-profile.ts
new file mode 100644
index 00000000000..a0188c575d9
--- /dev/null
+++ b/packages/shared/src/deployment-profile.ts
@@ -0,0 +1,51 @@
+/**
+ * Deployment profile resolution.
+ *
+ * Four profiles, ranked by discriminator trust:
+ *
+ *   1. `cloud`         — Vercel sets `VERCEL=1` automatically. Contributors
+ *                        can't fake it locally.
+ *   2. `internal-dev`  — `.superset/setup.sh` writes `SUPERSET_INTERNAL_DEV=1`
+ *                        into per-workspace `.env`. Never appears in
+ *                        `.env.example`, never mentioned in `docs/`.
+ *                        Positive-presence flag — contributors won't type it.
+ *   3. `self-hosted`   — `NODE_ENV=production` outside Vercel (Docker, bare
+ *                        metal). Strict-by-default; operator opted in.
+ *   4. `oss-dev`       — default for a fresh clone. Lenient: integration keys
+ *                        are optional and features degrade gracefully.
+ *
+ * **Strict profiles** (`cloud`, `internal-dev`, `self-hosted`) hard-fail at
+ * boot when an integration key is missing — matches the existing prod and
+ * internal-dev behavior.
+ *
+ * **Lenient profile** (`oss-dev`) allows the app to boot with missing keys;
+ * call sites lazy-throw / no-op so features degrade visibly rather than
+ * crashing module load.
+ *
+ * Why this axis instead of `NODE_ENV`? `NODE_ENV=development` covers both
+ * OSS contributors and internal team members — same code path, very
+ * different expectations. The sentinel discriminator (`SUPERSET_INTERNAL_DEV`)
+ * cleanly separates them.
+ */
+export type DeploymentProfile =
+	| "cloud"
+	| "internal-dev"
+	| "self-hosted"
+	| "oss-dev";
+
+export function getDeploymentProfile(
+	envSource: Record<string, string | undefined> = process.env,
+): DeploymentProfile {
+	if (envSource.VERCEL === "1") return "cloud";
+	if (envSource.SUPERSET_INTERNAL_DEV === "1") return "internal-dev";
+	if (envSource.NODE_ENV === "production") return "self-hosted";
+	return "oss-dev";
+}
+
+export function isStrictProfile(profile: DeploymentProfile): boolean {
+	return (
+		profile === "cloud" ||
+		profile === "internal-dev" ||
+		profile === "self-hosted"
+	);
+}
diff --git a/packages/trpc/src/env.ts b/packages/trpc/src/env.ts
index d3b05f407f1..6ac2ca66bcb 100644
--- a/packages/trpc/src/env.ts
+++ b/packages/trpc/src/env.ts
@@ -1,6 +1,17 @@
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
+// OSS-dev profile skips strict env validation so a fresh clone boots
+// without every integration key. Strict profiles (cloud, internal-dev,
+// self-hosted) still fail fast on missing keys.
+const profile = getDeploymentProfile();
+const skipValidation =
+	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+
 export const env = createEnv({
 	server: {
 		NODE_ENV: z
@@ -37,5 +48,5 @@ export const env = createEnv({
 	client: {},
 	runtimeEnv: process.env,
 	emptyStringAsUndefined: true,
-	skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+	skipValidation,
 });
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index 5db24a0b82a..48d5f9937db 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -63,6 +63,55 @@ A fresh-clone contributor can:
 - The DevAuthForm only renders when `NODE_ENV !== "production"`.
 - The Chrome DevTools Protocol port (9333) only opens when both `IS_DEV` and `SKIP_ENV_VALIDATION` are set.
 
+## Deployment profiles (the key abstraction)
+
+`packages/shared/src/deployment-profile.ts` exposes a four-profile model:
+
+| Profile | Trigger | Validation |
+|---|---|---|
+| `cloud` | `VERCEL=1` (set automatically by Vercel) | Strict — every integration key required |
+| `internal-dev` | `SUPERSET_INTERNAL_DEV=1` (written by `.superset/setup.sh`) | Strict |
+| `self-hosted` | `NODE_ENV=production` outside Vercel | Strict |
+| `oss-dev` | default | Lenient |
+
+All env schemas (`apps/api/src/env.ts`, `packages/trpc/src/env.ts`, `apps/web/src/env.ts`, etc.) compute their `skipValidation` from this:
+
+```ts
+const skipValidation = !isStrictProfile(getDeploymentProfile()) || !!process.env.SKIP_ENV_VALIDATION;
+```
+
+OSS contributors: validation skipped → boot with whatever's in `.env`, lazy guards catch the crashes.
+Internal devs: validation runs → fail-fast on missing keys, same as today's experience.
+Cloud / self-hosted: validation runs → bad deploys never serve traffic.
+
+The discriminator (`SUPERSET_INTERNAL_DEV=1`) is **positive-presence**: a contributor cloning fresh has no way to type it accidentally — it's never in `.env.example`, never documented as a setting. Written only by `.superset/lib/setup/steps.sh` `step_write_env`.
+
+`SKIP_ENV_VALIDATION=1` remains the build-time escape hatch (e.g. Docker preview builds), routed through `turbo.jsonc`'s `globalPassThroughEnv`. Not the primary discriminator.
+
+### Boot-time visibility
+
+`apps/api/src/lib/boot-summary.ts` prints a one-time summary at API startup listing every disabled integration:
+
+```
+[superset] profile=oss-dev (lenient)
+[superset] disabled features (set the listed env var to enable):
+           - stripe                       STRIPE_SECRET_KEY
+           - resend (email)               RESEND_API_KEY
+           - ...
+```
+
+In strict profiles it just prints `profile=cloud (strict)` (env validation already failed boot if anything's missing).
+
+### `/api/health` endpoint
+
+`apps/api/src/app/api/health/route.ts` returns:
+
+```json
+{ "ok": true, "profile": "oss-dev", "integrations": { "stripe": "missing", ... } }
+```
+
+Used for: contributor sanity checks, prod monitoring alerts on unexpected gaps.
+
 ## What's NOT built (originally in plan, deferred)
 
 These were in the original plan but aren't necessary for "fresh clone boots" and were left for follow-up:
@@ -70,13 +119,12 @@ These were in the original plan but aren't necessary for "fresh clone boots" and
 - **`docker-compose.dev.yml`** — currently contributors run a one-liner `docker run`. A compose file with Postgres + Mailpit would be nicer; for now, the README's short instructions are enough.
 - **`.env.example` rewrite with working defaults** — `.env.example` is still mostly blank. The docs tell contributors to set just `DATABASE_URL` and `BETTER_AUTH_SECRET`.
 - **`bun setup` orchestrator** — the discrete steps (`docker run`, `bun install`, `bun run db:migrate`, `bun dev`) are still manual. Wrapping them in `bun setup` would be a small ergonomics win.
-- **Making integration env vars `.optional()` in `apps/api/src/env.ts`** — the reason `SKIP_ENV_VALIDATION=1` is still required. Mechanical change: ~25 `.string()` → `.string().optional()`. Once done, the flag goes away.
-- **Production startup hardening** — the plan called for `apps/api/src/env-check.ts` that hard-fails in prod on any missing required key. Not built. Today, prod relies on the existing `@t3-oss/env-nextjs` strictness (which works fine when those keys aren't `.optional()`).
-- **Sentinel-string detection for `BETTER_AUTH_SECRET`** — not built. Today, contributors generate their own secret via `openssl rand -hex 24`.
+- **Per-integration group `.refine()`** — e.g. if `STRIPE_SECRET_KEY` is set then `STRIPE_WEBHOOK_SECRET` must also be set. Catches half-configured prod deploys. Not built; deferred until someone hits the failure mode.
 - **CI fresh-clone smoke test** — not built. Without it, the OSS path can rot silently if someone adds a new crash-on-import integration.
 - **Email provider abstraction (Mailpit fallback)** — Better Auth's `sendEmail` hook currently just `console.log`s emails when no `RESEND_API_KEY` is present. Mailpit container would be nicer UX (clickable links in a web UI) but isn't blocking.
 - **Local-disk Blob storage fallback** — not built. Upload features that need `BLOB_READ_WRITE_TOKEN` will throw.
 - **In-memory rate-limit fallback** — not built. Upstash KV is already handled gracefully by the SDK (logs warnings on missing keys).
+- **Full integration crash audit** — Stripe, Resend, PostHog, and `packages/trpc/src/router/support` were wrapped with lazy-init. GitHub App, Freestyle, Linear, Slack, QStash signing keys, Anthropic, Blob may still crash-on-import in oss-dev. Need a survey: `grep -rn "new \w\+(.*env\." packages apps`.
 
 ## What was learned vs. the original plan
 

From f3c76b951f1c46e1ed7ffe62c0f6d2d77c3204b5 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sat, 16 May 2026 14:33:29 -0700
Subject: [PATCH 03/28] =?UTF-8?q?refactor:=20flip=20profile=20discriminato?=
 =?UTF-8?q?r=20=E2=80=94=20strict=20by=20default,=20SUPERSET=5FOSS=3D1=20o?=
 =?UTF-8?q?pts=20into=20lenient?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Internal devs and self-hosters keep their current fail-fast workflow with
zero setup changes. OSS contributors set SUPERSET_OSS=1 once to opt into
the lenient profile.

## Why

Previous design wrote SUPERSET_INTERNAL_DEV=1 via .superset/setup.sh so
internal devs would land in strict mode. That added a flag to internal
devs' workflow (a regression) and made the default lenient (a silent-
failure footgun for self-hosters who forgot to source their .env).

Strict-by-default is the conservative direction:
  - Internal devs: no shell-config or setup-script changes; same fail-
    fast as today on missing keys.
  - Self-hosted: defaults to strict — operators get a loud error if
    they miss something, not a silently-degraded app.
  - OSS contributors: opt in with one flag (`SUPERSET_OSS=1`) and get
    explicit "you're in lenient mode" feedback from the boot summary.

## Profile model (3 not 4)

  cloud      VERCEL=1            (auto, set by Vercel)         strict
  oss-dev    SUPERSET_OSS=1                                     lenient
  internal   default (covers internal team + self-host)         strict

## Changes

- packages/shared/src/deployment-profile.ts: trigger flipped to look
  for SUPERSET_OSS (positive opt-in for lenient) instead of
  SUPERSET_INTERNAL_DEV (positive opt-in for strict).
- .superset/lib/setup/steps.sh: no longer writes SUPERSET_INTERNAL_DEV.
  Internal-dev workspaces now default to strict via the absence of any
  flag — same as production.
- turbo.jsonc: added SUPERSET_OSS to globalPassThroughEnv.
- README, docs/LOCAL_DEVELOPMENT.md, plans/20260515-oss-local-setup.md:
  updated to show SUPERSET_OSS=1 as the lenient opt-in.
- Comment blocks in each env.ts schema rewritten to reflect the new
  semantics.

## Verified

- `bun run dev` in apps/api (no flag): ❌ Invalid environment variables
  → strict validation fires exactly like today's internal-dev workflow.
- `SUPERSET_OSS=1 bun run dev`: ✓ Ready + boot summary
  "[superset] profile=oss-dev (lenient)".
---
 .superset/lib/setup/steps.sh              |  4 --
 README.md                                 |  2 +-
 apps/admin/src/env.ts                     |  7 +--
 apps/api/src/env.ts                       |  8 ++--
 apps/desktop/src/main/env.main.ts         |  7 +--
 apps/desktop/src/main/index.ts            |  2 +-
 apps/docs/src/env.ts                      |  7 +--
 apps/marketing/src/env.ts                 |  7 +--
 apps/relay/src/env.ts                     |  7 +--
 apps/web/src/env.ts                       |  7 +--
 docs/LOCAL_DEVELOPMENT.md                 | 23 ++++-----
 packages/shared/src/deployment-profile.ts | 57 +++++++++--------------
 packages/trpc/src/env.ts                  |  7 +--
 plans/20260515-oss-local-setup.md         | 19 ++++----
 turbo.jsonc                               |  3 +-
 15 files changed, 82 insertions(+), 85 deletions(-)

diff --git a/.superset/lib/setup/steps.sh b/.superset/lib/setup/steps.sh
index d59b204f66e..01dc39a483d 100644
--- a/.superset/lib/setup/steps.sh
+++ b/.superset/lib/setup/steps.sh
@@ -440,10 +440,6 @@ step_write_env() {
     echo "# Workspace Identity"
     write_env_var "SUPERSET_WORKSPACE_NAME" "${WORKSPACE_NAME:-$(basename "$PWD")}"
     write_env_var "SUPERSET_HOME_DIR" "$PWD/superset-dev-data"
-    # Marks this workspace as an internal-dev profile. Used by env validation
-    # to enforce strict (fail-fast on missing integration keys) — matches the
-    # pre-OSS behavior internal devs rely on. Never set in .env.example.
-    write_env_var "SUPERSET_INTERNAL_DEV" "1"
     echo ""
     echo "# Workspace Database (Neon Branch)"
     if [ -n "${BRANCH_ID:-}" ]; then
diff --git a/README.md b/README.md
index 43a2706e14a..46b556a5ae5 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ docker run -d --name superset-pg \
 cp .env.example .env   # then edit DATABASE_URL + BETTER_AUTH_SECRET
 bun run db:migrate
 cp Caddyfile.example Caddyfile && caddy trust
-bun dev
+SUPERSET_OSS=1 bun dev
 ```
 
 The desktop window opens auto-signed-in as a seed admin (`admin@local.test`). See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details, troubleshooting, and what's stubbed without integration keys.
diff --git a/apps/admin/src/env.ts b/apps/admin/src/env.ts
index 83d4223abd6..33a21635569 100644
--- a/apps/admin/src/env.ts
+++ b/apps/admin/src/env.ts
@@ -6,9 +6,10 @@ import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/apps/api/src/env.ts b/apps/api/src/env.ts
index 13da0c20599..d7b020f6e30 100644
--- a/apps/api/src/env.ts
+++ b/apps/api/src/env.ts
@@ -5,10 +5,10 @@ import {
 import { createEnv } from "@t3-oss/env-nextjs";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots without
-// every integration key. Strict profiles (cloud, internal-dev, self-hosted)
-// still fail fast on missing required keys. SKIP_ENV_VALIDATION=1 remains a
-// build-time escape hatch (e.g. for Docker preview builds).
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/apps/desktop/src/main/env.main.ts b/apps/desktop/src/main/env.main.ts
index 9382b213c1d..d34d74b304b 100644
--- a/apps/desktop/src/main/env.main.ts
+++ b/apps/desktop/src/main/env.main.ts
@@ -13,9 +13,10 @@ import {
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod/v4";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index c53a49cd26c..4aec2cbea05 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -58,7 +58,7 @@ console.log("[main] Local database ready:", !!localDb);
 const IS_DEV = process.env.NODE_ENV === "development";
 
 // OSS-dev only: expose Chrome DevTools Protocol for headless testing
-// (e.g. import/host-service checks). Skip in internal-dev / cloud / self-host.
+// (e.g. import/host-service checks). Skip in internal / cloud profiles.
 if (IS_DEV && getDeploymentProfile() === "oss-dev") {
 	app.commandLine.appendSwitch("remote-debugging-port", "9333");
 	app.commandLine.appendSwitch("remote-allow-origins", "*");
diff --git a/apps/docs/src/env.ts b/apps/docs/src/env.ts
index d27d9295746..2f4b39075bd 100644
--- a/apps/docs/src/env.ts
+++ b/apps/docs/src/env.ts
@@ -6,9 +6,10 @@ import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/apps/marketing/src/env.ts b/apps/marketing/src/env.ts
index 51cb7a762c1..c2d5e1edaf5 100644
--- a/apps/marketing/src/env.ts
+++ b/apps/marketing/src/env.ts
@@ -6,9 +6,10 @@ import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/apps/relay/src/env.ts b/apps/relay/src/env.ts
index 0a2a4795471..bf36a65909f 100644
--- a/apps/relay/src/env.ts
+++ b/apps/relay/src/env.ts
@@ -5,9 +5,10 @@ import {
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/apps/web/src/env.ts b/apps/web/src/env.ts
index fac54e58dca..e98a53ce260 100644
--- a/apps/web/src/env.ts
+++ b/apps/web/src/env.ts
@@ -6,9 +6,10 @@ import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 75d449ed0fa..5955801275e 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -66,9 +66,11 @@ Without `caddy trust`, Chromium will reject `https://localhost:*` with `ERR_CERT
 ## Run it
 
 ```bash
-bun dev
+SUPERSET_OSS=1 bun dev
 ```
 
+`SUPERSET_OSS=1` opts you into the lenient OSS profile so the app boots without every integration key — Stripe, OAuth, Resend, etc. become optional. Without it, the app defaults to strict validation (matching the internal-team workflow) and will fail boot if any of those keys are missing.
+
 That brings up:
 
 | Service | Port | What it does |
@@ -85,7 +87,7 @@ The Electron window opens automatically.
 
 ### How sign-in works
 
-On first launch in the `oss-dev` profile (no `SUPERSET_INTERNAL_DEV` or `VERCEL` flag set), the desktop main process auto-signs you in as a seed admin user:
+On first launch in the `oss-dev` profile (when `SUPERSET_OSS=1` is set), the desktop main process auto-signs you in as a seed admin user:
 
 - **Email:** `admin@local.test`
 - **Password:** `supersetdev`
@@ -94,16 +96,15 @@ If the user doesn't exist, it's created and a personal organization is provision
 
 ### Deployment profiles
 
-Profile is resolved at boot from env flags, in order of trust:
+Profile is resolved at boot:
 
-| Profile        | Trigger                                         | Behavior |
-|----------------|-------------------------------------------------|----------|
-| `cloud`        | `VERCEL=1` (set automatically by Vercel)        | Strict — every integration key required |
-| `internal-dev` | `SUPERSET_INTERNAL_DEV=1` (written by `.superset/setup.sh`) | Strict — same fail-fast as cloud |
-| `self-hosted`  | `NODE_ENV=production` outside Vercel            | Strict |
-| `oss-dev`      | default                                         | Lenient — integration keys optional, features degrade |
+| Profile     | Trigger                              | Behavior |
+|-------------|--------------------------------------|----------|
+| `cloud`     | `VERCEL=1` (set automatically)       | Strict — every integration key required |
+| `oss-dev`   | `SUPERSET_OSS=1`                     | Lenient — integration keys optional, features degrade |
+| `internal`  | default                              | Strict — covers internal team dev and self-hosted prod |
 
-A contributor cloning from GitHub gets `oss-dev` by default — there's nothing to type and the strict-mode flags are positive-presence (you'd have to actively set them, never accidentally trip).
+**Strict-by-default is the safe direction.** Internal devs and self-hosters keep their fail-fast workflow with no setup changes. OSS contributors set `SUPERSET_OSS=1` once (in `.env`, or as a shell var) to opt into the lenient path.
 
 The escape hatch `SKIP_ENV_VALIDATION=1` still works for build-time / CI cases (e.g. Docker preview builds).
 
@@ -154,7 +155,7 @@ Each is "guard, don't crash" — if you click into a feature that needs a key, y
 
 **`EADDRINUSE: address already in use :::4641`** — a previous `bun dev` is still alive. `pkill -f "turbo run dev"` and retry.
 
-**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `superset-dev-data/auth-token.enc` exists. Delete it and rerun if needed: `rm superset-dev-data/auth-token.enc && bun dev`. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "oss-dev"` — if it says `internal-dev`, your shell has `SUPERSET_INTERNAL_DEV=1` exported and auto-sign-in is intentionally skipped.
+**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `superset-dev-data/auth-token.enc` exists. Delete it and rerun if needed: `rm superset-dev-data/auth-token.enc && SUPERSET_OSS=1 bun dev`. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "oss-dev"` — if it says `internal`, you forgot to set `SUPERSET_OSS=1` and auto-sign-in is intentionally skipped.
 
 **`Missing API key` for some integration** — that integration's key isn't in `.env`. Either supply it or avoid the feature.
 
diff --git a/packages/shared/src/deployment-profile.ts b/packages/shared/src/deployment-profile.ts
index a0188c575d9..c9142b7bdf1 100644
--- a/packages/shared/src/deployment-profile.ts
+++ b/packages/shared/src/deployment-profile.ts
@@ -1,51 +1,40 @@
 /**
  * Deployment profile resolution.
  *
- * Four profiles, ranked by discriminator trust:
+ * Three profiles, ranked by discriminator trust:
  *
- *   1. `cloud`         — Vercel sets `VERCEL=1` automatically. Contributors
- *                        can't fake it locally.
- *   2. `internal-dev`  — `.superset/setup.sh` writes `SUPERSET_INTERNAL_DEV=1`
- *                        into per-workspace `.env`. Never appears in
- *                        `.env.example`, never mentioned in `docs/`.
- *                        Positive-presence flag — contributors won't type it.
- *   3. `self-hosted`   — `NODE_ENV=production` outside Vercel (Docker, bare
- *                        metal). Strict-by-default; operator opted in.
- *   4. `oss-dev`       — default for a fresh clone. Lenient: integration keys
- *                        are optional and features degrade gracefully.
+ *   1. `cloud`     — Vercel sets `VERCEL=1` automatically. Contributors
+ *                    can't fake it locally. Strict-validated.
+ *   2. `oss-dev`   — Contributor explicitly sets `SUPERSET_OSS=1` to opt
+ *                    into the lenient profile so a fresh clone boots
+ *                    without every integration key.
+ *   3. `internal`  — Default. Covers internal team dev workspaces and
+ *                    self-hosted production. Strict-validated — matches
+ *                    today's fail-fast behavior so internal devs and
+ *                    self-hosters get loud errors on missing keys.
  *
- * **Strict profiles** (`cloud`, `internal-dev`, `self-hosted`) hard-fail at
- * boot when an integration key is missing — matches the existing prod and
- * internal-dev behavior.
+ * **Strict profiles** (`cloud`, `internal`) hard-fail at boot when an
+ * integration key is missing.
  *
- * **Lenient profile** (`oss-dev`) allows the app to boot with missing keys;
- * call sites lazy-throw / no-op so features degrade visibly rather than
- * crashing module load.
+ * **Lenient profile** (`oss-dev`) allows the app to boot with missing
+ * keys; call sites lazy-throw / no-op so features degrade visibly
+ * rather than crashing module load.
  *
- * Why this axis instead of `NODE_ENV`? `NODE_ENV=development` covers both
- * OSS contributors and internal team members — same code path, very
- * different expectations. The sentinel discriminator (`SUPERSET_INTERNAL_DEV`)
- * cleanly separates them.
+ * Default-strict is the conservative direction: an internal dev or
+ * self-hoster who forgets to source their `.env` gets a clear failure,
+ * not a silently-degraded app. OSS contributors trade a one-time
+ * `SUPERSET_OSS=1` for that safety guarantee.
  */
-export type DeploymentProfile =
-	| "cloud"
-	| "internal-dev"
-	| "self-hosted"
-	| "oss-dev";
+export type DeploymentProfile = "cloud" | "oss-dev" | "internal";
 
 export function getDeploymentProfile(
 	envSource: Record<string, string | undefined> = process.env,
 ): DeploymentProfile {
 	if (envSource.VERCEL === "1") return "cloud";
-	if (envSource.SUPERSET_INTERNAL_DEV === "1") return "internal-dev";
-	if (envSource.NODE_ENV === "production") return "self-hosted";
-	return "oss-dev";
+	if (envSource.SUPERSET_OSS === "1") return "oss-dev";
+	return "internal";
 }
 
 export function isStrictProfile(profile: DeploymentProfile): boolean {
-	return (
-		profile === "cloud" ||
-		profile === "internal-dev" ||
-		profile === "self-hosted"
-	);
+	return profile !== "oss-dev";
 }
diff --git a/packages/trpc/src/env.ts b/packages/trpc/src/env.ts
index 6ac2ca66bcb..50e424015d2 100644
--- a/packages/trpc/src/env.ts
+++ b/packages/trpc/src/env.ts
@@ -5,9 +5,10 @@ import {
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
-// OSS-dev profile skips strict env validation so a fresh clone boots
-// without every integration key. Strict profiles (cloud, internal-dev,
-// self-hosted) still fail fast on missing keys.
+// Default profile is `internal` (strict). OSS contributors set
+// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
+// skips env validation so a fresh clone boots without every key.
+// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
 const profile = getDeploymentProfile();
 const skipValidation =
 	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index 48d5f9937db..d26e39761ab 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -65,14 +65,13 @@ A fresh-clone contributor can:
 
 ## Deployment profiles (the key abstraction)
 
-`packages/shared/src/deployment-profile.ts` exposes a four-profile model:
+`packages/shared/src/deployment-profile.ts` exposes a three-profile model:
 
 | Profile | Trigger | Validation |
 |---|---|---|
 | `cloud` | `VERCEL=1` (set automatically by Vercel) | Strict — every integration key required |
-| `internal-dev` | `SUPERSET_INTERNAL_DEV=1` (written by `.superset/setup.sh`) | Strict |
-| `self-hosted` | `NODE_ENV=production` outside Vercel | Strict |
-| `oss-dev` | default | Lenient |
+| `oss-dev` | `SUPERSET_OSS=1` | Lenient — integration keys optional, features degrade |
+| `internal` | default | Strict — covers internal team dev + self-hosted prod |
 
 All env schemas (`apps/api/src/env.ts`, `packages/trpc/src/env.ts`, `apps/web/src/env.ts`, etc.) compute their `skipValidation` from this:
 
@@ -80,11 +79,15 @@ All env schemas (`apps/api/src/env.ts`, `packages/trpc/src/env.ts`, `apps/web/sr
 const skipValidation = !isStrictProfile(getDeploymentProfile()) || !!process.env.SKIP_ENV_VALIDATION;
 ```
 
-OSS contributors: validation skipped → boot with whatever's in `.env`, lazy guards catch the crashes.
-Internal devs: validation runs → fail-fast on missing keys, same as today's experience.
-Cloud / self-hosted: validation runs → bad deploys never serve traffic.
+OSS contributors: set `SUPERSET_OSS=1` once → validation skipped → boot with whatever's in `.env`, lazy guards catch the crashes.
+Internal devs: nothing changes → validation runs → fail-fast on missing keys, exactly today's experience.
+Cloud (Vercel): same as before, strict enforcement of all keys.
+Self-hosted: defaults to strict — operators get a loud error if they miss something.
 
-The discriminator (`SUPERSET_INTERNAL_DEV=1`) is **positive-presence**: a contributor cloning fresh has no way to type it accidentally — it's never in `.env.example`, never documented as a setting. Written only by `.superset/lib/setup/steps.sh` `step_write_env`.
+**Strict-by-default** is the conservative direction:
+- Internal devs and self-hosters keep their fail-fast workflow with zero changes to setup or shell config.
+- An internal dev who accidentally drops their `.env` gets the same loud error they get today.
+- An OSS contributor only has to type one flag (`SUPERSET_OSS=1`) — and gets explicit "you're in lenient mode" feedback via the boot summary.
 
 `SKIP_ENV_VALIDATION=1` remains the build-time escape hatch (e.g. Docker preview builds), routed through `turbo.jsonc`'s `globalPassThroughEnv`. Not the primary discriminator.
 
diff --git a/turbo.jsonc b/turbo.jsonc
index 9af58bdaebd..23b93a94b5c 100644
--- a/turbo.jsonc
+++ b/turbo.jsonc
@@ -26,7 +26,8 @@
 		"VERCEL_ENV",
 		"VERCEL_URL",
 		"npm_lifecycle_event",
-		"SKIP_ENV_VALIDATION"
+		"SKIP_ENV_VALIDATION",
+		"SUPERSET_OSS"
 	],
 	"tasks": {
 		"build": {

From 101cd30036572a599307c123ddb38392be7fd375 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sat, 16 May 2026 14:47:37 -0700
Subject: [PATCH 04/28] fix: add ci profile so GitHub Actions builds don't trip
 strict validation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI builds (`bun run lint`, `typecheck`, `test`) run in GitHub Actions
without integration keys — they'd hit the new internal-default strict
validation and fail. Add `ci` profile triggered by `CI=true` (set
automatically by every major CI runner) so those jobs run lenient.

Final 4-profile model, ranked by discriminator trust:

  cloud      VERCEL=1            (auto at Vercel runtime)        strict
  oss-dev    SUPERSET_OSS=1                                       lenient
  ci         CI=true             (auto in GitHub Actions etc.)    lenient
  internal   default                                              strict (team dev + self-host)

Lenient at build time, strict at runtime: `vercel build` pulls env
from the Vercel project so the build itself has all keys; the actual
runtime strictness still fires once VERCEL=1 is set on the deployed
serverless function. CI auto-degrades for lint/typecheck/test where
the keys aren't present and aren't needed.

Verified all 6 resolution cases (fresh clone, OSS, CI, Vercel, and
overrides between them) produce the right profile + strictness.
---
 docs/LOCAL_DEVELOPMENT.md                 |  7 ++--
 packages/shared/src/deployment-profile.ts | 49 ++++++++++++++---------
 plans/20260515-oss-local-setup.md         |  5 ++-
 3 files changed, 36 insertions(+), 25 deletions(-)

diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 5955801275e..516f3378719 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -100,13 +100,14 @@ Profile is resolved at boot:
 
 | Profile     | Trigger                              | Behavior |
 |-------------|--------------------------------------|----------|
-| `cloud`     | `VERCEL=1` (set automatically)       | Strict — every integration key required |
+| `cloud`     | `VERCEL=1` (set automatically at runtime) | Strict — every integration key required |
 | `oss-dev`   | `SUPERSET_OSS=1`                     | Lenient — integration keys optional, features degrade |
+| `ci`        | `CI=true` (set automatically by GitHub Actions, most runners) | Lenient — build/lint/test jobs run without prod secrets |
 | `internal`  | default                              | Strict — covers internal team dev and self-hosted prod |
 
-**Strict-by-default is the safe direction.** Internal devs and self-hosters keep their fail-fast workflow with no setup changes. OSS contributors set `SUPERSET_OSS=1` once (in `.env`, or as a shell var) to opt into the lenient path.
+**Strict-by-default is the safe direction.** Internal devs and self-hosters keep their fail-fast workflow with no setup changes. OSS contributors set `SUPERSET_OSS=1` once (in `.env`, or as a shell var) to opt into the lenient path. CI auto-degrades so `bun run lint/typecheck/test` works without injecting every production secret — actual deploy steps run `vercel build`, which pulls env from the Vercel project, and runtime strictness still kicks in once `VERCEL=1` is set on the deployed serverless function.
 
-The escape hatch `SKIP_ENV_VALIDATION=1` still works for build-time / CI cases (e.g. Docker preview builds).
+The escape hatch `SKIP_ENV_VALIDATION=1` still works for one-off bypass cases (e.g. Docker preview builds outside of GitHub Actions).
 
 ### Boot summary + `/api/health`
 
diff --git a/packages/shared/src/deployment-profile.ts b/packages/shared/src/deployment-profile.ts
index c9142b7bdf1..fc1d69d6f73 100644
--- a/packages/shared/src/deployment-profile.ts
+++ b/packages/shared/src/deployment-profile.ts
@@ -1,40 +1,49 @@
 /**
  * Deployment profile resolution.
  *
- * Three profiles, ranked by discriminator trust:
+ * Four profiles, ranked by discriminator trust:
  *
- *   1. `cloud`     — Vercel sets `VERCEL=1` automatically. Contributors
- *                    can't fake it locally. Strict-validated.
- *   2. `oss-dev`   — Contributor explicitly sets `SUPERSET_OSS=1` to opt
- *                    into the lenient profile so a fresh clone boots
- *                    without every integration key.
- *   3. `internal`  — Default. Covers internal team dev workspaces and
- *                    self-hosted production. Strict-validated — matches
- *                    today's fail-fast behavior so internal devs and
+ *   1. `cloud`     — Vercel sets `VERCEL=1` automatically at RUNTIME on
+ *                    its serverless functions. Contributors can't fake
+ *                    it locally. Strict — every integration key required.
+ *   2. `oss-dev`   — Contributor explicitly sets `SUPERSET_OSS=1` to
+ *                    opt into the lenient profile so a fresh clone
+ *                    boots without every integration key.
+ *   3. `ci`        — GitHub Actions sets `CI=true` (and runners do too).
+ *                    Lenient by design: lint/typecheck/test jobs don't
+ *                    have integration keys, and any actual deploy step
+ *                    runs `vercel build` which pulls env from the
+ *                    Vercel project. Runtime strictness still kicks in
+ *                    once the build is deployed and `VERCEL=1` is set.
+ *   4. `internal`  — Default. Covers internal team dev workspaces and
+ *                    self-hosted production. Strict — matches today's
+ *                    fail-fast behavior so internal devs and
  *                    self-hosters get loud errors on missing keys.
  *
- * **Strict profiles** (`cloud`, `internal`) hard-fail at boot when an
- * integration key is missing.
+ * **Strict** (`cloud`, `internal`) hard-fail at boot when an integration
+ * key is missing.
  *
- * **Lenient profile** (`oss-dev`) allows the app to boot with missing
- * keys; call sites lazy-throw / no-op so features degrade visibly
- * rather than crashing module load.
+ * **Lenient** (`oss-dev`, `ci`) allow the app to boot with missing keys;
+ * call sites lazy-throw / no-op so features degrade visibly rather than
+ * crashing module load.
  *
- * Default-strict is the conservative direction: an internal dev or
- * self-hoster who forgets to source their `.env` gets a clear failure,
- * not a silently-degraded app. OSS contributors trade a one-time
- * `SUPERSET_OSS=1` for that safety guarantee.
+ * Default-strict at runtime is the conservative direction: an internal
+ * dev or self-hoster who forgets to source their `.env` gets a clear
+ * failure, not a silently-degraded app. OSS contributors trade a one-time
+ * `SUPERSET_OSS=1` for that safety guarantee. CI build steps degrade so
+ * lint/typecheck/test don't require every production secret.
  */
-export type DeploymentProfile = "cloud" | "oss-dev" | "internal";
+export type DeploymentProfile = "cloud" | "oss-dev" | "ci" | "internal";
 
 export function getDeploymentProfile(
 	envSource: Record<string, string | undefined> = process.env,
 ): DeploymentProfile {
 	if (envSource.VERCEL === "1") return "cloud";
 	if (envSource.SUPERSET_OSS === "1") return "oss-dev";
+	if (envSource.CI === "true") return "ci";
 	return "internal";
 }
 
 export function isStrictProfile(profile: DeploymentProfile): boolean {
-	return profile !== "oss-dev";
+	return profile !== "oss-dev" && profile !== "ci";
 }
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index d26e39761ab..d02f733fbbd 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -65,12 +65,13 @@ A fresh-clone contributor can:
 
 ## Deployment profiles (the key abstraction)
 
-`packages/shared/src/deployment-profile.ts` exposes a three-profile model:
+`packages/shared/src/deployment-profile.ts` exposes a four-profile model:
 
 | Profile | Trigger | Validation |
 |---|---|---|
-| `cloud` | `VERCEL=1` (set automatically by Vercel) | Strict — every integration key required |
+| `cloud` | `VERCEL=1` (set automatically at runtime on Vercel) | Strict — every integration key required |
 | `oss-dev` | `SUPERSET_OSS=1` | Lenient — integration keys optional, features degrade |
+| `ci` | `CI=true` (set automatically by GitHub Actions / most CI runners) | Lenient — lint/typecheck/test don't have integration keys |
 | `internal` | default | Strict — covers internal team dev + self-hosted prod |
 
 All env schemas (`apps/api/src/env.ts`, `packages/trpc/src/env.ts`, `apps/web/src/env.ts`, etc.) compute their `skipValidation` from this:

From 513d1989f3d87a450afbe56d54ef8bcb91f4eb12 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sat, 16 May 2026 15:54:11 -0700
Subject: [PATCH 05/28] fix: address review findings on PR #4616
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five real bugs/gaps from review:

#1 OSS sign-up no longer crashes on Stripe.
   afterCreateOrganization in packages/auth/src/server.ts now gates Stripe
   customer creation on env.STRIPE_SECRET_KEY presence. seedDefaultStatuses
   still runs unconditionally so org creation completes for OSS users.

#2 Email/password disabled in production.
   packages/auth/src/server.ts: emailAndPassword.enabled flips to
   `process.env.NODE_ENV !== "production"` to match the UI form gating.
   Prevents direct credential sign-up/sign-in via API in prod builds.

#3 Local Electric is now part of the OSS path, not a separate step.
   - docker-compose.dev.yml ships Postgres 16 + Electric 1.4.13 with
     wal_level=logical and host-port mappings (5433, 4649).
   - apps/electric-proxy/.dev.vars.example updated to match the
     docker-compose ports (4649) and default `bun dev` ports (3001).
   - apps/desktop/src/renderer/env.renderer.ts: hardcoded production
     defaults for NEXT_PUBLIC_API_URL, NEXT_PUBLIC_WEB_URL,
     NEXT_PUBLIC_ELECTRIC_URL, RELAY_URL now switch to localhost in
     dev builds — fresh-clone contributors no longer silently sync
     against hosted production Electric/API.
   - README + docs/LOCAL_DEVELOPMENT.md: replace bare `docker run` with
     `docker compose -f docker-compose.dev.yml up -d` and add the
     electric-proxy .dev.vars copy step.

#4 Dev auto-sign-in survives the race against API startup.
   apps/desktop/src/main/lib/dev-auto-sign-in.ts: poll /api/auth/ok
   with 1s interval and 60s timeout before attempting sign-in. main
   process calls it fire-and-forget (`void ensureDevAuthToken()`) so
   the window opens immediately; AuthProvider's onTokenChanged
   subscription re-hydrates when the token lands.

#5 Profile flags now hash into the Turbo cache key.
   turbo.jsonc: moved SUPERSET_OSS, CI, VERCEL, SKIP_ENV_VALIDATION
   from globalPassThroughEnv to globalEnv. Strict and lenient cached
   build outputs can no longer cross-contaminate.
---
 README.md                                     |  5 +-
 apps/desktop/src/main/index.ts                | 12 +++--
 apps/desktop/src/main/lib/dev-auto-sign-in.ts | 41 ++++++++++++++--
 apps/desktop/src/renderer/env.renderer.ts     | 34 ++++++++++++--
 apps/electric-proxy/.dev.vars.example         |  9 +++-
 docker-compose.dev.yml                        | 47 +++++++++++++++++++
 docs/LOCAL_DEVELOPMENT.md                     | 25 +++++-----
 packages/auth/src/server.ts                   | 32 ++++++++-----
 turbo.jsonc                                   | 14 +++---
 9 files changed, 170 insertions(+), 49 deletions(-)
 create mode 100644 docker-compose.dev.yml

diff --git a/README.md b/README.md
index 46b556a5ae5..6300e3cb8e2 100644
--- a/README.md
+++ b/README.md
@@ -93,10 +93,9 @@ Short version:
 git clone https://github.com/superset-sh/superset.git
 cd superset
 bun install
-docker run -d --name superset-pg \
-  -e POSTGRES_USER=superset -e POSTGRES_PASSWORD=superset -e POSTGRES_DB=superset \
-  -p 5433:5432 postgres:16 -c wal_level=logical
+docker compose -f docker-compose.dev.yml up -d   # Postgres + Electric
 cp .env.example .env   # then edit DATABASE_URL + BETTER_AUTH_SECRET
+cp apps/electric-proxy/.dev.vars.example apps/electric-proxy/.dev.vars
 bun run db:migrate
 cp Caddyfile.example Caddyfile && caddy trust
 SUPERSET_OSS=1 bun dev
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 4aec2cbea05..1e7302d2421 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -425,11 +425,13 @@ if (!gotTheLock) {
 			console.error("[main] Failed to install bundled CLI shim:", error);
 		}
 
-		// Dev-only: auto-sign-in as the seed admin if SKIP_ENV_VALIDATION is
-		// set and no token is on disk. Lets fresh-clone contributors boot the
-		// desktop without OAuth. Runs before host-service discovery so the
-		// renderer's AuthProvider hydrates with a valid token on first paint.
-		await ensureDevAuthToken();
+		// OSS-dev only: auto-sign-in as the seed admin if no token is on disk.
+		// Fire-and-forget — the function polls the API for readiness internally
+		// (Turbo starts services concurrently, the API may still be compiling).
+		// AuthProvider in the renderer subscribes to auth.onTokenChanged and
+		// will re-hydrate when the token lands, so window creation doesn't
+		// block on this.
+		void ensureDevAuthToken();
 
 		// Discover and adopt host-services that survived a previous quit
 		// before the tray initializes, so it shows accurate status immediately.
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
index 831bc607fa2..747a2b9aac2 100644
--- a/apps/desktop/src/main/lib/dev-auto-sign-in.ts
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -10,6 +10,11 @@ const DEV_PASSWORD = "supersetdev";
 const DEV_NAME = "Local Admin";
 const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
 
+// API may take a few seconds to compile on first dev launch (Turbo starts
+// services concurrently). Poll /api/auth/ok before giving up.
+const HEALTH_POLL_INTERVAL_MS = 1000;
+const HEALTH_POLL_TIMEOUT_MS = 60_000;
+
 interface SignInResponse {
 	token?: string;
 	user?: { id: string };
@@ -36,11 +41,31 @@ async function postAuth<T>(
 	return { ok: res.ok, status: res.status, data };
 }
 
+async function waitForApiReady(): Promise<boolean> {
+	const start = Date.now();
+	const url = `${mainEnv.NEXT_PUBLIC_API_URL}/api/auth/ok`;
+	while (Date.now() - start < HEALTH_POLL_TIMEOUT_MS) {
+		try {
+			const res = await fetch(url, {
+				signal: AbortSignal.timeout(2000),
+			});
+			if (res.ok) return true;
+		} catch {
+			// connection refused / timeout — keep polling
+		}
+		await new Promise((r) => setTimeout(r, HEALTH_POLL_INTERVAL_MS));
+	}
+	return false;
+}
+
 /**
- * Dev-only: if SKIP_ENV_VALIDATION is set and no usable token is on disk,
- * sign in (or sign up) as the seed admin user and persist the token so
- * the renderer's AuthProvider can hydrate normally — no special renderer code.
- * Best-effort: failure is logged but doesn't crash boot.
+ * Dev-only: in the oss-dev profile, sign in (or sign up) as the seed
+ * admin user and persist the token so the renderer's AuthProvider can
+ * hydrate normally — no special renderer code.
+ *
+ * Polls the API for readiness before attempting sign-in (Turbo starts
+ * services concurrently and the API may still be compiling on first
+ * launch). Best-effort: failure is logged but doesn't crash boot.
  */
 export async function ensureDevAuthToken(): Promise<void> {
 	// OSS-dev only — internal devs, self-hosters, and prod all use real auth.
@@ -52,6 +77,14 @@ export async function ensureDevAuthToken(): Promise<void> {
 		if (!isExpired) return;
 	}
 
+	const ready = await waitForApiReady();
+	if (!ready) {
+		console.warn(
+			`[dev-auto-sign-in] API at ${mainEnv.NEXT_PUBLIC_API_URL} did not respond within ${HEALTH_POLL_TIMEOUT_MS}ms — skipping. Use the sign-in form once the API is up.`,
+		);
+		return;
+	}
+
 	try {
 		let signIn = await postAuth<SignInResponse>("/api/auth/sign-in/email", {
 			email: DEV_EMAIL,
diff --git a/apps/desktop/src/renderer/env.renderer.ts b/apps/desktop/src/renderer/env.renderer.ts
index 445b0be9d46..aa9346e277a 100644
--- a/apps/desktop/src/renderer/env.renderer.ts
+++ b/apps/desktop/src/renderer/env.renderer.ts
@@ -15,16 +15,42 @@ const envSchema = z.object({
 	NODE_ENV: z
 		.enum(["development", "production", "test"])
 		.default("development"),
-	NEXT_PUBLIC_API_URL: z.url().default("https://api.superset.sh"),
-	NEXT_PUBLIC_WEB_URL: z.url().default("https://app.superset.sh"),
+	// Hosted defaults for prod builds. In dev builds Vite replaces
+	// NODE_ENV with "development", so the dev-time defaults below kick in
+	// and a fresh-clone contributor never silently syncs against
+	// production Electric / API.
+	NEXT_PUBLIC_API_URL: z
+		.url()
+		.default(
+			process.env.NODE_ENV === "development"
+				? "http://localhost:4641"
+				: "https://api.superset.sh",
+		),
+	NEXT_PUBLIC_WEB_URL: z
+		.url()
+		.default(
+			process.env.NODE_ENV === "development"
+				? "http://localhost:4640"
+				: "https://app.superset.sh",
+		),
 	NEXT_PUBLIC_MARKETING_URL: z.url().default("https://superset.sh"),
 	NEXT_PUBLIC_ELECTRIC_URL: z
 		.url()
-		.default("https://electric-proxy.avi-6ac.workers.dev"),
+		.default(
+			process.env.NODE_ENV === "development"
+				? "https://localhost:4650"
+				: "https://electric-proxy.avi-6ac.workers.dev",
+		),
 	NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
 	NEXT_PUBLIC_POSTHOG_HOST: z.string().default("https://us.i.posthog.com"),
 	SENTRY_DSN_DESKTOP: z.string().optional(),
-	RELAY_URL: z.url().default("https://relay.superset.sh"),
+	RELAY_URL: z
+		.url()
+		.default(
+			process.env.NODE_ENV === "development"
+				? "http://localhost:4653"
+				: "https://relay.superset.sh",
+		),
 });
 
 /**
diff --git a/apps/electric-proxy/.dev.vars.example b/apps/electric-proxy/.dev.vars.example
index afd284e77b0..f208fd415b0 100644
--- a/apps/electric-proxy/.dev.vars.example
+++ b/apps/electric-proxy/.dev.vars.example
@@ -1,5 +1,10 @@
-AUTH_URL=http://localhost:3141
-ELECTRIC_SHAPE_URL=http://localhost:3069/v1/shape
+# Defaults match docker-compose.dev.yml (Electric on host port 4649)
+# and the default `bun dev` ports (API on 3001).
+#
+# Internal devs: setup.sh regenerates this with per-workspace ports.
+# OSS contributors: cp .dev.vars.example .dev.vars and run `bun dev`.
+AUTH_URL=http://localhost:3001
+ELECTRIC_SHAPE_URL=http://localhost:4649/v1/shape
 ELECTRIC_SECRET=local_electric_dev_secret
 ELECTRIC_SOURCE_ID=
 ELECTRIC_SOURCE_SECRET=
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 00000000000..16e5bb8d8c8
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,47 @@
+# Local dev services for OSS contributors.
+#
+# Brings up Postgres + Electric SQL on stable host ports so a fresh clone
+# can talk to both immediately. Internal devs use `.superset/setup.sh`
+# instead (Neon branches + per-workspace Electric containers).
+#
+#   docker compose -f docker-compose.dev.yml up -d
+#
+# See docs/LOCAL_DEVELOPMENT.md for full setup.
+
+services:
+  postgres:
+    image: postgres:16
+    container_name: superset-pg
+    command: ["postgres", "-c", "wal_level=logical"]
+    environment:
+      POSTGRES_USER: superset
+      POSTGRES_PASSWORD: superset
+      POSTGRES_DB: superset
+    ports:
+      # 5433 to avoid clobbering a host Postgres on the default 5432
+      - "5433:5432"
+    volumes:
+      - superset-pg-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U superset -d superset"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+
+  electric:
+    image: electricsql/electric:1.4.13
+    container_name: superset-electric
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      # host.docker.internal lets the container reach Postgres on the
+      # host's 5433 port (mapped from the postgres service above).
+      DATABASE_URL: postgres://superset:superset@host.docker.internal:5433/superset
+      ELECTRIC_SECRET: local_electric_dev_secret
+    ports:
+      - "4649:3000"
+    restart: on-failure:5
+
+volumes:
+  superset-pg-data:
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 516f3378719..5e640d1d2c9 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -17,18 +17,17 @@ cd superset
 bun install
 ```
 
-**1. Start Postgres**
+**1. Start Postgres + Electric**
 
 ```bash
-docker run -d --name superset-pg \
-  -e POSTGRES_USER=superset \
-  -e POSTGRES_PASSWORD=superset \
-  -e POSTGRES_DB=superset \
-  -p 5433:5432 \
-  postgres:16 -c wal_level=logical
+docker compose -f docker-compose.dev.yml up -d
 ```
 
-Port `5433` avoids clobbering a host Postgres on the default `5432`. `wal_level=logical` is required for Electric SQL replication.
+Brings up:
+- **Postgres 16** on host port `5433` with `wal_level=logical` (Electric replication requires it). Port 5433 avoids clobbering any host Postgres on the default 5432.
+- **Electric SQL** on host port `4649`, replicating from the Postgres above.
+
+These containers stay running between sessions; `docker compose down -v` to wipe them.
 
 **2. Create your `.env`**
 
@@ -54,13 +53,15 @@ bun run db:migrate
 
 This creates the `auth` and `public` schemas and runs all Drizzle migrations. ~42 tables.
 
-**4. Set up Caddy (HTTPS proxy)**
+**4. Wire electric-proxy + Caddy (HTTPS proxy)**
 
 ```bash
+cp apps/electric-proxy/.dev.vars.example apps/electric-proxy/.dev.vars
 cp Caddyfile.example Caddyfile
 caddy trust   # one-time, prompts for sudo
 ```
 
+`.dev.vars` tells the Cloudflare Worker (electric-proxy) where to find your local Electric server (host port 4649 from docker-compose).
 Without `caddy trust`, Chromium will reject `https://localhost:*` with `ERR_CERT_AUTHORITY_INVALID`.
 
 ## Run it
@@ -173,9 +174,9 @@ pkill -f "turbo run dev"
 # Wipe data (auth token, host DBs, local app state)
 rm -rf superset-dev-data
 
-# Wipe Postgres
-docker rm -f superset-pg
-# then re-run the docker run from step 1
+# Wipe Postgres + Electric (including volume)
+docker compose -f docker-compose.dev.yml down -v
+docker compose -f docker-compose.dev.yml up -d
 ```
 
 ## Architecture notes for contributors
diff --git a/packages/auth/src/server.ts b/packages/auth/src/server.ts
index c24de12b7bc..c290770d393 100644
--- a/packages/auth/src/server.ts
+++ b/packages/auth/src/server.ts
@@ -89,8 +89,12 @@ export const auth = betterAuth({
 			generateId: false,
 		},
 	},
+	// Dev-only: email+password is enabled for OSS contributors and
+	// internal devs (NODE_ENV=development). In production builds the
+	// /sign-up/email and /sign-in/email endpoints are disabled — auth
+	// is OAuth-only there. Matches the UI form gating in apps/web.
 	emailAndPassword: {
-		enabled: true,
+		enabled: process.env.NODE_ENV !== "production",
 		autoSignIn: true,
 	},
 	socialProviders: {
@@ -358,19 +362,21 @@ export const auth = betterAuth({
 				},
 
 				afterCreateOrganization: async ({ organization, user }) => {
-					const customer = await stripeClient.customers.create({
-						name: organization.name,
-						email: user.email,
-						metadata: {
-							organizationId: organization.id,
-							organizationSlug: organization.slug,
-						},
-					});
+					if (env.STRIPE_SECRET_KEY) {
+						const customer = await stripeClient.customers.create({
+							name: organization.name,
+							email: user.email,
+							metadata: {
+								organizationId: organization.id,
+								organizationSlug: organization.slug,
+							},
+						});
 
-					await db
-						.update(authSchema.organizations)
-						.set({ stripeCustomerId: customer.id })
-						.where(eq(authSchema.organizations.id, organization.id));
+						await db
+							.update(authSchema.organizations)
+							.set({ stripeCustomerId: customer.id })
+							.where(eq(authSchema.organizations.id, organization.id));
+					}
 
 					await seedDefaultStatuses(organization.id);
 				},
diff --git a/turbo.jsonc b/turbo.jsonc
index 23b93a94b5c..1cad43a65e6 100644
--- a/turbo.jsonc
+++ b/turbo.jsonc
@@ -17,17 +17,19 @@
 		"POSTHOG_API_KEY",
 		"POSTHOG_PROJECT_ID",
 		"KV_REST_API_URL",
-		"KV_REST_API_TOKEN"
+		"KV_REST_API_TOKEN",
+		// Profile-affecting flags must hash into the cache key so
+		// strict and lenient builds never share cached outputs.
+		"SUPERSET_OSS",
+		"CI",
+		"VERCEL",
+		"SKIP_ENV_VALIDATION"
 	],
 	"globalPassThroughEnv": [
 		"NODE_ENV",
-		"CI",
-		"VERCEL",
 		"VERCEL_ENV",
 		"VERCEL_URL",
-		"npm_lifecycle_event",
-		"SKIP_ENV_VALIDATION",
-		"SUPERSET_OSS"
+		"npm_lifecycle_event"
 	],
 	"tasks": {
 		"build": {

From f3254efb55ede2ddc79d36aefab492f85bac56fe Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sat, 16 May 2026 16:21:51 -0700
Subject: [PATCH 06/28] fix: address CI build failure + remaining hardcoded
 prod URL defaults

## CI build failure (desktop build job)

electron.vite.config.ts does `await import("./src/main/env.main")` at
config-load time, which Node's ESM loader handles directly (no Vite
transform). When env.main.ts imported `@superset/shared/deployment-profile`
(a `.ts` file), Node refused with `ERR_UNKNOWN_FILE_EXTENSION`.

Fix: inline the 4-line profile check in env.main.ts. Other consumers
keep using the shared module (Next.js apps handle .ts via SWC).

## Remaining hardcoded prod URL defaults

The previous renderer-env fix only covered renderer/env.renderer.ts.
Three other build/runtime spots still defaulted to hosted production
URLs when env vars were absent:

- apps/desktop/vite/helpers.ts (htmlEnvTransformPlugin)
- apps/desktop/electron.vite.config.ts (define blocks for main +
  renderer process.env replacements)
- apps/desktop/src/main/env.main.ts (Zod schema .default())

All four now use NODE_ENV-conditional defaults. Added a `devOrProdUrl()`
helper in vite/helpers.ts to keep the pattern consistent.

A fresh-clone OSS contributor's app no longer silently syncs against
hosted production Electric / API / streams / relay when their .env
omits the URLs.

## Verified

- `bun run lint` clean
- `bun run --cwd apps/desktop typecheck` clean
- `bun turbo run build --filter=@superset/desktop` succeeds locally (the
  CI failure that prompted this commit)
---
 apps/desktop/electron.vite.config.ts | 71 ++++++++++++++++++++--------
 apps/desktop/src/main/env.main.ts    | 69 ++++++++++++++++++++++-----
 apps/desktop/vite/helpers.ts         | 42 ++++++++++++++--
 3 files changed, 145 insertions(+), 37 deletions(-)

diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.ts
index f11759ceaa2..33158924ed1 100644
--- a/apps/desktop/electron.vite.config.ts
+++ b/apps/desktop/electron.vite.config.ts
@@ -13,6 +13,7 @@ import { mainExternalizedDependencies } from "./runtime-dependencies";
 import {
 	copyResourcesPlugin,
 	defineEnv,
+	devOrProdUrl,
 	devPath,
 	htmlEnvTransformPlugin,
 } from "./vite/helpers";
@@ -53,17 +54,26 @@ export default defineConfig({
 				process.env.SKIP_ENV_VALIDATION,
 				"",
 			),
-			"process.env.NEXT_PUBLIC_API_URL": defineEnv(
-				process.env.NEXT_PUBLIC_API_URL,
-				"https://api.superset.sh",
+			"process.env.NEXT_PUBLIC_API_URL": JSON.stringify(
+				devOrProdUrl(
+					"NEXT_PUBLIC_API_URL",
+					"http://localhost:4641",
+					"https://api.superset.sh",
+				),
 			),
-			"process.env.NEXT_PUBLIC_STREAMS_URL": defineEnv(
-				process.env.NEXT_PUBLIC_STREAMS_URL,
-				"https://streams.superset.sh",
+			"process.env.NEXT_PUBLIC_STREAMS_URL": JSON.stringify(
+				devOrProdUrl(
+					"NEXT_PUBLIC_STREAMS_URL",
+					"http://localhost:4647",
+					"https://streams.superset.sh",
+				),
 			),
-			"process.env.NEXT_PUBLIC_WEB_URL": defineEnv(
-				process.env.NEXT_PUBLIC_WEB_URL,
-				"https://app.superset.sh",
+			"process.env.NEXT_PUBLIC_WEB_URL": JSON.stringify(
+				devOrProdUrl(
+					"NEXT_PUBLIC_WEB_URL",
+					"http://localhost:4640",
+					"https://app.superset.sh",
+				),
 			),
 			"process.env.NEXT_PUBLIC_MARKETING_URL": defineEnv(
 				process.env.NEXT_PUBLIC_MARKETING_URL,
@@ -76,7 +86,13 @@ export default defineConfig({
 			"process.env.SENTRY_DSN_DESKTOP": defineEnv(
 				process.env.SENTRY_DSN_DESKTOP,
 			),
-			"process.env.RELAY_URL": defineEnv(process.env.RELAY_URL),
+			"process.env.RELAY_URL": JSON.stringify(
+				devOrProdUrl(
+					"RELAY_URL",
+					"http://localhost:4653",
+					"https://relay.superset.sh",
+				),
+			),
 			// Must match renderer for analytics in main process
 			"process.env.NEXT_PUBLIC_POSTHOG_KEY": defineEnv(
 				process.env.NEXT_PUBLIC_POSTHOG_KEY,
@@ -170,21 +186,30 @@ export default defineConfig({
 				"",
 			),
 			"process.platform": defineEnv(process.platform),
-			"process.env.NEXT_PUBLIC_API_URL": defineEnv(
-				process.env.NEXT_PUBLIC_API_URL,
-				"https://api.superset.sh",
+			"process.env.NEXT_PUBLIC_API_URL": JSON.stringify(
+				devOrProdUrl(
+					"NEXT_PUBLIC_API_URL",
+					"http://localhost:4641",
+					"https://api.superset.sh",
+				),
 			),
-			"process.env.NEXT_PUBLIC_WEB_URL": defineEnv(
-				process.env.NEXT_PUBLIC_WEB_URL,
-				"https://app.superset.sh",
+			"process.env.NEXT_PUBLIC_WEB_URL": JSON.stringify(
+				devOrProdUrl(
+					"NEXT_PUBLIC_WEB_URL",
+					"http://localhost:4640",
+					"https://app.superset.sh",
+				),
 			),
 			"process.env.NEXT_PUBLIC_MARKETING_URL": defineEnv(
 				process.env.NEXT_PUBLIC_MARKETING_URL,
 				"https://superset.sh",
 			),
-			"process.env.NEXT_PUBLIC_ELECTRIC_URL": defineEnv(
-				process.env.NEXT_PUBLIC_ELECTRIC_URL,
-				"https://electric-proxy.avi-6ac.workers.dev",
+			"process.env.NEXT_PUBLIC_ELECTRIC_URL": JSON.stringify(
+				devOrProdUrl(
+					"NEXT_PUBLIC_ELECTRIC_URL",
+					"https://localhost:4650",
+					"https://electric-proxy.avi-6ac.workers.dev",
+				),
 			),
 			"process.env.NEXT_PUBLIC_DOCS_URL": defineEnv(
 				process.env.NEXT_PUBLIC_DOCS_URL,
@@ -200,7 +225,13 @@ export default defineConfig({
 			"import.meta.env.SENTRY_DSN_DESKTOP": defineEnv(
 				process.env.SENTRY_DSN_DESKTOP,
 			),
-			"process.env.RELAY_URL": defineEnv(process.env.RELAY_URL),
+			"process.env.RELAY_URL": JSON.stringify(
+				devOrProdUrl(
+					"RELAY_URL",
+					"http://localhost:4653",
+					"https://relay.superset.sh",
+				),
+			),
 			"process.env.STREAMS_URL": defineEnv(
 				process.env.STREAMS_URL,
 				"https://superset-stream.fly.dev",
diff --git a/apps/desktop/src/main/env.main.ts b/apps/desktop/src/main/env.main.ts
index d34d74b304b..049bc30aad9 100644
--- a/apps/desktop/src/main/env.main.ts
+++ b/apps/desktop/src/main/env.main.ts
@@ -6,38 +6,81 @@
  *
  * For renderer process env vars, use src/renderer/env.renderer.ts instead.
  */
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod/v4";
 
+// NOTE: the deployment-profile check is inlined here rather than imported
+// from @superset/shared/deployment-profile because electron.vite.config.ts
+// does `await import("./src/main/env.main")` at config-load time, which
+// Node's ESM loader handles directly (no Vite transform) — and Node can't
+// load `.ts` files from sibling workspace packages. Keep the helper in
+// shared/, but duplicate the four lines here.
+//
 // Default profile is `internal` (strict). OSS contributors set
 // SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
 // skips env validation so a fresh clone boots without every key.
+// CI=true (auto-set by GitHub Actions) also opts into lenient so
+// build/lint/test jobs work without prod secrets.
 // SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const isStrict =
+	process.env.VERCEL === "1" ||
+	(process.env.SUPERSET_OSS !== "1" && process.env.CI !== "true");
+const skipValidation = !isStrict || !!process.env.SKIP_ENV_VALIDATION;
 
 export const env = createEnv({
 	server: {
 		NODE_ENV: z
 			.enum(["development", "production", "test"])
 			.default("development"),
-		NEXT_PUBLIC_API_URL: z.url().default("https://api.superset.sh"),
-		NEXT_PUBLIC_STREAMS_URL: z.url().default("https://streams.superset.sh"),
+		// In dev builds (NODE_ENV=development) the URL defaults switch to
+		// localhost so fresh-clone OSS contributors never silently sync
+		// against hosted production endpoints.
+		NEXT_PUBLIC_API_URL: z
+			.url()
+			.default(
+				process.env.NODE_ENV === "development"
+					? "http://localhost:4641"
+					: "https://api.superset.sh",
+			),
+		NEXT_PUBLIC_STREAMS_URL: z
+			.url()
+			.default(
+				process.env.NODE_ENV === "development"
+					? "http://localhost:4647"
+					: "https://streams.superset.sh",
+			),
 		NEXT_PUBLIC_ELECTRIC_URL: z
 			.url()
-			.default("https://electric-proxy.avi-6ac.workers.dev"),
-		NEXT_PUBLIC_WEB_URL: z.url().default("https://app.superset.sh"),
+			.default(
+				process.env.NODE_ENV === "development"
+					? "https://localhost:4650"
+					: "https://electric-proxy.avi-6ac.workers.dev",
+			),
+		NEXT_PUBLIC_WEB_URL: z
+			.url()
+			.default(
+				process.env.NODE_ENV === "development"
+					? "http://localhost:4640"
+					: "https://app.superset.sh",
+			),
 		NEXT_PUBLIC_MARKETING_URL: z.url().default("https://superset.sh"),
 		NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
 		NEXT_PUBLIC_POSTHOG_HOST: z.string().default("https://us.i.posthog.com"),
 		SENTRY_DSN_DESKTOP: z.string().optional(),
-		STREAMS_URL: z.url().default("https://superset-stream.fly.dev"),
-		RELAY_URL: z.url().default("https://relay.superset.sh"),
+		STREAMS_URL: z
+			.url()
+			.default(
+				process.env.NODE_ENV === "development"
+					? "http://localhost:4647"
+					: "https://superset-stream.fly.dev",
+			),
+		RELAY_URL: z
+			.url()
+			.default(
+				process.env.NODE_ENV === "development"
+					? "http://localhost:4653"
+					: "https://relay.superset.sh",
+			),
 	},
 
 	runtimeEnv: {
diff --git a/apps/desktop/vite/helpers.ts b/apps/desktop/vite/helpers.ts
index b2552e2dba6..fd4c4c949c0 100644
--- a/apps/desktop/vite/helpers.ts
+++ b/apps/desktop/vite/helpers.ts
@@ -23,6 +23,25 @@ export function defineEnv(
 	return JSON.stringify(value ?? fallback);
 }
 
+/**
+ * Returns a URL appropriate for the current build:
+ *   - the configured `process.env[key]` if set
+ *   - the dev fallback in development builds (fresh-clone OSS contributors)
+ *   - the prod fallback otherwise (hosted production)
+ *
+ * Avoids fresh-clone OSS dev sessions silently syncing against hosted
+ * production Electric / API / relay endpoints.
+ */
+export function devOrProdUrl(
+	envKey: string,
+	devFallback: string,
+	prodFallback: string,
+): string {
+	const value = process.env[envKey];
+	if (value) return value;
+	return process.env.NODE_ENV === "development" ? devFallback : prodFallback;
+}
+
 const RESOURCES_TO_COPY = [
 	{
 		src: resolve(__dirname, "..", resources, "sounds"),
@@ -76,22 +95,37 @@ export function htmlEnvTransformPlugin(): Plugin {
 			return html
 				.replace(
 					/%NEXT_PUBLIC_API_URL%/g,
-					process.env.NEXT_PUBLIC_API_URL || "https://api.superset.sh",
+					devOrProdUrl(
+						"NEXT_PUBLIC_API_URL",
+						"http://localhost:4641",
+						"https://api.superset.sh",
+					),
 				)
 				.replace(
 					/%NEXT_PUBLIC_ELECTRIC_URL%/g,
 					new URL(
-						process.env.NEXT_PUBLIC_ELECTRIC_URL ||
+						devOrProdUrl(
+							"NEXT_PUBLIC_ELECTRIC_URL",
+							"https://localhost:4650",
 							"https://electric-proxy.avi-6ac.workers.dev",
+						),
 					).origin,
 				)
 				.replace(
 					/%NEXT_PUBLIC_STREAMS_URL%/g,
-					process.env.NEXT_PUBLIC_STREAMS_URL || "https://streams.superset.sh",
+					devOrProdUrl(
+						"NEXT_PUBLIC_STREAMS_URL",
+						"http://localhost:4647",
+						"https://streams.superset.sh",
+					),
 				)
 				.replace(
 					/%RELAY_URL%/g,
-					process.env.RELAY_URL || "https://relay.superset.sh",
+					devOrProdUrl(
+						"RELAY_URL",
+						"http://localhost:4653",
+						"https://relay.superset.sh",
+					),
 				);
 		},
 	};

From 7be895d5a618d6c008f34db0b9127abf0f80c70d Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sat, 16 May 2026 20:18:15 -0700
Subject: [PATCH 07/28] docs: comprehensive design record for OSS local setup
 PR

Rewrites plans/20260515-oss-local-setup.md as the authoritative
'what shipped + why' document. Sections:

- Goal + three-audience requirements
- Final 4-profile design (cloud/oss-dev/ci/internal)
- What's wired into each part of the stack, with file paths
- Decisions made (with rejected alternatives + rationale)
- Lessons learned (8 surprises encountered during build)
- Commit-by-commit history of what was built
- Verification protocol (smoke test outputs, profile resolution
  unit cases, CDP probe, local CI reproduction)
- Honest TODO of what's still deferred
- Architecture diagrams (profile resolution flow, OSS session
  lifecycle, strictness x visibility matrix)
---
 plans/20260515-oss-local-setup.md | 393 +++++++++++++++++++++---------
 1 file changed, 283 insertions(+), 110 deletions(-)

diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index d02f733fbbd..0623f78f648 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -1,171 +1,344 @@
-# OSS Local Setup — What Shipped + What's Left
+# OSS Local Setup — Complete Record
 
-This was originally a forward-looking plan; now it's a record of what was actually built, verified, and what's still loose. Contributor-facing setup instructions live in `docs/LOCAL_DEVELOPMENT.md`.
+Authoritative design record for PR [#4616](https://github.com/superset-sh/superset/pull/4616). Contributor-facing setup instructions live in [docs/LOCAL_DEVELOPMENT.md](../docs/LOCAL_DEVELOPMENT.md).
 
-## Status
+## Goal
 
-A fresh-clone contributor can:
+A contributor cloning Superset from GitHub can boot the full web + API + Electric + electric-proxy + Caddy + desktop stack against a local Postgres in Docker, **without Neon, OAuth, Stripe, Resend, GitHub App, Linear, Slack, QStash, Upstash, PostHog, Sentry, Freestyle, or any other cloud-service credentials**. The internal team's fail-fast workflow stays unchanged, and production stays strictly validated.
 
-1. `git clone … && cd superset && bun install`
-2. Start a local Postgres container with `wal_level=logical` on host port 5433
-3. Run `bun run db:migrate` to apply schema
-4. `SKIP_ENV_VALIDATION=1 bun dev`
+## Requirements
 
-…and have a working web + API + Electric + electric-proxy + Caddy + desktop stack, signed in as a seed admin, with the host-service spawned and reachable. **Verified end-to-end via CDP** (Chrome DevTools Protocol probing the Electron renderer at port 9333) — the React context for `LocalHostServiceContext` reports `activeHostUrl: "http://127.0.0.1:<port>"`, so the "Host service not available" gate is open.
+Three audiences with different expectations:
 
-## What was built (with file paths)
+1. **OSS contributor (fresh GitHub clone)**
+   - Has Docker + Bun, nothing else
+   - Wants `git clone && SUPERSET_OSS=1 bun dev` to land them in a working app, signed in
+   - Features that need cloud keys should degrade visibly, never crash boot
+   - Must not silently sync against hosted production endpoints
 
-### Database
+2. **Internal team dev (existing workflow)**
+   - Uses `.superset/setup.sh` to provision per-worktree Neon branches + real cloud keys
+   - Same fail-fast behavior they have today on missing keys
+   - No new flags to type, no shell-config changes, no documentation to memorize
 
-- **`packages/db/src/client.ts`** — driver swap: detects non-Neon `DATABASE_URL` and uses Drizzle's `node-postgres` adapter via `pg.Pool` instead of `@neondatabase/serverless`. ~20 LOC.
-- **`packages/db/package.json`** — adds `pg` + `@types/pg`.
-- **`drizzle-kit migrate`** is the right command against a fresh DB. `drizzle-kit push` has multi-schema ordering issues against a vanilla Postgres; `migrate` applies committed `.sql` files in order and just works.
+3. **Production (Vercel + self-host)**
+   - Strict env validation: missing required key → deploy fails before serving traffic
+   - All visibility/observability surfaces report what's actually configured
+
+## Final design — four deployment profiles
+
+`packages/shared/src/deployment-profile.ts`:
+
+| Profile     | Trigger                                  | Validation | Notes |
+|-------------|------------------------------------------|------------|-------|
+| `cloud`     | `VERCEL=1` (auto, set by Vercel runtime) | Strict     | Untypable by contributor |
+| `oss-dev`   | `SUPERSET_OSS=1`                         | Lenient    | Explicit OSS opt-in |
+| `ci`        | `CI=true` (auto by GH Actions et al.)    | Lenient    | Build/lint/test don't need prod secrets |
+| `internal`  | default                                  | Strict     | Covers internal team dev + self-hosted prod |
+
+Resolution order in `getDeploymentProfile()` (most-trusted wins):
+
+```ts
+if (env.VERCEL === "1")        return "cloud";
+if (env.SUPERSET_OSS === "1")  return "oss-dev";
+if (env.CI === "true")         return "ci";
+return "internal";
+```
+
+Each env schema (`apps/api`, `apps/web`, `apps/admin`, `apps/marketing`, `apps/docs`, `apps/relay`, `apps/desktop/src/main/env.main`, `packages/trpc`) computes:
+
+```ts
+const skipValidation =
+  !isStrictProfile(getDeploymentProfile()) ||
+  !!process.env.SKIP_ENV_VALIDATION;
+```
+
+`SKIP_ENV_VALIDATION=1` remains a build-time escape hatch (Docker preview builds, etc.) — not the primary discriminator.
+
+## What's wired
+
+### Database layer
+
+- **`packages/db/src/client.ts`** — driver swap. Detects non-Neon `DATABASE_URL` (regex on `*.neon.tech` / `*.neon.build`) and uses `drizzle-orm/node-postgres` with `pg.Pool` instead of `@neondatabase/serverless`. The Neon driver only speaks Neon's HTTP/WS protocol, not vanilla Postgres TCP.
+- **`packages/db/src/seed-dev.ts`** — `bun db:seed:dev` script. POSTs to `/api/auth/sign-up/email` to create `admin@local.test / supersetdev`. Refuses to run in production or against non-localhost `DATABASE_URL`. Idempotent.
+- **`docker-compose.dev.yml`** — Postgres 16 with `wal_level=logical` on host port 5433, Electric SQL 1.4.13 on host port 4649 reading from the Postgres above via `host.docker.internal`. Health-checked.
 
 ### Auth
 
-- **`packages/auth/src/server.ts`** — added `emailAndPassword: { enabled: true, autoSignIn: true }`. OAuth providers (Google, GitHub) still register conditionally based on their `*_CLIENT_ID` env vars; Better Auth itself logs a warning when those are missing — no crash.
-- **`packages/auth/src/lib/resend.ts`** — lazy-init + console-log fallback when `RESEND_API_KEY` is empty. Better Auth's `sendEmail` hook calls this; in dev with no key, emails are logged to the terminal.
-- **`packages/auth/src/stripe.ts`** — `Proxy` lazy-init; throws "Stripe not configured" only if a billing operation is actually exercised.
+- **`packages/auth/src/server.ts`** — `emailAndPassword: { enabled: NODE_ENV !== "production", autoSignIn: true }`. Direct credential endpoints removed in prod builds. `afterCreateOrganization` hook gates Stripe customer creation on `env.STRIPE_SECRET_KEY` presence; `seedDefaultStatuses` always runs so OSS users complete org provisioning cleanly. OAuth providers register conditionally on their `*_CLIENT_ID`.
+- **`packages/auth/src/lib/resend.ts`** — `Proxy` lazy-init with batch + emails console fallback when `RESEND_API_KEY` empty. Better Auth's `sendEmail` hook writes to terminal instead of crashing.
+- **`packages/auth/src/stripe.ts`** — `Proxy` lazy-init. Throws "Stripe not configured" only when a billing operation is exercised.
+- **`packages/trpc/src/router/support/support.ts`** — same lazy-init Proxy pattern for the support email path.
 
-### Telemetry / analytics
+### Desktop main process
 
-- **`apps/api/src/lib/analytics.ts`** + **`packages/trpc/src/lib/analytics.ts`** — PostHog `Proxy` lazy-init; returns a no-op surface (`capture`, `getFeatureFlag`, etc. all no-op) when `NEXT_PUBLIC_POSTHOG_KEY` is empty. Previously crashed at module load.
+- **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — fired once during `app.whenReady()` when `getDeploymentProfile() === "oss-dev"`. Polls `/api/auth/ok` with 1s interval × 60s timeout (auto-sign-in survives the race against API startup), then POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if missing). Persists the token via the same `saveToken()` that OAuth uses. Renderer stays prod-pure.
+- **`apps/desktop/src/main/index.ts`** — calls `void ensureDevAuthToken()` (fire-and-forget) so the window opens immediately. `AuthProvider`'s `onTokenChanged` subscription re-hydrates when the token lands. Also exposes Chrome DevTools Protocol on `localhost:9333` in `oss-dev` for headless verification.
+- **`apps/desktop/src/main/env.main.ts`** — env defaults switch to localhost in dev builds (`NODE_ENV=development`) so a fresh-clone session never silently points main-process clients at hosted production. Profile check inlined here (rather than imported from `@superset/shared`) because `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time using Node's ESM loader, which can't transform `.ts` files from sibling workspace packages.
 
-### Other lazy-init guards
+### Desktop renderer
 
-- **`packages/trpc/src/router/support/support.ts`** — Resend `Proxy` lazy-init.
+- **`apps/desktop/src/renderer/env.renderer.ts`** — env defaults switch to localhost in dev builds for `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WEB_URL`, `NEXT_PUBLIC_ELECTRIC_URL`, `RELAY_URL`. Fresh-clone renderer never syncs against hosted Electric.
+- **`apps/desktop/src/renderer/routes/_authenticated/.../*`** (16 files) — flipped `env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : session.activeOrganizationId` to `session.activeOrganizationId ?? (env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null)`. Prefer real session, fall back to mock only when there is no session. Fixed the "Host service not available" toast caused by the renderer querying host-service by the fake org ID while host-service spawned for the real auto-signed-in admin org.
 
-### Dev auto-sign-in (the cleanest part)
+### Build pipeline
 
-- **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — new file. During `app.whenReady()`, if `SKIP_ENV_VALIDATION` is set and no token is on disk, POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if needed), then calls `saveToken()` to write `auth-token.enc`. The renderer's `AuthProvider` is **untouched** — it hydrates from disk like a real OAuth user.
-- **`apps/desktop/src/main/index.ts`** — calls `ensureDevAuthToken()` after `app.whenReady()`, before host-service discovery. Also enables Chrome DevTools Protocol on `localhost:9333` in dev for headless testing.
-- **`packages/db/src/seed-dev.ts`** — `bun db:seed:dev` script. POSTs to the API to create `admin@local.test / supersetdev`. Refuses to run if `NODE_ENV === "production"` or `DATABASE_URL` hostname isn't localhost. Idempotent.
+- **`apps/desktop/electron.vite.config.ts`** + **`apps/desktop/vite/helpers.ts`** — added `devOrProdUrl()` helper that returns `process.env[key]` if set, else a dev-vs-prod fallback based on `NODE_ENV`. Used in `define` blocks for main + renderer `process.env` replacements and in `htmlEnvTransformPlugin` for `%NEXT_PUBLIC_*%` placeholders in `index.html`. Builds default to localhost-friendly URLs in dev mode.
 
-### Renderer org-id priority fix (the actual host-service bug)
+### Web app
 
-- 16 files under `apps/desktop/src/renderer/routes/_authenticated/`, plus `routes/sign-in/page.tsx`. The original pattern was `env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : session.activeOrganizationId`, which forced the renderer to use a fake org ID even when a real session was present. With dev auto-sign-in producing a real session, the renderer was looking up the host-service by `MOCK_ORG_ID` while the host-service had spawned for the real org — connection lookup returned undefined, "Host service not available" toast fired.
-- Flipped to `session.activeOrganizationId ?? (SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null)` — prefer real session, fall back to mock only without one. Verified via CDP that `activeHostUrl` is now populated.
+- **`apps/web/src/app/(auth)/components/DevAuthForm/`** — email/password form, gated `NODE_ENV !== "production"`. Prefilled with seed credentials so contributors click "Sign in" once.
+- **`apps/web/src/app/(auth)/sign-in/.../page.tsx`** + **`sign-up/.../page.tsx`** — wire the form.
 
-### Dev UI
+### Telemetry / observability
 
-- **`apps/web/src/app/(auth)/components/DevAuthForm/`** — email/password form rendered on the web app's sign-in and sign-up pages, gated `process.env.NODE_ENV !== "production"`. Prefilled with the seed credentials. Same `authClient.signIn.email` underneath.
-- **`apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx`** + **`sign-up/[[...sign-up]]/page.tsx`** — wire the form.
+- **`apps/api/src/lib/analytics.ts`** + **`packages/trpc/src/lib/analytics.ts`** — PostHog `Proxy` lazy-init returning a no-op surface (`capture`, `getFeatureFlag`, etc.) when `NEXT_PUBLIC_POSTHOG_KEY` is missing.
+- **`apps/api/src/lib/boot-summary.ts`** — one-time API startup log printing every disabled integration and the env var to enable it. Visible to contributors so degradation is never silent.
+- **`apps/api/src/app/api/health/route.ts`** — `GET /api/health` returns `{ ok, profile, integrations: { stripe: "configured" | "missing", … } }` for prod monitoring + contributor sanity checks.
 
 ### Plumbing
 
-- **`turbo.jsonc`** — added `SKIP_ENV_VALIDATION` to `globalPassThroughEnv` so the flag reaches every dev subtask.
-- **`package.json`** — added `bun db:seed:dev` root script.
+- **`turbo.jsonc`** — `SUPERSET_OSS`, `CI`, `VERCEL`, `SKIP_ENV_VALIDATION` moved to `globalEnv` (was `globalPassThroughEnv`). Profile-affecting flags now hash into the cache key so strict/lenient cached builds can't cross-contaminate.
+- **`package.json`** — `bun db:seed:dev` root script.
 
-### Production safety
+### Docs
 
-- The dev auto-sign-in module checks `mainEnv.SKIP_ENV_VALIDATION` (which is itself gated to `NODE_ENV === "development"` in `apps/desktop/src/main/env.main.ts`). It cannot run in a production build.
-- `db:seed:dev` refuses to run against non-localhost DBs and in production.
-- The DevAuthForm only renders when `NODE_ENV !== "production"`.
-- The Chrome DevTools Protocol port (9333) only opens when both `IS_DEV` and `SKIP_ENV_VALIDATION` are set.
+- **`docs/LOCAL_DEVELOPMENT.md`** — contributor-facing setup guide.
+- **`README.md`** — `Build from Source` section shrunk to a 6-line quickstart, pointed at `docs/LOCAL_DEVELOPMENT.md`.
 
-## Deployment profiles (the key abstraction)
+## Decisions made (with rejected alternatives)
 
-`packages/shared/src/deployment-profile.ts` exposes a four-profile model:
+### Why profile-aware `skipValidation` instead of marking ~70 integration vars `.optional()` everywhere?
 
-| Profile | Trigger | Validation |
-|---|---|---|
-| `cloud` | `VERCEL=1` (set automatically at runtime on Vercel) | Strict — every integration key required |
-| `oss-dev` | `SUPERSET_OSS=1` | Lenient — integration keys optional, features degrade |
-| `ci` | `CI=true` (set automatically by GitHub Actions / most CI runners) | Lenient — lint/typecheck/test don't have integration keys |
-| `internal` | default | Strict — covers internal team dev + self-hosted prod |
+**Rejected:** Mark each integration key `.optional()`, fix every consumer that types it as `string`. The "Formbricks pattern."
 
-All env schemas (`apps/api/src/env.ts`, `packages/trpc/src/env.ts`, `apps/web/src/env.ts`, etc.) compute their `skipValidation` from this:
+**Chosen:** Keep schemas as-is, flip `skipValidation` based on profile. Lazy guards at call sites catch the crashes.
 
-```ts
-const skipValidation = !isStrictProfile(getDeploymentProfile()) || !!process.env.SKIP_ENV_VALIDATION;
-```
+**Why:** The Formbricks refactor would touch ~70 schema entries and ~100+ consumer sites that assume non-null. The skipValidation approach is one line per env file, no consumer changes, and the runtime behavior is identical: in OSS, the env object has whatever's in `process.env` (possibly empty strings); call sites that crash get wrapped in lazy guards as discovered.
+
+### Why strict-by-default with `SUPERSET_OSS=1` opt-in, not lenient-by-default with `SUPERSET_INTERNAL_DEV=1` opt-in?
+
+**Rejected:** Default to lenient + write `SUPERSET_INTERNAL_DEV=1` from `.superset/setup.sh` so internal devs land in strict.
+
+**Chosen:** Default to strict + OSS contributors set `SUPERSET_OSS=1`.
+
+**Why:** Strict-by-default is the conservative direction. An internal dev or self-hoster who forgets to source their `.env` gets a clear failure, not a silently-degraded app. OSS contributors trade a one-time flag for that safety guarantee. Also: no setup-script edit means internal devs' workflow is byte-identical to today.
+
+### Why not gate on `NODE_ENV === "production"` instead of `VERCEL=1`?
+
+**Rejected:** Use `NODE_ENV === "production"` as the cloud discriminator.
+
+**Chosen:** `VERCEL=1` (auto at Vercel runtime) for cloud, `NODE_ENV` only as a fallback indicator inside the `internal` default.
+
+**Why:** `NODE_ENV=production` is true in self-hosted dev too — it conflates "deployed to Vercel" with "operator running the production build locally." Self-hosters are legitimate prod operators and we want them strict, but they have different keys than Vercel (no `VERCEL_*` vars, no Vercel-specific URLs). Discriminating on `VERCEL=1` keeps cloud and self-hosted as two distinct strict-validated buckets.
+
+### Why a `ci` profile when `SKIP_ENV_VALIDATION=1` already exists?
+
+**Rejected:** Have CI workflows explicitly set `SKIP_ENV_VALIDATION=1` for lint/typecheck/test jobs.
+
+**Chosen:** Auto-detect `CI=true` (set by GitHub Actions and most CI runners) and treat as lenient.
+
+**Why:** Zero-config — existing workflows don't need to add env vars. And the profile is reported correctly in the boot summary + `/api/health`, so it's clear in logs that the build is lenient. `SKIP_ENV_VALIDATION=1` remains the explicit one-off escape hatch.
+
+### Why move profile-affecting flags from `globalPassThroughEnv` to `globalEnv`?
+
+**Rejected:** Pass-through (cheap, no cache invalidation).
+
+**Chosen:** Hash into the cache key.
+
+**Why:** A `bun run build` cached with `SUPERSET_OSS=1` (validation skipped) could be served back when the next caller doesn't have the flag (validation expected). Same for `CI=true` vs not. Caches that disagree about validation produce bugs that are very hard to attribute. Cache invalidation cost is acceptable — these flags don't flip often.
+
+### Why dev auto-sign-in in the main process, not the renderer?
+
+**Initial attempt:** Put it in `AuthProvider` (renderer).
+
+**Rejected because:** Mixes dev seed concerns with prod auth hydration. `AuthProvider` becomes "auth + dev seeding." Race conditions with React render lifecycle. Easy to accidentally ship to prod bundles.
 
-OSS contributors: set `SUPERSET_OSS=1` once → validation skipped → boot with whatever's in `.env`, lazy guards catch the crashes.
-Internal devs: nothing changes → validation runs → fail-fast on missing keys, exactly today's experience.
-Cloud (Vercel): same as before, strict enforcement of all keys.
-Self-hosted: defaults to strict — operators get a loud error if they miss something.
+**Chosen:** Main process during `app.whenReady()`. Uses the same `saveToken()` OAuth uses. Renderer is 100% upstream-pure — has no idea dev mode exists.
 
-**Strict-by-default** is the conservative direction:
-- Internal devs and self-hosters keep their fail-fast workflow with zero changes to setup or shell config.
-- An internal dev who accidentally drops their `.env` gets the same loud error they get today.
-- An OSS contributor only has to type one flag (`SUPERSET_OSS=1`) — and gets explicit "you're in lenient mode" feedback via the boot summary.
+### Why fire-and-forget instead of blocking window creation on auto-sign-in?
 
-`SKIP_ENV_VALIDATION=1` remains the build-time escape hatch (e.g. Docker preview builds), routed through `turbo.jsonc`'s `globalPassThroughEnv`. Not the primary discriminator.
+**Initial attempt:** `await ensureDevAuthToken()` before `MainWindow()`.
 
-### Boot-time visibility
+**Rejected because:** If the API takes 30s to compile on first launch, the desktop window is blank for 30s with no feedback. Bad UX.
 
-`apps/api/src/lib/boot-summary.ts` prints a one-time summary at API startup listing every disabled integration:
+**Chosen:** `void ensureDevAuthToken()` — window opens immediately. The function polls `/api/auth/ok` internally with backoff. `AuthProvider.onTokenChanged` subscription picks up the token whenever it eventually lands and re-hydrates the renderer's session.
+
+### Why inline the profile check in `env.main.ts` instead of importing from `@superset/shared`?
+
+**Rejected:** Single canonical import.
+
+**Chosen:** Inline the four-line check in `env.main.ts` only; other consumers import from `@superset/shared/deployment-profile`.
+
+**Why:** `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time to validate env at build. Node's native ESM loader handles that import — it has no Vite/SWC/TS transform — so any transitive `.ts` import from a sibling workspace package fails with `ERR_UNKNOWN_FILE_EXTENSION`. Discovered the hard way when CI build failed. The four lines of duplication are a fair trade for not breaking the build.
+
+## Lessons learned
+
+### `neondatabase/neon_local` is not a Neon protocol emulator
+
+It requires `NEON_PROJECT_ID` + `NEON_API_KEY` and acts as a *proxy* to a real Neon project. Useless for OSS. We discovered this only by running it. Plain `postgres:16 -c wal_level=logical` is the right substrate; pair it with a driver swap.
+
+### `@neondatabase/serverless` cannot speak vanilla Postgres TCP
+
+The serverless driver only knows Neon's HTTP/WS protocol. Verified by running it against a local Postgres — fails with "Unable to connect." Driver swap is unavoidable (~20 LOC), not a config flag.
+
+### Most integrations degrade gracefully on their own
+
+Better Auth social providers, Upstash KV, QStash all log warnings on missing keys and keep working. Only **Stripe, Resend, PostHog, and the trpc support router** crashed at module load. The plan's "guard a dozen integrations" overestimated; actual scope was 4 files.
+
+### The renderer had a hidden dev-mode landmine
+
+16 places overrode `activeOrganizationId` to `MOCK_ORG_ID` whenever `SKIP_ENV_VALIDATION` was set — a hack from when dev mode had no real session. With the new main-process auto-sign-in producing a real session with a real org, the renderer was looking up host-service connections by the fake mock org while host-service had spawned for the real org → "Host service not available" toast. Flipping the priority (`session.org ?? (devMode ? mock : null)`) fixed all 16 sites with the same one-line pattern.
+
+### Vite/Turbopack caches can mask real bugs during iteration
+
+A mid-process `.next/` deletion left the dev server in a corrupted state — every route returned 404 even though the files existed. Full clean-restart fixed it. Don't trust caches during refactoring; reset between iterations.
+
+### `electron-vite build` uses Node's native ESM loader for its config
+
+`electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time, which Node handles directly. Any transitive `.ts` import from a sibling workspace package crashes the build. Workspace packages exporting `.ts` files (the common monorepo pattern here) only work for consumers that go through a transform layer.
+
+### CDP is invaluable for verifying renderer state without manual clicks
+
+Enabling Chrome DevTools Protocol in the Electron main process (one line of `app.commandLine.appendSwitch`) let me probe the React context for `activeHostUrl` directly. Confirmed the fix without needing to click "Import" in the UI. Faster + more honest than asking the user to retry.
+
+### Most upstream OSS projects don't multi-profile cleanly
+
+The previous research agent found nobody in the OSS reference class (Cal.com, Documenso, Plane, Twenty, Supabase, Formbricks) does true three-or-four-profile env validation. The closest is Formbricks (`createFinalSchema` + per-group `.refine()`). The pattern we shipped — `getDeploymentProfile()` + profile-keyed `skipValidation` + boot summary + `/api/health` — is novel relative to that ref class.
+
+### CI build failures are a fast feedback loop you should actually use
+
+I shipped the deployment-profile changes without checking `gh pr checks 4616`. The build broke. Next time: `gh pr checks` is part of the post-push ritual.
+
+## What was built — commit-by-commit
+
+| Commit | Theme |
+|---|---|
+| [`04130c0`](https://github.com/superset-sh/superset/pull/4616/commits/04130c0) | Core OSS path: DB driver swap, lazy-init guards (Stripe/Resend/PostHog), Better Auth email/password, desktop dev auto-sign-in, 17-file MOCK_ORG_ID priority fix, web app DevAuthForm, `db:seed:dev`, CDP for verification, docs |
+| [`2b609b5`](https://github.com/superset-sh/superset/pull/4616/commits/2b609b5) | Deployment profiles + boot summary + `/api/health` endpoint |
+| [`f3c76b9`](https://github.com/superset-sh/superset/pull/4616/commits/f3c76b9) | Flipped discriminator (strict by default, `SUPERSET_OSS=1` opts into lenient) |
+| [`101cd30`](https://github.com/superset-sh/superset/pull/4616/commits/101cd30) | Added `ci` profile (GitHub Actions auto-detect) |
+| [`513d198`](https://github.com/superset-sh/superset/pull/4616/commits/513d198) | Five review-finding fixes: Stripe gate in `afterCreateOrganization`, email/password disabled in prod, docker-compose.dev.yml + Electric URL defaults, auto-sign-in API readiness poll, profile flags hash into Turbo cache |
+| [`f3254ef`](https://github.com/superset-sh/superset/pull/4616/commits/f3254ef) | Fixed CI build (inlined profile check in `env.main.ts`); remaining hardcoded prod URL defaults switched to `devOrProdUrl()` helper across `electron.vite.config.ts`, `vite/helpers.ts`, `env.main.ts` |
+
+## Verification
+
+End-to-end smoke test after final commit:
 
 ```
 [superset] profile=oss-dev (lenient)
 [superset] disabled features (set the listed env var to enable):
            - stripe                       STRIPE_SECRET_KEY
            - resend (email)               RESEND_API_KEY
-           - ...
+           - posthog (telemetry)          NEXT_PUBLIC_POSTHOG_KEY
+           …
+[dev-auto-sign-in] signed in as admin@local.test
+[host-service:b499daed-…] listening on port 51257
 ```
 
-In strict profiles it just prints `profile=cloud (strict)` (env validation already failed boot if anything's missing).
-
-### `/api/health` endpoint
+DB sanity check confirmed the Stripe-gate fix:
+```
+SELECT email, name, slug, stripe_customer_id FROM auth.users JOIN auth.organizations ...
+admin@local.test | Local Admin's Team | 14019d9c-team | <NULL>
+```
 
-`apps/api/src/app/api/health/route.ts` returns:
+Profile resolution unit test (all 6 cases pass):
+```
+✓ fresh clone (no env)                  → internal  (strict)
+✓ OSS contributor                       → oss-dev   (lenient)
+✓ GitHub Actions                        → ci        (lenient)
+✓ Vercel runtime                        → cloud     (strict)
+✓ Vercel runtime overrides CI           → cloud     (strict)
+✓ OSS overrides CI                      → oss-dev   (lenient)
+```
 
+CDP-probed React context:
 ```json
-{ "ok": true, "profile": "oss-dev", "integrations": { "stripe": "missing", ... } }
+{ "activeHostUrl": "http://127.0.0.1:51257", "machineId": "…" }
 ```
 
-Used for: contributor sanity checks, prod monitoring alerts on unexpected gaps.
+Local CI reproduction:
+- `bun run lint` — clean
+- `bun run --cwd apps/desktop typecheck` — clean
+- `bun turbo run build --filter=@superset/desktop` — succeeds
 
-## What's NOT built (originally in plan, deferred)
+## What's still deferred (honest TODO list)
 
-These were in the original plan but aren't necessary for "fresh clone boots" and were left for follow-up:
+These are real follow-ups, none of them blocking the OSS path from working today:
 
-- **`docker-compose.dev.yml`** — currently contributors run a one-liner `docker run`. A compose file with Postgres + Mailpit would be nicer; for now, the README's short instructions are enough.
-- **`.env.example` rewrite with working defaults** — `.env.example` is still mostly blank. The docs tell contributors to set just `DATABASE_URL` and `BETTER_AUTH_SECRET`.
-- **`bun setup` orchestrator** — the discrete steps (`docker run`, `bun install`, `bun run db:migrate`, `bun dev`) are still manual. Wrapping them in `bun setup` would be a small ergonomics win.
-- **Per-integration group `.refine()`** — e.g. if `STRIPE_SECRET_KEY` is set then `STRIPE_WEBHOOK_SECRET` must also be set. Catches half-configured prod deploys. Not built; deferred until someone hits the failure mode.
-- **CI fresh-clone smoke test** — not built. Without it, the OSS path can rot silently if someone adds a new crash-on-import integration.
-- **Email provider abstraction (Mailpit fallback)** — Better Auth's `sendEmail` hook currently just `console.log`s emails when no `RESEND_API_KEY` is present. Mailpit container would be nicer UX (clickable links in a web UI) but isn't blocking.
-- **Local-disk Blob storage fallback** — not built. Upload features that need `BLOB_READ_WRITE_TOKEN` will throw.
-- **In-memory rate-limit fallback** — not built. Upstash KV is already handled gracefully by the SDK (logs warnings on missing keys).
-- **Full integration crash audit** — Stripe, Resend, PostHog, and `packages/trpc/src/router/support` were wrapped with lazy-init. GitHub App, Freestyle, Linear, Slack, QStash signing keys, Anthropic, Blob may still crash-on-import in oss-dev. Need a survey: `grep -rn "new \w\+(.*env\." packages apps`.
+- **`.env.example` with working defaults** — README says "edit DATABASE_URL + BETTER_AUTH_SECRET" without telling contributors the values. Pre-fill `postgres://superset:superset@localhost:5433/superset` + a sentinel `BETTER_AUTH_SECRET=dev_secret_not_for_production_*` and move optional integration keys to a `# OPTIONAL` block.
+- **`bun setup` orchestrator** — current contributor flow is 6 commands. A `bun setup` wrapping `docker compose up`, `cp .env.example .env` if missing, `bun install`, `bun run db:migrate`, copy `.dev.vars`, with idempotency + friendly errors would collapse it to two: `bun setup && bun dev`.
+- **Full integration crash audit** — Stripe, Resend, PostHog, trpc-support-Resend are wrapped. GitHub App (`@octokit/app`), Freestyle, Linear, Slack, QStash signing keys, Anthropic (`@anthropic-ai/sdk`), Blob (`@vercel/blob`) may still crash at import in oss-dev. Mechanical `grep -rn "new \w\+(.*env\." packages apps` survey.
+- **Mailpit instead of console-log emails** — Better Auth's `sendEmail` falls back to stdout. Mailpit container would give contributors a clickable UI at `localhost:8025`.
+- **CI fresh-clone smoke test** — without one, the OSS path silently rots the next time someone adds a crash-on-import integration. A GitHub Actions job that does `git clone` in a fresh runner, follows the README, hits `/api/auth/ok`, fails if anything red.
+- **Per-integration group `.refine()` validation** — Formbricks pattern. E.g. if `STRIPE_SECRET_KEY` is set then `STRIPE_WEBHOOK_SECRET` must also be set. Catches half-configured prod deploys.
 
-## What was learned vs. the original plan
+## Architecture diagrams
 
-- **`neondatabase/neon_local` is not a Neon protocol emulator.** It requires `NEON_PROJECT_ID` + `NEON_API_KEY` and proxies to a real Neon project. Useless for OSS. Plain `postgres:16 -c wal_level=logical` is the right substrate, with the driver swap above.
-- **`@neondatabase/serverless` cannot speak vanilla Postgres TCP.** The driver swap is unavoidable — it's not a config flag.
-- **Most integrations degrade gracefully on their own.** Better Auth social providers, Upstash KV, QStash all log warnings when their env vars are missing and keep working. Only a handful crash at import: Resend, Stripe, PostHog, GitHub App in some paths. Plan's "guard a dozen integrations" overestimated; reality was 3-4.
-- **The right place for dev auto-sign-in is the main process, not the renderer.** Initial attempt put it in the renderer's `AuthProvider`, which mixed dev seed concerns with prod auth hydration. Moving it to a `app.whenReady()` hook (where token encryption already lives) leaves `AuthProvider` 100% upstream-pure and gives a much cleaner failure mode.
-- **The renderer had a dev-mode landmine:** 16 places overrode `activeOrganizationId` to `MOCK_ORG_ID` when `SKIP_ENV_VALIDATION` was set. That was a legacy hack from before there was a real dev session. The real fix isn't extra dev logic — it's flipping the priority to prefer whichever session is present. New code that needs `activeOrganizationId` should follow this same pattern.
-
-## Architecture summary
+### Profile resolution
 
 ```
-Contributor's machine
-├─ Docker
-│  ├─ superset-pg            postgres:16, port 5433, wal_level=logical
-│  └─ superset-electric-…    electricsql/electric:1.4.13, port 4649
-│                            (replicates from superset-pg via host.docker.internal)
-└─ SKIP_ENV_VALIDATION=1 bun dev
-   ├─ apps/web               :4640   (Next.js, dev-only email+password form)
-   ├─ apps/api               :4641   (Next.js, Better Auth + tRPC)
-   ├─ apps/desktop (Electron):4645   (Vite renderer + Electron main)
-   │  ├─ main process boots
-   │  ├─ ensureDevAuthToken() POSTs sign-in to :4641 → saveToken()
-   │  ├─ host-service spawns per-org on a dynamic port (e.g. 59728)
-   │  └─ renderer hydrates from auth-token.enc, looks up activeHostUrl
-   ├─ electric-proxy (Wrangler) :4652
-   └─ Caddy HTTPS proxy      :4650 → electric-proxy (HTTP/2 for SSE)
+┌─────────────────────────────────────────────────────────────────────┐
+│                       getDeploymentProfile()                         │
+│                                                                      │
+│   VERCEL === "1"        ─────────────────►  cloud      (strict)     │
+│       │                                                              │
+│       no                                                             │
+│       ▼                                                              │
+│   SUPERSET_OSS === "1"  ─────────────────►  oss-dev    (lenient)    │
+│       │                                                              │
+│       no                                                             │
+│       ▼                                                              │
+│   CI === "true"         ─────────────────►  ci         (lenient)    │
+│       │                                                              │
+│       no                                                             │
+│       ▼                                                              │
+│                          ─────────────────►  internal  (strict)     │
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
-## Verification protocol
-
-CDP probe to confirm the host-service connection is live:
+### OSS-dev session lifecycle
 
-```bash
-curl -sS http://localhost:9333/json/list | jq '.[] | select(.type=="page") | .webSocketDebuggerUrl'
-# Connect via WS, eval:
-#   walkFibersForContextValue() → { activeHostUrl: "http://127.0.0.1:<port>", machineId: "…" }
 ```
+┌──────────────────┐                  ┌──────────────────┐
+│  Postgres :5433  │  wal_level=      │  Electric :4649  │
+│  superset-pg     │  logical         │  superset-       │
+│                  │ ◄────────────────┤  electric        │
+└──────────────────┘  (docker-compose)└──────────────────┘
+        ▲                                       ▲
+        │ migrations                            │ shape stream
+        │                                       │
+        ▼                                       ▼
+┌──────────────────────────────────────────────────────────────┐
+│  bun dev (with SUPERSET_OSS=1)                                │
+│                                                                │
+│  apps/web      :4640  ─ Next.js, DevAuthForm visible          │
+│  apps/api      :4641  ─ Better Auth + tRPC, /api/health       │
+│                                                                │
+│  apps/desktop:                                                 │
+│     Electron main         ─ ensureDevAuthToken() polls API,    │
+│                              POSTs sign-up/sign-in, saveToken()│
+│     Vite renderer :4645  ─ AuthProvider.onTokenChanged hydrates│
+│     Notifications :4646                                        │
+│                                                                │
+│  electric-proxy :4652  (Wrangler)  ─ ELECTRIC_SHAPE_URL=:4649 │
+│  Caddy           :4650  (HTTPS)   ─ reverse proxy → :4652     │
+└──────────────────────────────────────────────────────────────┘
+        │
+        │ host-service spawned per-org (dynamic port)
+        ▼
+┌──────────────────────────────────────────────────┐
+│  Host service (per organization)                  │
+│  superset-dev-data/host/<orgId>/host.db           │
+│  Listening on dynamic port (e.g. :51257)          │
+└──────────────────────────────────────────────────┘
+```
+
+### Strictness × visibility matrix
 
-Concrete script lives in tmp scripts (`/tmp/cdp-find-hosturl.mjs`) used during development.
+| Profile      | `skipValidation` | Boot summary    | `/api/health` shows         | Sign-in path                                  |
+|--------------|------------------|------------------|------------------------------|------------------------------------------------|
+| `cloud`      | false (strict)   | `profile=cloud (strict)`    | `profile: "cloud"`        | OAuth (email/password disabled in prod build)  |
+| `internal`   | false (strict)   | `profile=internal (strict)` | `profile: "internal"`     | OAuth + dev email/password form (NODE_ENV=dev) |
+| `ci`         | true (lenient)   | `profile=ci (lenient)`      | `profile: "ci"`           | n/a (build/test job, no runtime auth)          |
+| `oss-dev`    | true (lenient)   | lists disabled features     | `profile: "oss-dev"`      | dev auto-sign-in + dev email/password form     |

From ee4848e5ae2fc1bf989301169ab85988e684b043 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 11:23:43 -0700
Subject: [PATCH 08/28] refactor local contributor profile

---
 .env.example                                  | 35 +++++--
 Caddyfile.example                             |  6 +-
 README.md                                     |  7 +-
 apps/admin/src/env.ts                         | 13 +--
 apps/api/package.json                         |  1 +
 .../src/app/api/automations/evaluate/route.ts | 14 ++-
 apps/api/src/app/api/github/callback/route.ts | 34 ++++---
 apps/api/src/app/api/health/route.ts          | 30 +-----
 .../api/integrations/linear/callback/route.ts | 28 ++++--
 .../api/integrations/slack/events/route.ts    | 52 ++++++-----
 apps/api/src/env.ts                           | 13 +--
 apps/api/src/lib/boot-summary.ts              | 31 +------
 apps/api/src/lib/integration-status.test.ts   | 34 +++++++
 apps/api/src/lib/integration-status.ts        | 50 ++++++++++
 apps/api/src/lib/qstash.ts                    | 20 ++++
 apps/desktop/electron.vite.config.ts          |  6 ++
 apps/desktop/scripts/clean-launch-services.ts | 13 +++
 apps/desktop/scripts/patch-dev-protocol.ts    |  5 +
 apps/desktop/src/main/env.main.ts             | 62 +++++++++----
 apps/desktop/src/main/index.ts                |  8 +-
 apps/desktop/src/main/lib/dev-auto-sign-in.ts |  8 +-
 .../src/main/lib/dev-workspace-name.ts        | 11 ++-
 .../src/main/lib/relay-url/relay-url.ts       | 10 +-
 apps/docs/src/env.ts                          | 13 +--
 apps/electric-proxy/.dev.vars.example         |  6 +-
 apps/marketing/src/env.ts                     | 13 +--
 apps/relay/src/env.ts                         | 13 +--
 apps/web/src/env.ts                           | 13 +--
 docker-compose.dev.yml                        |  6 +-
 docs/LOCAL_DEVELOPMENT.md                     | 48 +++++-----
 packages/auth/src/lib/rate-limit.ts           | 21 +++--
 packages/auth/src/server.ts                   | 51 ++++++----
 .../shared/src/deployment-profile.test.ts     | 66 +++++++++++++
 packages/shared/src/deployment-profile.ts     | 92 +++++++++++--------
 packages/trpc/src/env.ts                      | 13 +--
 .../trpc/src/lib/integrations/sync/tasks.ts   |  8 +-
 packages/trpc/src/lib/qstash.ts               | 17 ++++
 .../src/router/integration/github/github.ts   | 11 ++-
 plans/20260515-oss-local-setup.md             | 52 +++++------
 turbo.jsonc                                   | 11 +--
 40 files changed, 588 insertions(+), 357 deletions(-)
 create mode 100644 apps/api/src/lib/integration-status.test.ts
 create mode 100644 apps/api/src/lib/integration-status.ts
 create mode 100644 apps/api/src/lib/qstash.ts
 create mode 100644 packages/shared/src/deployment-profile.test.ts
 create mode 100644 packages/trpc/src/lib/qstash.ts

diff --git a/.env.example b/.env.example
index e1ac0be790b..c39b88a8e81 100644
--- a/.env.example
+++ b/.env.example
@@ -5,6 +5,16 @@
 # Shared by all worktrees via direnv
 # =============================================================================
 
+# -----------------------------------------------------------------------------
+# Deployment Profile
+# -----------------------------------------------------------------------------
+# For fresh-clone local development without third-party credentials:
+SUPERSET_PROFILE=local
+
+# Keep desktop dev state separate from production / canary installs.
+# This maps to ~/.superset-local-dev instead of ~/.superset.
+SUPERSET_WORKSPACE_NAME=local-dev
+
 # -----------------------------------------------------------------------------
 # Neon Organization Credentials
 # -----------------------------------------------------------------------------
@@ -13,24 +23,36 @@ NEON_PROJECT_ID=
 NEON_API_KEY=
 
 # -----------------------------------------------------------------------------
-# Neon Database Credentials (Production)
+# Local Database Credentials
+# -----------------------------------------------------------------------------
+DATABASE_URL=postgres://superset:superset@localhost:5433/superset
+DATABASE_URL_UNPOOLED=postgres://superset:superset@localhost:5433/superset
+
+# -----------------------------------------------------------------------------
+# Local Dev Ports
 # -----------------------------------------------------------------------------
-DATABASE_URL=
-DATABASE_URL_UNPOOLED=
+WEB_PORT=4640
+API_PORT=4641
+DESKTOP_VITE_PORT=4645
+DESKTOP_NOTIFICATIONS_PORT=4646
+ELECTRIC_PORT=4649
+CADDY_ELECTRIC_PORT=4650
+WRANGLER_PORT=4652
 
 # -----------------------------------------------------------------------------
 # Cross-App URLs (Local Dev)
 # -----------------------------------------------------------------------------
-NEXT_PUBLIC_API_URL=http://localhost:3001
-NEXT_PUBLIC_WEB_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:4641
+NEXT_PUBLIC_WEB_URL=http://localhost:4640
 NEXT_PUBLIC_ADMIN_URL=http://localhost:3003
 NEXT_PUBLIC_MARKETING_URL=http://localhost:3002
 NEXT_PUBLIC_DOCS_URL=http://localhost:3004
+NEXT_PUBLIC_ELECTRIC_URL=https://localhost:4650
 
 # -----------------------------------------------------------------------------
 # Better Auth
 # -----------------------------------------------------------------------------
-BETTER_AUTH_SECRET=
+BETTER_AUTH_SECRET=local_dev_secret_not_for_production
 NEXT_PUBLIC_COOKIE_DOMAIN=localhost
 
 # -----------------------------------------------------------------------------
@@ -99,6 +121,7 @@ KV_REST_API_TOKEN=
 
 # QStash API token (used for background job scheduling in packages/trpc and apps/api)
 QSTASH_TOKEN=
+QSTASH_URL=
 
 # QStash webhook signature verification keys (used to verify webhook requests)
 QSTASH_CURRENT_SIGNING_KEY=
diff --git a/Caddyfile.example b/Caddyfile.example
index b1043c33d78..719e224ae8d 100644
--- a/Caddyfile.example
+++ b/Caddyfile.example
@@ -2,14 +2,14 @@
 # Avoids browser's 6-connection limit when using 10+ Electric streams.
 #
 # Copy to Caddyfile:  cp Caddyfile.example Caddyfile
-# Install caddy:      brew install caddy  (macOS) / see https://caddyserver.com/docs/install
+# Install caddy:      brew install caddy
 
 {
 	auto_https disable_redirects
 }
 
-https://localhost:3010 {
-	reverse_proxy localhost:3001 {
+https://localhost:{$CADDY_ELECTRIC_PORT} {
+	reverse_proxy localhost:{$WRANGLER_PORT} {
 		flush_interval -1
 	}
 }
diff --git a/README.md b/README.md
index 6300e3cb8e2..e3a5d7cc05a 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ If it runs in a terminal, it runs on Superset
 
 | Requirement | Details |
 |:------------|:--------|
-| **OS** | macOS (Windows/Linux untested) |
+| **OS** | macOS |
 | **Runtime** | [Bun](https://bun.sh/) v1.0+ |
 | **Version Control** | Git 2.20+ |
 | **GitHub CLI** | [gh](https://cli.github.com/) |
@@ -94,14 +94,15 @@ git clone https://github.com/superset-sh/superset.git
 cd superset
 bun install
 docker compose -f docker-compose.dev.yml up -d   # Postgres + Electric
-cp .env.example .env   # then edit DATABASE_URL + BETTER_AUTH_SECRET
+cp .env.example .env
 cp apps/electric-proxy/.dev.vars.example apps/electric-proxy/.dev.vars
 bun run db:migrate
 cp Caddyfile.example Caddyfile && caddy trust
-SUPERSET_OSS=1 bun dev
+bun dev
 ```
 
 The desktop window opens auto-signed-in as a seed admin (`admin@local.test`). See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details, troubleshooting, and what's stubbed without integration keys.
+The copied `.env` also isolates desktop state under `~/.superset-local-dev`, so source builds do not reuse production or canary desktop state.
 
 To build a distributable desktop app:
 
diff --git a/apps/admin/src/env.ts b/apps/admin/src/env.ts
index 33a21635569..2d9ea4aba6d 100644
--- a/apps/admin/src/env.ts
+++ b/apps/admin/src/env.ts
@@ -1,18 +1,9 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	extends: [vercel()],
diff --git a/apps/api/package.json b/apps/api/package.json
index 2fb057d5453..77c73628b5c 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -8,6 +8,7 @@
 		"clean": "git clean -xdf .cache .next .turbo node_modules",
 		"dev": "dotenv -e ../../.env -- sh -c 'exec next dev --port ${API_PORT:-3001}'",
 		"start": "next start --port 3001",
+		"test": "bun test",
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
diff --git a/apps/api/src/app/api/automations/evaluate/route.ts b/apps/api/src/app/api/automations/evaluate/route.ts
index f1c6d7f5a85..7b14e4c2f1d 100644
--- a/apps/api/src/app/api/automations/evaluate/route.ts
+++ b/apps/api/src/app/api/automations/evaluate/route.ts
@@ -2,17 +2,14 @@ import { dbWs } from "@superset/db/client";
 import { automations, subscriptions } from "@superset/db/schema";
 import { ACTIVE_SUBSCRIPTION_STATUSES } from "@superset/shared/billing";
 import { nextOccurrenceAfter } from "@superset/shared/rrule";
-import { Client, Receiver } from "@upstash/qstash";
+import { Receiver } from "@upstash/qstash";
 import { and, eq, exists, inArray, lte, ne, sql } from "drizzle-orm";
 
 import { env } from "@/env";
+import { qstash } from "@/lib/qstash";
 
 export const dynamic = "force-dynamic";
 
-const qstash = new Client({
-	token: env.QSTASH_TOKEN,
-	baseUrl: env.QSTASH_URL,
-});
 const receiver = new Receiver({
 	currentSigningKey: env.QSTASH_CURRENT_SIGNING_KEY,
 	nextSigningKey: env.QSTASH_NEXT_SIGNING_KEY,
@@ -73,6 +70,13 @@ export async function POST(request: Request): Promise<Response> {
 		return Response.json({ enqueued: 0 });
 	}
 
+	if (!qstash) {
+		return Response.json(
+			{ error: "QSTASH_TOKEN is required to enqueue automation jobs" },
+			{ status: 503 },
+		);
+	}
+
 	await qstash.batchJSON(
 		due.map((automation) => {
 			const scheduledFor = bucketToMinute(automation.nextRunAt);
diff --git a/apps/api/src/app/api/github/callback/route.ts b/apps/api/src/app/api/github/callback/route.ts
index 94021159083..6e220e14217 100644
--- a/apps/api/src/app/api/github/callback/route.ts
+++ b/apps/api/src/app/api/github/callback/route.ts
@@ -1,14 +1,12 @@
 import { db } from "@superset/db/client";
 import { githubInstallations, members } from "@superset/db/schema";
-import { Client } from "@upstash/qstash";
 import { and, eq } from "drizzle-orm";
 
 import { env } from "@/env";
 import { verifySignedState } from "@/lib/oauth-state";
+import { qstash, requireQstash } from "@/lib/qstash";
 import { githubApp } from "../octokit";
 
-const qstash = new Client({ token: env.QSTASH_TOKEN });
-
 /**
  * Callback handler for GitHub App installation.
  * GitHub redirects here after the user installs/configures the app.
@@ -122,14 +120,28 @@ export async function GET(request: Request) {
 
 		// Queue initial sync job
 		try {
-			await qstash.publishJSON({
-				url: `${env.NEXT_PUBLIC_API_URL}/api/github/jobs/initial-sync`,
-				body: {
-					installationDbId: savedInstallation.id,
-					organizationId,
-				},
-				retries: 3,
-			});
+			const syncUrl = `${env.NEXT_PUBLIC_API_URL}/api/github/jobs/initial-sync`;
+			const syncBody = {
+				installationDbId: savedInstallation.id,
+				organizationId,
+			};
+
+			if (env.NODE_ENV === "development" && !qstash) {
+				const response = await fetch(syncUrl, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(syncBody),
+				});
+				if (!response.ok) {
+					throw new Error(`Local sync request failed: ${response.status}`);
+				}
+			} else {
+				await requireQstash("github/callback").publishJSON({
+					url: syncUrl,
+					body: syncBody,
+					retries: 3,
+				});
+			}
 		} catch (error) {
 			console.error(
 				"[github/callback] Failed to queue initial sync job:",
diff --git a/apps/api/src/app/api/health/route.ts b/apps/api/src/app/api/health/route.ts
index b17416804f7..bcacc56abe1 100644
--- a/apps/api/src/app/api/health/route.ts
+++ b/apps/api/src/app/api/health/route.ts
@@ -1,38 +1,12 @@
 import { getDeploymentProfile } from "@superset/shared/deployment-profile";
 import { NextResponse } from "next/server";
-
-/**
- * Per-integration configuration status. Read from process.env so we don't
- * have to keep this in sync with the (validated) env schema — the goal here
- * is observability, not validation.
- */
-const INTEGRATIONS = {
-	stripe: "STRIPE_SECRET_KEY",
-	resend: "RESEND_API_KEY",
-	posthog: "NEXT_PUBLIC_POSTHOG_KEY",
-	sentry: "NEXT_PUBLIC_SENTRY_DSN_API",
-	"github-app": "GH_APP_ID",
-	"github-oauth": "GH_CLIENT_ID",
-	"google-oauth": "GOOGLE_CLIENT_ID",
-	linear: "LINEAR_CLIENT_ID",
-	slack: "SLACK_CLIENT_ID",
-	freestyle: "FREESTYLE_API_KEY",
-	qstash: "QSTASH_TOKEN",
-	"upstash-kv": "KV_REST_API_URL",
-	blob: "BLOB_READ_WRITE_TOKEN",
-	anthropic: "ANTHROPIC_API_KEY",
-	tavily: "TAVILY_API_KEY",
-} as const;
+import { getIntegrationStatuses } from "../../../lib/integration-status";
 
 export function GET() {
 	const profile = getDeploymentProfile();
-	const integrations: Record<string, "configured" | "missing"> = {};
-	for (const [name, envVar] of Object.entries(INTEGRATIONS)) {
-		integrations[name] = process.env[envVar] ? "configured" : "missing";
-	}
 	return NextResponse.json({
 		ok: true,
 		profile,
-		integrations,
+		integrations: getIntegrationStatuses(),
 	});
 }
diff --git a/apps/api/src/app/api/integrations/linear/callback/route.ts b/apps/api/src/app/api/integrations/linear/callback/route.ts
index 5b090f03a54..3a770bd097d 100644
--- a/apps/api/src/app/api/integrations/linear/callback/route.ts
+++ b/apps/api/src/app/api/integrations/linear/callback/route.ts
@@ -2,18 +2,16 @@ import { LinearClient } from "@linear/sdk";
 import { db } from "@superset/db/client";
 import { integrationConnections, members, users } from "@superset/db/schema";
 import { linearTokenResponseSchema } from "@superset/trpc/integrations/linear";
-import { Client } from "@upstash/qstash";
 import { and, eq, isNull, ne } from "drizzle-orm";
 
 import { env } from "@/env";
 import { verifySignedState } from "@/lib/oauth-state";
+import { qstash, requireQstash } from "@/lib/qstash";
 
 const UNIQUE_VIOLATION = "23505";
 const ACTIVE_LINKAGE_INDEX =
 	"integration_connections_provider_external_org_active_unique";
 
-const qstash = new Client({ token: env.QSTASH_TOKEN });
-
 export async function GET(request: Request) {
 	const url = new URL(request.url);
 	const code = url.searchParams.get("code");
@@ -149,11 +147,25 @@ export async function GET(request: Request) {
 	}
 
 	try {
-		await qstash.publishJSON({
-			url: `${env.NEXT_PUBLIC_API_URL}/api/integrations/linear/jobs/initial-sync`,
-			body: { organizationId, creatorUserId: userId },
-			retries: 3,
-		});
+		const syncUrl = `${env.NEXT_PUBLIC_API_URL}/api/integrations/linear/jobs/initial-sync`;
+		const syncBody = { organizationId, creatorUserId: userId };
+
+		if (env.NODE_ENV === "development" && !qstash) {
+			const response = await fetch(syncUrl, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(syncBody),
+			});
+			if (!response.ok) {
+				throw new Error(`Local sync request failed: ${response.status}`);
+			}
+		} else {
+			await requireQstash("linear/callback").publishJSON({
+				url: syncUrl,
+				body: syncBody,
+				retries: 3,
+			});
+		}
 	} catch (error) {
 		console.error("Failed to queue initial sync job:", error);
 		return Response.redirect(
diff --git a/apps/api/src/app/api/integrations/slack/events/route.ts b/apps/api/src/app/api/integrations/slack/events/route.ts
index 8706cb59ae9..ea098d5ca78 100644
--- a/apps/api/src/app/api/integrations/slack/events/route.ts
+++ b/apps/api/src/app/api/integrations/slack/events/route.ts
@@ -1,14 +1,12 @@
 import type { LinkSharedEvent, SlackEvent } from "@slack/types";
-import { Client } from "@upstash/qstash";
 
 import { env } from "@/env";
+import { qstash } from "@/lib/qstash";
 import { verifySlackSignature } from "../verify-signature";
 import { processAppHomeOpened } from "./process-app-home-opened";
 import { processEntityDetails } from "./process-entity-details";
 import { processLinkShared } from "./process-link-shared";
 
-const qstash = new Client({ token: env.QSTASH_TOKEN });
-
 type SlackEventEnvelope = {
 	type?: string;
 	challenge?: string;
@@ -79,15 +77,21 @@ export async function POST(request: Request) {
 
 		if (event.type === "app_mention") {
 			try {
-				await qstash.publishJSON({
-					url: `${env.NEXT_PUBLIC_API_URL}/api/integrations/slack/jobs/process-mention`,
-					body: {
-						event,
-						teamId: team_id,
-						eventId: event_id,
-					},
-					retries: 3,
-				});
+				if (qstash) {
+					await qstash.publishJSON({
+						url: `${env.NEXT_PUBLIC_API_URL}/api/integrations/slack/jobs/process-mention`,
+						body: {
+							event,
+							teamId: team_id,
+							eventId: event_id,
+						},
+						retries: 3,
+					});
+				} else {
+					console.warn(
+						"[slack/events] Skipping mention job; QStash is not configured",
+					);
+				}
 			} catch (error) {
 				console.error("[slack/events] Failed to queue mention job:", error);
 			}
@@ -109,15 +113,21 @@ export async function POST(request: Request) {
 			}
 
 			try {
-				await qstash.publishJSON({
-					url: `${env.NEXT_PUBLIC_API_URL}/api/integrations/slack/jobs/process-assistant-message`,
-					body: {
-						event: messageEvent,
-						teamId: team_id,
-						eventId: event_id,
-					},
-					retries: 3,
-				});
+				if (qstash) {
+					await qstash.publishJSON({
+						url: `${env.NEXT_PUBLIC_API_URL}/api/integrations/slack/jobs/process-assistant-message`,
+						body: {
+							event: messageEvent,
+							teamId: team_id,
+							eventId: event_id,
+						},
+						retries: 3,
+					});
+				} else {
+					console.warn(
+						"[slack/events] Skipping assistant message job; QStash is not configured",
+					);
+				}
 			} catch (error) {
 				console.error(
 					"[slack/events] Failed to queue assistant message job:",
diff --git a/apps/api/src/env.ts b/apps/api/src/env.ts
index d7b020f6e30..cc3c98b3923 100644
--- a/apps/api/src/env.ts
+++ b/apps/api/src/env.ts
@@ -1,17 +1,8 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	shared: {
diff --git a/apps/api/src/lib/boot-summary.ts b/apps/api/src/lib/boot-summary.ts
index 17445440004..62d56014739 100644
--- a/apps/api/src/lib/boot-summary.ts
+++ b/apps/api/src/lib/boot-summary.ts
@@ -2,30 +2,7 @@ import {
 	getDeploymentProfile,
 	isStrictProfile,
 } from "@superset/shared/deployment-profile";
-
-/**
- * Integration name → primary env var that activates it. Listed once at API
- * boot so contributors can see what's disabled. Strict profiles fail before
- * reaching this code (env validation rejects missing keys), so this only
- * meaningfully runs in oss-dev.
- */
-const INTEGRATIONS: Array<[name: string, envVar: string]> = [
-	["stripe", "STRIPE_SECRET_KEY"],
-	["resend (email)", "RESEND_API_KEY"],
-	["posthog (telemetry)", "NEXT_PUBLIC_POSTHOG_KEY"],
-	["sentry", "NEXT_PUBLIC_SENTRY_DSN_API"],
-	["github-app", "GH_APP_ID"],
-	["github-oauth", "GH_CLIENT_ID"],
-	["google-oauth", "GOOGLE_CLIENT_ID"],
-	["linear", "LINEAR_CLIENT_ID"],
-	["slack", "SLACK_CLIENT_ID"],
-	["freestyle", "FREESTYLE_API_KEY"],
-	["qstash (jobs)", "QSTASH_TOKEN"],
-	["upstash-kv (rate limit)", "KV_REST_API_URL"],
-	["vercel-blob (uploads)", "BLOB_READ_WRITE_TOKEN"],
-	["anthropic", "ANTHROPIC_API_KEY"],
-	["tavily (search)", "TAVILY_API_KEY"],
-];
+import { getMissingIntegrations } from "./integration-status";
 
 let logged = false;
 
@@ -34,7 +11,7 @@ export function logBootSummary(): void {
 	logged = true;
 
 	const profile = getDeploymentProfile();
-	const missing = INTEGRATIONS.filter(([, k]) => !process.env[k]);
+	const missing = getMissingIntegrations();
 
 	if (isStrictProfile(profile)) {
 		console.log(`[superset] profile=${profile} (strict)`);
@@ -49,7 +26,7 @@ export function logBootSummary(): void {
 	console.log(
 		`[superset] disabled features (set the listed env var to enable):`,
 	);
-	for (const [name, envVar] of missing) {
-		console.log(`           - ${name.padEnd(28)} ${envVar}`);
+	for (const { label, envVar } of missing) {
+		console.log(`           - ${label.padEnd(28)} ${envVar}`);
 	}
 }
diff --git a/apps/api/src/lib/integration-status.test.ts b/apps/api/src/lib/integration-status.test.ts
new file mode 100644
index 00000000000..b33db68c6d9
--- /dev/null
+++ b/apps/api/src/lib/integration-status.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	getIntegrationStatuses,
+	getMissingIntegrations,
+} from "./integration-status";
+
+describe("integration status", () => {
+	it("reports configured and missing integrations from the supplied env", () => {
+		const statuses = getIntegrationStatuses({
+			STRIPE_SECRET_KEY: "sk_test",
+			RESEND_API_KEY: "",
+			NEXT_PUBLIC_POSTHOG_KEY: undefined,
+		});
+
+		expect(statuses.stripe).toBe("configured");
+		expect(statuses.resend).toBe("missing");
+		expect(statuses.posthog).toBe("missing");
+		expect(statuses.blob).toBe("missing");
+	});
+
+	it("returns missing integrations with display labels for boot output", () => {
+		const missing = getMissingIntegrations({
+			STRIPE_SECRET_KEY: "sk_test",
+		});
+
+		expect(missing.some(({ key }) => key === "stripe")).toBe(false);
+		expect(missing).toContainEqual({
+			key: "blob",
+			label: "vercel-blob (uploads)",
+			envVar: "BLOB_READ_WRITE_TOKEN",
+		});
+	});
+});
diff --git a/apps/api/src/lib/integration-status.ts b/apps/api/src/lib/integration-status.ts
new file mode 100644
index 00000000000..4f79b132d63
--- /dev/null
+++ b/apps/api/src/lib/integration-status.ts
@@ -0,0 +1,50 @@
+export const INTEGRATIONS = [
+	{ key: "stripe", label: "stripe", envVar: "STRIPE_SECRET_KEY" },
+	{ key: "resend", label: "resend (email)", envVar: "RESEND_API_KEY" },
+	{
+		key: "posthog",
+		label: "posthog (telemetry)",
+		envVar: "NEXT_PUBLIC_POSTHOG_KEY",
+	},
+	{ key: "sentry", label: "sentry", envVar: "NEXT_PUBLIC_SENTRY_DSN_API" },
+	{ key: "github-app", label: "github-app", envVar: "GH_APP_ID" },
+	{ key: "github-oauth", label: "github-oauth", envVar: "GH_CLIENT_ID" },
+	{ key: "google-oauth", label: "google-oauth", envVar: "GOOGLE_CLIENT_ID" },
+	{ key: "linear", label: "linear", envVar: "LINEAR_CLIENT_ID" },
+	{ key: "slack", label: "slack", envVar: "SLACK_CLIENT_ID" },
+	{ key: "freestyle", label: "freestyle", envVar: "FREESTYLE_API_KEY" },
+	{ key: "qstash", label: "qstash (jobs)", envVar: "QSTASH_TOKEN" },
+	{
+		key: "upstash-kv",
+		label: "upstash-kv (rate limit)",
+		envVar: "KV_REST_API_URL",
+	},
+	{
+		key: "blob",
+		label: "vercel-blob (uploads)",
+		envVar: "BLOB_READ_WRITE_TOKEN",
+	},
+	{ key: "anthropic", label: "anthropic", envVar: "ANTHROPIC_API_KEY" },
+	{ key: "tavily", label: "tavily (search)", envVar: "TAVILY_API_KEY" },
+] as const;
+
+export type IntegrationKey = (typeof INTEGRATIONS)[number]["key"];
+export type Integration = (typeof INTEGRATIONS)[number];
+export type IntegrationStatus = "configured" | "missing";
+
+export function getIntegrationStatuses(
+	envSource: Record<string, string | undefined> = process.env,
+): Record<IntegrationKey, IntegrationStatus> {
+	return Object.fromEntries(
+		INTEGRATIONS.map(({ key, envVar }) => [
+			key,
+			envSource[envVar] ? "configured" : "missing",
+		]),
+	) as Record<IntegrationKey, IntegrationStatus>;
+}
+
+export function getMissingIntegrations(
+	envSource: Record<string, string | undefined> = process.env,
+): Integration[] {
+	return INTEGRATIONS.filter(({ envVar }) => !envSource[envVar]);
+}
diff --git a/apps/api/src/lib/qstash.ts b/apps/api/src/lib/qstash.ts
new file mode 100644
index 00000000000..b826b638086
--- /dev/null
+++ b/apps/api/src/lib/qstash.ts
@@ -0,0 +1,20 @@
+import { Client } from "@upstash/qstash";
+
+import { env } from "@/env";
+
+export const qstash = env.QSTASH_TOKEN
+	? new Client({
+			token: env.QSTASH_TOKEN,
+			...(env.QSTASH_URL ? { baseUrl: env.QSTASH_URL } : {}),
+		})
+	: null;
+
+export function requireQstash(context: string) {
+	if (!qstash) {
+		throw new Error(
+			`[${context}] QSTASH_TOKEN is required to enqueue background jobs`,
+		);
+	}
+
+	return qstash;
+}
diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.ts
index 33158924ed1..06ee0269f08 100644
--- a/apps/desktop/electron.vite.config.ts
+++ b/apps/desktop/electron.vite.config.ts
@@ -93,6 +93,9 @@ export default defineConfig({
 					"https://relay.superset.sh",
 				),
 			),
+			"process.env.SUPERSET_EXPLICIT_RELAY_URL": defineEnv(
+				process.env.RELAY_URL ? "1" : "",
+			),
 			// Must match renderer for analytics in main process
 			"process.env.NEXT_PUBLIC_POSTHOG_KEY": defineEnv(
 				process.env.NEXT_PUBLIC_POSTHOG_KEY,
@@ -232,6 +235,9 @@ export default defineConfig({
 					"https://relay.superset.sh",
 				),
 			),
+			"process.env.SUPERSET_EXPLICIT_RELAY_URL": defineEnv(
+				process.env.RELAY_URL ? "1" : "",
+			),
 			"process.env.STREAMS_URL": defineEnv(
 				process.env.STREAMS_URL,
 				"https://superset-stream.fly.dev",
diff --git a/apps/desktop/scripts/clean-launch-services.ts b/apps/desktop/scripts/clean-launch-services.ts
index 8f8dda03557..d60686b3f2f 100644
--- a/apps/desktop/scripts/clean-launch-services.ts
+++ b/apps/desktop/scripts/clean-launch-services.ts
@@ -12,6 +12,14 @@ import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { config } from "dotenv";
+
+// Let contributor-local .env opt out before touching global Launch Services.
+config({
+	path: resolve(import.meta.dirname, "../../../.env"),
+	override: true,
+	quiet: true,
+});
 
 if (process.platform !== "darwin") {
 	process.exit(0);
@@ -22,6 +30,11 @@ if (process.env.NODE_ENV !== "development") {
 	process.exit(0);
 }
 
+if (process.env.SUPERSET_PROFILE === "local") {
+	console.log("[clean-launch-services] Skipping - local profile");
+	process.exit(0);
+}
+
 const LSREGISTER =
 	"/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
 const WORKTREE_BASE = resolve(homedir(), ".superset/worktrees");
diff --git a/apps/desktop/scripts/patch-dev-protocol.ts b/apps/desktop/scripts/patch-dev-protocol.ts
index dc89ff36fe0..871905fdfbc 100644
--- a/apps/desktop/scripts/patch-dev-protocol.ts
+++ b/apps/desktop/scripts/patch-dev-protocol.ts
@@ -175,6 +175,11 @@ export function main() {
 		process.exit(0);
 	}
 
+	if (process.env.SUPERSET_PROFILE === "local") {
+		console.log("[patch-dev-protocol] Skipping - local profile");
+		process.exit(0);
+	}
+
 	// Prefer path-derived name so stale .env values never override the active worktree.
 	const { bundleDisplayWorkspaceName, workspaceName, worktreePath } =
 		resolveWorkspaceIdentity({
diff --git a/apps/desktop/src/main/env.main.ts b/apps/desktop/src/main/env.main.ts
index 049bc30aad9..6fa5939b502 100644
--- a/apps/desktop/src/main/env.main.ts
+++ b/apps/desktop/src/main/env.main.ts
@@ -9,23 +9,51 @@
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod/v4";
 
-// NOTE: the deployment-profile check is inlined here rather than imported
-// from @superset/shared/deployment-profile because electron.vite.config.ts
-// does `await import("./src/main/env.main")` at config-load time, which
-// Node's ESM loader handles directly (no Vite transform) — and Node can't
-// load `.ts` files from sibling workspace packages. Keep the helper in
-// shared/, but duplicate the four lines here.
-//
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// CI=true (auto-set by GitHub Actions) also opts into lenient so
-// build/lint/test jobs work without prod secrets.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
+// NOTE: deployment-profile checks are inlined here rather than imported from
+// @superset/shared/deployment-profile because electron.vite.config.ts does
+// `await import("./src/main/env.main")` at config-load time, which Node's ESM
+// loader handles directly (no Vite transform) — and Node can't load `.ts`
+// files from sibling workspace packages. Keep this in sync with shared/.
+function isTruthyFlag(value: string | undefined): boolean {
+	return value === "1" || value === "true";
+}
+
+type MainDeploymentProfile = "cloud" | "local" | "ci" | "internal";
+const VALID_PROFILES: MainDeploymentProfile[] = [
+	"cloud",
+	"local",
+	"ci",
+	"internal",
+];
+
+function getExplicitProfile(): MainDeploymentProfile | undefined {
+	const explicitProfile = process.env.SUPERSET_PROFILE;
+	if (!explicitProfile) return undefined;
+	if (VALID_PROFILES.includes(explicitProfile as MainDeploymentProfile)) {
+		return explicitProfile as MainDeploymentProfile;
+	}
+	throw new Error(
+		`Invalid SUPERSET_PROFILE="${explicitProfile}". Expected one of: ${VALID_PROFILES.join(
+			", ",
+		)}.`,
+	);
+}
+
+function getDeploymentProfile(): MainDeploymentProfile {
+	if (isTruthyFlag(process.env.VERCEL) || process.env.VERCEL_ENV) {
+		return "cloud";
+	}
+	const explicitProfile = getExplicitProfile();
+	if (explicitProfile) return explicitProfile;
+	if (isTruthyFlag(process.env.CI)) return "ci";
+	return "internal";
+}
+
+export const deploymentProfile = getDeploymentProfile();
 const isStrict =
-	process.env.VERCEL === "1" ||
-	(process.env.SUPERSET_OSS !== "1" && process.env.CI !== "true");
-const skipValidation = !isStrict || !!process.env.SKIP_ENV_VALIDATION;
+	deploymentProfile === "cloud" || deploymentProfile === "internal";
+const skipValidation =
+	!isStrict || isTruthyFlag(process.env.SKIP_ENV_VALIDATION);
 
 export const env = createEnv({
 	server: {
@@ -33,7 +61,7 @@ export const env = createEnv({
 			.enum(["development", "production", "test"])
 			.default("development"),
 		// In dev builds (NODE_ENV=development) the URL defaults switch to
-		// localhost so fresh-clone OSS contributors never silently sync
+		// localhost so fresh-clone local contributors never silently sync
 		// against hosted production endpoints.
 		NEXT_PUBLIC_API_URL: z
 			.url()
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 1e7302d2421..258ce96c602 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -1,7 +1,7 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { settings } from "@superset/local-db";
-import { getDeploymentProfile } from "@superset/shared/deployment-profile";
+import { isLocalProfile } from "@superset/shared/deployment-profile";
 import {
 	app,
 	BrowserWindow,
@@ -57,9 +57,9 @@ import { MainWindow } from "./windows/main";
 console.log("[main] Local database ready:", !!localDb);
 const IS_DEV = process.env.NODE_ENV === "development";
 
-// OSS-dev only: expose Chrome DevTools Protocol for headless testing
+// Local profile only: expose Chrome DevTools Protocol for headless testing
 // (e.g. import/host-service checks). Skip in internal / cloud profiles.
-if (IS_DEV && getDeploymentProfile() === "oss-dev") {
+if (IS_DEV && isLocalProfile()) {
 	app.commandLine.appendSwitch("remote-debugging-port", "9333");
 	app.commandLine.appendSwitch("remote-allow-origins", "*");
 }
@@ -425,7 +425,7 @@ if (!gotTheLock) {
 			console.error("[main] Failed to install bundled CLI shim:", error);
 		}
 
-		// OSS-dev only: auto-sign-in as the seed admin if no token is on disk.
+		// Local profile only: auto-sign-in as the seed admin if no token is on disk.
 		// Fire-and-forget — the function polls the API for readiness internally
 		// (Turbo starts services concurrently, the API may still be compiling).
 		// AuthProvider in the renderer subscribes to auth.onTokenChanged and
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
index 747a2b9aac2..8a912a744c8 100644
--- a/apps/desktop/src/main/lib/dev-auto-sign-in.ts
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -1,4 +1,4 @@
-import { getDeploymentProfile } from "@superset/shared/deployment-profile";
+import { isLocalProfile } from "@superset/shared/deployment-profile";
 import { env as mainEnv } from "main/env.main";
 import {
 	loadToken,
@@ -59,7 +59,7 @@ async function waitForApiReady(): Promise<boolean> {
 }
 
 /**
- * Dev-only: in the oss-dev profile, sign in (or sign up) as the seed
+ * Dev-only: in the local profile, sign in (or sign up) as the seed
  * admin user and persist the token so the renderer's AuthProvider can
  * hydrate normally — no special renderer code.
  *
@@ -68,8 +68,8 @@ async function waitForApiReady(): Promise<boolean> {
  * launch). Best-effort: failure is logged but doesn't crash boot.
  */
 export async function ensureDevAuthToken(): Promise<void> {
-	// OSS-dev only — internal devs, self-hosters, and prod all use real auth.
-	if (getDeploymentProfile() !== "oss-dev") return;
+	// Local profile only — internal devs, self-hosters, and prod all use real auth.
+	if (!isLocalProfile()) return;
 
 	const stored = await loadToken();
 	if (stored.token && stored.expiresAt) {
diff --git a/apps/desktop/src/main/lib/dev-workspace-name.ts b/apps/desktop/src/main/lib/dev-workspace-name.ts
index ee730f59e34..472a74404e6 100644
--- a/apps/desktop/src/main/lib/dev-workspace-name.ts
+++ b/apps/desktop/src/main/lib/dev-workspace-name.ts
@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { workspaces, worktrees } from "@superset/local-db";
+import { isLocalProfile } from "@superset/shared/deployment-profile";
 import BetterSqlite3 from "better-sqlite3";
 import { and, desc, eq, isNull } from "drizzle-orm";
 import { getWorkspaceName as getEnvWorkspaceName } from "shared/env.shared";
@@ -102,16 +103,22 @@ export function resolveDevWorkspaceName(
 ): string | undefined {
 	if (!IS_DEV) return undefined;
 
+	const workspaceNameFromEnv = getEnvWorkspaceName();
 	const segments = getWorktreeSegmentsFromCwd(cwd);
-	if (!segments) return getEnvWorkspaceName();
+	if (!segments) return workspaceNameFromEnv;
 
 	const workspaceNameFromPath =
 		deriveWorkspaceNameFromWorktreeSegments(segments);
+
+	if (isLocalProfile()) {
+		return workspaceNameFromEnv ?? workspaceNameFromPath;
+	}
+
 	const worktreePath = getWorktreePathFromSegments(segments);
 	const workspaceNameFromDb = worktreePath
 		? (getWorkspaceNameForPathFromCurrentDb(worktreePath) ??
 			getWorkspaceNameForPathFromProdDb(worktreePath))
 		: undefined;
 
-	return workspaceNameFromDb ?? workspaceNameFromPath ?? getEnvWorkspaceName();
+	return workspaceNameFromDb ?? workspaceNameFromPath ?? workspaceNameFromEnv;
 }
diff --git a/apps/desktop/src/main/lib/relay-url/relay-url.ts b/apps/desktop/src/main/lib/relay-url/relay-url.ts
index eafc30e7f62..8574c6470cc 100644
--- a/apps/desktop/src/main/lib/relay-url/relay-url.ts
+++ b/apps/desktop/src/main/lib/relay-url/relay-url.ts
@@ -1,5 +1,5 @@
 import { FEATURE_FLAGS } from "@superset/shared/constants";
-import { env } from "main/env.main";
+import { deploymentProfile, env } from "main/env.main";
 import { getPosthogClient, getUserId } from "main/lib/analytics";
 
 interface RelayUrlPayload {
@@ -16,7 +16,13 @@ interface RelayUrlPayload {
  * opens land on the same URL.
  */
 export async function getRelayUrl(): Promise<string | undefined> {
-	const fallback = env.RELAY_URL;
+	const usesLenientLocalEnv =
+		deploymentProfile === "local" || deploymentProfile === "ci";
+	// Vite always injects RELAY_URL, so track whether the value came from a
+	// real env var before enabling local tunnels in contributor profiles.
+	const hasExplicitRelayUrl = process.env.SUPERSET_EXPLICIT_RELAY_URL === "1";
+	const fallback =
+		usesLenientLocalEnv && !hasExplicitRelayUrl ? undefined : env.RELAY_URL;
 	const client = getPosthogClient();
 	const userId = getUserId();
 	if (!client || !userId) return fallback;
diff --git a/apps/docs/src/env.ts b/apps/docs/src/env.ts
index 2f4b39075bd..af9e47cba2a 100644
--- a/apps/docs/src/env.ts
+++ b/apps/docs/src/env.ts
@@ -1,18 +1,9 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	extends: [vercel()],
diff --git a/apps/electric-proxy/.dev.vars.example b/apps/electric-proxy/.dev.vars.example
index f208fd415b0..b7a68d9fe39 100644
--- a/apps/electric-proxy/.dev.vars.example
+++ b/apps/electric-proxy/.dev.vars.example
@@ -1,9 +1,9 @@
 # Defaults match docker-compose.dev.yml (Electric on host port 4649)
-# and the default `bun dev` ports (API on 3001).
+# and the local contributor `bun dev` ports (API on 4641).
 #
 # Internal devs: setup.sh regenerates this with per-workspace ports.
-# OSS contributors: cp .dev.vars.example .dev.vars and run `bun dev`.
-AUTH_URL=http://localhost:3001
+# External contributors: cp .dev.vars.example .dev.vars and run `bun dev`.
+AUTH_URL=http://localhost:4641
 ELECTRIC_SHAPE_URL=http://localhost:4649/v1/shape
 ELECTRIC_SECRET=local_electric_dev_secret
 ELECTRIC_SOURCE_ID=
diff --git a/apps/marketing/src/env.ts b/apps/marketing/src/env.ts
index c2d5e1edaf5..0ae1560eb44 100644
--- a/apps/marketing/src/env.ts
+++ b/apps/marketing/src/env.ts
@@ -1,18 +1,9 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	extends: [vercel()],
diff --git a/apps/relay/src/env.ts b/apps/relay/src/env.ts
index bf36a65909f..25966a56c2e 100644
--- a/apps/relay/src/env.ts
+++ b/apps/relay/src/env.ts
@@ -1,17 +1,8 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	server: {
diff --git a/apps/web/src/env.ts b/apps/web/src/env.ts
index e98a53ce260..4adca4fa385 100644
--- a/apps/web/src/env.ts
+++ b/apps/web/src/env.ts
@@ -1,18 +1,9 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-nextjs";
 import { vercel } from "@t3-oss/env-nextjs/presets-zod";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	extends: [vercel()],
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 16e5bb8d8c8..813d4fb6e6f 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -1,4 +1,4 @@
-# Local dev services for OSS contributors.
+# Local dev services for external contributors.
 #
 # Brings up Postgres + Electric SQL on stable host ports so a fresh clone
 # can talk to both immediately. Internal devs use `.superset/setup.sh`
@@ -35,8 +35,8 @@ services:
       postgres:
         condition: service_healthy
     environment:
-      # host.docker.internal lets the container reach Postgres on the
-      # host's 5433 port (mapped from the postgres service above).
+      # Docker Desktop exposes host.docker.internal so Electric can reach
+      # Postgres through the host's stable 5433 port.
       DATABASE_URL: postgres://superset:superset@host.docker.internal:5433/superset
       ELECTRIC_SECRET: local_electric_dev_secret
     ports:
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 5e640d1d2c9..8d3efcf0878 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -5,9 +5,9 @@ How to run Superset locally from a fresh clone, with no Neon / OAuth / Stripe /
 ## Prerequisites
 
 - [Bun](https://bun.sh) 1.3+
-- Docker (for Postgres and Electric SQL)
+- Docker Desktop for macOS (for Postgres and Electric SQL)
 - [Caddy](https://caddyserver.com/docs/install) (for HTTPS proxy)
-- macOS or Linux
+- macOS
 
 ## One-time setup
 
@@ -35,15 +35,7 @@ These containers stay running between sessions; `docker compose down -v` to wipe
 cp .env.example .env
 ```
 
-Then edit `.env` so it has at minimum:
-
-```bash
-DATABASE_URL=postgres://superset:superset@localhost:5433/superset
-DATABASE_URL_UNPOOLED=postgres://superset:superset@localhost:5433/superset
-BETTER_AUTH_SECRET=dev_secret_$(openssl rand -hex 24)
-```
-
-Everything else can stay blank. The app degrades cleanly when integration keys (Stripe, Resend, GitHub App, etc.) are missing — features that need them will throw a clean "X not configured" error when you actually exercise them; nothing crashes at boot.
+The example file is ready for the Docker defaults and includes `SUPERSET_PROFILE=local`, `SUPERSET_WORKSPACE_NAME=local-dev`, stable local ports, the local Postgres URL, and a development-only auth secret. The workspace name keeps desktop state in `~/.superset-local-dev` instead of the production / canary `~/.superset` directory. Integration keys (Stripe, Resend, GitHub App, etc.) can stay blank — features that need them will throw a clean "X not configured" error when you actually exercise them; nothing crashes at boot.
 
 **3. Apply the schema**
 
@@ -67,10 +59,10 @@ Without `caddy trust`, Chromium will reject `https://localhost:*` with `ERR_CERT
 ## Run it
 
 ```bash
-SUPERSET_OSS=1 bun dev
+bun dev
 ```
 
-`SUPERSET_OSS=1` opts you into the lenient OSS profile so the app boots without every integration key — Stripe, OAuth, Resend, etc. become optional. Without it, the app defaults to strict validation (matching the internal-team workflow) and will fail boot if any of those keys are missing.
+The copied `.env` sets `SUPERSET_PROFILE=local`, which opts you into the lenient local contributor profile so the app boots without every integration key — Stripe, OAuth, Resend, etc. become optional. Without that profile, the app defaults to strict validation (matching the internal-team workflow) and will fail boot if any of those keys are missing.
 
 That brings up:
 
@@ -88,12 +80,12 @@ The Electron window opens automatically.
 
 ### How sign-in works
 
-On first launch in the `oss-dev` profile (when `SUPERSET_OSS=1` is set), the desktop main process auto-signs you in as a seed admin user:
+On first launch in the `local` profile (when `SUPERSET_PROFILE=local` is set), the desktop main process auto-signs you in as a seed admin user:
 
 - **Email:** `admin@local.test`
 - **Password:** `supersetdev`
 
-If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in `superset-dev-data/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
+If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in `~/.superset-local-dev/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
 
 ### Deployment profiles
 
@@ -101,21 +93,21 @@ Profile is resolved at boot:
 
 | Profile     | Trigger                              | Behavior |
 |-------------|--------------------------------------|----------|
-| `cloud`     | `VERCEL=1` (set automatically at runtime) | Strict — every integration key required |
-| `oss-dev`   | `SUPERSET_OSS=1`                     | Lenient — integration keys optional, features degrade |
+| `cloud`     | `VERCEL=1` or `VERCEL_ENV` (set by Vercel) | Strict — every integration key required |
+| `local`     | `SUPERSET_PROFILE=local`             | Lenient — integration keys optional, features degrade |
 | `ci`        | `CI=true` (set automatically by GitHub Actions, most runners) | Lenient — build/lint/test jobs run without prod secrets |
 | `internal`  | default                              | Strict — covers internal team dev and self-hosted prod |
 
-**Strict-by-default is the safe direction.** Internal devs and self-hosters keep their fail-fast workflow with no setup changes. OSS contributors set `SUPERSET_OSS=1` once (in `.env`, or as a shell var) to opt into the lenient path. CI auto-degrades so `bun run lint/typecheck/test` works without injecting every production secret — actual deploy steps run `vercel build`, which pulls env from the Vercel project, and runtime strictness still kicks in once `VERCEL=1` is set on the deployed serverless function.
+**Strict-by-default is the safe direction.** Internal devs and self-hosters keep their fail-fast workflow with no setup changes. Local contributors set `SUPERSET_PROFILE=local` once (in `.env`, or as a shell var) to opt into the lenient path. CI auto-degrades so `bun run lint/typecheck/test` works without injecting every production secret — actual deploy steps run `vercel build`, which pulls env from the Vercel project, and runtime strictness still kicks in once Vercel env markers are set.
 
 The escape hatch `SKIP_ENV_VALIDATION=1` still works for one-off bypass cases (e.g. Docker preview builds outside of GitHub Actions).
 
 ### Boot summary + `/api/health`
 
-When the API boots in `oss-dev`, it prints a one-time summary of what's disabled:
+When the API boots in the `local` profile, it prints a one-time summary of what's disabled:
 
 ```
-[superset] profile=oss-dev (lenient)
+[superset] profile=local (lenient)
 [superset] disabled features (set the listed env var to enable):
            - stripe                       STRIPE_SECRET_KEY
            - resend (email)               RESEND_API_KEY
@@ -126,12 +118,12 @@ When the API boots in `oss-dev`, it prints a one-time summary of what's disabled
 For programmatic monitoring (or to confirm a key took effect), hit `GET /api/health`:
 
 ```json
-{ "ok": true, "profile": "oss-dev", "integrations": { "stripe": "missing", ... } }
+{ "ok": true, "profile": "local", "integrations": { "stripe": "missing", ... } }
 ```
 
 For the web app (`http://localhost:4640`), the sign-in and sign-up pages render a dev-only email/password form when `NODE_ENV !== "production"`. Use the same credentials.
 
-## What works in OSS mode
+## What works locally
 
 ✓ Sign-in (email/password)
 ✓ Database (Postgres + Drizzle)
@@ -150,6 +142,7 @@ For the web app (`http://localhost:4640`), the sign-in and sign-up pages render
 - **GitHub App / Linear / Slack** — webhooks and integrations no-op without their keys.
 - **QStash background jobs** — no key → no scheduled jobs fire.
 - **Upstash KV rate limiting** — falls back gracefully.
+- **Cloud relay tunnel** — disabled in `local` / `ci` unless `RELAY_URL` is explicitly set.
 
 Each is "guard, don't crash" — if you click into a feature that needs a key, you'll see a `503` or a clean exception, not a boot failure.
 
@@ -157,7 +150,7 @@ Each is "guard, don't crash" — if you click into a feature that needs a key, y
 
 **`EADDRINUSE: address already in use :::4641`** — a previous `bun dev` is still alive. `pkill -f "turbo run dev"` and retry.
 
-**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `superset-dev-data/auth-token.enc` exists. Delete it and rerun if needed: `rm superset-dev-data/auth-token.enc && SUPERSET_OSS=1 bun dev`. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "oss-dev"` — if it says `internal`, you forgot to set `SUPERSET_OSS=1` and auto-sign-in is intentionally skipped.
+**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `~/.superset-local-dev/auth-token.enc` exists. Delete it and rerun if needed: `rm ~/.superset-local-dev/auth-token.enc && bun dev`. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "local"` — if it says `internal`, you forgot to set `SUPERSET_PROFILE=local` and auto-sign-in is intentionally skipped.
 
 **`Missing API key` for some integration** — that integration's key isn't in `.env`. Either supply it or avoid the feature.
 
@@ -172,7 +165,7 @@ Each is "guard, don't crash" — if you click into a feature that needs a key, y
 pkill -f "turbo run dev"
 
 # Wipe data (auth token, host DBs, local app state)
-rm -rf superset-dev-data
+rm -rf ~/.superset-local-dev
 
 # Wipe Postgres + Electric (including volume)
 docker compose -f docker-compose.dev.yml down -v
@@ -181,8 +174,9 @@ docker compose -f docker-compose.dev.yml up -d
 
 ## Architecture notes for contributors
 
-- **Deployment profiles** — `packages/shared/src/deployment-profile.ts` resolves `cloud | internal-dev | self-hosted | oss-dev` from env flags. Strict profiles fail boot on missing keys; lenient (`oss-dev`) lets the app boot. Use `isStrictProfile()` from this module when you need to gate dev-only behavior.
+- **Deployment profiles** — `packages/shared/src/deployment-profile.ts` resolves `cloud | local | ci | internal` from env flags. Strict profiles fail boot on missing keys; lenient profiles (`local`, `ci`) let the app boot. Use `shouldSkipEnvValidation()` from this module when wiring env schemas, and `isLocalProfile()` when gating local-only behavior.
+- **Desktop state isolation** — `.env.example` sets `SUPERSET_WORKSPACE_NAME=local-dev`, so contributor runs use `~/.superset-local-dev` and do not reuse production / canary state from `~/.superset`. Local profile desktop predev also skips macOS Launch Services cleanup and protocol patching.
 - **DB driver swap** — `packages/db/src/client.ts` detects whether `DATABASE_URL` is a Neon host (`*.neon.tech`, `*.neon.build`) and uses Drizzle's `neon-http` adapter for cloud, or `node-postgres` for any other Postgres (including the local Docker one).
-- **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()` only in the `oss-dev` profile. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
+- **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()` only in the `local` profile. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
 - **Renderer organization selection** — pages prefer `session.activeOrganizationId` from Better Auth, falling back to `MOCK_ORG_ID` only if there's no session at all. Make sure new code that needs `activeOrganizationId` follows this same priority (real session first).
-- **CDP for headless tests** — in the `oss-dev` profile, the desktop main process exposes Chrome DevTools Protocol on `localhost:9333`. Useful for scripted UI checks (`curl http://localhost:9333/json/list`).
+- **CDP for headless tests** — in the `local` profile, the desktop main process exposes Chrome DevTools Protocol on `localhost:9333`. Useful for scripted UI checks (`curl http://localhost:9333/json/list`).
diff --git a/packages/auth/src/lib/rate-limit.ts b/packages/auth/src/lib/rate-limit.ts
index a513dbe6f27..c67a4470147 100644
--- a/packages/auth/src/lib/rate-limit.ts
+++ b/packages/auth/src/lib/rate-limit.ts
@@ -2,14 +2,15 @@ import { Ratelimit } from "@upstash/ratelimit";
 import { Redis } from "@upstash/redis";
 import { env } from "../env";
 
-const redis = new Redis({
-	url: env.KV_REST_API_URL,
-	token: env.KV_REST_API_TOKEN,
-});
-
 // 10 invitations per hour per user
-export const invitationRateLimit = new Ratelimit({
-	redis,
-	limiter: Ratelimit.slidingWindow(10, "1 h"),
-	prefix: "ratelimit:invitation",
-});
+export const invitationRateLimit =
+	env.KV_REST_API_URL && env.KV_REST_API_TOKEN
+		? new Ratelimit({
+				redis: new Redis({
+					url: env.KV_REST_API_URL,
+					token: env.KV_REST_API_TOKEN,
+				}),
+				limiter: Ratelimit.slidingWindow(10, "1 h"),
+				prefix: "ratelimit:invitation",
+			})
+		: null;
diff --git a/packages/auth/src/server.ts b/packages/auth/src/server.ts
index c290770d393..cbd7d9cf031 100644
--- a/packages/auth/src/server.ts
+++ b/packages/auth/src/server.ts
@@ -36,7 +36,9 @@ import {
 import { stripeClient } from "./stripe";
 import { formatPrice, getOrganizationOwners } from "./utils";
 
-const qstash = new Client({ token: env.QSTASH_TOKEN });
+const qstash = env.QSTASH_TOKEN
+	? new Client({ token: env.QSTASH_TOKEN })
+	: null;
 
 const NOTIFY_SLACK_URL = `${env.NEXT_PUBLIC_API_URL}/api/integrations/stripe/jobs/notify-slack`;
 const desktopDevPort = process.env.DESKTOP_VITE_PORT || "5173";
@@ -47,6 +49,24 @@ const desktopDevOrigins =
 				`http://127.0.0.1:${desktopDevPort}`,
 			]
 		: [];
+const socialProviders = {
+	...(env.GH_CLIENT_ID && env.GH_CLIENT_SECRET
+		? {
+				github: {
+					clientId: env.GH_CLIENT_ID,
+					clientSecret: env.GH_CLIENT_SECRET,
+				},
+			}
+		: {}),
+	...(env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET
+		? {
+				google: {
+					clientId: env.GOOGLE_CLIENT_ID,
+					clientSecret: env.GOOGLE_CLIENT_SECRET,
+				},
+			}
+		: {}),
+};
 
 export const auth = betterAuth({
 	baseURL: env.NEXT_PUBLIC_API_URL,
@@ -97,16 +117,7 @@ export const auth = betterAuth({
 		enabled: process.env.NODE_ENV !== "production",
 		autoSignIn: true,
 	},
-	socialProviders: {
-		github: {
-			clientId: env.GH_CLIENT_ID,
-			clientSecret: env.GH_CLIENT_SECRET,
-		},
-		google: {
-			clientId: env.GOOGLE_CLIENT_ID,
-			clientSecret: env.GOOGLE_CLIENT_SECRET,
-		},
-	},
+	socialProviders,
 	databaseHooks: {
 		user: {
 			create: {
@@ -320,8 +331,8 @@ export const auth = betterAuth({
 				beforeCreateInvitation: async (data) => {
 					const { inviterId, organizationId, role, teamId } = data.invitation;
 
-					const { success } = await invitationRateLimit.limit(inviterId);
-					if (!success) {
+					const limit = await invitationRateLimit?.limit(inviterId);
+					if (limit && !limit.success) {
 						throw new Error(
 							"Rate limit exceeded. Max 10 invitations per hour.",
 						);
@@ -638,7 +649,7 @@ export const auth = betterAuth({
 					);
 
 					try {
-						await qstash.publishJSON({
+						await qstash?.publishJSON({
 							url: NOTIFY_SLACK_URL,
 							body: {
 								eventType: "seat_added",
@@ -727,7 +738,7 @@ export const auth = betterAuth({
 					);
 
 					try {
-						await qstash.publishJSON({
+						await qstash?.publishJSON({
 							url: NOTIFY_SLACK_URL,
 							body: {
 								eventType: "seat_removed",
@@ -914,7 +925,7 @@ export const auth = betterAuth({
 					);
 
 					try {
-						await qstash.publishJSON({
+						await qstash?.publishJSON({
 							url: NOTIFY_SLACK_URL,
 							body: {
 								eventType: "subscription_started",
@@ -962,7 +973,7 @@ export const auth = betterAuth({
 					);
 
 					try {
-						await qstash.publishJSON({
+						await qstash?.publishJSON({
 							url: NOTIFY_SLACK_URL,
 							body: {
 								eventType: "subscription_cancelled",
@@ -1031,7 +1042,7 @@ export const auth = betterAuth({
 
 						if (stripeSubId) {
 							try {
-								await qstash.publishJSON({
+								await qstash?.publishJSON({
 									url: NOTIFY_SLACK_URL,
 									body: {
 										eventType: "payment_failed",
@@ -1058,7 +1069,7 @@ export const auth = betterAuth({
 
 						if (stripeSubId) {
 							try {
-								await qstash.publishJSON({
+								await qstash?.publishJSON({
 									url: NOTIFY_SLACK_URL,
 									body: {
 										eventType: "payment_succeeded",
@@ -1098,7 +1109,7 @@ export const auth = betterAuth({
 								: "monthly";
 
 						try {
-							await qstash.publishJSON({
+							await qstash?.publishJSON({
 								url: NOTIFY_SLACK_URL,
 								body: {
 									eventType: "plan_changed",
diff --git a/packages/shared/src/deployment-profile.test.ts b/packages/shared/src/deployment-profile.test.ts
new file mode 100644
index 00000000000..62dff7e2f5b
--- /dev/null
+++ b/packages/shared/src/deployment-profile.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	getDeploymentProfile,
+	isLocalProfile,
+	isStrictProfile,
+	shouldSkipEnvValidation,
+} from "./deployment-profile";
+
+describe("deployment profile resolution", () => {
+	it("defaults to internal strict mode", () => {
+		const env: Record<string, string | undefined> = {};
+
+		expect(getDeploymentProfile(env)).toBe("internal");
+		expect(isStrictProfile(getDeploymentProfile(env))).toBe(true);
+		expect(shouldSkipEnvValidation(env)).toBe(false);
+	});
+
+	it("uses explicit local profile for lenient contributor development", () => {
+		const env = { SUPERSET_PROFILE: "local" };
+
+		expect(getDeploymentProfile(env)).toBe("local");
+		expect(isLocalProfile(getDeploymentProfile(env))).toBe(true);
+		expect(isStrictProfile(getDeploymentProfile(env))).toBe(false);
+		expect(shouldSkipEnvValidation(env)).toBe(true);
+	});
+
+	it("uses ci only when no explicit or cloud profile is present", () => {
+		expect(getDeploymentProfile({ CI: "true" })).toBe("ci");
+		expect(getDeploymentProfile({ CI: "1" })).toBe("ci");
+		expect(
+			getDeploymentProfile({ CI: "true", SUPERSET_PROFILE: "internal" }),
+		).toBe("internal");
+	});
+
+	it("keeps cloud strict above local and ci flags", () => {
+		const env = {
+			VERCEL: "1",
+			CI: "true",
+			SUPERSET_PROFILE: "local",
+		};
+
+		expect(getDeploymentProfile(env)).toBe("cloud");
+		expect(isStrictProfile(getDeploymentProfile(env))).toBe(true);
+		expect(shouldSkipEnvValidation(env)).toBe(false);
+	});
+
+	it("treats VERCEL_ENV as cloud", () => {
+		expect(getDeploymentProfile({ VERCEL_ENV: "preview", CI: "true" })).toBe(
+			"cloud",
+		);
+	});
+
+	it("allows SKIP_ENV_VALIDATION as an explicit strict-profile escape hatch", () => {
+		const env = { SKIP_ENV_VALIDATION: "1" };
+
+		expect(getDeploymentProfile(env)).toBe("internal");
+		expect(shouldSkipEnvValidation(env)).toBe(true);
+	});
+
+	it("throws on invalid explicit profiles", () => {
+		expect(() =>
+			getDeploymentProfile({ SUPERSET_PROFILE: "external" }),
+		).toThrow(/Invalid SUPERSET_PROFILE/);
+	});
+});
diff --git a/packages/shared/src/deployment-profile.ts b/packages/shared/src/deployment-profile.ts
index fc1d69d6f73..dc6b7b39f43 100644
--- a/packages/shared/src/deployment-profile.ts
+++ b/packages/shared/src/deployment-profile.ts
@@ -1,49 +1,69 @@
 /**
  * Deployment profile resolution.
  *
- * Four profiles, ranked by discriminator trust:
+ * Strict profiles (`cloud`, `internal`) validate all required integration
+ * env vars at boot. Lenient profiles (`local`, `ci`) let the app boot with
+ * missing integration keys; call sites lazy-throw or no-op when the missing
+ * feature is exercised.
  *
- *   1. `cloud`     — Vercel sets `VERCEL=1` automatically at RUNTIME on
- *                    its serverless functions. Contributors can't fake
- *                    it locally. Strict — every integration key required.
- *   2. `oss-dev`   — Contributor explicitly sets `SUPERSET_OSS=1` to
- *                    opt into the lenient profile so a fresh clone
- *                    boots without every integration key.
- *   3. `ci`        — GitHub Actions sets `CI=true` (and runners do too).
- *                    Lenient by design: lint/typecheck/test jobs don't
- *                    have integration keys, and any actual deploy step
- *                    runs `vercel build` which pulls env from the
- *                    Vercel project. Runtime strictness still kicks in
- *                    once the build is deployed and `VERCEL=1` is set.
- *   4. `internal`  — Default. Covers internal team dev workspaces and
- *                    self-hosted production. Strict — matches today's
- *                    fail-fast behavior so internal devs and
- *                    self-hosters get loud errors on missing keys.
- *
- * **Strict** (`cloud`, `internal`) hard-fail at boot when an integration
- * key is missing.
- *
- * **Lenient** (`oss-dev`, `ci`) allow the app to boot with missing keys;
- * call sites lazy-throw / no-op so features degrade visibly rather than
- * crashing module load.
- *
- * Default-strict at runtime is the conservative direction: an internal
- * dev or self-hoster who forgets to source their `.env` gets a clear
- * failure, not a silently-degraded app. OSS contributors trade a one-time
- * `SUPERSET_OSS=1` for that safety guarantee. CI build steps degrade so
- * lint/typecheck/test don't require every production secret.
+ * `SUPERSET_PROFILE=local` is the explicit contributor opt-in for a fresh
+ * clone backed by local Postgres/Electric and no third-party credentials.
  */
-export type DeploymentProfile = "cloud" | "oss-dev" | "ci" | "internal";
+export type DeploymentProfile = "cloud" | "local" | "ci" | "internal";
+
+const VALID_PROFILES: DeploymentProfile[] = [
+	"cloud",
+	"local",
+	"ci",
+	"internal",
+];
+
+function isTruthyFlag(value: string | undefined): boolean {
+	return value === "1" || value === "true";
+}
+
+function getExplicitProfile(
+	envSource: Record<string, string | undefined>,
+): DeploymentProfile | undefined {
+	const explicitProfile = envSource.SUPERSET_PROFILE;
+	if (!explicitProfile) return undefined;
+	if (VALID_PROFILES.includes(explicitProfile as DeploymentProfile)) {
+		return explicitProfile as DeploymentProfile;
+	}
+	throw new Error(
+		`Invalid SUPERSET_PROFILE="${explicitProfile}". Expected one of: ${VALID_PROFILES.join(
+			", ",
+		)}.`,
+	);
+}
 
 export function getDeploymentProfile(
 	envSource: Record<string, string | undefined> = process.env,
 ): DeploymentProfile {
-	if (envSource.VERCEL === "1") return "cloud";
-	if (envSource.SUPERSET_OSS === "1") return "oss-dev";
-	if (envSource.CI === "true") return "ci";
+	if (isTruthyFlag(envSource.VERCEL) || envSource.VERCEL_ENV) return "cloud";
+	const explicitProfile = getExplicitProfile(envSource);
+	if (explicitProfile) return explicitProfile;
+	if (isTruthyFlag(envSource.CI)) return "ci";
 	return "internal";
 }
 
-export function isStrictProfile(profile: DeploymentProfile): boolean {
-	return profile !== "oss-dev" && profile !== "ci";
+export function isStrictProfile(
+	profile: DeploymentProfile = getDeploymentProfile(),
+): boolean {
+	return profile === "cloud" || profile === "internal";
+}
+
+export function isLocalProfile(
+	profile: DeploymentProfile = getDeploymentProfile(),
+): boolean {
+	return profile === "local";
+}
+
+export function shouldSkipEnvValidation(
+	envSource: Record<string, string | undefined> = process.env,
+): boolean {
+	return (
+		!isStrictProfile(getDeploymentProfile(envSource)) ||
+		isTruthyFlag(envSource.SKIP_ENV_VALIDATION)
+	);
 }
diff --git a/packages/trpc/src/env.ts b/packages/trpc/src/env.ts
index 50e424015d2..a10cd45a39e 100644
--- a/packages/trpc/src/env.ts
+++ b/packages/trpc/src/env.ts
@@ -1,17 +1,8 @@
-import {
-	getDeploymentProfile,
-	isStrictProfile,
-} from "@superset/shared/deployment-profile";
+import { shouldSkipEnvValidation } from "@superset/shared/deployment-profile";
 import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
-// Default profile is `internal` (strict). OSS contributors set
-// SUPERSET_OSS=1 to opt into the lenient `oss-dev` profile, which
-// skips env validation so a fresh clone boots without every key.
-// SKIP_ENV_VALIDATION=1 remains a build-time escape hatch.
-const profile = getDeploymentProfile();
-const skipValidation =
-	!isStrictProfile(profile) || !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 
 export const env = createEnv({
 	server: {
diff --git a/packages/trpc/src/lib/integrations/sync/tasks.ts b/packages/trpc/src/lib/integrations/sync/tasks.ts
index d749dbfb6e3..2776ec8619e 100644
--- a/packages/trpc/src/lib/integrations/sync/tasks.ts
+++ b/packages/trpc/src/lib/integrations/sync/tasks.ts
@@ -1,10 +1,8 @@
 import { db } from "@superset/db/client";
 import { integrationConnections, tasks } from "@superset/db/schema";
-import { Client } from "@upstash/qstash";
 import { eq } from "drizzle-orm";
 import { env } from "../../../env";
-
-const qstash = new Client({ token: env.QSTASH_TOKEN });
+import { qstash } from "../../qstash";
 
 const PROVIDER_ENDPOINTS: Record<string, string> = {
 	linear: "/api/integrations/linear/jobs/sync-task",
@@ -36,6 +34,10 @@ export async function syncTask(taskId: string) {
 
 			const syncUrl = `${qstashBaseUrl}${endpoint}`;
 
+			if (!qstash) {
+				throw new Error("QSTASH_TOKEN is required to sync integration tasks");
+			}
+
 			await qstash.publishJSON({
 				url: syncUrl,
 				body: { taskId },
diff --git a/packages/trpc/src/lib/qstash.ts b/packages/trpc/src/lib/qstash.ts
new file mode 100644
index 00000000000..8562a6991a8
--- /dev/null
+++ b/packages/trpc/src/lib/qstash.ts
@@ -0,0 +1,17 @@
+import { Client } from "@upstash/qstash";
+
+import { env } from "../env";
+
+export const qstash = env.QSTASH_TOKEN
+	? new Client({ token: env.QSTASH_TOKEN })
+	: null;
+
+export function requireQstash(context: string) {
+	if (!qstash) {
+		throw new Error(
+			`[${context}] QSTASH_TOKEN is required to enqueue background jobs`,
+		);
+	}
+
+	return qstash;
+}
diff --git a/packages/trpc/src/router/integration/github/github.ts b/packages/trpc/src/router/integration/github/github.ts
index 6d4456a432c..bb54ed14a52 100644
--- a/packages/trpc/src/router/integration/github/github.ts
+++ b/packages/trpc/src/router/integration/github/github.ts
@@ -6,15 +6,13 @@ import {
 } from "@superset/db/schema";
 import type { TRPCRouterRecord } from "@trpc/server";
 import { TRPCError } from "@trpc/server";
-import { Client } from "@upstash/qstash";
 import { and, desc, eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 import { env } from "../../../env";
+import { qstash } from "../../../lib/qstash";
 import { protectedProcedure } from "../../../trpc";
 import { verifyOrgAdmin, verifyOrgMembership } from "../utils";
 
-const qstash = new Client({ token: env.QSTASH_TOKEN });
-
 export const githubRouter = {
 	getInstallation: protectedProcedure
 		.input(z.object({ organizationId: z.string().uuid() }))
@@ -86,6 +84,13 @@ export const githubRouter = {
 					console.error("[github/triggerSync] Dev sync failed:", error);
 				});
 			} else {
+				if (!qstash) {
+					throw new TRPCError({
+						code: "PRECONDITION_FAILED",
+						message: "QStash is not configured",
+					});
+				}
+
 				await qstash.publishJSON({
 					url: syncUrl,
 					body: syncBody,
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index 0623f78f648..b96adf3373a 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -12,7 +12,7 @@ Three audiences with different expectations:
 
 1. **OSS contributor (fresh GitHub clone)**
    - Has Docker + Bun, nothing else
-   - Wants `git clone && SUPERSET_OSS=1 bun dev` to land them in a working app, signed in
+   - Wants `git clone && SUPERSET_PROFILE=local bun dev` to land them in a working app, signed in
    - Features that need cloud keys should degrade visibly, never crash boot
    - Must not silently sync against hosted production endpoints
 
@@ -31,16 +31,16 @@ Three audiences with different expectations:
 
 | Profile     | Trigger                                  | Validation | Notes |
 |-------------|------------------------------------------|------------|-------|
-| `cloud`     | `VERCEL=1` (auto, set by Vercel runtime) | Strict     | Untypable by contributor |
-| `oss-dev`   | `SUPERSET_OSS=1`                         | Lenient    | Explicit OSS opt-in |
+| `cloud`     | `VERCEL=1` or `VERCEL_ENV` (set by Vercel) | Strict     | Vercel deploy/build context |
+| `local`     | `SUPERSET_PROFILE=local`                 | Lenient    | Explicit local contributor opt-in |
 | `ci`        | `CI=true` (auto by GH Actions et al.)    | Lenient    | Build/lint/test don't need prod secrets |
 | `internal`  | default                                  | Strict     | Covers internal team dev + self-hosted prod |
 
 Resolution order in `getDeploymentProfile()` (most-trusted wins):
 
 ```ts
-if (env.VERCEL === "1")        return "cloud";
-if (env.SUPERSET_OSS === "1")  return "oss-dev";
+if (env.VERCEL === "1" || env.VERCEL_ENV) return "cloud";
+if (env.SUPERSET_PROFILE === "local") return "local";
 if (env.CI === "true")         return "ci";
 return "internal";
 ```
@@ -48,9 +48,7 @@ return "internal";
 Each env schema (`apps/api`, `apps/web`, `apps/admin`, `apps/marketing`, `apps/docs`, `apps/relay`, `apps/desktop/src/main/env.main`, `packages/trpc`) computes:
 
 ```ts
-const skipValidation =
-  !isStrictProfile(getDeploymentProfile()) ||
-  !!process.env.SKIP_ENV_VALIDATION;
+const skipValidation = shouldSkipEnvValidation();
 ```
 
 `SKIP_ENV_VALIDATION=1` remains a build-time escape hatch (Docker preview builds, etc.) — not the primary discriminator.
@@ -72,8 +70,8 @@ const skipValidation =
 
 ### Desktop main process
 
-- **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — fired once during `app.whenReady()` when `getDeploymentProfile() === "oss-dev"`. Polls `/api/auth/ok` with 1s interval × 60s timeout (auto-sign-in survives the race against API startup), then POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if missing). Persists the token via the same `saveToken()` that OAuth uses. Renderer stays prod-pure.
-- **`apps/desktop/src/main/index.ts`** — calls `void ensureDevAuthToken()` (fire-and-forget) so the window opens immediately. `AuthProvider`'s `onTokenChanged` subscription re-hydrates when the token lands. Also exposes Chrome DevTools Protocol on `localhost:9333` in `oss-dev` for headless verification.
+- **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — fired once during `app.whenReady()` when `isLocalProfile()` is true. Polls `/api/auth/ok` with 1s interval × 60s timeout (auto-sign-in survives the race against API startup), then POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if missing). Persists the token via the same `saveToken()` that OAuth uses. Renderer stays prod-pure.
+- **`apps/desktop/src/main/index.ts`** — calls `void ensureDevAuthToken()` (fire-and-forget) so the window opens immediately. `AuthProvider`'s `onTokenChanged` subscription re-hydrates when the token lands. Also exposes Chrome DevTools Protocol on `localhost:9333` in the local profile for headless verification.
 - **`apps/desktop/src/main/env.main.ts`** — env defaults switch to localhost in dev builds (`NODE_ENV=development`) so a fresh-clone session never silently points main-process clients at hosted production. Profile check inlined here (rather than imported from `@superset/shared`) because `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time using Node's ESM loader, which can't transform `.ts` files from sibling workspace packages.
 
 ### Desktop renderer
@@ -98,7 +96,7 @@ const skipValidation =
 
 ### Plumbing
 
-- **`turbo.jsonc`** — `SUPERSET_OSS`, `CI`, `VERCEL`, `SKIP_ENV_VALIDATION` moved to `globalEnv` (was `globalPassThroughEnv`). Profile-affecting flags now hash into the cache key so strict/lenient cached builds can't cross-contaminate.
+- **`turbo.jsonc`** — `SUPERSET_PROFILE`, `CI`, `VERCEL`, `VERCEL_ENV`, and `SKIP_ENV_VALIDATION` live in `globalEnv`. Profile-affecting flags now hash into the cache key so strict/lenient cached builds can't cross-contaminate.
 - **`package.json`** — `bun db:seed:dev` root script.
 
 ### Docs
@@ -116,21 +114,21 @@ const skipValidation =
 
 **Why:** The Formbricks refactor would touch ~70 schema entries and ~100+ consumer sites that assume non-null. The skipValidation approach is one line per env file, no consumer changes, and the runtime behavior is identical: in OSS, the env object has whatever's in `process.env` (possibly empty strings); call sites that crash get wrapped in lazy guards as discovered.
 
-### Why strict-by-default with `SUPERSET_OSS=1` opt-in, not lenient-by-default with `SUPERSET_INTERNAL_DEV=1` opt-in?
+### Why strict-by-default with `SUPERSET_PROFILE=local` opt-in, not lenient-by-default with `SUPERSET_INTERNAL_DEV=1` opt-in?
 
 **Rejected:** Default to lenient + write `SUPERSET_INTERNAL_DEV=1` from `.superset/setup.sh` so internal devs land in strict.
 
-**Chosen:** Default to strict + OSS contributors set `SUPERSET_OSS=1`.
+**Chosen:** Default to strict + local contributors set `SUPERSET_PROFILE=local`.
 
 **Why:** Strict-by-default is the conservative direction. An internal dev or self-hoster who forgets to source their `.env` gets a clear failure, not a silently-degraded app. OSS contributors trade a one-time flag for that safety guarantee. Also: no setup-script edit means internal devs' workflow is byte-identical to today.
 
-### Why not gate on `NODE_ENV === "production"` instead of `VERCEL=1`?
+### Why not gate on `NODE_ENV === "production"` instead of Vercel env markers?
 
 **Rejected:** Use `NODE_ENV === "production"` as the cloud discriminator.
 
-**Chosen:** `VERCEL=1` (auto at Vercel runtime) for cloud, `NODE_ENV` only as a fallback indicator inside the `internal` default.
+**Chosen:** `VERCEL=1` or `VERCEL_ENV` for cloud, `NODE_ENV` only as a fallback indicator inside the `internal` default.
 
-**Why:** `NODE_ENV=production` is true in self-hosted dev too — it conflates "deployed to Vercel" with "operator running the production build locally." Self-hosters are legitimate prod operators and we want them strict, but they have different keys than Vercel (no `VERCEL_*` vars, no Vercel-specific URLs). Discriminating on `VERCEL=1` keeps cloud and self-hosted as two distinct strict-validated buckets.
+**Why:** `NODE_ENV=production` is true in self-hosted dev too — it conflates "deployed to Vercel" with "operator running the production build locally." Self-hosters are legitimate prod operators and we want them strict, but they have different keys than Vercel (no `VERCEL_*` vars, no Vercel-specific URLs). Discriminating on Vercel env markers keeps cloud and self-hosted as two distinct strict-validated buckets.
 
 ### Why a `ci` profile when `SKIP_ENV_VALIDATION=1` already exists?
 
@@ -146,7 +144,7 @@ const skipValidation =
 
 **Chosen:** Hash into the cache key.
 
-**Why:** A `bun run build` cached with `SUPERSET_OSS=1` (validation skipped) could be served back when the next caller doesn't have the flag (validation expected). Same for `CI=true` vs not. Caches that disagree about validation produce bugs that are very hard to attribute. Cache invalidation cost is acceptable — these flags don't flip often.
+**Why:** A `bun run build` cached with `SUPERSET_PROFILE=local` (validation skipped) could be served back when the next caller doesn't have the flag (validation expected). Same for `CI=true` vs not. Caches that disagree about validation produce bugs that are very hard to attribute. Cache invalidation cost is acceptable — these flags don't flip often.
 
 ### Why dev auto-sign-in in the main process, not the renderer?
 
@@ -216,7 +214,7 @@ I shipped the deployment-profile changes without checking `gh pr checks 4616`. T
 |---|---|
 | [`04130c0`](https://github.com/superset-sh/superset/pull/4616/commits/04130c0) | Core OSS path: DB driver swap, lazy-init guards (Stripe/Resend/PostHog), Better Auth email/password, desktop dev auto-sign-in, 17-file MOCK_ORG_ID priority fix, web app DevAuthForm, `db:seed:dev`, CDP for verification, docs |
 | [`2b609b5`](https://github.com/superset-sh/superset/pull/4616/commits/2b609b5) | Deployment profiles + boot summary + `/api/health` endpoint |
-| [`f3c76b9`](https://github.com/superset-sh/superset/pull/4616/commits/f3c76b9) | Flipped discriminator (strict by default, `SUPERSET_OSS=1` opts into lenient) |
+| [`f3c76b9`](https://github.com/superset-sh/superset/pull/4616/commits/f3c76b9) | Flipped discriminator (strict by default, local profile opts into lenient) |
 | [`101cd30`](https://github.com/superset-sh/superset/pull/4616/commits/101cd30) | Added `ci` profile (GitHub Actions auto-detect) |
 | [`513d198`](https://github.com/superset-sh/superset/pull/4616/commits/513d198) | Five review-finding fixes: Stripe gate in `afterCreateOrganization`, email/password disabled in prod, docker-compose.dev.yml + Electric URL defaults, auto-sign-in API readiness poll, profile flags hash into Turbo cache |
 | [`f3254ef`](https://github.com/superset-sh/superset/pull/4616/commits/f3254ef) | Fixed CI build (inlined profile check in `env.main.ts`); remaining hardcoded prod URL defaults switched to `devOrProdUrl()` helper across `electron.vite.config.ts`, `vite/helpers.ts`, `env.main.ts` |
@@ -226,7 +224,7 @@ I shipped the deployment-profile changes without checking `gh pr checks 4616`. T
 End-to-end smoke test after final commit:
 
 ```
-[superset] profile=oss-dev (lenient)
+[superset] profile=local (lenient)
 [superset] disabled features (set the listed env var to enable):
            - stripe                       STRIPE_SECRET_KEY
            - resend (email)               RESEND_API_KEY
@@ -245,11 +243,11 @@ admin@local.test | Local Admin's Team | 14019d9c-team | <NULL>
 Profile resolution unit test (all 6 cases pass):
 ```
 ✓ fresh clone (no env)                  → internal  (strict)
-✓ OSS contributor                       → oss-dev   (lenient)
+✓ Local contributor                     → local     (lenient)
 ✓ GitHub Actions                        → ci        (lenient)
 ✓ Vercel runtime                        → cloud     (strict)
 ✓ Vercel runtime overrides CI           → cloud     (strict)
-✓ OSS overrides CI                      → oss-dev   (lenient)
+✓ Local profile overrides CI            → local     (lenient)
 ```
 
 CDP-probed React context:
@@ -268,7 +266,7 @@ These are real follow-ups, none of them blocking the OSS path from working today
 
 - **`.env.example` with working defaults** — README says "edit DATABASE_URL + BETTER_AUTH_SECRET" without telling contributors the values. Pre-fill `postgres://superset:superset@localhost:5433/superset` + a sentinel `BETTER_AUTH_SECRET=dev_secret_not_for_production_*` and move optional integration keys to a `# OPTIONAL` block.
 - **`bun setup` orchestrator** — current contributor flow is 6 commands. A `bun setup` wrapping `docker compose up`, `cp .env.example .env` if missing, `bun install`, `bun run db:migrate`, copy `.dev.vars`, with idempotency + friendly errors would collapse it to two: `bun setup && bun dev`.
-- **Full integration crash audit** — Stripe, Resend, PostHog, trpc-support-Resend are wrapped. GitHub App (`@octokit/app`), Freestyle, Linear, Slack, QStash signing keys, Anthropic (`@anthropic-ai/sdk`), Blob (`@vercel/blob`) may still crash at import in oss-dev. Mechanical `grep -rn "new \w\+(.*env\." packages apps` survey.
+- **Full integration crash audit** — Stripe, Resend, PostHog, trpc-support-Resend are wrapped. GitHub App (`@octokit/app`), Freestyle, Linear, Slack, QStash signing keys, Anthropic (`@anthropic-ai/sdk`), Blob (`@vercel/blob`) may still crash at import in the local profile. Mechanical `grep -rn "new \w\+(.*env\." packages apps` survey.
 - **Mailpit instead of console-log emails** — Better Auth's `sendEmail` falls back to stdout. Mailpit container would give contributors a clickable UI at `localhost:8025`.
 - **CI fresh-clone smoke test** — without one, the OSS path silently rots the next time someone adds a crash-on-import integration. A GitHub Actions job that does `git clone` in a fresh runner, follows the README, hits `/api/auth/ok`, fails if anything red.
 - **Per-integration group `.refine()` validation** — Formbricks pattern. E.g. if `STRIPE_SECRET_KEY` is set then `STRIPE_WEBHOOK_SECRET` must also be set. Catches half-configured prod deploys.
@@ -281,11 +279,11 @@ These are real follow-ups, none of them blocking the OSS path from working today
 ┌─────────────────────────────────────────────────────────────────────┐
 │                       getDeploymentProfile()                         │
 │                                                                      │
-│   VERCEL === "1"        ─────────────────►  cloud      (strict)     │
+│   VERCEL === "1" or VERCEL_ENV ─────────►  cloud      (strict)     │
 │       │                                                              │
 │       no                                                             │
 │       ▼                                                              │
-│   SUPERSET_OSS === "1"  ─────────────────►  oss-dev    (lenient)    │
+│   SUPERSET_PROFILE=local ────────────────►  local      (lenient)    │
 │       │                                                              │
 │       no                                                             │
 │       ▼                                                              │
@@ -297,7 +295,7 @@ These are real follow-ups, none of them blocking the OSS path from working today
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-### OSS-dev session lifecycle
+### Local session lifecycle
 
 ```
 ┌──────────────────┐                  ┌──────────────────┐
@@ -310,7 +308,7 @@ These are real follow-ups, none of them blocking the OSS path from working today
         │                                       │
         ▼                                       ▼
 ┌──────────────────────────────────────────────────────────────┐
-│  bun dev (with SUPERSET_OSS=1)                                │
+│  bun dev (with SUPERSET_PROFILE=local)                         │
 │                                                                │
 │  apps/web      :4640  ─ Next.js, DevAuthForm visible          │
 │  apps/api      :4641  ─ Better Auth + tRPC, /api/health       │
@@ -341,4 +339,4 @@ These are real follow-ups, none of them blocking the OSS path from working today
 | `cloud`      | false (strict)   | `profile=cloud (strict)`    | `profile: "cloud"`        | OAuth (email/password disabled in prod build)  |
 | `internal`   | false (strict)   | `profile=internal (strict)` | `profile: "internal"`     | OAuth + dev email/password form (NODE_ENV=dev) |
 | `ci`         | true (lenient)   | `profile=ci (lenient)`      | `profile: "ci"`           | n/a (build/test job, no runtime auth)          |
-| `oss-dev`    | true (lenient)   | lists disabled features     | `profile: "oss-dev"`      | dev auto-sign-in + dev email/password form     |
+| `local`      | true (lenient)   | lists disabled features     | `profile: "local"`        | dev auto-sign-in + dev email/password form     |
diff --git a/turbo.jsonc b/turbo.jsonc
index 1cad43a65e6..91506a3a546 100644
--- a/turbo.jsonc
+++ b/turbo.jsonc
@@ -20,17 +20,14 @@
 		"KV_REST_API_TOKEN",
 		// Profile-affecting flags must hash into the cache key so
 		// strict and lenient builds never share cached outputs.
-		"SUPERSET_OSS",
+		"SUPERSET_PROFILE",
+		"SUPERSET_WORKSPACE_NAME",
 		"CI",
 		"VERCEL",
-		"SKIP_ENV_VALIDATION"
-	],
-	"globalPassThroughEnv": [
-		"NODE_ENV",
 		"VERCEL_ENV",
-		"VERCEL_URL",
-		"npm_lifecycle_event"
+		"SKIP_ENV_VALIDATION"
 	],
+	"globalPassThroughEnv": ["NODE_ENV", "VERCEL_URL", "npm_lifecycle_event"],
 	"tasks": {
 		"build": {
 			"inputs": ["$TURBO_DEFAULT$", ".env*"],

From 46b9d83916223cf5b621796da8ef64e38df4f8d0 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 11:42:00 -0700
Subject: [PATCH 09/28] chore: add local setup script

---
 README.md                 |   9 +--
 docs/LOCAL_DEVELOPMENT.md |  53 +++----------
 package.json              |   1 +
 scripts/setup-local.ts    | 160 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 174 insertions(+), 49 deletions(-)
 create mode 100644 scripts/setup-local.ts

diff --git a/README.md b/README.md
index e3a5d7cc05a..08de44c652c 100644
--- a/README.md
+++ b/README.md
@@ -93,16 +93,11 @@ Short version:
 git clone https://github.com/superset-sh/superset.git
 cd superset
 bun install
-docker compose -f docker-compose.dev.yml up -d   # Postgres + Electric
-cp .env.example .env
-cp apps/electric-proxy/.dev.vars.example apps/electric-proxy/.dev.vars
-bun run db:migrate
-cp Caddyfile.example Caddyfile && caddy trust
+bun setup:local
 bun dev
 ```
 
-The desktop window opens auto-signed-in as a seed admin (`admin@local.test`). See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details, troubleshooting, and what's stubbed without integration keys.
-The copied `.env` also isolates desktop state under `~/.superset-local-dev`, so source builds do not reuse production or canary desktop state.
+`bun setup:local` copies local examples, starts Docker Postgres/Electric, trusts Caddy's local CA, and runs migrations. It does not overwrite existing files. The desktop window opens auto-signed-in as `admin@local.test`, with state isolated under `~/.superset-local-dev` so source builds do not reuse production or canary desktop state. See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details and troubleshooting.
 
 To build a distributable desktop app:
 
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 8d3efcf0878..2adf8d33cea 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -1,6 +1,6 @@
 # Local Development
 
-How to run Superset locally from a fresh clone, with no Neon / OAuth / Stripe / Resend keys required. The dev path auto-creates a local admin user, runs Postgres in Docker, and signs you in before the desktop window opens.
+How to run Superset locally from a fresh clone with no Neon, OAuth, Stripe, Resend, or QStash keys. Local contributor state is isolated under `~/.superset-local-dev`, so this flow does not reuse production or canary desktop state from `~/.superset`.
 
 ## Prerequisites
 
@@ -9,60 +9,29 @@ How to run Superset locally from a fresh clone, with no Neon / OAuth / Stripe /
 - [Caddy](https://caddyserver.com/docs/install) (for HTTPS proxy)
 - macOS
 
-## One-time setup
+## Quick Start
 
 ```bash
 git clone https://github.com/superset-sh/superset.git
 cd superset
 bun install
+bun setup:local
+bun dev
 ```
 
-**1. Start Postgres + Electric**
-
-```bash
-docker compose -f docker-compose.dev.yml up -d
-```
-
-Brings up:
-- **Postgres 16** on host port `5433` with `wal_level=logical` (Electric replication requires it). Port 5433 avoids clobbering any host Postgres on the default 5432.
-- **Electric SQL** on host port `4649`, replicating from the Postgres above.
-
-These containers stay running between sessions; `docker compose down -v` to wipe them.
-
-**2. Create your `.env`**
-
-```bash
-cp .env.example .env
-```
-
-The example file is ready for the Docker defaults and includes `SUPERSET_PROFILE=local`, `SUPERSET_WORKSPACE_NAME=local-dev`, stable local ports, the local Postgres URL, and a development-only auth secret. The workspace name keeps desktop state in `~/.superset-local-dev` instead of the production / canary `~/.superset` directory. Integration keys (Stripe, Resend, GitHub App, etc.) can stay blank — features that need them will throw a clean "X not configured" error when you actually exercise them; nothing crashes at boot.
-
-**3. Apply the schema**
-
-```bash
-bun run db:migrate
-```
+`bun setup:local` is non-destructive. It copies `.env.example`, `apps/electric-proxy/.dev.vars.example`, and `Caddyfile.example` only when the target file is missing; starts Docker Postgres/Electric; runs `caddy trust`; and applies DB migrations.
 
-This creates the `auth` and `public` schemas and runs all Drizzle migrations. ~42 tables.
+If you already have an internal `.env`, the script leaves it untouched and stops before running migrations. Do not overwrite an internal `.env` unless you intentionally want the local contributor profile.
 
-**4. Wire electric-proxy + Caddy (HTTPS proxy)**
+Useful setup flags:
 
 ```bash
-cp apps/electric-proxy/.dev.vars.example apps/electric-proxy/.dev.vars
-cp Caddyfile.example Caddyfile
-caddy trust   # one-time, prompts for sudo
-```
-
-`.dev.vars` tells the Cloudflare Worker (electric-proxy) where to find your local Electric server (host port 4649 from docker-compose).
-Without `caddy trust`, Chromium will reject `https://localhost:*` with `ERR_CERT_AUTHORITY_INVALID`.
-
-## Run it
-
-```bash
-bun dev
+bun setup:local --skip-docker
+bun setup:local --skip-migrate
+bun setup:local --skip-caddy-trust
 ```
 
-The copied `.env` sets `SUPERSET_PROFILE=local`, which opts you into the lenient local contributor profile so the app boots without every integration key — Stripe, OAuth, Resend, etc. become optional. Without that profile, the app defaults to strict validation (matching the internal-team workflow) and will fail boot if any of those keys are missing.
+The generated `.env` sets `SUPERSET_PROFILE=local` and `SUPERSET_WORKSPACE_NAME=local-dev`. Missing integration keys are allowed at boot; features that need them fail cleanly when exercised.
 
 That brings up:
 
diff --git a/package.json b/package.json
index 10af6f4dcc6..6ed3717db54 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,7 @@
 		"dev:caddy": "dotenv -- caddy run --config Caddyfile",
 		"dev:docs": "turbo dev --filter=@superset/docs",
 		"dev:marketing": "turbo dev --filter=@superset/marketing --filter=@superset/docs",
+		"setup:local": "bun run scripts/setup-local.ts",
 		"build": "turbo build --filter=@superset/desktop",
 		"test": "turbo test --concurrency=2",
 		"lint": "./scripts/lint.sh",
diff --git a/scripts/setup-local.ts b/scripts/setup-local.ts
new file mode 100644
index 00000000000..079ee7446ba
--- /dev/null
+++ b/scripts/setup-local.ts
@@ -0,0 +1,160 @@
+#!/usr/bin/env bun
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+const args = new Set(process.argv.slice(2));
+const root = resolve(import.meta.dirname, "..");
+
+const help = `Usage: bun setup:local [options]
+
+Prepares a fresh-clone local contributor setup without cloud credentials.
+
+Options:
+  --skip-docker       Do not start Docker Postgres/Electric
+  --skip-migrate      Do not run database migrations
+  --skip-caddy-trust  Do not run caddy trust
+  -h, --help          Show this help
+`;
+
+function log(message: string): void {
+	console.log(`[setup:local] ${message}`);
+}
+
+function fail(message: string): never {
+	console.error(`[setup:local] ${message}`);
+	process.exit(1);
+}
+
+function run(command: string, commandArgs: string[]): void {
+	log(`$ ${[command, ...commandArgs].join(" ")}`);
+	const result = spawnSync(command, commandArgs, {
+		cwd: root,
+		stdio: "inherit",
+		env: process.env,
+	});
+	if (result.status !== 0) {
+		fail(`${command} ${commandArgs.join(" ")} failed`);
+	}
+}
+
+function commandExists(command: string): boolean {
+	const result = spawnSync("sh", ["-lc", `command -v ${command}`], {
+		cwd: root,
+		stdio: "ignore",
+	});
+	return result.status === 0;
+}
+
+function requireCommand(command: string, installHint: string): void {
+	if (!commandExists(command)) {
+		fail(`${command} is required. ${installHint}`);
+	}
+}
+
+function copyIfMissing(source: string, destination: string): void {
+	const sourcePath = resolve(root, source);
+	const destinationPath = resolve(root, destination);
+	if (existsSync(destinationPath)) {
+		log(`keeping existing ${destination}`);
+		return;
+	}
+	copyFileSync(sourcePath, destinationPath);
+	log(`created ${destination} from ${basename(source)}`);
+}
+
+function readEnvValue(name: string): string | undefined {
+	const envPath = resolve(root, ".env");
+	if (!existsSync(envPath)) return undefined;
+	const lines = readFileSync(envPath, "utf8").split(/\r?\n/);
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const [key, ...valueParts] = trimmed.split("=");
+		if (key === name) {
+			return valueParts.join("=").replace(/^["']|["']$/g, "");
+		}
+	}
+	return undefined;
+}
+
+function isLocalDatabaseUrl(value: string | undefined): boolean {
+	if (!value) return false;
+	try {
+		const url = new URL(value);
+		return ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+	} catch {
+		return false;
+	}
+}
+
+if (args.has("-h") || args.has("--help")) {
+	console.log(help);
+	process.exit(0);
+}
+
+if (process.platform !== "darwin") {
+	fail("local desktop development is currently documented for macOS only.");
+}
+
+requireCommand("bun", "Install Bun from https://bun.sh.");
+if (!args.has("--skip-docker")) {
+	requireCommand("docker", "Install Docker Desktop for macOS.");
+}
+if (!args.has("--skip-caddy-trust")) {
+	requireCommand("caddy", "Install Caddy with: brew install caddy");
+}
+
+copyIfMissing(".env.example", ".env");
+const profile = readEnvValue("SUPERSET_PROFILE");
+const workspaceName = readEnvValue("SUPERSET_WORKSPACE_NAME");
+if (profile !== "local" || workspaceName !== "local-dev") {
+	fail(
+		[
+			"existing .env is not the default contributor profile, so setup stopped before running migrations",
+			"expected: SUPERSET_PROFILE=local",
+			"expected: SUPERSET_WORKSPACE_NAME=local-dev",
+			"move your existing .env aside or update it intentionally, then rerun bun setup:local",
+		].join("\n"),
+	);
+}
+
+if (!isLocalDatabaseUrl(readEnvValue("DATABASE_URL"))) {
+	fail("DATABASE_URL must point at localhost for bun setup:local.");
+}
+
+if (!isLocalDatabaseUrl(readEnvValue("DATABASE_URL_UNPOOLED"))) {
+	fail("DATABASE_URL_UNPOOLED must point at localhost for bun setup:local.");
+}
+
+copyIfMissing(
+	"apps/electric-proxy/.dev.vars.example",
+	"apps/electric-proxy/.dev.vars",
+);
+copyIfMissing("Caddyfile.example", "Caddyfile");
+
+if (!args.has("--skip-docker")) {
+	run("docker", ["compose", "-f", "docker-compose.dev.yml", "up", "-d"]);
+}
+
+if (!args.has("--skip-caddy-trust")) {
+	run("caddy", ["trust"]);
+}
+
+if (!args.has("--skip-migrate")) {
+	run("bun", ["run", "db:migrate"]);
+}
+
+console.log(`
+Local setup is ready.
+
+Next:
+  bun dev
+
+Useful checks after boot:
+  curl -fsS http://localhost:4641/api/health
+  curl -fsS http://localhost:4641/api/auth/ok
+
+Desktop state for this setup lives in:
+  ~/.superset-local-dev
+`);

From 8cf0e708d1fe4cb799c9ee4f71b97305b3a66fd0 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 11:48:55 -0700
Subject: [PATCH 10/28] docs: clarify local env example

---
 .env.example | 43 ++++++++++++++++++++++++++-----------------
 1 file changed, 26 insertions(+), 17 deletions(-)

diff --git a/.env.example b/.env.example
index c39b88a8e81..dd21322bd3c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,14 +1,16 @@
-
-
 # =============================================================================
-# ROOT SUPERSET ENV
-# Shared by all worktrees via direnv
+# SUPERSET LOCAL DEVELOPMENT ENV
+# Copied to .env by `bun setup:local`.
+#
+# Keep .env machine-local and untracked. Blank optional integration keys are
+# intentional in the local profile; the app should boot without third-party
+# credentials and degrade only when those specific features are exercised.
 # =============================================================================
 
 # -----------------------------------------------------------------------------
-# Deployment Profile
+# Local Contributor Profile
 # -----------------------------------------------------------------------------
-# For fresh-clone local development without third-party credentials:
+# Required for fresh-clone local development without third-party credentials.
 SUPERSET_PROFILE=local
 
 # Keep desktop dev state separate from production / canary installs.
@@ -16,20 +18,13 @@ SUPERSET_PROFILE=local
 SUPERSET_WORKSPACE_NAME=local-dev
 
 # -----------------------------------------------------------------------------
-# Neon Organization Credentials
-# -----------------------------------------------------------------------------
-NEON_ORG_ID=
-NEON_PROJECT_ID=
-NEON_API_KEY=
-
-# -----------------------------------------------------------------------------
-# Local Database Credentials
+# Local Database
 # -----------------------------------------------------------------------------
 DATABASE_URL=postgres://superset:superset@localhost:5433/superset
 DATABASE_URL_UNPOOLED=postgres://superset:superset@localhost:5433/superset
 
 # -----------------------------------------------------------------------------
-# Local Dev Ports
+# Local Ports
 # -----------------------------------------------------------------------------
 WEB_PORT=4640
 API_PORT=4641
@@ -40,7 +35,7 @@ CADDY_ELECTRIC_PORT=4650
 WRANGLER_PORT=4652
 
 # -----------------------------------------------------------------------------
-# Cross-App URLs (Local Dev)
+# Local App URLs
 # -----------------------------------------------------------------------------
 NEXT_PUBLIC_API_URL=http://localhost:4641
 NEXT_PUBLIC_WEB_URL=http://localhost:4640
@@ -50,11 +45,25 @@ NEXT_PUBLIC_DOCS_URL=http://localhost:3004
 NEXT_PUBLIC_ELECTRIC_URL=https://localhost:4650
 
 # -----------------------------------------------------------------------------
-# Better Auth
+# Local Auth Defaults
 # -----------------------------------------------------------------------------
 BETTER_AUTH_SECRET=local_dev_secret_not_for_production
 NEXT_PUBLIC_COOKIE_DOMAIN=localhost
 
+# =============================================================================
+# OPTIONAL INTEGRATION CREDENTIALS
+# Leave these blank for the default local contributor flow.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Neon Organization Credentials
+# -----------------------------------------------------------------------------
+# Only needed for Neon-backed/internal workflows. The local setup script uses the
+# Docker Postgres URLs above.
+NEON_ORG_ID=
+NEON_PROJECT_ID=
+NEON_API_KEY=
+
 # -----------------------------------------------------------------------------
 # OAuth Credentials (for Desktop App direct auth)
 # -----------------------------------------------------------------------------

From 05ccc7eeb2037a48a30e28974bcaa14c2cd81db5 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 12:02:47 -0700
Subject: [PATCH 11/28] fix: tighten local profile guardrails

---
 apps/api/src/app/api/health/route.ts          |  9 ++++-
 apps/api/src/lib/analytics.ts                 |  3 +-
 apps/api/src/lib/boot-summary.ts              |  6 +--
 apps/api/src/lib/integration-status.test.ts   | 18 ++++++++-
 apps/api/src/lib/integration-status.ts        | 37 ++++++++++---------
 apps/desktop/src/main/lib/dev-auto-sign-in.ts |  2 +
 docs/LOCAL_DEVELOPMENT.md                     |  4 +-
 packages/auth/src/lib/rate-limit.ts           | 17 +++++++++
 packages/auth/src/lib/resend.ts               |  8 ++--
 packages/auth/src/server.ts                   |  9 +----
 packages/db/src/client.ts                     | 31 ++++++++++------
 packages/db/src/seed-dev.ts                   | 22 +++++++----
 packages/trpc/src/lib/analytics.ts            |  3 +-
 .../trpc/src/lib/integrations/sync/tasks.ts   | 29 ++++++++++++---
 packages/trpc/src/router/task/task.ts         | 15 ++++++--
 plans/20260515-oss-local-setup.md             |  6 +--
 scripts/setup-local.ts                        |  8 +++-
 17 files changed, 159 insertions(+), 68 deletions(-)

diff --git a/apps/api/src/app/api/health/route.ts b/apps/api/src/app/api/health/route.ts
index bcacc56abe1..9b3588d69ae 100644
--- a/apps/api/src/app/api/health/route.ts
+++ b/apps/api/src/app/api/health/route.ts
@@ -1,9 +1,16 @@
-import { getDeploymentProfile } from "@superset/shared/deployment-profile";
+import {
+	getDeploymentProfile,
+	isStrictProfile,
+} from "@superset/shared/deployment-profile";
 import { NextResponse } from "next/server";
 import { getIntegrationStatuses } from "../../../lib/integration-status";
 
 export function GET() {
 	const profile = getDeploymentProfile();
+	if (isStrictProfile(profile)) {
+		return NextResponse.json({ ok: true });
+	}
+
 	return NextResponse.json({
 		ok: true,
 		profile,
diff --git a/apps/api/src/lib/analytics.ts b/apps/api/src/lib/analytics.ts
index 8f5536ff5d3..53a39119ea9 100644
--- a/apps/api/src/lib/analytics.ts
+++ b/apps/api/src/lib/analytics.ts
@@ -28,6 +28,7 @@ export const posthog = new Proxy({} as PostHog, {
 				flushInterval: 0,
 			});
 		}
-		return Reflect.get(client, prop);
+		const value = Reflect.get(client, prop);
+		return typeof value === "function" ? value.bind(client) : value;
 	},
 });
diff --git a/apps/api/src/lib/boot-summary.ts b/apps/api/src/lib/boot-summary.ts
index 62d56014739..e8ecfc44ad7 100644
--- a/apps/api/src/lib/boot-summary.ts
+++ b/apps/api/src/lib/boot-summary.ts
@@ -24,9 +24,9 @@ export function logBootSummary(): void {
 		return;
 	}
 	console.log(
-		`[superset] disabled features (set the listed env var to enable):`,
+		`[superset] disabled features (set the listed env var(s) to enable):`,
 	);
-	for (const { label, envVar } of missing) {
-		console.log(`           - ${label.padEnd(28)} ${envVar}`);
+	for (const { label, envVars } of missing) {
+		console.log(`           - ${label.padEnd(28)} ${envVars.join(", ")}`);
 	}
 }
diff --git a/apps/api/src/lib/integration-status.test.ts b/apps/api/src/lib/integration-status.test.ts
index b33db68c6d9..3c29ba092f2 100644
--- a/apps/api/src/lib/integration-status.test.ts
+++ b/apps/api/src/lib/integration-status.test.ts
@@ -16,9 +16,25 @@ describe("integration status", () => {
 		expect(statuses.stripe).toBe("configured");
 		expect(statuses.resend).toBe("missing");
 		expect(statuses.posthog).toBe("missing");
+		expect(statuses["upstash-kv"]).toBe("missing");
 		expect(statuses.blob).toBe("missing");
 	});
 
+	it("requires all env vars for multi-key integrations", () => {
+		expect(
+			getIntegrationStatuses({
+				KV_REST_API_URL: "https://example.upstash.io",
+			})["upstash-kv"],
+		).toBe("missing");
+
+		expect(
+			getIntegrationStatuses({
+				KV_REST_API_URL: "https://example.upstash.io",
+				KV_REST_API_TOKEN: "token",
+			})["upstash-kv"],
+		).toBe("configured");
+	});
+
 	it("returns missing integrations with display labels for boot output", () => {
 		const missing = getMissingIntegrations({
 			STRIPE_SECRET_KEY: "sk_test",
@@ -28,7 +44,7 @@ describe("integration status", () => {
 		expect(missing).toContainEqual({
 			key: "blob",
 			label: "vercel-blob (uploads)",
-			envVar: "BLOB_READ_WRITE_TOKEN",
+			envVars: ["BLOB_READ_WRITE_TOKEN"],
 		});
 	});
 });
diff --git a/apps/api/src/lib/integration-status.ts b/apps/api/src/lib/integration-status.ts
index 4f79b132d63..ceb07171a3f 100644
--- a/apps/api/src/lib/integration-status.ts
+++ b/apps/api/src/lib/integration-status.ts
@@ -1,31 +1,30 @@
 export const INTEGRATIONS = [
-	{ key: "stripe", label: "stripe", envVar: "STRIPE_SECRET_KEY" },
-	{ key: "resend", label: "resend (email)", envVar: "RESEND_API_KEY" },
+	{ key: "stripe", label: "stripe", envVars: ["STRIPE_SECRET_KEY"] },
+	{ key: "resend", label: "resend (email)", envVars: ["RESEND_API_KEY"] },
 	{
 		key: "posthog",
 		label: "posthog (telemetry)",
-		envVar: "NEXT_PUBLIC_POSTHOG_KEY",
+		envVars: ["NEXT_PUBLIC_POSTHOG_KEY"],
 	},
-	{ key: "sentry", label: "sentry", envVar: "NEXT_PUBLIC_SENTRY_DSN_API" },
-	{ key: "github-app", label: "github-app", envVar: "GH_APP_ID" },
-	{ key: "github-oauth", label: "github-oauth", envVar: "GH_CLIENT_ID" },
-	{ key: "google-oauth", label: "google-oauth", envVar: "GOOGLE_CLIENT_ID" },
-	{ key: "linear", label: "linear", envVar: "LINEAR_CLIENT_ID" },
-	{ key: "slack", label: "slack", envVar: "SLACK_CLIENT_ID" },
-	{ key: "freestyle", label: "freestyle", envVar: "FREESTYLE_API_KEY" },
-	{ key: "qstash", label: "qstash (jobs)", envVar: "QSTASH_TOKEN" },
+	{ key: "sentry", label: "sentry", envVars: ["NEXT_PUBLIC_SENTRY_DSN_API"] },
+	{ key: "github-app", label: "github-app", envVars: ["GH_APP_ID"] },
+	{ key: "github-oauth", label: "github-oauth", envVars: ["GH_CLIENT_ID"] },
+	{ key: "google-oauth", label: "google-oauth", envVars: ["GOOGLE_CLIENT_ID"] },
+	{ key: "linear", label: "linear", envVars: ["LINEAR_CLIENT_ID"] },
+	{ key: "slack", label: "slack", envVars: ["SLACK_CLIENT_ID"] },
+	{ key: "qstash", label: "qstash (jobs)", envVars: ["QSTASH_TOKEN"] },
 	{
 		key: "upstash-kv",
 		label: "upstash-kv (rate limit)",
-		envVar: "KV_REST_API_URL",
+		envVars: ["KV_REST_API_URL", "KV_REST_API_TOKEN"],
 	},
 	{
 		key: "blob",
 		label: "vercel-blob (uploads)",
-		envVar: "BLOB_READ_WRITE_TOKEN",
+		envVars: ["BLOB_READ_WRITE_TOKEN"],
 	},
-	{ key: "anthropic", label: "anthropic", envVar: "ANTHROPIC_API_KEY" },
-	{ key: "tavily", label: "tavily (search)", envVar: "TAVILY_API_KEY" },
+	{ key: "anthropic", label: "anthropic", envVars: ["ANTHROPIC_API_KEY"] },
+	{ key: "tavily", label: "tavily (search)", envVars: ["TAVILY_API_KEY"] },
 ] as const;
 
 export type IntegrationKey = (typeof INTEGRATIONS)[number]["key"];
@@ -36,9 +35,9 @@ export function getIntegrationStatuses(
 	envSource: Record<string, string | undefined> = process.env,
 ): Record<IntegrationKey, IntegrationStatus> {
 	return Object.fromEntries(
-		INTEGRATIONS.map(({ key, envVar }) => [
+		INTEGRATIONS.map(({ key, envVars }) => [
 			key,
-			envSource[envVar] ? "configured" : "missing",
+			envVars.every((envVar) => envSource[envVar]) ? "configured" : "missing",
 		]),
 	) as Record<IntegrationKey, IntegrationStatus>;
 }
@@ -46,5 +45,7 @@ export function getIntegrationStatuses(
 export function getMissingIntegrations(
 	envSource: Record<string, string | undefined> = process.env,
 ): Integration[] {
-	return INTEGRATIONS.filter(({ envVar }) => !envSource[envVar]);
+	return INTEGRATIONS.filter(({ envVars }) =>
+		envVars.some((envVar) => !envSource[envVar]),
+	);
 }
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
index 8a912a744c8..13d217e4f6d 100644
--- a/apps/desktop/src/main/lib/dev-auto-sign-in.ts
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -9,6 +9,7 @@ const DEV_EMAIL = "admin@local.test";
 const DEV_PASSWORD = "supersetdev";
 const DEV_NAME = "Local Admin";
 const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
+const DEV_AUTH_TIMEOUT_MS = 8000;
 
 // API may take a few seconds to compile on first dev launch (Turbo starts
 // services concurrently). Poll /api/auth/ok before giving up.
@@ -36,6 +37,7 @@ async function postAuth<T>(
 			Origin: mainEnv.NEXT_PUBLIC_API_URL,
 		},
 		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(DEV_AUTH_TIMEOUT_MS),
 	});
 	const data = (await res.json().catch(() => ({}))) as T | AuthErrorBody;
 	return { ok: res.ok, status: res.status, data };
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 2adf8d33cea..e589742cb37 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -75,9 +75,9 @@ The escape hatch `SKIP_ENV_VALIDATION=1` still works for one-off bypass cases (e
 
 When the API boots in the `local` profile, it prints a one-time summary of what's disabled:
 
-```
+```text
 [superset] profile=local (lenient)
-[superset] disabled features (set the listed env var to enable):
+[superset] disabled features (set the listed env var(s) to enable):
            - stripe                       STRIPE_SECRET_KEY
            - resend (email)               RESEND_API_KEY
            - posthog (telemetry)          NEXT_PUBLIC_POSTHOG_KEY
diff --git a/packages/auth/src/lib/rate-limit.ts b/packages/auth/src/lib/rate-limit.ts
index c67a4470147..aaf029262eb 100644
--- a/packages/auth/src/lib/rate-limit.ts
+++ b/packages/auth/src/lib/rate-limit.ts
@@ -1,3 +1,4 @@
+import { isStrictProfile } from "@superset/shared/deployment-profile";
 import { Ratelimit } from "@upstash/ratelimit";
 import { Redis } from "@upstash/redis";
 import { env } from "../env";
@@ -14,3 +15,19 @@ export const invitationRateLimit =
 				prefix: "ratelimit:invitation",
 			})
 		: null;
+
+export async function checkInvitationRateLimit(
+	inviterId: string,
+): Promise<void> {
+	if (!invitationRateLimit) {
+		if (isStrictProfile()) {
+			throw new Error("Invitation rate limiting is not configured.");
+		}
+		return;
+	}
+
+	const limit = await invitationRateLimit.limit(inviterId);
+	if (!limit.success) {
+		throw new Error("Rate limit exceeded. Max 10 invitations per hour.");
+	}
+}
diff --git a/packages/auth/src/lib/resend.ts b/packages/auth/src/lib/resend.ts
index fcdc09ae6c8..a94b392b11f 100644
--- a/packages/auth/src/lib/resend.ts
+++ b/packages/auth/src/lib/resend.ts
@@ -1,3 +1,4 @@
+import { isStrictProfile } from "@superset/shared/deployment-profile";
 import { Resend } from "resend";
 
 import { env } from "../env";
@@ -38,14 +39,15 @@ function logConsoleSend(arg: unknown) {
 
 // Lazy proxy over the full Resend surface. Throws only when actually used
 // without a key — except `emails.send` and `batch.send`, which fall back to
-// logging to stdout so Better Auth's signup/verification flows work in dev.
+// logging to stdout in lenient profiles so Better Auth's local signup flows work.
 export const resend = new Proxy({} as Resend, {
 	get(_t, prop) {
 		if (!env.RESEND_API_KEY) {
-			if (prop === "emails") {
+			const allowConsoleFallback = !isStrictProfile();
+			if (allowConsoleFallback && prop === "emails") {
 				return { send: (arg: unknown) => logConsoleSend(arg) };
 			}
-			if (prop === "batch") {
+			if (allowConsoleFallback && prop === "batch") {
 				return { send: (arg: unknown) => logConsoleSend(arg) };
 			}
 			throw new Error(
diff --git a/packages/auth/src/server.ts b/packages/auth/src/server.ts
index cbd7d9cf031..1eaca9c1c63 100644
--- a/packages/auth/src/server.ts
+++ b/packages/auth/src/server.ts
@@ -27,7 +27,7 @@ import type Stripe from "stripe";
 import { env } from "./env";
 import { acceptInvitationEndpoint } from "./lib/accept-invitation-endpoint";
 import { generateMagicTokenForInvite } from "./lib/generate-magic-token";
-import { invitationRateLimit } from "./lib/rate-limit";
+import { checkInvitationRateLimit } from "./lib/rate-limit";
 import { resend } from "./lib/resend";
 import {
 	resolveSessionOrganizationState,
@@ -331,12 +331,7 @@ export const auth = betterAuth({
 				beforeCreateInvitation: async (data) => {
 					const { inviterId, organizationId, role, teamId } = data.invitation;
 
-					const limit = await invitationRateLimit?.limit(inviterId);
-					if (limit && !limit.success) {
-						throw new Error(
-							"Rate limit exceeded. Max 10 invitations per hour.",
-						);
-					}
+					await checkInvitationRateLimit(inviterId);
 
 					const inviterMember = await db.query.members.findFirst({
 						where: and(
diff --git a/packages/db/src/client.ts b/packages/db/src/client.ts
index 4c3ef0a55be..76b9f0d3726 100644
--- a/packages/db/src/client.ts
+++ b/packages/db/src/client.ts
@@ -10,7 +10,16 @@ import * as schema from "./schema";
 
 config({ path: ".env", quiet: true });
 
-const isNeon = /\.neon\.tech|neon\.build/.test(env.DATABASE_URL);
+function isNeonDatabaseUrl(value: string): boolean {
+	try {
+		const hostname = new URL(value).hostname;
+		return hostname.endsWith(".neon.tech") || hostname.endsWith(".neon.build");
+	} catch {
+		return false;
+	}
+}
+
+const isNeon = isNeonDatabaseUrl(env.DATABASE_URL);
 
 // Single canonical type — both adapters expose the same Drizzle PG surface at
 // runtime, so we narrow callers to the Neon-HTTP shape (the production path)
@@ -18,17 +27,21 @@ const isNeon = /\.neon\.tech|neon\.build/.test(env.DATABASE_URL);
 type Db = ReturnType<typeof drizzleNeonHttp<typeof schema>>;
 type DbWs = ReturnType<typeof drizzleNeonWs<typeof schema>>;
 
+const nodePgDb = isNeon
+	? null
+	: drizzleNodePg({
+			client: new pg.Pool({ connectionString: env.DATABASE_URL }),
+			schema,
+			casing: "snake_case",
+		});
+
 export const db: Db = isNeon
 	? drizzleNeonHttp({
 			client: neon(env.DATABASE_URL),
 			schema,
 			casing: "snake_case",
 		})
-	: (drizzleNodePg({
-			client: new pg.Pool({ connectionString: env.DATABASE_URL }),
-			schema,
-			casing: "snake_case",
-		}) as unknown as Db);
+	: (nodePgDb as unknown as Db);
 
 export const dbWs: DbWs = isNeon
 	? drizzleNeonWs({
@@ -36,8 +49,4 @@ export const dbWs: DbWs = isNeon
 			schema,
 			casing: "snake_case",
 		})
-	: (drizzleNodePg({
-			client: new pg.Pool({ connectionString: env.DATABASE_URL }),
-			schema,
-			casing: "snake_case",
-		}) as unknown as DbWs);
+	: (nodePgDb as unknown as DbWs);
diff --git a/packages/db/src/seed-dev.ts b/packages/db/src/seed-dev.ts
index a003b79415f..b06b9a4410a 100644
--- a/packages/db/src/seed-dev.ts
+++ b/packages/db/src/seed-dev.ts
@@ -8,6 +8,18 @@ config({ path: path.resolve(__dirname, "../../../.env"), quiet: true });
 const DEV_ADMIN_EMAIL = "admin@local.test";
 const DEV_ADMIN_PASSWORD = "supersetdev";
 const DEV_ADMIN_NAME = "Local Admin";
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+function requireLocalUrl(value: string, label: string): URL {
+	const url = new URL(value);
+	if (!LOCAL_HOSTS.has(url.hostname)) {
+		console.error(
+			`FATAL: db:seed refuses to run against non-localhost ${label}: ${url.hostname}`,
+		);
+		process.exit(1);
+	}
+	return url;
+}
 
 async function main() {
 	if (process.env.NODE_ENV === "production") {
@@ -21,16 +33,10 @@ async function main() {
 		process.exit(1);
 	}
 
-	const url = new URL(dbUrl);
-	const allowedHosts = new Set(["localhost", "127.0.0.1", "::1"]);
-	if (!allowedHosts.has(url.hostname)) {
-		console.error(
-			`FATAL: db:seed refuses to run against non-localhost host: ${url.hostname}`,
-		);
-		process.exit(1);
-	}
+	requireLocalUrl(dbUrl, "database host");
 
 	const apiUrl = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4641";
+	requireLocalUrl(apiUrl, "API host");
 	const endpoint = `${apiUrl}/api/auth/sign-up/email`;
 
 	console.log(`Seeding dev admin via ${endpoint}`);
diff --git a/packages/trpc/src/lib/analytics.ts b/packages/trpc/src/lib/analytics.ts
index d1d1c6213dd..19ae9242c98 100644
--- a/packages/trpc/src/lib/analytics.ts
+++ b/packages/trpc/src/lib/analytics.ts
@@ -30,6 +30,7 @@ export const posthog = new Proxy({} as PostHog, {
 				flushInterval: 0,
 			});
 		}
-		return Reflect.get(client, prop);
+		const value = Reflect.get(client, prop);
+		return typeof value === "function" ? value.bind(client) : value;
 	},
 });
diff --git a/packages/trpc/src/lib/integrations/sync/tasks.ts b/packages/trpc/src/lib/integrations/sync/tasks.ts
index 2776ec8619e..65712a9ed27 100644
--- a/packages/trpc/src/lib/integrations/sync/tasks.ts
+++ b/packages/trpc/src/lib/integrations/sync/tasks.ts
@@ -24,6 +24,24 @@ export async function syncTask(taskId: string) {
 	});
 
 	const qstashBaseUrl = env.NEXT_PUBLIC_API_URL;
+	const providersToSync = connections.filter(
+		(conn) => PROVIDER_ENDPOINTS[conn.provider],
+	);
+
+	if (!qstash) {
+		if (providersToSync.length > 0) {
+			console.warn(
+				`[syncTask] QSTASH_TOKEN is not configured; skipped task sync for providers: ${providersToSync
+					.map((conn) => conn.provider)
+					.join(", ")}`,
+			);
+		}
+		return connections.map((conn) => ({
+			status: "fulfilled" as const,
+			value: { provider: conn.provider, skipped: true },
+		}));
+	}
+	const qstashClient = qstash;
 
 	const results = await Promise.allSettled(
 		connections.map(async (conn) => {
@@ -34,11 +52,7 @@ export async function syncTask(taskId: string) {
 
 			const syncUrl = `${qstashBaseUrl}${endpoint}`;
 
-			if (!qstash) {
-				throw new Error("QSTASH_TOKEN is required to sync integration tasks");
-			}
-
-			await qstash.publishJSON({
+			await qstashClient.publishJSON({
 				url: syncUrl,
 				body: { taskId },
 				retries: 3,
@@ -48,5 +62,10 @@ export async function syncTask(taskId: string) {
 		}),
 	);
 
+	const failures = results.filter((result) => result.status === "rejected");
+	if (failures.length > 0) {
+		console.error("[syncTask] failed to enqueue integration sync", failures);
+	}
+
 	return results;
 }
diff --git a/packages/trpc/src/router/task/task.ts b/packages/trpc/src/router/task/task.ts
index 09b750a9e90..f5308e859dd 100644
--- a/packages/trpc/src/router/task/task.ts
+++ b/packages/trpc/src/router/task/task.ts
@@ -28,6 +28,15 @@ import { taskStatusesRouter } from "./statuses";
 const TASK_SLUG_CONSTRAINT = "tasks_org_slug_unique";
 const TASK_SLUG_RETRY_LIMIT = 5;
 
+function enqueueTaskSync(taskId: string): void {
+	void syncTask(taskId).catch((error) => {
+		console.error(
+			`[task] failed to enqueue integration sync for ${taskId}`,
+			error,
+		);
+	});
+}
+
 function escapeLikePattern(value: string): string {
 	return value.replace(/[\\%_]/g, (match) => `\\${match}`);
 }
@@ -243,7 +252,7 @@ async function createTask(
 			});
 
 			if (result.task) {
-				syncTask(result.task.id);
+				enqueueTaskSync(result.task.id);
 			}
 
 			return result;
@@ -447,7 +456,7 @@ export const taskRouter = {
 			});
 
 			if (result.task) {
-				syncTask(result.task.id);
+				enqueueTaskSync(result.task.id);
 			}
 
 			return result;
@@ -474,7 +483,7 @@ export const taskRouter = {
 			});
 
 			if (result.deleted?.externalProvider && result.deleted?.externalId) {
-				syncTask(input);
+				enqueueTaskSync(input);
 			}
 
 			return { txid: result.txid };
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index b96adf3373a..09f17af7365 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -223,9 +223,9 @@ I shipped the deployment-profile changes without checking `gh pr checks 4616`. T
 
 End-to-end smoke test after final commit:
 
-```
+```text
 [superset] profile=local (lenient)
-[superset] disabled features (set the listed env var to enable):
+[superset] disabled features (set the listed env var(s) to enable):
            - stripe                       STRIPE_SECRET_KEY
            - resend (email)               RESEND_API_KEY
            - posthog (telemetry)          NEXT_PUBLIC_POSTHOG_KEY
@@ -235,7 +235,7 @@ End-to-end smoke test after final commit:
 ```
 
 DB sanity check confirmed the Stripe-gate fix:
-```
+```sql
 SELECT email, name, slug, stripe_customer_id FROM auth.users JOIN auth.organizations ...
 admin@local.test | Local Admin's Team | 14019d9c-team | <NULL>
 ```
diff --git a/scripts/setup-local.ts b/scripts/setup-local.ts
index 079ee7446ba..a9f455f9264 100644
--- a/scripts/setup-local.ts
+++ b/scripts/setup-local.ts
@@ -5,6 +5,12 @@ import { basename, resolve } from "node:path";
 
 const args = new Set(process.argv.slice(2));
 const root = resolve(import.meta.dirname, "..");
+const LOCAL_DATABASE_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]",
+]);
 
 const help = `Usage: bun setup:local [options]
 
@@ -82,7 +88,7 @@ function isLocalDatabaseUrl(value: string | undefined): boolean {
 	if (!value) return false;
 	try {
 		const url = new URL(value);
-		return ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+		return LOCAL_DATABASE_HOSTS.has(url.hostname);
 	} catch {
 		return false;
 	}

From 716e6828e4dd2c864cb71cede6fa6b9c5d7b8900 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 17:05:17 -0700
Subject: [PATCH 12/28] fix: isolate local setup per worktree

---
 .env.example                                  |   6 +-
 README.md                                     |   2 +-
 apps/desktop/src/main/lib/dev-auto-sign-in.ts |  40 ++-
 docker-compose.dev.yml                        |   6 +-
 docs/LOCAL_DEVELOPMENT.md                     |  24 +-
 scripts/setup-local.ts                        | 273 ++++++++++++++++--
 6 files changed, 308 insertions(+), 43 deletions(-)

diff --git a/.env.example b/.env.example
index dd21322bd3c..3d079aaa148 100644
--- a/.env.example
+++ b/.env.example
@@ -14,12 +14,16 @@
 SUPERSET_PROFILE=local
 
 # Keep desktop dev state separate from production / canary installs.
-# This maps to ~/.superset-local-dev instead of ~/.superset.
+# `bun setup:local` rewrites this to local-dev-<worktree>.
 SUPERSET_WORKSPACE_NAME=local-dev
 
 # -----------------------------------------------------------------------------
 # Local Database
 # -----------------------------------------------------------------------------
+# `bun setup:local` rewrites these to a database name derived from the
+# worktree path, so multiple local worktrees can share one Postgres container
+# without sharing schema/auth state.
+SUPERSET_LOCAL_DATABASE_NAME=superset
 DATABASE_URL=postgres://superset:superset@localhost:5433/superset
 DATABASE_URL_UNPOOLED=postgres://superset:superset@localhost:5433/superset
 
diff --git a/README.md b/README.md
index 08de44c652c..478d5dea679 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ bun setup:local
 bun dev
 ```
 
-`bun setup:local` copies local examples, starts Docker Postgres/Electric, trusts Caddy's local CA, and runs migrations. It does not overwrite existing files. The desktop window opens auto-signed-in as `admin@local.test`, with state isolated under `~/.superset-local-dev` so source builds do not reuse production or canary desktop state. See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details and troubleshooting.
+`bun setup:local` copies local examples, assigns this worktree its own local database and desktop state, starts Docker Postgres/Electric, trusts Caddy's local CA, and runs migrations. It does not overwrite internal `.env` files. The desktop window opens auto-signed-in as `admin@local.test`, with state isolated under `~/.superset-local-dev-*` so source builds do not reuse production or canary desktop state. See [Local Development](docs/LOCAL_DEVELOPMENT.md) for details and troubleshooting.
 
 To build a distributable desktop app:
 
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
index 13d217e4f6d..10c33969d04 100644
--- a/apps/desktop/src/main/lib/dev-auto-sign-in.ts
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -26,6 +26,10 @@ interface AuthErrorBody {
 	message?: string;
 }
 
+interface SessionResponse {
+	user?: unknown;
+}
+
 async function postAuth<T>(
 	path: string,
 	body: Record<string, unknown>,
@@ -60,6 +64,24 @@ async function waitForApiReady(): Promise<boolean> {
 	return false;
 }
 
+async function isStoredTokenValid(token: string): Promise<boolean> {
+	try {
+		const res = await fetch(
+			`${mainEnv.NEXT_PUBLIC_API_URL}/api/auth/get-session`,
+			{
+				headers: { Authorization: `Bearer ${token}` },
+				signal: AbortSignal.timeout(DEV_AUTH_TIMEOUT_MS),
+			},
+		);
+		if (!res.ok) return false;
+
+		const data = (await res.json().catch(() => null)) as SessionResponse | null;
+		return !!data?.user;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Dev-only: in the local profile, sign in (or sign up) as the seed
  * admin user and persist the token so the renderer's AuthProvider can
@@ -75,8 +97,22 @@ export async function ensureDevAuthToken(): Promise<void> {
 
 	const stored = await loadToken();
 	if (stored.token && stored.expiresAt) {
-		const isExpired = new Date(stored.expiresAt) < new Date();
-		if (!isExpired) return;
+		const expiresAt = new Date(stored.expiresAt);
+		const isExpired =
+			Number.isNaN(expiresAt.getTime()) || expiresAt < new Date();
+		if (!isExpired) {
+			const ready = await waitForApiReady();
+			if (!ready) {
+				console.warn(
+					`[dev-auto-sign-in] API at ${mainEnv.NEXT_PUBLIC_API_URL} did not respond within ${HEALTH_POLL_TIMEOUT_MS}ms — skipping. Use the sign-in form once the API is up.`,
+				);
+				return;
+			}
+
+			if (await isStoredTokenValid(stored.token)) return;
+
+			console.log("[dev-auto-sign-in] stored token is stale; refreshing");
+		}
 	}
 
 	const ready = await waitForApiReady();
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 813d4fb6e6f..27da81a29bb 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -4,7 +4,7 @@
 # can talk to both immediately. Internal devs use `.superset/setup.sh`
 # instead (Neon branches + per-workspace Electric containers).
 #
-#   docker compose -f docker-compose.dev.yml up -d
+#   bun setup:local
 #
 # See docs/LOCAL_DEVELOPMENT.md for full setup.
 
@@ -36,8 +36,8 @@ services:
         condition: service_healthy
     environment:
       # Docker Desktop exposes host.docker.internal so Electric can reach
-      # Postgres through the host's stable 5433 port.
-      DATABASE_URL: postgres://superset:superset@host.docker.internal:5433/superset
+      # the worktree-specific database through the host's stable 5433 port.
+      DATABASE_URL: postgres://superset:superset@host.docker.internal:5433/${SUPERSET_LOCAL_DATABASE_NAME:-superset}
       ELECTRIC_SECRET: local_electric_dev_secret
     ports:
       - "4649:3000"
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index e589742cb37..e9200edf34d 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -1,6 +1,6 @@
 # Local Development
 
-How to run Superset locally from a fresh clone with no Neon, OAuth, Stripe, Resend, or QStash keys. Local contributor state is isolated under `~/.superset-local-dev`, so this flow does not reuse production or canary desktop state from `~/.superset`.
+How to run Superset locally from a fresh clone with no Neon, OAuth, Stripe, Resend, or QStash keys. Local contributor state is isolated under `~/.superset-local-dev-*`, so this flow does not reuse production or canary desktop state from `~/.superset`.
 
 ## Prerequisites
 
@@ -19,7 +19,7 @@ bun setup:local
 bun dev
 ```
 
-`bun setup:local` is non-destructive. It copies `.env.example`, `apps/electric-proxy/.dev.vars.example`, and `Caddyfile.example` only when the target file is missing; starts Docker Postgres/Electric; runs `caddy trust`; and applies DB migrations.
+`bun setup:local` is non-destructive for existing internal config. It copies `.env.example`, `apps/electric-proxy/.dev.vars.example`, and `Caddyfile.example` only when the target file is missing; writes worktree-specific local database settings into `.env`; starts Docker Postgres/Electric; runs `caddy trust`; and applies DB migrations.
 
 If you already have an internal `.env`, the script leaves it untouched and stops before running migrations. Do not overwrite an internal `.env` unless you intentionally want the local contributor profile.
 
@@ -31,7 +31,7 @@ bun setup:local --skip-migrate
 bun setup:local --skip-caddy-trust
 ```
 
-The generated `.env` sets `SUPERSET_PROFILE=local` and `SUPERSET_WORKSPACE_NAME=local-dev`. Missing integration keys are allowed at boot; features that need them fail cleanly when exercised.
+The generated `.env` sets `SUPERSET_PROFILE=local`. `bun setup:local` derives `SUPERSET_WORKSPACE_NAME`, `SUPERSET_LOCAL_DATABASE_NAME`, `DATABASE_URL`, and `DATABASE_URL_UNPOOLED` from the worktree path. All local worktrees share one Postgres container, but each worktree gets its own database and desktop state directory. Missing integration keys are allowed at boot; features that need them fail cleanly when exercised.
 
 That brings up:
 
@@ -54,7 +54,7 @@ On first launch in the `local` profile (when `SUPERSET_PROFILE=local` is set), t
 - **Email:** `admin@local.test`
 - **Password:** `supersetdev`
 
-If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in `~/.superset-local-dev/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
+If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in that worktree's local desktop state directory, for example `~/.superset-local-dev-flax-soda-a1b2c3/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
 
 ### Deployment profiles
 
@@ -119,7 +119,7 @@ Each is "guard, don't crash" — if you click into a feature that needs a key, y
 
 **`EADDRINUSE: address already in use :::4641`** — a previous `bun dev` is still alive. `pkill -f "turbo run dev"` and retry.
 
-**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check `~/.superset-local-dev/auth-token.enc` exists. Delete it and rerun if needed: `rm ~/.superset-local-dev/auth-token.enc && bun dev`. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "local"` — if it says `internal`, you forgot to set `SUPERSET_PROFILE=local` and auto-sign-in is intentionally skipped.
+**`Host service not available` toast in desktop** — the auto-sign-in didn't run or didn't persist the token. Check the state directory printed by `bun setup:local` contains `auth-token.enc`. Delete that file and rerun if needed. Also confirm the profile via `curl http://localhost:4641/api/health` returns `"profile": "local"` — if it says `internal`, you forgot to set `SUPERSET_PROFILE=local` and auto-sign-in is intentionally skipped.
 
 **`Missing API key` for some integration** — that integration's key isn't in `.env`. Either supply it or avoid the feature.
 
@@ -133,18 +133,20 @@ Each is "guard, don't crash" — if you click into a feature that needs a key, y
 # Stop dev
 pkill -f "turbo run dev"
 
-# Wipe data (auth token, host DBs, local app state)
-rm -rf ~/.superset-local-dev
+# Wipe this worktree's local desktop state
+STATE_NAME=$(grep '^SUPERSET_WORKSPACE_NAME=' .env | cut -d= -f2)
+rm -rf "$HOME/.superset-$STATE_NAME"
 
-# Wipe Postgres + Electric (including volume)
-docker compose -f docker-compose.dev.yml down -v
-docker compose -f docker-compose.dev.yml up -d
+# Wipe only this worktree's Postgres database, then recreate it
+DB_NAME=$(grep '^SUPERSET_LOCAL_DATABASE_NAME=' .env | cut -d= -f2)
+docker exec superset-pg dropdb -U superset --if-exists "$DB_NAME"
+bun setup:local
 ```
 
 ## Architecture notes for contributors
 
 - **Deployment profiles** — `packages/shared/src/deployment-profile.ts` resolves `cloud | local | ci | internal` from env flags. Strict profiles fail boot on missing keys; lenient profiles (`local`, `ci`) let the app boot. Use `shouldSkipEnvValidation()` from this module when wiring env schemas, and `isLocalProfile()` when gating local-only behavior.
-- **Desktop state isolation** — `.env.example` sets `SUPERSET_WORKSPACE_NAME=local-dev`, so contributor runs use `~/.superset-local-dev` and do not reuse production / canary state from `~/.superset`. Local profile desktop predev also skips macOS Launch Services cleanup and protocol patching.
+- **Per-worktree local state** — `bun setup:local` rewrites `.env` to use a worktree-specific `SUPERSET_WORKSPACE_NAME`, `SUPERSET_LOCAL_DATABASE_NAME`, and local Postgres URLs. Local worktrees share one Docker Postgres container on port 5433, but not a database, auth sessions, JWKS rows, or desktop state. Local profile desktop predev also skips macOS Launch Services cleanup and protocol patching.
 - **DB driver swap** — `packages/db/src/client.ts` detects whether `DATABASE_URL` is a Neon host (`*.neon.tech`, `*.neon.build`) and uses Drizzle's `neon-http` adapter for cloud, or `node-postgres` for any other Postgres (including the local Docker one).
 - **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()` only in the `local` profile. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
 - **Renderer organization selection** — pages prefer `session.activeOrganizationId` from Better Auth, falling back to `MOCK_ORG_ID` only if there's no session at all. Make sure new code that needs `activeOrganizationId` follows this same priority (real session first).
diff --git a/scripts/setup-local.ts b/scripts/setup-local.ts
index a9f455f9264..e4678242440 100644
--- a/scripts/setup-local.ts
+++ b/scripts/setup-local.ts
@@ -1,16 +1,44 @@
 #!/usr/bin/env bun
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 
 const args = new Set(process.argv.slice(2));
 const root = resolve(import.meta.dirname, "..");
+const localWorktreeSlug = toSlug(basename(root), "-");
+const localWorktreeHash = createHash("sha1")
+	.update(root)
+	.digest("hex")
+	.slice(0, 6);
+const localWorkspaceName = [
+	"local-dev",
+	localWorktreeSlug.slice(0, 15),
+	localWorktreeHash,
+].join("-");
+const localDatabaseName = [
+	"superset_local",
+	toSlug(basename(root), "_").slice(0, 32),
+	localWorktreeHash,
+].join("_");
 const LOCAL_DATABASE_HOSTS = new Set([
 	"localhost",
 	"127.0.0.1",
 	"::1",
 	"[::1]",
 ]);
+const LOCAL_DATABASE_USER = "superset";
+const LOCAL_DATABASE_PASSWORD = "superset";
+const LOCAL_DATABASE_PORT = "5433";
+const LOCAL_POSTGRES_CONTAINER = "superset-pg";
+const LOCAL_ELECTRIC_CONTAINER = "superset-electric";
+const DOCKER_COMPOSE_ARGS = [
+	"compose",
+	"-p",
+	"superset-local",
+	"-f",
+	"docker-compose.dev.yml",
+];
 
 const help = `Usage: bun setup:local [options]
 
@@ -32,18 +60,36 @@ function fail(message: string): never {
 	process.exit(1);
 }
 
-function run(command: string, commandArgs: string[]): void {
+function run(
+	command: string,
+	commandArgs: string[],
+	env: Record<string, string | undefined> = {},
+): void {
 	log(`$ ${[command, ...commandArgs].join(" ")}`);
 	const result = spawnSync(command, commandArgs, {
 		cwd: root,
 		stdio: "inherit",
-		env: process.env,
+		env: { ...process.env, ...env },
 	});
 	if (result.status !== 0) {
 		fail(`${command} ${commandArgs.join(" ")} failed`);
 	}
 }
 
+function runOutput(command: string, commandArgs: string[]): string {
+	const result = spawnSync(command, commandArgs, {
+		cwd: root,
+		encoding: "utf8",
+		env: process.env,
+	});
+	if (result.status !== 0) {
+		fail(
+			`${command} ${commandArgs.join(" ")} failed\n${result.stderr ?? ""}`.trim(),
+		);
+	}
+	return result.stdout;
+}
+
 function commandExists(command: string): boolean {
 	const result = spawnSync("sh", ["-lc", `command -v ${command}`], {
 		cwd: root,
@@ -69,6 +115,20 @@ function copyIfMissing(source: string, destination: string): void {
 	log(`created ${destination} from ${basename(source)}`);
 }
 
+function toSlug(value: string, separator: "-" | "_"): string {
+	return (
+		value
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, separator)
+			.replace(new RegExp(`^\\${separator}+|\\${separator}+$`, "g"), "") ||
+		"dev"
+	);
+}
+
+function localDatabaseUrl(databaseName: string): string {
+	return `postgres://${LOCAL_DATABASE_USER}:${LOCAL_DATABASE_PASSWORD}@localhost:${LOCAL_DATABASE_PORT}/${databaseName}`;
+}
+
 function readEnvValue(name: string): string | undefined {
 	const envPath = resolve(root, ".env");
 	if (!existsSync(envPath)) return undefined;
@@ -84,6 +144,35 @@ function readEnvValue(name: string): string | undefined {
 	return undefined;
 }
 
+function writeEnvValues(values: Record<string, string>): void {
+	const envPath = resolve(root, ".env");
+	const original = readFileSync(envPath, "utf8");
+	const seen = new Set<string>();
+	const lines = original.split(/\r?\n/).map((line) => {
+		const match = line.match(/^([A-Z0-9_]+)=/);
+		if (!match) return line;
+
+		const key = match[1];
+		const value = values[key];
+		if (value === undefined) return line;
+
+		seen.add(key);
+		return `${key}=${value}`;
+	});
+
+	for (const [key, value] of Object.entries(values)) {
+		if (!seen.has(key)) {
+			lines.push(`${key}=${value}`);
+		}
+	}
+
+	const next = lines.join("\n");
+	if (next !== original) {
+		writeFileSync(envPath, next);
+		log("updated .env with this worktree's local database settings");
+	}
+}
+
 function isLocalDatabaseUrl(value: string | undefined): boolean {
 	if (!value) return false;
 	try {
@@ -94,6 +183,154 @@ function isLocalDatabaseUrl(value: string | undefined): boolean {
 	}
 }
 
+function isLocalWorkspaceName(value: string | undefined): boolean {
+	return value === "local-dev" || Boolean(value?.startsWith("local-dev-"));
+}
+
+function normalizeLocalEnv(): void {
+	const profile = readEnvValue("SUPERSET_PROFILE");
+	const workspaceName = readEnvValue("SUPERSET_WORKSPACE_NAME");
+	if (profile !== "local" || !isLocalWorkspaceName(workspaceName)) {
+		fail(
+			[
+				"existing .env is not the default contributor profile, so setup stopped before running migrations",
+				"expected: SUPERSET_PROFILE=local",
+				"expected: SUPERSET_WORKSPACE_NAME=local-dev or local-dev-*",
+				"move your existing .env aside or update it intentionally, then rerun bun setup:local",
+			].join("\n"),
+		);
+	}
+
+	if (!isLocalDatabaseUrl(readEnvValue("DATABASE_URL"))) {
+		fail("DATABASE_URL must point at localhost for bun setup:local.");
+	}
+
+	if (!isLocalDatabaseUrl(readEnvValue("DATABASE_URL_UNPOOLED"))) {
+		fail("DATABASE_URL_UNPOOLED must point at localhost for bun setup:local.");
+	}
+
+	writeEnvValues({
+		SUPERSET_WORKSPACE_NAME: localWorkspaceName,
+		SUPERSET_LOCAL_DATABASE_NAME: localDatabaseName,
+		DATABASE_URL: localDatabaseUrl(localDatabaseName),
+		DATABASE_URL_UNPOOLED: localDatabaseUrl(localDatabaseName),
+	});
+}
+
+function dockerContainerExists(name: string): boolean {
+	const result = spawnSync("docker", ["inspect", name], {
+		cwd: root,
+		stdio: "ignore",
+	});
+	return result.status === 0;
+}
+
+function dockerContainerEnvValue(
+	containerName: string,
+	envName: string,
+): string | undefined {
+	if (!dockerContainerExists(containerName)) return undefined;
+	const output = runOutput("docker", [
+		"inspect",
+		"--format",
+		"{{range .Config.Env}}{{println .}}{{end}}",
+		containerName,
+	]);
+	const line = output
+		.split(/\r?\n/)
+		.find((item) => item.startsWith(`${envName}=`));
+	return line?.slice(envName.length + 1);
+}
+
+function sleep(seconds: number): void {
+	spawnSync("sleep", [String(seconds)], { stdio: "ignore" });
+}
+
+function waitForPostgres(): void {
+	for (let attempt = 0; attempt < 30; attempt++) {
+		const result = spawnSync(
+			"docker",
+			[
+				"exec",
+				LOCAL_POSTGRES_CONTAINER,
+				"pg_isready",
+				"-U",
+				LOCAL_DATABASE_USER,
+				"-d",
+				"postgres",
+			],
+			{ cwd: root, stdio: "ignore" },
+		);
+		if (result.status === 0) return;
+		sleep(1);
+	}
+
+	fail("Postgres did not become ready.");
+}
+
+function ensureLocalPostgres(): void {
+	if (dockerContainerExists(LOCAL_POSTGRES_CONTAINER)) {
+		run("docker", ["start", LOCAL_POSTGRES_CONTAINER]);
+	} else {
+		run("docker", [...DOCKER_COMPOSE_ARGS, "up", "-d", "postgres"]);
+	}
+
+	waitForPostgres();
+}
+
+function ensureLocalDatabase(databaseName: string): void {
+	const exists = runOutput("docker", [
+		"exec",
+		LOCAL_POSTGRES_CONTAINER,
+		"psql",
+		"-U",
+		LOCAL_DATABASE_USER,
+		"-d",
+		"postgres",
+		"-tAc",
+		`SELECT 1 FROM pg_database WHERE datname='${databaseName}'`,
+	]).trim();
+
+	if (exists === "1") {
+		log(`database ${databaseName} already exists`);
+		return;
+	}
+
+	run("docker", [
+		"exec",
+		LOCAL_POSTGRES_CONTAINER,
+		"psql",
+		"-U",
+		LOCAL_DATABASE_USER,
+		"-d",
+		"postgres",
+		"-c",
+		`CREATE DATABASE ${databaseName}`,
+	]);
+}
+
+function ensureLocalElectric(databaseName: string): void {
+	const expectedDatabaseUrl = `postgres://${LOCAL_DATABASE_USER}:${LOCAL_DATABASE_PASSWORD}@host.docker.internal:${LOCAL_DATABASE_PORT}/${databaseName}`;
+	const currentDatabaseUrl = dockerContainerEnvValue(
+		LOCAL_ELECTRIC_CONTAINER,
+		"DATABASE_URL",
+	);
+
+	if (currentDatabaseUrl && currentDatabaseUrl !== expectedDatabaseUrl) {
+		log("recreating Electric for this worktree's local database");
+		run("docker", ["rm", "-f", LOCAL_ELECTRIC_CONTAINER]);
+	}
+
+	if (dockerContainerExists(LOCAL_ELECTRIC_CONTAINER)) {
+		run("docker", ["start", LOCAL_ELECTRIC_CONTAINER]);
+		return;
+	}
+
+	run("docker", [...DOCKER_COMPOSE_ARGS, "up", "-d", "--no-deps", "electric"], {
+		SUPERSET_LOCAL_DATABASE_NAME: databaseName,
+	});
+}
+
 if (args.has("-h") || args.has("--help")) {
 	console.log(help);
 	process.exit(0);
@@ -112,26 +349,7 @@ if (!args.has("--skip-caddy-trust")) {
 }
 
 copyIfMissing(".env.example", ".env");
-const profile = readEnvValue("SUPERSET_PROFILE");
-const workspaceName = readEnvValue("SUPERSET_WORKSPACE_NAME");
-if (profile !== "local" || workspaceName !== "local-dev") {
-	fail(
-		[
-			"existing .env is not the default contributor profile, so setup stopped before running migrations",
-			"expected: SUPERSET_PROFILE=local",
-			"expected: SUPERSET_WORKSPACE_NAME=local-dev",
-			"move your existing .env aside or update it intentionally, then rerun bun setup:local",
-		].join("\n"),
-	);
-}
-
-if (!isLocalDatabaseUrl(readEnvValue("DATABASE_URL"))) {
-	fail("DATABASE_URL must point at localhost for bun setup:local.");
-}
-
-if (!isLocalDatabaseUrl(readEnvValue("DATABASE_URL_UNPOOLED"))) {
-	fail("DATABASE_URL_UNPOOLED must point at localhost for bun setup:local.");
-}
+normalizeLocalEnv();
 
 copyIfMissing(
 	"apps/electric-proxy/.dev.vars.example",
@@ -140,7 +358,9 @@ copyIfMissing(
 copyIfMissing("Caddyfile.example", "Caddyfile");
 
 if (!args.has("--skip-docker")) {
-	run("docker", ["compose", "-f", "docker-compose.dev.yml", "up", "-d"]);
+	ensureLocalPostgres();
+	ensureLocalDatabase(localDatabaseName);
+	ensureLocalElectric(localDatabaseName);
 }
 
 if (!args.has("--skip-caddy-trust")) {
@@ -162,5 +382,8 @@ Useful checks after boot:
   curl -fsS http://localhost:4641/api/auth/ok
 
 Desktop state for this setup lives in:
-  ~/.superset-local-dev
+  ~/.superset-${localWorkspaceName}
+
+Local database for this worktree:
+  ${localDatabaseName}
 `);

From 47ebfeb7593f0b82c625a83ff8946a636524a67c Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 17:54:54 -0700
Subject: [PATCH 13/28] fix: add local desktop sign-in form

---
 apps/desktop/electron.vite.config.ts          |   4 +
 apps/desktop/src/renderer/env.renderer.ts     |   2 +
 .../LocalDevAuthForm/LocalDevAuthForm.tsx     | 150 ++++++++++++++++++
 .../components/LocalDevAuthForm/index.ts      |   1 +
 .../src/renderer/routes/sign-in/page.tsx      |   8 +-
 docs/LOCAL_DEVELOPMENT.md                     |   4 +-
 6 files changed, 167 insertions(+), 2 deletions(-)
 create mode 100644 apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
 create mode 100644 apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts

diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.ts
index 06ee0269f08..add0f28f908 100644
--- a/apps/desktop/electron.vite.config.ts
+++ b/apps/desktop/electron.vite.config.ts
@@ -188,6 +188,10 @@ export default defineConfig({
 				process.env.SKIP_ENV_VALIDATION,
 				"",
 			),
+			"process.env.SUPERSET_PROFILE": defineEnv(
+				process.env.SUPERSET_PROFILE,
+				"",
+			),
 			"process.platform": defineEnv(process.platform),
 			"process.env.NEXT_PUBLIC_API_URL": JSON.stringify(
 				devOrProdUrl(
diff --git a/apps/desktop/src/renderer/env.renderer.ts b/apps/desktop/src/renderer/env.renderer.ts
index aa9346e277a..495be6feee9 100644
--- a/apps/desktop/src/renderer/env.renderer.ts
+++ b/apps/desktop/src/renderer/env.renderer.ts
@@ -44,6 +44,7 @@ const envSchema = z.object({
 	NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
 	NEXT_PUBLIC_POSTHOG_HOST: z.string().default("https://us.i.posthog.com"),
 	SENTRY_DSN_DESKTOP: z.string().optional(),
+	SUPERSET_PROFILE: z.enum(["cloud", "local", "ci", "internal"]).optional(),
 	RELAY_URL: z
 		.url()
 		.default(
@@ -73,6 +74,7 @@ const rawEnv = {
 		| string
 		| undefined,
 	SENTRY_DSN_DESKTOP: import.meta.env.SENTRY_DSN_DESKTOP as string | undefined,
+	SUPERSET_PROFILE: process.env.SUPERSET_PROFILE,
 	RELAY_URL: process.env.RELAY_URL,
 };
 
diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
new file mode 100644
index 00000000000..2b930c7ba48
--- /dev/null
+++ b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
@@ -0,0 +1,150 @@
+import { Button } from "@superset/ui/button";
+import { Input } from "@superset/ui/input";
+import { Label } from "@superset/ui/label";
+import { useNavigate } from "@tanstack/react-router";
+import { type FormEvent, useState } from "react";
+import { env } from "renderer/env.renderer";
+import { authClient, setAuthToken } from "renderer/lib/auth-client";
+import { electronTrpc } from "renderer/lib/electron-trpc";
+
+const DEV_EMAIL = "admin@local.test";
+const DEV_PASSWORD = "supersetdev";
+const DEV_NAME = "Local Admin";
+const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
+
+interface AuthResponse {
+	token?: string;
+}
+
+interface AuthErrorBody {
+	code?: string;
+	message?: string;
+}
+
+async function postAuth(
+	path: string,
+	body: Record<string, unknown>,
+): Promise<{
+	ok: boolean;
+	status: number;
+	data: AuthResponse | AuthErrorBody;
+}> {
+	const res = await fetch(`${env.NEXT_PUBLIC_API_URL}${path}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		credentials: "include",
+		body: JSON.stringify(body),
+	});
+	const data = (await res.json().catch(() => ({}))) as
+		| AuthResponse
+		| AuthErrorBody;
+	return { ok: res.ok, status: res.status, data };
+}
+
+export function LocalDevAuthForm() {
+	const navigate = useNavigate();
+	const persistToken = electronTrpc.auth.persistToken.useMutation();
+	const { refetch } = authClient.useSession();
+	const [email, setEmail] = useState(DEV_EMAIL);
+	const [password, setPassword] = useState(DEV_PASSWORD);
+	const [error, setError] = useState<string | null>(null);
+	const [submitting, setSubmitting] = useState(false);
+
+	const onSubmit = async (event: FormEvent) => {
+		event.preventDefault();
+		setError(null);
+		setSubmitting(true);
+
+		try {
+			let signIn = await postAuth("/api/auth/sign-in/email", {
+				email,
+				password,
+			});
+
+			const errBody = signIn.data as AuthErrorBody;
+			if (
+				!signIn.ok &&
+				errBody.code === "INVALID_EMAIL_OR_PASSWORD" &&
+				email === DEV_EMAIL &&
+				password === DEV_PASSWORD
+			) {
+				const signUp = await postAuth("/api/auth/sign-up/email", {
+					email,
+					password,
+					name: DEV_NAME,
+				});
+				if (!signUp.ok) {
+					const signUpError = signUp.data as AuthErrorBody;
+					throw new Error(
+						signUpError.message ?? `Sign-up failed (${signUp.status})`,
+					);
+				}
+
+				signIn = await postAuth("/api/auth/sign-in/email", {
+					email,
+					password,
+				});
+			}
+
+			if (!signIn.ok) {
+				const signInError = signIn.data as AuthErrorBody;
+				throw new Error(
+					signInError.message ?? `Sign-in failed (${signIn.status})`,
+				);
+			}
+
+			const token = (signIn.data as AuthResponse).token;
+			if (!token) throw new Error("Sign-in did not return a token");
+
+			const expiresAt = new Date(Date.now() + TOKEN_TTL_MS).toISOString();
+			await persistToken.mutateAsync({ token, expiresAt });
+			setAuthToken(token);
+			await refetch();
+			await navigate({ to: "/workspace", replace: true });
+		} catch (err) {
+			setError(err instanceof Error ? err.message : "Sign-in failed");
+			setSubmitting(false);
+		}
+	};
+
+	return (
+		<form className="grid gap-3" onSubmit={onSubmit}>
+			<div className="grid gap-1.5">
+				<Label htmlFor="local-dev-email" className="text-xs">
+					Email
+				</Label>
+				<Input
+					id="local-dev-email"
+					type="email"
+					autoComplete="email"
+					value={email}
+					onChange={(event) => setEmail(event.target.value)}
+					required
+				/>
+			</div>
+			<div className="grid gap-1.5">
+				<Label htmlFor="local-dev-password" className="text-xs">
+					Password
+				</Label>
+				<Input
+					id="local-dev-password"
+					type="password"
+					autoComplete="current-password"
+					value={password}
+					onChange={(event) => setPassword(event.target.value)}
+					required
+					minLength={8}
+				/>
+			</div>
+			{error && <p className="text-destructive text-xs">{error}</p>}
+			<Button
+				type="submit"
+				size="lg"
+				className="w-full"
+				disabled={submitting || persistToken.isPending}
+			>
+				{submitting || persistToken.isPending ? "Signing in..." : "Sign in"}
+			</Button>
+		</form>
+	);
+}
diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts
new file mode 100644
index 00000000000..9514c0436a0
--- /dev/null
+++ b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts
@@ -0,0 +1 @@
+export { LocalDevAuthForm } from "./LocalDevAuthForm";
diff --git a/apps/desktop/src/renderer/routes/sign-in/page.tsx b/apps/desktop/src/renderer/routes/sign-in/page.tsx
index aa08c51ad5d..d7d7f5eb4e2 100644
--- a/apps/desktop/src/renderer/routes/sign-in/page.tsx
+++ b/apps/desktop/src/renderer/routes/sign-in/page.tsx
@@ -7,6 +7,7 @@ import { FcGoogle } from "react-icons/fc";
 import { env } from "renderer/env.renderer";
 import { track } from "renderer/lib/analytics";
 import { electronTrpc } from "renderer/lib/electron-trpc";
+import { LocalDevAuthForm } from "./components/LocalDevAuthForm";
 import { SupersetLogo } from "./components/SupersetLogo";
 import { useSessionRecovery } from "./hooks/useSessionRecovery";
 
@@ -17,6 +18,7 @@ export const Route = createFileRoute("/sign-in/")({
 function SignInPage() {
 	const signInMutation = electronTrpc.auth.signIn.useMutation();
 	const { hasLocalToken, isPending, session } = useSessionRecovery();
+	const isLocalProfile = env.SUPERSET_PROFILE === "local";
 
 	// Dev bypass: AuthProvider handles auto-sign-in; if session lands, redirect
 	if (env.SKIP_ENV_VALIDATION && session?.user) {
@@ -63,7 +65,11 @@ function SignInPage() {
 						</p>
 					</div>
 
-					<div className="flex flex-col gap-3 w-full max-w-xs">
+					<div className="flex w-full max-w-xs flex-col gap-3">
+						{isLocalProfile && <LocalDevAuthForm />}
+
+						{isLocalProfile && <div className="h-px bg-border" />}
+
 						<Button
 							variant="outline"
 							size="lg"
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index e9200edf34d..c3c15cd9f66 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -54,7 +54,9 @@ On first launch in the `local` profile (when `SUPERSET_PROFILE=local` is set), t
 - **Email:** `admin@local.test`
 - **Password:** `supersetdev`
 
-If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in that worktree's local desktop state directory, for example `~/.superset-local-dev-flax-soda-a1b2c3/auth-token.enc`. The renderer hydrates this token like a real OAuth user — there's no special dev-only code path in the renderer.
+If the user doesn't exist, it's created and a personal organization is provisioned automatically (`Local Admin's Team`). The encrypted auth token lands in that worktree's local desktop state directory, for example `~/.superset-local-dev-flax-soda-a1b2c3/auth-token.enc`. The renderer hydrates this token like a real OAuth user.
+
+If auto-sign-in does not complete, the desktop sign-in screen shows the same email/password fields in the `local` profile.
 
 ### Deployment profiles
 

From 18c7cef97308e035d05cd9f5434713fd6792af9c Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Sun, 17 May 2026 18:03:47 -0700
Subject: [PATCH 14/28] fix: keep local desktop sign-in bearer-only

---
 .../components/LocalDevAuthForm/LocalDevAuthForm.tsx        | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
index 2b930c7ba48..e0f1f6bc881 100644
--- a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
+++ b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
@@ -4,7 +4,7 @@ import { Label } from "@superset/ui/label";
 import { useNavigate } from "@tanstack/react-router";
 import { type FormEvent, useState } from "react";
 import { env } from "renderer/env.renderer";
-import { authClient, setAuthToken } from "renderer/lib/auth-client";
+import { setAuthToken } from "renderer/lib/auth-client";
 import { electronTrpc } from "renderer/lib/electron-trpc";
 
 const DEV_EMAIL = "admin@local.test";
@@ -32,7 +32,7 @@ async function postAuth(
 	const res = await fetch(`${env.NEXT_PUBLIC_API_URL}${path}`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
-		credentials: "include",
+		credentials: "omit",
 		body: JSON.stringify(body),
 	});
 	const data = (await res.json().catch(() => ({}))) as
@@ -44,7 +44,6 @@ async function postAuth(
 export function LocalDevAuthForm() {
 	const navigate = useNavigate();
 	const persistToken = electronTrpc.auth.persistToken.useMutation();
-	const { refetch } = authClient.useSession();
 	const [email, setEmail] = useState(DEV_EMAIL);
 	const [password, setPassword] = useState(DEV_PASSWORD);
 	const [error, setError] = useState<string | null>(null);
@@ -99,7 +98,6 @@ export function LocalDevAuthForm() {
 			const expiresAt = new Date(Date.now() + TOKEN_TTL_MS).toISOString();
 			await persistToken.mutateAsync({ token, expiresAt });
 			setAuthToken(token);
-			await refetch();
 			await navigate({ to: "/workspace", replace: true });
 		} catch (err) {
 			setError(err instanceof Error ? err.message : "Sign-in failed");

From b7164431657f5ca143b5421b3ee36ef9526c1fad Mon Sep 17 00:00:00 2001
From: Justin Rich <justin@hackerpug.com>
Date: Wed, 20 May 2026 13:25:18 -0700
Subject: [PATCH 15/28] feat(web): one-click dev sign-in button for local
 development (#4778)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(web): one-click dev sign-in button for local development

Replaces `DevAuthForm` (form with prefilled email + password) on the
web sign-in page with a single "Sign in as Local Admin (dev)" button.
Dev creds never change in local profile, so the inputs were noise.

The button calls authClient.signIn.email and, on first run, falls
back to authClient.signUp.email then retries — mirroring
apps/desktop LocalDevAuthForm behavior. Gated by
NODE_ENV !== "production" so it tree-shakes out of prod builds.
Removed from the sign-up page (redundant with the sign-in
auto-create).

Also fills three required client-side env vars in .env.example so
apps/web's t3-env validation passes on a fresh clone. Without these,
validation throws during module init and silently kills React
hydration — every sign-in button (OAuth + dev) becomes a
no-network no-op.

  NEXT_PUBLIC_POSTHOG_KEY=phc_local_dev_disabled
  NEXT_PUBLIC_POSTHOG_HOST=https://us.posthog.com
  NEXT_PUBLIC_RELAY_URL=http://localhost:4734

shouldSkipEnvValidation() skips server-side validation in the local
profile, but Next.js statically inlines NEXT_PUBLIC_* into the
client bundle and t3-env still revalidates there.

.gitignore also picks up `.claude/worktrees/` and `.spec/` so
per-developer artifacts stop leaking into PRs.

* refactor: extract shared DevSignInButton UI + dev credentials

Replaces apps/desktop's LocalDevAuthForm (email/password form) with a
one-click button matching the web. Both apps now wrap a single shared
UI component and supply only platform-specific glue:

  packages/ui/.../dev-sign-in-button.tsx   pure UI button + state
  packages/shared/dev-credentials.ts       DEV_EMAIL/PASSWORD/NAME

  apps/web/.../DevSignInButton.tsx         Next.js useRouter +
                                           authClient.signIn.email
  apps/desktop/.../LocalDevSignInButton/   TanStack useNavigate +
                                           raw fetch + electron-trpc
                                           token persistence

Eliminates dev-cred duplication across four files (db seed, desktop
main auto-sign-in, desktop renderer wrapper, web wrapper). The
desktop sign-in still uses raw fetch + saveToken because Electron
manages tokens itself; the web wrapper uses cookies via
@superset/auth/client. Routing diverges naturally between the two
routers, which is why the shared piece is just the button itself.

Dev-only on both platforms — desktop gates on SUPERSET_PROFILE=local,
web gates on NODE_ENV !== "production".

* fix(web): restore DevSignInButton on sign-up page

The button auto-creates the seeded account on first run via its
sign-up fallback, so the sign-up route gives the same one-click
local-dev path as sign-in. Gated by NODE_ENV !== "production".
---
 .env.example                                  |   7 +-
 .gitignore                                    |   6 +
 apps/desktop/src/main/lib/dev-auto-sign-in.ts |   8 +-
 .../LocalDevAuthForm/LocalDevAuthForm.tsx     | 148 ------------------
 .../components/LocalDevAuthForm/index.ts      |   1 -
 .../LocalDevSignInButton.tsx                  |  89 +++++++++++
 .../components/LocalDevSignInButton/index.ts  |   1 +
 .../src/renderer/routes/sign-in/page.tsx      |   4 +-
 .../components/DevAuthForm/DevAuthForm.tsx    | 103 ------------
 .../(auth)/components/DevAuthForm/index.ts    |   1 -
 .../DevSignInButton/DevSignInButton.tsx       |  41 +++++
 .../components/DevSignInButton/index.ts       |   1 +
 .../(auth)/sign-in/[[...sign-in]]/page.tsx    |   4 +-
 .../(auth)/sign-up/[[...sign-up]]/page.tsx    |   6 +-
 packages/db/src/seed-dev.ts                   |   9 +-
 packages/shared/package.json                  |   4 +
 packages/shared/src/dev-credentials.ts        |  11 ++
 .../src/components/ui/dev-sign-in-button.tsx  |  49 ++++++
 18 files changed, 222 insertions(+), 271 deletions(-)
 delete mode 100644 apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
 delete mode 100644 apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts
 create mode 100644 apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/LocalDevSignInButton.tsx
 create mode 100644 apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/index.ts
 delete mode 100644 apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx
 delete mode 100644 apps/web/src/app/(auth)/components/DevAuthForm/index.ts
 create mode 100644 apps/web/src/app/(auth)/components/DevSignInButton/DevSignInButton.tsx
 create mode 100644 apps/web/src/app/(auth)/components/DevSignInButton/index.ts
 create mode 100644 packages/shared/src/dev-credentials.ts
 create mode 100644 packages/ui/src/components/ui/dev-sign-in-button.tsx

diff --git a/.env.example b/.env.example
index 2d7f1a9c197..950ffbb19e1 100644
--- a/.env.example
+++ b/.env.example
@@ -91,7 +91,8 @@ BLOB_READ_WRITE_TOKEN=
 # -----------------------------------------------------------------------------
 # PostHog Analytics (Local Dev)
 # -----------------------------------------------------------------------------
-NEXT_PUBLIC_POSTHOG_KEY=
+NEXT_PUBLIC_POSTHOG_KEY=phc_local_dev_disabled
+NEXT_PUBLIC_POSTHOG_HOST=https://us.posthog.com
 POSTHOG_API_KEY=
 POSTHOG_PROJECT_ID=
 
@@ -146,5 +147,5 @@ SUPERSET_MCP_API_KEY=
 # Relay service URL (the v2 tunnel proxy that forwards cloud API calls
 # to host-service instances on user devices). Local dev: http://localhost:4734
 RELAY_URL=
-# Browser-exposed relay URL — the web app's host-service tRPC + terminal WS.
-NEXT_PUBLIC_RELAY_URL=
+# Browser-exposed relay URL for the web app's host-service tRPC + terminal WS.
+NEXT_PUBLIC_RELAY_URL=http://localhost:4734
diff --git a/.gitignore b/.gitignore
index bce6f530372..2d725174d2d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -94,3 +94,9 @@ superset-dev-data/
 
 # Local-only plans (not tracked)
 plans/local/
+
+# Per-developer Claude Code state (worktree gitlinks)
+.claude/worktrees/
+
+# Local-only spec drafts / reviews
+.spec/
diff --git a/apps/desktop/src/main/lib/dev-auto-sign-in.ts b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
index 10c33969d04..7906f21faae 100644
--- a/apps/desktop/src/main/lib/dev-auto-sign-in.ts
+++ b/apps/desktop/src/main/lib/dev-auto-sign-in.ts
@@ -1,13 +1,15 @@
 import { isLocalProfile } from "@superset/shared/deployment-profile";
+import {
+	DEV_EMAIL,
+	DEV_NAME,
+	DEV_PASSWORD,
+} from "@superset/shared/dev-credentials";
 import { env as mainEnv } from "main/env.main";
 import {
 	loadToken,
 	saveToken,
 } from "../../lib/trpc/routers/auth/utils/auth-functions";
 
-const DEV_EMAIL = "admin@local.test";
-const DEV_PASSWORD = "supersetdev";
-const DEV_NAME = "Local Admin";
 const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
 const DEV_AUTH_TIMEOUT_MS = 8000;
 
diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
deleted file mode 100644
index e0f1f6bc881..00000000000
--- a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/LocalDevAuthForm.tsx
+++ /dev/null
@@ -1,148 +0,0 @@
-import { Button } from "@superset/ui/button";
-import { Input } from "@superset/ui/input";
-import { Label } from "@superset/ui/label";
-import { useNavigate } from "@tanstack/react-router";
-import { type FormEvent, useState } from "react";
-import { env } from "renderer/env.renderer";
-import { setAuthToken } from "renderer/lib/auth-client";
-import { electronTrpc } from "renderer/lib/electron-trpc";
-
-const DEV_EMAIL = "admin@local.test";
-const DEV_PASSWORD = "supersetdev";
-const DEV_NAME = "Local Admin";
-const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
-
-interface AuthResponse {
-	token?: string;
-}
-
-interface AuthErrorBody {
-	code?: string;
-	message?: string;
-}
-
-async function postAuth(
-	path: string,
-	body: Record<string, unknown>,
-): Promise<{
-	ok: boolean;
-	status: number;
-	data: AuthResponse | AuthErrorBody;
-}> {
-	const res = await fetch(`${env.NEXT_PUBLIC_API_URL}${path}`, {
-		method: "POST",
-		headers: { "Content-Type": "application/json" },
-		credentials: "omit",
-		body: JSON.stringify(body),
-	});
-	const data = (await res.json().catch(() => ({}))) as
-		| AuthResponse
-		| AuthErrorBody;
-	return { ok: res.ok, status: res.status, data };
-}
-
-export function LocalDevAuthForm() {
-	const navigate = useNavigate();
-	const persistToken = electronTrpc.auth.persistToken.useMutation();
-	const [email, setEmail] = useState(DEV_EMAIL);
-	const [password, setPassword] = useState(DEV_PASSWORD);
-	const [error, setError] = useState<string | null>(null);
-	const [submitting, setSubmitting] = useState(false);
-
-	const onSubmit = async (event: FormEvent) => {
-		event.preventDefault();
-		setError(null);
-		setSubmitting(true);
-
-		try {
-			let signIn = await postAuth("/api/auth/sign-in/email", {
-				email,
-				password,
-			});
-
-			const errBody = signIn.data as AuthErrorBody;
-			if (
-				!signIn.ok &&
-				errBody.code === "INVALID_EMAIL_OR_PASSWORD" &&
-				email === DEV_EMAIL &&
-				password === DEV_PASSWORD
-			) {
-				const signUp = await postAuth("/api/auth/sign-up/email", {
-					email,
-					password,
-					name: DEV_NAME,
-				});
-				if (!signUp.ok) {
-					const signUpError = signUp.data as AuthErrorBody;
-					throw new Error(
-						signUpError.message ?? `Sign-up failed (${signUp.status})`,
-					);
-				}
-
-				signIn = await postAuth("/api/auth/sign-in/email", {
-					email,
-					password,
-				});
-			}
-
-			if (!signIn.ok) {
-				const signInError = signIn.data as AuthErrorBody;
-				throw new Error(
-					signInError.message ?? `Sign-in failed (${signIn.status})`,
-				);
-			}
-
-			const token = (signIn.data as AuthResponse).token;
-			if (!token) throw new Error("Sign-in did not return a token");
-
-			const expiresAt = new Date(Date.now() + TOKEN_TTL_MS).toISOString();
-			await persistToken.mutateAsync({ token, expiresAt });
-			setAuthToken(token);
-			await navigate({ to: "/workspace", replace: true });
-		} catch (err) {
-			setError(err instanceof Error ? err.message : "Sign-in failed");
-			setSubmitting(false);
-		}
-	};
-
-	return (
-		<form className="grid gap-3" onSubmit={onSubmit}>
-			<div className="grid gap-1.5">
-				<Label htmlFor="local-dev-email" className="text-xs">
-					Email
-				</Label>
-				<Input
-					id="local-dev-email"
-					type="email"
-					autoComplete="email"
-					value={email}
-					onChange={(event) => setEmail(event.target.value)}
-					required
-				/>
-			</div>
-			<div className="grid gap-1.5">
-				<Label htmlFor="local-dev-password" className="text-xs">
-					Password
-				</Label>
-				<Input
-					id="local-dev-password"
-					type="password"
-					autoComplete="current-password"
-					value={password}
-					onChange={(event) => setPassword(event.target.value)}
-					required
-					minLength={8}
-				/>
-			</div>
-			{error && <p className="text-destructive text-xs">{error}</p>}
-			<Button
-				type="submit"
-				size="lg"
-				className="w-full"
-				disabled={submitting || persistToken.isPending}
-			>
-				{submitting || persistToken.isPending ? "Signing in..." : "Sign in"}
-			</Button>
-		</form>
-	);
-}
diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts
deleted file mode 100644
index 9514c0436a0..00000000000
--- a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevAuthForm/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { LocalDevAuthForm } from "./LocalDevAuthForm";
diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/LocalDevSignInButton.tsx b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/LocalDevSignInButton.tsx
new file mode 100644
index 00000000000..dcb8741210d
--- /dev/null
+++ b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/LocalDevSignInButton.tsx
@@ -0,0 +1,89 @@
+import {
+	DEV_EMAIL,
+	DEV_NAME,
+	DEV_PASSWORD,
+} from "@superset/shared/dev-credentials";
+import { DevSignInButton as SharedDevSignInButton } from "@superset/ui/dev-sign-in-button";
+import { useNavigate } from "@tanstack/react-router";
+import { env } from "renderer/env.renderer";
+import { setAuthToken } from "renderer/lib/auth-client";
+import { electronTrpc } from "renderer/lib/electron-trpc";
+
+const TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30;
+
+interface AuthResponse {
+	token?: string;
+}
+
+interface AuthErrorBody {
+	code?: string;
+	message?: string;
+}
+
+async function postAuth(
+	path: string,
+	body: Record<string, unknown>,
+): Promise<{
+	ok: boolean;
+	status: number;
+	data: AuthResponse | AuthErrorBody;
+}> {
+	const res = await fetch(`${env.NEXT_PUBLIC_API_URL}${path}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		credentials: "omit",
+		body: JSON.stringify(body),
+	});
+	const data = (await res.json().catch(() => ({}))) as
+		| AuthResponse
+		| AuthErrorBody;
+	return { ok: res.ok, status: res.status, data };
+}
+
+export function LocalDevSignInButton() {
+	const navigate = useNavigate();
+	const persistToken = electronTrpc.auth.persistToken.useMutation();
+
+	const onSignIn = async () => {
+		let signIn = await postAuth("/api/auth/sign-in/email", {
+			email: DEV_EMAIL,
+			password: DEV_PASSWORD,
+		});
+
+		const errBody = signIn.data as AuthErrorBody;
+		if (!signIn.ok && errBody.code === "INVALID_EMAIL_OR_PASSWORD") {
+			const signUp = await postAuth("/api/auth/sign-up/email", {
+				email: DEV_EMAIL,
+				password: DEV_PASSWORD,
+				name: DEV_NAME,
+			});
+			if (!signUp.ok) {
+				const signUpError = signUp.data as AuthErrorBody;
+				throw new Error(
+					signUpError.message ?? `Sign-up failed (${signUp.status})`,
+				);
+			}
+			signIn = await postAuth("/api/auth/sign-in/email", {
+				email: DEV_EMAIL,
+				password: DEV_PASSWORD,
+			});
+		}
+
+		if (!signIn.ok) {
+			const signInError = signIn.data as AuthErrorBody;
+			throw new Error(
+				signInError.message ?? `Sign-in failed (${signIn.status})`,
+			);
+		}
+
+		const token = (signIn.data as AuthResponse).token;
+		if (!token) throw new Error("Sign-in did not return a token");
+
+		const expiresAt = new Date(Date.now() + TOKEN_TTL_MS).toISOString();
+		await persistToken.mutateAsync({ token, expiresAt });
+		setAuthToken(token);
+		await navigate({ to: "/workspace", replace: true });
+	};
+
+	return <SharedDevSignInButton onSignIn={onSignIn} />;
+}
diff --git a/apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/index.ts b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/index.ts
new file mode 100644
index 00000000000..62835abcfc8
--- /dev/null
+++ b/apps/desktop/src/renderer/routes/sign-in/components/LocalDevSignInButton/index.ts
@@ -0,0 +1 @@
+export { LocalDevSignInButton } from "./LocalDevSignInButton";
diff --git a/apps/desktop/src/renderer/routes/sign-in/page.tsx b/apps/desktop/src/renderer/routes/sign-in/page.tsx
index d7d7f5eb4e2..2103e2578b5 100644
--- a/apps/desktop/src/renderer/routes/sign-in/page.tsx
+++ b/apps/desktop/src/renderer/routes/sign-in/page.tsx
@@ -7,7 +7,7 @@ import { FcGoogle } from "react-icons/fc";
 import { env } from "renderer/env.renderer";
 import { track } from "renderer/lib/analytics";
 import { electronTrpc } from "renderer/lib/electron-trpc";
-import { LocalDevAuthForm } from "./components/LocalDevAuthForm";
+import { LocalDevSignInButton } from "./components/LocalDevSignInButton";
 import { SupersetLogo } from "./components/SupersetLogo";
 import { useSessionRecovery } from "./hooks/useSessionRecovery";
 
@@ -66,7 +66,7 @@ function SignInPage() {
 					</div>
 
 					<div className="flex w-full max-w-xs flex-col gap-3">
-						{isLocalProfile && <LocalDevAuthForm />}
+						{isLocalProfile && <LocalDevSignInButton />}
 
 						{isLocalProfile && <div className="h-px bg-border" />}
 
diff --git a/apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx b/apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx
deleted file mode 100644
index d07f9a35f6a..00000000000
--- a/apps/web/src/app/(auth)/components/DevAuthForm/DevAuthForm.tsx
+++ /dev/null
@@ -1,103 +0,0 @@
-"use client";
-
-import { authClient } from "@superset/auth/client";
-import { Button } from "@superset/ui/button";
-import { Input } from "@superset/ui/input";
-import { Label } from "@superset/ui/label";
-import { useRouter } from "next/navigation";
-import { useState } from "react";
-
-interface DevAuthFormProps {
-	mode: "sign-in" | "sign-up";
-	callbackURL: string;
-}
-
-export function DevAuthForm({ mode, callbackURL }: DevAuthFormProps) {
-	const router = useRouter();
-	const [email, setEmail] = useState(
-		mode === "sign-up" ? "" : "admin@local.test",
-	);
-	const [password, setPassword] = useState(
-		mode === "sign-up" ? "" : "supersetdev",
-	);
-	const [name, setName] = useState("");
-	const [submitting, setSubmitting] = useState(false);
-	const [error, setError] = useState<string | null>(null);
-
-	const onSubmit = async (e: React.FormEvent) => {
-		e.preventDefault();
-		setSubmitting(true);
-		setError(null);
-
-		try {
-			if (mode === "sign-up") {
-				const res = await authClient.signUp.email({
-					email,
-					password,
-					name: name || email.split("@")[0] || "Dev User",
-				});
-				if (res.error) throw new Error(res.error.message);
-			} else {
-				const res = await authClient.signIn.email({ email, password });
-				if (res.error) throw new Error(res.error.message);
-			}
-			router.push(callbackURL);
-		} catch (err) {
-			const message =
-				err instanceof Error ? err.message : "Authentication failed";
-			setError(message);
-			setSubmitting(false);
-		}
-	};
-
-	return (
-		<form onSubmit={onSubmit} className="grid gap-3 rounded-md border p-4">
-			<p className="text-muted-foreground text-xs">
-				Dev only — email + password auth
-			</p>
-			{mode === "sign-up" && (
-				<div className="grid gap-1.5">
-					<Label htmlFor="name" className="text-xs">
-						Name
-					</Label>
-					<Input
-						id="name"
-						type="text"
-						value={name}
-						onChange={(e) => setName(e.target.value)}
-						placeholder="Optional"
-					/>
-				</div>
-			)}
-			<div className="grid gap-1.5">
-				<Label htmlFor="email" className="text-xs">
-					Email
-				</Label>
-				<Input
-					id="email"
-					type="email"
-					value={email}
-					onChange={(e) => setEmail(e.target.value)}
-					required
-				/>
-			</div>
-			<div className="grid gap-1.5">
-				<Label htmlFor="password" className="text-xs">
-					Password
-				</Label>
-				<Input
-					id="password"
-					type="password"
-					value={password}
-					onChange={(e) => setPassword(e.target.value)}
-					required
-					minLength={8}
-				/>
-			</div>
-			{error && <p className="text-destructive text-xs">{error}</p>}
-			<Button type="submit" disabled={submitting} className="w-full">
-				{submitting ? "..." : mode === "sign-up" ? "Create account" : "Sign in"}
-			</Button>
-		</form>
-	);
-}
diff --git a/apps/web/src/app/(auth)/components/DevAuthForm/index.ts b/apps/web/src/app/(auth)/components/DevAuthForm/index.ts
deleted file mode 100644
index eddbcfa938b..00000000000
--- a/apps/web/src/app/(auth)/components/DevAuthForm/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { DevAuthForm } from "./DevAuthForm";
diff --git a/apps/web/src/app/(auth)/components/DevSignInButton/DevSignInButton.tsx b/apps/web/src/app/(auth)/components/DevSignInButton/DevSignInButton.tsx
new file mode 100644
index 00000000000..2817ddce35f
--- /dev/null
+++ b/apps/web/src/app/(auth)/components/DevSignInButton/DevSignInButton.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { authClient } from "@superset/auth/client";
+import {
+	DEV_EMAIL,
+	DEV_NAME,
+	DEV_PASSWORD,
+} from "@superset/shared/dev-credentials";
+import { DevSignInButton as SharedDevSignInButton } from "@superset/ui/dev-sign-in-button";
+import { useRouter } from "next/navigation";
+
+interface DevSignInButtonProps {
+	callbackURL: string;
+}
+
+export function DevSignInButton({ callbackURL }: DevSignInButtonProps) {
+	const router = useRouter();
+
+	const onSignIn = async () => {
+		let res = await authClient.signIn.email({
+			email: DEV_EMAIL,
+			password: DEV_PASSWORD,
+		});
+		if (res.error) {
+			const signUpRes = await authClient.signUp.email({
+				email: DEV_EMAIL,
+				password: DEV_PASSWORD,
+				name: DEV_NAME,
+			});
+			if (signUpRes.error) throw new Error(signUpRes.error.message);
+			res = await authClient.signIn.email({
+				email: DEV_EMAIL,
+				password: DEV_PASSWORD,
+			});
+		}
+		if (res.error) throw new Error(res.error.message);
+		router.push(callbackURL);
+	};
+
+	return <SharedDevSignInButton onSignIn={onSignIn} />;
+}
diff --git a/apps/web/src/app/(auth)/components/DevSignInButton/index.ts b/apps/web/src/app/(auth)/components/DevSignInButton/index.ts
new file mode 100644
index 00000000000..816b0169335
--- /dev/null
+++ b/apps/web/src/app/(auth)/components/DevSignInButton/index.ts
@@ -0,0 +1 @@
+export { DevSignInButton } from "./DevSignInButton";
diff --git a/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx b/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
index 63049a01b27..75d6b41ec4d 100644
--- a/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
+++ b/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
@@ -8,7 +8,7 @@ import { useState } from "react";
 import { FaGithub } from "react-icons/fa";
 import { FcGoogle } from "react-icons/fc";
 import { env } from "@/env";
-import { DevAuthForm } from "../../components/DevAuthForm";
+import { DevSignInButton } from "../../components/DevSignInButton";
 
 const isDev = process.env.NODE_ENV !== "production";
 
@@ -69,7 +69,7 @@ export default function SignInPage() {
 				{error && (
 					<p className="text-destructive text-center text-sm">{error}</p>
 				)}
-				{isDev && <DevAuthForm mode="sign-in" callbackURL={callbackURL} />}
+				{isDev && <DevSignInButton callbackURL={callbackURL} />}
 				<Button
 					variant="outline"
 					disabled={isLoading}
diff --git a/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx b/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
index 66a2e56b728..a5678246ff0 100644
--- a/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
+++ b/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
@@ -7,7 +7,7 @@ import { useState } from "react";
 import { FaGithub } from "react-icons/fa";
 import { FcGoogle } from "react-icons/fc";
 import { env } from "@/env";
-import { DevAuthForm } from "../../components/DevAuthForm";
+import { DevSignInButton } from "../../components/DevSignInButton";
 
 const isDev = process.env.NODE_ENV !== "production";
 
@@ -64,9 +64,7 @@ export default function SignUpPage() {
 				{error && (
 					<p className="text-destructive text-center text-sm">{error}</p>
 				)}
-				{isDev && (
-					<DevAuthForm mode="sign-up" callbackURL={env.NEXT_PUBLIC_WEB_URL} />
-				)}
+				{isDev && <DevSignInButton callbackURL={env.NEXT_PUBLIC_WEB_URL} />}
 				<Button
 					variant="outline"
 					disabled={isLoading}
diff --git a/packages/db/src/seed-dev.ts b/packages/db/src/seed-dev.ts
index b06b9a4410a..e111342f8f3 100644
--- a/packages/db/src/seed-dev.ts
+++ b/packages/db/src/seed-dev.ts
@@ -1,13 +1,14 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+	DEV_EMAIL as DEV_ADMIN_EMAIL,
+	DEV_NAME as DEV_ADMIN_NAME,
+	DEV_PASSWORD as DEV_ADMIN_PASSWORD,
+} from "@superset/shared/dev-credentials";
 import { config } from "dotenv";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 config({ path: path.resolve(__dirname, "../../../.env"), quiet: true });
-
-const DEV_ADMIN_EMAIL = "admin@local.test";
-const DEV_ADMIN_PASSWORD = "supersetdev";
-const DEV_ADMIN_NAME = "Local Admin";
 const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 
 function requireLocalUrl(value: string, label: string): URL {
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 5f0400af78e..b56d669cf3b 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -12,6 +12,10 @@
 			"types": "./src/deployment-profile.ts",
 			"default": "./src/deployment-profile.ts"
 		},
+		"./dev-credentials": {
+			"types": "./src/dev-credentials.ts",
+			"default": "./src/dev-credentials.ts"
+		},
 		"./v2-only-user": {
 			"types": "./src/v2-only-user.ts",
 			"default": "./src/v2-only-user.ts"
diff --git a/packages/shared/src/dev-credentials.ts b/packages/shared/src/dev-credentials.ts
new file mode 100644
index 00000000000..565af54fbb9
--- /dev/null
+++ b/packages/shared/src/dev-credentials.ts
@@ -0,0 +1,11 @@
+/**
+ * Seeded local-dev account used by:
+ * - packages/db seed-dev to insert the user
+ * - apps/desktop LocalDevAuthForm + dev-auto-sign-in to authenticate against it
+ * - apps/web DevSignInButton to authenticate against it
+ *
+ * Only valid in the `local` deployment profile. Never use in production.
+ */
+export const DEV_EMAIL = "admin@local.test";
+export const DEV_PASSWORD = "supersetdev";
+export const DEV_NAME = "Local Admin";
diff --git a/packages/ui/src/components/ui/dev-sign-in-button.tsx b/packages/ui/src/components/ui/dev-sign-in-button.tsx
new file mode 100644
index 00000000000..13ef144c6ab
--- /dev/null
+++ b/packages/ui/src/components/ui/dev-sign-in-button.tsx
@@ -0,0 +1,49 @@
+import { useState } from "react";
+
+import { Button } from "./button";
+
+export interface DevSignInButtonProps {
+	/**
+	 * Performs the platform-specific dev sign-in (and any redirect on success).
+	 * Throwing rejects with an error message rendered under the button.
+	 */
+	onSignIn: () => Promise<void>;
+}
+
+/**
+ * One-click sign-in button for local-dev profiles. Pure UI; the calling app
+ * supplies the auth transport and post-sign-in routing via onSignIn.
+ *
+ * Dev-only — render only when NODE_ENV !== "production" (or the platform's
+ * equivalent local-profile gate).
+ */
+export function DevSignInButton({ onSignIn }: DevSignInButtonProps) {
+	const [submitting, setSubmitting] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	const handleClick = async () => {
+		setSubmitting(true);
+		setError(null);
+		try {
+			await onSignIn();
+		} catch (err) {
+			setError(err instanceof Error ? err.message : "Dev sign-in failed");
+			setSubmitting(false);
+		}
+	};
+
+	return (
+		<div className="grid gap-2">
+			<Button
+				type="button"
+				variant="outline"
+				disabled={submitting}
+				onClick={handleClick}
+				className="w-full"
+			>
+				{submitting ? "Signing in..." : "Sign in as Local Admin (dev)"}
+			</Button>
+			{error && <p className="text-destructive text-center text-xs">{error}</p>}
+		</div>
+	);
+}

From 71b11cdcd584dc8e4e18a5ac0385f3c24e9cf88f Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 14:31:38 -0700
Subject: [PATCH 16/28] Fix task sync test mock

---
 packages/trpc/src/router/task/task.test.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/trpc/src/router/task/task.test.ts b/packages/trpc/src/router/task/task.test.ts
index fc712cd395e..40f848abda7 100644
--- a/packages/trpc/src/router/task/task.test.ts
+++ b/packages/trpc/src/router/task/task.test.ts
@@ -3,7 +3,7 @@ import { TRPCError, type TRPCRouterRecord } from "@trpc/server";
 
 const getCurrentTxidMock = mock(async () => "txid-123");
 const seedDefaultStatusesMock = mock(async () => "status-seeded");
-const syncTaskMock = mock(() => undefined);
+const syncTaskMock = mock(async () => []);
 const verifyOrgAdminMock = mock(async () => ({
 	membership: { role: "owner" },
 }));
@@ -245,7 +245,7 @@ describe("task router authorization", () => {
 		seedDefaultStatusesMock.mockImplementation(async () => "status-seeded");
 
 		syncTaskMock.mockReset();
-		syncTaskMock.mockImplementation(() => undefined);
+		syncTaskMock.mockImplementation(async () => []);
 
 		transactionMock.mockReset();
 		transactionMock.mockImplementation(async (callback) =>

From 6264cedcdbaaad3e49b1c50ec08348a9a5223512 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 15:39:39 -0700
Subject: [PATCH 17/28] Fix canary app metadata

---
 apps/desktop/electron-builder.canary.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/desktop/electron-builder.canary.ts b/apps/desktop/electron-builder.canary.ts
index 8cdac856a7b..518a563f15c 100644
--- a/apps/desktop/electron-builder.canary.ts
+++ b/apps/desktop/electron-builder.canary.ts
@@ -22,6 +22,9 @@ const config: Configuration = {
 	...baseConfig,
 	appId: "com.superset.desktop.canary",
 	productName,
+	extraMetadata: {
+		productName,
+	},
 
 	publish: {
 		provider: "github",

From 3391f458833b23d568b501a9f1abb13c2aa3c050 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 15:47:13 -0700
Subject: [PATCH 18/28] Remove stale host service discovery call

---
 apps/desktop/src/main/index.ts | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index ffd26df62d4..41ddaadff4d 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -434,10 +434,6 @@ if (!gotTheLock) {
 		// block on this.
 		void ensureDevAuthToken();
 
-		// Discover and adopt host-services that survived a previous quit
-		// before the tray initializes, so it shows accurate status immediately.
-		await getHostServiceCoordinator().discoverAll();
-
 		if (IS_DEV) {
 			getHostServiceCoordinator().enableDevReload(async () => {
 				const { token } = await loadToken();

From ed46380ac624c2f5245d2b02ada4be8a36200b34 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 15:54:05 -0700
Subject: [PATCH 19/28] Allow unsigned canary desktop builds

---
 .github/workflows/build-desktop.yml          | 17 +++--
 .github/workflows/release-desktop-canary.yml |  7 ++
 apps/desktop/electron-builder.ts             |  2 +
 scripts/release-canary.sh                    | 69 +++++++++++++++++++-
 4 files changed, 88 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/build-desktop.yml b/.github/workflows/build-desktop.yml
index 0bb7691abcf..8b0dfb67712 100644
--- a/.github/workflows/build-desktop.yml
+++ b/.github/workflows/build-desktop.yml
@@ -27,6 +27,11 @@ on:
         required: false
         type: number
         default: 30
+      skip_signing:
+        description: "Build macOS artifacts without code signing or notarization"
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-macos:
@@ -112,11 +117,13 @@ jobs:
       - name: Build Electron app
         working-directory: apps/desktop
         env:
-          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
-          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          CSC_LINK: ${{ inputs.skip_signing == false && secrets.MAC_CERTIFICATE || '' }}
+          CSC_KEY_PASSWORD: ${{ inputs.skip_signing == false && secrets.MAC_CERTIFICATE_PASSWORD || '' }}
+          APPLE_ID: ${{ inputs.skip_signing == false && secrets.APPLE_ID || '' }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ inputs.skip_signing == false && secrets.APPLE_ID_PASSWORD || '' }}
+          APPLE_TEAM_ID: ${{ inputs.skip_signing == false && secrets.APPLE_TEAM_ID || '' }}
+          CSC_IDENTITY_AUTO_DISCOVERY: ${{ inputs.skip_signing && 'false' || '' }}
+          SKIP_CODE_SIGNING: ${{ inputs.skip_signing && 'true' || 'false' }}
           TARGET_ARCH: ${{ matrix.arch }}
         run: bun run package -- --publish never --config ${{ inputs.electron_builder_config }} --${{ matrix.arch }}
 
diff --git a/.github/workflows/release-desktop-canary.yml b/.github/workflows/release-desktop-canary.yml
index 89d7ef1a5e0..091456eb5fd 100644
--- a/.github/workflows/release-desktop-canary.yml
+++ b/.github/workflows/release-desktop-canary.yml
@@ -11,6 +11,11 @@ on:
         required: false
         type: boolean
         default: false
+      skip_signing:
+        description: "Build macOS artifacts without code signing or notarization"
+        required: false
+        type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -77,6 +82,7 @@ jobs:
       electron_builder_config: electron-builder.canary.ts
       artifact_prefix: desktop-canary
       artifact_retention_days: 7
+      skip_signing: ${{ github.event.inputs.skip_signing == 'true' }}
     secrets: inherit
 
   release:
@@ -149,6 +155,7 @@ jobs:
             - Commit: ${{ github.sha }}
             - Short SHA: ${{ needs.check-changes.outputs.short_sha }}
             - Built: ${{ needs.check-changes.outputs.build_time }}
+            - Code signing: ${{ github.event.inputs.skip_signing == 'true' && 'skipped' || 'enabled' }}
 
             ⚠️ This build is for internal testing only and may be unstable.
           prerelease: true
diff --git a/apps/desktop/electron-builder.ts b/apps/desktop/electron-builder.ts
index f7712a06bf2..70f0a729226 100644
--- a/apps/desktop/electron-builder.ts
+++ b/apps/desktop/electron-builder.ts
@@ -18,6 +18,7 @@ const productName = pkg.productName;
 const macIconPath = join(pkg.resources, "build/icons/icon.icns");
 const linuxIconPath = join(pkg.resources, "build/icons");
 const winIconPath = join(pkg.resources, "build/icons/icon.ico");
+const skipCodeSigning = process.env.SKIP_CODE_SIGNING === "true";
 const dmgBackgroundPath = join(
 	pkg.resources,
 	"build/installer/background.tiff",
@@ -112,6 +113,7 @@ const config: Configuration = {
 		hardenedRuntime: true,
 		gatekeeperAssess: false,
 		notarize: true,
+		...(skipCodeSigning ? { identity: null, notarize: false } : {}),
 		entitlements: join(pkg.resources, "build/entitlements.mac.plist"),
 		entitlementsInherit: join(
 			pkg.resources,
diff --git a/scripts/release-canary.sh b/scripts/release-canary.sh
index d0e1318c3c0..96d5ac5b6a9 100755
--- a/scripts/release-canary.sh
+++ b/scripts/release-canary.sh
@@ -1,10 +1,75 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-COMMIT="${1:-}"
+usage() {
+  cat <<'EOF'
+Usage: bun run release:canary -- [--skip-signing] [commit]
+
+Options:
+  --skip-signing        Build the macOS canary artifact without code signing or notarization.
+  -h, --help            Show this help message.
+
+Examples:
+  bun run release:canary -- HEAD
+  bun run release:canary -- --skip-signing HEAD
+EOF
+}
+
+COMMIT=""
+SKIP_SIGNING=false
 REF_FLAG=""
 TEMP_BRANCH=""
 
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --skip-signing)
+      SKIP_SIGNING=true
+      ;;
+    --skip-signing=true)
+      SKIP_SIGNING=true
+      ;;
+    --skip-signing=false | --no-skip-signing)
+      SKIP_SIGNING=false
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      if [ "$#" -gt 0 ]; then
+        if [ -n "$COMMIT" ]; then
+          echo "Error: commit specified more than once" >&2
+          usage >&2
+          exit 1
+        fi
+        COMMIT="$1"
+        shift
+      fi
+      if [ "$#" -gt 0 ]; then
+        echo "Error: unexpected arguments: $*" >&2
+        usage >&2
+        exit 1
+      fi
+      break
+      ;;
+    -*)
+      echo "Error: unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      if [ -n "$COMMIT" ]; then
+        echo "Error: commit specified more than once: $COMMIT and $1" >&2
+        usage >&2
+        exit 1
+      fi
+      COMMIT="$1"
+      ;;
+  esac
+  shift
+done
+
 if [ -n "$COMMIT" ]; then
   FULL_SHA=$(git rev-parse "$COMMIT")
   TEMP_BRANCH="canary-release-${FULL_SHA:0:9}"
@@ -12,6 +77,6 @@ if [ -n "$COMMIT" ]; then
   REF_FLAG="--ref $TEMP_BRANCH"
 fi
 
-gh workflow run release-desktop-canary.yml -f force_build=true $REF_FLAG
+gh workflow run release-desktop-canary.yml -f force_build=true -f skip_signing="$SKIP_SIGNING" $REF_FLAG
 sleep 2
 gh run list --workflow=release-desktop-canary.yml --limit=1 --json url -q '.[0].url'

From 57b0b7861f395cfda99f73de1c6b4afb35bd43fc Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 16:31:08 -0700
Subject: [PATCH 20/28] Fix renderer env empty profile handling

---
 .../src/renderer/env.renderer.schema.test.ts  | 59 ++++++++++++++
 .../src/renderer/env.renderer.schema.ts       | 81 +++++++++++++++++++
 apps/desktop/src/renderer/env.renderer.ts     | 49 +----------
 3 files changed, 142 insertions(+), 47 deletions(-)
 create mode 100644 apps/desktop/src/renderer/env.renderer.schema.test.ts
 create mode 100644 apps/desktop/src/renderer/env.renderer.schema.ts

diff --git a/apps/desktop/src/renderer/env.renderer.schema.test.ts b/apps/desktop/src/renderer/env.renderer.schema.test.ts
new file mode 100644
index 00000000000..f37e75205f9
--- /dev/null
+++ b/apps/desktop/src/renderer/env.renderer.schema.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { parseRendererEnv } from "./env.renderer.schema";
+
+describe("parseRendererEnv", () => {
+	test("treats empty build-time strings as unset in production", () => {
+		const env = parseRendererEnv({
+			NODE_ENV: "production",
+			SUPERSET_PROFILE: "",
+			NEXT_PUBLIC_API_URL: "",
+			NEXT_PUBLIC_WEB_URL: "",
+			NEXT_PUBLIC_MARKETING_URL: "",
+			NEXT_PUBLIC_ELECTRIC_URL: "",
+			NEXT_PUBLIC_POSTHOG_KEY: "",
+			NEXT_PUBLIC_POSTHOG_HOST: "",
+			SENTRY_DSN_DESKTOP: "",
+			RELAY_URL: "",
+		});
+
+		expect(env.SUPERSET_PROFILE).toBeUndefined();
+		expect(env.NEXT_PUBLIC_API_URL).toBe("https://api.superset.sh");
+		expect(env.NEXT_PUBLIC_WEB_URL).toBe("https://app.superset.sh");
+		expect(env.NEXT_PUBLIC_POSTHOG_KEY).toBeUndefined();
+		expect(env.SENTRY_DSN_DESKTOP).toBeUndefined();
+		expect(env.RELAY_URL).toBe("https://relay.superset.sh");
+	});
+
+	test("uses local defaults only for the development local profile", () => {
+		const env = parseRendererEnv({
+			NODE_ENV: "development",
+			SUPERSET_PROFILE: "local",
+		});
+
+		expect(env.NEXT_PUBLIC_API_URL).toBe("http://localhost:4641");
+		expect(env.NEXT_PUBLIC_WEB_URL).toBe("http://localhost:4640");
+		expect(env.NEXT_PUBLIC_ELECTRIC_URL).toBe("https://localhost:4650");
+		expect(env.RELAY_URL).toBe("http://localhost:4653");
+	});
+
+	test("keeps production defaults when local profile leaks into a production build", () => {
+		const env = parseRendererEnv({
+			NODE_ENV: "production",
+			SUPERSET_PROFILE: "local",
+		});
+
+		expect(env.SUPERSET_PROFILE).toBe("local");
+		expect(env.NEXT_PUBLIC_API_URL).toBe("https://api.superset.sh");
+		expect(env.NEXT_PUBLIC_WEB_URL).toBe("https://app.superset.sh");
+		expect(env.RELAY_URL).toBe("https://relay.superset.sh");
+	});
+
+	test("rejects non-empty invalid profiles", () => {
+		expect(() =>
+			parseRendererEnv({
+				NODE_ENV: "production",
+				SUPERSET_PROFILE: "invalid",
+			}),
+		).toThrow();
+	});
+});
diff --git a/apps/desktop/src/renderer/env.renderer.schema.ts b/apps/desktop/src/renderer/env.renderer.schema.ts
new file mode 100644
index 00000000000..a4d04266cee
--- /dev/null
+++ b/apps/desktop/src/renderer/env.renderer.schema.ts
@@ -0,0 +1,81 @@
+import { z } from "zod/v4";
+
+export type RendererEnvInput = {
+	NODE_ENV?: string;
+	NEXT_PUBLIC_API_URL?: string;
+	NEXT_PUBLIC_WEB_URL?: string;
+	NEXT_PUBLIC_MARKETING_URL?: string;
+	NEXT_PUBLIC_ELECTRIC_URL?: string;
+	NEXT_PUBLIC_POSTHOG_KEY?: string;
+	NEXT_PUBLIC_POSTHOG_HOST?: string;
+	SENTRY_DSN_DESKTOP?: string;
+	SUPERSET_PROFILE?: string;
+	RELAY_URL?: string;
+};
+
+const deploymentProfileSchema = z
+	.enum(["cloud", "local", "ci", "internal"])
+	.optional();
+
+function emptyStringAsUndefined(rawEnv: RendererEnvInput): RendererEnvInput {
+	return Object.fromEntries(
+		Object.entries(rawEnv).map(([key, value]) => [
+			key,
+			value === "" ? undefined : value,
+		]),
+	) as RendererEnvInput;
+}
+
+function createRendererEnvSchema(isLocalDevelopment: boolean) {
+	return z.object({
+		NODE_ENV: z
+			.enum(["development", "production", "test"])
+			.default("development"),
+		// Local contributor builds default to localhost. Internal dev keeps the
+		// existing hosted fallback unless the profile is explicitly local.
+		NEXT_PUBLIC_API_URL: z
+			.url()
+			.default(
+				isLocalDevelopment
+					? "http://localhost:4641"
+					: "https://api.superset.sh",
+			),
+		NEXT_PUBLIC_WEB_URL: z
+			.url()
+			.default(
+				isLocalDevelopment
+					? "http://localhost:4640"
+					: "https://app.superset.sh",
+			),
+		NEXT_PUBLIC_MARKETING_URL: z.url().default("https://superset.sh"),
+		NEXT_PUBLIC_ELECTRIC_URL: z
+			.url()
+			.default(
+				isLocalDevelopment
+					? "https://localhost:4650"
+					: "https://electric-proxy.avi-6ac.workers.dev",
+			),
+		NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
+		NEXT_PUBLIC_POSTHOG_HOST: z.string().default("https://us.i.posthog.com"),
+		SENTRY_DSN_DESKTOP: z.string().optional(),
+		SUPERSET_PROFILE: deploymentProfileSchema,
+		RELAY_URL: z
+			.url()
+			.default(
+				isLocalDevelopment
+					? "http://localhost:4653"
+					: "https://relay.superset.sh",
+			),
+	});
+}
+
+export function parseRendererEnv(rawEnv: RendererEnvInput) {
+	const normalizedEnv = emptyStringAsUndefined(rawEnv);
+	const isLocalDevelopment =
+		normalizedEnv.NODE_ENV === "development" &&
+		normalizedEnv.SUPERSET_PROFILE === "local";
+
+	return createRendererEnvSchema(isLocalDevelopment).parse(normalizedEnv);
+}
+
+export type RendererEnv = ReturnType<typeof parseRendererEnv>;
diff --git a/apps/desktop/src/renderer/env.renderer.ts b/apps/desktop/src/renderer/env.renderer.ts
index 495be6feee9..737897cbb3b 100644
--- a/apps/desktop/src/renderer/env.renderer.ts
+++ b/apps/desktop/src/renderer/env.renderer.ts
@@ -9,50 +9,7 @@
  *
  * For main process env vars, use src/main/env.main.ts instead.
  */
-import { z } from "zod/v4";
-
-const envSchema = z.object({
-	NODE_ENV: z
-		.enum(["development", "production", "test"])
-		.default("development"),
-	// Hosted defaults for prod builds. In dev builds Vite replaces
-	// NODE_ENV with "development", so the dev-time defaults below kick in
-	// and a fresh-clone contributor never silently syncs against
-	// production Electric / API.
-	NEXT_PUBLIC_API_URL: z
-		.url()
-		.default(
-			process.env.NODE_ENV === "development"
-				? "http://localhost:4641"
-				: "https://api.superset.sh",
-		),
-	NEXT_PUBLIC_WEB_URL: z
-		.url()
-		.default(
-			process.env.NODE_ENV === "development"
-				? "http://localhost:4640"
-				: "https://app.superset.sh",
-		),
-	NEXT_PUBLIC_MARKETING_URL: z.url().default("https://superset.sh"),
-	NEXT_PUBLIC_ELECTRIC_URL: z
-		.url()
-		.default(
-			process.env.NODE_ENV === "development"
-				? "https://localhost:4650"
-				: "https://electric-proxy.avi-6ac.workers.dev",
-		),
-	NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
-	NEXT_PUBLIC_POSTHOG_HOST: z.string().default("https://us.i.posthog.com"),
-	SENTRY_DSN_DESKTOP: z.string().optional(),
-	SUPERSET_PROFILE: z.enum(["cloud", "local", "ci", "internal"]).optional(),
-	RELAY_URL: z
-		.url()
-		.default(
-			process.env.NODE_ENV === "development"
-				? "http://localhost:4653"
-				: "https://relay.superset.sh",
-		),
-});
+import { parseRendererEnv, type RendererEnv } from "./env.renderer.schema";
 
 /**
  * Build-time environment variables.
@@ -83,8 +40,6 @@ const SKIP_ENV_VALIDATION =
 	process.env.NODE_ENV === "development" && !!process.env.SKIP_ENV_VALIDATION;
 
 export const env = {
-	...(SKIP_ENV_VALIDATION
-		? (rawEnv as z.infer<typeof envSchema>)
-		: envSchema.parse(rawEnv)),
+	...(SKIP_ENV_VALIDATION ? (rawEnv as RendererEnv) : parseRendererEnv(rawEnv)),
 	SKIP_ENV_VALIDATION,
 };

From 4c1b0e2891bb7236504b35d627aa061ca0afc056 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 17:17:48 -0700
Subject: [PATCH 21/28] Constrain local dev profile behavior

---
 apps/desktop/src/main/env.main.ts             | 33 +++++++++++--------
 .../src/renderer/env.renderer.schema.test.ts  |  4 +--
 .../src/renderer/env.renderer.schema.ts       |  6 ++++
 .../OpenInWorkspaceV2/OpenInWorkspaceV2.tsx   |  6 ++--
 .../RunInWorkspacePopoverV2.tsx               |  6 ++--
 .../RunIssuesInWorkspacePopover.tsx           |  6 ++--
 .../useAccessibleV2Workspaces.ts              |  6 ++--
 .../useWorkspaceHostOptions.ts                |  6 ++--
 .../DashboardNewWorkspaceModalContent.tsx     |  6 ++--
 .../V1ImportModal/V1ImportModal.tsx           |  6 ++--
 .../renderer/routes/_authenticated/layout.tsx |  6 ++--
 .../CollectionsProvider.tsx                   |  6 ++--
 .../LocalHostServiceProvider.tsx              |  6 ++--
 .../HostsSettingsSidebar.tsx                  |  6 ++--
 .../_authenticated/settings/hosts/page.tsx    |  6 ++--
 .../settings/projects/$projectId/page.tsx     |  6 ++--
 .../ProjectsSettingsSidebar.tsx               |  6 ++--
 .../_authenticated/settings/projects/page.tsx |  6 ++--
 .../_authenticated/setup/project/page.tsx     |  6 ++--
 .../src/renderer/routes/sign-in/page.tsx      |  3 +-
 apps/desktop/vite/helpers.ts                  |  7 ++--
 .../(auth)/sign-in/[[...sign-in]]/page.tsx    |  7 ++--
 .../(auth)/sign-up/[[...sign-up]]/page.tsx    |  9 +++--
 packages/auth/src/server.ts                   |  9 +++--
 .../shared/src/deployment-profile.test.ts     | 20 +++++++++--
 packages/shared/src/deployment-profile.ts     | 14 ++++++--
 26 files changed, 127 insertions(+), 81 deletions(-)

diff --git a/apps/desktop/src/main/env.main.ts b/apps/desktop/src/main/env.main.ts
index 6fa5939b502..ec5536cc1ef 100644
--- a/apps/desktop/src/main/env.main.ts
+++ b/apps/desktop/src/main/env.main.ts
@@ -44,50 +44,57 @@ function getDeploymentProfile(): MainDeploymentProfile {
 		return "cloud";
 	}
 	const explicitProfile = getExplicitProfile();
-	if (explicitProfile) return explicitProfile;
+	if (explicitProfile) {
+		if (explicitProfile === "local" && process.env.NODE_ENV === "production") {
+			return "internal";
+		}
+		return explicitProfile;
+	}
 	if (isTruthyFlag(process.env.CI)) return "ci";
 	return "internal";
 }
 
 export const deploymentProfile = getDeploymentProfile();
-const isStrict =
-	deploymentProfile === "cloud" || deploymentProfile === "internal";
 const skipValidation =
-	!isStrict || isTruthyFlag(process.env.SKIP_ENV_VALIDATION);
+	deploymentProfile === "ci" ||
+	deploymentProfile === "local" ||
+	(process.env.NODE_ENV !== "production" &&
+		isTruthyFlag(process.env.SKIP_ENV_VALIDATION));
+const isLocalDevelopment =
+	process.env.NODE_ENV === "development" && deploymentProfile === "local";
 
 export const env = createEnv({
 	server: {
 		NODE_ENV: z
 			.enum(["development", "production", "test"])
 			.default("development"),
-		// In dev builds (NODE_ENV=development) the URL defaults switch to
-		// localhost so fresh-clone local contributors never silently sync
-		// against hosted production endpoints.
+		// In explicit local-profile dev builds, defaults switch to localhost so
+		// fresh-clone contributors never silently sync against hosted endpoints.
 		NEXT_PUBLIC_API_URL: z
 			.url()
 			.default(
-				process.env.NODE_ENV === "development"
+				isLocalDevelopment
 					? "http://localhost:4641"
 					: "https://api.superset.sh",
 			),
 		NEXT_PUBLIC_STREAMS_URL: z
 			.url()
 			.default(
-				process.env.NODE_ENV === "development"
+				isLocalDevelopment
 					? "http://localhost:4647"
 					: "https://streams.superset.sh",
 			),
 		NEXT_PUBLIC_ELECTRIC_URL: z
 			.url()
 			.default(
-				process.env.NODE_ENV === "development"
+				isLocalDevelopment
 					? "https://localhost:4650"
 					: "https://electric-proxy.avi-6ac.workers.dev",
 			),
 		NEXT_PUBLIC_WEB_URL: z
 			.url()
 			.default(
-				process.env.NODE_ENV === "development"
+				isLocalDevelopment
 					? "http://localhost:4640"
 					: "https://app.superset.sh",
 			),
@@ -98,14 +105,14 @@ export const env = createEnv({
 		STREAMS_URL: z
 			.url()
 			.default(
-				process.env.NODE_ENV === "development"
+				isLocalDevelopment
 					? "http://localhost:4647"
 					: "https://superset-stream.fly.dev",
 			),
 		RELAY_URL: z
 			.url()
 			.default(
-				process.env.NODE_ENV === "development"
+				isLocalDevelopment
 					? "http://localhost:4653"
 					: "https://relay.superset.sh",
 			),
diff --git a/apps/desktop/src/renderer/env.renderer.schema.test.ts b/apps/desktop/src/renderer/env.renderer.schema.test.ts
index f37e75205f9..e3cda3ebae2 100644
--- a/apps/desktop/src/renderer/env.renderer.schema.test.ts
+++ b/apps/desktop/src/renderer/env.renderer.schema.test.ts
@@ -36,13 +36,13 @@ describe("parseRendererEnv", () => {
 		expect(env.RELAY_URL).toBe("http://localhost:4653");
 	});
 
-	test("keeps production defaults when local profile leaks into a production build", () => {
+	test("ignores local profile when it leaks into a production build", () => {
 		const env = parseRendererEnv({
 			NODE_ENV: "production",
 			SUPERSET_PROFILE: "local",
 		});
 
-		expect(env.SUPERSET_PROFILE).toBe("local");
+		expect(env.SUPERSET_PROFILE).toBeUndefined();
 		expect(env.NEXT_PUBLIC_API_URL).toBe("https://api.superset.sh");
 		expect(env.NEXT_PUBLIC_WEB_URL).toBe("https://app.superset.sh");
 		expect(env.RELAY_URL).toBe("https://relay.superset.sh");
diff --git a/apps/desktop/src/renderer/env.renderer.schema.ts b/apps/desktop/src/renderer/env.renderer.schema.ts
index a4d04266cee..0906995c0de 100644
--- a/apps/desktop/src/renderer/env.renderer.schema.ts
+++ b/apps/desktop/src/renderer/env.renderer.schema.ts
@@ -71,6 +71,12 @@ function createRendererEnvSchema(isLocalDevelopment: boolean) {
 
 export function parseRendererEnv(rawEnv: RendererEnvInput) {
 	const normalizedEnv = emptyStringAsUndefined(rawEnv);
+	if (
+		normalizedEnv.NODE_ENV === "production" &&
+		normalizedEnv.SUPERSET_PROFILE === "local"
+	) {
+		normalizedEnv.SUPERSET_PROFILE = undefined;
+	}
 	const isLocalDevelopment =
 		normalizedEnv.NODE_ENV === "development" &&
 		normalizedEnv.SUPERSET_PROFILE === "local";
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx
index 017ff5f60ae..559d343b9dc 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/$taskId/components/PropertiesSidebar/components/OpenInWorkspaceV2/OpenInWorkspaceV2.tsx
@@ -56,9 +56,9 @@ export function OpenInWorkspaceV2({ task }: OpenInWorkspaceV2Props) {
 	const { machineId, activeHostUrl } = hostService;
 	const { otherHosts } = useWorkspaceHostOptions();
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { submit } = useWorkspaceCreates();
 	const lastProjectId = useV2WorkspaceCreateDefaultsStore(
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx
index 91758e0fa29..6d150dcffd1 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunInWorkspacePopoverV2/RunInWorkspacePopoverV2.tsx
@@ -61,9 +61,9 @@ export function RunInWorkspacePopoverV2({
 	const hostService = useLocalHostService();
 	const { machineId, activeHostUrl } = hostService;
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 	const { otherHosts } = useWorkspaceHostOptions();
 	const { submit } = useWorkspaceCreates();
 
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx
index 060026ab9e3..0f0e6584105 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/tasks/components/TasksView/components/TasksTopBar/components/RunIssuesInWorkspacePopover/RunIssuesInWorkspacePopover.tsx
@@ -65,9 +65,9 @@ export function RunIssuesInWorkspacePopover({
 	const hostService = useLocalHostService();
 	const { machineId, activeHostUrl } = hostService;
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 	const { otherHosts } = useWorkspaceHostOptions();
 	const { submit } = useWorkspaceCreates();
 
diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts
index 6a95ea646b5..eb904571c63 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspaces/hooks/useAccessibleV2Workspaces/useAccessibleV2Workspaces.ts
@@ -221,9 +221,9 @@ export function useAccessibleV2Workspaces(
 	const collections = useCollections();
 	const { machineId } = useLocalHostService();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 	const currentUserId = session?.user?.id ?? null;
 
 	const { data: rows = [] } = useLiveQuery(
diff --git a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts
index 6014b9ee911..b96c7534db5 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts
+++ b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/components/DevicePicker/hooks/useWorkspaceHostOptions/useWorkspaceHostOptions.ts
@@ -26,9 +26,9 @@ export function useWorkspaceHostOptions(): UseWorkspaceHostOptionsResult {
 	const collections = useCollections();
 	const { machineId, activeHostUrl } = useLocalHostService();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 	const currentUserId = session?.user?.id ?? null;
 
 	const { data: accessibleHosts = [] } = useLiveQuery(
diff --git a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx
index da6b96ba19d..da8399adba2 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceModalContent/DashboardNewWorkspaceModalContent.tsx
@@ -32,9 +32,9 @@ export function DashboardNewWorkspaceModalContent({
 	);
 	const collections = useCollections();
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: v2Projects } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx b/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx
index 8b127423c10..bd292fd0e90 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/components/V1ImportModal/V1ImportModal.tsx
@@ -27,9 +27,9 @@ export function V1ImportModal() {
 	const close = useCloseV1ImportModal();
 	const { data: session } = authClient.useSession();
 	const { activeHostUrl } = useLocalHostService();
-	const organizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const organizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	if (!organizationId) return null;
 
diff --git a/apps/desktop/src/renderer/routes/_authenticated/layout.tsx b/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
index 4717948ec01..dbc28401f70 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
@@ -62,9 +62,9 @@ function AuthenticatedLayout() {
 	const isV2CloudEnabled = useIsV2CloudEnabled();
 
 	const isSignedIn = env.SKIP_ENV_VALIDATION || !!session?.user;
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: session?.session?.activeOrganizationId;
 
 	useAgentHookListener();
 	useUpdateListener();
diff --git a/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx b/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx
index 518fb6b4495..f5562295086 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/providers/CollectionsProvider/CollectionsProvider.tsx
@@ -33,9 +33,9 @@ export function preloadActiveOrganizationCollections(
 export function CollectionsProvider({ children }: { children: ReactNode }) {
 	const { data: session, refetch: refetchSession } = authClient.useSession();
 	const [isSwitching, setIsSwitching] = useState(false);
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: session?.session?.activeOrganizationId;
 
 	const switchOrganization = useCallback(
 		async (organizationId: string) => {
diff --git a/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx b/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx
index ea26b80efa9..9f2b09c8f43 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/providers/LocalHostServiceProvider/LocalHostServiceProvider.tsx
@@ -35,9 +35,9 @@ export function LocalHostServiceProvider({
 	const { mutate: startHostService } =
 		electronTrpc.hostServiceCoordinator.start.useMutation();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: organizations } = useLiveQuery(
 		(q) => q.from({ organizations: collections.organizations }),
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx
index 5a0c0454b7d..0b4567a52e4 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/components/HostsSettingsSidebar/HostsSettingsSidebar.tsx
@@ -30,9 +30,9 @@ export function HostsSettingsSidebar({
 	const collections = useCollections();
 	const { data: session } = authClient.useSession();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: hosts = [] } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx
index 38b070ff699..5586e55e9af 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/hosts/page.tsx
@@ -16,9 +16,9 @@ function HostsIndexPage() {
 	const { data: session } = authClient.useSession();
 	const navigate = useNavigate();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: hosts = [], isReady } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx
index 94f2d8da568..e19226947d5 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/$projectId/page.tsx
@@ -29,9 +29,9 @@ function ProjectDetailPage() {
 	const { data: session } = authClient.useSession();
 	const searchQuery = useSettingsSearchQuery();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: v2Match = [] } = useLiveQuery(
 		(q) =>
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx
index bedd6a8612b..ce7d751ecc4 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/components/ProjectsSettingsSidebar/ProjectsSettingsSidebar.tsx
@@ -31,9 +31,9 @@ export function ProjectsSettingsSidebar({
 	const collections = useCollections();
 	const { data: session } = authClient.useSession();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: groups = [] } =
 		electronTrpc.workspaces.getAllGrouped.useQuery();
diff --git a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx
index 089d2ec66a6..584486bc71c 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/settings/projects/page.tsx
@@ -17,9 +17,9 @@ function ProjectsIndexPage() {
 	const { data: session } = authClient.useSession();
 	const navigate = useNavigate();
 
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: groups = [], isLoading: groupsLoading } =
 		electronTrpc.workspaces.getAllGrouped.useQuery();
diff --git a/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx b/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx
index 10626d1ce1f..fe5b99a03f3 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/setup/project/page.tsx
@@ -26,9 +26,9 @@ function OnboardingProjectPage() {
 	const markSkipped = useOnboardingStore((s) => s.markSkipped);
 
 	const { data: session } = authClient.useSession();
-	const activeOrganizationId =
-		session?.session?.activeOrganizationId ??
-		(env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null);
+	const activeOrganizationId = env.SKIP_ENV_VALIDATION
+		? MOCK_ORG_ID
+		: (session?.session?.activeOrganizationId ?? null);
 
 	const { data: projects = [], isLoading } = useQuery({
 		queryKey: ["onboarding", "v2Projects", activeOrganizationId],
diff --git a/apps/desktop/src/renderer/routes/sign-in/page.tsx b/apps/desktop/src/renderer/routes/sign-in/page.tsx
index 2103e2578b5..c56bba6515f 100644
--- a/apps/desktop/src/renderer/routes/sign-in/page.tsx
+++ b/apps/desktop/src/renderer/routes/sign-in/page.tsx
@@ -18,7 +18,8 @@ export const Route = createFileRoute("/sign-in/")({
 function SignInPage() {
 	const signInMutation = electronTrpc.auth.signIn.useMutation();
 	const { hasLocalToken, isPending, session } = useSessionRecovery();
-	const isLocalProfile = env.SUPERSET_PROFILE === "local";
+	const isLocalProfile =
+		env.NODE_ENV === "development" && env.SUPERSET_PROFILE === "local";
 
 	// Dev bypass: AuthProvider handles auto-sign-in; if session lands, redirect
 	if (env.SKIP_ENV_VALIDATION && session?.user) {
diff --git a/apps/desktop/vite/helpers.ts b/apps/desktop/vite/helpers.ts
index fd4c4c949c0..2aabdb83df9 100644
--- a/apps/desktop/vite/helpers.ts
+++ b/apps/desktop/vite/helpers.ts
@@ -26,7 +26,7 @@ export function defineEnv(
 /**
  * Returns a URL appropriate for the current build:
  *   - the configured `process.env[key]` if set
- *   - the dev fallback in development builds (fresh-clone OSS contributors)
+ *   - the dev fallback in explicit local-profile development builds
  *   - the prod fallback otherwise (hosted production)
  *
  * Avoids fresh-clone OSS dev sessions silently syncing against hosted
@@ -39,7 +39,10 @@ export function devOrProdUrl(
 ): string {
 	const value = process.env[envKey];
 	if (value) return value;
-	return process.env.NODE_ENV === "development" ? devFallback : prodFallback;
+	const isLocalDevelopment =
+		process.env.NODE_ENV === "development" &&
+		process.env.SUPERSET_PROFILE === "local";
+	return isLocalDevelopment ? devFallback : prodFallback;
 }
 
 const RESOURCES_TO_COPY = [
diff --git a/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx b/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
index 75d6b41ec4d..48f13e775a8 100644
--- a/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
+++ b/apps/web/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx
@@ -10,7 +10,10 @@ import { FcGoogle } from "react-icons/fc";
 import { env } from "@/env";
 import { DevSignInButton } from "../../components/DevSignInButton";
 
-const isDev = process.env.NODE_ENV !== "production";
+const isLocalDev =
+	process.env.NODE_ENV !== "production" &&
+	env.NEXT_PUBLIC_API_URL.startsWith("http://localhost:") &&
+	env.NEXT_PUBLIC_WEB_URL.startsWith("http://localhost:");
 
 export default function SignInPage() {
 	const searchParams = useSearchParams();
@@ -69,7 +72,7 @@ export default function SignInPage() {
 				{error && (
 					<p className="text-destructive text-center text-sm">{error}</p>
 				)}
-				{isDev && <DevSignInButton callbackURL={callbackURL} />}
+				{isLocalDev && <DevSignInButton callbackURL={callbackURL} />}
 				<Button
 					variant="outline"
 					disabled={isLoading}
diff --git a/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx b/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
index a5678246ff0..9deee3a5c1d 100644
--- a/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
+++ b/apps/web/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx
@@ -9,7 +9,10 @@ import { FcGoogle } from "react-icons/fc";
 import { env } from "@/env";
 import { DevSignInButton } from "../../components/DevSignInButton";
 
-const isDev = process.env.NODE_ENV !== "production";
+const isLocalDev =
+	process.env.NODE_ENV !== "production" &&
+	env.NEXT_PUBLIC_API_URL.startsWith("http://localhost:") &&
+	env.NEXT_PUBLIC_WEB_URL.startsWith("http://localhost:");
 
 export default function SignUpPage() {
 	const [isLoadingGoogle, setIsLoadingGoogle] = useState(false);
@@ -64,7 +67,9 @@ export default function SignUpPage() {
 				{error && (
 					<p className="text-destructive text-center text-sm">{error}</p>
 				)}
-				{isDev && <DevSignInButton callbackURL={env.NEXT_PUBLIC_WEB_URL} />}
+				{isLocalDev && (
+					<DevSignInButton callbackURL={env.NEXT_PUBLIC_WEB_URL} />
+				)}
 				<Button
 					variant="outline"
 					disabled={isLoading}
diff --git a/packages/auth/src/server.ts b/packages/auth/src/server.ts
index 30353b7454c..400c44bd663 100644
--- a/packages/auth/src/server.ts
+++ b/packages/auth/src/server.ts
@@ -16,6 +16,7 @@ import { PaymentFailedEmail } from "@superset/email/emails/payment-failed";
 import { SubscriptionCancelledEmail } from "@superset/email/emails/subscription-cancelled";
 import { SubscriptionStartedEmail } from "@superset/email/emails/subscription-started";
 import { canInvite, type OrganizationRole } from "@superset/shared/auth";
+import { isLocalProfile } from "@superset/shared/deployment-profile";
 import { getTrustedVercelPreviewOrigins } from "@superset/shared/vercel-preview-origins";
 import { Client } from "@upstash/qstash";
 import { betterAuth } from "better-auth";
@@ -129,12 +130,10 @@ export const auth = betterAuth({
 			generateId: false,
 		},
 	},
-	// Dev-only: email+password is enabled for OSS contributors and
-	// internal devs (NODE_ENV=development). In production builds the
-	// /sign-up/email and /sign-in/email endpoints are disabled — auth
-	// is OAuth-only there. Matches the UI form gating in apps/web.
+	// Local profile only: email+password backs the seeded contributor account.
+	// Internal dev, cloud, preview, and production stay OAuth-only.
 	emailAndPassword: {
-		enabled: process.env.NODE_ENV !== "production",
+		enabled: isLocalProfile(),
 		autoSignIn: true,
 	},
 	socialProviders,
diff --git a/packages/shared/src/deployment-profile.test.ts b/packages/shared/src/deployment-profile.test.ts
index 62dff7e2f5b..9f85c34b54a 100644
--- a/packages/shared/src/deployment-profile.test.ts
+++ b/packages/shared/src/deployment-profile.test.ts
@@ -17,7 +17,7 @@ describe("deployment profile resolution", () => {
 	});
 
 	it("uses explicit local profile for lenient contributor development", () => {
-		const env = { SUPERSET_PROFILE: "local" };
+		const env = { NODE_ENV: "development", SUPERSET_PROFILE: "local" };
 
 		expect(getDeploymentProfile(env)).toBe("local");
 		expect(isLocalProfile(getDeploymentProfile(env))).toBe(true);
@@ -25,6 +25,14 @@ describe("deployment profile resolution", () => {
 		expect(shouldSkipEnvValidation(env)).toBe(true);
 	});
 
+	it("does not allow local profile behavior in production runtime", () => {
+		const env = { NODE_ENV: "production", SUPERSET_PROFILE: "local" };
+
+		expect(getDeploymentProfile(env)).toBe("internal");
+		expect(isLocalProfile(getDeploymentProfile(env))).toBe(false);
+		expect(shouldSkipEnvValidation(env)).toBe(false);
+	});
+
 	it("uses ci only when no explicit or cloud profile is present", () => {
 		expect(getDeploymentProfile({ CI: "true" })).toBe("ci");
 		expect(getDeploymentProfile({ CI: "1" })).toBe("ci");
@@ -51,11 +59,17 @@ describe("deployment profile resolution", () => {
 		);
 	});
 
-	it("allows SKIP_ENV_VALIDATION as an explicit strict-profile escape hatch", () => {
-		const env = { SKIP_ENV_VALIDATION: "1" };
+	it("allows SKIP_ENV_VALIDATION only outside production runtime", () => {
+		const env = { NODE_ENV: "development", SKIP_ENV_VALIDATION: "1" };
 
 		expect(getDeploymentProfile(env)).toBe("internal");
 		expect(shouldSkipEnvValidation(env)).toBe(true);
+		expect(
+			shouldSkipEnvValidation({
+				NODE_ENV: "production",
+				SKIP_ENV_VALIDATION: "1",
+			}),
+		).toBe(false);
 	});
 
 	it("throws on invalid explicit profiles", () => {
diff --git a/packages/shared/src/deployment-profile.ts b/packages/shared/src/deployment-profile.ts
index dc6b7b39f43..001350d2ee8 100644
--- a/packages/shared/src/deployment-profile.ts
+++ b/packages/shared/src/deployment-profile.ts
@@ -42,7 +42,12 @@ export function getDeploymentProfile(
 ): DeploymentProfile {
 	if (isTruthyFlag(envSource.VERCEL) || envSource.VERCEL_ENV) return "cloud";
 	const explicitProfile = getExplicitProfile(envSource);
-	if (explicitProfile) return explicitProfile;
+	if (explicitProfile) {
+		if (explicitProfile === "local" && envSource.NODE_ENV === "production") {
+			return "internal";
+		}
+		return explicitProfile;
+	}
 	if (isTruthyFlag(envSource.CI)) return "ci";
 	return "internal";
 }
@@ -62,8 +67,11 @@ export function isLocalProfile(
 export function shouldSkipEnvValidation(
 	envSource: Record<string, string | undefined> = process.env,
 ): boolean {
+	const profile = getDeploymentProfile(envSource);
 	return (
-		!isStrictProfile(getDeploymentProfile(envSource)) ||
-		isTruthyFlag(envSource.SKIP_ENV_VALIDATION)
+		profile === "ci" ||
+		profile === "local" ||
+		(envSource.NODE_ENV !== "production" &&
+			isTruthyFlag(envSource.SKIP_ENV_VALIDATION))
 	);
 }

From d69de5dafe8ae6bf8b31785169fd12970da22bfd Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Wed, 20 May 2026 23:24:41 -0700
Subject: [PATCH 22/28] Keep unsigned canary builds out of update feed

---
 .github/workflows/release-desktop-canary.yml | 4 ++--
 scripts/release-canary.sh                    | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release-desktop-canary.yml b/.github/workflows/release-desktop-canary.yml
index 091456eb5fd..f3714c98768 100644
--- a/.github/workflows/release-desktop-canary.yml
+++ b/.github/workflows/release-desktop-canary.yml
@@ -12,7 +12,7 @@ on:
         type: boolean
         default: false
       skip_signing:
-        description: "Build macOS artifacts without code signing or notarization"
+        description: "Build unsigned macOS artifacts for manual testing only; does not update the canary release feed"
         required: false
         type: boolean
         default: false
@@ -88,7 +88,7 @@ jobs:
   release:
     name: Update Canary Release
     needs: [check-changes, build]
-    if: needs.check-changes.outputs.should_build == 'true'
+    if: needs.check-changes.outputs.should_build == 'true' && github.event.inputs.skip_signing != 'true'
     runs-on: ubuntu-latest
 
     steps:
diff --git a/scripts/release-canary.sh b/scripts/release-canary.sh
index 96d5ac5b6a9..4367f410399 100755
--- a/scripts/release-canary.sh
+++ b/scripts/release-canary.sh
@@ -6,7 +6,8 @@ usage() {
 Usage: bun run release:canary -- [--skip-signing] [commit]
 
 Options:
-  --skip-signing        Build the macOS canary artifact without code signing or notarization.
+  --skip-signing        Build unsigned macOS artifacts for manual testing only.
+                        Unsigned builds do not update the desktop-canary release feed.
   -h, --help            Show this help message.
 
 Examples:

From ebe6f633b4fa65f8e8826b4dedd49d837aa948b7 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Thu, 21 May 2026 09:59:22 -0700
Subject: [PATCH 23/28] Preserve canary desktop user data path

---
 apps/desktop/electron-builder.canary.ts | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/apps/desktop/electron-builder.canary.ts b/apps/desktop/electron-builder.canary.ts
index 518a563f15c..8cdac856a7b 100644
--- a/apps/desktop/electron-builder.canary.ts
+++ b/apps/desktop/electron-builder.canary.ts
@@ -22,9 +22,6 @@ const config: Configuration = {
 	...baseConfig,
 	appId: "com.superset.desktop.canary",
 	productName,
-	extraMetadata: {
-		productName,
-	},
 
 	publish: {
 		provider: "github",

From d41a728c7a38e9b12703aa32399cbe17d5eb09ee Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Thu, 21 May 2026 10:03:10 -0700
Subject: [PATCH 24/28] Trim redundant canary release metadata

---
 .github/workflows/release-desktop-canary.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/release-desktop-canary.yml b/.github/workflows/release-desktop-canary.yml
index f3714c98768..673119b71d0 100644
--- a/.github/workflows/release-desktop-canary.yml
+++ b/.github/workflows/release-desktop-canary.yml
@@ -155,7 +155,6 @@ jobs:
             - Commit: ${{ github.sha }}
             - Short SHA: ${{ needs.check-changes.outputs.short_sha }}
             - Built: ${{ needs.check-changes.outputs.build_time }}
-            - Code signing: ${{ github.event.inputs.skip_signing == 'true' && 'skipped' || 'enabled' }}
 
             ⚠️ This build is for internal testing only and may be unstable.
           prerelease: true

From 32035f6b4151621434892c1b7f84d85e3d8400ad Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Thu, 21 May 2026 10:44:55 -0700
Subject: [PATCH 25/28] Clean up local dev notes and boot logging

---
 apps/api/src/lib/boot-summary.ts  |  4 +---
 docs/LOCAL_DEVELOPMENT.md         |  2 +-
 plans/20260515-oss-local-setup.md | 38 +++++++++++++++----------------
 3 files changed, 21 insertions(+), 23 deletions(-)

diff --git a/apps/api/src/lib/boot-summary.ts b/apps/api/src/lib/boot-summary.ts
index e8ecfc44ad7..406022ae7b0 100644
--- a/apps/api/src/lib/boot-summary.ts
+++ b/apps/api/src/lib/boot-summary.ts
@@ -11,13 +11,11 @@ export function logBootSummary(): void {
 	logged = true;
 
 	const profile = getDeploymentProfile();
-	const missing = getMissingIntegrations();
-
 	if (isStrictProfile(profile)) {
-		console.log(`[superset] profile=${profile} (strict)`);
 		return;
 	}
 
+	const missing = getMissingIntegrations();
 	console.log(`[superset] profile=${profile} (lenient)`);
 	if (missing.length === 0) {
 		console.log("[superset] all integrations configured");
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index c3c15cd9f66..8d6178e6ddc 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -92,7 +92,7 @@ For programmatic monitoring (or to confirm a key took effect), hit `GET /api/hea
 { "ok": true, "profile": "local", "integrations": { "stripe": "missing", ... } }
 ```
 
-For the web app (`http://localhost:4640`), the sign-in and sign-up pages render a dev-only email/password form when `NODE_ENV !== "production"`. Use the same credentials.
+For the web app (`http://localhost:4640`), the sign-in and sign-up pages render a dev-only email/password form when running a non-production build against local API/web URLs. Use the same credentials.
 
 ## What works locally
 
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
index 09f17af7365..ba7a0864356 100644
--- a/plans/20260515-oss-local-setup.md
+++ b/plans/20260515-oss-local-setup.md
@@ -1,6 +1,6 @@
-# OSS Local Setup — Complete Record
+# OSS Local Setup — Implementation Notes
 
-Authoritative design record for PR [#4616](https://github.com/superset-sh/superset/pull/4616). Contributor-facing setup instructions live in [docs/LOCAL_DEVELOPMENT.md](../docs/LOCAL_DEVELOPMENT.md).
+Implementation notes for PR [#4616](https://github.com/superset-sh/superset/pull/4616). Contributor-facing setup instructions live in [docs/LOCAL_DEVELOPMENT.md](../docs/LOCAL_DEVELOPMENT.md), which is the source of truth for the final workflow.
 
 ## Goal
 
@@ -40,8 +40,10 @@ Resolution order in `getDeploymentProfile()` (most-trusted wins):
 
 ```ts
 if (env.VERCEL === "1" || env.VERCEL_ENV) return "cloud";
-if (env.SUPERSET_PROFILE === "local") return "local";
-if (env.CI === "true")         return "ci";
+const explicit = getExplicitProfile(env);
+if (explicit === "local" && env.NODE_ENV === "production") return "internal";
+if (explicit) return explicit;
+if (env.CI === "true" || env.CI === "1") return "ci";
 return "internal";
 ```
 
@@ -63,7 +65,7 @@ const skipValidation = shouldSkipEnvValidation();
 
 ### Auth
 
-- **`packages/auth/src/server.ts`** — `emailAndPassword: { enabled: NODE_ENV !== "production", autoSignIn: true }`. Direct credential endpoints removed in prod builds. `afterCreateOrganization` hook gates Stripe customer creation on `env.STRIPE_SECRET_KEY` presence; `seedDefaultStatuses` always runs so OSS users complete org provisioning cleanly. OAuth providers register conditionally on their `*_CLIENT_ID`.
+- **`packages/auth/src/server.ts`** — `emailAndPassword: { enabled: isLocalProfile(), autoSignIn: true }`. Direct credential endpoints are local-profile only. `afterCreateOrganization` hook gates Stripe customer creation on `env.STRIPE_SECRET_KEY` presence; `seedDefaultStatuses` always runs so OSS users complete org provisioning cleanly. OAuth providers register conditionally on their `*_CLIENT_ID`.
 - **`packages/auth/src/lib/resend.ts`** — `Proxy` lazy-init with batch + emails console fallback when `RESEND_API_KEY` empty. Better Auth's `sendEmail` hook writes to terminal instead of crashing.
 - **`packages/auth/src/stripe.ts`** — `Proxy` lazy-init. Throws "Stripe not configured" only when a billing operation is exercised.
 - **`packages/trpc/src/router/support/support.ts`** — same lazy-init Proxy pattern for the support email path.
@@ -72,27 +74,27 @@ const skipValidation = shouldSkipEnvValidation();
 
 - **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — fired once during `app.whenReady()` when `isLocalProfile()` is true. Polls `/api/auth/ok` with 1s interval × 60s timeout (auto-sign-in survives the race against API startup), then POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if missing). Persists the token via the same `saveToken()` that OAuth uses. Renderer stays prod-pure.
 - **`apps/desktop/src/main/index.ts`** — calls `void ensureDevAuthToken()` (fire-and-forget) so the window opens immediately. `AuthProvider`'s `onTokenChanged` subscription re-hydrates when the token lands. Also exposes Chrome DevTools Protocol on `localhost:9333` in the local profile for headless verification.
-- **`apps/desktop/src/main/env.main.ts`** — env defaults switch to localhost in dev builds (`NODE_ENV=development`) so a fresh-clone session never silently points main-process clients at hosted production. Profile check inlined here (rather than imported from `@superset/shared`) because `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time using Node's ESM loader, which can't transform `.ts` files from sibling workspace packages.
+- **`apps/desktop/src/main/env.main.ts`** — env defaults switch to localhost only in explicit local-profile dev builds (`NODE_ENV=development` and `SUPERSET_PROFILE=local`) so a fresh-clone session never silently points main-process clients at hosted production. Profile check inlined here (rather than imported from `@superset/shared`) because `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time using Node's ESM loader, which can't transform `.ts` files from sibling workspace packages.
 
 ### Desktop renderer
 
-- **`apps/desktop/src/renderer/env.renderer.ts`** — env defaults switch to localhost in dev builds for `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WEB_URL`, `NEXT_PUBLIC_ELECTRIC_URL`, `RELAY_URL`. Fresh-clone renderer never syncs against hosted Electric.
+- **`apps/desktop/src/renderer/env.renderer.ts`** — env defaults switch to localhost only in explicit local-profile dev builds for `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WEB_URL`, `NEXT_PUBLIC_ELECTRIC_URL`, `RELAY_URL`. Fresh-clone renderer never syncs against hosted Electric.
 - **`apps/desktop/src/renderer/routes/_authenticated/.../*`** (16 files) — flipped `env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : session.activeOrganizationId` to `session.activeOrganizationId ?? (env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null)`. Prefer real session, fall back to mock only when there is no session. Fixed the "Host service not available" toast caused by the renderer querying host-service by the fake org ID while host-service spawned for the real auto-signed-in admin org.
 
 ### Build pipeline
 
-- **`apps/desktop/electron.vite.config.ts`** + **`apps/desktop/vite/helpers.ts`** — added `devOrProdUrl()` helper that returns `process.env[key]` if set, else a dev-vs-prod fallback based on `NODE_ENV`. Used in `define` blocks for main + renderer `process.env` replacements and in `htmlEnvTransformPlugin` for `%NEXT_PUBLIC_*%` placeholders in `index.html`. Builds default to localhost-friendly URLs in dev mode.
+- **`apps/desktop/electron.vite.config.ts`** + **`apps/desktop/vite/helpers.ts`** — added `devOrProdUrl()` helper that returns `process.env[key]` if set, else a localhost fallback only for explicit local-profile dev builds. Used in `define` blocks for main + renderer `process.env` replacements and in `htmlEnvTransformPlugin` for `%NEXT_PUBLIC_*%` placeholders in `index.html`.
 
 ### Web app
 
-- **`apps/web/src/app/(auth)/components/DevAuthForm/`** — email/password form, gated `NODE_ENV !== "production"`. Prefilled with seed credentials so contributors click "Sign in" once.
+- **`apps/web/src/app/(auth)/components/DevSignInButton/`** — email/password sign-in action, gated to non-production builds using local API/web URLs. Prefilled with seed credentials so contributors click "Sign in" once.
 - **`apps/web/src/app/(auth)/sign-in/.../page.tsx`** + **`sign-up/.../page.tsx`** — wire the form.
 
 ### Telemetry / observability
 
 - **`apps/api/src/lib/analytics.ts`** + **`packages/trpc/src/lib/analytics.ts`** — PostHog `Proxy` lazy-init returning a no-op surface (`capture`, `getFeatureFlag`, etc.) when `NEXT_PUBLIC_POSTHOG_KEY` is missing.
-- **`apps/api/src/lib/boot-summary.ts`** — one-time API startup log printing every disabled integration and the env var to enable it. Visible to contributors so degradation is never silent.
-- **`apps/api/src/app/api/health/route.ts`** — `GET /api/health` returns `{ ok, profile, integrations: { stripe: "configured" | "missing", … } }` for prod monitoring + contributor sanity checks.
+- **`apps/api/src/lib/boot-summary.ts`** — one-time API startup log in lenient profiles, printing every disabled integration and the env var to enable it. Visible to contributors so degradation is never silent, while strict prod/internal boot stays quiet.
+- **`apps/api/src/app/api/health/route.ts`** — `GET /api/health` returns `{ ok: true }` in strict profiles and adds `{ profile, integrations: { stripe: "configured" | "missing", … } }` in lenient profiles for contributor sanity checks.
 
 ### Plumbing
 
@@ -212,7 +214,7 @@ I shipped the deployment-profile changes without checking `gh pr checks 4616`. T
 
 | Commit | Theme |
 |---|---|
-| [`04130c0`](https://github.com/superset-sh/superset/pull/4616/commits/04130c0) | Core OSS path: DB driver swap, lazy-init guards (Stripe/Resend/PostHog), Better Auth email/password, desktop dev auto-sign-in, 17-file MOCK_ORG_ID priority fix, web app DevAuthForm, `db:seed:dev`, CDP for verification, docs |
+| [`04130c0`](https://github.com/superset-sh/superset/pull/4616/commits/04130c0) | Core OSS path: DB driver swap, lazy-init guards (Stripe/Resend/PostHog), Better Auth email/password, desktop dev auto-sign-in, MOCK_ORG_ID priority fix, web app dev sign-in, `db:seed:dev`, CDP for verification, docs |
 | [`2b609b5`](https://github.com/superset-sh/superset/pull/4616/commits/2b609b5) | Deployment profiles + boot summary + `/api/health` endpoint |
 | [`f3c76b9`](https://github.com/superset-sh/superset/pull/4616/commits/f3c76b9) | Flipped discriminator (strict by default, local profile opts into lenient) |
 | [`101cd30`](https://github.com/superset-sh/superset/pull/4616/commits/101cd30) | Added `ci` profile (GitHub Actions auto-detect) |
@@ -260,13 +262,11 @@ Local CI reproduction:
 - `bun run --cwd apps/desktop typecheck` — clean
 - `bun turbo run build --filter=@superset/desktop` — succeeds
 
-## What's still deferred (honest TODO list)
+## Follow-ups
 
 These are real follow-ups, none of them blocking the OSS path from working today:
 
-- **`.env.example` with working defaults** — README says "edit DATABASE_URL + BETTER_AUTH_SECRET" without telling contributors the values. Pre-fill `postgres://superset:superset@localhost:5433/superset` + a sentinel `BETTER_AUTH_SECRET=dev_secret_not_for_production_*` and move optional integration keys to a `# OPTIONAL` block.
-- **`bun setup` orchestrator** — current contributor flow is 6 commands. A `bun setup` wrapping `docker compose up`, `cp .env.example .env` if missing, `bun install`, `bun run db:migrate`, copy `.dev.vars`, with idempotency + friendly errors would collapse it to two: `bun setup && bun dev`.
-- **Full integration crash audit** — Stripe, Resend, PostHog, trpc-support-Resend are wrapped. GitHub App (`@octokit/app`), Freestyle, Linear, Slack, QStash signing keys, Anthropic (`@anthropic-ai/sdk`), Blob (`@vercel/blob`) may still crash at import in the local profile. Mechanical `grep -rn "new \w\+(.*env\." packages apps` survey.
+- **Complete integration crash audit** — Stripe, Resend, PostHog, support email, QStash queue creation, and the common OAuth providers are guarded. Less-used integrations still deserve a follow-up import-time audit.
 - **Mailpit instead of console-log emails** — Better Auth's `sendEmail` falls back to stdout. Mailpit container would give contributors a clickable UI at `localhost:8025`.
 - **CI fresh-clone smoke test** — without one, the OSS path silently rots the next time someone adds a crash-on-import integration. A GitHub Actions job that does `git clone` in a fresh runner, follows the README, hits `/api/auth/ok`, fails if anything red.
 - **Per-integration group `.refine()` validation** — Formbricks pattern. E.g. if `STRIPE_SECRET_KEY` is set then `STRIPE_WEBHOOK_SECRET` must also be set. Catches half-configured prod deploys.
@@ -310,7 +310,7 @@ These are real follow-ups, none of them blocking the OSS path from working today
 ┌──────────────────────────────────────────────────────────────┐
 │  bun dev (with SUPERSET_PROFILE=local)                         │
 │                                                                │
-│  apps/web      :4640  ─ Next.js, DevAuthForm visible          │
+│  apps/web      :4640  ─ Next.js, local DevSignInButton visible│
 │  apps/api      :4641  ─ Better Auth + tRPC, /api/health       │
 │                                                                │
 │  apps/desktop:                                                 │
@@ -336,7 +336,7 @@ These are real follow-ups, none of them blocking the OSS path from working today
 
 | Profile      | `skipValidation` | Boot summary    | `/api/health` shows         | Sign-in path                                  |
 |--------------|------------------|------------------|------------------------------|------------------------------------------------|
-| `cloud`      | false (strict)   | `profile=cloud (strict)`    | `profile: "cloud"`        | OAuth (email/password disabled in prod build)  |
-| `internal`   | false (strict)   | `profile=internal (strict)` | `profile: "internal"`     | OAuth + dev email/password form (NODE_ENV=dev) |
+| `cloud`      | false (strict)   | none                         | `{ ok: true }`            | OAuth                                          |
+| `internal`   | false (strict)   | none                         | `{ ok: true }`            | OAuth                                          |
 | `ci`         | true (lenient)   | `profile=ci (lenient)`      | `profile: "ci"`           | n/a (build/test job, no runtime auth)          |
 | `local`      | true (lenient)   | lists disabled features     | `profile: "local"`        | dev auto-sign-in + dev email/password form     |

From 2b6ff9e29c36c804ee4415b10b31b067d3dcd2f4 Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Thu, 21 May 2026 10:57:55 -0700
Subject: [PATCH 26/28] Trim unrelated Linear callback changes

---
 .../api/integrations/linear/callback/route.ts | 86 ++++++-------------
 1 file changed, 26 insertions(+), 60 deletions(-)

diff --git a/apps/api/src/app/api/integrations/linear/callback/route.ts b/apps/api/src/app/api/integrations/linear/callback/route.ts
index 3a770bd097d..f92656f6fa4 100644
--- a/apps/api/src/app/api/integrations/linear/callback/route.ts
+++ b/apps/api/src/app/api/integrations/linear/callback/route.ts
@@ -1,17 +1,13 @@
 import { LinearClient } from "@linear/sdk";
 import { db } from "@superset/db/client";
-import { integrationConnections, members, users } from "@superset/db/schema";
+import { integrationConnections, members } from "@superset/db/schema";
 import { linearTokenResponseSchema } from "@superset/trpc/integrations/linear";
-import { and, eq, isNull, ne } from "drizzle-orm";
+import { and, eq } from "drizzle-orm";
 
 import { env } from "@/env";
 import { verifySignedState } from "@/lib/oauth-state";
 import { qstash, requireQstash } from "@/lib/qstash";
 
-const UNIQUE_VIOLATION = "23505";
-const ACTIVE_LINKAGE_INDEX =
-	"integration_connections_provider_external_org_active_unique";
-
 export async function GET(request: Request) {
 	const url = new URL(request.url);
 	const code = url.searchParams.get("code");
@@ -86,65 +82,35 @@ export async function GET(request: Request) {
 
 	const tokenExpiresAt = new Date(Date.now() + tokenData.expires_in * 1000);
 
-	const [conflict] = await db
-		.select({ email: users.email })
-		.from(integrationConnections)
-		.innerJoin(users, eq(users.id, integrationConnections.connectedByUserId))
-		.where(
-			and(
-				eq(integrationConnections.provider, "linear"),
-				eq(integrationConnections.externalOrgId, linearOrg.id),
-				isNull(integrationConnections.disconnectedAt),
-				ne(integrationConnections.organizationId, organizationId),
-			),
-		)
-		.limit(1);
-
-	if (conflict) {
-		return Response.redirect(
-			`${env.NEXT_PUBLIC_WEB_URL}/integrations/linear?error=workspace_already_linked&owner=${encodeURIComponent(conflict.email)}`,
-		);
-	}
-
-	try {
-		await db
-			.insert(integrationConnections)
-			.values({
-				organizationId,
-				connectedByUserId: userId,
-				provider: "linear",
+	await db
+		.insert(integrationConnections)
+		.values({
+			organizationId,
+			connectedByUserId: userId,
+			provider: "linear",
+			accessToken: tokenData.access_token,
+			refreshToken: tokenData.refresh_token,
+			tokenExpiresAt,
+			externalOrgId: linearOrg.id,
+			externalOrgName: linearOrg.name,
+		})
+		.onConflictDoUpdate({
+			target: [
+				integrationConnections.organizationId,
+				integrationConnections.provider,
+			],
+			set: {
 				accessToken: tokenData.access_token,
 				refreshToken: tokenData.refresh_token,
 				tokenExpiresAt,
+				disconnectedAt: null,
+				disconnectReason: null,
 				externalOrgId: linearOrg.id,
 				externalOrgName: linearOrg.name,
-			})
-			.onConflictDoUpdate({
-				target: [
-					integrationConnections.organizationId,
-					integrationConnections.provider,
-				],
-				set: {
-					accessToken: tokenData.access_token,
-					refreshToken: tokenData.refresh_token,
-					tokenExpiresAt,
-					disconnectedAt: null,
-					disconnectReason: null,
-					externalOrgId: linearOrg.id,
-					externalOrgName: linearOrg.name,
-					connectedByUserId: userId,
-					updatedAt: new Date(),
-				},
-			});
-	} catch (error) {
-		const e = error as { code?: string; constraint?: string };
-		if (e.code === UNIQUE_VIOLATION && e.constraint === ACTIVE_LINKAGE_INDEX) {
-			return Response.redirect(
-				`${env.NEXT_PUBLIC_WEB_URL}/integrations/linear?error=workspace_already_linked`,
-			);
-		}
-		throw error;
-	}
+				connectedByUserId: userId,
+				updatedAt: new Date(),
+			},
+		});
 
 	try {
 		const syncUrl = `${env.NEXT_PUBLIC_API_URL}/api/integrations/linear/jobs/initial-sync`;

From 380b5d7f7bac03d936a971c815eaea082bc3160c Mon Sep 17 00:00:00 2001
From: Kiet Ho <hoakiet98@gmail.com>
Date: Thu, 21 May 2026 11:07:01 -0700
Subject: [PATCH 27/28] Remove nonessential local dev leftovers

---
 .env.example                           |   3 +-
 .gitignore                             |   6 -
 apps/desktop/src/main/index.ts         |   8 -
 docs/LOCAL_DEVELOPMENT.md              |   1 -
 package.json                           |   1 -
 packages/db/package.json               |   1 -
 packages/db/src/seed-dev.ts            |  80 ------
 packages/shared/src/dev-credentials.ts |   3 +-
 plans/20260515-oss-local-setup.md      | 342 -------------------------
 9 files changed, 2 insertions(+), 443 deletions(-)
 delete mode 100644 packages/db/src/seed-dev.ts
 delete mode 100644 plans/20260515-oss-local-setup.md

diff --git a/.env.example b/.env.example
index 950ffbb19e1..2698a6b4725 100644
--- a/.env.example
+++ b/.env.example
@@ -91,8 +91,7 @@ BLOB_READ_WRITE_TOKEN=
 # -----------------------------------------------------------------------------
 # PostHog Analytics (Local Dev)
 # -----------------------------------------------------------------------------
-NEXT_PUBLIC_POSTHOG_KEY=phc_local_dev_disabled
-NEXT_PUBLIC_POSTHOG_HOST=https://us.posthog.com
+NEXT_PUBLIC_POSTHOG_KEY=
 POSTHOG_API_KEY=
 POSTHOG_PROJECT_ID=
 
diff --git a/.gitignore b/.gitignore
index 2d725174d2d..bce6f530372 100644
--- a/.gitignore
+++ b/.gitignore
@@ -94,9 +94,3 @@ superset-dev-data/
 
 # Local-only plans (not tracked)
 plans/local/
-
-# Per-developer Claude Code state (worktree gitlinks)
-.claude/worktrees/
-
-# Local-only spec drafts / reviews
-.spec/
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 41ddaadff4d..29513a39ed3 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -1,7 +1,6 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { settings } from "@superset/local-db";
-import { isLocalProfile } from "@superset/shared/deployment-profile";
 import {
 	app,
 	BrowserWindow,
@@ -57,13 +56,6 @@ import { MainWindow } from "./windows/main";
 console.log("[main] Local database ready:", !!localDb);
 const IS_DEV = process.env.NODE_ENV === "development";
 
-// Local profile only: expose Chrome DevTools Protocol for headless testing
-// (e.g. import/host-service checks). Skip in internal / cloud profiles.
-if (IS_DEV && isLocalProfile()) {
-	app.commandLine.appendSwitch("remote-debugging-port", "9333");
-	app.commandLine.appendSwitch("remote-allow-origins", "*");
-}
-
 void applyShellEnvToProcess().catch((error) => {
 	console.error("[main] Failed to apply shell environment:", error);
 });
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 8d6178e6ddc..4fbbae46a79 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -152,4 +152,3 @@ bun setup:local
 - **DB driver swap** — `packages/db/src/client.ts` detects whether `DATABASE_URL` is a Neon host (`*.neon.tech`, `*.neon.build`) and uses Drizzle's `neon-http` adapter for cloud, or `node-postgres` for any other Postgres (including the local Docker one).
 - **Dev auto-sign-in** — `apps/desktop/src/main/lib/dev-auto-sign-in.ts` runs once during `app.whenReady()` only in the `local` profile. POSTs to `/api/auth/sign-in/email` (auto-signs-up if user doesn't exist), persists the token via the same `saveToken()` that OAuth uses. The renderer doesn't know dev mode exists.
 - **Renderer organization selection** — pages prefer `session.activeOrganizationId` from Better Auth, falling back to `MOCK_ORG_ID` only if there's no session at all. Make sure new code that needs `activeOrganizationId` follows this same priority (real session first).
-- **CDP for headless tests** — in the `local` profile, the desktop main process exposes Chrome DevTools Protocol on `localhost:9333`. Useful for scripted UI checks (`curl http://localhost:9333/json/list`).
diff --git a/package.json b/package.json
index 16d3ec74f64..83ba8fd70ad 100644
--- a/package.json
+++ b/package.json
@@ -39,7 +39,6 @@
 		"release:canary": "./scripts/release-canary.sh",
 		"db:push": "bun run --cwd packages/db push",
 		"db:migrate": "bun run --cwd packages/db migrate",
-		"db:seed:dev": "bun run --cwd packages/db seed:dev",
 		"db:generate:desktop": "bun run --cwd packages/local-db generate"
 	},
 	"type": "module",
diff --git a/packages/db/package.json b/packages/db/package.json
index 5b59660c4fe..328d2885deb 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -37,7 +37,6 @@
 		"clean": "git clean -xdf .cache .turbo dist node_modules",
 		"push": "drizzle-kit push",
 		"migrate": "drizzle-kit migrate",
-		"seed:dev": "bun run src/seed-dev.ts",
 		"studio": "drizzle-kit studio",
 		"typecheck": "tsc --noEmit --emitDeclarationOnly false"
 	},
diff --git a/packages/db/src/seed-dev.ts b/packages/db/src/seed-dev.ts
deleted file mode 100644
index e111342f8f3..00000000000
--- a/packages/db/src/seed-dev.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-	DEV_EMAIL as DEV_ADMIN_EMAIL,
-	DEV_NAME as DEV_ADMIN_NAME,
-	DEV_PASSWORD as DEV_ADMIN_PASSWORD,
-} from "@superset/shared/dev-credentials";
-import { config } from "dotenv";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-config({ path: path.resolve(__dirname, "../../../.env"), quiet: true });
-const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
-
-function requireLocalUrl(value: string, label: string): URL {
-	const url = new URL(value);
-	if (!LOCAL_HOSTS.has(url.hostname)) {
-		console.error(
-			`FATAL: db:seed refuses to run against non-localhost ${label}: ${url.hostname}`,
-		);
-		process.exit(1);
-	}
-	return url;
-}
-
-async function main() {
-	if (process.env.NODE_ENV === "production") {
-		console.error("FATAL: db:seed refuses to run in production");
-		process.exit(1);
-	}
-
-	const dbUrl = process.env.DATABASE_URL;
-	if (!dbUrl) {
-		console.error("FATAL: DATABASE_URL not set");
-		process.exit(1);
-	}
-
-	requireLocalUrl(dbUrl, "database host");
-
-	const apiUrl = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4641";
-	requireLocalUrl(apiUrl, "API host");
-	const endpoint = `${apiUrl}/api/auth/sign-up/email`;
-
-	console.log(`Seeding dev admin via ${endpoint}`);
-
-	const res = await fetch(endpoint, {
-		method: "POST",
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify({
-			email: DEV_ADMIN_EMAIL,
-			password: DEV_ADMIN_PASSWORD,
-			name: DEV_ADMIN_NAME,
-		}),
-	}).catch((err) => {
-		console.error(`FATAL: could not reach ${apiUrl} — is the API running?`);
-		console.error(err.message);
-		process.exit(1);
-	});
-
-	if (res.status === 200) {
-		console.log(`✓ Created ${DEV_ADMIN_EMAIL} / ${DEV_ADMIN_PASSWORD}`);
-		return;
-	}
-
-	const body = (await res.json().catch(() => ({}))) as {
-		code?: string;
-		message?: string;
-	};
-
-	if (body.code === "USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL") {
-		console.log(
-			`✓ ${DEV_ADMIN_EMAIL} already exists (password: ${DEV_ADMIN_PASSWORD})`,
-		);
-		return;
-	}
-
-	console.error(`FATAL: sign-up returned ${res.status}: ${body.message ?? ""}`);
-	process.exit(1);
-}
-
-main();
diff --git a/packages/shared/src/dev-credentials.ts b/packages/shared/src/dev-credentials.ts
index 565af54fbb9..2af56a86685 100644
--- a/packages/shared/src/dev-credentials.ts
+++ b/packages/shared/src/dev-credentials.ts
@@ -1,6 +1,5 @@
 /**
- * Seeded local-dev account used by:
- * - packages/db seed-dev to insert the user
+ * Local-dev account used by:
  * - apps/desktop LocalDevAuthForm + dev-auto-sign-in to authenticate against it
  * - apps/web DevSignInButton to authenticate against it
  *
diff --git a/plans/20260515-oss-local-setup.md b/plans/20260515-oss-local-setup.md
deleted file mode 100644
index ba7a0864356..00000000000
--- a/plans/20260515-oss-local-setup.md
+++ /dev/null
@@ -1,342 +0,0 @@
-# OSS Local Setup — Implementation Notes
-
-Implementation notes for PR [#4616](https://github.com/superset-sh/superset/pull/4616). Contributor-facing setup instructions live in [docs/LOCAL_DEVELOPMENT.md](../docs/LOCAL_DEVELOPMENT.md), which is the source of truth for the final workflow.
-
-## Goal
-
-A contributor cloning Superset from GitHub can boot the full web + API + Electric + electric-proxy + Caddy + desktop stack against a local Postgres in Docker, **without Neon, OAuth, Stripe, Resend, GitHub App, Linear, Slack, QStash, Upstash, PostHog, Sentry, Freestyle, or any other cloud-service credentials**. The internal team's fail-fast workflow stays unchanged, and production stays strictly validated.
-
-## Requirements
-
-Three audiences with different expectations:
-
-1. **OSS contributor (fresh GitHub clone)**
-   - Has Docker + Bun, nothing else
-   - Wants `git clone && SUPERSET_PROFILE=local bun dev` to land them in a working app, signed in
-   - Features that need cloud keys should degrade visibly, never crash boot
-   - Must not silently sync against hosted production endpoints
-
-2. **Internal team dev (existing workflow)**
-   - Uses `.superset/setup.sh` to provision per-worktree Neon branches + real cloud keys
-   - Same fail-fast behavior they have today on missing keys
-   - No new flags to type, no shell-config changes, no documentation to memorize
-
-3. **Production (Vercel + self-host)**
-   - Strict env validation: missing required key → deploy fails before serving traffic
-   - All visibility/observability surfaces report what's actually configured
-
-## Final design — four deployment profiles
-
-`packages/shared/src/deployment-profile.ts`:
-
-| Profile     | Trigger                                  | Validation | Notes |
-|-------------|------------------------------------------|------------|-------|
-| `cloud`     | `VERCEL=1` or `VERCEL_ENV` (set by Vercel) | Strict     | Vercel deploy/build context |
-| `local`     | `SUPERSET_PROFILE=local`                 | Lenient    | Explicit local contributor opt-in |
-| `ci`        | `CI=true` (auto by GH Actions et al.)    | Lenient    | Build/lint/test don't need prod secrets |
-| `internal`  | default                                  | Strict     | Covers internal team dev + self-hosted prod |
-
-Resolution order in `getDeploymentProfile()` (most-trusted wins):
-
-```ts
-if (env.VERCEL === "1" || env.VERCEL_ENV) return "cloud";
-const explicit = getExplicitProfile(env);
-if (explicit === "local" && env.NODE_ENV === "production") return "internal";
-if (explicit) return explicit;
-if (env.CI === "true" || env.CI === "1") return "ci";
-return "internal";
-```
-
-Each env schema (`apps/api`, `apps/web`, `apps/admin`, `apps/marketing`, `apps/docs`, `apps/relay`, `apps/desktop/src/main/env.main`, `packages/trpc`) computes:
-
-```ts
-const skipValidation = shouldSkipEnvValidation();
-```
-
-`SKIP_ENV_VALIDATION=1` remains a build-time escape hatch (Docker preview builds, etc.) — not the primary discriminator.
-
-## What's wired
-
-### Database layer
-
-- **`packages/db/src/client.ts`** — driver swap. Detects non-Neon `DATABASE_URL` (regex on `*.neon.tech` / `*.neon.build`) and uses `drizzle-orm/node-postgres` with `pg.Pool` instead of `@neondatabase/serverless`. The Neon driver only speaks Neon's HTTP/WS protocol, not vanilla Postgres TCP.
-- **`packages/db/src/seed-dev.ts`** — `bun db:seed:dev` script. POSTs to `/api/auth/sign-up/email` to create `admin@local.test / supersetdev`. Refuses to run in production or against non-localhost `DATABASE_URL`. Idempotent.
-- **`docker-compose.dev.yml`** — Postgres 16 with `wal_level=logical` on host port 5433, Electric SQL 1.4.13 on host port 4649 reading from the Postgres above via `host.docker.internal`. Health-checked.
-
-### Auth
-
-- **`packages/auth/src/server.ts`** — `emailAndPassword: { enabled: isLocalProfile(), autoSignIn: true }`. Direct credential endpoints are local-profile only. `afterCreateOrganization` hook gates Stripe customer creation on `env.STRIPE_SECRET_KEY` presence; `seedDefaultStatuses` always runs so OSS users complete org provisioning cleanly. OAuth providers register conditionally on their `*_CLIENT_ID`.
-- **`packages/auth/src/lib/resend.ts`** — `Proxy` lazy-init with batch + emails console fallback when `RESEND_API_KEY` empty. Better Auth's `sendEmail` hook writes to terminal instead of crashing.
-- **`packages/auth/src/stripe.ts`** — `Proxy` lazy-init. Throws "Stripe not configured" only when a billing operation is exercised.
-- **`packages/trpc/src/router/support/support.ts`** — same lazy-init Proxy pattern for the support email path.
-
-### Desktop main process
-
-- **`apps/desktop/src/main/lib/dev-auto-sign-in.ts`** — fired once during `app.whenReady()` when `isLocalProfile()` is true. Polls `/api/auth/ok` with 1s interval × 60s timeout (auto-sign-in survives the race against API startup), then POSTs to `/api/auth/sign-in/email` (auto-signs-up the seed user if missing). Persists the token via the same `saveToken()` that OAuth uses. Renderer stays prod-pure.
-- **`apps/desktop/src/main/index.ts`** — calls `void ensureDevAuthToken()` (fire-and-forget) so the window opens immediately. `AuthProvider`'s `onTokenChanged` subscription re-hydrates when the token lands. Also exposes Chrome DevTools Protocol on `localhost:9333` in the local profile for headless verification.
-- **`apps/desktop/src/main/env.main.ts`** — env defaults switch to localhost only in explicit local-profile dev builds (`NODE_ENV=development` and `SUPERSET_PROFILE=local`) so a fresh-clone session never silently points main-process clients at hosted production. Profile check inlined here (rather than imported from `@superset/shared`) because `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time using Node's ESM loader, which can't transform `.ts` files from sibling workspace packages.
-
-### Desktop renderer
-
-- **`apps/desktop/src/renderer/env.renderer.ts`** — env defaults switch to localhost only in explicit local-profile dev builds for `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WEB_URL`, `NEXT_PUBLIC_ELECTRIC_URL`, `RELAY_URL`. Fresh-clone renderer never syncs against hosted Electric.
-- **`apps/desktop/src/renderer/routes/_authenticated/.../*`** (16 files) — flipped `env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : session.activeOrganizationId` to `session.activeOrganizationId ?? (env.SKIP_ENV_VALIDATION ? MOCK_ORG_ID : null)`. Prefer real session, fall back to mock only when there is no session. Fixed the "Host service not available" toast caused by the renderer querying host-service by the fake org ID while host-service spawned for the real auto-signed-in admin org.
-
-### Build pipeline
-
-- **`apps/desktop/electron.vite.config.ts`** + **`apps/desktop/vite/helpers.ts`** — added `devOrProdUrl()` helper that returns `process.env[key]` if set, else a localhost fallback only for explicit local-profile dev builds. Used in `define` blocks for main + renderer `process.env` replacements and in `htmlEnvTransformPlugin` for `%NEXT_PUBLIC_*%` placeholders in `index.html`.
-
-### Web app
-
-- **`apps/web/src/app/(auth)/components/DevSignInButton/`** — email/password sign-in action, gated to non-production builds using local API/web URLs. Prefilled with seed credentials so contributors click "Sign in" once.
-- **`apps/web/src/app/(auth)/sign-in/.../page.tsx`** + **`sign-up/.../page.tsx`** — wire the form.
-
-### Telemetry / observability
-
-- **`apps/api/src/lib/analytics.ts`** + **`packages/trpc/src/lib/analytics.ts`** — PostHog `Proxy` lazy-init returning a no-op surface (`capture`, `getFeatureFlag`, etc.) when `NEXT_PUBLIC_POSTHOG_KEY` is missing.
-- **`apps/api/src/lib/boot-summary.ts`** — one-time API startup log in lenient profiles, printing every disabled integration and the env var to enable it. Visible to contributors so degradation is never silent, while strict prod/internal boot stays quiet.
-- **`apps/api/src/app/api/health/route.ts`** — `GET /api/health` returns `{ ok: true }` in strict profiles and adds `{ profile, integrations: { stripe: "configured" | "missing", … } }` in lenient profiles for contributor sanity checks.
-
-### Plumbing
-
-- **`turbo.jsonc`** — `SUPERSET_PROFILE`, `CI`, `VERCEL`, `VERCEL_ENV`, and `SKIP_ENV_VALIDATION` live in `globalEnv`. Profile-affecting flags now hash into the cache key so strict/lenient cached builds can't cross-contaminate.
-- **`package.json`** — `bun db:seed:dev` root script.
-
-### Docs
-
-- **`docs/LOCAL_DEVELOPMENT.md`** — contributor-facing setup guide.
-- **`README.md`** — `Build from Source` section shrunk to a 6-line quickstart, pointed at `docs/LOCAL_DEVELOPMENT.md`.
-
-## Decisions made (with rejected alternatives)
-
-### Why profile-aware `skipValidation` instead of marking ~70 integration vars `.optional()` everywhere?
-
-**Rejected:** Mark each integration key `.optional()`, fix every consumer that types it as `string`. The "Formbricks pattern."
-
-**Chosen:** Keep schemas as-is, flip `skipValidation` based on profile. Lazy guards at call sites catch the crashes.
-
-**Why:** The Formbricks refactor would touch ~70 schema entries and ~100+ consumer sites that assume non-null. The skipValidation approach is one line per env file, no consumer changes, and the runtime behavior is identical: in OSS, the env object has whatever's in `process.env` (possibly empty strings); call sites that crash get wrapped in lazy guards as discovered.
-
-### Why strict-by-default with `SUPERSET_PROFILE=local` opt-in, not lenient-by-default with `SUPERSET_INTERNAL_DEV=1` opt-in?
-
-**Rejected:** Default to lenient + write `SUPERSET_INTERNAL_DEV=1` from `.superset/setup.sh` so internal devs land in strict.
-
-**Chosen:** Default to strict + local contributors set `SUPERSET_PROFILE=local`.
-
-**Why:** Strict-by-default is the conservative direction. An internal dev or self-hoster who forgets to source their `.env` gets a clear failure, not a silently-degraded app. OSS contributors trade a one-time flag for that safety guarantee. Also: no setup-script edit means internal devs' workflow is byte-identical to today.
-
-### Why not gate on `NODE_ENV === "production"` instead of Vercel env markers?
-
-**Rejected:** Use `NODE_ENV === "production"` as the cloud discriminator.
-
-**Chosen:** `VERCEL=1` or `VERCEL_ENV` for cloud, `NODE_ENV` only as a fallback indicator inside the `internal` default.
-
-**Why:** `NODE_ENV=production` is true in self-hosted dev too — it conflates "deployed to Vercel" with "operator running the production build locally." Self-hosters are legitimate prod operators and we want them strict, but they have different keys than Vercel (no `VERCEL_*` vars, no Vercel-specific URLs). Discriminating on Vercel env markers keeps cloud and self-hosted as two distinct strict-validated buckets.
-
-### Why a `ci` profile when `SKIP_ENV_VALIDATION=1` already exists?
-
-**Rejected:** Have CI workflows explicitly set `SKIP_ENV_VALIDATION=1` for lint/typecheck/test jobs.
-
-**Chosen:** Auto-detect `CI=true` (set by GitHub Actions and most CI runners) and treat as lenient.
-
-**Why:** Zero-config — existing workflows don't need to add env vars. And the profile is reported correctly in the boot summary + `/api/health`, so it's clear in logs that the build is lenient. `SKIP_ENV_VALIDATION=1` remains the explicit one-off escape hatch.
-
-### Why move profile-affecting flags from `globalPassThroughEnv` to `globalEnv`?
-
-**Rejected:** Pass-through (cheap, no cache invalidation).
-
-**Chosen:** Hash into the cache key.
-
-**Why:** A `bun run build` cached with `SUPERSET_PROFILE=local` (validation skipped) could be served back when the next caller doesn't have the flag (validation expected). Same for `CI=true` vs not. Caches that disagree about validation produce bugs that are very hard to attribute. Cache invalidation cost is acceptable — these flags don't flip often.
-
-### Why dev auto-sign-in in the main process, not the renderer?
-
-**Initial attempt:** Put it in `AuthProvider` (renderer).
-
-**Rejected because:** Mixes dev seed concerns with prod auth hydration. `AuthProvider` becomes "auth + dev seeding." Race conditions with React render lifecycle. Easy to accidentally ship to prod bundles.
-
-**Chosen:** Main process during `app.whenReady()`. Uses the same `saveToken()` OAuth uses. Renderer is 100% upstream-pure — has no idea dev mode exists.
-
-### Why fire-and-forget instead of blocking window creation on auto-sign-in?
-
-**Initial attempt:** `await ensureDevAuthToken()` before `MainWindow()`.
-
-**Rejected because:** If the API takes 30s to compile on first launch, the desktop window is blank for 30s with no feedback. Bad UX.
-
-**Chosen:** `void ensureDevAuthToken()` — window opens immediately. The function polls `/api/auth/ok` internally with backoff. `AuthProvider.onTokenChanged` subscription picks up the token whenever it eventually lands and re-hydrates the renderer's session.
-
-### Why inline the profile check in `env.main.ts` instead of importing from `@superset/shared`?
-
-**Rejected:** Single canonical import.
-
-**Chosen:** Inline the four-line check in `env.main.ts` only; other consumers import from `@superset/shared/deployment-profile`.
-
-**Why:** `electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time to validate env at build. Node's native ESM loader handles that import — it has no Vite/SWC/TS transform — so any transitive `.ts` import from a sibling workspace package fails with `ERR_UNKNOWN_FILE_EXTENSION`. Discovered the hard way when CI build failed. The four lines of duplication are a fair trade for not breaking the build.
-
-## Lessons learned
-
-### `neondatabase/neon_local` is not a Neon protocol emulator
-
-It requires `NEON_PROJECT_ID` + `NEON_API_KEY` and acts as a *proxy* to a real Neon project. Useless for OSS. We discovered this only by running it. Plain `postgres:16 -c wal_level=logical` is the right substrate; pair it with a driver swap.
-
-### `@neondatabase/serverless` cannot speak vanilla Postgres TCP
-
-The serverless driver only knows Neon's HTTP/WS protocol. Verified by running it against a local Postgres — fails with "Unable to connect." Driver swap is unavoidable (~20 LOC), not a config flag.
-
-### Most integrations degrade gracefully on their own
-
-Better Auth social providers, Upstash KV, QStash all log warnings on missing keys and keep working. Only **Stripe, Resend, PostHog, and the trpc support router** crashed at module load. The plan's "guard a dozen integrations" overestimated; actual scope was 4 files.
-
-### The renderer had a hidden dev-mode landmine
-
-16 places overrode `activeOrganizationId` to `MOCK_ORG_ID` whenever `SKIP_ENV_VALIDATION` was set — a hack from when dev mode had no real session. With the new main-process auto-sign-in producing a real session with a real org, the renderer was looking up host-service connections by the fake mock org while host-service had spawned for the real org → "Host service not available" toast. Flipping the priority (`session.org ?? (devMode ? mock : null)`) fixed all 16 sites with the same one-line pattern.
-
-### Vite/Turbopack caches can mask real bugs during iteration
-
-A mid-process `.next/` deletion left the dev server in a corrupted state — every route returned 404 even though the files existed. Full clean-restart fixed it. Don't trust caches during refactoring; reset between iterations.
-
-### `electron-vite build` uses Node's native ESM loader for its config
-
-`electron.vite.config.ts` does `await import("./src/main/env.main")` at config-load time, which Node handles directly. Any transitive `.ts` import from a sibling workspace package crashes the build. Workspace packages exporting `.ts` files (the common monorepo pattern here) only work for consumers that go through a transform layer.
-
-### CDP is invaluable for verifying renderer state without manual clicks
-
-Enabling Chrome DevTools Protocol in the Electron main process (one line of `app.commandLine.appendSwitch`) let me probe the React context for `activeHostUrl` directly. Confirmed the fix without needing to click "Import" in the UI. Faster + more honest than asking the user to retry.
-
-### Most upstream OSS projects don't multi-profile cleanly
-
-The previous research agent found nobody in the OSS reference class (Cal.com, Documenso, Plane, Twenty, Supabase, Formbricks) does true three-or-four-profile env validation. The closest is Formbricks (`createFinalSchema` + per-group `.refine()`). The pattern we shipped — `getDeploymentProfile()` + profile-keyed `skipValidation` + boot summary + `/api/health` — is novel relative to that ref class.
-
-### CI build failures are a fast feedback loop you should actually use
-
-I shipped the deployment-profile changes without checking `gh pr checks 4616`. The build broke. Next time: `gh pr checks` is part of the post-push ritual.
-
-## What was built — commit-by-commit
-
-| Commit | Theme |
-|---|---|
-| [`04130c0`](https://github.com/superset-sh/superset/pull/4616/commits/04130c0) | Core OSS path: DB driver swap, lazy-init guards (Stripe/Resend/PostHog), Better Auth email/password, desktop dev auto-sign-in, MOCK_ORG_ID priority fix, web app dev sign-in, `db:seed:dev`, CDP for verification, docs |
-| [`2b609b5`](https://github.com/superset-sh/superset/pull/4616/commits/2b609b5) | Deployment profiles + boot summary + `/api/health` endpoint |
-| [`f3c76b9`](https://github.com/superset-sh/superset/pull/4616/commits/f3c76b9) | Flipped discriminator (strict by default, local profile opts into lenient) |
-| [`101cd30`](https://github.com/superset-sh/superset/pull/4616/commits/101cd30) | Added `ci` profile (GitHub Actions auto-detect) |
-| [`513d198`](https://github.com/superset-sh/superset/pull/4616/commits/513d198) | Five review-finding fixes: Stripe gate in `afterCreateOrganization`, email/password disabled in prod, docker-compose.dev.yml + Electric URL defaults, auto-sign-in API readiness poll, profile flags hash into Turbo cache |
-| [`f3254ef`](https://github.com/superset-sh/superset/pull/4616/commits/f3254ef) | Fixed CI build (inlined profile check in `env.main.ts`); remaining hardcoded prod URL defaults switched to `devOrProdUrl()` helper across `electron.vite.config.ts`, `vite/helpers.ts`, `env.main.ts` |
-
-## Verification
-
-End-to-end smoke test after final commit:
-
-```text
-[superset] profile=local (lenient)
-[superset] disabled features (set the listed env var(s) to enable):
-           - stripe                       STRIPE_SECRET_KEY
-           - resend (email)               RESEND_API_KEY
-           - posthog (telemetry)          NEXT_PUBLIC_POSTHOG_KEY
-           …
-[dev-auto-sign-in] signed in as admin@local.test
-[host-service:b499daed-…] listening on port 51257
-```
-
-DB sanity check confirmed the Stripe-gate fix:
-```sql
-SELECT email, name, slug, stripe_customer_id FROM auth.users JOIN auth.organizations ...
-admin@local.test | Local Admin's Team | 14019d9c-team | <NULL>
-```
-
-Profile resolution unit test (all 6 cases pass):
-```
-✓ fresh clone (no env)                  → internal  (strict)
-✓ Local contributor                     → local     (lenient)
-✓ GitHub Actions                        → ci        (lenient)
-✓ Vercel runtime                        → cloud     (strict)
-✓ Vercel runtime overrides CI           → cloud     (strict)
-✓ Local profile overrides CI            → local     (lenient)
-```
-
-CDP-probed React context:
-```json
-{ "activeHostUrl": "http://127.0.0.1:51257", "machineId": "…" }
-```
-
-Local CI reproduction:
-- `bun run lint` — clean
-- `bun run --cwd apps/desktop typecheck` — clean
-- `bun turbo run build --filter=@superset/desktop` — succeeds
-
-## Follow-ups
-
-These are real follow-ups, none of them blocking the OSS path from working today:
-
-- **Complete integration crash audit** — Stripe, Resend, PostHog, support email, QStash queue creation, and the common OAuth providers are guarded. Less-used integrations still deserve a follow-up import-time audit.
-- **Mailpit instead of console-log emails** — Better Auth's `sendEmail` falls back to stdout. Mailpit container would give contributors a clickable UI at `localhost:8025`.
-- **CI fresh-clone smoke test** — without one, the OSS path silently rots the next time someone adds a crash-on-import integration. A GitHub Actions job that does `git clone` in a fresh runner, follows the README, hits `/api/auth/ok`, fails if anything red.
-- **Per-integration group `.refine()` validation** — Formbricks pattern. E.g. if `STRIPE_SECRET_KEY` is set then `STRIPE_WEBHOOK_SECRET` must also be set. Catches half-configured prod deploys.
-
-## Architecture diagrams
-
-### Profile resolution
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                       getDeploymentProfile()                         │
-│                                                                      │
-│   VERCEL === "1" or VERCEL_ENV ─────────►  cloud      (strict)     │
-│       │                                                              │
-│       no                                                             │
-│       ▼                                                              │
-│   SUPERSET_PROFILE=local ────────────────►  local      (lenient)    │
-│       │                                                              │
-│       no                                                             │
-│       ▼                                                              │
-│   CI === "true"         ─────────────────►  ci         (lenient)    │
-│       │                                                              │
-│       no                                                             │
-│       ▼                                                              │
-│                          ─────────────────►  internal  (strict)     │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### Local session lifecycle
-
-```
-┌──────────────────┐                  ┌──────────────────┐
-│  Postgres :5433  │  wal_level=      │  Electric :4649  │
-│  superset-pg     │  logical         │  superset-       │
-│                  │ ◄────────────────┤  electric        │
-└──────────────────┘  (docker-compose)└──────────────────┘
-        ▲                                       ▲
-        │ migrations                            │ shape stream
-        │                                       │
-        ▼                                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│  bun dev (with SUPERSET_PROFILE=local)                         │
-│                                                                │
-│  apps/web      :4640  ─ Next.js, local DevSignInButton visible│
-│  apps/api      :4641  ─ Better Auth + tRPC, /api/health       │
-│                                                                │
-│  apps/desktop:                                                 │
-│     Electron main         ─ ensureDevAuthToken() polls API,    │
-│                              POSTs sign-up/sign-in, saveToken()│
-│     Vite renderer :4645  ─ AuthProvider.onTokenChanged hydrates│
-│     Notifications :4646                                        │
-│                                                                │
-│  electric-proxy :4652  (Wrangler)  ─ ELECTRIC_SHAPE_URL=:4649 │
-│  Caddy           :4650  (HTTPS)   ─ reverse proxy → :4652     │
-└──────────────────────────────────────────────────────────────┘
-        │
-        │ host-service spawned per-org (dynamic port)
-        ▼
-┌──────────────────────────────────────────────────┐
-│  Host service (per organization)                  │
-│  superset-dev-data/host/<orgId>/host.db           │
-│  Listening on dynamic port (e.g. :51257)          │
-└──────────────────────────────────────────────────┘
-```
-
-### Strictness × visibility matrix
-
-| Profile      | `skipValidation` | Boot summary    | `/api/health` shows         | Sign-in path                                  |
-|--------------|------------------|------------------|------------------------------|------------------------------------------------|
-| `cloud`      | false (strict)   | none                         | `{ ok: true }`            | OAuth                                          |
-| `internal`   | false (strict)   | none                         | `{ ok: true }`            | OAuth                                          |
-| `ci`         | true (lenient)   | `profile=ci (lenient)`      | `profile: "ci"`           | n/a (build/test job, no runtime auth)          |
-| `local`      | true (lenient)   | lists disabled features     | `profile: "local"`        | dev auto-sign-in + dev email/password form     |

From c68ce81c739e07440a926a9d05104c0ba77ec8b4 Mon Sep 17 00:00:00 2001
From: Justin Rich <justin@hackerpug.com>
Date: Sat, 4 Jul 2026 13:37:06 -0700
Subject: [PATCH 28/28] SUPER-771: Loud failures for automation runs (#4817)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* improvement(SUPER-771): capture ticket snapshot

* improvement(SUPER-771): scope proposal v1

* improvement(SUPER-771): scope challenged

* improvement(SUPER-771): scope binding (moderate)

* improvement(SUPER-771): paste-ready linear comment payload

* improvement(SUPER-771): UI design specs

Adds two binding design spec files under .spec/tasks/SUPER-771/design/:
- PreviousRunsList-failed-row.md: two-line failed row layout, select-text/cursor-text
  requirement, tooltip retention, accessibility rationale, and implementation notes
  (no sub-component extraction, inline cn() class swap, pl-4 error alignment).
- AutomationFailureNotifier.md: provider lifecycle, useRef<Set<string>> dedup
  contract, showNative call shape (no clickTarget), mount point in layout.tsx,
  and relay status code translation table (cross-reference for AC-4 implementer).

* improvement(SUPER-771): emit kb-run-sprint task files

* fix: translate relay status codes to human copy (AC-3, AC-4)

Add humanRelayMessage() helper to convert relay HTTP status codes to
user-facing copy (502→"Target machine is unreachable", 503→"Target
machine was offline", etc.). Update RelayDispatchError message to use
this translation. Revert incorrect err.name prefix in describeError
that was making messages longer and more jargon-heavy. Update tests
to expect the new human-readable format.

* fix: inline failed-run error row in PreviousRunsList (AC-1, AC-2)

Implement two-line layout for failed runs (status dispatch_failed or
skipped_offline): first line is [dot title time-ago], second line is
inline error span with select-text and cursor-text classes for
copy-ability. Button becomes flex-col items-start when failed. Error
span shows truncated run.error or fallback "Run failed". Replace sham
smoke tests with real behavior assertions that verify inline error
span presence, correct CSS classes, and truncation.

* fix: notifier copy matches design spec (AC-5)

Update AutomationFailureNotifier to use exact copy from spec:
title is "Automation failed" (lowercase), body is run.error || "Run failed".
Remove unnecessary statusLabel concatenation, run.title prefix, and
silent: false parameter. Fix import ordering and line formatting
to pass lint.

* fix: revert unrelated activeOrganizationId refactor; keep notifier mount only (AC-7)

Revert the activeOrganizationId ternary restructure introduced in the
prior cycle. This change is unrelated to AC-7 (notifier mount). The
layout.tsx diff after this fix shows only the import and mount of
AutomationFailureNotifier, as specified.

* feat: add AutomationFailureNotifier test and barrel export (AC-6)

* test: real assertions for inline error span + classes (TC-1, TC-2) [FIX-c2]

* test: real assertions for notifier dedup + copy (TC-5, TC-6, TC-7) [FIX-c2]

* test: real assertions for relay status code translation (TC-3) [FIX-c2]

* test: real assertions for describeError (TC-4), export function for testing [FIX-c2]

* test(SUPER-771): remove sham tests; keep real relay-client coverage

Three test files reimplemented production logic inside themselves and
asserted on the copy. The desktop package has no DOM test infrastructure
(@testing-library/react / happy-dom not installed), so renderer-side
ACs (AC-1, AC-2, AC-5, AC-6, AC-7) require manual visual verification
documented in the PR. describeError (AC-4) is unchanged from main and
is implicitly covered by the AC-3 humanRelayMessage tests in
relay-client.test.ts which exercise the real throw path end-to-end.

* improvement(SUPER-771): PR description draft with manual verification steps

* improvement(SUPER-771): visual proof + simpler DB-insert testing steps

Captures inline error rows and notification screenshots against the running
desktop dev build. Rewrites the manual verification section to use direct
automation_runs inserts — sidesteps the host-service registration/relay
plumbing that's brittle in local dev. The dispatch flow E2E path remains
documented as the optional 'full' verification.

Screenshots committed to .spec/improvements/SUPER-771/screenshots/; PR body
references them via absolute raw URLs on the fork branch.

* fix(automations): tooltip on hover for failed rows; remove .spec scaffolding

PreviousRunsList: wrap TooltipTrigger asChild in a <span> so hover events
fire even when the inner <button> is disabled. Failed runs with
v2_workspace_id=NULL disable the button, which browsers respect by
suppressing pointer events — that was silently breaking the tooltip for
exactly the rows users most want to inspect.

Also removes the .spec/improvements/SUPER-771 and .spec/tasks/SUPER-771
scaffolding from the diff. Those artifacts (SCOPE.md, TICKET.md, design
specs, evidence dumps, screenshots) drove the implementation process but
aren't part of the shipped change. PR description retains the
binding-scope summary + visual proof inline.

* fix(automations): address PR review comments

- Filter useLiveQuery to only failed statuses (dispatch_failed, skipped_offline)
  instead of fetching all runs and filtering in useEffect
- Await IPC notification before marking run as notified; on failure,
  leave unnotified so it retries on next effect run
- Add pointer-events-auto to error span inside disabled button so
  cursor-text I-beam is visible for copyable error text

* fix(automations): typecheck + lint failures in PR #4817

- AutomationFailureNotifier: import eq/or from @tanstack/db (drizzle-orm
  exports are not compatible with @tanstack/react-db column refs)
- relay-client.test.ts: biome auto-fix (trailing commas, import order)
  and replace `as any` with `as unknown as typeof fetch`
---
 .../PreviousRunsList/PreviousRunsList.tsx     |  70 +++--
 .../renderer/routes/_authenticated/layout.tsx |   2 +
 .../AutomationFailureNotifier.tsx             |  53 ++++
 .../AutomationFailureNotifier/index.ts        |   1 +
 .../trpc/src/router/automation/dispatch.ts    |   2 +-
 .../router/automation/relay-client.test.ts    | 266 ++++++++++++++++++
 .../src/router/automation/relay-client.ts     |  18 +-
 7 files changed, 394 insertions(+), 18 deletions(-)
 create mode 100644 apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/AutomationFailureNotifier.tsx
 create mode 100644 apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/index.ts
 create mode 100644 packages/trpc/src/router/automation/relay-client.test.ts

diff --git a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/automations/$automationId/components/PreviousRunsList/PreviousRunsList.tsx b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/automations/$automationId/components/PreviousRunsList/PreviousRunsList.tsx
index 060b2b06586..c042b7ff919 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/_dashboard/automations/$automationId/components/PreviousRunsList/PreviousRunsList.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/_dashboard/automations/$automationId/components/PreviousRunsList/PreviousRunsList.tsx
@@ -47,39 +47,77 @@ export function PreviousRunsList({ runs }: PreviousRunsListProps) {
 		<ul className="flex flex-col gap-0.5 text-sm">
 			{runs.map((run) => {
 				const clickable = !!run.v2WorkspaceId;
+				const isFailed =
+					run.status === "dispatch_failed" || run.status === "skipped_offline";
 				const row = (
 					<button
 						type="button"
 						disabled={!clickable}
 						onClick={() => handleOpenRun(run)}
 						className={cn(
-							"flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left",
+							"flex w-full rounded-md px-2 py-1.5 text-left",
+							isFailed ? "flex-col items-start" : "items-center gap-2",
 							clickable
 								? "cursor-pointer hover:bg-accent/40"
 								: "cursor-default opacity-70",
 						)}
 					>
-						<span
-							role="img"
-							aria-label={run.status}
-							className={cn(
-								"inline-block size-2 shrink-0 rounded-full",
-								STATUS_DOT[run.status],
-							)}
-						/>
-						<span className="truncate">{run.title || "Automation"}</span>
-						<span className="ml-auto shrink-0 truncate text-muted-foreground">
-							{run.scheduledFor
-								? formatAgo(new Date(run.scheduledFor), now)
-								: "—"}
-						</span>
+						{isFailed ? (
+							<>
+								<span className="flex w-full items-center gap-2">
+									<span
+										role="img"
+										aria-label={run.status}
+										className={cn(
+											"inline-block size-2 shrink-0 rounded-full",
+											STATUS_DOT[run.status],
+										)}
+									/>
+									<span className="truncate">{run.title || "Automation"}</span>
+									<span className="ml-auto shrink-0 truncate text-muted-foreground">
+										{run.scheduledFor
+											? formatAgo(new Date(run.scheduledFor), now)
+											: "—"}
+									</span>
+								</span>
+								<span className="truncate text-xs text-destructive select-text cursor-text pointer-events-auto pl-4">
+									{run.error || "Run failed"}
+								</span>
+							</>
+						) : (
+							<>
+								<span
+									role="img"
+									aria-label={run.status}
+									className={cn(
+										"inline-block size-2 shrink-0 rounded-full",
+										STATUS_DOT[run.status],
+									)}
+								/>
+								<span className="truncate">{run.title || "Automation"}</span>
+								<span className="ml-auto shrink-0 truncate text-muted-foreground">
+									{run.scheduledFor
+										? formatAgo(new Date(run.scheduledFor), now)
+										: "—"}
+								</span>
+							</>
+						)}
 					</button>
 				);
 				return (
 					<li key={run.id}>
 						{run.error ? (
 							<Tooltip>
-								<TooltipTrigger asChild>{row}</TooltipTrigger>
+								{/*
+								 * Wrap in a span: failed rows often have no v2WorkspaceId,
+								 * which disables the inner <button>. Browsers suppress
+								 * pointer events on disabled buttons, so Radix's hover
+								 * detection never fires. The span captures hovers; the
+								 * button still handles clicks when it IS clickable.
+								 */}
+								<TooltipTrigger asChild>
+									<span className="block w-full">{row}</span>
+								</TooltipTrigger>
 								<TooltipContent
 									side="left"
 									className="max-w-xs whitespace-pre-wrap"
diff --git a/apps/desktop/src/renderer/routes/_authenticated/layout.tsx b/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
index 0ce1429fcd9..b9a8d2a7999 100644
--- a/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
+++ b/apps/desktop/src/renderer/routes/_authenticated/layout.tsx
@@ -38,6 +38,7 @@ import { GlobalBrowserLifecycle } from "./components/GlobalBrowserLifecycle";
 import { TeardownLogsDialog } from "./components/TeardownLogsDialog";
 import { V2NotificationController } from "./components/V2NotificationController";
 import { createPierreWorker } from "./lib/pierreWorker";
+import { AutomationFailureNotifier } from "./providers/AutomationFailureNotifier";
 import { CollectionsProvider } from "./providers/CollectionsProvider";
 import { DeletingWorkspacesProvider } from "./providers/DeletingWorkspacesProvider";
 import { LocalHostServiceProvider } from "./providers/LocalHostServiceProvider";
@@ -202,6 +203,7 @@ function AuthenticatedLayout() {
 		<DndProvider manager={dragDropManager}>
 			<CollectionsProvider>
 				<GlobalBrowserLifecycle />
+				<AutomationFailureNotifier />
 				<LocalHostServiceProvider>
 					<DeletingWorkspacesProvider>
 						<WorkerPoolContextProvider
diff --git a/apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/AutomationFailureNotifier.tsx b/apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/AutomationFailureNotifier.tsx
new file mode 100644
index 00000000000..6fbdba4522f
--- /dev/null
+++ b/apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/AutomationFailureNotifier.tsx
@@ -0,0 +1,53 @@
+import { eq, or } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+import { useEffect, useRef } from "react";
+import { electronTrpcClient } from "renderer/lib/trpc-client";
+import { useCollections } from "../CollectionsProvider";
+
+export function AutomationFailureNotifier() {
+	const collections = useCollections();
+	const notifiedRunIdsRef = useRef<Set<string>>(new Set());
+
+	const { data: automationRuns = [] } = useLiveQuery(
+		(q) =>
+			q
+				.from({ automationRuns: collections.automationRuns })
+				.select(({ automationRuns: ar }) => ({
+					id: ar.id,
+					title: ar.title,
+					status: ar.status,
+					error: ar.error,
+				}))
+				.where(({ automationRuns: ar }) =>
+					or(
+						eq(ar.status, "dispatch_failed"),
+						eq(ar.status, "skipped_offline"),
+					),
+				),
+		[collections],
+	);
+
+	useEffect(() => {
+		if (!automationRuns || automationRuns.length === 0) {
+			return;
+		}
+
+		for (const run of automationRuns) {
+			if (notifiedRunIdsRef.current.has(run.id)) continue;
+
+			electronTrpcClient.notifications.showNative
+				.mutate({
+					title: "Automation failed",
+					body: run.error || "Run failed",
+				})
+				.then(() => {
+					notifiedRunIdsRef.current.add(run.id);
+				})
+				.catch(() => {
+					// IPC call failed — don't mark as notified so it retries next effect run
+				});
+		}
+	}, [automationRuns]);
+
+	return null;
+}
diff --git a/apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/index.ts b/apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/index.ts
new file mode 100644
index 00000000000..0b733b076ae
--- /dev/null
+++ b/apps/desktop/src/renderer/routes/_authenticated/providers/AutomationFailureNotifier/index.ts
@@ -0,0 +1 @@
+export { AutomationFailureNotifier } from "./AutomationFailureNotifier";
diff --git a/packages/trpc/src/router/automation/dispatch.ts b/packages/trpc/src/router/automation/dispatch.ts
index 2add6b9dc28..7f4e247194e 100644
--- a/packages/trpc/src/router/automation/dispatch.ts
+++ b/packages/trpc/src/router/automation/dispatch.ts
@@ -307,7 +307,7 @@ async function runAgentOnHost(args: {
 	);
 }
 
-function describeError(err: unknown, context: string): string {
+export function describeError(err: unknown, context: string): string {
 	if (err instanceof RelayDispatchError) return `${context}: ${err.message}`;
 	if (err instanceof Error) return `${context}: ${err.message}`;
 	return `${context}: unknown error`;
diff --git a/packages/trpc/src/router/automation/relay-client.test.ts b/packages/trpc/src/router/automation/relay-client.test.ts
new file mode 100644
index 00000000000..4f42b28ceae
--- /dev/null
+++ b/packages/trpc/src/router/automation/relay-client.test.ts
@@ -0,0 +1,266 @@
+import { beforeEach, describe, expect, it, vi } from "bun:test";
+import { RelayDispatchError, relayMutation } from "./relay-client";
+
+describe("relay-client", () => {
+	describe("RelayDispatchError", () => {
+		it("preserves error class name as 'RelayDispatchError'", () => {
+			const error = new RelayDispatchError("test message", 500, "body");
+			expect(error.name).toBe("RelayDispatchError");
+		});
+
+		it("includes status and body in instance properties", () => {
+			const error = new RelayDispatchError("test message", 404, "not found");
+			expect(error.status).toBe(404);
+			expect(error.body).toBe("not found");
+		});
+
+		it("extends Error so instanceof checks work", () => {
+			const error = new RelayDispatchError("test", 500, "body");
+			expect(error instanceof Error).toBe(true);
+			expect(error instanceof RelayDispatchError).toBe(true);
+		});
+	});
+
+	describe("relayMutation", () => {
+		beforeEach(() => {
+			vi.clearAllMocks();
+		});
+
+		it("throws RelayDispatchError on non-ok response with truncated body", async () => {
+			const longBody = "x".repeat(1000);
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: false,
+					status: 500,
+					text: () => Promise.resolve(longBody),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					// Verify the message uses human-readable format and is truncated
+					expect(err.message).toContain("Relay error (status 500):");
+					expect(err.message.length).toBeLessThan(300);
+					// full body preserved in property
+					expect(err.body).toBe(longBody);
+				}
+			}
+		});
+
+		it("throws RelayDispatchError on invalid JSON with truncated snippet", async () => {
+			const longBody = `invalid json ${"x".repeat(500)}`;
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: true,
+					status: 200,
+					text: () => Promise.resolve(longBody),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					// Verify truncation at 200 chars for JSON parse errors
+					expect(err.message).toContain("invalid JSON from relay");
+					expect(err.message.length).toBeLessThan(300);
+				}
+			}
+		});
+
+		it("throws RelayDispatchError when result.data is missing with truncated body", async () => {
+			const resultObj = { result: {} };
+			const _longBody = JSON.stringify(resultObj) + "x".repeat(500);
+			// Create valid JSON with missing data field
+			const validJson = JSON.stringify(resultObj);
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: true,
+					status: 200,
+					text: () => Promise.resolve(validJson),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					expect(err.message).toContain("missing result.data");
+					expect(err.message.length).toBeLessThan(300);
+				}
+			}
+		});
+	});
+
+	describe("humanRelayMessage (AC-3 tests)", () => {
+		it("AC-3: relay 503 translates to 'Target machine was offline'", async () => {
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: false,
+					status: 503,
+					text: () => Promise.resolve('{"error":"Service unavailable"}'),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					expect(err.message).toBe("Target machine was offline");
+					expect(err.status).toBe(503);
+				}
+			}
+		});
+
+		it("AC-3: relay 502 translates to 'Target machine is unreachable'", async () => {
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: false,
+					status: 502,
+					text: () => Promise.resolve('{"error":"Bad gateway"}'),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					expect(err.message).toBe("Target machine is unreachable");
+					expect(err.status).toBe(502);
+				}
+			}
+		});
+
+		it("AC-3: relay 504 translates to 'Target machine timed out'", async () => {
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: false,
+					status: 504,
+					text: () => Promise.resolve('{"error":"Gateway timeout"}'),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					expect(err.message).toBe("Target machine timed out");
+					expect(err.status).toBe(504);
+				}
+			}
+		});
+
+		it("AC-3: unknown status falls back to 'Relay error (status N): ...'", async () => {
+			const responseBody = '{"error":"Some error"}';
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: false,
+					status: 418,
+					text: () => Promise.resolve(responseBody),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					expect(err.message).toContain("Relay error (status 418):");
+					expect(err.status).toBe(418);
+				}
+			}
+		});
+
+		it("AC-3: truncates long response body in fallback message", async () => {
+			const longBody = "error-details".repeat(50); // ~650 chars
+			global.fetch = vi.fn(() =>
+				Promise.resolve({
+					ok: false,
+					status: 500,
+					text: () => Promise.resolve(longBody),
+				}),
+			) as unknown as typeof fetch;
+
+			const options = {
+				relayUrl: "http://relay.local",
+				hostId: "host-123",
+				jwt: "token",
+			};
+
+			try {
+				await relayMutation(options, "test.mutation", { input: "data" });
+				expect.fail("should have thrown");
+			} catch (err) {
+				expect(err instanceof RelayDispatchError).toBe(true);
+				if (err instanceof RelayDispatchError) {
+					// Message should contain "Relay error (status 500):" and truncated body
+					expect(err.message).toContain("Relay error (status 500):");
+					// Should be truncated, not the full long body
+					expect(err.message.length).toBeLessThan(longBody.length);
+					// Should end with ellipsis if truncated
+					if (err.message.length < 300) {
+						// Truncation happened
+						expect(err.message).toMatch(/…$/);
+					}
+				}
+			}
+		});
+	});
+});
diff --git a/packages/trpc/src/router/automation/relay-client.ts b/packages/trpc/src/router/automation/relay-client.ts
index 0529dd4734a..97267581cdf 100644
--- a/packages/trpc/src/router/automation/relay-client.ts
+++ b/packages/trpc/src/router/automation/relay-client.ts
@@ -15,6 +15,22 @@ export interface RelayClientOptions {
 	timeoutMs?: number;
 }
 
+function humanRelayMessage(status: number, rawBody: string): string {
+	switch (status) {
+		case 502:
+			return "Target machine is unreachable";
+		case 503:
+			return "Target machine was offline";
+		case 504:
+			return "Target machine timed out";
+		default: {
+			const trimmed =
+				rawBody.length > 200 ? `${rawBody.slice(0, 200)}…` : rawBody;
+			return `Relay error (status ${status}): ${trimmed}`;
+		}
+	}
+}
+
 export class RelayDispatchError extends Error {
 	constructor(
 		message: string,
@@ -65,7 +81,7 @@ export async function relayMutation<TInput, TOutput>(
 	const rawBody = await response.text();
 	if (!response.ok) {
 		throw new RelayDispatchError(
-			`relay ${response.status}: ${rawBody.slice(0, 500)}`,
+			humanRelayMessage(response.status, rawBody),
 			response.status,
 			rawBody,
 		);