From 9db6be99e17a1a89b0b4e06be8392dbe14f32117 Mon Sep 17 00:00:00 2001
From: Koraji95-coder <Koraji95-coder@users.noreply.github.com>
Date: Sun, 24 May 2026 04:33:31 +0000
Subject: [PATCH] docs(start.ps1+README): clarify native Windows venv path;
 remove misleading WSL2-venv-portability claim (#2806)

Squashed from 3 author commits onto current master (3 base commits from
already-shipped #2783 were filtered out by the squash). #2805's expanded
candidate-path discovery + PathType Container check preserved from prior
stage commit.

Authorship preserved. CHANGELOG entry merged into batch stamp commit.
---
 README.md |  3 ++-
 start.ps1 | 12 +++++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index d82ecf3c..ccaca241 100644
--- a/README.md
+++ b/README.md
@@ -137,7 +137,8 @@ A community-maintained native Windows setup is documented at [@markwang2658/herm
 - **Memory:** community-measured ~330 MB native vs ~1080 MB with WSL2+Docker (varies by configuration).
 - **What works:** chat, workspace browser, session management, all themes.
 - **Known limitations:** some POSIX-style file paths surface in the workspace browser; bash-assuming agent tools may not work natively.
-- **WSL2 relationship:** WSL2 is recommended *once* for first-time venv creation (since `bootstrap.py` currently refuses on native Windows). After the venv exists, `start.ps1` at the repo root runs the WebUI natively by invoking `server.py` directly — no WSL2 needed for day-to-day use.
+- **Native Windows setup:** install Python 3.11+, then from the hermes-agent root in PowerShell: `python -m venv venv` → `pip install -r requirements.txt` → `pwsh .\start.ps1` (it auto-discovers `venv\Scripts\python.exe`).
+- **WSL2 relationship:** not a prerequisite — a WSL2-built venv (`venv/bin/python`, ELF) isn't invokable by native Windows Python, so use the native setup above. WSL2 stays useful as a parallel install if you want the full `bootstrap.py` + Linux runtime.
 
 If provider setup is still incomplete after install, the onboarding wizard will point you to finish it with `hermes model` instead of trying to replicate the full CLI setup in-browser.
 For a step-by-step walkthrough of the wizard, provider choices, local model server Base URLs, and safe re-runs, see [`docs/onboarding.md`](docs/onboarding.md).
diff --git a/start.ps1 b/start.ps1
index af61f14b..705da3eb 100644
--- a/start.ps1
+++ b/start.ps1
@@ -11,9 +11,15 @@
     server.py itself runs cleanly on native Windows.
 
     Assumes Python + hermes-agent + the WebUI Python deps are already
-    installed - same assumption start.sh makes when invoked outside
-    a fresh bootstrap. For first-time setup, run bootstrap.py inside
-    WSL2 once to create the venv, then this script can use that venv.
+    installed natively on Windows - same assumption start.sh makes
+    when invoked outside a fresh bootstrap. For first-time setup, the
+    native Windows path is to install Python 3.11+, then create a
+    Windows venv (`python -m venv venv`) and `pip install -r
+    requirements.txt` from the hermes-agent root in PowerShell - this
+    script then finds `venv\Scripts\python.exe` automatically. A venv
+    created inside WSL2 is a Linux virtual environment (`venv/bin/python`)
+    and cannot be used by native Windows Python, so the bootstrap.py-
+    inside-WSL2 path produces a venv `start.ps1` can't invoke.
 
 .PARAMETER Port
     TCP port the WebUI binds to. Overrides HERMES_WEBUI_PORT env.