Add a stateful Proxmox API console and broad handler coverage beyond the

initial QEMU slice, backed by imported contracts for majors 6–9.
- Implement durable handlers for access/auth, cluster, LXC, storage, HA,
  firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops
- Serve an interactive Web UI with catalog browsing, demo seed controls,
  and OpenAPI/help surfaces
- Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3
- Support in-memory runtime contract Apply (POST /ui/api/contract/apply)
  so /version and /api2 routes follow the selected major until restart
- Expand seed profiles (including demo-cluster), migrations 007–008, TLS
  gateway config, Compose/Makefile tooling, and compatibility evidence
- Tighten .gitignore for macOS, hidden directories (.*/), and local secrets

docs/examples/ansible.md

@@ -0,0 +1,11 @@
+# Ansible
+
+Playbook uses the `uri` module against HTTP `:8006` with token auth, then
+ticket+CSRF for a mutation path.
+
+```bash
+cd examples/ansible
+ansible-playbook -i inventory.ini playbook.yml
+```
+
+Reseed the simulator before relying on fixed VMIDs from a previous run.

docs/examples/go.md

@@ -0,0 +1,11 @@
+# Go
+
+Uses the Go standard library against `http://localhost:8006` with API-token
+authentication.
+
+```bash
+cd examples/go
+go run .
+```
+
+See `main.go` for the cookbook flow and UPID polling helper.

docs/examples/java.md

@@ -0,0 +1,11 @@
+# Java
+
+Java 11+ `HttpClient` cookbook using API-token auth against `:8006`.
+
+```bash
+cd examples/java
+javac Cookbook.java && java Cookbook
+```
+
+Requires no third-party JSON library — responses are inspected with simple
+string helpers suitable for a lab smoke.

docs/examples/overview.md

@@ -0,0 +1,56 @@
+# Client examples overview
+
+## Bring-up checklist
+
+```bash
+make up
+curl -sf http://localhost:8006/health/ready
+make seed PROFILE=small
+curl -s http://localhost:8006/api2/json/version
+```
+
+Optional — pin major 8 for the session:
+
+```bash
+curl -s -X POST 'http://localhost:8006/ui/api/contract/apply?major=8'
+```
+
+## Endpoints
+
+| URL | When |
+|---|---|
+| `http://localhost:8006` | curl, Go, Java, Perl, Ansible, requests |
+| `https://localhost:8007` | proxmoxer, many Terraform/Pulumi TLS clients |
+
+## Auth quick reference
+
+**Ticket**
+
+```bash
+RESP=$(curl -s -X POST -d 'username=root@pam&password=secret' \
+  http://localhost:8006/api2/json/access/ticket)
+TICKET=$(echo "$RESP" | jq -r .data.ticket)
+CSRF=$(echo "$RESP" | jq -r .data.CSRFPreventionToken)
+```
+
+**Token header**
+
+```text
+Authorization: PVEAPIToken=root@pam!automation=automation-secret
+```
+
+## UPID waiting
+
+Never treat the mutation HTTP response alone as “VM running”. Poll
+`/nodes/{node}/tasks/{upid}/status` until `data.status` is terminal (typically
+`stopped` with exit status OK for completed tasks — match Proxmox fields your
+client already understands).
+
+## Reseed warning
+
+`make seed` replaces PostgreSQL guests. Refresh Terraform/Pulumi/Ansible state
+afterwards.
+
+## Runnable tree
+
+See [`examples/README.md`](../../examples/README.md).

docs/examples/perl.md

@@ -0,0 +1,9 @@
+# Perl
+
+`HTTP::Tiny` + JSON cookbook with API-token auth.
+
+```bash
+cd examples/perl
+cpanm --installdeps .   # or install HTTP::Tiny and JSON manually
+perl cookbook.pl
+```

docs/examples/pulumi.md

@@ -0,0 +1,13 @@
+# Pulumi
+
+Python Pulumi program that drives the simulator over HTTPS using token auth via
+the Pulumi Command/provider patterns documented in `examples/pulumi`.
+
+```bash
+cd examples/pulumi
+pulumi stack init dev   # once
+pulumi up
+```
+
+Same reseed caution as Terraform: simulator PostgreSQL state and Pulumi state
+are independent. Pin the API major for reproducible CI.

docs/examples/python-proxmoxer.md

@@ -0,0 +1,21 @@
+# Python — proxmoxer
+
+Canonical library path against the HTTPS gateway.
+
+## Run
+
+```bash
+make up && make seed PROFILE=small
+pip install -r examples/python/requirements.txt
+python examples/python/proxmoxer_cookbook.py
+```
+
+Environment overrides: `PVE_HOST` (default `localhost`), `PVE_PORT` (default
+`8007`), `PVE_USER`, `PVE_PASSWORD`, or token via `PVE_TOKEN_NAME` /
+`PVE_TOKEN_VALUE`.
+
+## Notes
+
+- `verify_ssl=False` is required only for the disposable local certificate.
+- Ticket mutations handled by proxmoxer include CSRF automatically.
+- Default node for `small` is `pve01`.

docs/examples/python-requests.md

@@ -0,0 +1,11 @@
+# Python — requests
+
+Raw HTTP against `:8006` without proxmoxer.
+
+```bash
+pip install -r examples/python/requirements.txt
+python examples/python/requests_cookbook.py
+```
+
+The script demonstrates token auth (no CSRF) and ticket auth (with CSRF) for the
+shared create → wait → start → stop → delete flow.

docs/examples/terraform.md

@@ -0,0 +1,19 @@
+# Terraform
+
+Example uses a Proxmox provider pointed at the local HTTPS gateway
+(`https://localhost:8007`) with `insecure = true` for the development
+certificate.
+
+```bash
+cd examples/terraform
+terraform init
+terraform apply
+```
+
+Provider plugin versions move quickly — pin versions in `versions.tf` to what
+you have tested. After `make seed`, refresh or recreate state so VMID/node
+assumptions stay aligned.
+
+This cookbook is a starting point for lab CI, not a certification of every
+provider resource against all four API majors. Pin the simulator major before
+apply (`CONTRACT_SNAPSHOT` or hot-swap + `/version` assert).

docs/examples/troubleshooting-clients.md

@@ -0,0 +1,11 @@
+# Troubleshooting clients
+
+| Symptom | Fix |
+|---|---|
+| TLS certificate errors | Use `:8007` with verify disabled **only** locally, or use HTTP `:8006` |
+| CSRF failure | Send `CSRFPreventionToken` with ticket mutations; prefer token auth in scripts |
+| Node not found | `small` seed uses `pve01` |
+| 403 on power | You may be using `auditor@pve` / readonly token — switch to root or operator |
+| Provider create vs UPID | Poll tasks; many providers already wait — raw HTTP clients often forget |
+| Drift after reseed | Refresh/recreate Terraform/Pulumi/Ansible state |
+| Wrong schema fields | Hot-swap or cold-start the intended major; confirm `/version` |