fix: Make Echo seamless to run locally on Windows

README.md

@@ -121,7 +121,66 @@ Or run `npx echo-start my-app` to choose interactively.
 
 # Development
 
-Fill out `packages/app/control/.env` and `packages/app/server/.env`. Then...
+## Prerequisites
 
-- `pnpm i`
-- `pnpm dev`
+Before running Echo locally, ensure you have:
+
+- **Node.js 18+** ([download](https://nodejs.org/))
+- **pnpm 10+** - Install via `npm install -g pnpm` or `corepack enable && corepack prepare pnpm@latest --activate`
+- **Docker Desktop** ([download](https://www.docker.com/products/docker-desktop/)) with Docker Compose plugin
+- **Git** ([download](https://git-scm.com/downloads))
+
+> **Windows Users**: See [WINDOWS-SETUP.md](./WINDOWS-SETUP.md) for detailed Windows-specific instructions and troubleshooting.
+
+## Quick Start
+
+1. **Clone and install dependencies**
+   ```bash
+   git clone https://github.com/Merit-Systems/Echo.git
+   cd Echo
+   pnpm install
+   ```
+
+2. **Start development servers**
+   ```bash
+   pnpm dev
+   ```
+
+   This command automatically:
+   - Starts PostgreSQL in Docker
+   - Generates Prisma client
+   - Runs database migrations  
+   - Starts Echo Control (port 3000) and Echo Server
+
+3. **Open Echo in your browser**
+   Navigate to [http://localhost:3000](http://localhost:3000)
+
+## Manual Setup (if needed)
+
+If you prefer to set up components individually:
+
+```bash
+# Set up Echo Control
+cd packages/app/control
+./scripts/setup.sh              # Linux/Mac/Git Bash
+# OR
+.\scripts\setup-windows.ps1     # Windows PowerShell
+
+# Start everything from repo root
+cd ../../..
+pnpm dev
+```
+
+## Common Issues
+
+### `pnpm: command not found`
+Install pnpm: `npm install -g pnpm`
+
+### Docker daemon not running
+Start Docker Desktop and wait for it to be ready (green icon in system tray)
+
+### Port conflicts
+If port 3000 or 5469 is in use, stop conflicting services or change ports in config files
+
+### Windows-specific issues
+See [WINDOWS-SETUP.md](./WINDOWS-SETUP.md) for PowerShell scripts, execution policy fixes, and line-ending configuration

WINDOWS-SETUP.md

@@ -0,0 +1,183 @@
+# Windows Setup Guide for Echo
+
+This guide helps Windows users get Echo running locally with minimal friction.
+
+## Prerequisites
+
+### 1. Install Node.js
+- Download and install Node.js 18+ from [nodejs.org](https://nodejs.org/)
+- Verify installation: `node --version`
+
+### 2. Install pnpm
+Echo uses pnpm as its package manager. Choose one of these methods:
+
+**Option A: Using npm (Recommended for Windows)**
+```powershell
+npm install -g pnpm
+```
+
+**Option B: Using corepack (built into Node 16.13+)**
+```powershell
+corepack enable
+corepack prepare pnpm@latest --activate
+```
+
+Verify installation:
+```powershell
+pnpm --version
+```
+
+### 3. Install Docker Desktop
+- Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)
+- Install and start Docker Desktop
+- Verify: `docker --version` and `docker compose version`
+
+### 4. Install Git for Windows (if not already installed)
+- Download from [git-scm.com](https://git-scm.com/download/win)
+- Choose "Git Bash" during installation for Unix-style shell support
+
+## Quick Start
+
+### Using PowerShell (Windows-native)
+
+1. **Clone the repository**
+   ```powershell
+   git clone https://github.com/Merit-Systems/Echo.git
+   cd Echo
+   ```
+
+2. **Install dependencies**
+   ```powershell
+   pnpm install
+   ```
+
+3. **Set up environment (Control Plane)**
+   ```powershell
+   cd packages\app\control
+   .\scripts\setup-windows.ps1
+   ```
+
+4. **Start development servers**
+   ```powershell
+   cd ..\..\..
+   pnpm dev
+   ```
+
+   This automatically:
+   - Starts Docker containers for PostgreSQL
+   - Generates Prisma client
+   - Runs database migrations
+   - Starts both Echo Control and Echo Server
+
+5. **Open in browser**
+   Navigate to [http://localhost:3000](http://localhost:3000)
+
+### Using Git Bash (Unix-style)
+
+If you prefer bash-style commands:
+
+1. **Clone and install**
+   ```bash
+   git clone https://github.com/Merit-Systems/Echo.git
+   cd Echo
+   pnpm install
+   ```
+
+2. **Set up and run**
+   ```bash
+   cd packages/app/control
+   ./scripts/setup.sh
+   cd ../../..
+   pnpm dev
+   ```
+
+## Common Issues on Windows
+
+### pnpm command not found
+**Solution**: Install pnpm using `npm install -g pnpm` or enable corepack as shown above.
+
+### Docker daemon is not running
+**Solution**: Open Docker Desktop and wait for it to fully start. You'll see a green icon in the system tray when ready.
+
+### Port 5469 already in use
+**Solution**: Another PostgreSQL instance may be running. Either:
+- Stop the conflicting service
+- Change the port in `packages/app/control/docker-local-db.yml` and update `DATABASE_URL` in `.env`
+
+### PowerShell execution policy error
+**Solution**: If you see "cannot be loaded because running scripts is disabled", run:
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+### Setup scripts won't run
+**Solution**: Windows users should use `setup-windows.ps1` in PowerShell or `setup.sh` in Git Bash:
+```powershell
+# In PowerShell
+.\scripts\setup-windows.ps1
+
+# In Git Bash
+./scripts/setup.sh
+```
+
+### Line ending errors (CRLF vs LF)
+**Solution**: Configure Git to handle line endings:
+```bash
+git config --global core.autocrlf true
+```
+
+## Verifying Your Setup
+
+After completing setup, verify everything works:
+
+1. **Check Docker**
+   ```powershell
+   docker ps
+   ```
+   Should show `echo-control-postgres-v2` container running
+
+2. **Check Database Connection**
+   ```powershell
+   cd packages\app\control
+   pnpm exec prisma studio
+   ```
+   Should open Prisma Studio in your browser
+
+3. **Access Echo**
+   Visit [http://localhost:3000](http://localhost:3000)
+   You should see the Echo Control dashboard
+
+## Development Workflow
+
+### Starting the servers
+```powershell
+# From repo root
+pnpm dev
+```
+
+### Stopping the servers
+- Press `Ctrl+C` in the terminal running `pnpm dev`
+- Stop Docker containers:
+  ```powershell
+  cd packages\app\control
+  docker compose -f docker-local-db.yml down
+  ```
+
+### Resetting the database
+```powershell
+cd packages\app\control
+pnpm exec prisma migrate reset
+```
+
+### Viewing database
+```powershell
+cd packages\app\control
+pnpm exec prisma studio
+```
+
+## Need Help?
+
+- Check the main [README.md](./README.md) for general documentation
+- Review [packages/app/control/README.md](./packages/app/control/README.md) for Control Plane details
+- Check [packages/app/server/README.md](./packages/app/server/README.md) for Server details
+- Report issues at [github.com/Merit-Systems/Echo/issues](https://github.com/Merit-Systems/Echo/issues)

check-prerequisites-windows.ps1

@@ -0,0 +1,100 @@
+# Echo Prerequisites Checker for Windows
+
+Write-Host "=== Echo Prerequisites Verification ===" -ForegroundColor Cyan
+Write-Host ""
+
+$allGood = $true
+
+# Check Node.js
+Write-Host "Checking Node.js..." -NoNewline
+$nodeInstalled = $false
+try {
+    $nodeCheck = & node --version 2>&1
+    if ($LASTEXITCODE -eq 0) {
+        $nodeInstalled = $true
+        Write-Host " OK $nodeCheck" -ForegroundColor Green
+    }
+} catch { }
+
+if (-not $nodeInstalled) {
+    Write-Host " MISSING" -ForegroundColor Red
+    Write-Host "   Install from https://nodejs.org/" -ForegroundColor Yellow
+    $allGood = $false
+}
+
+# Check pnpm
+Write-Host "Checking pnpm..." -NoNewline
+$pnpmInstalled = $false
+try {
+    $pnpmCheck = & pnpm --version 2>&1
+    if ($LASTEXITCODE -eq 0) {
+        $pnpmInstalled = $true
+        Write-Host " OK $pnpmCheck" -ForegroundColor Green
+    }
+} catch { }
+
+if (-not $pnpmInstalled) {
+    Write-Host " MISSING" -ForegroundColor Red
+    Write-Host "   Run: npm install -g pnpm" -ForegroundColor Yellow
+    $allGood = $false
+}
+
+# Check Docker
+Write-Host "Checking Docker..." -NoNewline
+$dockerInstalled = $false
+try {
+    $dockerCheck = & docker --version 2>&1
+    if ($LASTEXITCODE -eq 0) {
+        $dockerInstalled = $true
+        Write-Host " OK" -ForegroundColor Green
+
+        # Check if Docker daemon is running
+        Write-Host "Checking Docker daemon..." -NoNewline
+        $daemonCheck = & docker ps 2>&1
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host " RUNNING" -ForegroundColor Green
+        } else {
+            Write-Host " NOT RUNNING" -ForegroundColor Red
+            Write-Host "   Start Docker Desktop" -ForegroundColor Yellow
+            $allGood = $false
+        }
+    }
+} catch { }
+
+if (-not $dockerInstalled) {
+    Write-Host " MISSING" -ForegroundColor Red
+    Write-Host "   Install from https://www.docker.com/products/docker-desktop/" -ForegroundColor Yellow
+    $allGood = $false
+}
+
+# Check Git
+Write-Host "Checking Git..." -NoNewline
+$gitInstalled = $false
+try {
+    $gitCheck = & git --version 2>&1
+    if ($LASTEXITCODE -eq 0) {
+        $gitInstalled = $true
+        Write-Host " OK" -ForegroundColor Green
+    }
+} catch { }
+
+if (-not $gitInstalled) {
+    Write-Host " MISSING" -ForegroundColor Red
+    Write-Host "   Install from https://git-scm.com/download/win" -ForegroundColor Yellow
+    $allGood = $false
+}
+
+Write-Host ""
+if ($allGood) {
+    Write-Host "All prerequisites met! You are ready to run Echo." -ForegroundColor Green
+    Write-Host ""
+    Write-Host "Next steps:" -ForegroundColor Cyan
+    Write-Host "  1. pnpm install" -ForegroundColor White
+    Write-Host "  2. cd packages\app\control" -ForegroundColor White
+    Write-Host "  3. .\scripts\setup-windows.ps1" -ForegroundColor White
+    Write-Host "  4. cd ..\..\..  " -ForegroundColor White
+    Write-Host "  5. pnpm dev" -ForegroundColor White
+} else {
+    Write-Host "Please install missing prerequisites and run this script again." -ForegroundColor Red
+}
+Write-Host ""

packages/app/control/README.md

@@ -46,8 +46,10 @@ A comprehensive Next.js application for managing Echo applications, API keys, an
 ### Prerequisites
 
 - Node.js 18+
-- PostgreSQL database
-- pnpm
+- pnpm (install via `npm install -g pnpm` or `corepack enable`)
+- Docker + Docker Compose plugin (`docker compose`)
+
+> **Windows Users**: Use `.\scripts\setup-windows.ps1` in PowerShell instead of `./scripts/setup.sh`. See [WINDOWS-SETUP.md](../../../WINDOWS-SETUP.md) for complete Windows setup guide.
 
 ### Installation
 
@@ -66,8 +68,11 @@ A comprehensive Next.js application for managing Echo applications, API keys, an
 3. **Create .env file**:
 
    ```bash
-   # Generate .env file
+   # Linux/Mac/Git Bash
    pnpm local-setup
+
+   # Windows PowerShell
+   .\scripts\setup-windows.ps1
    ```
 
 4. **Run database migrations**: