Add User Guide (#53)

* Draft 1- Enhance UI with User Guide and Sidebar Improvements

- Added UserGuide component to App for global help access.
- Updated Sidebar component to replace icons and improve button styles.
- Introduced new chat button with updated design and functionality.
- Enhanced ChatPage with a help button to open the user guide.
- Improved CSS styles for better layout and user experience.

* Enhance User Guide with Advisor Information

- Updated UserGuide component to include advisor data from app configuration.
- Modified user guide content to dynamically display the number of advisors and their descriptions.
- Replaced static advisor list with a generated list based on available advisors.

* Fixed Help Circle error

phd-advisor-frontend/src/App.js

@@ -5,6 +5,7 @@ import HomePage from './pages/HomePage';
 import ChatPage from './pages/ChatPage';
 import AuthPage from './pages/AuthPage';
 import CanvasPage from './pages/CanvasPage';
+import UserGuide from './components/UserGuide';
 import './styles/components.css';
 
 function App() {
@@ -97,6 +98,8 @@ function App() {
               onSignOut={handleSignOut}
             />
           )}
+          {/* Global help center — listens for the 'open-user-guide' event */}
+          <UserGuide />
         </div>
       </ThemeProvider>
     </AppConfigProvider>

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

@@ -0,0 +1,110 @@
+import React, { useState, useEffect } from 'react';
+import ReactDOM from 'react-dom';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import * as LucideIcons from 'lucide-react';
+import { X, Search, ChevronRight, BookOpen } from 'lucide-react';
+import { useAppConfig } from '../contexts/AppConfigContext';
+import { userGuideTopics } from '../data/userGuide';
+import '../styles/UserGuide.css';
+
+const UserGuide = () => {
+  const { config, advisors } = useAppConfig();
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeId, setActiveId] = useState(userGuideTopics[0].id);
+  const [search, setSearch] = useState('');
+
+  useEffect(() => {
+    const open = () => setIsOpen(true);
+    window.addEventListener('open-user-guide', open);
+    return () => window.removeEventListener('open-user-guide', open);
+  }, []);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e) => e.key === 'Escape' && setIsOpen(false);
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [isOpen]);
+
+  const appName = config?.app?.title || 'the app';
+  const advisorEntries = Object.values(advisors || {});
+  const advisorCount = advisorEntries.length;
+  const advisorList = advisorEntries
+    .map((a) => `- **${a.name}:** ${a.description || a.role || ''}`.trimEnd())
+    .join('\n');
+  const q = search.toLowerCase().trim();
+  const filteredTopics = q
+    ? userGuideTopics.filter(t =>
+        t.title.toLowerCase().includes(q) || t.content.toLowerCase().includes(q))
+    : userGuideTopics;
+  const activeTopic = userGuideTopics.find(t => t.id === activeId) || userGuideTopics[0];
+
+  if (!isOpen) return null;
+
+  return ReactDOM.createPortal(
+    <div className="ug-overlay" onClick={(e) => e.target === e.currentTarget && setIsOpen(false)}>
+      <div className="ug-modal" role="dialog" aria-label="User Guide">
+        {/* Header */}
+        <div className="ug-header">
+          <div className="ug-title">
+            <span className="ug-title-icon">
+              <BookOpen size={18} />
+            </span>
+            <span>User Guide</span>
+          </div>
+          <button className="ug-close" onClick={() => setIsOpen(false)} aria-label="Close">
+            <X size={20} />
+          </button>
+        </div>
+
+        <div className="ug-body">
+          {/* Sidebar / TOC */}
+          <aside className="ug-sidebar">
+            <div className="ug-search">
+              <Search size={14} />
+              <input
+                type="text"
+                placeholder="Search the guide…"
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+              />
+            </div>
+            <nav className="ug-toc">
+              {filteredTopics.length === 0 && (
+                <div className="ug-empty">No matches</div>
+              )}
+              {filteredTopics.map((t) => {
+                const TopicIcon = LucideIcons[t.icon] || BookOpen;
+                return (
+                  <button
+                    key={t.id}
+                    className={`ug-toc-item ${t.id === activeId ? 'active' : ''}`}
+                    onClick={() => setActiveId(t.id)}
+                  >
+                    <TopicIcon size={16} />
+                    <span>{t.title}</span>
+                    <ChevronRight size={14} className="ug-toc-arrow" />
+                  </button>
+                );
+              })}
+            </nav>
+          </aside>
+
+          {/* Content */}
+          <main className="ug-content" key={activeTopic.id}>
+            <ReactMarkdown remarkPlugins={[remarkGfm]}>
+              {activeTopic.content
+                .replace(/\{\{appName\}\}/g, appName)
+                .replace(/\{\{advisorCount\}\}/g, String(advisorCount))
+                .replace(/\{\{advisorList\}\}/g, advisorList)}
+            </ReactMarkdown>
+          </main>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+};
+
+export default UserGuide;

phd-advisor-frontend/src/data/userGuide.js

@@ -0,0 +1,143 @@
+// User Guide content. Content can be overridden per-application by replacing
+// these strings with values pulled from the backend config in the future.
+// Use {{appName}} as a placeholder. It gets replaced at render time.
+
+export const userGuideTopics = [
+  {
+    id: 'getting-started',
+    title: 'Getting Started',
+    icon: 'Sparkles',
+    content: `# Welcome to {{appName}}
+
+{{appName}} is your AI-powered academic guidance system. A panel of specialized AI advisors gives you diverse perspectives on your research, writing, methodology, and more.
+
+## Your first steps
+1. **Start a new chat** using the pencil icon next to the search bar
+2. **Type a question.** Anything about your research, methodology, or PhD journey
+3. **Read multiple advisor responses.** Each persona brings a different lens
+4. **Reply to a specific advisor** to dig deeper into their perspective
+
+## Need help?
+You can return to this guide anytime by clicking the **?** icon in the header.`,
+  },
+  {
+    id: 'advisors',
+    title: 'Your Advisors',
+    icon: 'GraduationCap',
+    content: `# Your Advisors
+
+{{appName}} comes with {{advisorCount}} specialized advisor personas. Each one is tuned with a different perspective and area of expertise.
+
+## Available advisors
+{{advisorList}}
+
+## Seeing who's available
+Click the **"X Advisors"** dropdown in the top right of the chat to see all of your advisors and their current status.`,
+  },
+  {
+    id: 'conversations',
+    title: 'Conversations & Replies',
+    icon: 'MessageCircle',
+    content: `# Conversations & Replies
+
+## Asking a question
+Type into the chat box at the bottom. All advisors will respond with their unique perspective.
+
+## Replying to a specific advisor
+Click on any advisor's response to **reply directly to them**. This continues the conversation with just that persona, letting you go deeper on their specific angle.
+
+## Expanding a response
+Some responses include an **"Expand"** action to ask the advisor to elaborate further with more detail.
+
+## Tips
+- Be specific. The more context, the better the advice
+- Ask follow-up questions to refine the response
+- Different advisors will sometimes disagree, and that's a feature, not a bug`,
+  },
+  {
+    id: 'documents',
+    title: 'Uploading Documents',
+    icon: 'Paperclip',
+    content: `# Uploading Documents
+
+You can attach **PDFs, Word documents, and text files** to give your advisors context.
+
+## How it works
+1. Click the paperclip icon in the chat input
+2. Select your file
+3. Wait for it to process
+4. Ask a question, and your advisors will reference the document
+
+## What can it handle?
+- Research papers (PDF)
+- Drafts and chapters (DOCX, TXT)
+- Notes and outlines
+
+## Behind the scenes
+Documents are processed using **RAG (retrieval-augmented generation)**. The system finds the most relevant chunks of your document for each question, so even long documents work well.`,
+  },
+  {
+    id: 'sessions',
+    title: 'Sessions & History',
+    icon: 'MessagesSquare',
+    content: `# Sessions & History
+
+Every conversation is automatically saved as a session.
+
+## Finding past chats
+Use the **search bar** in the sidebar to filter your past sessions by title.
+
+## Switching between sessions
+Click any session in the sidebar to return to it. Your full context is preserved.
+
+## Starting a new chat
+Click the pencil/edit icon next to the search bar to start a fresh conversation.
+
+## Renaming or deleting
+Hover any session to reveal the **menu**. From there you can rename or delete.`,
+  },
+  {
+    id: 'canvas',
+    title: 'Progress Canvas',
+    icon: 'BarChart3',
+    content: `# {{appName}} Canvas
+
+The Canvas is a **structured dashboard view** of your PhD journey. It pulls insights from your conversations and organizes them into 10 sections:
+
+- Research Progress
+- Methodology
+- Theoretical Framework
+- Challenges & Obstacles
+- Next Steps
+- Writing & Communication
+- Career Development
+- Literature Review
+- Data Analysis
+- Motivation & Mindset
+
+## Accessing the Canvas
+Click the **{{appName}} Canvas** button in the sidebar.
+
+## Exporting
+You can print or download the Canvas as a snapshot of your progress.`,
+  },
+  {
+    id: 'tips',
+    title: 'Tips & Shortcuts',
+    icon: 'Sparkles',
+    content: `# Tips & Shortcuts
+
+## Get better answers
+- **Provide context.** Mention your field, your stage, your specific concern.
+- **Quote your work.** Paste a paragraph from your draft for targeted feedback.
+- **Use multiple advisors.** Ask one for theory, another for practical next steps.
+
+## Useful workflows
+- **Stuck on methodology?** Ask the Methodologist + Theorist together.
+- **Feeling burnt out?** The Motivational Coach + Empathetic Listener help reframe.
+- **Need to be challenged?** Talk to the Constructive Critic and Socratic Mentor.
+
+## Theme
+Switch between light and dark mode using the toggle in the top right.`,
+  },
+];

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

@@ -1,5 +1,7 @@
 import React, { useState, useEffect, useRef, useMemo } from 'react';
-import { Home, MessageCircle, Reply, X, Sparkles, Users, Settings2, FileText, Menu } from 'lucide-react';
+
+import { Home, MessageCircle, Reply, X, Sparkles, Users, Settings2, FileText, Menu, HelpCircle } from 'lucide-react';
+
 import EnhancedChatInput from '../components/EnhancedChatInput';
 import MessageBubble from '../components/MessageBubble';
 import ThinkingIndicator from '../components/ThinkingIndicator';
@@ -824,6 +826,15 @@ const handleNewChat = async (sessionId = null) => {
 
                 {/* Theme Toggle */}
                 <ThemeToggle />
+
+                {/* Help / User Guide */}
+                <button
+                  className="header-help-btn"
+                  onClick={() => window.dispatchEvent(new CustomEvent('open-user-guide'))}
+                  title="Open user guide"
+                >
+                  <HelpCircle />
+                </button>
               </div>
             </div>
           </div>

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

@@ -730,6 +730,32 @@
   background: var(--bg-secondary-dark, #374151);
 }
 
+.header-help-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 10px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 12px;
+  cursor: pointer;
+  color: var(--text-secondary);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
+  transition: all 0.2s ease;
+}
+
+.header-help-btn svg {
+  width: 20px;
+  height: 20px;
+  display: block;
+}
+
+.header-help-btn:hover {
+  background: var(--bg-secondary);
+  border-color: #2663EB;
+  color: #2663EB;
+}
+
 /* Loading session indicator */
 .loading-session {
   display: flex;

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

@@ -0,0 +1,281 @@
+/* === User Guide modal ============================================== */
+.ug-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(4px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  animation: ug-fade 0.18s ease;
+}
+
+@keyframes ug-fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.ug-modal {
+  width: 92vw;
+  max-width: 1000px;
+  height: 80vh;
+  max-height: 720px;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 18px;
+  box-shadow: 0 30px 80px -10px rgba(0, 0, 0, 0.5);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  animation: ug-pop 0.22s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes ug-pop {
+  from { opacity: 0; transform: scale(0.96); }
+  to   { opacity: 1; transform: scale(1); }
+}
+
+/* Header bar */
+.ug-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 18px 22px;
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.ug-title {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 16px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+}
+
+.ug-title-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  background: #2663EB;
+  color: #fff;
+  flex-shrink: 0;
+}
+
+.ug-close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border: none;
+  background: transparent;
+  border-radius: 8px;
+  cursor: pointer;
+  color: var(--text-secondary);
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+.ug-close:hover {
+  background: var(--bg-secondary);
+  color: var(--text-primary);
+}
+
+/* Body layout: sidebar + content */
+.ug-body {
+  flex: 1;
+  display: grid;
+  grid-template-columns: 240px 1fr;
+  min-height: 0;
+}
+
+/* Sidebar */
+.ug-sidebar {
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid var(--border-primary);
+  background: var(--bg-secondary);
+  min-height: 0;
+}
+
+.ug-search {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 14px;
+  padding: 8px 12px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 10px;
+  color: var(--text-secondary);
+}
+
+.ug-search input {
+  flex: 1;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: var(--text-primary);
+  font-size: 13.5px;
+}
+
+.ug-search input::placeholder {
+  color: var(--text-tertiary);
+}
+
+.ug-toc {
+  flex: 1;
+  overflow-y: auto;
+  padding: 4px 10px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.ug-toc-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  border: none;
+  background: transparent;
+  border-radius: 8px;
+  cursor: pointer;
+  color: var(--text-secondary);
+  font-size: 13.5px;
+  font-weight: 500;
+  text-align: left;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+.ug-toc-item span {
+  flex: 1;
+}
+
+.ug-toc-arrow {
+  opacity: 0;
+  transition: opacity 0.15s ease, transform 0.15s ease;
+}
+
+.ug-toc-item:hover {
+  background: var(--bg-primary);
+  color: var(--text-primary);
+}
+
+.ug-toc-item:hover .ug-toc-arrow {
+  opacity: 0.6;
+}
+
+.ug-toc-item.active {
+  background: rgba(38, 99, 235, 0.1);
+  color: #2663EB;
+}
+
+.ug-toc-item.active .ug-toc-arrow {
+  opacity: 1;
+  transform: translateX(2px);
+}
+
+.ug-empty {
+  padding: 14px;
+  font-size: 13px;
+  color: var(--text-tertiary);
+  text-align: center;
+}
+
+/* Content area */
+.ug-content {
+  overflow-y: auto;
+  padding: 28px 36px 40px;
+  font-size: 15px;
+  line-height: 1.65;
+  color: var(--text-primary);
+  animation: ug-slide 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes ug-slide {
+  from { opacity: 0; transform: translateY(6px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.ug-content h1 {
+  margin: 0 0 16px;
+  font-size: 26px;
+  font-weight: 800;
+  letter-spacing: -0.02em;
+  color: var(--text-primary);
+}
+
+.ug-content h2 {
+  margin: 28px 0 10px;
+  font-size: 18px;
+  font-weight: 700;
+  color: var(--text-primary);
+  letter-spacing: -0.01em;
+}
+
+.ug-content h3 {
+  margin: 22px 0 6px;
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--text-primary);
+}
+
+.ug-content p {
+  margin: 0 0 14px;
+  color: var(--text-secondary);
+}
+
+.ug-content ul, .ug-content ol {
+  margin: 0 0 16px;
+  padding-left: 22px;
+  color: var(--text-secondary);
+}
+
+.ug-content li {
+  margin-bottom: 6px;
+}
+
+.ug-content strong {
+  color: var(--text-primary);
+  font-weight: 600;
+}
+
+.ug-content code {
+  padding: 1px 6px;
+  border-radius: 4px;
+  background: var(--bg-secondary);
+  font-size: 0.9em;
+  color: #2663EB;
+  font-family: 'SF Mono', ui-monospace, monospace;
+}
+
+.ug-content a {
+  color: #2663EB;
+  text-decoration: none;
+}
+
+.ug-content a:hover {
+  text-decoration: underline;
+}
+
+/* Mobile */
+@media (max-width: 720px) {
+  .ug-body {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto 1fr;
+  }
+  .ug-sidebar {
+    border-right: none;
+    border-bottom: 1px solid var(--border-primary);
+    max-height: 200px;
+  }
+  .ug-content {
+    padding: 22px 22px 36px;
+  }
+}