feat: onboarding config, reset onboarding, xai agentic migration (#701)01-24-feat_onboarding_config_reset_onboarding_xai_agentic_migration

- Created a new `useOrgOnboarding` hook that uses `org.metadata.isOnboarded` to track onboarding state
- Updated the home page to conditionally use either the old localStorage-based onboarding or the new DB-backed onboarding based on feature flag
- Added a "Restart Onboarding" option in the user dropdown menu
- Improved the onboarding chat sidebar with per-link loading indicators
- Enhanced the X/Twitter research API to better handle different URL formats
- Updated the integrations step to use the new onboarding completion method
- Added `updateOrgMetadata` function to the auth context for easier metadata updates

2 files changed, 106 insertions, 0 deletions

diff --git a/packages/hooks/use-org-onboarding.ts b/packages/hooks/use-org-onboarding.ts
new file mode 100644
index 00000000..e71eab8f
--- /dev/null
+++ b/packages/hooks/use-org-onboarding.ts
@@ -0,0 +1,85 @@
+"use client"
+
+import { useCallback, useMemo } from "react"
+import { useAuth } from "@lib/auth-context"
+import { authClient } from "@lib/auth"
+
+/**
+ * DB-backed onboarding completion hook for the new app flow.
+ * Uses consumer org `metadata.isOnboarded` instead of localStorage.
+ *
+ * TODO: remove this after the feature flag is removed
+ * This hook is for the new app flow only (feature-flagged `nova-alpha-access`).
+ * The old onboarding flow will continue to use `useOnboardingStorage` (localStorage).
+ */
+export function useOrgOnboarding() {
+	const { org, updateOrgMetadata } = useAuth()
+
+	const isOrgOnboarded = useMemo(() => {
+		if (!org) return null
+		return org.metadata?.isOnboarded === true
+	}, [org])
+
+	const markOrgOnboarded = useCallback(() => {
+		if (!org?.id) {
+			console.error("No organization context when marking as onboarded")
+			return
+		}
+
+		// Optimistic update: update in-memory state immediately
+		updateOrgMetadata({ isOnboarded: true })
+
+		authClient.organization
+			.update({
+				organizationId: org.id,
+				data: {
+					metadata: {
+						...org.metadata,
+						isOnboarded: true,
+					},
+				},
+			})
+			.catch((error) => {
+				console.error("Failed to mark organization as onboarded:", error)
+				updateOrgMetadata({ isOnboarded: false })
+			})
+	}, [org, updateOrgMetadata])
+
+	const resetOrgOnboarded = useCallback(() => {
+		if (!org?.id) {
+			console.error("No organization context when resetting onboarding")
+			return
+		}
+
+		// Optimistic update: update in-memory state immediately
+		updateOrgMetadata({ isOnboarded: false })
+
+		authClient.organization
+			.update({
+				organizationId: org.id,
+				data: {
+					metadata: {
+						...org.metadata,
+						isOnboarded: false,
+					},
+				},
+			})
+			.catch((error) => {
+				console.error("Failed to reset organization onboarding:", error)
+				updateOrgMetadata({ isOnboarded: true })
+			})
+	}, [org, updateOrgMetadata])
+
+	const shouldShowOnboarding = useCallback(() => {
+		if (isOrgOnboarded === null) return null // Still loading (org not ready)
+		return !isOrgOnboarded
+	}, [isOrgOnboarded])
+
+	return {
+		isOrgOnboarded,
+		markOrgOnboarded,
+		resetOrgOnboarded,
+		shouldShowOnboarding,
+		isLoading: org === null,
+	}
+}
diff --git a/packages/lib/auth-context.tsx b/packages/lib/auth-context.tsx
index 4bfdc2d7..67e57d49 100644
--- a/packages/lib/auth-context.tsx
+++ b/packages/lib/auth-context.tsx
@@ -3,6 +3,7 @@
 import {
 	createContext,
 	type ReactNode,
+	useCallback,
 	useContext,
 	useEffect,
 	useState,
@@ -17,6 +18,9 @@ interface AuthContextType {
 	user: SessionData["user"] | null
 	org: Organization | null
 	setActiveOrg: (orgSlug: string) => Promise<void>
+	updateOrgMetadata: (
+		partial: Record<string, unknown>,
+	) => void
 }
 
 const AuthContext = createContext<AuthContextType | undefined>(undefined)
@@ -35,6 +39,22 @@ export function AuthProvider({ children }: { children: ReactNode }) {
 		setOrg(activeOrg)
 	}
 
+	const updateOrgMetadata = useCallback(
+		(partial: Record<string, unknown>) => {
+			setOrg((prev) => {
+				if (!prev) return prev
+				return {
+					...prev,
+					metadata: {
+						...prev.metadata,
+						...partial,
+					},
+				}
+			})
+		},
+		[],
+	)
+
 	// biome-ignore lint/correctness/useExhaustiveDependencies: ignoring the setActiveOrg dependency
 	useEffect(() => {
 		if (session?.session.activeOrganizationId) {
@@ -99,6 +119,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
 				session: session?.session ?? null,
 				user: session?.user ?? null,
 				setActiveOrg,
+				updateOrgMetadata,
 			}}
 		>
 			{children}