docs: document full environment setup and enforce venv startup

Add a from-scratch setup section covering Python, Node/npm, PostgreSQL, and startup commands, and update the startup script to always create/use .venv instead of falling back to system Python.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -11,15 +11,50 @@ Independent operations tool (web + MCP) for alarm-centric workflows.
 - Quick diagnostics endpoint (`/v1/diagnostics`)
 - AP analysis bridge to oclaw (`/v1/ap/analyze`)
 
-## Run locally
+## Environment setup (from scratch)
 
-1. Install dependencies:
+### 0) Prerequisites
+
+- Python `3.11+` (project currently tested on newer versions too)
+- Node.js `20+` (includes npm) for frontend
+- PostgreSQL `14+`
+- PowerShell (Windows startup scripts use `.ps1`)
+
+Quick check:
 
 ```powershell
-python -m pip install -r requirements.txt
+python --version
+node --version
+npm --version
+psql --version
 ```
 
-2. Set environment variables:
+If Node/npm is missing (Windows example):
+
+```powershell
+winget install OpenJS.NodeJS.LTS
+```
+
+### 1) Python virtual environment and backend deps
+
+```powershell
+cd netx
+python -m venv .venv
+.\.venv\Scripts\python -m pip install --upgrade pip
+.\.venv\Scripts\python -m pip install -r requirements.txt
+```
+
+### 2) Frontend deps (npm)
+
+```powershell
+cd .\web
+npm install
+cd ..
+```
+
+### 3) Configure environment variables
+
+Option A: temporary env vars in current shell
 
 ```powershell
 $env:NETX_DATABASE_URL = "postgresql+psycopg://netx:netx@127.0.0.1:5432/netx"
@@ -27,7 +62,7 @@ $env:NETX_HOST = "127.0.0.1"
 $env:NETX_PORT = "8890"
 ```
 
-Or create a local `.env` (recommended for persistent local run):
+Option B: local `.env` (recommended)
 
 ```env
 NETX_DATABASE_URL=postgresql+psycopg://postgres:admin123@127.0.0.1:5432/netx
@@ -35,25 +70,29 @@ NETX_OCLAW_ANALYZE_TOKEN=admin123
 NETX_OCLAW_HEALTH_URL=http://127.0.0.1:8787/admin/api/ops-ai/health
 ```
 
-3. Start API:
+### 4) Start services
+
+Direct backend start:
 
 ```powershell
-python -m netx_api.main
+.\.venv\Scripts\python -m netx_api.main
 ```
 
-Or use automation scripts:
+Or use automation scripts (recommended):
+
+- API only (background):
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\scripts\start_netx.ps1 -SkipInstall -Background
 ```
 
-Start API + Vite together:
+- API + Vite UI (background):
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\scripts\start_netx.ps1 -SkipInstall -Background -WithWeb
 ```
 
-Stop:
+Stop all started services:
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\scripts\stop_netx.ps1 -Force
@@ -62,35 +101,16 @@ powershell -ExecutionPolicy Bypass -File .\scripts\stop_netx.ps1 -Force
 Primary web UI (Vite): `http://127.0.0.1:5173/`  
 API base: `http://127.0.0.1:8890/`
 
-4. Optional: start MCP server (for oclaw integration):
+### 5) Optional: MCP server (for oclaw integration)
 
 ```powershell
-python -m netx_api.mcp_server
+.\.venv\Scripts\python -m netx_api.mcp_server
 ```
 
-Or use MCP install payload:
+Or install via payload:
 
 - `netx/mcp_install_payload.json`
 
-## Industrial UI (Vite + React + TS)
-
-Frontend project lives in:
-
-- `netx/web`
-
-Run:
-
-```powershell
-cd web
-npm install
-npm run dev
-```
-
-Dev server: `http://127.0.0.1:5173`  
-`vite.config.ts` proxies `/v1/*` to `http://127.0.0.1:8890`.
-
-`8890` is API-only and no longer serves the main UI page.
-
 ## Useful API endpoints
 
 - `POST /v1/alarms/import`

scripts/start_netx.ps1

@@ -25,7 +25,14 @@ $webLogFile = Join-Path $runDir "web.out.log"
 $webErrFile = Join-Path $runDir "web.err.log"
 
 $venvPython = Join-Path $projectRoot ".venv\\Scripts\\python.exe"
-$pythonExe = if (Test-Path $venvPython) { $venvPython } else { "python" }
+if (-not (Test-Path $venvPython)) {
+    Write-Host "==> .venv not found, creating virtual environment"
+    python -m venv (Join-Path $projectRoot ".venv")
+}
+if (-not (Test-Path $venvPython)) {
+    throw "failed_to_create_venv"
+}
+$pythonExe = $venvPython
 
 Write-Host "==> Project root: $projectRoot"
 Write-Host "==> Using python: $pythonExe"