@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pve/enrichment/delete_nodes_node_ceph_osd_osdid.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_ceph_osd_osdid",
+  "usageNotes": "Permanently removes an OSD from the Ceph cluster. The OSD must first be taken out of the CRUSH map and marked 'down' (typically via the Ceph 'osd out' and 'osd down' commands) before deletion is safe — destroying an in-service OSD will cause data loss or reduced redundancy. Returns an async task UPID; poll the task endpoint to confirm completion. Set 'cleanup=true' to also wipe the underlying block device LVs, PVs, and leftover partitions; omit it only if you need to inspect the disk before reassignment.",
+  "examples": [
+    {
+      "summary": "Remove OSD 3 from node pve1 and wipe its underlying LVM volumes",
+      "path_params": {
+        "node": "pve1",
+        "osdid": 3
+      },
+      "params": {
+        "cleanup": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently destroys the OSD daemon and, when cleanup=true, irreversibly wipes the block device's logical volumes and partitions, removing all data stored on that OSD from the Ceph pool.",
+  "tips": [
+    "Run 'ceph osd safe-to-destroy <osdid>' before calling this endpoint to confirm no unique data copies will be lost.",
+    "The OSD must be in 'down' and 'out' state before destruction; use the Ceph CLI or PVE GUI to drain it first.",
+    "Without cleanup=true, the disk LVs remain and must be zeroed manually before the disk can be reused by Ceph.",
+    "If the Ceph cluster health is already degraded (e.g., fewer than min_size replicas), removing another OSD can make PGs unavailable — verify cluster health first."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_ceph_osd",
+    "get_nodes_node_ceph_osd",
+    "get_nodes_node_ceph_osd_osdid_in",
+    "get_nodes_node_ceph_osd_osdid_out",
+    "get_nodes_node_ceph_status"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_ceph_pool_name.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_ceph_pool_name",
+  "usageNotes": "Permanently destroys a Ceph pool and all data it contains; requires `Sys.Modify` at the root level. By default the pool will not be deleted if it is still in use — pass `force: true` to override this guard. The call returns a task UPID string, so poll the task endpoint to confirm completion before assuming the pool is gone.",
+  "examples": [
+    {
+      "summary": "Remove an unused replicated pool and its associated Proxmox storage entry",
+      "path_params": {
+        "node": "pve1",
+        "name": "vm-data"
+      },
+      "params": {
+        "remove_storages": true,
+        "remove_ecprofile": false
+      }
+    }
+  ],
+  "destructiveReason": "All objects (VM disks, RBD images, etc.) stored in the pool are permanently erased from the Ceph cluster with no recovery path.",
+  "tips": [
+    "The return value is a UPID task string — follow up with get_nodes_node_tasks_upid_status to verify the pool was actually removed.",
+    "If `remove_storages` is false (the default), any pveceph-managed Proxmox storage entries pointing at this pool will become broken and must be removed manually from datacenter storage config.",
+    "For erasure-coded pools, `remove_ecprofile` defaults to true; set it to false only if the EC profile is shared with another pool.",
+    "Ensure no running VMs or containers have disks mapped to this pool before issuing the delete, even with `force: true`."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_pool",
+    "get_nodes_node_ceph_pool_name_status",
+    "post_nodes_node_ceph_pool",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_certificates_acme_certificate.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_nodes_node_certificates_acme_certificate",
+  "usageNotes": "Revokes the node's current ACME-issued TLS certificate with the CA (e.g., Let's Encrypt), which will invalidate the certificate in the CA's records and trigger a new certificate order if ACME is reconfigured. Use this when you need to permanently retire a certificate — such as when rotating ACME accounts, changing the domain, or responding to a compromise. Requires Sys.Modify on the node; the node must be reachable and the ACME plugin must already be configured.",
+  "examples": [
+    {
+      "summary": "Revoke the ACME certificate on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Revokes the node's TLS certificate with the ACME CA, immediately invalidating it; the node will fall back to its self-signed certificate until a new ACME certificate is issued.",
+  "tips": [
+    "After revocation the node's web UI and API will present a self-signed certificate, causing browser warnings and breaking clients that enforce certificate validation.",
+    "This does not delete the local certificate files — use the ACME order endpoint to issue a replacement after revocation.",
+    "Revocation is reported to the CA and cannot be undone; if you only need to renew, use the POST /acme/certificate endpoint instead."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_certificates_acme_certificate",
+    "put_nodes_node_certificates_acme_certificate",
+    "get_nodes_node_certificates_info",
+    "get_nodes_node_config"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_certificates_custom.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_nodes_node_certificates_custom",
+  "usageNotes": "Removes the custom TLS certificate and private key from the specified node, reverting pveproxy to its self-signed certificate. Use `restart: true` to immediately reload pveproxy so the change takes effect without a manual service restart; omitting it means the old certificate stays in memory until the next pveproxy restart. Requires `Sys.Modify` on `/nodes/{node}` — API tokens are supported.",
+  "examples": [
+    {
+      "summary": "Remove the custom certificate on node pve1 and restart pveproxy immediately",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "restart": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the node's custom certificate chain and private key; HTTPS access reverts to the self-signed certificate, which will trigger browser/client trust warnings until a new certificate is uploaded.",
+  "tips": [
+    "If `restart` is false (default), pveproxy continues serving the old certificate from memory until the service is manually restarted or the node reboots.",
+    "After deletion, upload a replacement certificate with the POST /nodes/{node}/certificates/custom endpoint before restarting pveproxy to avoid a trust gap.",
+    "Returns null on success — no UPID is issued; the operation is synchronous."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_certificates_custom",
+    "get_nodes_node_certificates"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_disks_directory_name.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "delete_nodes_node_disks_directory_name",
+  "usageNotes": "Unmounts a directory-backed storage mount and removes its systemd mount unit from the specified node; requires `Sys.Modify` at the root level, and additionally `Datastore.Allocate` on `/storage/<name>` when using `cleanup-config`. Pass `cleanup-config: true` to also remove the storage from the cluster configuration (or mark it unavailable on this node); pass `cleanup-disks: true` to wipe the underlying disk so it can be repurposed. The operation returns a task UPID — poll the task status before treating the storage as fully removed.",
+  "examples": [
+    {
+      "summary": "Remove a directory storage named 'local-data' from node 'pve1', clean up its config entry, and wipe the disk for reuse",
+      "path_params": {
+        "node": "pve1",
+        "name": "local-data"
+      },
+      "params": {
+        "cleanup-config": true,
+        "cleanup-disks": true
+      }
+    }
+  ],
+  "destructiveReason": "Unmounts the directory and removes the mount unit; with cleanup-disks enabled, the underlying disk is wiped and all data on it is permanently destroyed.",
+  "tips": [
+    "Always verify no VMs or containers are actively using the storage before calling this — running guests with disks on the target storage will cause the unmount to fail.",
+    "The return value is a UPID string; use get_nodes_node_tasks_upid_status to poll completion before assuming the storage is fully gone.",
+    "cleanup-config only removes the storage from this node's config if it is configured exclusively for this node; otherwise it marks it unavailable here, leaving the entry for other nodes."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_disks_directory",
+    "get_nodes_node_disks_directory",
+    "get_nodes_node_tasks_upid_status",
+    "get_storage"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_disks_lvm_name.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_disks_lvm_name",
+  "usageNotes": "Removes an LVM Volume Group from the specified node; the return value is a task UPID, so poll the task API to confirm completion before reusing the underlying disks. The caller must hold `Sys.Modify` on `/`; if `cleanup-config` is set, `Datastore.Allocate` on `/storage` is also required. Ensure no VMs or containers have active storage references to this VG before invoking, as removal is immediate and irreversible.",
+  "examples": [
+    {
+      "summary": "Remove VG 'pve-data' from node 'pve01', wiping disks and cleaning up storage config",
+      "path_params": {
+        "node": "pve01",
+        "name": "pve-data"
+      },
+      "params": {
+        "cleanup-config": true,
+        "cleanup-disks": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently destroys the LVM Volume Group and all logical volumes it contains; all data stored on those volumes is unrecoverable, and optionally wipes the underlying physical disks.",
+  "tips": [
+    "Run 'get_nodes_node_disks_lvm' first to confirm the VG name and which physical disks back it before deleting.",
+    "Set 'cleanup-config: true' when the storage is defined only on this node; omit it if the storage definition should remain for other nodes in the cluster.",
+    "Set 'cleanup-disks: true' only when you intend to reprovision the raw disks — it writes zeros to the disk headers, making recovery impossible.",
+    "Track the returned UPID via the task API (e.g., 'get_nodes_node_tasks_upid_status') to detect failures before assuming the VG is gone."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_lvm",
+    "post_nodes_node_disks_lvm",
+    "get_nodes_node_disks_list",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_disks_lvmthin_name.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_disks_lvmthin_name",
+  "usageNotes": "Use this to permanently remove an LVM thin pool from a node; the target node must be online and the caller must hold Sys.Modify at the root path (plus Datastore.Allocate on /storage when using cleanup-config). The operation returns an async task UPID — poll the task status to confirm completion before treating the pool as removed. If VMs or containers still reference volumes inside the thin pool, removal will fail; evacuate or remove those volumes first.",
+  "examples": [
+    {
+      "summary": "Remove thin pool 'data-thin' from node 'pve1', clean up storage config and wipe underlying disks",
+      "path_params": {
+        "node": "pve1",
+        "name": "data-thin"
+      },
+      "params": {
+        "volume-group": "pve-vg",
+        "cleanup-config": true,
+        "cleanup-disks": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently destroys the LVM thin pool and all virtual disk volumes it contains; data is unrecoverable unless a backup exists, and cleanup-disks will additionally wipe the underlying block devices.",
+  "tips": [
+    "cleanup-config removes the storage definition from Proxmox; omit it if you plan to recreate the pool under the same name and want to preserve the storage entry.",
+    "cleanup-disks wipes partition/signature data so the physical disk can be reused — skip this flag if you intend to repurpose the VG for another thin pool without re-partitioning.",
+    "The required volume-group param must match the VG that contains the thin pool, not the thin pool name itself.",
+    "Always snapshot or back up any VM/CT disks stored in the pool before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_disks_lvmthin",
+    "get_nodes_node_disks_lvmthin",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_disks_zfs_name.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_disks_zfs_name",
+  "usageNotes": "Permanently destroys a ZFS pool on the specified node; the node must be online and the caller must hold Sys.Modify on /. Returns a task UPID — poll the task status endpoint to confirm completion before treating the pool as gone. If the pool is also registered as a Proxmox storage, pass cleanup-config=true to remove or disable that storage entry; without it the storage record remains and will show errors.",
+  "examples": [
+    {
+      "summary": "Destroy a ZFS pool named 'tank' on node 'pve1', removing its storage config entry and wiping the member disks for reuse",
+      "path_params": {
+        "node": "pve1",
+        "name": "tank"
+      },
+      "params": {
+        "cleanup-config": true,
+        "cleanup-disks": true
+      }
+    }
+  ],
+  "destructiveReason": "All data on the ZFS pool is irrecoverably destroyed; if cleanup-disks is set, the underlying disk partitions are also wiped and cannot be recovered.",
+  "tips": [
+    "Poll the returned UPID via GET /nodes/{node}/tasks/{upid}/status to detect failures — the DELETE call returns immediately with a task reference, not the final result.",
+    "cleanup-config only removes the storage from this node's configuration; if the storage is shared across multiple nodes you may need to remove it cluster-wide via the storage API afterward.",
+    "Ensure no VMs or CTs have active disks on this pool before destroying it — Proxmox does not enforce this check automatically.",
+    "cleanup-disks performs a partition wipe (dd/blkdiscard) on member vdevs; omit it if you plan to reuse the disks in a new pool with a fresh zpool create."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_zfs_name",
+    "get_nodes_node_disks_zfs",
+    "post_nodes_node_disks_zfs",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_firewall_rules_pos.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_nodes_node_firewall_rules_pos",
+  "usageNotes": "Deletes a single firewall rule from a node's host-level firewall by zero-based position index; all rules below the deleted position shift up by one, so capture the rule set first if you need to reference other rules by position afterward. Requires Sys.Modify on the target node. Pass the `digest` parameter (obtained from the GET rules list) to prevent accidentally overwriting concurrent edits.",
+  "examples": [
+    {
+      "summary": "Delete the second firewall rule (position 1) on node pve01, with digest guard",
+      "path_params": {
+        "node": "pve01",
+        "pos": 1
+      },
+      "params": {
+        "digest": "a3f5c2e1b4d6789012345678901234567890abcd"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the firewall rule at the specified position from the node's host firewall; the rule cannot be recovered and traffic previously matched by it will no longer be filtered.",
+  "tips": [
+    "List rules first with GET /nodes/{node}/firewall/rules to confirm the target position and capture the current digest before deleting.",
+    "Position indices are zero-based and compact — deleting pos 0 makes the former pos 1 the new pos 0.",
+    "This operates on the node's host firewall only; VM/container firewall rules are managed under /nodes/{node}/qemu/{vmid}/firewall/rules or /lxc/{vmid}/firewall/rules."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_firewall_rules",
+    "get_nodes_node_firewall_rules_pos",
+    "put_nodes_node_firewall_rules_pos",
+    "post_nodes_node_firewall_rules"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_lxc_vmid.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_lxc_vmid",
+  "usageNotes": "Permanently destroys an LXC container and all its associated files on the specified node; the operation is asynchronous and returns a task UPID that should be polled for completion. The container must be stopped first unless the `force` flag is set. Use `purge` to remove the container from backup jobs, replication jobs, and HA configurations — ACLs and firewall entries are always removed regardless.",
+  "examples": [
+    {
+      "summary": "Destroy a stopped LXC container and purge all references",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201
+      },
+      "params": {
+        "purge": true,
+        "destroy-unreferenced-disks": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the container's rootfs, all referenced disk volumes, and (with destroy-unreferenced-disks) any orphaned disks sharing the VMID on enabled storages — data is unrecoverable without a prior backup.",
+  "tips": [
+    "Returns a task UPID string — use get_nodes_node_tasks_upid_status to poll until the task completes before treating the container as fully gone.",
+    "The container must be in a stopped state unless `force: true` is passed; forcing destruction of a running container kills it immediately with no graceful shutdown.",
+    "Without `purge`, stale references in backup and replication schedules will continue to run and generate errors — always pass purge: true for a clean removal.",
+    "Requires the VM.Allocate privilege on /vms/{vmid}; cluster-level permission is not sufficient."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_stop",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_lxc"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_lxc_vmid_firewall_aliases_name.json

@@ -0,0 +1,31 @@
+{
+  "operationId": "delete_nodes_node_lxc_vmid_firewall_aliases_name",
+  "usageNotes": "Use this to permanently remove a named IP/network alias from a specific LXC container's firewall configuration. The caller must hold VM.Config.Network on the target VMID. Pass the current config digest to guard against concurrent modifications overwriting each other.",
+  "examples": [
+    {
+      "summary": "Delete the 'mgmt-net' alias from LXC 201 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201,
+        "name": "mgmt-net"
+      },
+      "params": {
+        "digest": "a3f1c8b2e94d7021bc56f3a901234def56789abc"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the named firewall alias from the container; any firewall rules that reference this alias by name will break and must be updated or removed separately.",
+  "tips": [
+    "Check for firewall rules referencing this alias before deleting — orphaned alias references can silently block or allow traffic unexpectedly.",
+    "Alias names are container-scoped; deleting here does not affect cluster-level or node-level aliases with the same name.",
+    "The operation returns null on success with no UPID — it is synchronous and takes effect immediately.",
+    "Omitting digest is safe in single-operator environments but risky if multiple admins may be editing firewall config concurrently."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_aliases_name",
+    "get_nodes_node_lxc_vmid_firewall_aliases",
+    "post_nodes_node_lxc_vmid_firewall_aliases",
+    "put_nodes_node_lxc_vmid_firewall_aliases_name",
+    "get_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_lxc_vmid_firewall_ipset_name.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_lxc_vmid_firewall_ipset_name",
+  "usageNotes": "Deletes a named IPSet from an LXC container's firewall configuration. By default the request fails if the IPSet still contains members — pass `force: true` to delete all member entries and the set in one operation. Requires `VM.Config.Network` privilege on the container's VM path, and the container must exist on the specified node (it does not need to be running).",
+  "examples": [
+    {
+      "summary": "Force-delete an IPSet named 'trusted-mgmt' (including all its member IPs) from LXC 201 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201,
+        "name": "trusted-mgmt"
+      },
+      "params": {
+        "force": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the named IPSet and, if `force` is used, all of its member IP/CIDR entries from the container's firewall; any firewall rules referencing this IPSet by name will become dangling references and may silently stop matching traffic.",
+  "tips": [
+    "List existing IPSets first with the corresponding GET operation to confirm the name and membership before deleting.",
+    "If the IPSet is referenced by active firewall rules, remove or update those rules before deleting the set to avoid silent rule breakage.",
+    "Omitting `force` on a non-empty IPSet returns an error — use it intentionally when you want a single atomic delete of set + members."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_ipset",
+    "get_nodes_node_lxc_vmid_firewall_ipset_name",
+    "post_nodes_node_lxc_vmid_firewall_ipset",
+    "delete_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+    "get_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_lxc_vmid_firewall_ipset_name_cidr.json

@@ -0,0 +1,32 @@
+{
+  "operationId": "delete_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to remove a specific IP address, CIDR block, or IP alias from a named IPSet on an LXC container's firewall; the IPSet itself remains intact with any other entries. The caller must hold VM.Config.Network on the container's VM path. Pass the current config digest to guard against concurrent modifications before deleting.",
+  "examples": [
+    {
+      "summary": "Remove a trusted management subnet from the 'mgmt-allowed' IPSet on container 110",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110,
+        "name": "mgmt-allowed",
+        "cidr": "10.10.0.0/24"
+      },
+      "params": {
+        "digest": "a3f2c1b4e7d8901234567890abcdef1234567890"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the specified IP/CIDR entry from the IPSet, which may immediately allow or block traffic that was previously matched by that entry depending on the firewall rules referencing this IPSet.",
+  "tips": [
+    "The IPSet name must match the pattern [A-Za-z][A-Za-z0-9\\-\\_]+ — it cannot start with a digit.",
+    "The cidr path parameter accepts a plain IP (e.g. 192.168.1.5), a CIDR range (e.g. 10.0.0.0/8), or a defined IP alias name.",
+    "Omitting the digest parameter skips optimistic-locking; always supply it in automated scripts to avoid overwriting concurrent changes.",
+    "Returns null on success — check HTTP 200 status rather than response body to confirm deletion.",
+    "Firewall rules referencing this IPSet take effect immediately after the entry is removed; no container restart required."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_ipset_name",
+    "post_nodes_node_lxc_vmid_firewall_ipset_name",
+    "get_nodes_node_lxc_vmid_firewall_ipset",
+    "delete_nodes_node_lxc_vmid_firewall_ipset_name"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_lxc_vmid_firewall_rules_pos.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "delete_nodes_node_lxc_vmid_firewall_rules_pos",
+  "usageNotes": "Permanently deletes a single firewall rule from an LXC container's rule list by its zero-based position index; remaining rules shift up to fill the gap, so always verify current positions with the list endpoint before deleting. Requires VM.Config.Network on the container. Pass the current config digest to guard against concurrent modifications overwriting each other.",
+  "examples": [
+    {
+      "summary": "Delete the second firewall rule (index 1) on container 112 hosted on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 112,
+        "pos": 1
+      },
+      "params": {
+        "digest": "a3f1c2b4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the firewall rule at the specified position; the deletion is immediate with no undo, and remaining rules shift index positions.",
+  "tips": [
+    "Rule positions are zero-based and shift after any deletion — always re-fetch the rule list before deleting to confirm the correct pos value.",
+    "The digest parameter is strongly recommended in automated or concurrent environments to prevent race conditions with other clients modifying the ruleset simultaneously.",
+    "Returns null on success; a non-null error response indicates the rule was not deleted."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "get_nodes_node_lxc_vmid_firewall_rules_pos",
+    "put_nodes_node_lxc_vmid_firewall_rules_pos",
+    "post_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_lxc_vmid_snapshot_snapname.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_nodes_node_lxc_vmid_snapshot_snapname",
+  "usageNotes": "Permanently deletes a named LXC snapshot and its associated disk data; the operation is asynchronous and returns a UPID task ID that should be polled to confirm completion. The caller must hold the VM.Snapshot privilege on /vms/{vmid}, and the target node must be online. Use the `force` parameter only as a last resort when disk snapshot removal fails and you want to at least clean the config entry — disk data may then be orphaned.",
+  "examples": [
+    {
+      "summary": "Delete a pre-upgrade snapshot named 'before_upgrade' from LXC 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110,
+        "snapname": "before_upgrade"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the snapshot and its stored disk state; this data cannot be recovered after deletion.",
+  "tips": [
+    "Poll the returned UPID via the tasks API to confirm the snapshot was fully removed before taking further snapshot actions on the same CT.",
+    "Deleting a snapshot with a child snapshot (rollback chain) is not supported; remove descendants first.",
+    "If the LXC uses an overlayfs/dir-based rootfs, snapshot deletion is typically instant; for ZFS or LVM-thin it may take longer depending on data size.",
+    "The `force` flag bypasses disk-layer removal errors but can leave orphaned volumes on the storage — audit storage afterward if used."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_snapshot",
+    "get_nodes_node_lxc_vmid_snapshot",
+    "post_nodes_node_lxc_vmid_snapshot_snapname_rollback",
+    "get_nodes_node_lxc_vmid_snapshot_snapname_config"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_network.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_nodes_node_network",
+  "usageNotes": "Use this to discard pending network configuration changes on a node — it reverts the in-memory/staged config back to the last applied state without rebooting or reloading interfaces. This is the safe escape hatch when you have used POST /nodes/{node}/network or PUT /nodes/{node}/network/{iface} to stage changes but have not yet applied them with PUT /nodes/{node}/network. The node must be online and reachable; the caller requires Sys.Modify on /nodes/{node}.",
+  "examples": [
+    {
+      "summary": "Discard all staged network changes on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently discards all staged (unapplied) network interface changes on the node; any interface additions, edits, or deletions that have not yet been applied via PUT /nodes/{node}/network will be lost with no recovery path.",
+  "tips": [
+    "Returns null — a 200 with an empty body is success; no UPID is issued because this operation is synchronous.",
+    "Only staged (not-yet-applied) changes are reverted; live interface state on the running node is untouched.",
+    "Check for pending changes first with GET /nodes/{node}/network and look for entries where 'pending' fields differ from 'active' fields.",
+    "This is the complement to PUT /nodes/{node}/network (apply); use this instead of apply if you want to abandon the changes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "post_nodes_node_network",
+    "put_nodes_node_network",
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "delete_nodes_node_network_iface"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_network_iface.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_nodes_node_network_iface",
+  "usageNotes": "Removes a network interface configuration from the node's /etc/network/interfaces — the change is staged and does not take effect until the network is reloaded (use PUT /nodes/{node}/network to apply). Only removes the Proxmox-managed config entry; the physical NIC or bond members themselves are unaffected. Requires Sys.Modify on the target node.",
+  "examples": [
+    {
+      "summary": "Delete a Linux bridge that is no longer needed",
+      "path_params": {
+        "node": "pve01",
+        "iface": "vmbr1"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the named interface's configuration from the node; any VMs or containers bound to that interface will lose network connectivity once the change is applied.",
+  "tips": [
+    "The deletion is staged — run PUT /nodes/{node}/network (reload) to commit it; until then the interface remains active.",
+    "Verify no VMs or CTs reference the interface before deleting to avoid silent connectivity loss.",
+    "Returns null on success; check the node's pending network config with GET /nodes/{node}/network to confirm the entry is gone before reloading.",
+    "If the node is a cluster member, ensure the interface is not used for corosync/cluster traffic before removing it."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "get_nodes_node_network",
+    "put_nodes_node_network",
+    "post_nodes_node_network"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_qemu_vmid.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_qemu_vmid",
+  "usageNotes": "Use this to permanently destroy a QEMU VM and all of its owned disk volumes; the VM must be stopped first (use stop_nodes_node_qemu_vmid_status) or the API will return an error unless skiplock is set. The call is asynchronous — it returns a task UPID string that you should poll with get_nodes_node_tasks_upid_status to confirm completion before treating the VM as gone. Pass purge=true to also remove the VMID from backup schedules, replication jobs, and HA configuration; omit it and those references will linger.",
+  "examples": [
+    {
+      "summary": "Destroy stopped VM 108 on pve1, purging all backup/HA references and scrubbing unreferenced disks",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 108
+      },
+      "params": {
+        "purge": true,
+        "destroy-unreferenced-disks": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the VM configuration and all attached/owned disk volumes from storage; this action is irreversible and data cannot be recovered without an external backup.",
+  "tips": [
+    "Always stop the VM before calling this endpoint; a running VM will cause the request to fail with a locked-VM error.",
+    "skiplock is root-only and should only be used to recover from a stuck lock after confirming the VM is truly stopped.",
+    "destroy-unreferenced-disks is false by default; enable it after cloning operations that may have left orphaned disk images with the same VMID.",
+    "The returned UPID can be polled via get_nodes_node_tasks_upid_status to wait for full cleanup before reclaiming the VMID."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_qemu"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_qemu_vmid_firewall_aliases_name.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_qemu_vmid_firewall_aliases_name",
+  "usageNotes": "Permanently removes a named IP/network alias from a VM's firewall alias set; any firewall rules on that VM that reference this alias by name will break silently after deletion, so audit dependent rules first. The operation returns null synchronously — there is no UPID to poll. Requires VM.Config.Network on the VM's path.",
+  "examples": [
+    {
+      "summary": "Delete the 'mgmt-net' alias from VM 200 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200,
+        "name": "mgmt-net"
+      },
+      "params": {
+        "digest": "a3f1c2e4b5d60789abcdef1234567890abcdef12"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the named firewall alias; any VM firewall rules referencing this alias by name will no longer resolve, potentially breaking intended traffic policies without immediate error.",
+  "tips": [
+    "Pass the current config digest to guard against concurrent modifications — fetch it from the GET aliases list before deleting.",
+    "Check for rules referencing the alias name before deletion: use the VM firewall rules list endpoint and grep for the alias name.",
+    "This is VM-scoped; a same-named alias at the datacenter or node level is a separate object and is unaffected."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_aliases",
+    "get_nodes_node_qemu_vmid_firewall_aliases_name",
+    "post_nodes_node_qemu_vmid_firewall_aliases",
+    "put_nodes_node_qemu_vmid_firewall_aliases_name",
+    "get_nodes_node_qemu_vmid_firewall_rules"
+  ]
+}

package/dist/catalog-pve/enrichment/delete_nodes_node_qemu_vmid_firewall_ipset_name.json

@@ -0,0 +1,39 @@
+{
+  "operationId": "delete_nodes_node_qemu_vmid_firewall_ipset_name",
+  "usageNotes": "Permanently deletes a named IPSet from a VM's firewall configuration. By default the request fails if the IPSet still contains members; pass force=true to delete all member CIDRs/IPs atomically with the set. Requires VM.Config.Network permission on the target VM.",
+  "examples": [
+    {
+      "summary": "Delete an empty IPSet from a VM firewall",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110,
+        "name": "trusted-clients"
+      },
+      "params": {}
+    },
+    {
+      "summary": "Force-delete an IPSet that still has members",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110,
+        "name": "trusted-clients"
+      },
+      "params": {
+        "force": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the named IPSet and, when force=true, all its member IP/CIDR entries; any firewall rules referencing this IPSet by name will break silently.",
+  "tips": [
+    "Check for firewall rules that reference the IPSet by name before deleting — Proxmox does not cascade-update rules that cite a deleted IPSet.",
+    "Omitting force when the IPSet has members returns a 500 error; use force=true to delete non-empty sets in a single call.",
+    "The operation returns null on success (not a UPID); it is synchronous."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "post_nodes_node_qemu_vmid_firewall_ipset",
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+    "get_nodes_node_qemu_vmid_firewall_rules"
+  ]
+}