feat: improve interactive tutorial with progress tracking, tips, and keyboard nav (#576)

## Summary

Enhances the existing interactive tutorial (from PR #178) with better
UX, progress tracking, and visual polish.

## Changes

### Tutorial Overlay
- **Step progress dots** — visual dots showing current position within a
chapter (active/done/upcoming)
- **Overall progress bar** — thin bar at the bottom tracking global step
position
- **Keyboard navigation** — Arrow keys (left/right) to navigate, Escape
to close
- **Slide animations** — left/right transition between steps
- **Tip callouts** — contextual hints with lightbulb icon and
accent-colored left border
- **Better visual hierarchy** — chapter name in accent color, chapter
counter, SVG close button

### Tutorial Page
- **Overall progress section** — gradient progress bar with chapter
completion count
- **Numbered chapter cards** — chapter numbers in circular badges
- **Smart "Continue Tour" button** — resumes from first incomplete
chapter instead of restarting
- **"Replay Full Tour"** — shown when all chapters are completed
- **Keyboard shortcut hint** — footer note about arrow keys and Escape
- **Responsive layout** — single-column grid on mobile (\<640px)

### First-Launch Experience
- **Tutorial nudge banner** — shows on empty dashboard for new users
- **Dismissible** — persisted via `HasSeenTutorialPrompt` in UiState

### Model / Service
- **`TutorialStep.Tip`** — optional contextual hint property
- **`TutorialService` progress properties** — `TotalChapters`,
`TotalSteps`, `GlobalStepIndex`, `OverallProgressPercent`,
`CompletedChapterCount`
- **`UiState.HasSeenTutorialPrompt`** — persists nudge dismissal

### Tests
- 7 new tests: `TotalChapters`, `TotalSteps`, `GlobalStepIndex`,
`OverallProgressPercent` (zero/partial/full), `CompletedChapterCount`,
`TipsAreNotEmpty`
- All 3331 tests pass (0 failures)

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Shane Neuville <shneuvil@microsoft.com>

Author: 3 people

PolyPilot.Tests/TutorialServiceTests.cs

@@ -164,6 +164,87 @@ public void OnStateChanged_FiresOnStartAndNext()
 
         Assert.Equal(3, count);
     }
+
+    [Fact]
+    public void TotalChapters_ReturnsExpectedCount()
+    {
+        var svc = new TutorialService();
+        Assert.Equal(TutorialContent.Chapters.Count, svc.TotalChapters);
+    }
+
+    [Fact]
+    public void TotalSteps_ReturnsAllStepsAcrossChapters()
+    {
+        var svc = new TutorialService();
+        var expected = TutorialContent.Chapters.Sum(c => c.Steps.Count);
+        Assert.Equal(expected, svc.TotalSteps);
+    }
+
+    [Fact]
+    public void GlobalStepIndex_TracksPositionAcrossChapters()
+    {
+        var svc = new TutorialService();
+        svc.StartTutorial();
+        Assert.Equal(0, svc.GlobalStepIndex);
+
+        // Advance through first chapter
+        var stepsInFirst = svc.CurrentChapter!.Steps.Count;
+        for (int i = 0; i < stepsInFirst; i++)
+            svc.NextStep();
+
+        // Should now be at the first step of the second chapter
+        Assert.Equal(stepsInFirst, svc.GlobalStepIndex);
+    }
+
+    [Fact]
+    public void OverallProgressPercent_ZeroWhenNoneCompleted()
+    {
+        var svc = new TutorialService();
+        Assert.Equal(0, svc.OverallProgressPercent);
+    }
+
+    [Fact]
+    public void OverallProgressPercent_IncreasesOnChapterCompletion()
+    {
+        var svc = new TutorialService();
+        svc.StartTutorial();
+
+        // Complete first chapter
+        var stepsInFirst = svc.CurrentChapter!.Steps.Count;
+        for (int i = 0; i < stepsInFirst; i++)
+            svc.NextStep();
+
+        Assert.True(svc.OverallProgressPercent > 0);
+        Assert.True(svc.OverallProgressPercent <= 100);
+    }
+
+    [Fact]
+    public void OverallProgressPercent_100WhenAllCompleted()
+    {
+        var svc = new TutorialService();
+        svc.StartTutorial();
+
+        // Complete all chapters
+        int totalSteps = TutorialContent.Chapters.Sum(c => c.Steps.Count);
+        for (int i = 0; i < totalSteps; i++)
+            svc.NextStep();
+
+        Assert.Equal(100, svc.OverallProgressPercent);
+    }
+
+    [Fact]
+    public void CompletedChapterCount_TracksCompletions()
+    {
+        var svc = new TutorialService();
+        Assert.Equal(0, svc.CompletedChapterCount);
+
+        svc.StartTutorial();
+        var stepsInFirst = svc.CurrentChapter!.Steps.Count;
+        for (int i = 0; i < stepsInFirst; i++)
+            svc.NextStep();
+
+        Assert.Equal(1, svc.CompletedChapterCount);
+    }
 }
 
 public class TutorialContentTests
@@ -225,4 +306,17 @@ public void Content_HasExpectedChapterCount()
     {
         Assert.Equal(8, TutorialContent.Chapters.Count);
     }
+
+    [Fact]
+    public void TipsAreNotEmpty_WhenPresent()
+    {
+        foreach (var chapter in TutorialContent.Chapters)
+        {
+            foreach (var step in chapter.Steps.Where(s => s.Tip != null))
+            {
+                Assert.False(string.IsNullOrWhiteSpace(step.Tip),
+                    $"Step {step.Id} in {chapter.Id} has a non-null but empty Tip");
+            }
+        }
+    }
 }

PolyPilot/Components/Pages/Dashboard.razor

@@ -11,6 +11,7 @@
 @inject GitAutoUpdateService GitAutoUpdate
 @inject QrScannerService QrScanner
 @inject FiestaService FiestaService
+@inject TutorialService TutorialService
 @implements IAsyncDisposable
 
 <div class="dashboard @(expandedSession != null ? "expanded-mode" : "")" style="--card-min-height: @(_cardMinHeight)px">
@@ -19,6 +20,16 @@
         <div class="no-sessions-dash">
             <img src="PolyPilot_logo_lg.png" alt="PolyPilot" class="empty-logo" />
             <p class="welcome-title">Welcome to PolyPilot</p>
+            @if (!_hasSeenTutorialPrompt && PlatformHelper.IsDesktop)
+            {
+                <div class="tutorial-nudge">
+                    <span class="tutorial-nudge-text">New here? Take a quick tour to learn the basics.</span>
+                    <button class="tutorial-nudge-btn" @onclick="StartTutorialFromDashboard">Start Tutorial</button>
+                    <button class="tutorial-nudge-dismiss" @onclick="DismissTutorialNudge" title="Dismiss">
+                        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+                    </button>
+                </div>
+            }
             @if (CopilotService.IsRestoring)
             {
                 <div class="restoring-indicator">
@@ -587,6 +598,7 @@
     private DotNetObjectReference<Dashboard>? _dotNetRef;
     private string? initError;
     private bool _initializationComplete = false;
+    private bool _hasSeenTutorialPrompt = false;
     private readonly Dictionary<string, ChatMessage> _fiestaStreamingMessages = new(StringComparer.Ordinal);
     private Dictionary<string, (OrchestratorPhase Phase, string? Detail)> _groupPhases = new();
 
@@ -669,6 +681,9 @@
                 // Restore card min height (default 250, range 150-600)
                 _cardMinHeight = uiState.CardMinHeight is >= 150 and <= 600 ? uiState.CardMinHeight : 250;
 
+                // Restore tutorial prompt visibility
+                _hasSeenTutorialPrompt = uiState.HasSeenTutorialPrompt;
+                
                 // Restore expanded session state
                 if (!string.IsNullOrEmpty(uiState.ExpandedSession))
                 {
@@ -818,6 +833,20 @@
         StateHasChanged();
     }
 
+    private void StartTutorialFromDashboard()
+    {
+        _hasSeenTutorialPrompt = true;
+        CopilotService.SaveUiState("/", hasSeenTutorialPrompt: true);
+        TutorialService.StartTutorial();
+    }
+
+    private void DismissTutorialNudge()
+    {
+        _hasSeenTutorialPrompt = true;
+        CopilotService.SaveUiState("/", hasSeenTutorialPrompt: true);
+        StateHasChanged();
+    }
+
     private bool _isRestartingServer;
 
     private async Task RestartServer()

PolyPilot/Components/Pages/Dashboard.razor.css

@@ -236,6 +236,64 @@
     letter-spacing: 0.02em;
 }
 
+.tutorial-nudge {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 14px;
+    background: rgba(var(--accent-rgb), 0.08);
+    border: 1px solid rgba(var(--accent-rgb), 0.2);
+    border-radius: 8px;
+    margin-top: 12px;
+    animation: tutorialNudgeFadeIn 0.4s ease;
+}
+
+@keyframes tutorialNudgeFadeIn {
+    from { opacity: 0; transform: translateY(6px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.tutorial-nudge-text {
+    font-size: var(--type-callout);
+    color: var(--text-secondary);
+    flex: 1;
+}
+
+.tutorial-nudge-btn {
+    padding: 5px 14px;
+    border-radius: 6px;
+    font-size: var(--type-callout);
+    font-weight: 500;
+    cursor: pointer;
+    border: none;
+    background: var(--accent-primary);
+    color: #fff;
+    white-space: nowrap;
+    transition: filter 0.15s;
+}
+
+.tutorial-nudge-btn:hover {
+    filter: brightness(1.15);
+}
+
+.tutorial-nudge-dismiss {
+    background: none;
+    border: none;
+    color: var(--text-muted);
+    cursor: pointer;
+    padding: 4px;
+    border-radius: 4px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    line-height: 1;
+}
+
+.tutorial-nudge-dismiss:hover {
+    color: var(--text-primary);
+    background: var(--bg-tertiary);
+}
+
 .empty-logo {
     width: 120px;
     height: auto;

PolyPilot/Components/Pages/TutorialPage.razor

@@ -6,11 +6,36 @@
     <div class="tutorial-page-header">
         <h1>Tutorial</h1>
         <p class="tutorial-page-subtitle">Learn how to use PolyPilot with guided walkthroughs.</p>
+
+        @if (Tutorial.CompletedChapterCount > 0)
+        {
+            <div class="tutorial-overall-progress">
+                <div class="progress-label">
+                    <span>Overall progress</span>
+                    <span class="progress-value">@Tutorial.CompletedChapterCount / @Tutorial.TotalChapters chapters</span>
+                </div>
+                <div class="progress-track">
+                    <div class="progress-fill" style="width: @Tutorial.OverallProgressPercent%"></div>
+                </div>
+            </div>
+        }
+
         <div class="tutorial-page-actions">
             <button class="tutorial-btn tutorial-btn-primary tutorial-start-all" @onclick="StartFullTour">
-                Start Full Tour
+                @if (Tutorial.CompletedChapterCount == Tutorial.TotalChapters)
+                {
+                    <text>Replay Full Tour</text>
+                }
+                else if (Tutorial.CompletedChapterCount > 0)
+                {
+                    <text>Continue Tour</text>
+                }
+                else
+                {
+                    <text>Start Full Tour</text>
+                }
             </button>
-            @if (Tutorial.CompletedChapters.Count > 0)
+            @if (Tutorial.CompletedChapterCount > 0)
             {
                 <button class="tutorial-btn tutorial-btn-secondary" @onclick="ResetProgress">
                     Reset Progress
@@ -20,22 +45,32 @@
     </div>
 
     <div class="tutorial-chapters-grid">
+        @{ var chapterNum = 0; }
         @foreach (var chapter in TutorialContent.Chapters)
         {
+            chapterNum++;
             var isCompleted = Tutorial.CompletedChapters.Contains(chapter.Id);
+            var num = chapterNum;
             <div class="tutorial-chapter-card @(isCompleted ? "completed" : "")" @onclick="() => StartChapter(chapter.Id)">
+                <div class="chapter-number">@num</div>
                 <div class="chapter-card-body">
                     <h3>@chapter.Title</h3>
                     <p>@chapter.Description</p>
                     <span class="chapter-step-count">@chapter.Steps.Count steps</span>
                 </div>
                 @if (isCompleted)
                 {
-                    <div class="chapter-completed-badge">✓</div>
+                    <div class="chapter-completed-badge">
+                        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+                    </div>
                 }
             </div>
         }
     </div>
+
+    <div class="tutorial-page-footer">
+        <p>Use arrow keys to navigate during a walkthrough. Press Escape to exit.</p>
+    </div>
 </div>
 
 @code {
@@ -45,6 +80,16 @@
     private void StartFullTour()
     {
         NavManager.NavigateTo("/");
+        if (Tutorial.CompletedChapterCount > 0 && Tutorial.CompletedChapterCount < Tutorial.TotalChapters)
+        {
+            // Resume from first incomplete chapter
+            var firstIncomplete = TutorialContent.Chapters.FirstOrDefault(c => !Tutorial.CompletedChapters.Contains(c.Id));
+            if (firstIncomplete != null)
+            {
+                Tutorial.StartChapter(firstIncomplete.Id);
+                return;
+            }
+        }
         Tutorial.StartTutorial();
     }