docs: consolidate agent instructions into AGENTS.md

Replace CLAUDE.md and .github/copilot-instructions.md with a single
AGENTS.md as the canonical source of truth for AI coding agent
instructions. CLAUDE.md becomes a symlink to AGENTS.md; copilot-
instructions.md is removed since copilot reads AGENTS.md natively.

Co-Authored-By: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-Authored-By: Vic Kerr <wiktor.kerr@ionos.com>

Author: 3 people

.github/copilot-instructions.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+CAPMOX (Cluster API Provider for Proxmox VE) enables declarative management of Kubernetes clusters on Proxmox VE using the Cluster API provider contract. See `go.mod` for dependency versions.
+
+The storage API version is **v1alpha2** (imported as `infrav1`). v1alpha1 exists only for backward compatibility with automatic conversion to/from v1alpha2.
+
+## Repository Structure
+
+- `api/v1alpha1/` — deprecated CRDs with conversion to v1alpha2
+- `api/v1alpha2/` — current storage version CRDs (ProxmoxCluster, ProxmoxMachine, ProxmoxMachineTemplate, ProxmoxClusterTemplate)
+- `cmd/main.go` — controller manager entry point
+- `internal/controller/` — reconciliation logic
+- `internal/webhook/` — validation and defaulting webhooks
+- `internal/service/` — VM, scheduler, and task services
+- `pkg/` — shared packages (proxmox client, scope, cloudinit, ignition, ipam)
+- `config/` — Kustomize configuration for CRDs, RBAC, webhooks
+- `hack/` — helper scripts
+- `test/e2e/` — end-to-end tests
+
+## Commands
+
+### Build & Test
+
+```bash
+make build                      # Build manager binary
+make test                       # Run unit tests
+make test WHAT=./pkg/scope/...  # Run tests for specific packages
+make lint                       # Run golangci-lint + kube-api-linter
+make lint-fix                   # Lint with auto-fix
+make yamlfmt                    # Format YAML files
+make tidy                       # go mod tidy
+make tilt-up                    # Start Tilt dev environment in a kind cluster
+```
+
+### Code Generation
+
+```bash
+make manifests    # Regenerate CRDs, RBAC, webhook manifests
+make generate     # Regenerate DeepCopy methods and conversion functions
+make mockgen      # Regenerate mocks (configured in .mockery.yaml)
+```
+
+### Version Bumping
+
+Several dependencies appear in multiple files — always use these scripts, never edit manually:
+
+```bash
+hack/bump-go.sh <version>             # Go version in go.mod, Dockerfile, docs
+hack/bump-capi.sh <version> <stream>  # cluster-api require, replace, metadata.yaml
+hack/bump-k8s.sh <version>            # k8s.io/* and ENVTEST_K8S_VERSION in Makefile
+hack/bump-golangci-lint.sh <version>  # golangci-lint in go.mod and .custom-gcl.yaml
+```
+
+Each script accepts versions with or without a `v` prefix and runs `go mod tidy` automatically.
+
+### Verification
+
+```bash
+make verify           # Verify modules and generated files are up to date
+make verify-versions  # Check version references are consistent across the repo
+```
+
+## Architecture
+
+### Reconciliation Flow
+
+Controllers (`internal/controller/`) reconcile two custom resources:
+
+- **ProxmoxCluster** — manages cluster-level infrastructure (control plane endpoint, allowed nodes)
+- **ProxmoxMachine** — manages individual VM lifecycle on Proxmox VE
+
+Each controller creates a **Scope** (`pkg/scope/`) bundling the CAPI owner objects, infrastructure CR, Proxmox client, and IPAM helper into a single context object passed through the reconciliation pipeline.
+
+The ProxmoxMachine controller delegates VM operations to services under `internal/service/`:
+- `vmservice/` — VM clone, configure, bootstrap (cloud-init or Ignition), IP assignment, power management, deletion
+- `scheduler/` — selects which Proxmox node to place a new VM on
+- `taskservice/` — tracks async Proxmox task completion and error handling
+
+### Proxmox Client Abstraction
+
+`pkg/proxmox/client.go` defines the `Client` interface for all Proxmox API operations. The production implementation lives in `pkg/proxmox/goproxmox/` (wrapping `go-proxmox`). Tests use a mock at `pkg/proxmox/proxmoxtest/`.
+
+### API Versions and Conversion
+
+- `api/v1alpha2/` — current storage version
+- `api/v1alpha1/` — deprecated; conversion implemented in `*_conversion.go` and `zz_generated.conversion.go`
+
+Key v1alpha2 change: unified `NetworkDevices` array replacing v1alpha1's split of `Default` + `AdditionalDevices`.
+
+### Bootstrap & IPAM
+
+`pkg/cloudinit/` and `pkg/ignition/` handle cloud-init and Flatcar Ignition bootstrap data. IP management is via the Cluster API IPAM contract (`pkg/kubernetes/ipam/`).
+
+## Testing
+
+- Unit tests colocated with source files, using envtest; see `Makefile` for `ENVTEST_K8S_VERSION`
+- First `make test` run builds envtest binaries — setup output is not a test failure
+- `testify` for assertions, `gomega`/`ginkgo` for BDD-style tests
+- Proxmox client mocks generated via `make mockgen` (`.mockery.yaml`)
+- E2E tests in `test/e2e/` require a live Proxmox VE instance; controlled by PR labels
+
+## Rules
+
+✅ **Always:**
+- Run `make manifests generate mockgen` after modifying API types
+- If conversion behavior changes, update `api/v1alpha1/*_conversion.go`
+- Run `make lint verify test` before committing
+- Use `hack/bump-*.sh` scripts when changing Go, cluster-api, k8s.io, or golangci-lint versions
+- Run `make verify-versions` after any version bump
+
+⚠️ **Ask before:**
+- Changing v1alpha1 conversion functions (affects backward compatibility)
+- Removing or renaming fields in v1alpha2 API types
+
+🚫 **Never:**
+- Edit generated files manually — see `sonar-project.properties` `sonar.exclusions` for the full list of generated file patterns
+- Edit version-tracked dependencies without the corresponding `hack/bump-*.sh` script
+
+## Environment
+
+See `envfile.example` for development config. Key vars: `PROXMOX_URL`, `PROXMOX_TOKEN`, `PROXMOX_SECRET`, `CAPMOX_LOGLEVEL`.

AGENTS.md

@@ -0,0 +1 @@
+AGENTS.md