From 5cc1ec98c046591a4134f91ba995d1a01fdbc106 Mon Sep 17 00:00:00 2001
From: mika kuns <mika.kuns@fb-tuning.de>
Date: Wed, 5 Aug 2026 20:09:52 +0200
Subject: [PATCH] feat(installer): add SystemCheckPage with blocking-error
 gating
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a new wizard page (positioned right after Welcome, FreshInstall only)
that auto-runs EnvironmentCheckService on entry and shows one row per check
with status icon, localized title/message, and hint+help-link on
failure/unknown. A "Recheck" button re-runs it, guarded against re-entrancy.

IInstallerPage gets a BlocksNavigation default member; WizardViewModel's
Next button now binds to CanGoNext, which the current page can veto (used
here while a check run is in flight or a blocking Error+Failed result is
present — Warnings and Unknown results never block). The summary line names
the blocking checks so a disabled Next is self-explanatory.

Wires up DI for the check pipeline (IProcessRunner, IPortOwnerResolver,
per-run ClaudeCliLookup) and adds the checks.* / installer.systemCheck.*
locale keys in en.json + de.json.

Visual appearance is NOT verified — needs a manual pass in the running
installer.
---
 src/ClaudeDo.Installer/App.xaml.cs            |  26 +++
 .../Core/Interfaces/IInstallerPage.cs         |   3 +
 .../Pages/PathsPage/PathsPageViewModel.cs     |   2 +-
 .../Pages/ServicePage/ServicePageViewModel.cs |   2 +-
 .../SystemCheckPage/SystemCheckPageView.xaml  |  99 ++++++++++
 .../SystemCheckPageView.xaml.cs               |   8 +
 .../SystemCheckPageViewModel.cs               | 160 ++++++++++++++++
 .../UiSettingsPage/UiSettingsPageViewModel.cs |   2 +-
 .../Views/WizardViewModel.cs                  |  11 ++
 .../Views/WizardWindow.xaml                   |   1 +
 src/ClaudeDo.Localization/locales/de.json     |  45 +++++
 src/ClaudeDo.Localization/locales/en.json     |  45 +++++
 .../ClaudeDo.Installer.Tests/FakeLocalizer.cs |  13 ++
 .../PageResolverTests.cs                      |  43 +++++
 .../SystemCheckPage/FakeEnvironmentCheck.cs   |  35 ++++
 .../SystemCheckPageViewModelTests.cs          | 172 ++++++++++++++++++
 .../WizardViewModelTests.cs                   |  53 ++++++
 17 files changed, 717 insertions(+), 3 deletions(-)
 create mode 100644 src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml
 create mode 100644 src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml.cs
 create mode 100644 src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageViewModel.cs
 create mode 100644 tests/ClaudeDo.Installer.Tests/FakeLocalizer.cs
 create mode 100644 tests/ClaudeDo.Installer.Tests/PageResolverTests.cs
 create mode 100644 tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/FakeEnvironmentCheck.cs
 create mode 100644 tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/SystemCheckPageViewModelTests.cs
 create mode 100644 tests/ClaudeDo.Installer.Tests/WizardViewModelTests.cs

diff --git a/src/ClaudeDo.Installer/App.xaml.cs b/src/ClaudeDo.Installer/App.xaml.cs
index 89207019..ef35f7da 100644
--- a/src/ClaudeDo.Installer/App.xaml.cs
+++ b/src/ClaudeDo.Installer/App.xaml.cs
@@ -4,13 +4,17 @@ using System.Linq;
 using System.Net.Http;
 using System.Reflection;
 using System.Windows;
+using ClaudeDo.Installer.Checks;
+using ClaudeDo.Installer.Checks.Interfaces;
 using ClaudeDo.Installer.Core;
+using ClaudeDo.Installer.Core.Interfaces;
 using ClaudeDo.Installer.Localization;
 using ClaudeDo.Localization;
 using ClaudeDo.Releases;
 using ClaudeDo.Installer.Pages.InstallPage;
 using ClaudeDo.Installer.Pages.PathsPage;
 using ClaudeDo.Installer.Pages.ServicePage;
+using ClaudeDo.Installer.Pages.SystemCheckPage;
 using ClaudeDo.Installer.Pages.UiSettingsPage;
 using ClaudeDo.Installer.Pages.WelcomePage;
 using ClaudeDo.Installer.Steps;
@@ -121,8 +125,30 @@ public partial class App : Application
         sc.AddSingleton<IReleaseClient>(sp => new ReleaseClient(sp.GetRequiredService<HttpClient>()));
         sc.AddSingleton<InstallModeDetector>();
 
+        // Environment checks — stateless, so their infrastructure is shared; ClaudeCliLookup is
+        // rebuilt per EnvironmentCheckService instance so a re-check doesn't reuse a stale result.
+        sc.AddSingleton<IProcessRunner, ProcessRunnerAdapter>();
+        sc.AddSingleton<IPortOwnerResolver, NetstatPortOwnerResolver>();
+        sc.AddTransient<Func<EnvironmentCheckService>>(sp => () =>
+        {
+            var processRunner = sp.GetRequiredService<IProcessRunner>();
+            var claudeLookup = new ClaudeCliLookup(processRunner);
+            return new EnvironmentCheckService(new IEnvironmentCheck[]
+            {
+                new GitCheck(processRunner),
+                new GitIdentityCheck(processRunner),
+                new PortCheck(sp.GetRequiredService<IPortOwnerResolver>()),
+                new WriteAccessCheck(),
+                new ClaudeCliCheck(claudeLookup),
+                new ClaudeVersionCheck(claudeLookup),
+                new ClaudeAuthCheck(claudeLookup),
+                new PermissionModeAutoCheck(claudeLookup),
+            });
+        });
+
         // Pages
         sc.AddSingleton<IInstallerPage, WelcomePageViewModel>();
+        sc.AddSingleton<IInstallerPage, SystemCheckPageViewModel>();
         sc.AddSingleton<IInstallerPage, PathsPageViewModel>();
         sc.AddSingleton<IInstallerPage, ServicePageViewModel>();
         sc.AddSingleton<IInstallerPage, UiSettingsPageViewModel>();
diff --git a/src/ClaudeDo.Installer/Core/Interfaces/IInstallerPage.cs b/src/ClaudeDo.Installer/Core/Interfaces/IInstallerPage.cs
index ef4db1c9..bd9b6799 100644
--- a/src/ClaudeDo.Installer/Core/Interfaces/IInstallerPage.cs
+++ b/src/ClaudeDo.Installer/Core/Interfaces/IInstallerPage.cs
@@ -13,4 +13,7 @@ public interface IInstallerPage
     Task LoadAsync();
     Task ApplyAsync();
     bool Validate();
+
+    /// <summary>True while this page wants "Next" disabled (e.g. a check run in progress or a blocking error).</summary>
+    bool BlocksNavigation => false;
 }
diff --git a/src/ClaudeDo.Installer/Pages/PathsPage/PathsPageViewModel.cs b/src/ClaudeDo.Installer/Pages/PathsPage/PathsPageViewModel.cs
index cd6d7d12..16b64e8e 100644
--- a/src/ClaudeDo.Installer/Pages/PathsPage/PathsPageViewModel.cs
+++ b/src/ClaudeDo.Installer/Pages/PathsPage/PathsPageViewModel.cs
@@ -12,7 +12,7 @@ public partial class PathsPageViewModel : ObservableObject, IInstallerPage
 
     public string Title => TrExtension.Localizer?["installer.paths.title"] ?? "Paths";
     public string Icon => "\uE8B7";
-    public int Order => 1;
+    public int Order => 2;
     public bool ShowInWizard => true;
     public bool ShowInSettings => true;
     public UserControl View => _view ??= new PathsPageView { DataContext = this };
diff --git a/src/ClaudeDo.Installer/Pages/ServicePage/ServicePageViewModel.cs b/src/ClaudeDo.Installer/Pages/ServicePage/ServicePageViewModel.cs
index 437e93ac..76cc099e 100644
--- a/src/ClaudeDo.Installer/Pages/ServicePage/ServicePageViewModel.cs
+++ b/src/ClaudeDo.Installer/Pages/ServicePage/ServicePageViewModel.cs
@@ -14,7 +14,7 @@ public partial class ServicePageViewModel : ObservableObject, IInstallerPage
 
     public string Title => TrExtension.Localizer?["installer.service.title"] ?? "Service";
     public string Icon => "\uE912";
-    public int Order => 2;
+    public int Order => 3;
     public bool ShowInWizard => true;
     public bool ShowInSettings => true;
     public UserControl View => _view ??= new ServicePageView { DataContext = this };
diff --git a/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml b/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml
new file mode 100644
index 00000000..459163af
--- /dev/null
+++ b/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml
@@ -0,0 +1,99 @@
+<UserControl x:Class="ClaudeDo.Installer.Pages.SystemCheckPage.SystemCheckPageView"
+             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+             xmlns:local="clr-namespace:ClaudeDo.Installer.Pages.SystemCheckPage"
+             xmlns:loc="clr-namespace:ClaudeDo.Installer.Localization"
+             d:DataContext="{d:DesignInstance local:SystemCheckPageViewModel}"
+             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+             mc:Ignorable="d">
+
+    <Grid>
+        <Grid.RowDefinitions>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="*"/>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="Auto"/>
+        </Grid.RowDefinitions>
+
+        <!-- Header -->
+        <StackPanel Grid.Row="0" Margin="0,0,0,16">
+            <TextBlock Text="{loc:Tr installer.systemCheck.title}" FontSize="18" FontWeight="SemiBold" Margin="0,0,0,4"/>
+            <TextBlock Text="{loc:Tr installer.systemCheck.subtitle}"
+                       Foreground="{StaticResource TextSecondaryBrush}" TextWrapping="Wrap"/>
+        </StackPanel>
+
+        <!-- Check list -->
+        <ScrollViewer Grid.Row="1" VerticalScrollBarVisibility="Auto">
+            <ItemsControl ItemsSource="{Binding Rows}">
+                <ItemsControl.ItemTemplate>
+                    <DataTemplate DataType="{x:Type local:CheckRowViewModel}">
+                        <Border Margin="0,0,0,6" Padding="10,8"
+                                Background="{StaticResource IslandBgBrush}"
+                                BorderBrush="{StaticResource BorderSubtleBrush}"
+                                BorderThickness="1" CornerRadius="4">
+                            <StackPanel>
+                                <Grid>
+                                    <Grid.ColumnDefinitions>
+                                        <ColumnDefinition Width="Auto"/>
+                                        <ColumnDefinition Width="*"/>
+                                    </Grid.ColumnDefinitions>
+
+                                    <Ellipse Grid.Column="0" Width="10" Height="10" Margin="0,0,10,0"
+                                             VerticalAlignment="Top"
+                                             Fill="{Binding StatusBrush}"/>
+
+                                    <StackPanel Grid.Column="1">
+                                        <TextBlock Text="{Binding Title}" FontSize="13" FontWeight="SemiBold"/>
+                                        <TextBlock Text="{Binding Message}" FontSize="12"
+                                                   Foreground="{StaticResource TextSecondaryBrush}"
+                                                   TextWrapping="Wrap" Margin="0,2,0,0"/>
+
+                                        <TextBlock Text="{Binding Hint}" FontSize="11"
+                                                   Foreground="{StaticResource TextMutedBrush}"
+                                                   TextWrapping="Wrap" Margin="0,4,0,0"
+                                                   Visibility="{Binding Hint, Converter={StaticResource NullToCollapsedConverter}}"/>
+
+                                        <Button Content="{Binding HelpUrl}"
+                                                HorizontalAlignment="Left" Margin="-16,4,0,0"
+                                                Background="Transparent" BorderThickness="0"
+                                                Foreground="{StaticResource AccentLightBrush}"
+                                                Cursor="Hand"
+                                                Command="{Binding DataContext.OpenHelpUrlCommand, RelativeSource={RelativeSource AncestorType=ItemsControl}}"
+                                                CommandParameter="{Binding HelpUrl}"
+                                                Visibility="{Binding HelpUrl, Converter={StaticResource NullToCollapsedConverter}}"/>
+                                    </StackPanel>
+                                </Grid>
+                            </StackPanel>
+                        </Border>
+                    </DataTemplate>
+                </ItemsControl.ItemTemplate>
+            </ItemsControl>
+        </ScrollViewer>
+
+        <!-- Progress + summary -->
+        <StackPanel Grid.Row="2" Margin="0,8,0,0">
+            <ProgressBar IsIndeterminate="True" Margin="0,0,0,8"
+                         Visibility="{Binding IsRunning, Converter={StaticResource BoolToVisConverter}}"/>
+            <TextBlock Text="{Binding Summary}" FontSize="12" TextWrapping="Wrap"
+                       Foreground="{StaticResource TextSecondaryBrush}">
+                <TextBlock.Style>
+                    <Style TargetType="TextBlock">
+                        <Style.Triggers>
+                            <DataTrigger Binding="{Binding HasBlockingError}" Value="True">
+                                <Setter Property="Foreground" Value="{StaticResource ErrorBrush}"/>
+                            </DataTrigger>
+                        </Style.Triggers>
+                    </Style>
+                </TextBlock.Style>
+            </TextBlock>
+        </StackPanel>
+
+        <!-- Footer -->
+        <StackPanel Grid.Row="3" Orientation="Horizontal" HorizontalAlignment="Right" Margin="0,12,0,0">
+            <!-- Reserved space: a "Claude Help Me" button lands here in a follow-up task. -->
+            <Button Content="{loc:Tr installer.systemCheck.recheck}"
+                    Command="{Binding RunChecksCommand}"/>
+        </StackPanel>
+    </Grid>
+</UserControl>
diff --git a/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml.cs b/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml.cs
new file mode 100644
index 00000000..2d7fafd7
--- /dev/null
+++ b/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageView.xaml.cs
@@ -0,0 +1,8 @@
+using System.Windows.Controls;
+
+namespace ClaudeDo.Installer.Pages.SystemCheckPage;
+
+public partial class SystemCheckPageView : UserControl
+{
+    public SystemCheckPageView() => InitializeComponent();
+}
diff --git a/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageViewModel.cs b/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageViewModel.cs
new file mode 100644
index 00000000..5356ca84
--- /dev/null
+++ b/src/ClaudeDo.Installer/Pages/SystemCheckPage/SystemCheckPageViewModel.cs
@@ -0,0 +1,160 @@
+using System.Collections.ObjectModel;
+using System.Diagnostics;
+using System.Windows;
+using System.Windows.Controls;
+using System.Windows.Media;
+using ClaudeDo.Installer.Checks;
+using ClaudeDo.Installer.Core;
+using ClaudeDo.Installer.Localization;
+using CommunityToolkit.Mvvm.ComponentModel;
+using CommunityToolkit.Mvvm.Input;
+
+namespace ClaudeDo.Installer.Pages.SystemCheckPage;
+
+public sealed class CheckRowViewModel
+{
+    public CheckRowViewModel(CheckResult result)
+    {
+        var loc = TrExtension.Localizer;
+        Status = result.Status;
+        Severity = result.Severity;
+        Title = loc?[result.TitleKey] ?? result.TitleKey;
+        Message = result.Message;
+        Hint = result.HintKey is not null ? loc?[result.HintKey] ?? result.HintKey : null;
+        HelpUrl = result.HelpUrl;
+        StatusBrush = ResolveBrush(Status, Severity);
+    }
+
+    public CheckStatus Status { get; }
+    public CheckSeverity Severity { get; }
+    public string Title { get; }
+    public string Message { get; }
+    public string? Hint { get; }
+    public string? HelpUrl { get; }
+    public Brush StatusBrush { get; }
+
+    private static Brush ResolveBrush(CheckStatus status, CheckSeverity severity)
+    {
+        var key = status switch
+        {
+            CheckStatus.Ok => "StatusGreenBrush",
+            CheckStatus.Unknown => "StatusGrayBrush",
+            CheckStatus.Failed when severity == CheckSeverity.Error => "StatusRedBrush",
+            CheckStatus.Failed => "StatusOrangeBrush",
+            _ => "StatusGrayBrush",
+        };
+        return Application.Current?.Resources[key] as Brush ?? Brushes.Gray;
+    }
+}
+
+public partial class SystemCheckPageViewModel : ObservableObject, IInstallerPage
+{
+    private readonly InstallContext _context;
+    private readonly Func<EnvironmentCheckService> _checkServiceFactory;
+    private SystemCheckPageView? _view;
+    private bool _hasStarted;
+
+    public string Title => TrExtension.Localizer?["installer.systemCheck.title"] ?? "System Check";
+    public string Icon => "";
+    public int Order => 1;
+    public bool ShowInWizard => true;
+    public bool ShowInSettings => false;
+    public UserControl View => _view ??= new SystemCheckPageView { DataContext = this };
+
+    public ObservableCollection<CheckRowViewModel> Rows { get; } = [];
+
+    [ObservableProperty] private bool _isRunning;
+    [ObservableProperty] private bool _hasRun;
+    [ObservableProperty] private bool _hasBlockingError;
+    [ObservableProperty] private string _summary = string.Empty;
+
+    public bool BlocksNavigation => IsRunning || HasBlockingError;
+
+    public SystemCheckPageViewModel(InstallContext context, Func<EnvironmentCheckService> checkServiceFactory)
+    {
+        _context = context;
+        _checkServiceFactory = checkServiceFactory;
+    }
+
+    partial void OnIsRunningChanged(bool value)
+    {
+        OnPropertyChanged(nameof(BlocksNavigation));
+        RunChecksCommand.NotifyCanExecuteChanged();
+    }
+
+    partial void OnHasBlockingErrorChanged(bool value) => OnPropertyChanged(nameof(BlocksNavigation));
+
+    public Task LoadAsync()
+    {
+        if (!_hasStarted)
+        {
+            _hasStarted = true;
+            _ = RunChecksAsync();
+        }
+        return Task.CompletedTask;
+    }
+
+    public Task ApplyAsync() => Task.CompletedTask;
+
+    public bool Validate() => !HasBlockingError;
+
+    [RelayCommand(CanExecute = nameof(CanRunChecks))]
+    private async Task RunChecksAsync()
+    {
+        if (IsRunning) return;
+
+        IsRunning = true;
+        Summary = TrExtension.Localizer?["installer.systemCheck.summary.running"] ?? "Checking your system…";
+
+        try
+        {
+            var service = _checkServiceFactory();
+            var report = await service.RunAllAsync(_context, CancellationToken.None);
+
+            Rows.Clear();
+            foreach (var result in report.Results)
+                Rows.Add(new CheckRowViewModel(result));
+
+            HasBlockingError = report.HasBlockingError;
+            Summary = BuildSummary(report);
+            HasRun = true;
+        }
+        finally
+        {
+            IsRunning = false;
+        }
+    }
+
+    private bool CanRunChecks() => !IsRunning;
+
+    private static string BuildSummary(EnvironmentCheckReport report)
+    {
+        var loc = TrExtension.Localizer;
+
+        var blocking = report.Results
+            .Where(r => r.Severity == CheckSeverity.Error && r.Status == CheckStatus.Failed)
+            .ToList();
+        if (blocking.Count > 0)
+        {
+            var names = string.Join(", ", blocking.Select(r => loc?[r.TitleKey] ?? r.TitleKey));
+            return loc?.Get("installer.systemCheck.summary.blocking", blocking.Count, names)
+                   ?? $"{blocking.Count} problem(s) must be fixed: {names}";
+        }
+
+        var warnings = report.Results.Count(r => r.Severity == CheckSeverity.Warning && r.Status == CheckStatus.Failed);
+        if (warnings > 0)
+        {
+            return loc?.Get("installer.systemCheck.summary.warnings", warnings)
+                   ?? $"{warnings} warning(s) found.";
+        }
+
+        return loc?["installer.systemCheck.summary.ok"] ?? "Everything looks good.";
+    }
+
+    [RelayCommand]
+    private static void OpenHelpUrl(string? url)
+    {
+        if (string.IsNullOrEmpty(url)) return;
+        Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
+    }
+}
diff --git a/src/ClaudeDo.Installer/Pages/UiSettingsPage/UiSettingsPageViewModel.cs b/src/ClaudeDo.Installer/Pages/UiSettingsPage/UiSettingsPageViewModel.cs
index 2bbc09c6..290a9655 100644
--- a/src/ClaudeDo.Installer/Pages/UiSettingsPage/UiSettingsPageViewModel.cs
+++ b/src/ClaudeDo.Installer/Pages/UiSettingsPage/UiSettingsPageViewModel.cs
@@ -12,7 +12,7 @@ public partial class UiSettingsPageViewModel : ObservableObject, IInstallerPage
 
     public string Title => TrExtension.Localizer?["installer.uiSettings.title"] ?? "UI Settings";
     public string Icon => "\uE771";
-    public int Order => 3;
+    public int Order => 4;
     public bool ShowInWizard => true;
     public bool ShowInSettings => true;
     public UserControl View => _view ??= new UiSettingsPageView { DataContext = this };
diff --git a/src/ClaudeDo.Installer/Views/WizardViewModel.cs b/src/ClaudeDo.Installer/Views/WizardViewModel.cs
index 69f54c75..7b8f546e 100644
--- a/src/ClaudeDo.Installer/Views/WizardViewModel.cs
+++ b/src/ClaudeDo.Installer/Views/WizardViewModel.cs
@@ -1,3 +1,4 @@
+using System.ComponentModel;
 using System.Linq;
 using System.Windows;
 using ClaudeDo.Installer.Core;
@@ -32,10 +33,12 @@ public partial class WizardViewModel : ObservableObject
     [NotifyPropertyChangedFor(nameof(IsLastPage))]
     [NotifyPropertyChangedFor(nameof(NextButtonText))]
     [NotifyPropertyChangedFor(nameof(CurrentPage))]
+    [NotifyPropertyChangedFor(nameof(CanGoNext))]
     private int _currentPageIndex;
 
     public IInstallerPage CurrentPage => Pages[CurrentPageIndex];
     public bool CanGoBack => CurrentPageIndex > 0;
+    public bool CanGoNext => !CurrentPage.BlocksNavigation;
     public bool IsLastPage => CurrentPageIndex == Pages.Count - 1;
     public string NextButtonText => IsLastPage
         ? (_localizer["installer.nav.install"])
@@ -58,6 +61,14 @@ public partial class WizardViewModel : ObservableObject
                           || p is InstallPageViewModel).ToList()
             : all;
 
+        // A page's blocking state (e.g. a running/failed system check) can change while it's
+        // displayed; re-evaluate CanGoNext whenever any page raises a property change.
+        foreach (var page in Pages)
+        {
+            if (page is INotifyPropertyChanged notifying)
+                notifying.PropertyChanged += (_, _) => OnPropertyChanged(nameof(CanGoNext));
+        }
+
         if (Pages.Count > 0)
             _ = InitAsync();
     }
diff --git a/src/ClaudeDo.Installer/Views/WizardWindow.xaml b/src/ClaudeDo.Installer/Views/WizardWindow.xaml
index b063c0e6..a984f334 100644
--- a/src/ClaudeDo.Installer/Views/WizardWindow.xaml
+++ b/src/ClaudeDo.Installer/Views/WizardWindow.xaml
@@ -100,6 +100,7 @@
 
                 <Button Grid.Column="2" Content="{Binding NextButtonText}"
                         Command="{Binding GoNextCommand}"
+                        IsEnabled="{Binding CanGoNext}"
                         Style="{StaticResource AccentButton}"
                         MinWidth="100"/>
             </Grid>
diff --git a/src/ClaudeDo.Localization/locales/de.json b/src/ClaudeDo.Localization/locales/de.json
index 2504b9f3..2e441565 100644
--- a/src/ClaudeDo.Localization/locales/de.json
+++ b/src/ClaudeDo.Localization/locales/de.json
@@ -481,6 +481,17 @@
       "registerMcp": "MCP-Server bei Claude registrieren",
       "registerMcpHint": "Führt 'claude mcp add' aus, damit Claude deine ClaudeDo-Aufgaben sehen und verwalten kann. Du kannst dies später ändern."
     },
+    "systemCheck": {
+      "title": "Systemprüfung",
+      "subtitle": "ClaudeDo prüft dein System vor der Installation.",
+      "recheck": "Erneut prüfen",
+      "summary": {
+        "running": "System wird geprüft…",
+        "ok": "Alles in Ordnung.",
+        "warnings": "{0} Warnung(en) gefunden.",
+        "blocking": "{0} Problem(e) müssen behoben werden: {1}"
+      }
+    },
     "paths": {
       "title": "Datenpfade",
       "subtitle": "Lege fest, wo ClaudeDo seine Daten speichert.",
@@ -525,6 +536,40 @@
       "continueAnyway": "Trotzdem fortfahren"
     }
   },
+  "checks": {
+    "git": {
+      "title": "Git",
+      "hint": "Installiere Git und stelle sicher, dass es im PATH liegt."
+    },
+    "gitIdentity": {
+      "title": "Git-Identität",
+      "hint": "Lege deine Git-Identität fest: git config --global user.name \"...\" und user.email \"...\"."
+    },
+    "ports": {
+      "title": "Ports",
+      "hint": "Gib den Port frei oder ändere ihn nach der Installation auf der Worker-Seite."
+    },
+    "writeAccess": {
+      "title": "Schreibzugriff",
+      "hint": "Wähle ein anderes Installationsverzeichnis oder starte den Installer als Administrator."
+    },
+    "claudeCli": {
+      "title": "Claude CLI",
+      "hint": "Installiere die Claude CLI und stelle sicher, dass sie im PATH liegt."
+    },
+    "claudeVersion": {
+      "title": "Claude-CLI-Version",
+      "hint": "Aktualisiere die Claude CLI auf eine neuere Version."
+    },
+    "claudeAuth": {
+      "title": "Claude-Anmeldung",
+      "hint": "Führe 'claude auth login' aus, um dich anzumelden."
+    },
+    "permissionModeAuto": {
+      "title": "Berechtigungsmodus",
+      "hint": "Aktualisiere die Claude CLI auf eine Version, die --permission-mode auto unterstützt."
+    }
+  },
   "planning": {
     "conflict": {
       "windowTitle": "Merge-Konflikt",
diff --git a/src/ClaudeDo.Localization/locales/en.json b/src/ClaudeDo.Localization/locales/en.json
index 3c9a44e1..66d8aa93 100644
--- a/src/ClaudeDo.Localization/locales/en.json
+++ b/src/ClaudeDo.Localization/locales/en.json
@@ -481,6 +481,17 @@
       "registerMcp": "Register MCP server with Claude",
       "registerMcpHint": "Runs 'claude mcp add' so Claude can view and manage your ClaudeDo tasks. You can change this later."
     },
+    "systemCheck": {
+      "title": "System Check",
+      "subtitle": "ClaudeDo checks your system before installing.",
+      "recheck": "Recheck",
+      "summary": {
+        "running": "Checking your system…",
+        "ok": "Everything looks good.",
+        "warnings": "{0} warning(s) found.",
+        "blocking": "{0} problem(s) must be fixed: {1}"
+      }
+    },
     "paths": {
       "title": "Data Paths",
       "subtitle": "Configure where ClaudeDo stores its data.",
@@ -525,6 +536,40 @@
       "continueAnyway": "Continue anyway"
     }
   },
+  "checks": {
+    "git": {
+      "title": "Git",
+      "hint": "Install Git and make sure it is on PATH."
+    },
+    "gitIdentity": {
+      "title": "Git Identity",
+      "hint": "Set your git identity: git config --global user.name \"...\" and user.email \"...\"."
+    },
+    "ports": {
+      "title": "Ports",
+      "hint": "Free the port, or change it on the Worker page after install."
+    },
+    "writeAccess": {
+      "title": "Write Access",
+      "hint": "Choose a different install directory, or run the installer as administrator."
+    },
+    "claudeCli": {
+      "title": "Claude CLI",
+      "hint": "Install the Claude CLI and make sure it is on PATH."
+    },
+    "claudeVersion": {
+      "title": "Claude CLI Version",
+      "hint": "Update the Claude CLI to a newer version."
+    },
+    "claudeAuth": {
+      "title": "Claude Login",
+      "hint": "Run 'claude auth login' to sign in."
+    },
+    "permissionModeAuto": {
+      "title": "Permission Mode",
+      "hint": "Update the Claude CLI to a version that supports --permission-mode auto."
+    }
+  },
   "planning": {
     "conflict": {
       "windowTitle": "Merge conflict",
diff --git a/tests/ClaudeDo.Installer.Tests/FakeLocalizer.cs b/tests/ClaudeDo.Installer.Tests/FakeLocalizer.cs
new file mode 100644
index 00000000..177947e1
--- /dev/null
+++ b/tests/ClaudeDo.Installer.Tests/FakeLocalizer.cs
@@ -0,0 +1,13 @@
+using ClaudeDo.Localization;
+
+namespace ClaudeDo.Installer.Tests;
+
+internal sealed class FakeLocalizer : ILocalizer
+{
+    public string this[string key] => key;
+    public string Get(string key, params object[] args) => key;
+    public string CurrentCode { get; private set; } = "en";
+    public IReadOnlyList<LanguageOption> AvailableLanguages { get; } = new[] { new LanguageOption("en", "English") };
+    public void SetLanguage(string code) => CurrentCode = code;
+    public event EventHandler? LanguageChanged;
+}
diff --git a/tests/ClaudeDo.Installer.Tests/PageResolverTests.cs b/tests/ClaudeDo.Installer.Tests/PageResolverTests.cs
new file mode 100644
index 00000000..bd5b5690
--- /dev/null
+++ b/tests/ClaudeDo.Installer.Tests/PageResolverTests.cs
@@ -0,0 +1,43 @@
+using ClaudeDo.Installer.Core;
+using ClaudeDo.Installer.Pages.PathsPage;
+using ClaudeDo.Installer.Pages.ServicePage;
+using ClaudeDo.Installer.Pages.SystemCheckPage;
+using ClaudeDo.Installer.Pages.UiSettingsPage;
+using ClaudeDo.Installer.Pages.WelcomePage;
+
+namespace ClaudeDo.Installer.Tests;
+
+public class PageResolverTests
+{
+    [Fact]
+    public void SystemCheckPage_is_in_the_wizard_directly_after_welcome()
+    {
+        var context = new InstallContext();
+        var pages = new IInstallerPage[]
+        {
+            new WelcomePageViewModel(context),
+            new SystemCheckPageViewModel(context, () => throw new InvalidOperationException()),
+            new PathsPageViewModel(context),
+            new ServicePageViewModel(context),
+            new UiSettingsPageViewModel(context),
+        };
+
+        var resolver = new PageResolver(pages);
+        var wizardPages = resolver.WizardPages;
+
+        var welcomeIndex = wizardPages.ToList().FindIndex(p => p is WelcomePageViewModel);
+        var systemCheckIndex = wizardPages.ToList().FindIndex(p => p is SystemCheckPageViewModel);
+
+        Assert.NotEqual(-1, welcomeIndex);
+        Assert.Equal(welcomeIndex + 1, systemCheckIndex);
+    }
+
+    [Fact]
+    public void SystemCheckPage_is_not_shown_in_settings()
+    {
+        var context = new InstallContext();
+        var page = new SystemCheckPageViewModel(context, () => throw new InvalidOperationException());
+
+        Assert.False(page.ShowInSettings);
+    }
+}
diff --git a/tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/FakeEnvironmentCheck.cs b/tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/FakeEnvironmentCheck.cs
new file mode 100644
index 00000000..98c54b71
--- /dev/null
+++ b/tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/FakeEnvironmentCheck.cs
@@ -0,0 +1,35 @@
+using ClaudeDo.Installer.Checks;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Tests.Pages.SystemCheckPage;
+
+internal sealed class FakeEnvironmentCheck : IEnvironmentCheck
+{
+    private readonly Func<InstallContext, CancellationToken, Task<CheckResult>> _run;
+
+    public FakeEnvironmentCheck(string id, CheckSeverity severity, Func<InstallContext, CancellationToken, Task<CheckResult>> run)
+    {
+        Id = id;
+        Severity = severity;
+        _run = run;
+    }
+
+    public static FakeEnvironmentCheck Ok(string id, CheckSeverity severity = CheckSeverity.Error) =>
+        new(id, severity, (_, _) => Task.FromResult(CheckResult.Ok(id, severity, $"checks.{id}.title", "ok")));
+
+    public static FakeEnvironmentCheck Fail(string id, CheckSeverity severity) =>
+        new(id, severity, (_, _) => Task.FromResult(CheckResult.Fail(id, severity, $"checks.{id}.title", "failed")));
+
+    public static FakeEnvironmentCheck Unknown(string id, CheckSeverity severity = CheckSeverity.Warning) =>
+        new(id, severity, (_, _) => Task.FromResult(CheckResult.Unknown(id, severity, $"checks.{id}.title", "unknown")));
+
+    public string Id { get; }
+    public CheckSeverity Severity { get; }
+    public int CallCount { get; private set; }
+
+    public Task<CheckResult> RunAsync(InstallContext ctx, CancellationToken ct)
+    {
+        CallCount++;
+        return _run(ctx, ct);
+    }
+}
diff --git a/tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/SystemCheckPageViewModelTests.cs b/tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/SystemCheckPageViewModelTests.cs
new file mode 100644
index 00000000..7465acc3
--- /dev/null
+++ b/tests/ClaudeDo.Installer.Tests/Pages/SystemCheckPage/SystemCheckPageViewModelTests.cs
@@ -0,0 +1,172 @@
+using ClaudeDo.Installer.Checks;
+using ClaudeDo.Installer.Core;
+using Vm = ClaudeDo.Installer.Pages.SystemCheckPage.SystemCheckPageViewModel;
+
+namespace ClaudeDo.Installer.Tests.Pages.SystemCheckPage;
+
+public sealed class SystemCheckPageViewModelTests
+{
+    private static Vm CreateViewModel(Func<EnvironmentCheckService> factory) =>
+        new(new InstallContext(), factory);
+
+    private static Func<EnvironmentCheckService> FactoryFor(params IEnvironmentCheck[] checks) =>
+        () => new EnvironmentCheckService(checks);
+
+    [Fact]
+    public async Task Entering_the_page_runs_checks_exactly_once()
+    {
+        var check = FakeEnvironmentCheck.Ok("a");
+        var vm = CreateViewModel(FactoryFor(check));
+
+        await vm.LoadAsync();
+
+        Assert.Equal(1, check.CallCount);
+        Assert.True(vm.HasRun);
+        Assert.Single(vm.Rows);
+    }
+
+    [Fact]
+    public async Task Entering_the_page_a_second_time_does_not_run_checks_again()
+    {
+        var check = FakeEnvironmentCheck.Ok("a");
+        var vm = CreateViewModel(FactoryFor(check));
+
+        await vm.LoadAsync();
+        await vm.LoadAsync();
+
+        Assert.Equal(1, check.CallCount);
+    }
+
+    [Fact]
+    public async Task Recheck_while_a_run_is_in_progress_does_not_start_a_second_run()
+    {
+        var gate = new TaskCompletionSource();
+        var slow = new FakeEnvironmentCheck("slow", CheckSeverity.Error, async (_, _) =>
+        {
+            await gate.Task;
+            return CheckResult.Ok("slow", CheckSeverity.Error, "checks.slow.title", "ok");
+        });
+
+        var factoryCalls = 0;
+        var vm = CreateViewModel(() =>
+        {
+            factoryCalls++;
+            return new EnvironmentCheckService(new IEnvironmentCheck[] { slow });
+        });
+
+        var firstRun = vm.RunChecksCommand.ExecuteAsync(null);
+        Assert.True(vm.IsRunning);
+
+        await vm.RunChecksCommand.ExecuteAsync(null); // recheck while the first run is still in flight
+
+        Assert.Equal(1, factoryCalls);
+        Assert.Equal(1, slow.CallCount);
+
+        gate.SetResult();
+        await firstRun;
+
+        Assert.False(vm.IsRunning);
+    }
+
+    [Fact]
+    public async Task Blocking_error_blocks_navigation_and_clears_after_a_clean_recheck()
+    {
+        var callNumber = 0;
+        var vm = CreateViewModel(() =>
+        {
+            callNumber++;
+            IEnvironmentCheck check = callNumber == 1
+                ? FakeEnvironmentCheck.Fail("git", CheckSeverity.Error)
+                : FakeEnvironmentCheck.Ok("git");
+            return new EnvironmentCheckService(new[] { check });
+        });
+
+        await vm.LoadAsync();
+
+        Assert.True(vm.HasBlockingError);
+        Assert.True(vm.BlocksNavigation);
+
+        await vm.RunChecksCommand.ExecuteAsync(null);
+
+        Assert.False(vm.HasBlockingError);
+        Assert.False(vm.BlocksNavigation);
+    }
+
+    [Fact]
+    public async Task Only_warnings_does_not_block_navigation()
+    {
+        var warning = FakeEnvironmentCheck.Fail("gitIdentity", CheckSeverity.Warning);
+        var vm = CreateViewModel(FactoryFor(warning));
+
+        await vm.LoadAsync();
+
+        Assert.False(vm.HasBlockingError);
+        Assert.False(vm.BlocksNavigation);
+    }
+
+    [Fact]
+    public async Task Only_unknown_results_do_not_block_navigation()
+    {
+        var unknown = FakeEnvironmentCheck.Unknown("claudeAuth", CheckSeverity.Error);
+        var vm = CreateViewModel(FactoryFor(unknown));
+
+        await vm.LoadAsync();
+
+        Assert.False(vm.HasBlockingError);
+        Assert.False(vm.BlocksNavigation);
+    }
+
+    [Fact]
+    public async Task Summary_reports_all_ok()
+    {
+        var vm = CreateViewModel(FactoryFor(FakeEnvironmentCheck.Ok("git")));
+
+        await vm.LoadAsync();
+
+        Assert.Equal("Everything looks good.", vm.Summary);
+    }
+
+    [Fact]
+    public async Task Summary_reports_warning_count()
+    {
+        var vm = CreateViewModel(FactoryFor(
+            FakeEnvironmentCheck.Fail("gitIdentity", CheckSeverity.Warning),
+            FakeEnvironmentCheck.Fail("ports", CheckSeverity.Warning)));
+
+        await vm.LoadAsync();
+
+        Assert.Equal("2 warning(s) found.", vm.Summary);
+    }
+
+    [Fact]
+    public async Task Summary_reports_blocking_errors_by_name()
+    {
+        var vm = CreateViewModel(FactoryFor(
+            FakeEnvironmentCheck.Fail("git", CheckSeverity.Error),
+            FakeEnvironmentCheck.Fail("writeAccess", CheckSeverity.Error)));
+
+        await vm.LoadAsync();
+
+        Assert.Equal("2 problem(s) must be fixed: checks.git.title, checks.writeAccess.title", vm.Summary);
+    }
+
+    [Fact]
+    public async Task Summary_reports_running_state_while_a_check_is_in_flight()
+    {
+        var gate = new TaskCompletionSource();
+        var slow = new FakeEnvironmentCheck("slow", CheckSeverity.Error, async (_, _) =>
+        {
+            await gate.Task;
+            return CheckResult.Ok("slow", CheckSeverity.Error, "checks.slow.title", "ok");
+        });
+        var vm = CreateViewModel(FactoryFor(slow));
+
+        var run = vm.RunChecksCommand.ExecuteAsync(null);
+
+        Assert.True(vm.IsRunning);
+        Assert.Equal("Checking your system…", vm.Summary);
+
+        gate.SetResult();
+        await run;
+    }
+}
diff --git a/tests/ClaudeDo.Installer.Tests/WizardViewModelTests.cs b/tests/ClaudeDo.Installer.Tests/WizardViewModelTests.cs
new file mode 100644
index 00000000..88c387cd
--- /dev/null
+++ b/tests/ClaudeDo.Installer.Tests/WizardViewModelTests.cs
@@ -0,0 +1,53 @@
+using ClaudeDo.Installer.Core;
+using ClaudeDo.Installer.Pages.InstallPage;
+using ClaudeDo.Installer.Pages.PathsPage;
+using ClaudeDo.Installer.Pages.ServicePage;
+using ClaudeDo.Installer.Pages.SystemCheckPage;
+using ClaudeDo.Installer.Pages.UiSettingsPage;
+using ClaudeDo.Installer.Pages.WelcomePage;
+using ClaudeDo.Installer.Views;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ClaudeDo.Installer.Tests;
+
+public class WizardViewModelTests
+{
+    private static IReadOnlyList<IInstallerPage> BuildAllPages(InstallContext context)
+    {
+        var emptyServiceProvider = new ServiceCollection().BuildServiceProvider();
+        return new IInstallerPage[]
+        {
+            new WelcomePageViewModel(context),
+            new SystemCheckPageViewModel(context, () => throw new InvalidOperationException("not needed for this test")),
+            new PathsPageViewModel(context),
+            new ServicePageViewModel(context),
+            new UiSettingsPageViewModel(context),
+            new InstallPageViewModel(context, emptyServiceProvider),
+        };
+    }
+
+    [Fact]
+    public void FreshInstall_includes_SystemCheckPage_directly_after_welcome()
+    {
+        var context = new InstallContext { Mode = InstallerMode.FreshInstall };
+        var resolver = new PageResolver(BuildAllPages(context));
+        var vm = new WizardViewModel(resolver, context, new FakeLocalizer());
+
+        var pages = vm.Pages.ToList();
+        var welcomeIndex = pages.FindIndex(p => p is WelcomePageViewModel);
+        var systemCheckIndex = pages.FindIndex(p => p is SystemCheckPageViewModel);
+
+        Assert.NotEqual(-1, welcomeIndex);
+        Assert.Equal(welcomeIndex + 1, systemCheckIndex);
+    }
+
+    [Fact]
+    public void Update_mode_does_not_show_SystemCheckPage()
+    {
+        var context = new InstallContext { Mode = InstallerMode.Update };
+        var resolver = new PageResolver(BuildAllPages(context));
+        var vm = new WizardViewModel(resolver, context, new FakeLocalizer());
+
+        Assert.DoesNotContain(vm.Pages, p => p is SystemCheckPageViewModel);
+    }
+}