Add Onboarding tour (#48)

* Upgraded onboarding experience by adding OnboardingTour component and related configuration.Using Reactour each indivual component is highlighted. Updated package.json to include @reactour/tour for onboarding functionality. Introduced TESTING_ONBOARDING flag in App.js to control tour visibility during development this allows for quick and easy changes.

* Refactor onboarding logic to utilize environment variable for TESTING_ONBOARDING flag in App.js. Enhanced OnboardingTour component by integrating dynamic feature and advisor data from AppConfigContext, improving the onboarding experience with customizable content based on backend configuration.

* Add onboarding and canvas configurations to YAML files and backend models

- Introduced onboarding features for both PhD and undergraduate configurations, including AI advisor advice, conversation saving, document uploads, and progress tracking.
- Added canvas configurations with tour titles and descriptions for PhD and undergraduate journeys.
- Updated backend models to include new onboarding and canvas configurations, ensuring they are integrated into the application settings.

* Pass `REACT_APP_TESTING_ONBOARDING` envvar to frontend container

* Rebase Complete

* Update App.js

* Refactor onboarding configuration by removing canvas settings

- Removed the CanvasConfig from the onboarding configuration in both the YAML and backend model files.
- Updated the OnboardingTour component to reference the onboarding configuration for tour titles and bodies instead of the removed canvas settings, streamlining the onboarding experience.

---------

Co-authored-by: Daniel McKnight <daniel@neon.ai>

docker-compose.yml

@@ -32,6 +32,7 @@ services:
       - backend
     environment:
       REACT_APP_API_URL: ${REACT_APP_API_URL:-http://localhost:8000}
+      REACT_APP_TESTING_ONBOARDING: ${REACT_APP_TESTING_ONBOARDING:-false}
   database:
     image: mongo:8.0
     volumes:

multi_llm_chatbot_backend/app/config.py

@@ -88,6 +88,12 @@ class ChatPageConfig(BaseModel):
     examples: List[ExampleCategory] = []
 
 
+class OnboardingConfig(BaseModel):
+    features: List[FeatureConfig] = []
+    tour_title: str = ""
+    tour_body: str = ""
+
+
 class PersonaItemConfig(_IconValidatorMixin):
     id: str
     name: str
@@ -305,6 +311,7 @@ class AppSettings(BaseModel):
     homepage: HomepageConfig = HomepageConfig()
     login: LoginConfig = LoginConfig()
     chat_page: ChatPageConfig = ChatPageConfig()
+    onboarding: OnboardingConfig = OnboardingConfig()
     personas: PersonasConfig = PersonasConfig()
     orchestrator: OrchestratorConfig = OrchestratorConfig()
     auth: AuthConfig = AuthConfig()
@@ -326,6 +333,7 @@ class AppSettings(BaseModel):
             "homepage": self.homepage.dict(),
             "login": self.login.dict(),
             "chat_page": self.chat_page.dict(),
+            "onboarding": self.onboarding.dict(),
             "personas": {
                 "items": [p.to_frontend_config() for p in self.personas.items],
             },

phd-advisor-frontend/package-lock.json

@@ -8,6 +8,7 @@
       "name": "phd-advisor-frontend",
       "version": "0.1.0",
       "dependencies": {
+        "@reactour/tour": "^3.8.0",
         "@testing-library/dom": "^10.4.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
@@ -3090,6 +3091,57 @@
         }
       }
     },
+    "node_modules/@reactour/mask": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@reactour/mask/-/mask-1.2.0.tgz",
+      "integrity": "sha512-XLgBLWfKJybtZjNTSO5lt/SIvRlCZBadB6JfE/hO1ErqURRjYhnv+edC0Ki1haUCqMGFppWk3lwcPCjmK0xNog==",
+      "license": "MIT",
+      "dependencies": {
+        "@reactour/utils": "*"
+      },
+      "peerDependencies": {
+        "react": "16.x || 17.x || 18.x || 19.x"
+      }
+    },
+    "node_modules/@reactour/popover": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@reactour/popover/-/popover-1.3.0.tgz",
+      "integrity": "sha512-YdyjSmHPvEeQEcJM4gcGFa5pI/Yf4nZGqwG4JnT+rK1SyUJBIPnm4Gkl/h7/+1g0KCFMkwNwagS3ZiXvZB7ThA==",
+      "license": "MIT",
+      "dependencies": {
+        "@reactour/utils": "*"
+      },
+      "peerDependencies": {
+        "react": "16.x || 17.x || 18.x || 19.x"
+      }
+    },
+    "node_modules/@reactour/tour": {
+      "version": "3.8.0",
+      "resolved": "https://registry.npmjs.org/@reactour/tour/-/tour-3.8.0.tgz",
+      "integrity": "sha512-KZTFi1pAvoTVKKRdBN5+XCYxXBp4k4Ql/acZcXyPvec8VU24fkMSEeV+v8krfYQpoVcewxIu3gM6xWZZLjxi7w==",
+      "license": "MIT",
+      "dependencies": {
+        "@reactour/mask": "*",
+        "@reactour/popover": "*",
+        "@reactour/utils": "*"
+      },
+      "peerDependencies": {
+        "react": "16.x || 17.x || 18.x || 19.x"
+      }
+    },
+    "node_modules/@reactour/utils": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/@reactour/utils/-/utils-0.6.0.tgz",
+      "integrity": "sha512-GqaLjQi7MJsgtAKjdiw2Eak1toFkADoLRnm1+HZpaD+yl+DkaHpC1N7JAl+kVOO5I17bWInPA+OFbXjO9Co8Qg==",
+      "license": "MIT",
+      "dependencies": {
+        "@rooks/use-mutation-observer": "^4.11.2",
+        "resize-observer-polyfill": "^1.5.1"
+      },
+      "peerDependencies": {
+        "react": "16.x || 17.x || 18.x || 19.x"
+      }
+    },
     "node_modules/@rollup/plugin-babel": {
       "version": "5.3.1",
       "resolved": "https://registry.npmjs.org/@rollup/plugin-babel/-/plugin-babel-5.3.1.tgz",
@@ -3169,6 +3221,15 @@
       "integrity": "sha512-EYNwp3bU+98cpU4lAWYYL7Zz+2gryWH1qbdDTidVd6hkiR6weksdbMadyXKXNPEkQFhXM+hVO9ZygomHXp+AIw==",
       "license": "MIT"
     },
+    "node_modules/@rooks/use-mutation-observer": {
+      "version": "4.11.2",
+      "resolved": "https://registry.npmjs.org/@rooks/use-mutation-observer/-/use-mutation-observer-4.11.2.tgz",
+      "integrity": "sha512-vpsdrZdr6TkB1zZJcHx+fR1YC/pHs2BaqcuYiEGjBVbwY5xcC49+h0hAUtQKHth3oJqXfIX/Ng8S7s5HFHdM/A==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": ">=16.8.0"
+      }
+    },
     "node_modules/@rtsao/scc": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@rtsao/scc/-/scc-1.1.0.tgz",
@@ -3866,16 +3927,6 @@
       "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
       "license": "MIT"
     },
-    "node_modules/@types/react": {
-      "version": "19.1.9",
-      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.1.9.tgz",
-      "integrity": "sha512-WmdoynAX8Stew/36uTSVMcLJJ1KRh6L3IZRx1PZ7qJtBqT3dYTgyDTx8H1qoRghErydW7xw9mSJ3wS//tCRpFA==",
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "csstype": "^3.0.2"
-      }
-    },
     "node_modules/@types/resolve": {
       "version": "1.17.1",
       "resolved": "https://registry.npmjs.org/@types/resolve/-/resolve-1.17.1.tgz",
@@ -6486,13 +6537,6 @@
       "integrity": "sha512-b0tGHbfegbhPJpxpiBPU2sCkigAqtM9O121le6bbOlgyV+NyGyCmVfJ6QW9eRjz8CpNfWEOYBIMIGRYkLwsIYg==",
       "license": "MIT"
     },
-    "node_modules/csstype": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz",
-      "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==",
-      "license": "MIT",
-      "peer": true
-    },
     "node_modules/damerau-levenshtein": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz",
@@ -15563,6 +15607,12 @@
       "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
       "license": "MIT"
     },
+    "node_modules/resize-observer-polyfill": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/resize-observer-polyfill/-/resize-observer-polyfill-1.5.1.tgz",
+      "integrity": "sha512-LwZrotdHOo12nQuZlHEmtuXdqGoOD0OhaxopaNFxWzInpEgaLWoVuAMbTzixuosCx2nEG58ngzW3vxdWoxIgdg==",
+      "license": "MIT"
+    },
     "node_modules/resolve": {
       "version": "1.22.10",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.10.tgz",
@@ -17704,20 +17754,6 @@
         "is-typedarray": "^1.0.0"
       }
     },
-    "node_modules/typescript": {
-      "version": "4.9.5",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz",
-      "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==",
-      "license": "Apache-2.0",
-      "peer": true,
-      "bin": {
-        "tsc": "bin/tsc",
-        "tsserver": "bin/tsserver"
-      },
-      "engines": {
-        "node": ">=4.2.0"
-      }
-    },
     "node_modules/unbox-primitive": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.1.0.tgz",

phd-advisor-frontend/package.json

@@ -10,6 +10,7 @@
     "lucide-react": "^0.544.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "@reactour/tour": "^3.8.0",
     "react-markdown": "^10.1.0",
     "react-scripts": "5.0.1",
     "remark-gfm": "^4.0.1",

phd-advisor-frontend/src/App.js

@@ -8,6 +8,11 @@ import CanvasPage from './pages/CanvasPage';
 import UserGuide from './components/UserGuide';
 import './styles/components.css';
 
+// Set REACT_APP_TESTING_ONBOARDING=true in your .env to force the onboarding
+// tour to run on every page load. Leave unset in production — tour will only
+// show once per user (localStorage).
+export const TESTING_ONBOARDING = process.env.REACT_APP_TESTING_ONBOARDING === 'true';
+
 function App() {
   const [currentView, setCurrentView] = useState('home');
   const [isAuthenticated, setIsAuthenticated] = useState(false);

phd-advisor-frontend/src/components/OnboardingTour.js

@@ -0,0 +1,320 @@
+import React, { useEffect, useMemo } from 'react';
+import { TourProvider, useTour } from '@reactour/tour';
+import { Hand, GraduationCap, Plus, MessageCircle, Paperclip, BarChart3 } from 'lucide-react';
+import { useTheme } from '../contexts/ThemeContext';
+import { useAppConfig } from '../contexts/AppConfigContext';
+import { TESTING_ONBOARDING } from '../App';
+import '../styles/OnboardingTour.css';
+
+const STORAGE_KEY = 'hasSeenOnboardingTour';
+
+// Fallbacks used when config.onboarding.* fields aren't provided by the backend.
+const DEFAULT_FEATURES = [
+  { Icon: GraduationCap, label: 'Get advice from specialized AI advisors' },
+  { Icon: MessageCircle, label: 'Save and revisit every conversation' },
+  { Icon: Paperclip, label: 'Upload PDFs and documents for context-aware answers' },
+  { Icon: BarChart3, label: 'Track your progress on a structured canvas' },
+];
+const DEFAULT_CANVAS_STEP = {
+  title: 'PhD Progress Canvas',
+  body: 'A dashboard view of your PhD journey — research progress, methodology, next steps, all in one place.',
+};
+
+const buildAdvisorBody = (advisors) => {
+  const names = Object.values(advisors || {}).map((a) => a.name).filter(Boolean);
+  if (names.length === 0) {
+    return "AI personas are ready to help. Click here anytime to see who's available.";
+  }
+  const firstThree = names.slice(0, 3).join(', ');
+  return `${names.length} AI personas are ready to help — ${firstThree}, and more. Click here anytime to see who's available.`;
+};
+
+const buildFeatures = (config, resolveIcon) => {
+  const fromConfig = config?.onboarding?.features;
+  if (!Array.isArray(fromConfig) || fromConfig.length === 0) return DEFAULT_FEATURES;
+  return fromConfig.map((f) => ({
+    Icon: f.icon ? resolveIcon(f.icon) : GraduationCap,
+    label: f.label || f.description || f.title || '',
+  }));
+};
+
+// Theme-resolved colors that match the rest of the app exactly
+const palette = (isDark) => ({
+  bg: isDark ? '#1F2937' : '#FFFFFF',
+  bgSubtle: isDark ? '#111827' : '#F9FAFB',
+  text: isDark ? '#F9FAFB' : '#111827',
+  textMuted: isDark ? '#D1D5DB' : '#6B7280',
+  textDim: isDark ? '#9CA3AF' : '#9CA3AF',
+  border: isDark ? '#374151' : '#E5E7EB',
+  accent: '#2663EB',
+  accentGrad: '#2663EB',
+  accentShadow: 'rgba(38, 99, 235, 0.45)',
+});
+
+// --- Step content -------------------------------------------------------
+const titleStyle = (c) => ({
+  margin: 0, fontSize: 22, fontWeight: 700, lineHeight: 1.2,
+  color: c.text, WebkitTextFillColor: c.text, letterSpacing: '-0.02em',
+});
+const bodyStyle = (c) => ({
+  margin: 0, fontSize: 15.5, lineHeight: 1.55,
+  color: c.textMuted, WebkitTextFillColor: c.textMuted,
+});
+
+const StepBody = ({ title, body, Icon, c }) => (
+  <div style={{ fontFamily: 'system-ui, -apple-system, sans-serif' }}>
+    <div style={{ display: 'flex', alignItems: 'center', gap: 14, marginBottom: 14 }}>
+      <div style={{
+        width: 48, height: 48, borderRadius: 14,
+        background: c.accent,
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+        flexShrink: 0,
+        boxShadow: `0 6px 16px -4px ${c.accentShadow}`,
+      }}>
+        <Icon size={24} color="#fff" strokeWidth={2.2} />
+      </div>
+      <div style={titleStyle(c)}>{title}</div>
+    </div>
+    <div style={bodyStyle(c)}>{body}</div>
+  </div>
+);
+
+const WelcomeBody = ({ c, title, subtitle, features }) => {
+  return (
+    <div style={{ fontFamily: 'system-ui, -apple-system, sans-serif', textAlign: 'center', padding: '4px 8px' }}>
+      <div style={{
+        width: 72, height: 72, borderRadius: 20, margin: '0 auto 20px',
+        background: c.accent,
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+        boxShadow: `0 12px 32px -8px ${c.accentShadow}`,
+      }}>
+        <Hand size={36} color="#fff" strokeWidth={2.2} />
+      </div>
+      <div style={{
+        margin: '0 0 12px', fontSize: 30, fontWeight: 800, lineHeight: 1.15,
+        color: c.text, WebkitTextFillColor: c.text, letterSpacing: '-0.025em',
+      }}>
+        Welcome to your<br />{title}
+      </div>
+      <div style={{
+        margin: '0 0 22px', fontSize: 16, lineHeight: 1.55,
+        color: c.textMuted, WebkitTextFillColor: c.textMuted,
+      }}>
+        {subtitle}
+      </div>
+      <div style={{
+        display: 'grid', gap: 14, textAlign: 'left',
+        background: c.bgSubtle,
+        border: `1px solid ${c.border}`,
+        borderRadius: 14, padding: '18px 20px',
+      }}>
+        {features.map(({ Icon, label }) => (
+          <div key={label} style={{ display: 'flex', alignItems: 'center', gap: 14 }}>
+            <div style={{
+              width: 32, height: 32, borderRadius: 8,
+              background: c.accent,
+              display: 'flex', alignItems: 'center', justifyContent: 'center',
+              flexShrink: 0,
+            }}>
+              <Icon size={18} color="#fff" strokeWidth={2.2} />
+            </div>
+            <span style={{ fontSize: 15, color: c.text, lineHeight: 1.4 }}>
+              {label}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+const buildSteps = (c, data) => [
+  {
+    selector: 'body',
+    position: 'center',
+    content: <WelcomeBody c={c} title={data.title} subtitle={data.subtitle} features={data.features} />,
+    styles: {
+      maskArea: (base) => ({ ...base, x: -10000, y: -10000, width: 0, height: 0 }),
+      popover: (base) => ({
+        ...base,
+        maxWidth: 540,
+        minWidth: 460,
+        padding: '32px 30px 24px',
+        borderRadius: 22,
+        background: c.bg,
+        backgroundColor: c.bg,
+        color: c.text,
+        border: `1px solid ${c.border}`,
+        boxShadow: '0 30px 80px -10px rgba(0,0,0,0.5)',
+      }),
+    },
+  },
+  {
+    selector: '.advisor-status-button',
+    content: <StepBody c={c} Icon={GraduationCap} title="Meet your advisors" body={data.advisorBody} />,
+  },
+  {
+    selector: '.new-chat-button',
+    content: <StepBody c={c} Icon={Plus} title="Start a new chat" body="Begin a fresh conversation. Each chat is saved automatically so you can return to it later." />,
+  },
+  {
+    selector: '.sessions-list',
+    content: <StepBody c={c} Icon={MessageCircle} title="Your past chats" body="All your previous conversations live here. Click any session to pick up where you left off." />,
+  },
+  {
+    selector: '.enhanced-chat-input-container',
+    content: <StepBody c={c} Icon={Paperclip} title="Ask anything" body="Type a question, attach a PDF or document for context, and your advisors will respond with diverse perspectives." />,
+  },
+  {
+    selector: '.sidebar-canvas-btn',
+    content: <StepBody c={c} Icon={BarChart3} title={data.canvas.title} body={data.canvas.body} />,
+  },
+];
+
+// --- Custom Buttons -----------------------------------------------------
+const makeButtons = (c) => {
+  const ghostBtn = {
+    background: 'transparent', color: c.textMuted,
+    border: `1px solid ${c.border}`, padding: '10px 18px',
+    borderRadius: 10, fontSize: 14, fontWeight: 600, cursor: 'pointer',
+  };
+  const primaryBtn = {
+    background: c.accent, color: '#fff',
+    border: 'none', padding: '10px 22px',
+    borderRadius: 10, fontSize: 14, fontWeight: 600, cursor: 'pointer',
+    boxShadow: `0 4px 14px -4px ${c.accentShadow}`,
+  };
+
+  const PrevButton = ({ currentStep, setCurrentStep }) => {
+    if (currentStep === 0) return <span />;
+    return (
+      <button style={ghostBtn} onClick={() => setCurrentStep(currentStep - 1)}>Back</button>
+    );
+  };
+
+  const NextButton = ({ currentStep, stepsLength, setCurrentStep, setIsOpen }) => {
+    const isFirst = currentStep === 0;
+    const isLast = currentStep === stepsLength - 1;
+    const label = isFirst ? 'Begin tour' : isLast ? 'Get started' : 'Next';
+    const padded = isFirst ? { ...primaryBtn, padding: '12px 28px', fontSize: 15 } : primaryBtn;
+    return (
+      <button
+        style={padded}
+        onClick={() => (isLast ? setIsOpen(false) : setCurrentStep(currentStep + 1))}
+      >
+        {label}
+      </button>
+    );
+  };
+
+  const SkipButton = ({ onClick }) => (
+    <button
+      onClick={onClick}
+      style={{
+        position: 'absolute', top: 14, right: 16,
+        background: 'transparent', border: 'none',
+        color: c.textDim, fontSize: 13, fontWeight: 500,
+        cursor: 'pointer', padding: '4px 8px', borderRadius: 6,
+      }}
+    >
+      Skip tour
+    </button>
+  );
+
+  return { PrevButton, NextButton, SkipButton };
+};
+
+// Auto-opens the tour, writes flag on close.
+const TourLauncher = () => {
+  const { setIsOpen, isOpen } = useTour();
+
+  useEffect(() => {
+    const seen = localStorage.getItem(STORAGE_KEY) === 'true';
+    if (TESTING_ONBOARDING || !seen) {
+      const t = setTimeout(() => setIsOpen(true), 400);
+      return () => clearTimeout(t);
+    }
+  }, [setIsOpen]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      if (sessionStorage.getItem('__tourStarted__')) {
+        localStorage.setItem(STORAGE_KEY, 'true');
+      }
+    } else {
+      sessionStorage.setItem('__tourStarted__', '1');
+    }
+  }, [isOpen]);
+
+  return null;
+};
+
+const OnboardingTour = ({ children }) => {
+  const { isDark } = useTheme();
+  const { config, advisors, resolveIcon } = useAppConfig();
+  const c = useMemo(() => palette(isDark), [isDark]);
+
+  const stepData = useMemo(() => ({
+    title: config?.app?.title || 'PhD Advisory Panel',
+    subtitle: config?.app?.subtitle || 'AI-Powered Guidance',
+    features: buildFeatures(config, resolveIcon),
+    advisorBody: buildAdvisorBody(advisors),
+    canvas: {
+      title: config?.onboarding?.tour_title || DEFAULT_CANVAS_STEP.title,
+      body: config?.onboarding?.tour_body || DEFAULT_CANVAS_STEP.body,
+    },
+  }), [config, advisors, resolveIcon]);
+
+  const steps = useMemo(() => buildSteps(c, stepData), [c, stepData]);
+  const { PrevButton, NextButton, SkipButton } = useMemo(() => makeButtons(c), [c]);
+
+  return (
+    <TourProvider
+      steps={steps}
+      showBadge={false}
+      disableInteraction
+      prevButton={PrevButton}
+      nextButton={NextButton}
+      components={{ Close: SkipButton }}
+      padding={{ mask: 8, popover: [16, 12] }}
+      styles={{
+        popover: (base) => ({
+          ...base,
+          borderRadius: 18,
+          padding: '28px 26px 22px',
+          maxWidth: 440,
+          minWidth: 360,
+          background: c.bg,
+          backgroundColor: c.bg,
+          color: c.text,
+          boxShadow: '0 30px 80px -10px rgba(0,0,0,0.5)',
+          border: `1px solid ${c.border}`,
+        }),
+        maskWrapper: (base) => ({ ...base, color: 'rgba(0, 0, 0, 0.82)' }),
+        maskArea: (base) => ({ ...base, rx: 14 }),
+        controls: (base) => ({
+          ...base,
+          marginTop: 22,
+          paddingTop: 18,
+          borderTop: `1px solid ${c.border}`,
+          alignItems: 'center',
+          justifyContent: 'space-between',
+        }),
+        dot: (base, { current }) => ({
+          ...base,
+          width: current ? 24 : 8,
+          height: 8,
+          borderRadius: 999,
+          background: current ? c.accent : c.border,
+          transition: 'all 0.25s ease',
+        }),
+        navigation: (base) => ({ ...base, gap: 7 }),
+      }}
+    >
+      <TourLauncher />
+      {children}
+    </TourProvider>
+  );
+};
+
+export default OnboardingTour;

phd-advisor-frontend/src/pages/ChatPage.js

@@ -16,6 +16,7 @@ import '../styles/ChatPage.css';
 import '../styles/EnhancedChatInput.css';
 import AdvisorStatusDropdown from '../components/AdvisorStatusDropdown';
 import AdvisorCarousel from '../components/AdvisorCarousel';
+import OnboardingTour from '../components/OnboardingTour';
 
 const ChatPage = ({ user, authToken, onNavigateToHome, onNavigateToCanvas, onSignOut, onUserUpdate }) => {
   const { config, advisors, getAdvisorColors } = useAppConfig();
@@ -752,6 +753,7 @@ const handleNewChat = async (sessionId = null) => {
   const chatPlaceholder = config?.chat_page?.placeholder || "Ask your advisors anything...";
 
   return (
+    <OnboardingTour>
     <div className="chat-page-with-sidebar">
       {/* Sidebar Component */}
       <Sidebar
@@ -998,6 +1000,7 @@ const handleNewChat = async (sessionId = null) => {
         </div>
       </div>
     </div>
+    </OnboardingTour>
   );
 };
 

phd-advisor-frontend/src/styles/OnboardingTour.css

@@ -0,0 +1,12 @@
+/* Force popover to match app theme via CSS vars set on :root[data-theme] */
+[data-tour-elem="popover"] {
+  background: var(--bg-primary) !important;
+  background-color: var(--bg-primary) !important;
+  color: var(--text-primary) !important;
+  border: 1px solid var(--border-primary) !important;
+}
+
+/* All text inside should respect theme */
+[data-tour-elem="popover"] * {
+  -webkit-text-fill-color: inherit;
+}

phd_config.yaml

@@ -84,6 +84,19 @@ chat_page:
         - "Should I speak up about unclear expectations or just try to figure it out quietly?"
         - "What are the unspoken expectations no one tells you about?"
 
+onboarding:
+  features:
+    - title: "Get advice from specialized AI advisors"
+      icon: "GraduationCap"
+    - title: "Save and revisit every conversation"
+      icon: "MessageCircle"
+    - title: "Upload PDFs for context-aware answers"
+      icon: "Paperclip"
+    - title: "Track your PhD progress on a structured canvas"
+      icon: "BarChart3"
+  tour_title: "PhD Progress Canvas"
+  tour_body: "A dashboard view of your PhD journey — research progress, methodology, next steps, all in one place."
+
 # ── Personas ───────────────────────────────────────────────────────────────
 
 personas:

undergrad_config.yaml

@@ -86,6 +86,21 @@ chat_page:
         - "How do I balance self-care with a heavy course load?"
         - "What campus resources exist for mental health, tutoring, or financial aid?"
 
+onboarding:
+  features:
+    - title: "Get advice from specialized AI advisors"
+      icon: "GraduationCap"
+    - title: "Save and revisit every conversation"
+      icon: "MessageCircle"
+    - title: "Upload course syllabi and documents for context-aware answers"
+      icon: "Paperclip"
+    - title: "Track your progress on a structured canvas"
+      icon: "BarChart3"
+
+canvas:
+  tour_title: "Academic Progress Canvas"
+  tour_body: "A dashboard view of your college journey -- courses, milestones, next steps, all in one place."
+
 # -- Personas ----------------------------------------------------------------
 
 personas: