feat: add NSIS installer and classroom admin checklist

docs/CLASSROOM_INSTALL.md

@@ -0,0 +1,178 @@
+# CodeWhale Classroom / Lab Install Checklist
+
+A step-by-step checklist for IT admins deploying CodeWhale on lab or classroom
+machines running Windows.
+
+> **Audience**: IT staff, teaching assistants, lab managers.
+> **Prereq**: Each target machine runs Windows 10 (1809+) or Windows 11.
+
+---
+
+## Pre-install checklist (run once per machine)
+
+| # | Task | Done? |
+|---|------|-------|
+| 1 | Confirm Windows version: `winver` → 10 build 17763+ or 11 | ☐ |
+| 2 | Ensure the user account is a **standard user** (not a local admin). The installer does not require elevation. | ☐ |
+| 3 | Verify outbound HTTPS (port 443) is open to `api.openai.com` (or whichever LLM provider the course uses). | ☐ |
+| 4 | Obtain the installer: download `CodeWhaleSetup.exe` from the [latest release](https://github.com/Hmbown/CodeWhale/releases/latest) or from your department mirror. | ☐ |
+| 5 | (Optional) Verify SHA-256 hash matches the published manifest. | ☐ |
+
+---
+
+## Installation
+
+### Option A — Silent install (recommended for imaging / SCCM / Intune)
+
+```powershell
+# Run as admin or via deployment tool
+CodeWhaleSetup.exe /S
+```
+
+The silent installer:
+- Installs to `%LOCALAPPDATA%\Programs\CodeWhale\bin`
+- Adds the bin directory to the **current user** PATH
+- Registers in Windows "Apps & Features" for uninstall
+
+### Option B — Interactive install
+
+1. Double-click `CodeWhaleSetup.exe`.
+2. Accept the license.
+3. Choose the install directory (default is fine for most setups).
+4. Click **Install**.
+
+### Option C — Manual fallback (no installer)
+
+If the NSIS installer is blocked by group policy, install manually:
+
+```powershell
+# 1. Create directory
+$binDir = "$env:LOCALAPPDATA\Programs\CodeWhale\bin"
+New-Item -ItemType Directory -Force -Path $binDir
+
+# 2. Download binaries (adjust URL to your mirror or release tag)
+$tag = (Invoke-RestMethod -Uri "https://api.github.com/repos/Hmbown/CodeWhale/releases/latest").tag_name
+Invoke-WebRequest -Uri "https://github.com/Hmbown/CodeWhale/releases/download/$tag/codewhale-x64.exe"     -OutFile "$binDir\codewhale.exe"
+Invoke-WebRequest -Uri "https://github.com/Hmbown/CodeWhale/releases/download/$tag/codewhale-tui-x64.exe" -OutFile "$binDir\codewhale-tui.exe"
+
+# 3. Add to user PATH (persistent)
+$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if ($currentPath -notlike "*$binDir*") {
+    [Environment]::SetEnvironmentVariable("Path", "$currentPath;$binDir", "User")
+}
+
+# 4. Refresh current session PATH
+$env:Path = [Environment]::GetEnvironmentVariable("Path", "User") + ";" + [Environment]::GetEnvironmentVariable("Path", "Machine")
+```
+
+---
+
+## Post-install verification
+
+Run these on **each machine** (or spot-check a sample):
+
+| # | Command | Expected output | Done? |
+|---|---------|-----------------|-------|
+| 1 | `codewhale --version` | Prints version string | ☐ |
+| 2 | `codewhale doctor` | All checks pass | ☐ |
+| 3 | `codewhale-tui --version` | Prints version string | ☐ |
+
+If `codewhale` is not found, the user may need to open a **new** terminal window for PATH changes to take effect.
+
+---
+
+## API key provisioning
+
+Each student needs an API key. Options:
+
+| Method | Pros | Cons |
+|--------|------|------|
+| **Per-student key** | Individual usage tracking | More key management |
+| **Shared lab key** | Simple to deploy | Harder to audit; rate limits shared |
+
+### Deploying a shared key via environment variable
+
+```powershell
+# Set for current user (persists across reboots)
+[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-...", "User")
+```
+
+Or create a `config.toml` in `%APPDATA%\codewhale\`:
+
+```toml
+[provider]
+api_key = "sk-..."
+base_url = "https://api.openai.com/v1"
+```
+
+### Deploying per-student keys with Intune / GPO
+
+Use a Group Policy Preference or Intune PowerShell script to set the
+`OPENAI_API_KEY` environment variable per user. The variable name depends on
+your LLM provider — see [CONFIGURATION.md](CONFIGURATION.md).
+
+---
+
+## Uninstall
+
+### Silent uninstall
+
+```powershell
+& "$env:LOCALAPPDATA\Programs\CodeWhale\Uninstall.exe" /S
+```
+
+### Manual uninstall (if installer was not used)
+
+```powershell
+$binDir = "$env:LOCALAPPDATA\Programs\CodeWhale\bin"
+Remove-Item -Recurse -Force (Split-Path $binDir)
+
+# Remove from PATH
+$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
+$newPath = ($currentPath -split ";" | Where-Object { $_ -ne $binDir }) -join ";"
+[Environment]::SetEnvironmentVariable("Path", $newPath, "User")
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `codewhale` not found after install | Open a **new** terminal. If still missing, check PATH: `echo $env:Path` |
+| `MISSING_COMPANION_BINARY` | Ensure both `codewhale.exe` and `codewhale-tui.exe` are in the same directory |
+| `TLS handshake` errors | Check proxy settings or use the CNB mirror (see [INSTALL.md](INSTALL.md)) |
+| Antivirus quarantines binaries | Add the install directory to AV exclusions |
+| `codewhale doctor` fails API check | Verify `OPENAI_API_KEY` is set or `config.toml` exists |
+
+---
+
+## Imaging / Golden Image Notes
+
+If building a golden image (WIM/FFU):
+
+1. Install CodeWhale using Option A (silent) or Option C (manual).
+2. Do **not** set API keys in the image — these are per-user/per-student.
+3. The install directory (`%LOCALAPPDATA%\Programs\CodeWhale\bin`) is per-user,
+   so it will be present for the user who installed it. For other users on the
+   same machine, run the installer again or use Option C.
+4. Alternatively, install to a shared location like `C:\Tools\CodeWhale\bin`
+   and add it to the **machine** PATH:
+   ```powershell
+   [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Tools\CodeWhale\bin", "Machine")
+   ```
+
+---
+
+## Quick Reference: All file paths
+
+| Item | Default location |
+|------|-----------------|
+| Binaries | `%LOCALAPPDATA%\Programs\CodeWhale\bin\` |
+| User config | `%APPDATA%\codewhale\config.toml` |
+| Uninstaller | `%LOCALAPPDATA%\Programs\CodeWhale\Uninstall.exe` |
+| PATH entry | `HKCU\Environment\Path` (current user) |
+
+---
+
+*Last updated: 2026-05-25*

docs/INSTALL.md

@@ -290,6 +290,43 @@ Scoop manifests are maintained outside this repository's release workflow and
 can lag GitHub/npm/Cargo releases. Use npm or manual GitHub release downloads
 when you need the newest version immediately.
 
+### Windows NSIS Installer
+
+A standalone NSIS-based installer is available for Windows users who prefer a
+traditional double-click setup (no npm, no Scoop, no Cargo required).
+
+**Download** `CodeWhaleSetup.exe` from the
+[Releases page](https://github.com/Hmbown/CodeWhale/releases/latest).
+
+**Install** by double-clicking the setup executable. The installer:
+
+- Installs `codewhale.exe` and `codewhale-tui.exe` side-by-side into
+  `%LOCALAPPDATA%\Programs\CodeWhale\bin`
+- Adds the install directory to the **current user** `PATH`
+- Registers in Windows **Apps & Features** for easy uninstall
+
+**Silent install** (for IT admins, SCCM, Intune):
+
+```powershell
+CodeWhaleSetup.exe /S
+```
+
+**Build the installer yourself** (requires [NSIS](https://nsis.sourceforge.io)):
+
+```powershell
+cd scripts\installer
+# Place codewhale.exe and codewhale-tui.exe here, then:
+makensis /DVERSION=0.9.0 codewhale.nsi
+```
+
+**Manual fallback** — if the installer is blocked by group policy, see the
+[CLASSROOM_INSTALL.md](CLASSROOM_INSTALL.md) guide for step-by-step PowerShell
+commands.
+
+> **Deploying to a classroom or lab?** See the full
+> [Classroom Install Checklist](CLASSROOM_INSTALL.md) for silent install,
+> API key provisioning, imaging notes, and troubleshooting.
+
 ---
 
 ## 7. Build from source