Add Codex repo guidance and skills

.codex/README.md

@@ -0,0 +1,30 @@
+# Codex Setup
+
+This directory contains repo-local Codex guidance for `cgfixit/sccm-veeam-proxy-patching`.
+
+## What This Repo Is
+
+A PowerShell 5.1-compatible maintenance helper for Veeam Backup & Replication VMware proxies during SCCM/ConfigMgr patching windows. The script disables selected VBR proxies, drains active backup tasks, remotely stops Veeam services, then starts services and re-enables proxies after patching.
+
+## First Files To Read
+
+- `AGENTS.md`: repo rules, validation commands, and safety posture.
+- `README.md`: operator runbook, SCCM integration, requirements, and exit codes.
+- `SECURITY.md`: vulnerability reporting and WinRM/service-account guidance.
+- `sccmpatch.ps1`: production script.
+- `tests/sccmpatch.Tests.ps1`: static Pester coverage.
+
+## Skills
+
+- `.codex/skills/code-optimizer/SKILL.md`
+- `.codex/skills/proxy-maintenance-safety/SKILL.md`
+- `.codex/skills/pester-validation/SKILL.md`
+- `.codex/skills/docs-runbook-sync/SKILL.md`
+
+Use the smallest skill that matches the work. Most changes should need only `code-optimizer` or `pester-validation`.
+
+## Non-Goals
+
+- No live Veeam, WinRM, SCCM, or proxy operations during normal Codex validation.
+- No new frameworks or dependencies for this one-script repo unless there is a concrete failing check that requires one.
+- No broad rewrite of `sccmpatch.ps1` without a specific defect, measurable risk, or requested refactor.

.codex/instructions.md

@@ -0,0 +1,8 @@
+# Codex Runtime Instructions
+
+- Start with `AGENTS.md`; it is the repo contract.
+- Before editing behavior, read the full `sccmpatch.ps1` flow and the matching tests.
+- Default validation is static: parser check, Pester, and PSScriptAnalyzer when available.
+- Never use a live proxy, VBR host, SCCM target, or WinRM command as a smoke test unless the user explicitly requests a live operational run.
+- Keep production script changes PowerShell 5.1-compatible.
+- Keep SCCM exit codes and README documentation in sync.

.codex/skills/code-optimizer/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: code-optimizer
+description: Optimize sccmpatch.ps1 while preserving Veeam proxy safety, SCCM exit codes, PowerShell 5.1 compatibility, and the repo validation path.
+---
+
+# Code Optimizer
+
+Use this skill for focused optimization or refactoring of `sccmpatch.ps1`.
+
+## Rules
+
+- Read `AGENTS.md`, `sccmpatch.ps1`, `tests/sccmpatch.Tests.ps1`, and the relevant README section first.
+- Optimize one concrete issue at a time: duplicated logic, fragile null handling, slow polling, unclear error handling, or documentation drift.
+- Preserve the SCCM exit-code contract unless tests and README change in the same PR.
+- Preserve PowerShell 5.1 compatibility in production code.
+- Do not add dependencies for simple parsing, logging, or validation.
+- Do not replace static validation with live Veeam or WinRM testing.
+
+## Workflow
+
+1. State the narrow target and why it matters for production survivability.
+2. Make the smallest code change that fixes the target.
+3. Add or update one Pester/static assertion when behavior or contracts change.
+4. Update README only when parameters, exit codes, operator steps, or failure modes change.
+5. Run the parser check and Pester; run PSScriptAnalyzer if available.
+
+## Validation
+
+```powershell
+pwsh -NoLogo -NoProfile -Command "$errors = $null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path './sccmpatch.ps1'), [ref]$null, [ref]$errors); if ($errors) { $errors | Format-List; exit 1 }"
+pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests -Output Detailed"
+```

.codex/skills/docs-runbook-sync/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: docs-runbook-sync
+description: Keep README, SECURITY, tests, and sccmpatch.ps1 aligned for SCCM/Veeam operator guidance, parameters, logs, and exit codes.
+---
+
+# Docs Runbook Sync
+
+Use this skill when script behavior, operator steps, parameters, logging, or exit codes change.
+
+## Sync Points
+
+- `README.md` must describe the current parameters, defaults, SCCM success/failure codes, and Pre/Post sequence.
+- `SECURITY.md` must stay accurate for WinRM, service-account, execution-policy, and elevated-operation guidance.
+- `tests/sccmpatch.Tests.ps1` must cover documented exit codes and key static safety guards.
+- `sccmpatch.ps1` header comments should not contradict README operator guidance.
+
+## Workflow
+
+1. Compare `sccmpatch.ps1` parameters and exits against README tables.
+2. Compare high-risk operational behavior against SECURITY guidance.
+3. Update the smallest set of docs/tests needed to remove drift.
+4. Run parser and Pester checks when tests or script contracts change.
+
+## Do Not
+
+- Add marketing copy.
+- Add unsupported live-run claims.
+- Document operator steps that the script does not actually implement.

.codex/skills/pester-validation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pester-validation
+description: Run and interpret the repo's PowerShell parser, Pester, PSScriptAnalyzer, and GitHub Actions validation for sccmpatch.ps1 changes.
+---
+
+# Pester Validation
+
+Use this skill when validating edits or diagnosing failed checks.
+
+## Local Checks
+
+Run the parser check first because it is cheap and catches syntax regressions:
+
+```powershell
+pwsh -NoLogo -NoProfile -Command "$errors = $null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path './sccmpatch.ps1'), [ref]$null, [ref]$errors); if ($errors) { $errors | Format-List; exit 1 }"
+```
+
+Run Pester next:
+
+```powershell
+pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests -Output Detailed"
+```
+
+If installed locally, run analyzer:
+
+```powershell
+pwsh -NoLogo -NoProfile -Command "Invoke-ScriptAnalyzer -Path . -Recurse"
+```
+
+## CI Checks
+
+Expected workflows:
+
+- `Pester Tests`
+- `PSScriptAnalyzer`
+- `CodeQL Advanced`
+- `Dependency review` on pull requests
+
+Use GitHub Actions logs for failures; do not infer root cause from workflow names alone.
+
+## Failure Handling
+
+- Parser failure: fix syntax first.
+- Pester failure: update script or test so the documented contract is true.
+- Analyzer failure: prefer changing the script over suppressing rules.
+- Missing local modules: report as an environment limitation and rely on CI if the workflow has the required action/tool.

.codex/skills/proxy-maintenance-safety/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: proxy-maintenance-safety
+description: Review changes that can affect Veeam proxy drain, service stop/start, WinRM, SCCM exit codes, or backup-infrastructure availability.
+---
+
+# Proxy Maintenance Safety
+
+Use this skill for safety review of production-impacting changes.
+
+## Review Checklist
+
+- `Pre` stage disables only the selected VBR proxy objects and waits for matching active tasks to drain.
+- Drain logic does not interrupt active backups or treat unrelated running tasks as safe to ignore without evidence.
+- Timeout behavior exits `30` and leaves enough log evidence for SCCM operators.
+- Remote service stop/start uses explicit proxy targets and does not broaden to non-target hosts.
+- `Post` stage attempts service start before proxy re-enable and preserves exit `60` for re-enable failure.
+- Reboot detection remains scoped to the script host, not remote proxies.
+- Logs do not expose credentials, tokens, or environment secrets.
+- README and tests match any changed parameter, exit code, or operator action.
+
+## Output
+
+Lead with a verdict:
+
+- `PASS`: no blocking production-safety issue found.
+- `BLOCKED`: change can disrupt backup infrastructure, hide failure, or strand disabled proxies.
+- `PARTIAL`: static evidence is acceptable, but live-environment behavior still needs operator validation.
+
+Keep findings file/line grounded and specific.

AGENTS.md

@@ -0,0 +1,59 @@
+# Repository Instructions
+
+Scope: this file applies to the whole repository.
+
+## Project Facts
+
+- This repo is a single-script PowerShell tool for SCCM/ConfigMgr-driven maintenance of Veeam VMware backup proxies.
+- Production entrypoint: `sccmpatch.ps1`.
+- Static tests live in `tests/sccmpatch.Tests.ps1`.
+- CI runs PSScriptAnalyzer, Pester, CodeQL for Actions, and dependency review.
+- The script is intended for PowerShell 5.1+ and Veeam Backup & Replication 12.3.2+.
+- The operational contract is the SCCM exit-code set: `0`, `3010`, `10`, `20`, `30`, `40`, `50`, `60`, `90`, `99`.
+
+## Safety Rules
+
+- Treat `-Stage Pre`, `-Stage Post`, WinRM, Veeam proxy enable/disable, and Veeam service stop/start as production-impacting operations.
+- Do not run `sccmpatch.ps1` against real proxy names, VBR servers, or production hosts unless the user explicitly asks for a live run and supplies the target environment.
+- Preserve the exit-code contract unless README, tests, and SCCM guidance are updated in the same change.
+- Preserve PowerShell 5.1 compatibility in `sccmpatch.ps1`. Avoid PowerShell 7-only syntax in production code.
+- Do not hardcode customer hostnames, credentials, tokens, domains, IPs, or service-account names.
+- Keep logs useful for SCCM troubleshooting, but do not log secrets or credential material.
+- Prefer small, auditable changes. This script controls backup infrastructure; broad rewrites are high risk.
+
+## Validation Commands
+
+Use the narrowest validation that matches the change.
+
+```powershell
+pwsh -NoLogo -NoProfile -Command "$errors = $null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path './sccmpatch.ps1'), [ref]$null, [ref]$errors); if ($errors) { $errors | Format-List; exit 1 }"
+pwsh -NoLogo -NoProfile -Command "Invoke-Pester -Path ./tests -Output Detailed"
+```
+
+If PSScriptAnalyzer is installed locally:
+
+```powershell
+pwsh -NoLogo -NoProfile -Command "Invoke-ScriptAnalyzer -Path . -Recurse"
+```
+
+For GitHub-side status:
+
+```powershell
+gh run list --repo cgfixit/sccm-veeam-proxy-patching --limit 5
+```
+
+## Codex Skills
+
+Repo-local skills live under `.codex/skills/`:
+
+- `code-optimizer`: optimize `sccmpatch.ps1` without breaking Veeam/SCCM safety contracts.
+- `proxy-maintenance-safety`: review production-impacting maintenance changes.
+- `pester-validation`: run and interpret parser, Pester, and analyzer checks.
+- `docs-runbook-sync`: keep README, SECURITY, tests, and script behavior aligned.
+
+## Change Workflow
+
+1. Read `sccmpatch.ps1`, `tests/sccmpatch.Tests.ps1`, `README.md`, and `SECURITY.md` before changing behavior.
+2. For code changes, update or add the smallest static test that would fail if the contract regresses.
+3. For parameter, exit-code, log, or operational behavior changes, update README/runbook guidance in the same PR.
+4. Use a branch and PR for repository changes. Do not push directly to `main` unless explicitly requested.