From 8d5564b4d0c6f5ea0d1ab4d8d6a38732bf08bed6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 26 Mar 2026 06:33:04 +0000
Subject: [PATCH] docs: add WSL setup and 'Catastrophic failure'
 troubleshooting

Windows developers using the Docker-based workflow need WSL 2.
The wsl.exe --update command can silently fail with "Catastrophic
failure" when not run as Administrator or when Windows features
are not fully enabled.

- Add WSL 2 prerequisite callout to the Windows Installation section
  with a direct link to the new troubleshooting entry
- Add Troubleshooting Issue #10 covering the "Catastrophic failure"
  error: causes (missing elevation, pending reboot, disabled Windows
  features, corrupted state) and five ordered resolution steps
  (run as Admin, Microsoft Store, GitHub offline install, enable
  Windows features + reboot, full reinstall) plus verification commands

https://claude.ai/code/session_01MAqcBuahYPa7CUZ1hTcYQd
---
 docs/HELP.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/docs/HELP.md b/docs/HELP.md
index bcf5638e00..4cfa554773 100644
--- a/docs/HELP.md
+++ b/docs/HELP.md
@@ -273,6 +273,8 @@ Access the dashboard at `http://localhost:8080`.
 
 ### Windows Installation
 
+> **WSL 2 prerequisite (Docker mode):** The Docker-based installation requires Windows Subsystem for Linux 2. Run `wsl --status` to verify WSL 2 is active. If WSL is not installed or needs updating, see [Troubleshooting Issue #10](#10-catastrophic-failure-when-updating-wsl-on-windows) for setup steps and fixes.
+
 The PowerShell installer mirrors the same workflow on Windows.
 
 ```powershell
@@ -1939,6 +1941,74 @@ grep -i "warning" restore-diag.log
 2. Enable garbage collection logging
 3. Reduce concurrent subscriptions
 
+#### 10. "Catastrophic failure" when updating WSL on Windows
+
+**Context:** The Docker-based DevContainer and `install.ps1 -Mode Docker` workflows require
+Windows Subsystem for Linux 2 (WSL 2). Attempting to install or update WSL may fail with:
+
+```
+Downloading: Windows Subsystem for Linux 2.6.3
+Installing: Windows Subsystem for Linux 2.6.3
+Catastrophic failure
+```
+
+**Causes:**
+- Command was not run as Administrator (elevation is required)
+- Windows Update is pending a reboot
+- Corrupted WSL installation state
+- Virtual Machine Platform Windows feature not enabled
+
+**Resolution — try in order:**
+
+1. **Run as Administrator**
+
+   Open PowerShell as Administrator and retry:
+   ```powershell
+   wsl.exe --update
+   ```
+
+2. **Install or update from the Microsoft Store**
+
+   Search for "Windows Subsystem for Linux" in the Microsoft Store and click **Update** or **Install**.
+
+3. **Install from GitHub releases (offline / behind firewall)**
+
+   Download the latest `.msixbundle` from the [WSL releases page](https://github.com/microsoft/WSL/releases)
+   and double-click to install, or install from an elevated PowerShell:
+   ```powershell
+   Add-AppxPackage .\Microsoft.WSL_<version>_x64_ARM64.msixbundle
+   ```
+
+4. **Enable required Windows features first, then update**
+
+   ```powershell
+   # Run as Administrator
+   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
+   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+   Restart-Computer
+   # After reboot, from an elevated PowerShell:
+   wsl --set-default-version 2
+   wsl --update
+   ```
+
+5. **Reinstall WSL from scratch**
+
+   ```powershell
+   # Run as Administrator — replaces the existing WSL installation
+   wsl --install
+   ```
+
+**Verify WSL 2 is active after fixing:**
+```powershell
+wsl --status          # Should report WSL version 2
+wsl --list --verbose  # Lists installed distros with their WSL version
+```
+
+Once WSL 2 is working, Docker Desktop will use it automatically. Re-run the installer:
+```powershell
+.\build\scripts\install\install.ps1 -Mode Docker
+```
+
 ### Logging
 
 Logs are stored in the data directory under `_logs/`: