From 4bc17bbdd3dee2eda4d345698ce1c88ef2a2c314 Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 17:52:35 +0600
Subject: [PATCH 1/9] fix(windows): handle tilde backslash paths and skip POSIX
 live-script test

---
 README.md                          |  6 ++++
 docs/windows-compatibility-plan.md | 46 ++++++++++++++++++++++++++++++
 internal/config/paths.go           | 10 +++++--
 internal/config/paths_test.go      |  5 ++++
 internal/integration/live_test.go  |  4 +++
 5 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 docs/windows-compatibility-plan.md

diff --git a/README.md b/README.md
index 13fd0f56..b3f8b967 100644
--- a/README.md
+++ b/README.md
@@ -1645,6 +1645,12 @@ scripts/live-test.sh --account you@gmail.com --skip groups,keep,calendar-enterpr
 scripts/live-test.sh --client work --account you@company.com
 ```
 
+Windows note: `scripts/live-test.sh` is a POSIX shell script. Run it from Git Bash or WSL.
+
+```powershell
+wsl bash scripts/live-test.sh --fast
+```
+
 Script toggles:
 
 - `--auth all,groups` to re-auth before running
diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
new file mode 100644
index 00000000..f3290c6b
--- /dev/null
+++ b/docs/windows-compatibility-plan.md
@@ -0,0 +1,46 @@
+# Windows Compatibility and Security Hardening Plan
+
+Date started: 2026-03-16
+Branch: windows-compatible
+
+## Goal
+Make the project reliably usable on Windows by identifying and fixing platform-specific assumptions in code, tests, scripts, and docs, while also flagging security risks for open-source distribution.
+
+## Scope
+- Go source under `cmd/` and `internal/`
+- Tests (`*_test.go`)
+- Build/dev scripts and Makefile usage
+- Docs that prescribe non-Windows-only commands without alternatives
+- Dependency and code-level security checks
+
+## Work Plan
+- [x] Baseline repository state captured
+- [x] Automated scan for Unix-specific usage patterns
+- [ ] Run test/build checks on Windows
+- [x] Implement code fixes for Windows compatibility
+- [x] Implement test fixes for Windows compatibility
+- [x] Improve docs with Windows-safe guidance where needed
+- [ ] Security review (deps + obvious code issues)
+- [ ] Final validation (`go test ./...` where feasible)
+- [ ] Summarize findings and residual risks
+
+## Progress Log
+- 2026-03-16: Initialized plan and tracking document.
+- 2026-03-16: Found and fixed `ExpandPath` handling for Windows-style `~\\...` paths.
+- 2026-03-16: Added test coverage for Windows-style home expansion.
+- 2026-03-16: Updated integration live-script test to skip on Windows (POSIX-shell dependency).
+- 2026-03-16: Added Windows guidance for live script execution in `README.md`.
+- 2026-03-16: Attempted `go test ./...` but `go` command is not available in current terminal PATH.
+
+## Findings
+### Windows Compatibility
+- `internal/config/ExpandPath` only supported `~/...`; Windows-style `~\\...` was not expanded.
+- `internal/integration/TestLiveScript` directly executed `scripts/live-test.sh`, which is not directly runnable on Windows shells.
+- Live-test documentation lacked explicit Windows guidance.
+
+### Security
+- Initial static review found no immediate command-injection sinks in touched areas; command invocations are fixed executable names with structured arguments.
+- Full dependency vulnerability scan is pending until `go` tooling is available in the terminal.
+
+## Commits
+- Pending (next step in progress)
diff --git a/internal/config/paths.go b/internal/config/paths.go
index 5b6636ad..2c4d55b6 100644
--- a/internal/config/paths.go
+++ b/internal/config/paths.go
@@ -262,13 +262,19 @@ func ExpandPath(path string) (string, error) {
 		return home, nil
 	}
 
-	if strings.HasPrefix(path, "~/") {
+	if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, "~\\") {
 		home, err := os.UserHomeDir()
 		if err != nil {
 			return "", fmt.Errorf("expand home dir: %w", err)
 		}
 
-		return filepath.Join(home, path[2:]), nil
+		rel := strings.TrimPrefix(path[2:], string(os.PathSeparator))
+		rel = strings.TrimLeft(rel, `/\\`)
+		if rel == "" {
+			return home, nil
+		}
+
+		return filepath.Join(home, rel), nil
 	}
 
 	return path, nil
diff --git a/internal/config/paths_test.go b/internal/config/paths_test.go
index 77429fe0..87fa91d1 100644
--- a/internal/config/paths_test.go
+++ b/internal/config/paths_test.go
@@ -96,6 +96,11 @@ func TestExpandPath(t *testing.T) {
 			input: "~/Downloads/file.txt",
 			want:  filepath.Join(home, "Downloads/file.txt"),
 		},
+		{
+			name:  "tilde with windows-style subpath",
+			input: "~\\Downloads\\file.txt",
+			want:  filepath.Join(home, "Downloads", "file.txt"),
+		},
 		{
 			name:  "absolute path unchanged",
 			input: "/usr/local/bin",
diff --git a/internal/integration/live_test.go b/internal/integration/live_test.go
index 9f688116..999d00e0 100644
--- a/internal/integration/live_test.go
+++ b/internal/integration/live_test.go
@@ -7,6 +7,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"testing"
 	"time"
 )
@@ -15,6 +16,9 @@ func TestLiveScript(t *testing.T) {
 	if os.Getenv("GOG_LIVE") == "" {
 		t.Skip("set GOG_LIVE=1 to run live tests")
 	}
+	if runtime.GOOS == "windows" {
+		t.Skip("scripts/live-test.sh requires a POSIX shell; run from Git Bash/WSL or use non-script integration tests")
+	}
 
 	root := findRepoRoot(t)
 	script := filepath.Join(root, "scripts", "live-test.sh")

From 5dded53fb8848b75b422f8f2106bbdae50e448d4 Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 17:55:32 +0600
Subject: [PATCH 2/9] docs(windows): add PowerShell guidance and update
 compatibility tracker

---
 README.md                          | 7 +++++++
 docs/windows-compatibility-plan.md | 2 ++
 2 files changed, 9 insertions(+)

diff --git a/README.md b/README.md
index b3f8b967..8ed3fff1 100644
--- a/README.md
+++ b/README.md
@@ -1614,6 +1614,13 @@ After cloning, install tools:
 make tools
 ```
 
+Windows (PowerShell) note: the `Makefile` uses POSIX shell commands. If you are not running Git Bash/WSL, use direct Go commands instead:
+
+```powershell
+go build -o .\bin\gog.exe .\cmd\gog
+go test ./...
+```
+
 Pinned tools (installed into `.tools/`):
 
 - Format: `make fmt` (goimports + gofumpt)
diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
index f3290c6b..dc7ac15d 100644
--- a/docs/windows-compatibility-plan.md
+++ b/docs/windows-compatibility-plan.md
@@ -30,6 +30,7 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - 2026-03-16: Added test coverage for Windows-style home expansion.
 - 2026-03-16: Updated integration live-script test to skip on Windows (POSIX-shell dependency).
 - 2026-03-16: Added Windows guidance for live script execution in `README.md`.
+- 2026-03-16: Added Windows PowerShell development fallback commands in `README.md` for environments without POSIX shell tooling.
 - 2026-03-16: Attempted `go test ./...` but `go` command is not available in current terminal PATH.
 
 ## Findings
@@ -40,6 +41,7 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 
 ### Security
 - Initial static review found no immediate command-injection sinks in touched areas; command invocations are fixed executable names with structured arguments.
+- `http://127.0.0.1` OAuth callback URLs are used intentionally for localhost redirect handling.
 - Full dependency vulnerability scan is pending until `go` tooling is available in the terminal.
 
 ## Commits

From 4503c799a5c2607acada388564987df1b43885ca Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 17:57:20 +0600
Subject: [PATCH 3/9] docs(plan): record security review and residual windows
 risks

---
 docs/windows-compatibility-plan.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
index dc7ac15d..fb9bc29b 100644
--- a/docs/windows-compatibility-plan.md
+++ b/docs/windows-compatibility-plan.md
@@ -20,9 +20,9 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - [x] Implement code fixes for Windows compatibility
 - [x] Implement test fixes for Windows compatibility
 - [x] Improve docs with Windows-safe guidance where needed
-- [ ] Security review (deps + obvious code issues)
+- [x] Security review (deps + obvious code issues)
 - [ ] Final validation (`go test ./...` where feasible)
-- [ ] Summarize findings and residual risks
+- [x] Summarize findings and residual risks
 
 ## Progress Log
 - 2026-03-16: Initialized plan and tracking document.
@@ -38,11 +38,14 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - `internal/config/ExpandPath` only supported `~/...`; Windows-style `~\\...` was not expanded.
 - `internal/integration/TestLiveScript` directly executed `scripts/live-test.sh`, which is not directly runnable on Windows shells.
 - Live-test documentation lacked explicit Windows guidance.
+- Residual: `Makefile` remains POSIX-shell oriented (`SHELL := /bin/bash`), so native PowerShell-only workflows should use direct `go build` / `go test` commands (documented in README).
 
 ### Security
 - Initial static review found no immediate command-injection sinks in touched areas; command invocations are fixed executable names with structured arguments.
 - `http://127.0.0.1` OAuth callback URLs are used intentionally for localhost redirect handling.
-- Full dependency vulnerability scan is pending until `go` tooling is available in the terminal.
+- `gmail watch serve` requires authentication safeguards (`--verify-oidc` or `--token`) when binding to non-loopback addresses, reducing accidental exposure risk.
+- Full dependency vulnerability scan is still pending until `go` tooling is available in the terminal.
 
 ## Commits
-- Pending (next step in progress)
+- `4bc17bb` fix(windows): handle tilde backslash paths and skip POSIX live-script test
+- `5dded53` docs(windows): add PowerShell guidance and update compatibility tracker

From aa2b075f52ee1d8616764592917a301d80f209f3 Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 18:28:50 +0600
Subject: [PATCH 4/9] feat(windows): add PowerShell live-test wrapper and use
 it in integration

---
 README.md                          |  8 +++++-
 docs/windows-compatibility-plan.md |  4 +++
 internal/integration/live_test.go  | 15 +++++++++---
 scripts/live-test.ps1              | 39 ++++++++++++++++++++++++++++++
 4 files changed, 61 insertions(+), 5 deletions(-)
 create mode 100644 scripts/live-test.ps1

diff --git a/README.md b/README.md
index 8ed3fff1..363d8dfb 100644
--- a/README.md
+++ b/README.md
@@ -1652,7 +1652,13 @@ scripts/live-test.sh --account you@gmail.com --skip groups,keep,calendar-enterpr
 scripts/live-test.sh --client work --account you@company.com
 ```
 
-Windows note: `scripts/live-test.sh` is a POSIX shell script. Run it from Git Bash or WSL.
+Windows note: use the PowerShell wrapper (it invokes Git Bash when available):
+
+```powershell
+.\scripts\live-test.ps1 --fast
+```
+
+If you prefer WSL directly:
 
 ```powershell
 wsl bash scripts/live-test.sh --fast
diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
index fb9bc29b..83b205fe 100644
--- a/docs/windows-compatibility-plan.md
+++ b/docs/windows-compatibility-plan.md
@@ -31,6 +31,8 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - 2026-03-16: Updated integration live-script test to skip on Windows (POSIX-shell dependency).
 - 2026-03-16: Added Windows guidance for live script execution in `README.md`.
 - 2026-03-16: Added Windows PowerShell development fallback commands in `README.md` for environments without POSIX shell tooling.
+- 2026-03-16: Added `scripts/live-test.ps1` wrapper so live CLI smoke tests can be launched from PowerShell.
+- 2026-03-16: Updated integration `TestLiveScript` to use the PowerShell wrapper on Windows when available.
 - 2026-03-16: Attempted `go test ./...` but `go` command is not available in current terminal PATH.
 
 ## Findings
@@ -38,6 +40,8 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - `internal/config/ExpandPath` only supported `~/...`; Windows-style `~\\...` was not expanded.
 - `internal/integration/TestLiveScript` directly executed `scripts/live-test.sh`, which is not directly runnable on Windows shells.
 - Live-test documentation lacked explicit Windows guidance.
+- Added PowerShell wrapper for live test script execution from Windows shells.
+- Residual: live tests still require a POSIX shell runtime (Git Bash/WSL) under the hood.
 - Residual: `Makefile` remains POSIX-shell oriented (`SHELL := /bin/bash`), so native PowerShell-only workflows should use direct `go build` / `go test` commands (documented in README).
 
 ### Security
diff --git a/internal/integration/live_test.go b/internal/integration/live_test.go
index 999d00e0..f677a6f1 100644
--- a/internal/integration/live_test.go
+++ b/internal/integration/live_test.go
@@ -16,12 +16,19 @@ func TestLiveScript(t *testing.T) {
 	if os.Getenv("GOG_LIVE") == "" {
 		t.Skip("set GOG_LIVE=1 to run live tests")
 	}
-	if runtime.GOOS == "windows" {
-		t.Skip("scripts/live-test.sh requires a POSIX shell; run from Git Bash/WSL or use non-script integration tests")
-	}
 
 	root := findRepoRoot(t)
 	script := filepath.Join(root, "scripts", "live-test.sh")
+	cmdName := script
+	cmdArgs := []string{}
+	if runtime.GOOS == "windows" {
+		script = filepath.Join(root, "scripts", "live-test.ps1")
+		if _, err := os.Stat(script); err != nil {
+			t.Skipf("windows live test wrapper not found at %s", script)
+		}
+		cmdName = "powershell"
+		cmdArgs = []string{"-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script}
+	}
 
 	args := []string{}
 	if os.Getenv("GOG_LIVE_FAST") != "" {
@@ -46,7 +53,7 @@ func TestLiveScript(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Minute)
 	defer cancel()
 
-	cmd := exec.CommandContext(ctx, script, args...)
+	cmd := exec.CommandContext(ctx, cmdName, append(cmdArgs, args...)...)
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
 	cmd.Env = os.Environ()
diff --git a/scripts/live-test.ps1 b/scripts/live-test.ps1
new file mode 100644
index 00000000..ba7c9625
--- /dev/null
+++ b/scripts/live-test.ps1
@@ -0,0 +1,39 @@
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$Args
+)
+
+$ErrorActionPreference = "Stop"
+
+$scriptPath = Join-Path $PSScriptRoot "live-test.sh"
+if (-not (Test-Path $scriptPath)) {
+    Write-Error "Could not find live-test.sh at $scriptPath"
+    exit 1
+}
+
+$bashCandidates = @()
+
+$bashCommand = Get-Command bash -ErrorAction SilentlyContinue
+if ($bashCommand) {
+    $bashCandidates += $bashCommand.Source
+}
+
+$gitBash = "C:\Program Files\Git\bin\bash.exe"
+if (Test-Path $gitBash) {
+    $bashCandidates += $gitBash
+}
+
+$bashCandidates = $bashCandidates | Select-Object -Unique
+
+if ($bashCandidates.Count -eq 0) {
+    Write-Error "No bash executable found. Install Git for Windows (Git Bash) or run scripts/live-test.sh in WSL."
+    exit 1
+}
+
+$bash = $bashCandidates[0]
+& $bash $scriptPath @Args
+$exitCode = $LASTEXITCODE
+if ($null -eq $exitCode) {
+    $exitCode = 0
+}
+exit $exitCode

From 65d0203149d88415f6f260589b909390db97455f Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 18:30:10 +0600
Subject: [PATCH 5/9] docs(plan): update latest windows progress and PATH
 blocker

---
 docs/windows-compatibility-plan.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
index 83b205fe..a44ad644 100644
--- a/docs/windows-compatibility-plan.md
+++ b/docs/windows-compatibility-plan.md
@@ -34,11 +34,12 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - 2026-03-16: Added `scripts/live-test.ps1` wrapper so live CLI smoke tests can be launched from PowerShell.
 - 2026-03-16: Updated integration `TestLiveScript` to use the PowerShell wrapper on Windows when available.
 - 2026-03-16: Attempted `go test ./...` but `go` command is not available in current terminal PATH.
+- 2026-03-16: Confirmed terminal PATH is missing Go bin directories (`C:\\Program Files\\Go\\bin` or equivalent), so test/CVE tooling remains blocked in this environment.
 
 ## Findings
 ### Windows Compatibility
 - `internal/config/ExpandPath` only supported `~/...`; Windows-style `~\\...` was not expanded.
-- `internal/integration/TestLiveScript` directly executed `scripts/live-test.sh`, which is not directly runnable on Windows shells.
+- `internal/integration/TestLiveScript` originally executed `scripts/live-test.sh` directly; updated to use `scripts/live-test.ps1` via PowerShell on Windows.
 - Live-test documentation lacked explicit Windows guidance.
 - Added PowerShell wrapper for live test script execution from Windows shells.
 - Residual: live tests still require a POSIX shell runtime (Git Bash/WSL) under the hood.
@@ -53,3 +54,5 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 ## Commits
 - `4bc17bb` fix(windows): handle tilde backslash paths and skip POSIX live-script test
 - `5dded53` docs(windows): add PowerShell guidance and update compatibility tracker
+- `4503c79` docs(plan): record security review and residual windows risks
+- `aa2b075` feat(windows): add PowerShell live-test wrapper and use it in integration

From 9632c2c6af49595efb3b7d4166ed24ee908eba20 Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 18:40:01 +0600
Subject: [PATCH 6/9] test(windows): stabilize ExpandPath home env on Windows

---
 internal/config/paths_test.go | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/internal/config/paths_test.go b/internal/config/paths_test.go
index 87fa91d1..d8e464e9 100644
--- a/internal/config/paths_test.go
+++ b/internal/config/paths_test.go
@@ -74,6 +74,11 @@ func TestPaths_CreateDirs(t *testing.T) {
 func TestExpandPath(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	if vol := filepath.VolumeName(home); vol != "" {
+		t.Setenv("HOMEDRIVE", vol)
+		t.Setenv("HOMEPATH", strings.TrimPrefix(home, vol))
+	}
 
 	tests := []struct {
 		name    string

From 3415538d48d53d0b6c418a1319a037a2c97fd1e2 Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 18:40:27 +0600
Subject: [PATCH 7/9] docs(plan): mark windows validation and vuln scan
 complete

---
 docs/windows-compatibility-plan.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
index a44ad644..743024f7 100644
--- a/docs/windows-compatibility-plan.md
+++ b/docs/windows-compatibility-plan.md
@@ -21,7 +21,7 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - [x] Implement test fixes for Windows compatibility
 - [x] Improve docs with Windows-safe guidance where needed
 - [x] Security review (deps + obvious code issues)
-- [ ] Final validation (`go test ./...` where feasible)
+- [x] Final validation (`go test ./...` where feasible)
 - [x] Summarize findings and residual risks
 
 ## Progress Log
@@ -35,6 +35,10 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - 2026-03-16: Updated integration `TestLiveScript` to use the PowerShell wrapper on Windows when available.
 - 2026-03-16: Attempted `go test ./...` but `go` command is not available in current terminal PATH.
 - 2026-03-16: Confirmed terminal PATH is missing Go bin directories (`C:\\Program Files\\Go\\bin` or equivalent), so test/CVE tooling remains blocked in this environment.
+- 2026-03-16: User provided Go path (`C:\\Program Files (x86)\\Go\\bin`), enabling final validation.
+- 2026-03-16: Full test suite passed on Windows via explicit go executable path.
+- 2026-03-16: `govulncheck` (run via `go run golang.org/x/vuln/cmd/govulncheck@latest ./...`) reported no known vulnerabilities.
+- 2026-03-16: Fixed a Windows-only test setup issue by setting `USERPROFILE`/`HOMEDRIVE`/`HOMEPATH` in `TestExpandPath`.
 
 ## Findings
 ### Windows Compatibility
@@ -49,10 +53,12 @@ Make the project reliably usable on Windows by identifying and fixing platform-s
 - Initial static review found no immediate command-injection sinks in touched areas; command invocations are fixed executable names with structured arguments.
 - `http://127.0.0.1` OAuth callback URLs are used intentionally for localhost redirect handling.
 - `gmail watch serve` requires authentication safeguards (`--verify-oidc` or `--token`) when binding to non-loopback addresses, reducing accidental exposure risk.
-- Full dependency vulnerability scan is still pending until `go` tooling is available in the terminal.
+- `govulncheck` returned: no known vulnerabilities found.
 
 ## Commits
 - `4bc17bb` fix(windows): handle tilde backslash paths and skip POSIX live-script test
 - `5dded53` docs(windows): add PowerShell guidance and update compatibility tracker
 - `4503c79` docs(plan): record security review and residual windows risks
 - `aa2b075` feat(windows): add PowerShell live-test wrapper and use it in integration
+- `65d0203` docs(plan): update latest windows progress and PATH blocker
+- `9632c2c` test(windows): stabilize ExpandPath home env on Windows

From a55d27988bb4cfae1db9d6189675f712ff16254e Mon Sep 17 00:00:00 2001
From: gagradebnath <salemdebnath@gmail.com>
Date: Mon, 16 Mar 2026 19:16:23 +0600
Subject: [PATCH 8/9] docs(readme): add Windows-native usage and compatibility
 status

---
 README.md               | 33 +++++++++++++++++++++++++++++++++
 docs/refactor/README.md |  5 +++++
 2 files changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 363d8dfb..eb684883 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,12 @@ cd gogcli
 make
 ```
 
+Windows (PowerShell, no Make/bash required):
+
+```powershell
+go build -o .\bin\gog.exe .\cmd\gog
+```
+
 Run:
 
 ```bash
@@ -107,6 +113,12 @@ Before adding an account, create OAuth2 credentials from Google Cloud Console:
 gog auth credentials ~/Downloads/client_secret_....json
 ```
 
+Windows PowerShell:
+
+```powershell
+.\bin\gog.exe auth credentials "C:\path\to\client_secret_....json"
+```
+
 For multiple OAuth clients/projects:
 
 ```bash
@@ -120,6 +132,12 @@ gog auth credentials list
 gog auth add you@gmail.com
 ```
 
+Windows PowerShell:
+
+```powershell
+.\bin\gog.exe auth add you@gmail.com
+```
+
 This will open a browser window for OAuth authorization. The refresh token is stored securely in your system keychain.
 
 Headless / remote server flows (no browser on the server):
@@ -175,6 +193,13 @@ export GOG_ACCOUNT=you@gmail.com
 gog gmail labels list
 ```
 
+Windows PowerShell:
+
+```powershell
+$env:GOG_ACCOUNT = "you@gmail.com"
+.\bin\gog.exe gmail labels list
+```
+
 ## Authentication & Secrets
 
 ### Accounts and tokens
@@ -557,6 +582,7 @@ Options:
 - **Never commit OAuth client credentials** to version control
 - Store client credentials outside your project directory
 - Use different OAuth clients for development and production
+- Rotate the OAuth client secret immediately if it is ever shared or exposed
 - Re-authorize with `--force-consent` if you suspect token compromise
 - Remove unused accounts with `gog auth remove <email>`
 
@@ -1677,6 +1703,13 @@ Go test wrapper (opt-in):
 GOG_LIVE=1 go test -tags=integration ./internal/integration -run Live
 ```
 
+Windows PowerShell:
+
+```powershell
+$env:GOG_LIVE = "1"
+go test -tags=integration ./internal/integration -run Live
+```
+
 Optional env:
 - `GOG_LIVE_FAST=1`
 - `GOG_LIVE_SKIP=groups,keep`
diff --git a/docs/refactor/README.md b/docs/refactor/README.md
index 504ac0b8..0169d370 100644
--- a/docs/refactor/README.md
+++ b/docs/refactor/README.md
@@ -12,6 +12,11 @@ Shipped (today)
 - `exports.md`: Drive-backed export command pattern (`docs|slides|sheets`).
 - `output.md`: shared table + paging helpers.
 - `templates.md`: googleauth HTML templates via `//go:embed`.
+- Windows compatibility pass:
+  - `config.ExpandPath` handles both `~/...` and `~\\...`.
+  - integration live tests support Windows via `scripts/live-test.ps1` wrapper.
+  - README now documents Windows-native build/auth/live-test flows.
+  - full `go test ./...` and `govulncheck` validation completed on Windows.
 
 Backlog / next wins
 

From 2e9ae76a8fc3ac925f6984dc0db4c6f0e7a9f0db Mon Sep 17 00:00:00 2001
From: Ghagra Salem Debnath <51057167+gagradebnath@users.noreply.github.com>
Date: Mon, 16 Mar 2026 19:38:09 +0600
Subject: [PATCH 9/9] Delete docs/windows-compatibility-plan.md

---
 docs/windows-compatibility-plan.md | 64 ------------------------------
 1 file changed, 64 deletions(-)
 delete mode 100644 docs/windows-compatibility-plan.md

diff --git a/docs/windows-compatibility-plan.md b/docs/windows-compatibility-plan.md
deleted file mode 100644
index 743024f7..00000000
--- a/docs/windows-compatibility-plan.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Windows Compatibility and Security Hardening Plan
-
-Date started: 2026-03-16
-Branch: windows-compatible
-
-## Goal
-Make the project reliably usable on Windows by identifying and fixing platform-specific assumptions in code, tests, scripts, and docs, while also flagging security risks for open-source distribution.
-
-## Scope
-- Go source under `cmd/` and `internal/`
-- Tests (`*_test.go`)
-- Build/dev scripts and Makefile usage
-- Docs that prescribe non-Windows-only commands without alternatives
-- Dependency and code-level security checks
-
-## Work Plan
-- [x] Baseline repository state captured
-- [x] Automated scan for Unix-specific usage patterns
-- [ ] Run test/build checks on Windows
-- [x] Implement code fixes for Windows compatibility
-- [x] Implement test fixes for Windows compatibility
-- [x] Improve docs with Windows-safe guidance where needed
-- [x] Security review (deps + obvious code issues)
-- [x] Final validation (`go test ./...` where feasible)
-- [x] Summarize findings and residual risks
-
-## Progress Log
-- 2026-03-16: Initialized plan and tracking document.
-- 2026-03-16: Found and fixed `ExpandPath` handling for Windows-style `~\\...` paths.
-- 2026-03-16: Added test coverage for Windows-style home expansion.
-- 2026-03-16: Updated integration live-script test to skip on Windows (POSIX-shell dependency).
-- 2026-03-16: Added Windows guidance for live script execution in `README.md`.
-- 2026-03-16: Added Windows PowerShell development fallback commands in `README.md` for environments without POSIX shell tooling.
-- 2026-03-16: Added `scripts/live-test.ps1` wrapper so live CLI smoke tests can be launched from PowerShell.
-- 2026-03-16: Updated integration `TestLiveScript` to use the PowerShell wrapper on Windows when available.
-- 2026-03-16: Attempted `go test ./...` but `go` command is not available in current terminal PATH.
-- 2026-03-16: Confirmed terminal PATH is missing Go bin directories (`C:\\Program Files\\Go\\bin` or equivalent), so test/CVE tooling remains blocked in this environment.
-- 2026-03-16: User provided Go path (`C:\\Program Files (x86)\\Go\\bin`), enabling final validation.
-- 2026-03-16: Full test suite passed on Windows via explicit go executable path.
-- 2026-03-16: `govulncheck` (run via `go run golang.org/x/vuln/cmd/govulncheck@latest ./...`) reported no known vulnerabilities.
-- 2026-03-16: Fixed a Windows-only test setup issue by setting `USERPROFILE`/`HOMEDRIVE`/`HOMEPATH` in `TestExpandPath`.
-
-## Findings
-### Windows Compatibility
-- `internal/config/ExpandPath` only supported `~/...`; Windows-style `~\\...` was not expanded.
-- `internal/integration/TestLiveScript` originally executed `scripts/live-test.sh` directly; updated to use `scripts/live-test.ps1` via PowerShell on Windows.
-- Live-test documentation lacked explicit Windows guidance.
-- Added PowerShell wrapper for live test script execution from Windows shells.
-- Residual: live tests still require a POSIX shell runtime (Git Bash/WSL) under the hood.
-- Residual: `Makefile` remains POSIX-shell oriented (`SHELL := /bin/bash`), so native PowerShell-only workflows should use direct `go build` / `go test` commands (documented in README).
-
-### Security
-- Initial static review found no immediate command-injection sinks in touched areas; command invocations are fixed executable names with structured arguments.
-- `http://127.0.0.1` OAuth callback URLs are used intentionally for localhost redirect handling.
-- `gmail watch serve` requires authentication safeguards (`--verify-oidc` or `--token`) when binding to non-loopback addresses, reducing accidental exposure risk.
-- `govulncheck` returned: no known vulnerabilities found.
-
-## Commits
-- `4bc17bb` fix(windows): handle tilde backslash paths and skip POSIX live-script test
-- `5dded53` docs(windows): add PowerShell guidance and update compatibility tracker
-- `4503c79` docs(plan): record security review and residual windows risks
-- `aa2b075` feat(windows): add PowerShell live-test wrapper and use it in integration
-- `65d0203` docs(plan): update latest windows progress and PATH blocker
-- `9632c2c` test(windows): stabilize ExpandPath home env on Windows