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/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).