Replace multi-screen onboarding with single checklist view

Replaces the 4 separate onboarding screens with a unified checklist
showing all steps (sign in, join org, start session) with live status.
Adds org membership polling via new GET /auth/org-membership endpoint
that reuses existing check_org_membership(). Join link opens as popup
and auto-closes when membership is detected.

backend/routes/auth.py

@@ -10,7 +10,7 @@ import time
 from urllib.parse import urlencode
 
 import httpx
-from dependencies import AUTH_ENABLED, get_current_user
+from dependencies import AUTH_ENABLED, check_org_membership, get_current_user
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import RedirectResponse
 
@@ -169,3 +169,20 @@ async def get_me(user: dict = Depends(get_current_user)) -> dict:
     Uses the shared auth dependency which handles cookie + Bearer token.
     """
     return user
+
+
+ORG_NAME = "ml-agent-explorers"
+
+
+@router.get("/org-membership")
+async def org_membership(
+    request: Request, user: dict = Depends(get_current_user)
+) -> dict:
+    """Check if the authenticated user belongs to the ml-agent-explorers org."""
+    if not AUTH_ENABLED:
+        return {"is_member": True}
+    token = request.cookies.get("hf_access_token") or ""
+    if not token:
+        return {"is_member": False}
+    is_member = await check_org_membership(token, ORG_NAME)
+    return {"is_member": is_member}

frontend/src/components/WelcomeScreen/WelcomeScreen.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback, useEffect, useRef } from 'react';
+import { useState, useCallback, type ReactNode } from 'react';
 import {
   Box,
   Typography,
@@ -6,53 +6,210 @@ import {
   CircularProgress,
   Alert,
 } from '@mui/material';
+import CheckCircleIcon from '@mui/icons-material/CheckCircle';
 import OpenInNewIcon from '@mui/icons-material/OpenInNew';
 import GroupAddIcon from '@mui/icons-material/GroupAdd';
+import LoginIcon from '@mui/icons-material/Login';
+import RocketLaunchIcon from '@mui/icons-material/RocketLaunch';
 import { useSessionStore } from '@/store/sessionStore';
 import { useAgentStore } from '@/store/agentStore';
 import { apiFetch } from '@/utils/api';
 import { isInIframe, triggerLogin } from '@/hooks/useAuth';
+import { useOrgMembership } from '@/hooks/useOrgMembership';
 
-/** HF brand orange */
 const HF_ORANGE = '#FF9D00';
+const ORG_JOIN_URL =
+  'https://huggingface.co/organizations/ml-agent-explorers/share/GzPMJUivoFPlfkvFtIqEouZKSytatKQSZT';
 
-const ORG_JOIN_URL = 'https://huggingface.co/organizations/ml-agent-explorers/share/GzPMJUivoFPlfkvFtIqEouZKSytatKQSZT';
-const ORG_JOINED_KEY = 'hf-agent-org-joined';
+// ---------------------------------------------------------------------------
+// ChecklistStep sub-component
+// ---------------------------------------------------------------------------
 
-function hasJoinedOrg(): boolean {
-  try { return localStorage.getItem(ORG_JOINED_KEY) === '1'; } catch { return false; }
+type StepStatus = 'completed' | 'active' | 'locked';
+
+interface ChecklistStepProps {
+  stepNumber: number;
+  title: string;
+  description: string;
+  status: StepStatus;
+  lockedReason?: string;
+  actionLabel?: string;
+  onAction?: () => void;
+  actionIcon?: ReactNode;
+  actionHref?: string;
+  loading?: boolean;
+  isLast?: boolean;
 }
 
-function markOrgJoined(): void {
-  try { localStorage.setItem(ORG_JOINED_KEY, '1'); } catch { /* ignore */ }
+function StepIndicator({ status, stepNumber }: { status: StepStatus; stepNumber: number }) {
+  if (status === 'completed') {
+    return <CheckCircleIcon sx={{ fontSize: 28, color: 'var(--accent-green)' }} />;
+  }
+  return (
+    <Box
+      sx={{
+        width: 28,
+        height: 28,
+        borderRadius: '50%',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        fontSize: '0.8rem',
+        fontWeight: 700,
+        ...(status === 'active'
+          ? { bgcolor: HF_ORANGE, color: '#000' }
+          : { bgcolor: 'transparent', border: '2px solid var(--border)', color: 'var(--muted-text)' }),
+      }}
+    >
+      {stepNumber}
+    </Box>
+  );
 }
 
+function ChecklistStep({
+  stepNumber,
+  title,
+  description,
+  status,
+  lockedReason,
+  actionLabel,
+  onAction,
+  actionIcon,
+  actionHref,
+  loading = false,
+  isLast = false,
+}: ChecklistStepProps) {
+  const btnSx = {
+    px: 3,
+    py: 0.75,
+    fontSize: '0.85rem',
+    fontWeight: 700,
+    textTransform: 'none' as const,
+    borderRadius: '10px',
+    whiteSpace: 'nowrap' as const,
+    textDecoration: 'none',
+    ...(status === 'active'
+      ? {
+          bgcolor: HF_ORANGE,
+          color: '#000',
+          boxShadow: '0 2px 12px rgba(255, 157, 0, 0.25)',
+          '&:hover': { bgcolor: '#FFB340', boxShadow: '0 4px 20px rgba(255, 157, 0, 0.4)' },
+        }
+      : {
+          bgcolor: 'rgba(255,255,255,0.04)',
+          color: 'var(--muted-text)',
+          '&.Mui-disabled': { bgcolor: 'rgba(255,255,255,0.04)', color: 'var(--muted-text)' },
+        }),
+  };
+
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 2,
+        px: 3,
+        py: 2.5,
+        borderLeft: '3px solid',
+        borderLeftColor:
+          status === 'completed'
+            ? 'var(--accent-green)'
+            : status === 'active'
+              ? HF_ORANGE
+              : 'transparent',
+        ...(!isLast && { borderBottom: '1px solid var(--border)' }),
+        opacity: status === 'locked' ? 0.55 : 1,
+        transition: 'opacity 0.2s, border-color 0.2s',
+      }}
+    >
+      <StepIndicator status={status} stepNumber={stepNumber} />
+
+      <Box sx={{ flex: 1, minWidth: 0 }}>
+        <Typography
+          variant="subtitle2"
+          sx={{
+            fontWeight: 600,
+            fontSize: '0.92rem',
+            color: status === 'completed' ? 'var(--muted-text)' : 'var(--text)',
+            ...(status === 'completed' && { textDecoration: 'line-through', textDecorationColor: 'var(--muted-text)' }),
+          }}
+        >
+          {title}
+        </Typography>
+        <Typography variant="body2" sx={{ color: 'var(--muted-text)', fontSize: '0.8rem', mt: 0.25, lineHeight: 1.5 }}>
+          {status === 'locked' && lockedReason ? lockedReason : description}
+        </Typography>
+      </Box>
+
+      {status === 'completed' ? (
+        <Typography variant="caption" sx={{ color: 'var(--accent-green)', fontWeight: 600, fontSize: '0.78rem', whiteSpace: 'nowrap' }}>
+          Done
+        </Typography>
+      ) : actionLabel ? (
+        actionHref ? (
+          <Button
+            variant="contained"
+            size="small"
+            component="a"
+            href={actionHref}
+            target="_blank"
+            rel="noopener noreferrer"
+            disabled={status === 'locked'}
+            startIcon={actionIcon}
+            sx={btnSx}
+            onClick={onAction}
+          >
+            {actionLabel}
+          </Button>
+        ) : (
+          <Button
+            variant="contained"
+            size="small"
+            disabled={status === 'locked' || loading}
+            startIcon={loading ? <CircularProgress size={16} color="inherit" /> : actionIcon}
+            onClick={onAction}
+            sx={btnSx}
+          >
+            {loading ? 'Loading...' : actionLabel}
+          </Button>
+        )
+      ) : null}
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// WelcomeScreen
+// ---------------------------------------------------------------------------
+
 export default function WelcomeScreen() {
   const { createSession } = useSessionStore();
   const { setPlan, clearPanel, user } = useAgentStore();
   const [isCreating, setIsCreating] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  const [orgJoined, setOrgJoined] = useState(hasJoinedOrg);
-  const joinLinkOpened = useRef(false);
 
   const inIframe = isInIframe();
-  const isAuthenticated = user?.authenticated;
+  const isAuthenticated = !!user?.authenticated;
   const isDevUser = user?.username === 'dev';
+  const isOrgMember = !!user?.orgMember;
+
+  // Poll for org membership once authenticated (skipped in dev mode)
+  const popupRef = useOrgMembership(isAuthenticated && !isDevUser && !isOrgMember);
 
-  // Auto-advance when user returns from the join link
-  useEffect(() => {
-    const handleVisibility = () => {
-      if (document.visibilityState !== 'visible' || !joinLinkOpened.current) return;
-      joinLinkOpened.current = false;
-      markOrgJoined();
-      setOrgJoined(true);
-    };
+  // ---- Actions ----
 
-    document.addEventListener('visibilitychange', handleVisibility);
-    return () => document.removeEventListener('visibilitychange', handleVisibility);
-  }, []);
+  const handleJoinOrg = useCallback(() => {
+    const popup = window.open(ORG_JOIN_URL, 'hf-org-join', 'noopener');
+    if (popup) {
+      popupRef.current = popup;
+    } else {
+      // Popup blocked — fall back to regular navigation
+      window.open(ORG_JOIN_URL, '_blank', 'noopener,noreferrer');
+    }
+  }, [popupRef]);
 
-  const tryCreateSession = useCallback(async () => {
+  const handleStartSession = useCallback(async () => {
+    if (isCreating) return;
     setIsCreating(true);
     setError(null);
 
@@ -80,72 +237,21 @@ export default function WelcomeScreen() {
     } finally {
       setIsCreating(false);
     }
-  }, [createSession, setPlan, clearPanel]);
-
-  const handleStart = useCallback(async () => {
-    if (isCreating) return;
+  }, [isCreating, createSession, setPlan, clearPanel]);
 
-    if (!isAuthenticated && !isDevUser) {
-      if (inIframe) return;
-      triggerLogin();
-      return;
-    }
+  // ---- Step status helpers ----
 
-    await tryCreateSession();
-  }, [isCreating, isAuthenticated, isDevUser, inIframe, tryCreateSession]);
+  const signInStatus: StepStatus = isAuthenticated ? 'completed' : 'active';
+  const joinOrgStatus: StepStatus = isOrgMember ? 'completed' : isAuthenticated ? 'active' : 'locked';
+  const startStatus: StepStatus = isAuthenticated && isOrgMember ? 'active' : 'locked';
 
-  // Build the direct Space URL for the "open in new tab" link
-  const spaceHost = typeof window !== 'undefined'
-    ? window.location.hostname.includes('.hf.space')
-      ? window.location.origin
-      : `https://smolagents-ml-agent.hf.space`
-    : '';
-
-  // Shared button style
-  const primaryBtnSx = {
-    px: 5,
-    py: 1.5,
-    fontSize: '1rem',
-    fontWeight: 700,
-    textTransform: 'none' as const,
-    borderRadius: '12px',
-    bgcolor: HF_ORANGE,
-    color: '#000',
-    boxShadow: '0 4px 24px rgba(255, 157, 0, 0.3)',
-    textDecoration: 'none',
-    '&:hover': {
-      bgcolor: '#FFB340',
-      boxShadow: '0 6px 32px rgba(255, 157, 0, 0.45)',
-    },
-  };
-
-  // Description block (reused across screens)
-  const description = (
-    <Typography
-      variant="body1"
-      sx={{
-        color: 'var(--muted-text)',
-        maxWidth: 520,
-        mb: 5,
-        lineHeight: 1.8,
-        fontSize: '0.95rem',
-        textAlign: 'center',
-        px: 2,
-        '& strong': { color: 'var(--text)', fontWeight: 600 },
-      }}
-    >
-      A general-purpose AI agent for <strong>machine learning engineering</strong>.
-      It browses <strong>Hugging Face documentation</strong>, manages{' '}
-      <strong>repositories</strong>, launches <strong>training jobs</strong>,
-      and explores <strong>datasets</strong> — all through natural conversation.
-    </Typography>
-  );
-
-  // Which screen to show
-  const needsJoin = inIframe && !orgJoined;
-  const showOpenAgent = inIframe && orgJoined;
-  const showSignin = !inIframe && !isAuthenticated && !isDevUser;
-  const showReady = !inIframe && (isAuthenticated || isDevUser);
+  // Space URL for iframe "Open HF Agent" step
+  const spaceHost =
+    typeof window !== 'undefined'
+      ? window.location.hostname.includes('.hf.space')
+        ? window.location.origin
+        : 'https://smolagents-ml-agent.hf.space'
+      : '';
 
   return (
     <Box
@@ -160,12 +266,12 @@ export default function WelcomeScreen() {
         py: 8,
       }}
     >
-      {/* HF Logo */}
+      {/* Logo */}
       <Box
         component="img"
         src="https://huggingface.co/front/assets/huggingface_logo-noborder.svg"
         alt="Hugging Face"
-        sx={{ width: 96, height: 96, mb: 3, display: 'block' }}
+        sx={{ width: 80, height: 80, mb: 2.5, display: 'block' }}
       />
 
       {/* Title */}
@@ -174,120 +280,128 @@ export default function WelcomeScreen() {
         sx={{
           fontWeight: 800,
           color: 'var(--text)',
-          mb: 1.5,
+          mb: 1,
           letterSpacing: '-0.02em',
-          fontSize: { xs: '2rem', md: '2.8rem' },
+          fontSize: { xs: '1.8rem', md: '2.4rem' },
         }}
       >
         HF Agent
       </Typography>
 
-      {/* ── Iframe: join org (first visit only) ──────────────────── */}
-      {needsJoin && (
-        <>
-          <Typography
-            variant="body1"
-            sx={{
-              color: 'var(--muted-text)',
-              maxWidth: 480,
-              mb: 4,
-              lineHeight: 1.8,
-              fontSize: '0.95rem',
-              textAlign: 'center',
-              px: 2,
-              '& strong': { color: 'var(--text)', fontWeight: 600 },
-            }}
-          >
-            Under the hood, this agent uses GPUs, inference APIs, and other paid Hub goodies — but we made them all free for you. Just join <strong>ML Agent Explorers</strong> to get started!
-          </Typography>
-
-          <Button
-            variant="contained"
-            size="large"
-            component="a"
-            href={ORG_JOIN_URL}
-            target="_blank"
-            rel="noopener noreferrer"
-            onClick={() => { joinLinkOpened.current = true; }}
-            startIcon={<GroupAddIcon />}
-            sx={primaryBtnSx}
-          >
-            Join ML Agent Explorers
-          </Button>
-        </>
-      )}
-
-      {/* ── Iframe: already joined → open Space ──────────────────── */}
-      {showOpenAgent && (
-        <>
-          {description}
-          <Button
-            variant="contained"
-            size="large"
-            component="a"
-            href={spaceHost}
-            target="_blank"
-            rel="noopener noreferrer"
-            endIcon={<OpenInNewIcon />}
-            sx={primaryBtnSx}
-          >
-            Open HF Agent
-          </Button>
-        </>
-      )}
-
-      {/* ── Direct: not logged in → sign in ──────────────────────── */}
-      {showSignin && (
-        <>
-          {description}
-          <Button
-            variant="contained"
-            size="large"
-            onClick={() => triggerLogin()}
-            sx={primaryBtnSx}
-          >
-            Sign in with Hugging Face
-          </Button>
+      {/* Description */}
+      <Typography
+        variant="body1"
+        sx={{
+          color: 'var(--muted-text)',
+          maxWidth: 480,
+          mb: 4,
+          lineHeight: 1.7,
+          fontSize: '0.9rem',
+          textAlign: 'center',
+          px: 2,
+          '& strong': { color: 'var(--text)', fontWeight: 600 },
+        }}
+      >
+        A general-purpose AI agent for <strong>machine learning engineering</strong>.
+        It browses <strong>Hugging Face docs</strong>, manages <strong>repos</strong>,
+        launches <strong>training jobs</strong>, and explores <strong>datasets</strong>.
+      </Typography>
 
-          <Typography
-            variant="caption"
-            sx={{
-              mt: 2.5,
-              color: 'var(--muted-text)',
-              fontSize: '0.78rem',
-              textAlign: 'center',
-              maxWidth: 360,
-              lineHeight: 1.6,
-            }}
-          >
-            Make sure to enable access to the <strong>ml-agent-explorers</strong> org when prompted.
-          </Typography>
-        </>
-      )}
+      {/* ── Checklist ──────────────────────────────────────────── */}
+      <Box
+        sx={{
+          width: '100%',
+          maxWidth: 520,
+          bgcolor: 'var(--surface)',
+          border: '1px solid var(--border)',
+          borderRadius: '12px',
+          overflow: 'hidden',
+          mx: 2,
+        }}
+      >
+        {isDevUser ? (
+          /* Dev mode: single step */
+          <ChecklistStep
+            stepNumber={1}
+            title="Start Session"
+            description="Launch an AI agent session for ML engineering."
+            status="active"
+            actionLabel="Start Session"
+            actionIcon={<RocketLaunchIcon sx={{ fontSize: 16 }} />}
+            onAction={handleStartSession}
+            loading={isCreating}
+            isLast
+          />
+        ) : inIframe ? (
+          /* Iframe: 2 steps */
+          <>
+            <ChecklistStep
+              stepNumber={1}
+              title="Join ML Agent Explorers"
+              description="Get free access to GPUs, inference APIs, and Hub resources."
+              status={isOrgMember ? 'completed' : 'active'}
+              actionLabel="Join Organization"
+              actionIcon={<GroupAddIcon sx={{ fontSize: 16 }} />}
+              onAction={handleJoinOrg}
+            />
+            <ChecklistStep
+              stepNumber={2}
+              title="Open HF Agent"
+              description="Open the agent in a full browser tab to get started."
+              status={isOrgMember ? 'active' : 'locked'}
+              lockedReason="Join the organization first."
+              actionLabel="Open HF Agent"
+              actionIcon={<OpenInNewIcon sx={{ fontSize: 16 }} />}
+              actionHref={spaceHost}
+              isLast
+            />
+          </>
+        ) : (
+          /* Direct access: 3 steps */
+          <>
+            <ChecklistStep
+              stepNumber={1}
+              title="Sign in with Hugging Face"
+              description="Authenticate to access GPU resources and model APIs."
+              status={signInStatus}
+              actionLabel="Sign in"
+              actionIcon={<LoginIcon sx={{ fontSize: 16 }} />}
+              onAction={() => triggerLogin()}
+            />
+            <ChecklistStep
+              stepNumber={2}
+              title="Join ML Agent Explorers"
+              description="Get free access to GPUs, inference APIs, and Hub resources."
+              status={joinOrgStatus}
+              lockedReason="Sign in first to continue."
+              actionLabel="Join Organization"
+              actionIcon={<GroupAddIcon sx={{ fontSize: 16 }} />}
+              onAction={handleJoinOrg}
+            />
+            <ChecklistStep
+              stepNumber={3}
+              title="Start Session"
+              description="Launch an AI agent session for ML engineering."
+              status={startStatus}
+              lockedReason="Complete the steps above to continue."
+              actionLabel="Start Session"
+              actionIcon={<RocketLaunchIcon sx={{ fontSize: 16 }} />}
+              onAction={handleStartSession}
+              loading={isCreating}
+              isLast
+            />
+          </>
+        )}
+      </Box>
 
-      {/* ── Direct: authenticated → start session ────────────────── */}
-      {showReady && (
-        <>
-          {description}
-          <Button
-            variant="contained"
-            size="large"
-            onClick={handleStart}
-            disabled={isCreating}
-            startIcon={
-              isCreating ? <CircularProgress size={20} color="inherit" /> : null
-            }
-            sx={{
-              ...primaryBtnSx,
-              '&.Mui-disabled': {
-                bgcolor: 'rgba(255, 157, 0, 0.35)',
-                color: 'rgba(0,0,0,0.45)',
-              },
-            }}
-          >
-            {isCreating ? 'Initializing...' : 'Start Session'}
-          </Button>
-        </>
+      {/* Polling hint when waiting for org join */}
+      {isAuthenticated && !isOrgMember && !isDevUser && !inIframe && (
+        <Typography
+          variant="caption"
+          sx={{ mt: 2, color: 'var(--muted-text)', fontSize: '0.75rem', textAlign: 'center' }}
+        >
+          This page updates automatically when you join the organization.
+        </Typography>
       )}
 
       {/* Error */}
@@ -311,7 +425,7 @@ export default function WelcomeScreen() {
       {/* Footnote */}
       <Typography
         variant="caption"
-        sx={{ mt: 5, color: 'var(--muted-text)', opacity: 0.5, fontSize: '0.7rem' }}
+        sx={{ mt: 4, color: 'var(--muted-text)', opacity: 0.5, fontSize: '0.7rem' }}
       >
         Conversations are stored locally in your browser.
       </Typography>

frontend/src/hooks/useOrgMembership.ts

@@ -0,0 +1,45 @@
+/**
+ * Polls backend for org membership status.
+ * When membership is detected, updates the user in the agent store
+ * and closes any org-join popup that was opened.
+ */
+import { useEffect, useRef } from 'react';
+import { useAgentStore } from '@/store/agentStore';
+
+const POLL_INTERVAL_MS = 3000;
+
+/**
+ * @param enabled  Only poll when true (user is authenticated but not yet confirmed as org member)
+ * @returns popupRef — assign `window.open()` result to `.current` so the hook can auto-close it
+ */
+export function useOrgMembership(enabled: boolean) {
+  const user = useAgentStore((s) => s.user);
+  const setUser = useAgentStore((s) => s.setUser);
+  const popupRef = useRef<Window | null>(null);
+
+  useEffect(() => {
+    if (!enabled || user?.orgMember) return;
+
+    let cancelled = false;
+
+    const check = async () => {
+      try {
+        const res = await fetch('/auth/org-membership', { credentials: 'include' });
+        if (!res.ok || cancelled) return;
+        const data = await res.json();
+        if (cancelled) return;
+        if (data.is_member && user) {
+          setUser({ ...user, orgMember: true });
+          try { popupRef.current?.close(); } catch { /* cross-origin or already closed */ }
+          popupRef.current = null;
+        }
+      } catch { /* backend unreachable — skip */ }
+    };
+
+    check();
+    const id = setInterval(check, POLL_INTERVAL_MS);
+    return () => { cancelled = true; clearInterval(id); };
+  }, [enabled, user?.orgMember, user, setUser]);
+
+  return popupRef;
+}

frontend/src/types/agent.ts

@@ -29,4 +29,5 @@ export interface User {
   username?: string;
   name?: string;
   picture?: string;
+  orgMember?: boolean;
 }