Status: Done (2026-03-03)
Priority: Medium
Component: docs/wsl-manager.md
Summary: As a new user following the VS Code DevContainer walkthrough, I want clearer instructions and fewer friction points so that I can complete the setup without confusion.
Description:
A hands-on walkthrough with a colleague revealed several documentation gaps and unclear instructions in the VS Code DevContainer section of docs/wsl-manager.md. This item covers all documentation-only improvements.
Tasks:
-
WSL user setup hint — Add a remark that a simple username/password combination (e.g.,
wsluser/wsluserorvscode/vscode) is sufficient for a local development distro. -
Proxy setup
aptformatting — Theaptreference in the proxy setup step renders oddly in a box/code block. Clean up the formatting so it reads naturally. -
PowerShell
~note —~does not resolve correctly in PowerShell. Replace occurrences with$env:USERPROFILEor add a note explaining the difference. -
VS Code Settings description — The current instruction says to open the JSON settings file, but File → Preferences → Settings opens the UI, not the JSON. Rewrite to guide users through the Settings UI: explain what to search for and which values to set, rather than asking them to edit JSON directly.
-
Required VS Code extensions — Add a prerequisites note in the VS Code section listing the extensions that must be installed: Dev Containers, Remote - SSH, and WSL.
Acceptance Criteria:
- User setup step includes a username/password suggestion for local dev distros
- Proxy setup step has clean formatting for the
aptreference - PowerShell paths use
$env:USERPROFILEinstead of~, or a note explains the caveat - VS Code Settings instructions guide users through the Settings UI with search terms
- Required VS Code extensions (Dev Containers, Remote - SSH, WSL) are listed as prerequisites
- All existing documentation links and cross-references remain valid