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/14] 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/14] =?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/14] =?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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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");