┌─────────────────────────────────────────────────────────────────────────────┐
│                           LEARNER JOURNEY                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  1. DISCOVER          2. EXPLORE           3. LEARN            4. ENGAGE    │
│  ───────────          ──────────           ────────            ─────────    │
│  Land on home    →    Browse courses   →   Read session   →   Comment &    │
│  page                 View details         Follow along       discuss       │
│                                            with repo                         │
│                                                                              │
│  ┌──────────┐        ┌──────────┐        ┌──────────┐        ┌──────────┐  │
│  │   Home   │   →    │ Catalog  │   →    │ Session  │   →    │ Comments │  │
│  │   Page   │        │   Page   │        │   Page   │        │ Section  │  │
│  └──────────┘        └──────────┘        └──────────┘        └──────────┘  │
│                            ↓                                                 │
│                      ┌──────────┐                                           │
│                      │  Course  │                                           │
│                      │  Detail  │                                           │
│                      └──────────┘                                           │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

1. User lands on Home page
2. User clicks "View Courses" or navigates to Catalog
3. User sees list of available courses with:
   - Course title
   - Description
   - Number of sessions
   - Estimated time
4. User clicks on a course
5. User sees Course Detail with:
   - Full description
   - Session list
   - Progress indicator (if signed in)
6. User clicks "Start Course" or selects a session

1. User is on Course Detail page
2. User clicks on a session
3. Session page loads with:
   - Session title and metadata
   - Sidebar navigation (all sessions)
   - Breadcrumbs (Home > Course > Session)
   - Session content (rendered markdown)
   - Comments section at bottom
4. User reads content, follows along with repo
5. User can navigate to next/previous session
6. User can comment or ask questions

┌─────────────────────────────────────────────────────────┐
│  Header (Logo, Nav, Sign In)                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│                      HERO SECTION                       │
│           "Learn to ship with AI"                       │
│     [Browse Courses]                                    │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│              FEATURED COURSES (3 cards)                 │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐             │
│   │ Course  │   │ Course  │   │ Course  │             │
│   │   1     │   │   2     │   │   3     │             │
│   └─────────┘   └─────────┘   └─────────┘             │
│                                                         │
│              [View All Courses →]                       │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  Footer                                                 │
└─────────────────────────────────────────────────────────┘

Scenario: Visitor understands Academy's value proposition
  Given I am a new visitor on the home page
  When the page loads
  Then I see a headline "Learn to ship with AI"
  And I see a tagline explaining the target audience
  And I see a primary CTA button

Scenario: Visitor navigates to course catalog
  Given I am on the home page
  When I click the "Browse Courses" button
  Then I am navigated to /courses

Scenario: Visitor clicks a featured course
  Given I am on the home page
  And there are featured courses displayed
  When I click on a course card
  Then I am navigated to /courses/[course-slug]

Scenario: Home page loads within performance budget
  Given I am accessing the home page
  When the page loads
  Then the Largest Contentful Paint is under 2 seconds
  And no layout shift occurs after initial render

┌─────────────────────────────────────────────────────────┐
│  Header                                                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Courses                                                │
│  ─────────────────────────────                          │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Course    │  │   Course    │  │   Course    │     │
│  │   Card 1    │  │   Card 2    │  │   Card 3    │     │
│  │             │  │             │  │             │     │
│  │ 12 sessions │  │ 8 sessions  │  │ 6 sessions  │     │
│  │ ~4 hours    │  │ ~3 hours    │  │ ~2 hours    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐                      │
│  │   Course    │  │   Course    │                      │
│  │   Card 4    │  │   Card 5    │                      │
│  └─────────────┘  └─────────────┘                      │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  Footer                                                 │
└─────────────────────────────────────────────────────────┘

Scenario: Visitor sees all published courses
  Given there are 5 courses with status "published"
  And there are 2 courses with status "draft"
  When I visit /courses
  Then I see exactly 5 course cards
  And I do not see any draft courses

Scenario: Visitor views course metadata
  Given there is a course with 12 sessions and 4 hours total time
  When I view the course card
  Then I see "12 sessions"
  And I see "~4 hours"

Scenario: Visitor clicks a course card
  Given I am on the catalog page
  When I click on a course card for "The Shipping AI Designer"
  Then I am navigated to /courses/shipping-ai-designer

Scenario: Grid responds to screen size
  Given I am on the catalog page
  When my viewport is 1200px wide
  Then courses display in 3 columns
  When my viewport is 800px wide
  Then courses display in 2 columns
  When my viewport is 400px wide
  Then courses display in 1 column

Scenario: Empty state when no courses
  Given there are no published courses
  When I visit /courses
  Then I see a message "No courses available yet"
  And I see a link to go back home

┌─────────────────────────────────────────────────────────┐
│  Header                                                 │
├─────────────────────────────────────────────────────────┤
│  Home > Courses > Course Name                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Course Title                                           │
│  ══════════════════════════════════════                 │
│                                                         │
│  Full course description goes here. Can be              │
│  multiple paragraphs with markdown formatting.          │
│                                                         │
│  12 sessions · ~4 hours total                           │
│                                                         │
│  [Start Course →]                                       │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  Sessions                                               │
│  ─────────                                              │
│                                                         │
│  1. Introduction to AI-Assisted Development    ~20 min │
│     Get started with the basics...                      │
│                                                         │
│  2. Setting Up Your Environment                ~30 min │
│     Install and configure the tools...                  │
│                                                         │
│  3. Your First Feature                         ~45 min │
│     Build something real...                             │
├─────────────────────────────────────────────────────────┤
│  Footer                                                 │
└─────────────────────────────────────────────────────────┘

Scenario: Visitor views course details
  Given there is a course with slug "shipping-ai-designer"
  When I visit /courses/shipping-ai-designer
  Then I see the course title
  And I see the full course description rendered from markdown
  And I see the total session count and duration

Scenario: Visitor sees session list
  Given the course has 12 sessions
  When I view the course detail page
  Then I see all 12 sessions listed in order
  And each session shows its title and estimated time

Scenario: Visitor starts the course
  Given I am on a course detail page
  And the first session has slug "introduction"
  When I click "Start Course"
  Then I am navigated to /courses/[slug]/introduction

Scenario: Visitor jumps to specific session
  Given I am on a course detail page
  When I click on "Session 5: Advanced Patterns"
  Then I am navigated to /courses/[slug]/advanced-patterns

Scenario: Breadcrumb navigation works
  Given I am on the course detail page for "The Shipping AI Designer"
  When I click "Courses" in the breadcrumbs
  Then I am navigated to /courses

Scenario: Invalid course slug returns 404
  Given there is no course with slug "nonexistent-course"
  When I visit /courses/nonexistent-course
  Then I see a 404 error page

┌─────────────────────────────────────────────────────────────────┐
│  Header                                                         │
├─────────────────────────────────────────────────────────────────┤
│  Home > Course > Session                                        │
├────────────────┬────────────────────────────────────────────────┤
│                │                                                │
│   SIDEBAR      │   Session Title                                │
│   ─────────    │   ════════════════════════════                 │
│                │   15 min read · Updated Jan 16                 │
│   1. Intro  ●  │                                                │
│   2. Setup     │   Content goes here. This is the main          │
│   3. First     │   learning content rendered from markdown.     │
│   4. [Current] │                                                │
│   5. Testing   │   ## Heading                                   │
│   6. Deploy    │                                                │
│   ...          │   Paragraph text with **bold** and *italic*.   │
│                │                                                │
│                │   ```javascript                                │
│                │   const example = "code";                      │
│                │   ```                                          │
│                │                                                │
│                │   ┌─────────────────────────────────┐          │
│                │   │ 💡 TIP: This is a callout box  │          │
│                │   └─────────────────────────────────┘          │
│                │                                                │
│                │   [← Previous]              [Next →]           │
│                │                                                │
│                ├────────────────────────────────────────────────┤
│                │                                                │
│                │   Comments (3)                                 │
│                │   ────────────                                 │
│                │                                                │
│                │   [Comment form - requires sign in]            │
│                │                                                │
│                │   ┌─────────────────────────────────┐          │
│                │   │ User1 · 2 hours ago             │          │
│                │   │ Great explanation!              │          │
│                │   └─────────────────────────────────┘          │
│                │                                                │
├────────────────┴────────────────────────────────────────────────┤
│  Footer                                                         │
└─────────────────────────────────────────────────────────────────┘

Scenario: Learner views session content
  Given I am on session "setting-up-environment" of course "shipping-ai-designer"
  When the page loads
  Then I see the session title "Setting Up Your Environment"
  And I see the reading time estimate
  And I see the session content rendered from MDX

Scenario: Code blocks render with highlighting
  Given the session contains a JavaScript code block
  When I view the session
  Then the code block has syntax highlighting
  And I see a "Copy" button on the code block
  When I click the "Copy" button
  Then the code is copied to my clipboard
  And the button shows "Copied!" temporarily

Scenario: Callout boxes render correctly
  Given the session contains a <Tip> component
  When I view the session
  Then I see a styled callout box with a lightbulb icon
  And the callout has a distinct background color (blue)

Scenario: Learner navigates to next session
  Given I am on session 3 of 12
  When I click "Next" at the bottom
  Then I am navigated to session 4
  And the sidebar updates to highlight session 4

Scenario: Learner on first session
  Given I am on session 1 of the course
  When I view the navigation
  Then I do not see a "Previous" button
  And I see a "Next" button

Scenario: Learner on last session
  Given I am on session 12 (last session)
  When I view the navigation
  Then I see a "Previous" button
  And I see a "Complete Course" button instead of "Next"

Scenario: Sidebar shows course progress
  Given I am on session 5 of a 12-session course
  When I view the sidebar
  Then I see all 12 sessions listed
  And session 5 is visually highlighted as current

Scenario: Mobile sidebar behavior
  Given I am viewing on a mobile device (< 768px)
  When the page loads
  Then the sidebar is hidden by default
  When I tap the menu toggle button
  Then the sidebar slides in as an overlay

Desktop (>768px):
┌─────────────────────────────────────────────────────────┐
│  🎓 Academy          Courses    [🔍 Search]   [Sign In] │
└─────────────────────────────────────────────────────────┘

Logged in:
┌─────────────────────────────────────────────────────────┐
│  🎓 Academy          Courses    [🔍 Search]     [👤▾]   │
└─────────────────────────────────────────────────────────┘

Mobile (<768px):
┌─────────────────────────────────────────────────────────┐
│  [☰]    🎓 Academy                         [Sign In]   │
└─────────────────────────────────────────────────────────┘

Home  >  Courses  >  The Shipping AI Designer  >  Session 3
[link]   [link]      [link]                       [current]

┌──────────────────────┐
│  Sessions            │
│  ─────────           │
│  ○ 1. Introduction   │
│  ○ 2. Setup          │
│  ● 3. First Feature  │  ← Current (highlighted)
│  ○ 4. Testing        │
│  ○ 5. Deployment     │
└──────────────────────┘

Scenario: Header displays on all pages
  Given I am on any page of the site
  When the page loads
  Then I see the header with logo, nav, and user area

Scenario: Logo navigates to home
  Given I am on the course catalog page
  When I click the Academy logo
  Then I am navigated to the home page (/)

Scenario: User menu shows sign in when logged out
  Given I am not signed in
  When I view the header
  Then I see a "Sign In" button
  And I do not see a user avatar

Scenario: User menu shows avatar when logged in
  Given I am signed in as "alex@example.com"
  When I view the header
  Then I see my avatar
  When I click my avatar
  Then I see a dropdown with "Profile" and "Sign Out"

Scenario: Breadcrumbs show correct path
  Given I am on session "first-feature" of course "shipping-ai-designer"
  When I view the breadcrumbs
  Then I see "Home > Courses > The Shipping AI Designer > First Feature"
  And "Home", "Courses", and course name are clickable links

Scenario: Sidebar highlights current session
  Given I am on session 3 of a 5-session course
  When I view the sidebar
  Then I see all 5 sessions listed
  And session 3 is visually highlighted (filled circle, bold text)

Scenario: Mobile hamburger menu
  Given I am on a mobile device (<768px)
  When I tap the hamburger icon (☰)
  Then a slide-out menu appears with navigation links
  When I tap "Courses"
  Then the menu closes and I navigate to /courses

1. User clicks "Sign Up"
2. User enters email and password (or clicks OAuth)
3. User verifies email (if required)
4. User is signed in and redirected

1. User clicks "Sign In"
2. User enters email/password or clicks OAuth
3. User is signed in and redirected to previous page

1. User clicks "Forgot Password"
2. User enters email
3. User receives reset link via email
4. User clicks link and sets new password
5. User is signed in

Scenario: User signs up with email
  Given I am on the sign-up page
  When I enter a valid email and password
  And I click "Sign Up"
  Then my account is created
  And I am redirected to the home page
  And I see my avatar in the header

Scenario: User signs in with GitHub
  Given I am on the sign-in page
  When I click "Continue with GitHub"
  And I authorize the application on GitHub
  Then I am signed in
  And I am redirected to my previous page

Scenario: User signs out
  Given I am signed in
  When I click my avatar in the header
  And I click "Sign Out"
  Then I am signed out
  And I see "Sign In" button in the header

Scenario: Password reset flow
  Given I am on the sign-in page
  When I click "Forgot Password"
  And I enter my registered email
  And I click "Send Reset Link"
  Then I see a confirmation message
  And I receive an email with a reset link

Scenario: Protected route redirects
  Given I am not signed in
  When I try to access /profile
  Then I am redirected to /sign-in
  And after signing in, I am redirected to /profile

Scenario: Session persists across visits
  Given I signed in yesterday
  When I return to the site today
  Then I am still signed in
  And I see my avatar in the header

┌─────────────────────────────────────────────────────────┐
│  Comments (5)                                           │
│  ───────────                                            │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Write a comment...                              │   │
│  │                                                  │   │
│  │                                    [Post]        │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 👤 Alex · 2 hours ago                           │   │
│  │                                                  │   │
│  │ Great explanation! How does this work with TS?  │   │
│  │                                                  │   │
│  │ [Reply]                                          │   │
│  │                                                  │   │
│  │   ┌─────────────────────────────────────────┐   │   │
│  │   │ 👤 Sam · 1 hour ago                     │   │   │
│  │   │ Good question! You would need to...     │   │   │
│  │   └─────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

interface Comment {
  id: string;
  content: string;        // Markdown
  user_id: string;        // → User (Supabase Auth)
  sessionId: string;      // → Session
  parentId: string | null; // → Comment (for replies)
  createdAt: Date;
}

Scenario: Signed-in user posts a comment
  Given I am signed in
  And I am on a session page
  When I type "Great explanation!" in the comment form
  And I click "Post"
  Then my comment appears at the top of the list
  And I see my avatar and name
  And I see "just now" as the timestamp

Scenario: Visitor sees sign-in prompt
  Given I am not signed in
  And I am on a session page
  When I view the comments section
  Then I see existing comments
  And I see "Sign in to comment" instead of the form
  When I click "Sign in to comment"
  Then I am redirected to /sign-in

Scenario: User replies to a comment
  Given I am signed in
  And there is an existing comment
  When I click "Reply" on that comment
  And I type my reply
  And I click "Post"
  Then my reply appears nested under the original comment
  And my reply is visually indented

Scenario: Comment renders markdown
  Given I post a comment with "Use `const` instead of **let**"
  When the comment is displayed
  Then "const" appears in code formatting
  And "let" appears in bold formatting

Scenario: Comments load on session page
  Given a session has 5 comments
  When I visit that session page
  Then I see "Comments (5)" as the section header
  And I see all 5 comments in reverse chronological order

┌─────────────────────────────────────────────────────────┐
│  Header with [🔍 Search input]                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Search results for "claude code"                       │
│  ─────────────────────────────────                      │
│  12 results                                             │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 📘 The Shipping AI Designer            [Course] │   │
│  │ Learn to ship features using **Claude Code**... │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 📄 Session 3: Your First Feature      [Session] │   │
│  │ The Shipping AI Designer                         │   │
│  │ ...use **Claude Code** to implement the...      │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 📄 Session 5: Advanced Patterns       [Session] │   │
│  │ The Shipping AI Designer                         │   │
│  │ ...advanced **Claude Code** workflows...        │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Scenario: User searches from header
  Given I am on any page
  When I type "claude code" in the search input
  And I press Enter
  Then I am navigated to /search?q=claude%20code
  And I see results matching "claude code"

Scenario: Search results display correctly
  Given there are courses and sessions containing "typescript"
  When I search for "typescript"
  Then I see matching courses with a "Course" badge
  And I see matching sessions with a "Session" badge
  And each result shows a highlighted snippet

Scenario: User clicks a search result
  Given I have search results displayed
  When I click on a session result
  Then I am navigated to that session page

Scenario: No results found
  Given there is no content matching "xyznonexistent"
  When I search for "xyznonexistent"
  Then I see "No results found for 'xyznonexistent'"
  And I see suggestions like "Try different keywords"

Scenario: Search is performant
  Given the search index contains 100 sessions
  When I search for "react"
  Then results appear in under 500ms

Scenario: Empty search query
  Given I am on the search page
  When I submit an empty search query
  Then I see a prompt to enter a search term
  And no results are displayed

-- Add search vector column
ALTER TABLE sessions ADD COLUMN search_vector tsvector;

-- Create index
CREATE INDEX sessions_search_idx ON sessions USING GIN(search_vector);

-- Search query
SELECT * FROM sessions 
WHERE search_vector @@ plainto_tsquery('english', $1)
ORDER BY ts_rank(search_vector, plainto_tsquery('english', $1)) DESC;

Academy
├── Home (/)
├── Courses (/courses)
│   └── [Course] (/courses/[slug])
│       └── [Session] (/courses/[slug]/[session])
├── Search (/search)
├── Sign In (/sign-in)
├── Sign Up (/sign-up)
└── Profile (/profile)

Course (1) ──────< Session (N)
                       │
                       └────< Comment (N) >──── User (1)
                                  │
                                  └── parent_id (self-reference, 1 level)

┌─────────────────────┐
│ ☰  Academy  [Sign]  │  ← Compact header (56px)
├─────────────────────┤
│ Home > Course > ... │  ← Breadcrumbs (truncated)
├─────────────────────┤
│                     │
│   Session Title     │
│   ═══════════════   │
│                     │
│   Content flows     │
│   full width with   │
│   16px padding.     │
│                     │
│   ┌───────────────┐ │
│   │ code block    │→│  ← Horizontal scroll
│   └───────────────┘ │
│                     │
│ [← Prev]   [Next →] │
│                     │
├─────────────────────┤
│ [≡ Show Sessions]   │  ← Toggle sidebar
├─────────────────────┤
│   Comments...       │
└─────────────────────┘

Scenario: Mobile layout renders correctly
  Given I am viewing on a 375px wide screen
  When I visit any page
  Then content fits within the viewport
  And there is no horizontal scrollbar
  And text is readable without zooming

Scenario: Course grid adapts to screen size
  Given there are 6 courses in the catalog
  When I view on mobile (<768px)
  Then courses display in 1 column
  When I view on tablet (768-1024px)
  Then courses display in 2 columns
  When I view on desktop (>1024px)
  Then courses display in 3 columns

Scenario: Touch targets are accessible
  Given I am on a touch device
  When I try to tap any interactive element
  Then the tap target is at least 44×44 pixels