From c715bc4ce424be77a11263dd6edcb34eb187b901 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 13:53:54 +0100
Subject: [PATCH 1/9] refactor: update routing logic to redirect to '/welcome'
 after auth callback and handle organization checks

---
 app/auth/callback/page.tsx |   2 +-
 app/welcome/page.tsx       | 519 +++++++++++++++++++++++++++++++++++++
 lib/auth/context.tsx       |   9 +-
 3 files changed, 523 insertions(+), 7 deletions(-)
 create mode 100644 app/welcome/page.tsx

diff --git a/app/auth/callback/page.tsx b/app/auth/callback/page.tsx
index db02ff4..0537e22 100644
--- a/app/auth/callback/page.tsx
+++ b/app/auth/callback/page.tsx
@@ -27,7 +27,7 @@ function AuthCallbackContent() {
       localStorage.removeItem('oauth_state')
       localStorage.removeItem('oauth_code_verifier')
       if (localStorage.getItem('pulse_pending_checkout')) {
-        router.push('/pricing')
+        router.push('/welcome')
       } else {
         router.push('/')
       }
diff --git a/app/welcome/page.tsx b/app/welcome/page.tsx
new file mode 100644
index 0000000..42e8363
--- /dev/null
+++ b/app/welcome/page.tsx
@@ -0,0 +1,519 @@
+'use client'
+
+/**
+ * Guided onboarding wizard for new Pulse users.
+ * Steps: Welcome → Workspace (create org) → Plan / trial → First site (optional) → Done.
+ * Supports ?step= in URL for back/refresh. Handles pulse_pending_checkout from pricing.
+ */
+
+import { useState, useEffect, useCallback, Suspense } from 'react'
+import { useRouter, useSearchParams } from 'next/navigation'
+import { motion, AnimatePresence } from 'framer-motion'
+import {
+  createOrganization,
+  getUserOrganizations,
+  switchContext,
+  type Organization,
+} from '@/lib/api/organization'
+import { createCheckoutSession } from '@/lib/api/billing'
+import { createSite, type Site } from '@/lib/api/sites'
+import { setSessionAction } from '@/app/actions/auth'
+import { useAuth } from '@/lib/auth/context'
+import { getAuthErrorMessage } from '@/lib/utils/authErrors'
+import { LoadingOverlay, Button, Input } from '@ciphera-net/ui'
+import { toast } from '@ciphera-net/ui'
+import {
+  CheckCircleIcon,
+  ArrowRightIcon,
+  BarChartIcon,
+  GlobeIcon,
+  ZapIcon,
+} from '@ciphera-net/ui'
+
+const TOTAL_STEPS = 5
+const DEFAULT_ORG_NAME = 'My workspace'
+
+function slugFromName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'my-workspace'
+}
+
+function WelcomeContent() {
+  const router = useRouter()
+  const searchParams = useSearchParams()
+  const { user, login } = useAuth()
+
+  const stepParam = searchParams.get('step')
+  const stepFromUrl = stepParam ? Math.min(Math.max(1, parseInt(stepParam, 10)), TOTAL_STEPS) : 1
+  const [step, setStepState] = useState(stepFromUrl)
+
+  const [orgName, setOrgName] = useState(DEFAULT_ORG_NAME)
+  const [orgSlug, setOrgSlug] = useState(slugFromName(DEFAULT_ORG_NAME))
+  const [orgLoading, setOrgLoading] = useState(false)
+  const [orgError, setOrgError] = useState('')
+
+  const [planLoading, setPlanLoading] = useState(false)
+  const [planError, setPlanError] = useState('')
+
+  const [siteName, setSiteName] = useState('')
+  const [siteDomain, setSiteDomain] = useState('')
+  const [siteLoading, setSiteLoading] = useState(false)
+  const [siteError, setSiteError] = useState('')
+  const [createdSite, setCreatedSite] = useState<Site | null>(null)
+
+  const [redirectingCheckout, setRedirectingCheckout] = useState(false)
+  const [hadPendingCheckout, setHadPendingCheckout] = useState<boolean | null>(null)
+  const [dismissedPendingCheckout, setDismissedPendingCheckout] = useState(false)
+
+  const setStep = useCallback(
+    (next: number) => {
+      const s = Math.min(Math.max(1, next), TOTAL_STEPS)
+      setStepState(s)
+      const url = new URL(window.location.href)
+      url.searchParams.set('step', String(s))
+      window.history.replaceState({}, '', url.pathname + url.search)
+    },
+    []
+  )
+
+  useEffect(() => {
+    const stepFromUrl = stepParam ? Math.min(Math.max(1, parseInt(stepParam, 10)), TOTAL_STEPS) : 1
+    if (stepFromUrl !== step) setStepState(stepFromUrl)
+  }, [stepParam, step])
+
+  // * If user already has orgs and no pending checkout, send to dashboard (avoid re-doing wizard)
+  useEffect(() => {
+    if (!user || step !== 1) return
+    let cancelled = false
+    getUserOrganizations()
+      .then((orgs) => {
+        if (cancelled || orgs.length === 0) return
+        if (!localStorage.getItem('pulse_pending_checkout')) {
+          router.replace('/')
+        }
+      })
+      .catch(() => {})
+    return () => {
+      cancelled = true
+    }
+  }, [user, step, router])
+
+  const handleNameChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const val = e.target.value
+    setOrgName(val)
+    setOrgSlug((prev) =>
+      prev === slugFromName(orgName) ? slugFromName(val) : prev
+    )
+  }
+
+  const handleWorkspaceSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setOrgLoading(true)
+    setOrgError('')
+    try {
+      const org = await createOrganization(orgName.trim(), orgSlug.trim())
+      const { access_token } = await switchContext(org.id)
+      const result = await setSessionAction(access_token)
+      if (result.success && result.user) {
+        login(result.user)
+        router.refresh()
+      }
+      setStep(3)
+    } catch (err: unknown) {
+      setOrgError(getAuthErrorMessage(err) || (err as Error)?.message || 'Failed to create workspace')
+    } finally {
+      setOrgLoading(false)
+    }
+  }
+
+  const handlePlanContinue = async () => {
+    const raw = localStorage.getItem('pulse_pending_checkout')
+    if (!raw) {
+      setStep(4)
+      return
+    }
+    setPlanLoading(true)
+    setPlanError('')
+    try {
+      const intent = JSON.parse(raw)
+      const { url } = await createCheckoutSession({
+        plan_id: intent.planId,
+        interval: intent.interval || 'month',
+        limit: intent.limit ?? 100000,
+      })
+      localStorage.removeItem('pulse_pending_checkout')
+      if (url) {
+        setRedirectingCheckout(true)
+        window.location.href = url
+        return
+      }
+      throw new Error('No checkout URL returned')
+    } catch (err: unknown) {
+      setPlanError(getAuthErrorMessage(err) || (err as Error)?.message || 'Failed to start checkout')
+      localStorage.removeItem('pulse_pending_checkout')
+    } finally {
+      setPlanLoading(false)
+    }
+  }
+
+  const handlePlanSkip = () => {
+    localStorage.removeItem('pulse_pending_checkout')
+    setDismissedPendingCheckout(true)
+    setStep(4)
+  }
+
+  const handleAddSite = async (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!siteName.trim() || !siteDomain.trim()) return
+    setSiteLoading(true)
+    setSiteError('')
+    try {
+      const site = await createSite({
+        name: siteName.trim(),
+        domain: siteDomain.trim().toLowerCase(),
+      })
+      setCreatedSite(site)
+      toast.success('Site added')
+      setStep(5)
+    } catch (err: unknown) {
+      setSiteError(getAuthErrorMessage(err) || (err as Error)?.message || 'Failed to add site')
+    } finally {
+      setSiteLoading(false)
+    }
+  }
+
+  const handleSkipSite = () => setStep(5)
+
+  const goToDashboard = () => router.push('/')
+  const goToSite = () => createdSite && router.push(`/sites/${createdSite.id}`)
+
+  const showPendingCheckoutInStep3 =
+    hadPendingCheckout === true && !dismissedPendingCheckout
+
+  useEffect(() => {
+    if (step === 3 && hadPendingCheckout === null && typeof window !== 'undefined') {
+      setHadPendingCheckout(!!localStorage.getItem('pulse_pending_checkout'))
+    }
+  }, [step, hadPendingCheckout])
+
+  if (orgLoading && step === 2) {
+    return <LoadingOverlay logoSrc="/pulse_icon_no_margins.png" title="Creating your workspace..." />
+  }
+
+  if (redirectingCheckout || (planLoading && step === 3)) {
+    return (
+      <LoadingOverlay
+        logoSrc="/pulse_icon_no_margins.png"
+        title={redirectingCheckout ? 'Taking you to checkout...' : 'Preparing your plan...'}
+      />
+    )
+  }
+
+  const cardClass =
+    'bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-800 rounded-2xl shadow-sm p-8 max-w-lg mx-auto'
+
+  return (
+    <div className="min-h-[80vh] flex flex-col items-center justify-center bg-neutral-50 dark:bg-neutral-950 px-4 py-12">
+      <div className="w-full max-w-lg">
+        <div className="flex justify-center gap-1.5 mb-8">
+          {Array.from({ length: TOTAL_STEPS }, (_, i) => (
+            <div
+              key={i}
+              className={`h-1.5 rounded-full transition-all duration-300 ${
+                i + 1 <= step
+                  ? 'bg-brand-orange w-8'
+                  : 'bg-neutral-200 dark:bg-neutral-700 w-6'
+              }`}
+              aria-hidden
+            />
+          ))}
+        </div>
+
+        <AnimatePresence mode="wait">
+          {step === 1 && (
+            <motion.div
+              key="step1"
+              initial={{ opacity: 0, y: 12 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -12 }}
+              transition={{ duration: 0.25 }}
+              className={cardClass}
+            >
+              <div className="text-center">
+                <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-6">
+                  <ZapIcon className="h-7 w-7" />
+                </div>
+                <h1 className="text-2xl font-bold text-neutral-900 dark:text-white">
+                  Welcome to Pulse
+                </h1>
+                <p className="mt-2 text-neutral-600 dark:text-neutral-400">
+                  Privacy-first analytics in a few steps. No credit card required to start.
+                </p>
+                <Button
+                  type="button"
+                  variant="primary"
+                  className="mt-8 w-full sm:w-auto min-w-[180px]"
+                  onClick={() => setStep(2)}
+                >
+                  Get started
+                  <ArrowRightIcon className="ml-2 h-4 w-4" />
+                </Button>
+              </div>
+            </motion.div>
+          )}
+
+          {step === 2 && (
+            <motion.div
+              key="step2"
+              initial={{ opacity: 0, y: 12 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -12 }}
+              transition={{ duration: 0.25 }}
+              className={cardClass}
+            >
+              <div className="text-center mb-6">
+                <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-4">
+                  <BarChartIcon className="h-7 w-7" />
+                </div>
+                <h2 className="text-xl font-bold text-neutral-900 dark:text-white">
+                  Name your workspace
+                </h2>
+                <p className="mt-1 text-sm text-neutral-600 dark:text-neutral-400">
+                  You can change this later in settings.
+                </p>
+              </div>
+              <form onSubmit={handleWorkspaceSubmit} className="space-y-4">
+                <div>
+                  <label htmlFor="welcome-org-name" className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
+                    Workspace name
+                  </label>
+                  <Input
+                    id="welcome-org-name"
+                    type="text"
+                    required
+                    placeholder="e.g. Acme Corp"
+                    value={orgName}
+                    onChange={handleNameChange}
+                    className="w-full"
+                  />
+                </div>
+                <div>
+                  <label htmlFor="welcome-org-slug" className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
+                    URL slug
+                  </label>
+                  <Input
+                    id="welcome-org-slug"
+                    type="text"
+                    required
+                    placeholder="acme-corp"
+                    value={orgSlug}
+                    onChange={(e) => setOrgSlug(e.target.value)}
+                    className="w-full"
+                  />
+                  <p className="mt-1 text-xs text-neutral-500 dark:text-neutral-400">
+                    Used in your workspace URL.
+                  </p>
+                </div>
+                {orgError && (
+                  <p className="text-sm text-red-500 dark:text-red-400">{orgError}</p>
+                )}
+                <Button type="submit" variant="primary" className="w-full" disabled={orgLoading}>
+                  Continue
+                </Button>
+              </form>
+            </motion.div>
+          )}
+
+          {step === 3 && (
+            <motion.div
+              key="step3"
+              initial={{ opacity: 0, y: 12 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -12 }}
+              transition={{ duration: 0.25 }}
+              className={cardClass}
+            >
+              <div className="text-center mb-6">
+                <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-green-500/10 text-green-600 dark:text-green-400 mb-4">
+                  <CheckCircleIcon className="h-7 w-7" />
+                </div>
+                <h2 className="text-xl font-bold text-neutral-900 dark:text-white">
+                  {showPendingCheckoutInStep3 ? 'Complete your plan' : "You're on the free plan"}
+                </h2>
+                <p className="mt-1 text-sm text-neutral-600 dark:text-neutral-400">
+                  {showPendingCheckoutInStep3
+                    ? 'You chose a plan on the pricing page. Continue to add a payment method and start your trial.'
+                    : 'Start with 1 site and 10k pageviews/month. Upgrade anytime from your dashboard.'}
+                </p>
+              </div>
+              {planError && (
+                <p className="text-sm text-red-500 dark:text-red-400 mb-4 text-center">{planError}</p>
+              )}
+              <div className="flex flex-col sm:flex-row gap-3 justify-center">
+                {showPendingCheckoutInStep3 ? (
+                  <>
+                    <Button
+                      variant="primary"
+                      className="w-full sm:w-auto"
+                      onClick={handlePlanContinue}
+                      disabled={planLoading}
+                    >
+                      Continue to checkout
+                    </Button>
+                    <Button
+                      variant="secondary"
+                      className="w-full sm:w-auto"
+                      onClick={handlePlanSkip}
+                      disabled={planLoading}
+                    >
+                      Stay on free plan
+                    </Button>
+                  </>
+                ) : (
+                  <Button
+                    variant="primary"
+                    className="w-full sm:w-auto"
+                    onClick={() => setStep(4)}
+                  >
+                    Continue
+                    <ArrowRightIcon className="ml-2 h-4 w-4" />
+                  </Button>
+                )}
+              </div>
+              {showPendingCheckoutInStep3 && (
+                <p className="mt-4 text-center">
+                  <button
+                    type="button"
+                    onClick={() => router.push('/pricing')}
+                    className="text-sm text-brand-orange hover:underline"
+                  >
+                    Choose a different plan
+                  </button>
+                </p>
+              )}
+            </motion.div>
+          )}
+
+          {step === 4 && (
+            <motion.div
+              key="step4"
+              initial={{ opacity: 0, y: 12 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -12 }}
+              transition={{ duration: 0.25 }}
+              className={cardClass}
+            >
+              <div className="text-center mb-6">
+                <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-4">
+                  <GlobeIcon className="h-7 w-7" />
+                </div>
+                <h2 className="text-xl font-bold text-neutral-900 dark:text-white">
+                  Add your first site
+                </h2>
+                <p className="mt-1 text-sm text-neutral-600 dark:text-neutral-400">
+                  Optional. You can add sites later from the dashboard.
+                </p>
+              </div>
+              <form onSubmit={handleAddSite} className="space-y-4">
+                <div>
+                  <label htmlFor="welcome-site-name" className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
+                    Site name
+                  </label>
+                  <Input
+                    id="welcome-site-name"
+                    type="text"
+                    placeholder="My Website"
+                    value={siteName}
+                    onChange={(e) => setSiteName(e.target.value)}
+                    className="w-full"
+                  />
+                </div>
+                <div>
+                  <label htmlFor="welcome-site-domain" className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
+                    Domain
+                  </label>
+                  <Input
+                    id="welcome-site-domain"
+                    type="text"
+                    placeholder="example.com"
+                    value={siteDomain}
+                    onChange={(e) => setSiteDomain(e.target.value.toLowerCase().trim())}
+                    className="w-full"
+                  />
+                  <p className="mt-1 text-xs text-neutral-500 dark:text-neutral-400">
+                    Without http:// or https://
+                  </p>
+                </div>
+                {siteError && (
+                  <p className="text-sm text-red-500 dark:text-red-400">{siteError}</p>
+                )}
+                <div className="flex flex-col sm:flex-row gap-3">
+                  <Button
+                    type="submit"
+                    variant="primary"
+                    className="flex-1"
+                    disabled={siteLoading || !siteName.trim() || !siteDomain.trim()}
+                    isLoading={siteLoading}
+                  >
+                    Add site
+                  </Button>
+                  <Button
+                    type="button"
+                    variant="secondary"
+                    className="flex-1"
+                    onClick={handleSkipSite}
+                    disabled={siteLoading}
+                  >
+                    Skip for now
+                  </Button>
+                </div>
+              </form>
+            </motion.div>
+          )}
+
+          {step === 5 && (
+            <motion.div
+              key="step5"
+              initial={{ opacity: 0, y: 12 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -12 }}
+              transition={{ duration: 0.25 }}
+              className={cardClass}
+            >
+              <div className="text-center">
+                <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-green-500/10 text-green-600 dark:text-green-400 mb-6">
+                  <CheckCircleIcon className="h-7 w-7" />
+                </div>
+                <h2 className="text-2xl font-bold text-neutral-900 dark:text-white">
+                  You're all set
+                </h2>
+                <p className="mt-2 text-neutral-600 dark:text-neutral-400">
+                  {createdSite
+                    ? `"${createdSite.name}" is ready. Add the script to your site to start collecting data.`
+                    : 'Head to your dashboard to add sites and view analytics.'}
+                </p>
+                <div className="mt-8 flex flex-col sm:flex-row gap-3 justify-center">
+                  <Button variant="primary" onClick={goToDashboard} className="min-w-[160px]">
+                    Go to dashboard
+                  </Button>
+                  {createdSite && (
+                    <Button variant="secondary" onClick={goToSite} className="min-w-[160px]">
+                      View {createdSite.name}
+                    </Button>
+                  )}
+                </div>
+              </div>
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </div>
+    </div>
+  )
+}
+
+export default function WelcomePage() {
+  return (
+    <Suspense fallback={<LoadingOverlay logoSrc="/pulse_icon_no_margins.png" title="Pulse" />}>
+      <WelcomeContent />
+    </Suspense>
+  )
+}
diff --git a/lib/auth/context.tsx b/lib/auth/context.tsx
index fc9fdad..bf4bcd4 100644
--- a/lib/auth/context.tsx
+++ b/lib/auth/context.tsx
@@ -130,18 +130,15 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   useEffect(() => {
     const checkOrg = async () => {
       if (!loading && user) {
-        // * If we are on onboarding, skip check
         if (pathname?.startsWith('/onboarding')) return
-        
-        // * If we are processing auth callback, skip check to avoid redirect loops
         if (pathname?.startsWith('/auth/callback')) return
 
         try {
           const organizations = await getUserOrganizations()
-          
+
           if (organizations.length === 0) {
-            // * No organizations -> Redirect to Onboarding
-            router.push('/onboarding')
+            if (pathname?.startsWith('/welcome')) return
+            router.push('/welcome')
             return
           }
 

From 58cfb6210b985788f071025846fee22225c19cf0 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 14:09:54 +0100
Subject: [PATCH 2/9] feat: add setup banner and site addition prompt to
 homepage; enhance welcome page with tracking and error handling

---
 app/page.tsx                  |  62 ++++++++++++++-
 app/welcome/page.tsx          | 141 ++++++++++++++++++++++++++++++----
 components/sites/SiteList.tsx |   7 +-
 lib/welcomeAnalytics.ts       |  72 +++++++++++++++++
 4 files changed, 267 insertions(+), 15 deletions(-)
 create mode 100644 lib/welcomeAnalytics.ts

diff --git a/app/page.tsx b/app/page.tsx
index a620a5e..35119cb 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -10,7 +10,7 @@ import { getSubscription, type SubscriptionDetails } from '@/lib/api/billing'
 import { LoadingOverlay } from '@ciphera-net/ui'
 import SiteList from '@/components/sites/SiteList'
 import { Button } from '@ciphera-net/ui'
-import { BarChartIcon, LockIcon, ZapIcon, CheckCircleIcon, XIcon } from '@ciphera-net/ui'
+import { BarChartIcon, LockIcon, ZapIcon, CheckCircleIcon, XIcon, GlobeIcon } from '@ciphera-net/ui'
 import { toast } from '@ciphera-net/ui'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
 
@@ -102,6 +102,7 @@ export default function HomePage() {
   const [sitesLoading, setSitesLoading] = useState(true)
   const [subscription, setSubscription] = useState<SubscriptionDetails | null>(null)
   const [subscriptionLoading, setSubscriptionLoading] = useState(false)
+  const [showFinishSetupBanner, setShowFinishSetupBanner] = useState(true)
 
   useEffect(() => {
     if (user?.org_id) {
@@ -110,6 +111,22 @@ export default function HomePage() {
     }
   }, [user])
 
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    if (localStorage.getItem('pulse_welcome_completed') === 'true') setShowFinishSetupBanner(false)
+  }, [user?.org_id])
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const params = new URLSearchParams(window.location.search)
+    if (params.get('trial_started') === '1') {
+      toast.success('Your trial is active. You can add sites and start tracking.')
+      params.delete('trial_started')
+      const newUrl = params.toString() ? `${window.location.pathname}?${params}` : window.location.pathname
+      window.history.replaceState({}, '', newUrl)
+    }
+  }, [])
+
   const loadSites = async () => {
     try {
       setSitesLoading(true)
@@ -289,6 +306,32 @@ export default function HomePage() {
 
   return (
     <div className="w-full max-w-6xl mx-auto px-4 sm:px-6 py-8">
+      {showFinishSetupBanner && (
+        <div className="mb-6 flex items-center justify-between gap-4 rounded-2xl border border-brand-orange/30 bg-brand-orange/5 px-4 py-3 dark:bg-brand-orange/10">
+          <p className="text-sm text-neutral-700 dark:text-neutral-300">
+            Finish setting up your workspace and add your first site.
+          </p>
+          <div className="flex items-center gap-2 flex-shrink-0">
+            <Link href="/welcome?step=5">
+              <Button variant="primary" className="text-sm">
+                Finish setup
+              </Button>
+            </Link>
+            <button
+              type="button"
+              onClick={() => {
+                if (typeof window !== 'undefined') localStorage.setItem('pulse_welcome_completed', 'true')
+                setShowFinishSetupBanner(false)
+              }}
+              className="text-neutral-500 hover:text-neutral-700 dark:hover:text-neutral-400 p-1 rounded"
+              aria-label="Dismiss"
+            >
+              <XIcon className="h-4 w-4" />
+            </button>
+          </div>
+        </div>
+      )}
+
       <div className="mb-8 flex items-center justify-between">
         <div>
           <h1 className="text-2xl font-bold text-neutral-900 dark:text-white">Your Sites</h1>
@@ -371,6 +414,23 @@ export default function HomePage() {
         </div>
       </div>
 
+      {!sitesLoading && sites.length === 0 && (
+        <div className="mb-8 rounded-2xl border-2 border-dashed border-brand-orange/30 bg-brand-orange/5 p-8 text-center dark:bg-brand-orange/10">
+          <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/20 text-brand-orange mb-4">
+            <GlobeIcon className="h-7 w-7" />
+          </div>
+          <h2 className="text-xl font-bold text-neutral-900 dark:text-white mb-2">Add your first site</h2>
+          <p className="text-neutral-600 dark:text-neutral-400 mb-6 max-w-md mx-auto">
+            Connect a domain to start collecting privacy-friendly analytics. You can add more sites later from the dashboard.
+          </p>
+          <Link href="/sites/new">
+            <Button variant="primary" className="min-w-[180px]">
+              Add your first site
+            </Button>
+          </Link>
+        </div>
+      )}
+
       <SiteList sites={sites} loading={sitesLoading} onDelete={handleDelete} />
     </div>
   )
diff --git a/app/welcome/page.tsx b/app/welcome/page.tsx
index 42e8363..dc93780 100644
--- a/app/welcome/page.tsx
+++ b/app/welcome/page.tsx
@@ -20,23 +20,56 @@ import { createSite, type Site } from '@/lib/api/sites'
 import { setSessionAction } from '@/app/actions/auth'
 import { useAuth } from '@/lib/auth/context'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
+import {
+  trackWelcomeStepView,
+  trackWelcomeWorkspaceCreated,
+  trackWelcomePlanContinue,
+  trackWelcomePlanSkip,
+  trackWelcomeSiteAdded,
+  trackWelcomeSiteSkipped,
+  trackWelcomeCompleted,
+} from '@/lib/welcomeAnalytics'
 import { LoadingOverlay, Button, Input } from '@ciphera-net/ui'
 import { toast } from '@ciphera-net/ui'
 import {
   CheckCircleIcon,
   ArrowRightIcon,
+  ArrowLeftIcon,
   BarChartIcon,
   GlobeIcon,
   ZapIcon,
 } from '@ciphera-net/ui'
+import Link from 'next/link'
 
 const TOTAL_STEPS = 5
 const DEFAULT_ORG_NAME = 'My workspace'
+const SITE_DRAFT_KEY = 'pulse_welcome_site_draft'
+const WELCOME_COMPLETED_KEY = 'pulse_welcome_completed'
 
 function slugFromName(name: string): string {
   return name.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'my-workspace'
 }
 
+function suggestSlugVariant(slug: string): string {
+  const m = slug.match(/^(.+?)(-\d+)?$/)
+  if (!m) return `${slug}-2`
+  const base = m[1]
+  const num = m[2] ? parseInt(m[2].slice(1), 10) : 0
+  return `${base}-${num + 2}`
+}
+
+function getOrgErrorMessage(err: unknown, currentSlug: string, fallback: string): { message: string; suggestSlug?: string } {
+  const apiErr = err as { data?: { message?: string }; message?: string }
+  const raw = apiErr?.data?.message || apiErr?.message || ''
+  if (/slug|already|taken|duplicate|exists/i.test(raw)) {
+    return {
+      message: 'This URL slug is already in use. Try a different one.',
+      suggestSlug: suggestSlugVariant(currentSlug),
+    }
+  }
+  return { message: getAuthErrorMessage(err) || (err as Error)?.message || fallback }
+}
+
 function WelcomeContent() {
   const router = useRouter()
   const searchParams = useSearchParams()
@@ -117,9 +150,12 @@ function WelcomeContent() {
         login(result.user)
         router.refresh()
       }
+      trackWelcomeWorkspaceCreated(!!(typeof window !== 'undefined' && localStorage.getItem('pulse_pending_checkout')))
       setStep(3)
     } catch (err: unknown) {
-      setOrgError(getAuthErrorMessage(err) || (err as Error)?.message || 'Failed to create workspace')
+      const { message, suggestSlug } = getOrgErrorMessage(err, orgSlug, 'Failed to create workspace')
+      setOrgError(message)
+      if (suggestSlug) setOrgSlug(suggestSlug)
     } finally {
       setOrgLoading(false)
     }
@@ -134,6 +170,7 @@ function WelcomeContent() {
     setPlanLoading(true)
     setPlanError('')
     try {
+      trackWelcomePlanContinue()
       const intent = JSON.parse(raw)
       const { url } = await createCheckoutSession({
         plan_id: intent.planId,
@@ -156,6 +193,7 @@ function WelcomeContent() {
   }
 
   const handlePlanSkip = () => {
+    trackWelcomePlanSkip()
     localStorage.removeItem('pulse_pending_checkout')
     setDismissedPendingCheckout(true)
     setStep(4)
@@ -172,6 +210,8 @@ function WelcomeContent() {
         domain: siteDomain.trim().toLowerCase(),
       })
       setCreatedSite(site)
+      if (typeof window !== 'undefined') sessionStorage.removeItem(SITE_DRAFT_KEY)
+      trackWelcomeSiteAdded()
       toast.success('Site added')
       setStep(5)
     } catch (err: unknown) {
@@ -181,9 +221,17 @@ function WelcomeContent() {
     }
   }
 
-  const handleSkipSite = () => setStep(5)
+  const handleSkipSite = () => {
+    trackWelcomeSiteSkipped()
+    if (typeof window !== 'undefined') sessionStorage.removeItem(SITE_DRAFT_KEY)
+    setStep(5)
+  }
 
-  const goToDashboard = () => router.push('/')
+  const goToDashboard = () => {
+    if (typeof window !== 'undefined') localStorage.setItem(WELCOME_COMPLETED_KEY, 'true')
+    trackWelcomeCompleted(!!createdSite)
+    router.push('/')
+  }
   const goToSite = () => createdSite && router.push(`/sites/${createdSite.id}`)
 
   const showPendingCheckoutInStep3 =
@@ -195,6 +243,31 @@ function WelcomeContent() {
     }
   }, [step, hadPendingCheckout])
 
+  useEffect(() => {
+    trackWelcomeStepView(step)
+  }, [step])
+
+  // * Restore first-site draft from sessionStorage
+  useEffect(() => {
+    if (step !== 4 || typeof window === 'undefined') return
+    try {
+      const raw = sessionStorage.getItem(SITE_DRAFT_KEY)
+      if (raw) {
+        const d = JSON.parse(raw) as { name?: string; domain?: string }
+        if (d.name) setSiteName(d.name)
+        if (d.domain) setSiteDomain(d.domain)
+      }
+    } catch {
+      // ignore
+    }
+  }, [step])
+
+  // * Persist first-site draft to sessionStorage
+  useEffect(() => {
+    if (step !== 4 || typeof window === 'undefined') return
+    sessionStorage.setItem(SITE_DRAFT_KEY, JSON.stringify({ name: siteName, domain: siteDomain }))
+  }, [step, siteName, siteDomain])
+
   if (orgLoading && step === 2) {
     return <LoadingOverlay logoSrc="/pulse_icon_no_margins.png" title="Creating your workspace..." />
   }
@@ -214,7 +287,14 @@ function WelcomeContent() {
   return (
     <div className="min-h-[80vh] flex flex-col items-center justify-center bg-neutral-50 dark:bg-neutral-950 px-4 py-12">
       <div className="w-full max-w-lg">
-        <div className="flex justify-center gap-1.5 mb-8">
+        <div
+          className="flex justify-center gap-1.5 mb-8"
+          role="progressbar"
+          aria-valuenow={step}
+          aria-valuemin={1}
+          aria-valuemax={TOTAL_STEPS}
+          aria-label={`Step ${step} of ${TOTAL_STEPS}`}
+        >
           {Array.from({ length: TOTAL_STEPS }, (_, i) => (
             <div
               key={i}
@@ -223,7 +303,8 @@ function WelcomeContent() {
                   ? 'bg-brand-orange w-8'
                   : 'bg-neutral-200 dark:bg-neutral-700 w-6'
               }`}
-              aria-hidden
+              aria-current={i + 1 === step ? 'step' : undefined}
+              aria-label={`Step ${i + 1} of ${TOTAL_STEPS}`}
             />
           ))}
         </div>
@@ -270,6 +351,15 @@ function WelcomeContent() {
               transition={{ duration: 0.25 }}
               className={cardClass}
             >
+              <button
+                type="button"
+                onClick={() => setStep(1)}
+                className="flex items-center gap-1.5 text-sm text-neutral-500 dark:text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-300 mb-6"
+                aria-label="Back to welcome"
+              >
+                <ArrowLeftIcon className="h-4 w-4" />
+                Back
+              </button>
               <div className="text-center mb-6">
                 <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-4">
                   <BarChartIcon className="h-7 w-7" />
@@ -332,6 +422,15 @@ function WelcomeContent() {
               transition={{ duration: 0.25 }}
               className={cardClass}
             >
+              <button
+                type="button"
+                onClick={() => setStep(2)}
+                className="flex items-center gap-1.5 text-sm text-neutral-500 dark:text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-300 mb-6"
+                aria-label="Back to workspace"
+              >
+                <ArrowLeftIcon className="h-4 w-4" />
+                Back
+              </button>
               <div className="text-center mb-6">
                 <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-green-500/10 text-green-600 dark:text-green-400 mb-4">
                   <CheckCircleIcon className="h-7 w-7" />
@@ -369,14 +468,21 @@ function WelcomeContent() {
                     </Button>
                   </>
                 ) : (
-                  <Button
-                    variant="primary"
-                    className="w-full sm:w-auto"
-                    onClick={() => setStep(4)}
-                  >
-                    Continue
-                    <ArrowRightIcon className="ml-2 h-4 w-4" />
-                  </Button>
+                  <>
+                    <Button
+                      variant="primary"
+                      className="w-full sm:w-auto"
+                      onClick={() => setStep(4)}
+                    >
+                      Continue
+                      <ArrowRightIcon className="ml-2 h-4 w-4" />
+                    </Button>
+                    <p className="mt-4 text-center">
+                      <Link href="/pricing" className="text-sm text-brand-orange hover:underline">
+                        View pricing
+                      </Link>
+                    </p>
+                  </>
                 )}
               </div>
               {showPendingCheckoutInStep3 && (
@@ -402,6 +508,15 @@ function WelcomeContent() {
               transition={{ duration: 0.25 }}
               className={cardClass}
             >
+              <button
+                type="button"
+                onClick={() => setStep(3)}
+                className="flex items-center gap-1.5 text-sm text-neutral-500 dark:text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-300 mb-6"
+                aria-label="Back to plan"
+              >
+                <ArrowLeftIcon className="h-4 w-4" />
+                Back
+              </button>
               <div className="text-center mb-6">
                 <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-4">
                   <GlobeIcon className="h-7 w-7" />
diff --git a/components/sites/SiteList.tsx b/components/sites/SiteList.tsx
index 37bf960..b88004f 100644
--- a/components/sites/SiteList.tsx
+++ b/components/sites/SiteList.tsx
@@ -28,7 +28,12 @@ export default function SiteList({ sites, loading, onDelete }: SiteListProps) {
     return (
       <div className="rounded-lg border border-dashed border-neutral-300 dark:border-neutral-700 p-12 text-center">
         <h3 className="text-lg font-semibold text-neutral-900 dark:text-white">No sites yet</h3>
-        <p className="mt-2 text-sm text-neutral-500 dark:text-neutral-400">Create your first site to get started.</p>
+        <p className="mt-2 text-sm text-neutral-500 dark:text-neutral-400 mb-4">Create your first site to get started.</p>
+        <Link href="/sites/new">
+          <Button variant="primary" className="text-sm">
+            Add your first site
+          </Button>
+        </Link>
       </div>
     )
   }
diff --git a/lib/welcomeAnalytics.ts b/lib/welcomeAnalytics.ts
new file mode 100644
index 0000000..d0887bf
--- /dev/null
+++ b/lib/welcomeAnalytics.ts
@@ -0,0 +1,72 @@
+/**
+ * Welcome/onboarding analytics. Emits custom events for step views and actions
+ * so drop-off and funnel can be measured. Listen for 'pulse_welcome' or use
+ * the payload with your analytics backend.
+ */
+
+export type WelcomeEventName =
+  | 'welcome_step_view'
+  | 'welcome_workspace_created'
+  | 'welcome_plan_continue'
+  | 'welcome_plan_skip'
+  | 'welcome_site_added'
+  | 'welcome_site_skipped'
+  | 'welcome_completed'
+
+export interface WelcomeEventPayload {
+  event: WelcomeEventName
+  step?: number
+  /** For workspace_created: has pending checkout */
+  had_pending_checkout?: boolean
+  /** For site_added: whether user added a site in wizard */
+  added_site?: boolean
+}
+
+const STORAGE_KEY = 'pulse_welcome_events'
+
+function emit(event: WelcomeEventName, payload: Omit<WelcomeEventPayload, 'event'> = {}) {
+  const full: WelcomeEventPayload = { event, ...payload }
+  if (typeof window === 'undefined') return
+  try {
+    window.dispatchEvent(
+      new CustomEvent('pulse_welcome', { detail: full })
+    )
+    if (process.env.NODE_ENV === 'development') {
+      // eslint-disable-next-line no-console
+      console.debug('[Pulse Welcome]', full)
+    }
+    const queue = JSON.parse(sessionStorage.getItem(STORAGE_KEY) || '[]')
+    queue.push({ ...full, ts: Date.now() })
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(queue.slice(-50)))
+  } catch {
+    // ignore
+  }
+}
+
+export function trackWelcomeStepView(step: number) {
+  emit('welcome_step_view', { step })
+}
+
+export function trackWelcomeWorkspaceCreated(hadPendingCheckout: boolean) {
+  emit('welcome_workspace_created', { had_pending_checkout: hadPendingCheckout })
+}
+
+export function trackWelcomePlanContinue() {
+  emit('welcome_plan_continue')
+}
+
+export function trackWelcomePlanSkip() {
+  emit('welcome_plan_skip')
+}
+
+export function trackWelcomeSiteAdded() {
+  emit('welcome_site_added', { added_site: true })
+}
+
+export function trackWelcomeSiteSkipped() {
+  emit('welcome_site_skipped')
+}
+
+export function trackWelcomeCompleted(addedSite: boolean) {
+  emit('welcome_completed', { added_site: addedSite })
+}

From a211193277ecd8e37653db6c73a026685ef4ebe5 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 14:21:38 +0100
Subject: [PATCH 3/9] feat: enhance welcome page with organization selection
 and workspace switching functionality

---
 app/welcome/page.tsx    | 134 ++++++++++++++++++++++++++++++++--------
 lib/welcomeAnalytics.ts |   5 ++
 2 files changed, 113 insertions(+), 26 deletions(-)

diff --git a/app/welcome/page.tsx b/app/welcome/page.tsx
index dc93780..f182db3 100644
--- a/app/welcome/page.tsx
+++ b/app/welcome/page.tsx
@@ -14,6 +14,7 @@ import {
   getUserOrganizations,
   switchContext,
   type Organization,
+  type OrganizationMember,
 } from '@/lib/api/organization'
 import { createCheckoutSession } from '@/lib/api/billing'
 import { createSite, type Site } from '@/lib/api/sites'
@@ -22,6 +23,7 @@ import { useAuth } from '@/lib/auth/context'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
 import {
   trackWelcomeStepView,
+  trackWelcomeWorkspaceSelected,
   trackWelcomeWorkspaceCreated,
   trackWelcomePlanContinue,
   trackWelcomePlanSkip,
@@ -38,6 +40,7 @@ import {
   BarChartIcon,
   GlobeIcon,
   ZapIcon,
+  PlusIcon,
 } from '@ciphera-net/ui'
 import Link from 'next/link'
 
@@ -97,6 +100,10 @@ function WelcomeContent() {
   const [hadPendingCheckout, setHadPendingCheckout] = useState<boolean | null>(null)
   const [dismissedPendingCheckout, setDismissedPendingCheckout] = useState(false)
 
+  const [organizations, setOrganizations] = useState<OrganizationMember[] | null>(null)
+  const [orgsLoading, setOrgsLoading] = useState(false)
+  const [switchingOrgId, setSwitchingOrgId] = useState<string | null>(null)
+
   const setStep = useCallback(
     (next: number) => {
       const s = Math.min(Math.max(1, next), TOTAL_STEPS)
@@ -113,22 +120,45 @@ function WelcomeContent() {
     if (stepFromUrl !== step) setStepState(stepFromUrl)
   }, [stepParam, step])
 
-  // * If user already has orgs and no pending checkout, send to dashboard (avoid re-doing wizard)
+  // * Fetch organizations when on step 1 so we can show "Choose workspace" when user has orgs
   useEffect(() => {
     if (!user || step !== 1) return
     let cancelled = false
+    setOrgsLoading(true)
     getUserOrganizations()
       .then((orgs) => {
-        if (cancelled || orgs.length === 0) return
-        if (!localStorage.getItem('pulse_pending_checkout')) {
-          router.replace('/')
-        }
+        if (!cancelled) setOrganizations(orgs || [])
+      })
+      .catch(() => {
+        if (!cancelled) setOrganizations([])
+      })
+      .finally(() => {
+        if (!cancelled) setOrgsLoading(false)
       })
-      .catch(() => {})
     return () => {
       cancelled = true
     }
-  }, [user, step, router])
+  }, [user, step])
+
+  const handleSelectWorkspace = async (org: OrganizationMember) => {
+    setSwitchingOrgId(org.organization_id)
+    try {
+      const { access_token } = await switchContext(org.organization_id)
+      const result = await setSessionAction(access_token)
+      if (result.success && result.user) {
+        login(result.user)
+        router.refresh()
+        trackWelcomeWorkspaceSelected()
+        setStep(3)
+      }
+    } catch (err) {
+      toast.error(getAuthErrorMessage(err) || 'Failed to switch workspace')
+    } finally {
+      setSwitchingOrgId(null)
+    }
+  }
+
+  const handleCreateNewWorkspace = () => setStep(2)
 
   const handleNameChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const val = e.target.value
@@ -272,6 +302,10 @@ function WelcomeContent() {
     return <LoadingOverlay logoSrc="/pulse_icon_no_margins.png" title="Creating your workspace..." />
   }
 
+  if (switchingOrgId) {
+    return <LoadingOverlay logoSrc="/pulse_icon_no_margins.png" title="Switching workspace..." />
+  }
+
   if (redirectingCheckout || (planLoading && step === 3)) {
     return (
       <LoadingOverlay
@@ -319,26 +353,74 @@ function WelcomeContent() {
               transition={{ duration: 0.25 }}
               className={cardClass}
             >
-              <div className="text-center">
-                <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-6">
-                  <ZapIcon className="h-7 w-7" />
+              {orgsLoading ? (
+                <div className="text-center py-8">
+                  <p className="text-neutral-600 dark:text-neutral-400">Loading your workspaces...</p>
                 </div>
-                <h1 className="text-2xl font-bold text-neutral-900 dark:text-white">
-                  Welcome to Pulse
-                </h1>
-                <p className="mt-2 text-neutral-600 dark:text-neutral-400">
-                  Privacy-first analytics in a few steps. No credit card required to start.
-                </p>
-                <Button
-                  type="button"
-                  variant="primary"
-                  className="mt-8 w-full sm:w-auto min-w-[180px]"
-                  onClick={() => setStep(2)}
-                >
-                  Get started
-                  <ArrowRightIcon className="ml-2 h-4 w-4" />
-                </Button>
-              </div>
+              ) : organizations && organizations.length > 0 ? (
+                <>
+                  <div className="text-center mb-6">
+                    <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-4">
+                      <BarChartIcon className="h-7 w-7" />
+                    </div>
+                    <h2 className="text-xl font-bold text-neutral-900 dark:text-white">
+                      Choose your workspace
+                    </h2>
+                    <p className="mt-1 text-sm text-neutral-600 dark:text-neutral-400">
+                      Continue with an existing workspace or create a new one.
+                    </p>
+                  </div>
+                  <div className="space-y-2 mb-6">
+                    {organizations.map((org) => (
+                      <button
+                        key={org.organization_id}
+                        type="button"
+                        onClick={() => handleSelectWorkspace(org)}
+                        disabled={!!switchingOrgId}
+                        className="w-full flex items-center justify-between gap-3 rounded-xl border border-neutral-200 dark:border-neutral-700 bg-neutral-50 dark:bg-neutral-800/50 hover:bg-neutral-100 dark:hover:bg-neutral-800 hover:border-brand-orange/50 px-4 py-3 text-left transition-colors disabled:opacity-60"
+                      >
+                        <span className="font-medium text-neutral-900 dark:text-white">
+                          {org.organization_name || 'Workspace'}
+                        </span>
+                        {user?.org_id === org.organization_id && (
+                          <span className="text-xs text-neutral-500 dark:text-neutral-400">Current</span>
+                        )}
+                        <ArrowRightIcon className="h-4 w-4 text-neutral-400 flex-shrink-0" />
+                      </button>
+                    ))}
+                  </div>
+                  <Button
+                    type="button"
+                    variant="secondary"
+                    className="w-full"
+                    onClick={handleCreateNewWorkspace}
+                  >
+                    <PlusIcon className="h-4 w-4 mr-2" />
+                    Create a new workspace
+                  </Button>
+                </>
+              ) : (
+                <div className="text-center">
+                  <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-brand-orange/10 text-brand-orange mb-6">
+                    <ZapIcon className="h-7 w-7" />
+                  </div>
+                  <h1 className="text-2xl font-bold text-neutral-900 dark:text-white">
+                    Welcome to Pulse
+                  </h1>
+                  <p className="mt-2 text-neutral-600 dark:text-neutral-400">
+                    Privacy-first analytics in a few steps. No credit card required to start.
+                  </p>
+                  <Button
+                    type="button"
+                    variant="primary"
+                    className="mt-8 w-full sm:w-auto min-w-[180px]"
+                    onClick={() => setStep(2)}
+                  >
+                    Get started
+                    <ArrowRightIcon className="ml-2 h-4 w-4" />
+                  </Button>
+                </div>
+              )}
             </motion.div>
           )}
 
diff --git a/lib/welcomeAnalytics.ts b/lib/welcomeAnalytics.ts
index d0887bf..9f1ee71 100644
--- a/lib/welcomeAnalytics.ts
+++ b/lib/welcomeAnalytics.ts
@@ -6,6 +6,7 @@
 
 export type WelcomeEventName =
   | 'welcome_step_view'
+  | 'welcome_workspace_selected'
   | 'welcome_workspace_created'
   | 'welcome_plan_continue'
   | 'welcome_plan_skip'
@@ -47,6 +48,10 @@ export function trackWelcomeStepView(step: number) {
   emit('welcome_step_view', { step })
 }
 
+export function trackWelcomeWorkspaceSelected() {
+  emit('welcome_workspace_selected')
+}
+
 export function trackWelcomeWorkspaceCreated(hadPendingCheckout: boolean) {
   emit('welcome_workspace_created', { had_pending_checkout: hadPendingCheckout })
 }

From 30dcd5ddbc1a48b883f0f2ce9cf259186af65112 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 14:29:33 +0100
Subject: [PATCH 4/9] fix: update auth callback routing to redirect to
 '/welcome' for pending checkouts

---
 app/auth/callback/page.tsx | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/app/auth/callback/page.tsx b/app/auth/callback/page.tsx
index 0537e22..631d19e 100644
--- a/app/auth/callback/page.tsx
+++ b/app/auth/callback/page.tsx
@@ -52,8 +52,12 @@ function AuthCallbackContent() {
         const result = await setSessionAction(token, refreshToken)
         if (result.success && result.user) {
           login(result.user)
-          const returnTo = searchParams.get('returnTo') || '/'
-          router.push(returnTo)
+          if (typeof window !== 'undefined' && localStorage.getItem('pulse_pending_checkout')) {
+            router.push('/welcome')
+          } else {
+            const returnTo = searchParams.get('returnTo') || '/'
+            router.push(returnTo)
+          }
         } else {
           setError(authMessageFromErrorType('invalid'))
         }

From b5f95a8abcd6f14df675cb4bc131e9036d185169 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 14:42:52 +0100
Subject: [PATCH 5/9] feat: add integration setup options and script copying
 functionality to welcome page

---
 app/welcome/page.tsx | 102 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 94 insertions(+), 8 deletions(-)

diff --git a/app/welcome/page.tsx b/app/welcome/page.tsx
index f182db3..691780a 100644
--- a/app/welcome/page.tsx
+++ b/app/welcome/page.tsx
@@ -21,6 +21,8 @@ import { createSite, type Site } from '@/lib/api/sites'
 import { setSessionAction } from '@/app/actions/auth'
 import { useAuth } from '@/lib/auth/context'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
+import { API_URL, APP_URL } from '@/lib/api/client'
+import { integrations, getIntegration } from '@/lib/integrations'
 import {
   trackWelcomeStepView,
   trackWelcomeWorkspaceSelected,
@@ -35,6 +37,7 @@ import { LoadingOverlay, Button, Input } from '@ciphera-net/ui'
 import { toast } from '@ciphera-net/ui'
 import {
   CheckCircleIcon,
+  CheckIcon,
   ArrowRightIcon,
   ArrowLeftIcon,
   BarChartIcon,
@@ -104,6 +107,9 @@ function WelcomeContent() {
   const [orgsLoading, setOrgsLoading] = useState(false)
   const [switchingOrgId, setSwitchingOrgId] = useState<string | null>(null)
 
+  const [selectedIntegrationSlug, setSelectedIntegrationSlug] = useState<string | null>(null)
+  const [scriptCopied, setScriptCopied] = useState(false)
+
   const setStep = useCallback(
     (next: number) => {
       const s = Math.min(Math.max(1, next), TOTAL_STEPS)
@@ -264,6 +270,17 @@ function WelcomeContent() {
   }
   const goToSite = () => createdSite && router.push(`/sites/${createdSite.id}`)
 
+  const copyScript = useCallback(() => {
+    if (!createdSite) return
+    const script = `<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
+    navigator.clipboard.writeText(script)
+    setScriptCopied(true)
+    toast.success('Script copied to clipboard')
+    setTimeout(() => setScriptCopied(false), 2000)
+  }, [createdSite])
+
+  const popularIntegrations = integrations.filter((i) => i.category === 'framework').slice(0, 10)
+
   const showPendingCheckoutInStep3 =
     hadPendingCheckout === true && !dismissedPendingCheckout
 
@@ -688,16 +705,85 @@ function WelcomeContent() {
                     ? `"${createdSite.name}" is ready. Add the script to your site to start collecting data.`
                     : 'Head to your dashboard to add sites and view analytics.'}
                 </p>
-                <div className="mt-8 flex flex-col sm:flex-row gap-3 justify-center">
-                  <Button variant="primary" onClick={goToDashboard} className="min-w-[160px]">
-                    Go to dashboard
-                  </Button>
-                  {createdSite && (
-                    <Button variant="secondary" onClick={goToSite} className="min-w-[160px]">
-                      View {createdSite.name}
-                    </Button>
+              </div>
+
+              {createdSite && (
+                <div className="mt-6 pt-6 border-t border-neutral-200 dark:border-neutral-700">
+                  <h3 className="text-sm font-semibold text-neutral-900 dark:text-white mb-1">
+                    Add the script to your site
+                  </h3>
+                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
+                    Choose your framework for setup instructions.
+                  </p>
+                  <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mb-4">
+                    {popularIntegrations.map((int) => (
+                      <button
+                        key={int.id}
+                        type="button"
+                        onClick={() => setSelectedIntegrationSlug(selectedIntegrationSlug === int.id ? null : int.id)}
+                        className={`flex items-center gap-2 rounded-lg border px-3 py-2.5 text-left text-sm transition-colors ${
+                          selectedIntegrationSlug === int.id
+                            ? 'border-brand-orange bg-brand-orange/10 text-brand-orange'
+                            : 'border-neutral-200 dark:border-neutral-700 bg-neutral-50 dark:bg-neutral-800/50 hover:bg-neutral-100 dark:hover:bg-neutral-800 text-neutral-700 dark:text-neutral-300'
+                        }`}
+                      >
+                        <span className="[&_svg]:h-4 [&_svg]:w-4 [&_svg]:shrink-0 flex items-center justify-center">
+                          {int.icon}
+                        </span>
+                        <span className="truncate font-medium">{int.name}</span>
+                      </button>
+                    ))}
+                  </div>
+                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">
+                    <Link href="/integrations" className="text-brand-orange hover:underline">
+                      View all integrations →
+                    </Link>
+                  </p>
+
+                  <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
+                    <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
+                      {`<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
+                    </code>
+                    <button
+                      type="button"
+                      onClick={copyScript}
+                      className="absolute top-2 right-2 p-2 bg-white dark:bg-neutral-700 rounded-lg shadow-sm hover:bg-neutral-50 dark:hover:bg-neutral-600 transition-colors"
+                      title="Copy script"
+                    >
+                      {scriptCopied ? (
+                        <CheckIcon className="w-4 h-4 text-green-500" />
+                      ) : (
+                        <svg className="w-4 h-4 text-neutral-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                          <rect x="9" y="9" width="13" height="13" rx="2" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+                          <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+                        </svg>
+                      )}
+                    </button>
+                  </div>
+                  {selectedIntegrationSlug && getIntegration(selectedIntegrationSlug) && (
+                    <p className="mt-3 text-xs">
+                      <Link
+                        href={`/integrations/${selectedIntegrationSlug}`}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="text-brand-orange hover:underline"
+                      >
+                        See full {getIntegration(selectedIntegrationSlug)!.name} guide →
+                      </Link>
+                    </p>
                   )}
                 </div>
+              )}
+
+              <div className="mt-8 flex flex-col sm:flex-row gap-3 justify-center">
+                <Button variant="primary" onClick={goToDashboard} className="min-w-[160px]">
+                  Go to dashboard
+                </Button>
+                {createdSite && (
+                  <Button variant="secondary" onClick={goToSite} className="min-w-[160px]">
+                    View {createdSite.name}
+                  </Button>
+                )}
               </div>
             </motion.div>
           )}

From a7933443ef026583445110958d5fd74f3b46a247 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 14:50:03 +0100
Subject: [PATCH 6/9] fix: update link in welcome page to open integrations in
 a new tab with appropriate security attributes

---
 app/welcome/page.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/welcome/page.tsx b/app/welcome/page.tsx
index 691780a..472d16d 100644
--- a/app/welcome/page.tsx
+++ b/app/welcome/page.tsx
@@ -735,7 +735,7 @@ function WelcomeContent() {
                     ))}
                   </div>
                   <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">
-                    <Link href="/integrations" className="text-brand-orange hover:underline">
+                    <Link href="/integrations" target="_blank" rel="noopener noreferrer" className="text-brand-orange hover:underline">
                       View all integrations →
                     </Link>
                   </p>

From 1404ac5d7738d92d69cfb49a08e5ab599e710bfa Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 15:06:46 +0100
Subject: [PATCH 7/9] fix: conditionally render SiteList component based on
 loading state and site availability

---
 app/page.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/app/page.tsx b/app/page.tsx
index 35119cb..c8b58f0 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -431,7 +431,9 @@ export default function HomePage() {
         </div>
       )}
 
-      <SiteList sites={sites} loading={sitesLoading} onDelete={handleDelete} />
+      {(sitesLoading || sites.length > 0) && (
+        <SiteList sites={sites} loading={sitesLoading} onDelete={handleDelete} />
+      )}
     </div>
   )
 }

From 39e90f4f09d4c7b6984a40a64870f4691d67a2c0 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 15:09:17 +0100
Subject: [PATCH 8/9] feat: implement site creation confirmation with
 integration options and script copying functionality

---
 app/sites/new/page.tsx | 124 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 120 insertions(+), 4 deletions(-)

diff --git a/app/sites/new/page.tsx b/app/sites/new/page.tsx
index 0350d07..b4f0522 100644
--- a/app/sites/new/page.tsx
+++ b/app/sites/new/page.tsx
@@ -1,12 +1,18 @@
 'use client'
 
-import { useState, useEffect } from 'react'
+import { useState, useEffect, useCallback } from 'react'
 import { useRouter } from 'next/navigation'
-import { createSite, listSites } from '@/lib/api/sites'
+import Link from 'next/link'
+import { createSite, listSites, type Site } from '@/lib/api/sites'
 import { getSubscription } from '@/lib/api/billing'
+import { API_URL, APP_URL } from '@/lib/api/client'
+import { integrations, getIntegration } from '@/lib/integrations'
 import { toast } from '@ciphera-net/ui'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
 import { Button, Input } from '@ciphera-net/ui'
+import { CheckCircleIcon, CheckIcon } from '@ciphera-net/ui'
+
+const popularIntegrations = integrations.filter((i) => i.category === 'framework').slice(0, 10)
 
 export default function NewSitePage() {
   const router = useRouter()
@@ -15,6 +21,9 @@ export default function NewSitePage() {
     name: '',
     domain: '',
   })
+  const [createdSite, setCreatedSite] = useState<Site | null>(null)
+  const [selectedIntegrationSlug, setSelectedIntegrationSlug] = useState<string | null>(null)
+  const [scriptCopied, setScriptCopied] = useState(false)
 
   // * Check for plan limits on mount
   useEffect(() => {
@@ -38,6 +47,15 @@ export default function NewSitePage() {
     checkLimits()
   }, [router])
 
+  const copyScript = useCallback(() => {
+    if (!createdSite) return
+    const script = `<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
+    navigator.clipboard.writeText(script)
+    setScriptCopied(true)
+    toast.success('Script copied to clipboard')
+    setTimeout(() => setScriptCopied(false), 2000)
+  }, [createdSite])
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault()
     setLoading(true)
@@ -45,14 +63,112 @@ export default function NewSitePage() {
     try {
       const site = await createSite(formData)
       toast.success('Site created successfully')
-      router.push(`/sites/${site.id}`)
-    } catch (error: any) {
+      setCreatedSite(site)
+    } catch (error: unknown) {
       toast.error(getAuthErrorMessage(error) || 'Failed to create site: ' + ((error as Error)?.message || 'Unknown error'))
     } finally {
       setLoading(false)
     }
   }
 
+  // * Step 2: Show framework picker + script (same as /welcome after adding first site)
+  if (createdSite) {
+    return (
+      <div className="container mx-auto px-4 py-8 max-w-2xl">
+        <div className="bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-800 rounded-2xl p-8">
+          <div className="text-center">
+            <div className="mx-auto flex h-14 w-14 items-center justify-center rounded-full bg-green-500/10 text-green-600 dark:text-green-400 mb-6">
+              <CheckCircleIcon className="h-7 w-7" />
+            </div>
+            <h2 className="text-2xl font-bold text-neutral-900 dark:text-white">
+              Site created
+            </h2>
+            <p className="mt-2 text-neutral-600 dark:text-neutral-400">
+              Add the script to your site to start collecting data.
+            </p>
+          </div>
+
+          <div className="mt-6 pt-6 border-t border-neutral-200 dark:border-neutral-700">
+            <h3 className="text-sm font-semibold text-neutral-900 dark:text-white mb-1">
+              Add the script to your site
+            </h3>
+            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
+              Choose your framework for setup instructions.
+            </p>
+            <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mb-4">
+              {popularIntegrations.map((int) => (
+                <button
+                  key={int.id}
+                  type="button"
+                  onClick={() => setSelectedIntegrationSlug(selectedIntegrationSlug === int.id ? null : int.id)}
+                  className={`flex items-center gap-2 rounded-lg border px-3 py-2.5 text-left text-sm transition-colors ${
+                    selectedIntegrationSlug === int.id
+                      ? 'border-brand-orange bg-brand-orange/10 text-brand-orange'
+                      : 'border-neutral-200 dark:border-neutral-700 bg-neutral-50 dark:bg-neutral-800/50 hover:bg-neutral-100 dark:hover:bg-neutral-800 text-neutral-700 dark:text-neutral-300'
+                  }`}
+                >
+                  <span className="[&_svg]:h-4 [&_svg]:w-4 [&_svg]:shrink-0 flex items-center justify-center">
+                    {int.icon}
+                  </span>
+                  <span className="truncate font-medium">{int.name}</span>
+                </button>
+              ))}
+            </div>
+            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">
+              <Link href="/integrations" target="_blank" rel="noopener noreferrer" className="text-brand-orange hover:underline">
+                View all integrations →
+              </Link>
+            </p>
+
+            <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
+              <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
+                {`<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
+              </code>
+              <button
+                type="button"
+                onClick={copyScript}
+                className="absolute top-2 right-2 p-2 bg-white dark:bg-neutral-700 rounded-lg shadow-sm hover:bg-neutral-50 dark:hover:bg-neutral-600 transition-colors"
+                title="Copy script"
+                aria-label={scriptCopied ? 'Copied' : 'Copy script to clipboard'}
+              >
+                {scriptCopied ? (
+                  <CheckIcon className="w-4 h-4 text-green-500" />
+                ) : (
+                  <svg className="w-4 h-4 text-neutral-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <rect x="9" y="9" width="13" height="13" rx="2" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+                    <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+                  </svg>
+                )}
+              </button>
+            </div>
+            {selectedIntegrationSlug && getIntegration(selectedIntegrationSlug) && (
+              <p className="mt-3 text-xs">
+                <Link
+                  href={`/integrations/${selectedIntegrationSlug}`}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-brand-orange hover:underline"
+                >
+                  See full {getIntegration(selectedIntegrationSlug)!.name} guide →
+                </Link>
+              </p>
+            )}
+          </div>
+
+          <div className="mt-8 flex flex-col sm:flex-row gap-3 justify-center">
+            <Button variant="primary" onClick={() => router.push('/')} className="min-w-[160px]">
+              Back to dashboard
+            </Button>
+            <Button variant="secondary" onClick={() => router.push(`/sites/${createdSite.id}`)} className="min-w-[160px]">
+              View {createdSite.name}
+            </Button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  // * Step 1: Name & domain form
   return (
     <div className="container mx-auto px-4 py-8 max-w-2xl">
       <h1 className="text-2xl font-bold mb-8 text-neutral-900 dark:text-white">

From bd2aca7a76d3f069f4074cf2f3e6fe965aa8023c Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Sun, 8 Feb 2026 15:18:33 +0100
Subject: [PATCH 9/9] feat: integrate ScriptSetupBlock component for improved
 site setup instructions and tracking script functionality across pages

---
 app/sites/[id]/settings/page.tsx      |  34 ++---
 app/sites/new/layout.tsx              |  14 +++
 app/sites/new/page.tsx                | 174 +++++++++++++-------------
 app/welcome/layout.tsx                |  14 +++
 app/welcome/page.tsx                  |  85 +------------
 components/sites/ScriptSetupBlock.tsx | 124 ++++++++++++++++++
 lib/welcomeAnalytics.ts               |  10 ++
 7 files changed, 266 insertions(+), 189 deletions(-)
 create mode 100644 app/sites/new/layout.tsx
 create mode 100644 app/welcome/layout.tsx
 create mode 100644 components/sites/ScriptSetupBlock.tsx

diff --git a/app/sites/[id]/settings/page.tsx b/app/sites/[id]/settings/page.tsx
index 8ea491f..32935e2 100644
--- a/app/sites/[id]/settings/page.tsx
+++ b/app/sites/[id]/settings/page.tsx
@@ -8,9 +8,10 @@ import { toast } from '@ciphera-net/ui'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
 import { LoadingOverlay } from '@ciphera-net/ui'
 import VerificationModal from '@/components/sites/VerificationModal'
+import ScriptSetupBlock from '@/components/sites/ScriptSetupBlock'
 import { PasswordInput } from '@ciphera-net/ui'
 import { Select, Modal, Button } from '@ciphera-net/ui'
-import { APP_URL, API_URL } from '@/lib/api/client'
+import { APP_URL } from '@/lib/api/client'
 import { generatePrivacySnippet } from '@/lib/utils/privacySnippet'
 import { motion, AnimatePresence } from 'framer-motion'
 import { useAuth } from '@/lib/auth/context'
@@ -69,7 +70,6 @@ export default function SiteSettingsPage() {
     // Bot and noise filtering
     filter_bots: true
   })
-  const [scriptCopied, setScriptCopied] = useState(false)
   const [linkCopied, setLinkCopied] = useState(false)
   const [snippetCopied, setSnippetCopied] = useState(false)
   const [showVerificationModal, setShowVerificationModal] = useState(false)
@@ -266,14 +266,6 @@ export default function SiteSettingsPage() {
     }
   }
 
-  const copyScript = () => {
-    const script = `<script defer data-domain="${site?.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
-    navigator.clipboard.writeText(script)
-    setScriptCopied(true)
-    toast.success('Script copied to clipboard')
-    setTimeout(() => setScriptCopied(false), 2000)
-  }
-
   const copyLink = () => {
     const link = `${APP_URL}/share/${siteId}`
     navigator.clipboard.writeText(link)
@@ -443,23 +435,15 @@ export default function SiteSettingsPage() {
                   <div className="pt-4 border-t border-neutral-100 dark:border-neutral-800">
                     <h3 className="text-lg font-semibold text-neutral-900 dark:text-white mb-2">Tracking Script</h3>
                     <p className="text-sm text-neutral-500 dark:text-neutral-400 mb-4">
-                      Add this script to your website to start tracking visitors.
+                      Add this script to your website to start tracking visitors. Choose your framework for setup instructions.
                     </p>
-                    <div className="bg-neutral-100 dark:bg-neutral-800 rounded-lg p-4 mb-4 relative group">
-                      <code className="text-sm text-neutral-900 dark:text-white break-all font-mono block">
-                        {`<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
-                      </code>
-                      <button
-                        type="button"
-                        onClick={copyScript}
-                        className="absolute top-2 right-2 p-2 bg-white dark:bg-neutral-700 rounded-lg shadow-sm opacity-0 group-hover:opacity-100 transition-opacity"
-                        title="Copy Script"
-                      >
-                        {scriptCopied ? <CheckIcon className="w-4 h-4 text-green-500" /> : <svg className="w-4 h-4 text-neutral-500" fill="none" viewBox="0 0 24 24" stroke="currentColor"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" /></svg>}
-                      </button>
-                    </div>
+                    <ScriptSetupBlock
+                      site={{ domain: site.domain, name: site.name }}
+                      showFrameworkPicker
+                      className="mb-4"
+                    />
 
-                    <div className="flex items-center gap-4">
+                    <div className="flex items-center gap-4 mt-4">
                       <button
                         type="button"
                         onClick={() => setShowVerificationModal(true)}
diff --git a/app/sites/new/layout.tsx b/app/sites/new/layout.tsx
new file mode 100644
index 0000000..283f564
--- /dev/null
+++ b/app/sites/new/layout.tsx
@@ -0,0 +1,14 @@
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Create site | Pulse',
+  description: 'Add a new site to start collecting privacy-friendly analytics.',
+}
+
+export default function NewSiteLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return children
+}
diff --git a/app/sites/new/page.tsx b/app/sites/new/page.tsx
index b4f0522..0ca6617 100644
--- a/app/sites/new/page.tsx
+++ b/app/sites/new/page.tsx
@@ -1,18 +1,19 @@
 'use client'
 
-import { useState, useEffect, useCallback } from 'react'
+import { useState, useEffect } from 'react'
 import { useRouter } from 'next/navigation'
 import Link from 'next/link'
-import { createSite, listSites, type Site } from '@/lib/api/sites'
+import { createSite, listSites, getSite, type Site } from '@/lib/api/sites'
 import { getSubscription } from '@/lib/api/billing'
-import { API_URL, APP_URL } from '@/lib/api/client'
-import { integrations, getIntegration } from '@/lib/integrations'
+import { trackSiteCreatedFromDashboard, trackSiteCreatedScriptCopied } from '@/lib/welcomeAnalytics'
 import { toast } from '@ciphera-net/ui'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
 import { Button, Input } from '@ciphera-net/ui'
-import { CheckCircleIcon, CheckIcon } from '@ciphera-net/ui'
+import { CheckCircleIcon } from '@ciphera-net/ui'
+import ScriptSetupBlock from '@/components/sites/ScriptSetupBlock'
+import VerificationModal from '@/components/sites/VerificationModal'
 
-const popularIntegrations = integrations.filter((i) => i.category === 'framework').slice(0, 10)
+const LAST_CREATED_SITE_KEY = 'pulse_last_created_site'
 
 export default function NewSitePage() {
   const router = useRouter()
@@ -22,8 +23,30 @@ export default function NewSitePage() {
     domain: '',
   })
   const [createdSite, setCreatedSite] = useState<Site | null>(null)
-  const [selectedIntegrationSlug, setSelectedIntegrationSlug] = useState<string | null>(null)
-  const [scriptCopied, setScriptCopied] = useState(false)
+  const [showVerificationModal, setShowVerificationModal] = useState(false)
+  const [atLimit, setAtLimit] = useState(false)
+  const [limitsChecked, setLimitsChecked] = useState(false)
+
+  // * Restore step 2 from sessionStorage after refresh (e.g. pulse_last_created_site = { id } )
+  useEffect(() => {
+    if (createdSite || typeof window === 'undefined') return
+    try {
+      const raw = sessionStorage.getItem(LAST_CREATED_SITE_KEY)
+      if (!raw) return
+      const { id } = JSON.parse(raw) as { id?: string }
+      if (!id) return
+      getSite(id)
+        .then((site) => {
+          setCreatedSite(site)
+          setFormData({ name: site.name, domain: site.domain })
+        })
+        .catch(() => {
+          sessionStorage.removeItem(LAST_CREATED_SITE_KEY)
+        })
+    } catch {
+      sessionStorage.removeItem(LAST_CREATED_SITE_KEY)
+    }
+  }, [createdSite])
 
   // * Check for plan limits on mount
   useEffect(() => {
@@ -35,27 +58,20 @@ export default function NewSitePage() {
         ])
 
         if (subscription?.plan_id === 'solo' && sites.length >= 1) {
+          setAtLimit(true)
           toast.error('Solo plan limit reached (1 site). Please upgrade to add more sites.')
           router.replace('/')
         }
       } catch (error) {
-        // Ignore errors here, let the backend handle the hard check on submit
         console.error('Failed to check limits', error)
+      } finally {
+        setLimitsChecked(true)
       }
     }
 
     checkLimits()
   }, [router])
 
-  const copyScript = useCallback(() => {
-    if (!createdSite) return
-    const script = `<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
-    navigator.clipboard.writeText(script)
-    setScriptCopied(true)
-    toast.success('Script copied to clipboard')
-    setTimeout(() => setScriptCopied(false), 2000)
-  }, [createdSite])
-
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault()
     setLoading(true)
@@ -64,6 +80,10 @@ export default function NewSitePage() {
       const site = await createSite(formData)
       toast.success('Site created successfully')
       setCreatedSite(site)
+      trackSiteCreatedFromDashboard()
+      if (typeof window !== 'undefined') {
+        sessionStorage.setItem(LAST_CREATED_SITE_KEY, JSON.stringify({ id: site.id }))
+      }
     } catch (error: unknown) {
       toast.error(getAuthErrorMessage(error) || 'Failed to create site: ' + ((error as Error)?.message || 'Unknown error'))
     } finally {
@@ -71,7 +91,17 @@ export default function NewSitePage() {
     }
   }
 
-  // * Step 2: Show framework picker + script (same as /welcome after adding first site)
+  const handleBackToForm = () => {
+    setCreatedSite(null)
+    if (typeof window !== 'undefined') sessionStorage.removeItem(LAST_CREATED_SITE_KEY)
+  }
+
+  const goToDashboard = () => {
+    router.refresh()
+    router.push('/')
+  }
+
+  // * Step 2: Framework picker + script (same as /welcome after adding first site)
   if (createdSite) {
     return (
       <div className="container mx-auto px-4 py-8 max-w-2xl">
@@ -89,74 +119,38 @@ export default function NewSitePage() {
           </div>
 
           <div className="mt-6 pt-6 border-t border-neutral-200 dark:border-neutral-700">
-            <h3 className="text-sm font-semibold text-neutral-900 dark:text-white mb-1">
-              Add the script to your site
-            </h3>
-            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
-              Choose your framework for setup instructions.
-            </p>
-            <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mb-4">
-              {popularIntegrations.map((int) => (
-                <button
-                  key={int.id}
-                  type="button"
-                  onClick={() => setSelectedIntegrationSlug(selectedIntegrationSlug === int.id ? null : int.id)}
-                  className={`flex items-center gap-2 rounded-lg border px-3 py-2.5 text-left text-sm transition-colors ${
-                    selectedIntegrationSlug === int.id
-                      ? 'border-brand-orange bg-brand-orange/10 text-brand-orange'
-                      : 'border-neutral-200 dark:border-neutral-700 bg-neutral-50 dark:bg-neutral-800/50 hover:bg-neutral-100 dark:hover:bg-neutral-800 text-neutral-700 dark:text-neutral-300'
-                  }`}
-                >
-                  <span className="[&_svg]:h-4 [&_svg]:w-4 [&_svg]:shrink-0 flex items-center justify-center">
-                    {int.icon}
-                  </span>
-                  <span className="truncate font-medium">{int.name}</span>
-                </button>
-              ))}
-            </div>
-            <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">
-              <Link href="/integrations" target="_blank" rel="noopener noreferrer" className="text-brand-orange hover:underline">
-                View all integrations →
-              </Link>
-            </p>
+            <ScriptSetupBlock
+              site={{ domain: createdSite.domain, name: createdSite.name }}
+              onScriptCopy={trackSiteCreatedScriptCopied}
+              showFrameworkPicker
+            />
+          </div>
 
-            <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
-              <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
-                {`<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
-              </code>
-              <button
-                type="button"
-                onClick={copyScript}
-                className="absolute top-2 right-2 p-2 bg-white dark:bg-neutral-700 rounded-lg shadow-sm hover:bg-neutral-50 dark:hover:bg-neutral-600 transition-colors"
-                title="Copy script"
-                aria-label={scriptCopied ? 'Copied' : 'Copy script to clipboard'}
-              >
-                {scriptCopied ? (
-                  <CheckIcon className="w-4 h-4 text-green-500" />
-                ) : (
-                  <svg className="w-4 h-4 text-neutral-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                    <rect x="9" y="9" width="13" height="13" rx="2" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
-                    <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
-                  </svg>
-                )}
-              </button>
-            </div>
-            {selectedIntegrationSlug && getIntegration(selectedIntegrationSlug) && (
-              <p className="mt-3 text-xs">
-                <Link
-                  href={`/integrations/${selectedIntegrationSlug}`}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  className="text-brand-orange hover:underline"
-                >
-                  See full {getIntegration(selectedIntegrationSlug)!.name} guide →
-                </Link>
-              </p>
-            )}
+          <div className="mt-6 flex flex-wrap items-center justify-center gap-2">
+            <button
+              type="button"
+              onClick={() => setShowVerificationModal(true)}
+              className="flex items-center gap-2 px-4 py-2 bg-white dark:bg-neutral-800 border border-neutral-200 dark:border-neutral-700 text-neutral-700 dark:text-neutral-300 rounded-xl hover:bg-neutral-50 dark:hover:bg-neutral-700 transition-all text-sm font-medium focus:outline-none focus:ring-2 focus:ring-brand-orange focus:ring-offset-2"
+            >
+              <span className="text-brand-orange">Verify installation</span>
+            </button>
+            <p className="text-xs text-neutral-500 dark:text-neutral-400">
+              Check if your site is sending data correctly.
+            </p>
+          </div>
+
+          <div className="mt-6 flex flex-wrap justify-center gap-2">
+            <button
+              type="button"
+              onClick={handleBackToForm}
+              className="text-sm text-neutral-500 dark:text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-300 underline"
+            >
+              Edit site details
+            </button>
           </div>
 
           <div className="mt-8 flex flex-col sm:flex-row gap-3 justify-center">
-            <Button variant="primary" onClick={() => router.push('/')} className="min-w-[160px]">
+            <Button variant="primary" onClick={goToDashboard} className="min-w-[160px]">
               Back to dashboard
             </Button>
             <Button variant="secondary" onClick={() => router.push(`/sites/${createdSite.id}`)} className="min-w-[160px]">
@@ -164,6 +158,12 @@ export default function NewSitePage() {
             </Button>
           </div>
         </div>
+
+        <VerificationModal
+          isOpen={showVerificationModal}
+          onClose={() => setShowVerificationModal(false)}
+          site={createdSite}
+        />
       </div>
     )
   }
@@ -175,6 +175,12 @@ export default function NewSitePage() {
         Create New Site
       </h1>
 
+      {atLimit && limitsChecked && (
+        <p className="mb-4 text-sm text-amber-600 dark:text-amber-400">
+          Plan limit reached. Upgrade to add more sites.
+        </p>
+      )}
+
       <form onSubmit={handleSubmit} className="bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-800 rounded-2xl p-6">
         <div className="mb-4">
           <label htmlFor="name" className="block text-sm font-medium mb-2 text-neutral-900 dark:text-white">
@@ -208,7 +214,7 @@ export default function NewSitePage() {
         <div className="flex gap-4">
           <Button
             type="submit"
-            disabled={loading}
+            disabled={loading || atLimit}
             isLoading={loading}
           >
             Create Site
diff --git a/app/welcome/layout.tsx b/app/welcome/layout.tsx
new file mode 100644
index 0000000..979f456
--- /dev/null
+++ b/app/welcome/layout.tsx
@@ -0,0 +1,14 @@
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Welcome | Pulse',
+  description: 'Set up your Pulse workspace and add your first site.',
+}
+
+export default function WelcomeLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return children
+}
diff --git a/app/welcome/page.tsx b/app/welcome/page.tsx
index 472d16d..1c3f64f 100644
--- a/app/welcome/page.tsx
+++ b/app/welcome/page.tsx
@@ -21,8 +21,6 @@ import { createSite, type Site } from '@/lib/api/sites'
 import { setSessionAction } from '@/app/actions/auth'
 import { useAuth } from '@/lib/auth/context'
 import { getAuthErrorMessage } from '@/lib/utils/authErrors'
-import { API_URL, APP_URL } from '@/lib/api/client'
-import { integrations, getIntegration } from '@/lib/integrations'
 import {
   trackWelcomeStepView,
   trackWelcomeWorkspaceSelected,
@@ -37,7 +35,6 @@ import { LoadingOverlay, Button, Input } from '@ciphera-net/ui'
 import { toast } from '@ciphera-net/ui'
 import {
   CheckCircleIcon,
-  CheckIcon,
   ArrowRightIcon,
   ArrowLeftIcon,
   BarChartIcon,
@@ -46,6 +43,7 @@ import {
   PlusIcon,
 } from '@ciphera-net/ui'
 import Link from 'next/link'
+import ScriptSetupBlock from '@/components/sites/ScriptSetupBlock'
 
 const TOTAL_STEPS = 5
 const DEFAULT_ORG_NAME = 'My workspace'
@@ -107,9 +105,6 @@ function WelcomeContent() {
   const [orgsLoading, setOrgsLoading] = useState(false)
   const [switchingOrgId, setSwitchingOrgId] = useState<string | null>(null)
 
-  const [selectedIntegrationSlug, setSelectedIntegrationSlug] = useState<string | null>(null)
-  const [scriptCopied, setScriptCopied] = useState(false)
-
   const setStep = useCallback(
     (next: number) => {
       const s = Math.min(Math.max(1, next), TOTAL_STEPS)
@@ -270,17 +265,6 @@ function WelcomeContent() {
   }
   const goToSite = () => createdSite && router.push(`/sites/${createdSite.id}`)
 
-  const copyScript = useCallback(() => {
-    if (!createdSite) return
-    const script = `<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
-    navigator.clipboard.writeText(script)
-    setScriptCopied(true)
-    toast.success('Script copied to clipboard')
-    setTimeout(() => setScriptCopied(false), 2000)
-  }, [createdSite])
-
-  const popularIntegrations = integrations.filter((i) => i.category === 'framework').slice(0, 10)
-
   const showPendingCheckoutInStep3 =
     hadPendingCheckout === true && !dismissedPendingCheckout
 
@@ -709,69 +693,10 @@ function WelcomeContent() {
 
               {createdSite && (
                 <div className="mt-6 pt-6 border-t border-neutral-200 dark:border-neutral-700">
-                  <h3 className="text-sm font-semibold text-neutral-900 dark:text-white mb-1">
-                    Add the script to your site
-                  </h3>
-                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
-                    Choose your framework for setup instructions.
-                  </p>
-                  <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mb-4">
-                    {popularIntegrations.map((int) => (
-                      <button
-                        key={int.id}
-                        type="button"
-                        onClick={() => setSelectedIntegrationSlug(selectedIntegrationSlug === int.id ? null : int.id)}
-                        className={`flex items-center gap-2 rounded-lg border px-3 py-2.5 text-left text-sm transition-colors ${
-                          selectedIntegrationSlug === int.id
-                            ? 'border-brand-orange bg-brand-orange/10 text-brand-orange'
-                            : 'border-neutral-200 dark:border-neutral-700 bg-neutral-50 dark:bg-neutral-800/50 hover:bg-neutral-100 dark:hover:bg-neutral-800 text-neutral-700 dark:text-neutral-300'
-                        }`}
-                      >
-                        <span className="[&_svg]:h-4 [&_svg]:w-4 [&_svg]:shrink-0 flex items-center justify-center">
-                          {int.icon}
-                        </span>
-                        <span className="truncate font-medium">{int.name}</span>
-                      </button>
-                    ))}
-                  </div>
-                  <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">
-                    <Link href="/integrations" target="_blank" rel="noopener noreferrer" className="text-brand-orange hover:underline">
-                      View all integrations →
-                    </Link>
-                  </p>
-
-                  <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
-                    <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
-                      {`<script defer data-domain="${createdSite.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
-                    </code>
-                    <button
-                      type="button"
-                      onClick={copyScript}
-                      className="absolute top-2 right-2 p-2 bg-white dark:bg-neutral-700 rounded-lg shadow-sm hover:bg-neutral-50 dark:hover:bg-neutral-600 transition-colors"
-                      title="Copy script"
-                    >
-                      {scriptCopied ? (
-                        <CheckIcon className="w-4 h-4 text-green-500" />
-                      ) : (
-                        <svg className="w-4 h-4 text-neutral-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                          <rect x="9" y="9" width="13" height="13" rx="2" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
-                          <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
-                        </svg>
-                      )}
-                    </button>
-                  </div>
-                  {selectedIntegrationSlug && getIntegration(selectedIntegrationSlug) && (
-                    <p className="mt-3 text-xs">
-                      <Link
-                        href={`/integrations/${selectedIntegrationSlug}`}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        className="text-brand-orange hover:underline"
-                      >
-                        See full {getIntegration(selectedIntegrationSlug)!.name} guide →
-                      </Link>
-                    </p>
-                  )}
+                  <ScriptSetupBlock
+                    site={{ domain: createdSite.domain, name: createdSite.name }}
+                    showFrameworkPicker
+                  />
                 </div>
               )}
 
diff --git a/components/sites/ScriptSetupBlock.tsx b/components/sites/ScriptSetupBlock.tsx
new file mode 100644
index 0000000..4d16d76
--- /dev/null
+++ b/components/sites/ScriptSetupBlock.tsx
@@ -0,0 +1,124 @@
+'use client'
+
+/**
+ * Shared block: framework picker, tracking script snippet with copy, and integration guide links.
+ * Used on welcome (step 5), /sites/new (step 2), and site settings.
+ */
+
+import { useState, useCallback } from 'react'
+import Link from 'next/link'
+import { API_URL, APP_URL } from '@/lib/api/client'
+import { integrations, getIntegration } from '@/lib/integrations'
+import { toast } from '@ciphera-net/ui'
+import { CheckIcon } from '@ciphera-net/ui'
+
+const POPULAR_INTEGRATIONS = integrations.filter((i) => i.category === 'framework').slice(0, 10)
+
+export interface ScriptSetupBlockSite {
+  domain: string
+  name?: string
+}
+
+interface ScriptSetupBlockProps {
+  /** Site domain (and optional name for display). */
+  site: ScriptSetupBlockSite
+  /** Called when user copies the script (e.g. for analytics). */
+  onScriptCopy?: () => void
+  /** Show framework picker and "View all integrations" / "See full guide" links. Default true. */
+  showFrameworkPicker?: boolean
+  /** Optional class for the root wrapper. */
+  className?: string
+}
+
+export default function ScriptSetupBlock({
+  site,
+  onScriptCopy,
+  showFrameworkPicker = true,
+  className = '',
+}: ScriptSetupBlockProps) {
+  const [selectedIntegrationSlug, setSelectedIntegrationSlug] = useState<string | null>(null)
+  const [scriptCopied, setScriptCopied] = useState(false)
+
+  const copyScript = useCallback(() => {
+    const script = `<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
+    navigator.clipboard.writeText(script)
+    setScriptCopied(true)
+    toast.success('Script copied to clipboard')
+    onScriptCopy?.()
+    setTimeout(() => setScriptCopied(false), 2000)
+  }, [site.domain, onScriptCopy])
+
+  return (
+    <div className={className}>
+      {showFrameworkPicker && (
+        <>
+          <h3 className="text-sm font-semibold text-neutral-900 dark:text-white mb-1">
+            Add the script to your site
+          </h3>
+          <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-3">
+            Choose your framework for setup instructions.
+          </p>
+          <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mb-4">
+            {POPULAR_INTEGRATIONS.map((int) => (
+              <button
+                key={int.id}
+                type="button"
+                onClick={() => setSelectedIntegrationSlug(selectedIntegrationSlug === int.id ? null : int.id)}
+                className={`flex items-center gap-2 rounded-lg border px-3 py-2.5 text-left text-sm transition-colors ${
+                  selectedIntegrationSlug === int.id
+                    ? 'border-brand-orange bg-brand-orange/10 text-brand-orange'
+                    : 'border-neutral-200 dark:border-neutral-700 bg-neutral-50 dark:bg-neutral-800/50 hover:bg-neutral-100 dark:hover:bg-neutral-800 text-neutral-700 dark:text-neutral-300'
+                }`}
+              >
+                <span className="[&_svg]:h-4 [&_svg]:w-4 [&_svg]:shrink-0 flex items-center justify-center">
+                  {int.icon}
+                </span>
+                <span className="truncate font-medium">{int.name}</span>
+              </button>
+            ))}
+          </div>
+          <p className="text-xs text-neutral-500 dark:text-neutral-400 mb-2">
+            <Link href="/integrations" target="_blank" rel="noopener noreferrer" className="text-brand-orange hover:underline">
+              View all integrations →
+            </Link>
+          </p>
+        </>
+      )}
+
+      <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
+        <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
+          {`<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
+        </code>
+        <button
+          type="button"
+          onClick={copyScript}
+          className="absolute top-2 right-2 p-2 bg-white dark:bg-neutral-700 rounded-lg shadow-sm hover:bg-neutral-50 dark:hover:bg-neutral-600 transition-colors"
+          title="Copy script"
+          aria-label={scriptCopied ? 'Copied' : 'Copy script to clipboard'}
+        >
+          {scriptCopied ? (
+            <CheckIcon className="w-4 h-4 text-green-500" />
+          ) : (
+            <svg className="w-4 h-4 text-neutral-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <rect x="9" y="9" width="13" height="13" rx="2" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+              <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+            </svg>
+          )}
+        </button>
+      </div>
+
+      {showFrameworkPicker && selectedIntegrationSlug && getIntegration(selectedIntegrationSlug) && (
+        <p className="mt-3 text-xs">
+          <Link
+            href={`/integrations/${selectedIntegrationSlug}`}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-brand-orange hover:underline"
+          >
+            See full {getIntegration(selectedIntegrationSlug)!.name} guide →
+          </Link>
+        </p>
+      )}
+    </div>
+  )
+}
diff --git a/lib/welcomeAnalytics.ts b/lib/welcomeAnalytics.ts
index 9f1ee71..5c2f2db 100644
--- a/lib/welcomeAnalytics.ts
+++ b/lib/welcomeAnalytics.ts
@@ -13,6 +13,8 @@ export type WelcomeEventName =
   | 'welcome_site_added'
   | 'welcome_site_skipped'
   | 'welcome_completed'
+  | 'site_created_from_dashboard'
+  | 'site_created_script_copied'
 
 export interface WelcomeEventPayload {
   event: WelcomeEventName
@@ -75,3 +77,11 @@ export function trackWelcomeSiteSkipped() {
 export function trackWelcomeCompleted(addedSite: boolean) {
   emit('welcome_completed', { added_site: addedSite })
 }
+
+export function trackSiteCreatedFromDashboard() {
+  emit('site_created_from_dashboard')
+}
+
+export function trackSiteCreatedScriptCopied() {
+  emit('site_created_script_copied')
+}