// prisma/schema.prisma (relevant models)
// enum OnboardingStep {
//   SIGNED_UP | SEGMENT_SELECTED | WORKSPACE_CREATED
//   FIRST_ITEM_CREATED | TEAMMATE_INVITED | TOUR_COMPLETED
//   ACTIVATED | DISMISSED
// }
// model User { ... onboardingStep OnboardingStep @default(SIGNED_UP)
//   activatedAt DateTime?  onboardingDismissedAt DateTime?
//   onboardingEvents OnboardingEvent[] }
// model OnboardingEvent { ... userId, fromStep, toStep, metadata Json?, createdAt
//   @@index([userId, createdAt]) }

// src/lib/onboarding/steps.ts
export const OnboardingStep = {
  SIGNED_UP: "SIGNED_UP",
  SEGMENT_SELECTED: "SEGMENT_SELECTED",
  WORKSPACE_CREATED: "WORKSPACE_CREATED",
  FIRST_ITEM_CREATED: "FIRST_ITEM_CREATED",
  TEAMMATE_INVITED: "TEAMMATE_INVITED",
  TOUR_COMPLETED: "TOUR_COMPLETED",
  ACTIVATED: "ACTIVATED",
  DISMISSED: "DISMISSED",
} as const;

export type OnboardingStepType =
  (typeof OnboardingStep)[keyof typeof OnboardingStep];

export type StepConfig = {
  label: string;
  description: string;
  required: boolean;
  segments: string[] | "all";
  ctaLabel: string;
  ctaHref?: string;
};

export const STEP_CONFIG: Record<OnboardingStepType, StepConfig> = {
  SIGNED_UP: {
    label: "Create account",
    description: "You're in! Welcome aboard.",
    required: true, segments: "all", ctaLabel: "Done",
  },
  SEGMENT_SELECTED: {
    label: "Tell us about yourself",
    description: "Pick your role so we can tailor your experience.",
    required: true, segments: "all", ctaLabel: "Select role",
    ctaHref: "/onboarding/segment",
  },
  WORKSPACE_CREATED: {
    label: "Create your workspace",
    description: "Set up a space for your team or personal projects.",
    required: true, segments: "all", ctaLabel: "Create workspace",
    ctaHref: "/onboarding/workspace",
  },
  FIRST_ITEM_CREATED: {
    label: "Create your first item",
    description: "Add your first project, task, or document.",
    required: true, segments: "all", ctaLabel: "Create item",
    ctaHref: "/dashboard",
  },
  TEAMMATE_INVITED: {
    label: "Invite a teammate",
    description: "Collaboration is better with your team.",
    required: false, segments: ["manager", "designer"],
    ctaLabel: "Invite", ctaHref: "/settings/team",
  },
  TOUR_COMPLETED: {
    label: "Take the product tour",
    description: "A quick walkthrough of the key features.",
    required: false, segments: "all", ctaLabel: "Start tour",
  },
  ACTIVATED: {
    label: "All set!", description: "You've completed onboarding.",
    required: false, segments: "all", ctaLabel: "Go to dashboard",
    ctaHref: "/dashboard",
  },
  DISMISSED: {
    label: "Dismissed", description: "Onboarding dismissed.",
    required: false, segments: "all", ctaLabel: "",
  },
};

export function getStepsForSegment(segment: string | null): OnboardingStepType[] {
  const allSteps: OnboardingStepType[] = [
    "SIGNED_UP", "SEGMENT_SELECTED", "WORKSPACE_CREATED",
    "FIRST_ITEM_CREATED", "TEAMMATE_INVITED", "TOUR_COMPLETED", "ACTIVATED",
  ];
  if (!segment) return allSteps;
  return allSteps.filter((step) => {
    const config = STEP_CONFIG[step];
    return config.segments === "all" || config.segments.includes(segment);
  });
}

// src/lib/onboarding/machine.ts
import { db } from "@/lib/db";
import { OnboardingStep, STEP_CONFIG, getStepsForSegment } from "./steps";
import type { OnboardingStepType } from "./steps";

export async function transitionOnboardingStep(
  userId: string,
  targetStep: OnboardingStepType,
  metadata?: Record<string, unknown>
) {
  const user = await db.user.findUniqueOrThrow({
    where: { id: userId },
    select: { onboardingStep: true, segment: true },
  });

  const currentStep = user.onboardingStep as OnboardingStepType;
  const steps = getStepsForSegment(user.segment);
  const currentIndex = steps.indexOf(currentStep);
  const targetIndex = steps.indexOf(targetStep);

  if (targetIndex <= currentIndex) {
    throw new Error(`Invalid transition: ${currentStep} → ${targetStep}`);
  }

  // Check no required steps are skipped
  for (let i = currentIndex + 1; i < targetIndex; i++) {
    if (STEP_CONFIG[steps[i]].required) {
      throw new Error(`Cannot skip required step: ${steps[i]}`);
    }
  }

  const isActivated = targetStep === OnboardingStep.ACTIVATED;

  await db.$transaction([
    db.user.update({
      where: { id: userId },
      data: {
        onboardingStep: targetStep,
        ...(isActivated ? { activatedAt: new Date() } : {}),
      },
    }),
    db.onboardingEvent.create({
      data: { userId, fromStep: currentStep, toStep: targetStep, metadata },
    }),
  ]);

  return { success: true, newStep: targetStep, isActivated };
}

export function getNextStep(
  currentStep: OnboardingStepType,
  segment: string | null
): OnboardingStepType | null {
  const steps = getStepsForSegment(segment);
  const idx = steps.indexOf(currentStep);
  return idx === -1 || idx >= steps.length - 1 ? null : steps[idx + 1];
}

// src/lib/onboarding/use-onboarding.ts
"use client";

import { useCallback, useOptimistic, useTransition } from "react";
import { useRouter } from "next/navigation";
import type { OnboardingStepType } from "@/lib/onboarding/steps";
import { completeStepAction, skipStepAction, dismissOnboardingAction }
  from "@/app/actions/onboarding";

type OnboardingState = {
  currentStep: OnboardingStepType;
  completedSteps: OnboardingStepType[];
  segment: string | null;
  totalSteps: number;
  progress: number;
  isDismissed: boolean;
};

export function useOnboarding(initialState: OnboardingState) {
  const router = useRouter();
  const [isPending, startTransition] = useTransition();
  const [state, setOptimistic] = useOptimistic(initialState);

  const completeStep = useCallback(
    (step: OnboardingStepType) => {
      startTransition(async () => {
        setOptimistic((prev) => ({
          ...prev,
          completedSteps: [...prev.completedSteps, step],
          progress: Math.round(
            ((prev.completedSteps.length + 1) / prev.totalSteps) * 100
          ),
        }));
        await completeStepAction(step);
        router.refresh();
      });
    },
    [router, startTransition, setOptimistic]
  );

  const skipStep = useCallback(
    (step: OnboardingStepType) => {
      startTransition(async () => {
        setOptimistic((prev) => ({
          ...prev,
          completedSteps: [...prev.completedSteps, step],
          progress: Math.round(
            ((prev.completedSteps.length + 1) / prev.totalSteps) * 100
          ),
        }));
        await skipStepAction(step);
        router.refresh();
      });
    },
    [router, startTransition, setOptimistic]
  );

  const dismiss = useCallback(() => {
    startTransition(async () => {
      setOptimistic((prev) => ({ ...prev, isDismissed: true }));
      await dismissOnboardingAction();
      router.refresh();
    });
  }, [router, startTransition, setOptimistic]);

  return { ...state, isPending, completeStep, skipStep, dismiss };
}

// src/components/onboarding/checklist.tsx
"use client";

import { useOnboarding } from "@/lib/onboarding/use-onboarding";
import { STEP_CONFIG, getStepsForSegment } from "@/lib/onboarding/steps";
import type { OnboardingStepType } from "@/lib/onboarding/steps";
import { CheckCircle2, Circle, SkipForward, X } from "lucide-react";
import Link from "next/link";

type ChecklistProps = {
  initialState: {
    currentStep: OnboardingStepType;
    completedSteps: OnboardingStepType[];
    segment: string | null;
    totalSteps: number;
    progress: number;
    isDismissed: boolean;
  };
};

export function OnboardingChecklist({ initialState }: ChecklistProps) {
  const {
    currentStep, completedSteps, segment, progress, isDismissed,
    isPending, completeStep, skipStep, dismiss,
  } = useOnboarding(initialState);

  if (isDismissed || currentStep === "ACTIVATED" || currentStep === "DISMISSED") {
    return null;
  }

  const steps = getStepsForSegment(segment).filter(
    (s) => s !== "ACTIVATED" && s !== "DISMISSED"
  );

  return (
    <div className="w-80 rounded-lg border border-gray-200 bg-white shadow-lg">
      <div className="flex items-center justify-between border-b px-4 py-3">
        <div>
          <h3 className="text-sm font-semibold text-gray-900">Getting Started</h3>
          <p className="text-xs text-gray-500">
            {completedSteps.length} of {steps.length} complete
          </p>
        </div>
        <button onClick={dismiss} className="text-gray-400 hover:text-gray-600">
          <X className="h-4 w-4" />
        </button>
      </div>

      <div className="px-4 pt-3">
        <div className="h-2 w-full rounded-full bg-gray-100">
          <div
            className="h-2 rounded-full bg-blue-600 transition-all duration-500"
            style={{ width: `${progress}%` }}
          />
        </div>
      </div>

      <div className="p-4 space-y-1">
        {steps.map((step) => {
          const config = STEP_CONFIG[step];
          const isCompleted = completedSteps.includes(step);
          const isCurrent = step === currentStep;

          return (
            <div
              key={step}
              className={`rounded-md p-3 transition-colors
                ${isCurrent ? "bg-blue-50 ring-1 ring-blue-200" : ""}
                ${isCompleted ? "opacity-60" : ""}`}
            >
              <div className="flex items-start gap-3">
                <div className="mt-0.5">
                  {isCompleted ? (
                    <CheckCircle2 className="h-5 w-5 text-green-600" />
                  ) : (
                    <Circle className={`h-5 w-5 ${
                      isCurrent ? "text-blue-600" : "text-gray-300"
                    }`} />
                  )}
                </div>
                <div className="flex-1 min-w-0">
                  <p className={`text-sm font-medium ${
                    isCompleted ? "text-gray-500 line-through" : "text-gray-900"
                  }`}>
                    {config.label}
                  </p>
                  {isCurrent && (
                    <>
                      <p className="mt-1 text-xs text-gray-600">
                        {config.description}
                      </p>
                      <div className="mt-2 flex items-center gap-2">
                        {config.ctaHref ? (
                          <Link href={config.ctaHref}
                            className="rounded-md bg-blue-600 px-3 py-1.5
                              text-xs font-medium text-white hover:bg-blue-700">
                            {config.ctaLabel}
                          </Link>
                        ) : (
                          <button onClick={() => completeStep(step)}
                            disabled={isPending}
                            className="rounded-md bg-blue-600 px-3 py-1.5
                              text-xs font-medium text-white hover:bg-blue-700
                              disabled:opacity-50">
                            {config.ctaLabel}
                          </button>
                        )}
                        {!config.required && (
                          <button onClick={() => skipStep(step)}
                            disabled={isPending}
                            className="flex items-center gap-1 text-xs
                              text-gray-500 hover:text-gray-700">
                            <SkipForward className="h-3 w-3" /> Skip
                          </button>
                        )}
                      </div>
                    </>
                  )}
                </div>
              </div>
            </div>
          );
        })}
      </div>
    </div>
  );
}

// src/app/actions/onboarding.ts
"use server";

import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { transitionOnboardingStep, getNextStep } from "@/lib/onboarding/machine";
import { trackServerEvent } from "@/lib/analytics/server";
import type { OnboardingStepType } from "@/lib/onboarding/steps";

export async function completeStepAction(step: OnboardingStepType) {
  const session = await auth();
  if (!session?.user?.id) throw new Error("Unauthorized");

  const result = await transitionOnboardingStep(session.user.id, step, {
    completedVia: "checklist",
  });

  trackServerEvent(session.user.id, "onboarding_step_completed", {
    step, is_activated: result.isActivated,
  });

  return result;
}

export async function skipStepAction(step: OnboardingStepType) {
  const session = await auth();
  if (!session?.user?.id) throw new Error("Unauthorized");

  const user = await db.user.findUniqueOrThrow({
    where: { id: session.user.id },
    select: { segment: true },
  });

  const nextStep = getNextStep(step, user.segment);
  if (!nextStep) throw new Error("No next step");

  const result = await transitionOnboardingStep(session.user.id, nextStep, {
    skippedStep: step,
  });

  trackServerEvent(session.user.id, "onboarding_step_skipped", {
    step, advanced_to: nextStep,
  });

  return result;
}

export async function dismissOnboardingAction() {
  const session = await auth();
  if (!session?.user?.id) throw new Error("Unauthorized");

  await db.user.update({
    where: { id: session.user.id },
    data: { onboardingStep: "DISMISSED", onboardingDismissedAt: new Date() },
  });

  trackServerEvent(session.user.id, "onboarding_dismissed", {});
}

// src/lib/tour/types.ts
export type TourStep = {
  id: string;
  targetSelector: string;
  title: string;
  content: string;
  placement: "top" | "bottom" | "left" | "right";
  advanceOn?: "click"; // advance when the target element is clicked
};

export type TourDefinition = {
  id: string;
  steps: TourStep[];
  segment?: string;
};

// src/components/tour/tour-provider.tsx
"use client";

import { createContext, useCallback, useContext, useEffect, useRef, useState }
  from "react";
import { createPortal } from "react-dom";
import type { TourDefinition, TourStep } from "@/lib/tour/types";

type TourContextType = {
  startTour: (tourId: string) => void;
  endTour: () => void;
  nextStep: () => void;
  activeTour: string | null;
};

const TourContext = createContext<TourContextType | null>(null);
export const useTour = () => useContext(TourContext)!;

type Props = {
  tours: Record<string, TourDefinition>;
  completedTours: string[];
  children: React.ReactNode;
};

export function TourProvider({ tours, completedTours, children }: Props) {
  const [activeTour, setActiveTour] = useState<TourDefinition | null>(null);
  const [stepIndex, setStepIndex] = useState(0);
  const [targetRect, setTargetRect] = useState<DOMRect | null>(null);

  const currentStep = activeTour?.steps[stepIndex] ?? null;

  // Measure the target element position
  const measure = useCallback(() => {
    if (!currentStep) return;
    const el = document.querySelector(currentStep.targetSelector);
    if (el) setTargetRect(el.getBoundingClientRect());
  }, [currentStep]);

  useEffect(() => {
    if (!activeTour) return;
    measure();
    window.addEventListener("scroll", measure, true);
    window.addEventListener("resize", measure);
    return () => {
      window.removeEventListener("scroll", measure, true);
      window.removeEventListener("resize", measure);
    };
  }, [activeTour, stepIndex, measure]);

  // Watch for target element to appear in DOM
  useEffect(() => {
    if (!currentStep) return;
    if (document.querySelector(currentStep.targetSelector)) { measure(); return; }

    const observer = new MutationObserver(() => {
      if (document.querySelector(currentStep.targetSelector)) {
        measure();
        observer.disconnect();
      }
    });
    observer.observe(document.body, { childList: true, subtree: true });
    return () => observer.disconnect();
  }, [currentStep, measure]);

  // Advance on target click when advanceOn === "click"
  useEffect(() => {
    if (!currentStep || currentStep.advanceOn !== "click") return;
    const el = document.querySelector(currentStep.targetSelector);
    if (!el) return;
    const handler = () => setTimeout(() => nextStep(), 100);
    el.addEventListener("click", handler);
    return () => el.removeEventListener("click", handler);
  }, [currentStep, stepIndex]);

  const startTour = useCallback((tourId: string) => {
    if (completedTours.includes(tourId)) return;
    const tour = tours[tourId];
    if (!tour) return;
    setActiveTour(tour);
    setStepIndex(0);
  }, [completedTours, tours]);

  const endTour = useCallback(async () => {
    if (!activeTour) return;
    await fetch("/api/onboarding/tour-complete", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ tourId: activeTour.id }),
    });
    setActiveTour(null);
    setStepIndex(0);
    setTargetRect(null);
  }, [activeTour]);

  const nextStep = useCallback(() => {
    if (!activeTour) return;
    if (stepIndex >= activeTour.steps.length - 1) { endTour(); return; }
    setStepIndex((i) => i + 1);
  }, [activeTour, stepIndex, endTour]);

  return (
    <TourContext.Provider value={{
      startTour, endTour, nextStep, activeTour: activeTour?.id ?? null,
    }}>
      {children}
      {activeTour && currentStep && targetRect && createPortal(
        <>
          {/* SVG overlay with spotlight cutout */}
          <svg className="fixed inset-0 z-[9998]" width="100%" height="100%"
            onClick={endTour} style={{ pointerEvents: "auto" }}>
            <defs>
              <mask id="tour-mask">
                <rect width="100%" height="100%" fill="white" />
                <rect x={targetRect.left - 8} y={targetRect.top - 8}
                  width={targetRect.width + 16} height={targetRect.height + 16}
                  rx={8} fill="black" />
              </mask>
            </defs>
            <rect width="100%" height="100%" fill="rgba(0,0,0,0.5)"
              mask="url(#tour-mask)" />
            <rect x={targetRect.left - 8} y={targetRect.top - 8}
              width={targetRect.width + 16} height={targetRect.height + 16}
              fill="transparent" onClick={(e) => e.stopPropagation()} />
          </svg>

          {/* Tooltip */}
          <div className="fixed z-[9999] w-72 rounded-lg bg-white p-4 shadow-xl
            border border-gray-200"
            style={getTooltipStyle(currentStep.placement, targetRect)}>
            <p className="text-xs text-gray-400 mb-1">
              Step {stepIndex + 1} of {activeTour.steps.length}
            </p>
            <h4 className="text-sm font-semibold text-gray-900 mb-1">
              {currentStep.title}
            </h4>
            <p className="text-sm text-gray-600 mb-3">{currentStep.content}</p>
            <div className="flex items-center justify-between">
              <button onClick={endTour}
                className="text-xs text-gray-500 hover:text-gray-700">
                Skip tour
              </button>
              {currentStep.advanceOn === "click" ? (
                <span className="text-xs text-blue-600 italic">
                  Click the element to continue
                </span>
              ) : (
                <button onClick={nextStep}
                  className="rounded-md bg-blue-600 px-3 py-1.5 text-xs
                    font-medium text-white hover:bg-blue-700">
                  {stepIndex === activeTour.steps.length - 1 ? "Finish" : "Next"}
                </button>
              )}
            </div>
          </div>
        </>,
        document.body
      )}
    </TourContext.Provider>
  );
}

function getTooltipStyle(
  placement: TourStep["placement"], rect: DOMRect
): React.CSSProperties {
  const OFFSET = 16;
  switch (placement) {
    case "top": return {
      bottom: window.innerHeight - rect.top + OFFSET,
      left: rect.left + rect.width / 2 - 144,
    };
    case "bottom": return {
      top: rect.bottom + OFFSET,
      left: rect.left + rect.width / 2 - 144,
    };
    case "left": return {
      top: rect.top + rect.height / 2 - 60,
      right: window.innerWidth - rect.left + OFFSET,
    };
    case "right": return {
      top: rect.top + rect.height / 2 - 60,
      left: rect.right + OFFSET,
    };
  }
}

// src/components/ui/empty-state.tsx
import Link from "next/link";

type EmptyStateProps = {
  icon: React.ReactNode;
  title: string;
  description: string;
  actionLabel: string;
  actionHref?: string;
  onAction?: () => void;
  secondaryLabel?: string;
  secondaryHref?: string;
};

export function EmptyState({
  icon, title, description, actionLabel, actionHref, onAction,
  secondaryLabel, secondaryHref,
}: EmptyStateProps) {
  return (
    <div className="flex flex-col items-center justify-center py-16 px-4 text-center">
      <div className="mb-4 rounded-full bg-gray-100 p-4 text-gray-400">{icon}</div>
      <h3 className="text-lg font-semibold text-gray-900 mb-2">{title}</h3>
      <p className="text-sm text-gray-600 max-w-sm mb-6">{description}</p>
      <div className="flex items-center gap-3">
        {actionHref ? (
          <Link href={actionHref}
            className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium
              text-white hover:bg-blue-700">
            {actionLabel}
          </Link>
        ) : (
          <button onClick={onAction}
            className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium
              text-white hover:bg-blue-700">
            {actionLabel}
          </button>
        )}
        {secondaryLabel && secondaryHref && (
          <Link href={secondaryHref}
            className="text-sm text-gray-600 hover:text-gray-900 underline">
            {secondaryLabel}
          </Link>
        )}
      </div>
    </div>
  );
}

// src/app/dashboard/projects/page.tsx
import { db } from "@/lib/db";
import { auth } from "@/lib/auth";
import { EmptyState } from "@/components/ui/empty-state";
import { FolderOpen } from "lucide-react";
import { ProjectList } from "@/components/projects/project-list";

export default async function ProjectsPage() {
  const session = await auth();
  if (!session?.user?.id) return null;

  const projects = await db.project.findMany({
    where: { userId: session.user.id },
    orderBy: { updatedAt: "desc" },
  });

  const hasEverCreated = await db.onboardingEvent.findFirst({
    where: { userId: session.user.id, toStep: "FIRST_ITEM_CREATED" },
  });

  if (projects.length === 0 && !hasEverCreated) {
    return (
      <EmptyState
        icon={<FolderOpen className="h-8 w-8" />}
        title="Create your first project"
        description="Projects help you organize your work. Create one to get
          started and see how everything comes together."
        actionLabel="Create project"
        actionHref="/projects/new"
        secondaryLabel="Watch a 30-second demo"
        secondaryHref="/demo/projects"
      />
    );
  }

  if (projects.length === 0) {
    return (
      <EmptyState
        icon={<FolderOpen className="h-8 w-8" />}
        title="No projects"
        description="You don't have any active projects."
        actionLabel="New project"
        actionHref="/projects/new"
      />
    );
  }

  return <ProjectList projects={projects} />;
}

-- Onboarding funnel by segment (last 30 days)
WITH signups AS (
  SELECT id AS user_id, segment, created_at
  FROM users
  WHERE created_at >= NOW() - INTERVAL '30 days'
),
completions AS (
  SELECT s.user_id, s.segment, oe.to_step
  FROM signups s
  INNER JOIN onboarding_events oe ON s.user_id = oe.user_id
)
SELECT
  segment,
  COUNT(DISTINCT user_id) AS signups,
  COUNT(DISTINCT user_id) FILTER (WHERE to_step = 'WORKSPACE_CREATED') AS workspaces,
  COUNT(DISTINCT user_id) FILTER (WHERE to_step = 'FIRST_ITEM_CREATED') AS first_items,
  COUNT(DISTINCT user_id) FILTER (WHERE to_step = 'ACTIVATED') AS activated,
  ROUND(
    COUNT(DISTINCT user_id) FILTER (WHERE to_step = 'ACTIVATED')::numeric /
    NULLIF(COUNT(DISTINCT user_id), 0) * 100, 1
  ) AS activation_rate_pct
FROM (SELECT DISTINCT user_id, segment FROM signups) base
LEFT JOIN completions USING (user_id, segment)
GROUP BY segment ORDER BY segment;

-- Time-to-value distribution by segment (p50/p75/p90 in minutes)
SELECT
  segment,
  COUNT(*) AS activated_users,
  ROUND(PERCENTILE_CONT(0.50) WITHIN GROUP (
    ORDER BY EXTRACT(EPOCH FROM (activated_at - created_at))
  )::numeric / 60, 1) AS p50_minutes,
  ROUND(PERCENTILE_CONT(0.75) WITHIN GROUP (
    ORDER BY EXTRACT(EPOCH FROM (activated_at - created_at))
  )::numeric / 60, 1) AS p75_minutes,
  ROUND(PERCENTILE_CONT(0.90) WITHIN GROUP (
    ORDER BY EXTRACT(EPOCH FROM (activated_at - created_at))
  )::numeric / 60, 1) AS p90_minutes
FROM users
WHERE activated_at IS NOT NULL
  AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY segment ORDER BY segment;

-- Activation cohort: % activated within 1, 3, 7 days per weekly cohort
SELECT
  DATE_TRUNC('week', created_at) AS cohort_week,
  COUNT(*) AS signups,
  COUNT(*) FILTER (
    WHERE activated_at <= created_at + INTERVAL '1 day'
  ) AS activated_day_1,
  COUNT(*) FILTER (
    WHERE activated_at <= created_at + INTERVAL '7 days'
  ) AS activated_day_7,
  ROUND(
    COUNT(*) FILTER (WHERE activated_at <= created_at + INTERVAL '7 days')::numeric
    / NULLIF(COUNT(*), 0) * 100, 1
  ) AS activation_rate_7d_pct
FROM users
WHERE created_at >= NOW() - INTERVAL '12 weeks'
GROUP BY cohort_week ORDER BY cohort_week;

const [completedSteps, setCompletedSteps] = useState<string[]>(() => {
  return JSON.parse(localStorage.getItem("onboarding") ?? "[]");
});

const user = await db.user.findUnique({
  where: { id: session.user.id },
  select: { onboardingStep: true, segment: true },
});

if (user.onboardingStep !== "ACTIVATED") {
  redirect("/onboarding"); // No escape
}

if (user.onboardingStep !== "ACTIVATED" && !user.onboardingDismissedAt) {
  // Show checklist alongside the product — do not redirect
}

<form>
  <input name="email" required />
  <input name="password" required />
  <input name="name" required />
  <input name="company" />       {/* ask later */}
  <select name="teamSize" />     {/* ask later */}
  <textarea name="useCase" />    {/* ask later */}
</form>

const steps = getStepsForSegment(user.segment);
// Developer: API key → Code example → First API call → Activated
// Manager: Workspace → Invite team → Create project → Activated

{projects.length === 0 && <p>No projects found.</p>}

{projects.length === 0 && (
  <EmptyState
    icon={<FolderOpen className="h-8 w-8" />}
    title="Create your first project"
    description="Projects organize your work. Create one to see how it works."
    actionLabel="Create project"
    actionHref="/projects/new"
  />
)}

<Modal open={tourActive}>
  <p>Here you can see your projects.</p>
  <button onClick={nextStep}>Next</button>
</Modal>

analytics.track("user_activated", { userId });
// Where is activated_at in the database? Nowhere.

await db.user.update({
  where: { id: userId },
  data: { activatedAt: new Date() },
});
trackServerEvent(userId, "onboarding_completed", { duration_seconds: ttv });

if (user.onboardingStep === "step_2") { /* ... */ }
// In another file:
const isOnboarding = !["step_5", "completed"].includes(user.onboardingStep);

import { STEP_CONFIG, getStepsForSegment } from "@/lib/onboarding/steps";
const steps = getStepsForSegment(user.segment);
const isOnboarding = steps.indexOf(user.onboardingStep) < steps.indexOf("ACTIVATED");

SELECT
  ROUND(PERCENTILE_CONT(0.50) WITHIN GROUP (
    ORDER BY EXTRACT(EPOCH FROM (activated_at - created_at))
  )::numeric / 60, 1) AS p50_minutes,
  ROUND(PERCENTILE_CONT(0.90) WITHIN GROUP (
    ORDER BY EXTRACT(EPOCH FROM (activated_at - created_at))
  )::numeric / 60, 1) AS p90_minutes
FROM users
WHERE activated_at IS NOT NULL AND created_at >= NOW() - INTERVAL '30 days';

useEffect(() => {
  startTour("dashboard_intro"); // Fires every mount
}, []);

useEffect(() => {
  if (!completedTours.includes("dashboard_intro")) {
    startTour("dashboard_intro");
  }
}, [completedTours]);