[AB#557] docs: Add optional cross-platform testing with nektos/act

Added instructions for developers who want to run cross-platform CI tests
locally using nektos/act before pushing to GitHub.

Also fixed PATH separator detection in prependToPath() to handle cross-
platform test scenarios where Unix-style paths (with :) are tested on
Windows runners (which default to ; separator).

Changes:
- Added nektos/act installation and usage guide to agent instructions
- Updated when-to-use guidance to cover all OS-specific code, not just shims
- Fixed prependToPath() to detect separator from existing PATH value
- Updated repo memory with cross-platform testing guidance

This is optional - CI always runs full cross-platform tests automatically.

Author: ChronosMasterOfAllTime

.github/copilot-instructions.md

@@ -315,6 +315,49 @@ Before submitting a PR:
 4. ✅ No race conditions: `go test -race ./...` (done by `make test`)
 5. ✅ Windows compatibility validated (for shim/path/shell changes)
 
+### Local Cross-Platform Testing (Optional)
+
+**For developers who want to test against Windows/other platforms locally**, you can use [nektos/act](https://github.com/nektos/act) to run GitHub Actions workflows on your machine:
+
+**Installation**:
+```bash
+# macOS
+brew install act
+
+# Linux
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows
+choco install act-cli
+```
+
+**Usage**:
+```bash
+# Run all CI tests (includes Windows)
+act
+
+# Run specific job (e.g., Windows tests only)
+act -j test-windows
+
+# Run with specific platform
+act --platform ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Dry run to see what would execute
+act --dryrun
+```
+
+**Note**: 
+- Windows containers require Docker Desktop with Windows containers enabled
+- For Windows-specific tests, you may need larger runners: `act -P windows-latest=-self-hosted`
+- CI will always run full cross-platform tests automatically when you push
+
+**When to use local cross-platform testing**:
+- ✅ Testing platform-specific code (Windows batch files, Unix shell scripts, path handling)
+- ✅ Verifying OS-specific features (environment variables, file permissions, executables)
+- ✅ Testing changes to shims, install scripts, or platform detection
+- ✅ Debugging cross-platform CI failures locally
+- ❌ Not needed for most changes (CI handles it automatically)
+
 ### Common Testing Commands
 
 ```bash

AGENTS.md

@@ -220,6 +220,49 @@ Before submitting:
 4. ✅ Windows compatibility validated (if applicable)
 5. ✅ Coverage maintained or improved
 
+### Local Cross-Platform Testing (Optional)
+
+**For developers who want to test against Windows/other platforms locally**, you can use [nektos/act](https://github.com/nektos/act) to run GitHub Actions workflows on your machine:
+
+**Installation**:
+```bash
+# macOS
+brew install act
+
+# Linux
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows
+choco install act-cli
+```
+
+**Usage**:
+```bash
+# Run all CI tests (includes Windows)
+act
+
+# Run specific job (e.g., Windows tests only)
+act -j test-windows
+
+# Run with specific platform
+act --platform ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Dry run to see what would execute
+act --dryrun
+```
+
+**Note**: 
+- Windows containers require Docker Desktop with Windows containers enabled
+- For Windows-specific tests, you may need larger runners: `act -P windows-latest=-self-hosted`
+- CI will always run full cross-platform tests automatically when you push
+
+**When to use local cross-platform testing**:
+- ✅ Testing platform-specific code (Windows batch files, Unix shell scripts, path handling)
+- ✅ Verifying OS-specific features (environment variables, file permissions, executables)
+- ✅ Testing changes to shims, install scripts, or platform detection
+- ✅ Debugging cross-platform CI failures locally
+- ❌ Not needed for most changes (CI handles it automatically)
+
 ### Quick Commands
 
 ```bash

cmd/shims/exec.go

@@ -428,7 +428,17 @@ func prependToPath(env []string, dir string) []string {
 	if idx, actualKey := findEnvVar(env, "PATH"); idx != -1 {
 		// Found PATH, extract current value and prepend new directory
 		currentPath := env[idx][len(actualKey)+1:] // +1 for the "=" sign
-		newPath := dir + string(os.PathListSeparator) + currentPath
+		
+		// Detect separator from existing PATH to handle cross-platform scenarios
+		// (e.g., testing Unix-style paths on Windows)
+		sep := string(os.PathListSeparator) // default to OS separator
+		if strings.Contains(currentPath, ";") {
+			sep = ";"
+		} else if strings.Contains(currentPath, ":") {
+			sep = ":"
+		}
+		
+		newPath := dir + sep + currentPath
 		// Preserve original key casing (e.g., "Path" on Windows, "PATH" on Unix)
 		env[idx] = actualKey + "=" + newPath
 		return env