From 3cd5400695a8ea1c85bb48f6086b046becfe5ed4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 20:37:18 +0000
Subject: [PATCH 1/2] Initial plan


From efc3e3a8e004147b1c7eb0a0c0f5fd3ba4a40b40 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 20:38:49 +0000
Subject: [PATCH 2/2] chore: add .github/copilot-instructions.md

Co-authored-by: GoodOlClint <151449+GoodOlClint@users.noreply.github.com>
Agent-Logs-Url: https://github.com/GoodOlClint/PSProxmoxVE/sessions/45c5e8bb-c3e5-461c-9064-6cdafab4daa0
---
 .github/copilot-instructions.md | 78 +++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..d735989
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,78 @@
+# PSProxmoxVE — Copilot Instructions
+
+## Project Overview
+
+C# binary PowerShell module for managing Proxmox VE (PVE) infrastructure. Two projects:
+- `src/PSProxmoxVE/` — Cmdlets and module surface (targets `netstandard2.0`)
+- `src/PSProxmoxVE.Core/` — Services, models, HTTP client (targets `netstandard2.0`)
+
+Tests: xUnit (`tests/PSProxmoxVE.Core.Tests/`) and Pester 5 (`tests/PSProxmoxVE.Tests/`).
+
+## Development Workflow
+
+**All changes go through pull requests.** The `main` branch has branch protection enabled
+(required build checks, required review, admin enforced). Never push directly to main.
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages
+(e.g. `feat: add new cmdlet`, `fix: handle null node name`, `chore: update deps`).
+
+### Build & test
+
+```bash
+# Build
+dotnet build PSProxmoxVE.sln
+
+# xUnit tests
+dotnet test tests/PSProxmoxVE.Core.Tests/
+
+# Pester tests (requires pwsh)
+pwsh -Command "Invoke-Pester tests/PSProxmoxVE.Tests/ -Output Detailed"
+```
+
+A Docker-based dev container replicates the full CI setup locally:
+
+```powershell
+./tests/dev.ps1              # Open pwsh shell in dev container
+./tests/dev.ps1 build        # Build the module
+./tests/dev.ps1 test         # Run unit tests
+./tests/dev.ps1 integration  # Provision nested PVE, run integration tests, cleanup (x86 only)
+```
+
+## Key Coding Conventions
+
+### Cmdlet rules
+- All cmdlets use the `Pve` noun prefix (e.g. `Get-PveVm`, `New-PveSnapshot`).
+- All cmdlet classes must be `sealed`.
+- All cmdlets must have an `[OutputType(typeof(...))]` attribute.
+- Destructive cmdlets (`Remove-*`, `Stop-*`, `Reset-*`, `Restart-*`, `Suspend-*`, restore ops) must set `ConfirmImpact = ConfirmImpact.High`.
+- Use verb class constants — `VerbsCommon.Get`, not the string literal `"Get"`.
+
+### Parameters
+- `VmId` parameters: `[ValidateRange(100, 999999999)]`; use `int?` (nullable) when optional.
+- Passwords must use `SecureString`, never plain `string`. Extract with `Marshal.SecureStringToGlobalAllocUnicode` inside a `try/finally` that calls `Marshal.ZeroFreeGlobalAllocUnicode`.
+
+### URL paths
+- All user-supplied or dynamic values interpolated into API URL paths must be wrapped in `Uri.EscapeDataString()`.
+
+### Task polling
+- Always use `TaskService.WaitForTask(upid, session, TimeoutSeconds, this)`.
+- Never implement inline `while (true)` / `do/while` polling loops in cmdlet files.
+
+### JSON serialization
+- Use only `Newtonsoft.Json` (`[JsonProperty]`). Do **not** add `System.Text.Json` (`[JsonPropertyName]`) attributes.
+
+### Error handling
+- No bare `catch { }` or `catch (Exception) { }` blocks.
+- Use a specific exception type (`catch (PveApiException ex)`) or a filtered catch with a `when` clause that excludes fatal exceptions.
+
+### Framework targeting
+- Publishable projects (`PSProxmoxVE`, `PSProxmoxVE.Core`): `netstandard2.0`.
+- Test projects: `net10.0` + `net48`.
+
+## Key Reference Files
+
+Before writing new code, read these files to understand established patterns and open issues:
+
+- [`DECISIONS.md`](../DECISIONS.md) — architectural decisions and anti-patterns that must not be reintroduced.
+- [`docs/review/findings.json`](../docs/review/findings.json) — stable findings database (IDs F001… are permanent; resolved findings are marked, never deleted).
+- [`docs/review/REVIEW_REPORT.md`](../docs/review/REVIEW_REPORT.md) — latest full review report.