consolidate agent instructions into AGENTS.md, add AI policy

AGENTS.md

@@ -0,0 +1,109 @@
+# 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)
+```
+
+### Verification
+
+```bash
+make verify           # Verify modules and generated files are up to date
+```
+
+## 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
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, paying particular attention to the [AI-Assisted Contributions](CONTRIBUTING.md#ai-assisted-contributions) section which covers authorship, transparency, and quality expectations for AI-assisted work.
+
+## 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
+
+⚠️ **Ask before:**
+- Changing v1alpha1 conversion functions (affects backward compatibility)
+- Removing or renaming fields in v1alpha2 API types
+
+🚫 **Never:**
+- Edit files with a `Code generated … DO NOT EDIT` header
+- Edit the unmarked outputs of `make manifests` (`config/crd/bases/*.yaml`, `config/rbac/role.yaml`, `config/webhook/manifests.yaml`) or `make crs-*` (`templates/crs/cni/*.yaml`) — regenerate instead
+
+## Environment
+
+See `envfile.example` for development config. Key vars: `PROXMOX_URL`, `PROXMOX_TOKEN`, `PROXMOX_SECRET`, `CAPMOX_LOGLEVEL`.

CLAUDE.md

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

CONTRIBUTING.md

@@ -33,6 +33,9 @@ git push origin feature-branch
 * Provide a clear and descriptive title for your changes.
 * Include details about the changes and the problem it solves.
 * Reference any relevant issues or pull requests.
+* Keep changes complete and self-contained — partial implementations are not mergeable and stall review.
+* Keep PRs focused and of reasonable size; smaller, focused changes are easier and faster to review and merge.
+* A chain of dependent PRs is a good way to break up large contributions.
 
 The ionos-cloud/cluster-api-provider-proxmox repo requires approval to run actions on external PRs.
 This includes linters, unit (go) and e2e tests, scanners.
@@ -67,6 +70,25 @@ Make sure that it's lint-free and that generated files are up to date.
 make lint test verify
 ```
 
+## AI-Assisted Contributions
+
+All guidelines in this document apply to AI-assisted contributions. The rules in this section are in addition to those.
+
+AI tools are welcome at any stage.
+
+**Authorship**: The git commit author must be the person responsible for the contribution. Any agent that produced code must be attributed with a `Co-Authored-By:` trailer. The only exception is a commit that solely modifies an agent instructions file (e.g. `AGENTS.md`) where the agent may be the author and the person a co-author.
+
+**Transparency**: AI agents must be clearly identified as such. We don't mind interacting with agents; we do mind agents masquerading as people. Do not have an agent interact on issues or pull requests while presenting as a human contributor.
+
+**Human oversight**: The human contributor is responsible for the entire contribution and must oversee it end to end — code, tests, and description.
+
+**Quality**: A non-draft pull request must represent completed work:
+- Includes relevant tests covering the changes
+- All tests and linters pass (`make lint test verify`)
+- Correct attribution on all commits
+
+Pull requests that violate these standards will be closed.
+
 ## Documentation
 Ensure that your changes are reflected in the documentation. If you are introducing new features, update the documentation accordingly.