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/domains/README.md

@@ -0,0 +1,26 @@
+# Domain guides
+
+These pages summarize durable semantics by area. For exhaustive method lists,
+use the Web UI catalog or OpenAPI (`/docs`) against the active major — declared
+coverage is **100%** for PVE 6–9.
+
+| Guide | Topics |
+|---|---|
+| [Core & cluster](core-cluster.md) | version, nodes, cluster resources/options/status |
+| [Access](access.md) | users, groups, roles, ACL, realms, tokens, TFA, OpenID |
+| [QEMU](qemu.md) | guests, power, disks, snapshots, clone/migrate, agent |
+| [LXC](lxc.md) | containers and parallel lifecycle operations |
+| [Storage & backup](storage-backup.md) | storages, content, vzdump / backup jobs |
+| [Firewall](firewall.md) | cluster / node / guest firewall objects |
+| [HA](ha.md) | groups, resources, status |
+| [Ceph](ceph.md) | simulated Ceph configuration and status |
+| [Pools](pools.md) | pools and membership |
+| [SDN](sdn.md) | zones, VNets, subnets, controllers, IPAM |
+| [Cluster extras](cluster-extras.md) | notifications, ACME, mapping, metrics servers |
+| [Tasks](tasks.md) | UPID workers, status, logs |
+
+## Persistence map
+
+- Guests / HA / storage / identity → normalized tables
+- Loose cluster config → `clusters.metadata` jsonb
+- Per-node ops (network, disks, apt, …) → `nodes.metadata` under `ops`

docs/domains/access.md

@@ -0,0 +1,16 @@
+# Access
+
+Durable identity and authorization: users, groups, roles, ACL entries, realms,
+passwords, API tokens, permissions queries, tickets, TFA, OpenID, VNC tickets.
+
+## Highlights
+
+- Ticket login and CSRF — see [Authentication](../authentication.md).
+- Token create returns the secret once; only hashes are stored.
+- ACL inheritance and token ∩ owner privilege intersection.
+- Realm / TFA / OpenID state is **local**; no live directory or IdP calls.
+
+## Seeded personas
+
+`root@pam`, `auditor@pve`, `operator@pve`, `storage@pve` — see the
+authentication guide for passwords and tokens.

docs/domains/ceph.md

@@ -0,0 +1,7 @@
+# Ceph
+
+Ceph-related API paths persist simulated cluster, pool, OSD, and monitor state.
+They do not speak to a live Ceph cluster.
+
+Legacy path aliases (for example historical `ceph/pools` spellings) map onto the
+shared handlers so older majors remain fully routed.

docs/domains/cluster-extras.md

@@ -0,0 +1,11 @@
+# Cluster extras
+
+Additional cluster-scoped domains with durable handlers:
+
+- **Notifications** — endpoints and targets configuration state
+- **ACME** — account/plugin/certificate simulation (no real CA enrollment)
+- **Mapping** — PCI / USB / resource mappings
+- **Metrics servers** — PVE metrics-server configuration/export simulation
+- **Custom CPU models** and bulk guest actions as declared
+
+Browse the Web UI catalog for the exact paths on your active major.

docs/domains/core-cluster.md

@@ -0,0 +1,23 @@
+# Core & cluster
+
+## Version
+
+`GET /version` reflects the **active** contract’s `source_version` (cold-start
+snapshot or hot-swapped major).
+
+## Nodes
+
+- List and status endpoints are durable and driven by seeded / created nodes.
+- Default `small` seed node name: **`pve01`**.
+- Node operational mutations (network, apt, disks, services, DNS/time/hosts,
+  certificates, …) persist under `nodes.metadata.ops`.
+
+## Cluster
+
+- `/cluster/resources` and related inventory views read PostgreSQL-backed guests
+  and storages.
+- Cluster options, status, tasks, logs, replication, config/join helpers persist
+  cluster metadata and related tables.
+
+Works for all declared methods on majors 6–9 for these paths. Use the Web UI
+catalog to inspect version-specific parameter differences.

docs/domains/firewall.md

@@ -0,0 +1,8 @@
+# Firewall
+
+Cluster, node, and guest firewall configuration — rules, aliases, IP sets,
+security groups — persists primarily through cluster/node metadata and related
+structures.
+
+Handlers cover the declared firewall surface for majors 6–9. Apply the major you
+care about before asserting version-specific field names.

docs/domains/ha.md

@@ -0,0 +1,8 @@
+# HA
+
+High-availability groups, resources, status, and rules persist in cluster
+metadata / HA tables.
+
+Use profile `ha-demo` (medium + HA resource for VM 100) or the demo cluster for
+richer fixtures. HA here orchestrates **simulated** guest placement state — it
+does not fence real nodes.

docs/domains/lxc.md

@@ -0,0 +1,13 @@
+# LXC
+
+Container APIs mirror the QEMU lifecycle patterns where the contract declares
+them: CRUD, power, clone/migrate, snapshots, volume operations, consoles, RRD,
+and firewall objects.
+
+Mutations persist to normalized container tables and related metadata. Async
+paths return UPIDs under the same leased-worker model as QEMU.
+
+Seed profiles:
+
+- `small` — CT `200` on `pve01`
+- `medium` / `large` / `demo-cluster` — many containers

docs/domains/pools.md

@@ -0,0 +1,4 @@
+# Pools
+
+Pool CRUD and resource membership are fully covered and durable. The `medium`
+seed includes a development pool for membership experiments.

docs/domains/qemu.md

@@ -0,0 +1,17 @@
+# QEMU
+
+Full contract surface for QEMU guests on the active major, including:
+
+- Create / sync & async config update / delete (UPID where async)
+- Power: start, stop, shutdown, reboot, reset, suspend, resume
+- Explicit state machine + per-VM PostgreSQL lock
+- Snapshots (create/delete/rollback as tasks)
+- Clone and local migration (UPID)
+- Disk resize (sync; shrink rejected) and disk move (task)
+- Pending config view
+- Guest agent read-only subset (info, OS/hostname, network, time, ping) when
+  `agent=1` and the guest is running
+- Cloud-init, consoles, RRD, guest firewall objects as declared
+
+Indexed contract fields such as `scsi[n]` accept concrete names (`scsi0`, …).
+Unknown version-dependent parameters are retained in JSONB.

docs/domains/sdn.md

@@ -0,0 +1,8 @@
+# SDN
+
+Software-defined networking handlers cover declared zones, VNets, subnets,
+controllers, IPAM, DNS, fabrics, locks, and related dry-run/rollback style
+operations for the active major.
+
+State is local to the simulator database. Switching majors 6–9 updates which
+SDN methods exist on the wire; all declared ones are implemented.

docs/domains/storage-backup.md

@@ -0,0 +1,16 @@
+# Storage & backup
+
+## Storage
+
+- Cluster and node storage inventories persist in normalized storage tables.
+- Content listings and mutations update `storage_contents` (and related rows).
+- `broken-storage` seed marks `local-lvm` unavailable for failure testing.
+
+## Backup
+
+- Backup jobs, metadata, and `vzdump`-style task paths create durable task rows
+  and backup records.
+- Workers execute leased backup tasks similarly to guest operations.
+
+No real remote backup targets are contacted; object state remains inside
+PostgreSQL.

docs/domains/tasks.md

@@ -0,0 +1,23 @@
+# Tasks
+
+Long-running operations return a Proxmox-style **UPID**. Task rows, events,
+optional resource locks, and idempotency metadata commit together.
+
+## Client pattern
+
+1. `POST`/`DELETE` mutation → read UPID from `data`
+2. Poll `GET /nodes/{node}/tasks/{upid}/status` until finished
+3. Optionally fetch `.../log`
+
+## Workers
+
+- Claim with `FOR UPDATE SKIP LOCKED`
+- Renewable leases (`TASK_LEASE_SECONDS`)
+- Progress + append-only logs
+- Recovery after process failure
+
+Simulation durations honour `SIMULATION_TIME_SCALE`. Worker lease safety uses
+wall-clock time so an accelerated scenario cannot invalidate distributed claim
+semantics.
+
+See [API surface](../api-surface.md) and [Operations](../operations.md).