@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_nodes_node_lxc_vmid_snapshot_snapname_config",
+  "usageNotes": "Use this to update the human-readable description on an existing LXC snapshot — the only editable metadata after a snapshot is taken. The call is synchronous and returns null on success; no task UPID is issued. Requires VM.Snapshot privilege on /vms/{vmid}; the snapshot must already exist (use get_nodes_node_lxc_vmid_snapshot_snapname_config to verify before calling).",
+  "examples": [
+    {
+      "summary": "Add a description to an existing snapshot before a planned upgrade",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 112,
+        "snapname": "pre-upgrade-2024"
+      },
+      "params": {
+        "description": "Taken before Debian 12 dist-upgrade on 2024-09-15. Safe rollback point."
+      }
+    }
+  ],
+  "tips": [
+    "This endpoint only accepts 'description' — snapshot name and creation time cannot be changed after creation.",
+    "Omitting 'description' or sending an empty string clears the existing description.",
+    "Snapshot names follow the pve-configid format (alphanumeric + underscore/hyphen, max 40 chars); verify the name with the list endpoint before updating.",
+    "Returns HTTP 200 with a null body on success — treat any non-200 as an error."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_snapshot_snapname_config",
+    "get_nodes_node_lxc_vmid_snapshot",
+    "post_nodes_node_lxc_vmid_snapshot",
+    "delete_nodes_node_lxc_vmid_snapshot_snapname"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_nodes_node_network",
+  "usageNotes": "Use this to apply pending network configuration changes on a node without rebooting — it reloads the interfaces file and restarts the networking stack. The node must be online and reachable, and the caller requires Sys.Modify on /nodes/{node}. Set regenerate-frr to true only if you use SDN/FRR-based routing and need the FRR daemon config rebuilt from the current SDN config.",
+  "examples": [
+    {
+      "summary": "Reload network config on pve1 and regenerate FRR routing config",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "regenerate-frr": true
+      }
+    }
+  ],
+  "tips": [
+    "This reloads the live networking stack — brief packet loss on active interfaces is expected during the reload.",
+    "Use POST /nodes/{node}/network to stage interface changes first; PUT applies all pending changes at once.",
+    "If the node has SDN zones configured, pass regenerate-frr: true to ensure FRR picks up any route/peer changes.",
+    "The return value is a plain string (e.g. an empty string or status message), not a task UPID — the reload is synchronous from the API's perspective."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "post_nodes_node_network",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network_iface"
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "operationId": "put_nodes_node_network_iface",
+  "usageNotes": "Use this to modify the persistent configuration of an existing network interface on a node (IP, gateway, MTU, VLAN settings, bridge ports, bonding mode, etc.). Changes are written to `/etc/network/interfaces` but are NOT applied to the live network until you call the network reload endpoint (`put_nodes_node_network_reload`) or reboot the node — running traffic is uninterrupted until that apply step. Requires `Sys.Modify` on `/nodes/{node}`; the `type` parameter is mandatory even when you are only changing other fields.",
+  "examples": [
+    {
+      "summary": "Set a static IPv4 address and gateway on a Linux bridge, enable VLAN awareness, and ensure it autostart on boot",
+      "path_params": {
+        "node": "pve01",
+        "iface": "vmbr0"
+      },
+      "params": {
+        "type": "bridge",
+        "address": "10.0.0.10",
+        "netmask": "255.255.255.0",
+        "gateway": "10.0.0.1",
+        "bridge_ports": "eth0",
+        "bridge_vlan_aware": true,
+        "autostart": true,
+        "comments": "Main LAN bridge"
+      }
+    }
+  ],
+  "tips": [
+    "Changes are staged only — always follow up with `put_nodes_node_network_reload` (applies via `ifreload -a`) or a node reboot to activate them.",
+    "Use the `delete` param (comma-separated config key names) to remove individual settings such as `gateway` or `bridge_vids` without recreating the interface from scratch.",
+    "Supplying `cidr` (e.g. '10.0.0.10/24') is equivalent to setting `address` + `netmask` separately; do not mix both forms for the same interface.",
+    "Bond mode `active-backup` requires `bond-primary` to be set to one of the slave interfaces for deterministic failover.",
+    "OVS parameters (`ovs_bridge`, `ovs_bonds`, `ovs_ports`, `ovs_tag`, `ovs_options`) are ignored unless the node has Open vSwitch installed and the interface `type` is one of OVSBridge/OVSBond/OVSPort/OVSIntPort."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network_iface",
+    "post_nodes_node_network",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network_reload",
+    "get_nodes_node_network"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_cloudinit",
+  "usageNotes": "Regenerates the cloud-init config drive ISO in-place for the specified VM; use this after changing any cloud-init parameters (user, network, meta) via the VM config endpoints so the drive reflects the current settings. The VM does not need to be running — the drive is rebuilt from the stored config — but the updated data is only applied on the next VM boot. Requires the VM.Config.Cloudinit privilege on /vms/{vmid}; returns null synchronously (no UPID), so no task polling is needed.",
+  "examples": [
+    {
+      "summary": "Regenerate the cloud-init drive on VM 201 after updating its network config",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This call is a no-op if the VM has no cloud-init drive attached — attach one via the disk config first.",
+    "Returns null (not a UPID), so the operation completes synchronously; no need to poll task status.",
+    "Cloud-init data is applied at boot time, not immediately — reboot the VM after regenerating to activate the new config.",
+    "If you updated cloud-init settings via the QEMU config PUT endpoint, always follow up with this call to keep the drive in sync."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_cloudinit",
+    "put_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_status_reboot"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_config",
+  "usageNotes": "Use this endpoint to synchronously update VM configuration settings such as CPU, memory, network, boot order, cloud-init parameters, or description — any change that does not require hotplug or storage allocation. For operations involving hotplug (attaching devices to a running VM) or allocating new disk volumes, use POST /nodes/{node}/qemu/{vmid}/config instead, which queues the change asynchronously and returns a UPID. The caller must hold at least one matching VM.Config.* privilege on /vms/{vmid} for the specific parameter category being changed.",
+  "examples": [
+    {
+      "summary": "Resize CPU and memory, update description, and enable QEMU guest agent on VM 200",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 200
+      },
+      "params": {
+        "cores": 4,
+        "memory": "4096",
+        "agent": "enabled=1,freeze-fs=1",
+        "description": "Production web server — updated 2026-06-29"
+      }
+    }
+  ],
+  "tips": [
+    "Pass the 'digest' param (from GET /config) to prevent overwriting concurrent changes — the API will reject the request if the config has changed since you read it.",
+    "To remove a config key (e.g., a network device or unused tag), use the 'delete' param with a comma-separated list of key names rather than omitting them.",
+    "Deleting a disk key without 'force: true' moves the volume to unused[n] rather than destroying it; set force=true only when you intend permanent removal.",
+    "Cloud-init params (ciuser, cipassword, ipconfig[n], etc.) take effect on the next VM start — they do not reconfigure a running instance.",
+    "Changes to CPU or memory on a running VM are not applied until the VM is next stopped and started unless those resources are hotplugged via the POST variant."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_config",
+    "get_nodes_node_qemu_vmid_pending",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_resize"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_firewall_aliases_name",
+  "usageNotes": "Use this to update the CIDR, comment, or name of an existing IP/network alias scoped to a specific VM's firewall. The alias must already exist — create it first with the corresponding POST endpoint. Supply the `digest` field from the current alias to guard against concurrent overwrites; Proxmox will reject the update if the config has changed since you read it.",
+  "examples": [
+    {
+      "summary": "Rename alias 'db-backend' to 'db-primary' and update its CIDR",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105,
+        "name": "db-backend"
+      },
+      "params": {
+        "cidr": "10.10.20.0/24",
+        "rename": "db-primary",
+        "comment": "Primary database subnet after rack reorganization"
+      }
+    }
+  ],
+  "tips": [
+    "The `name` path param must match the alias as it currently exists; use `rename` in the body to give it a new name in the same request.",
+    "Alias names must start with a letter and may contain letters, digits, hyphens, and underscores (2–64 chars); the same pattern applies to `rename`.",
+    "Returns null on success — no UPID is issued because this is a synchronous, in-place config file update.",
+    "VM-level aliases are only visible to that VM's firewall rules; they are not shared with the cluster-wide alias pool."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_aliases_name",
+    "post_nodes_node_qemu_vmid_firewall_aliases",
+    "delete_nodes_node_qemu_vmid_firewall_aliases_name",
+    "get_nodes_node_qemu_vmid_firewall_aliases"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to update the comment, nomatch flag, or digest guard on an existing CIDR entry within a VM-level firewall IP set; the CIDR itself is a path parameter and cannot be changed in-place — to change the address, delete and re-add the entry. Requires VM.Config.Network on /vms/{vmid}. Returns null synchronously (no UPID); the change is applied immediately to the in-memory firewall ruleset.",
+  "examples": [
+    {
+      "summary": "Add a comment and set nomatch on an existing IP set entry for VM 101",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101,
+        "name": "trusted-mgmt",
+        "cidr": "10.10.5.0/24"
+      },
+      "params": {
+        "comment": "Exclude management subnet from match",
+        "nomatch": true
+      }
+    }
+  ],
+  "tips": [
+    "Pass 'digest' to guard against concurrent edits — retrieve it from the GET endpoint for the same IP set entry before writing.",
+    "Setting 'nomatch' to true inverts the match for this CIDR, useful for punching exceptions into a broader allow/deny range.",
+    "The IP set 'name' must already exist; use post_nodes_node_qemu_vmid_firewall_ipset to create the set and post_nodes_node_qemu_vmid_firewall_ipset_name to add entries.",
+    "The cidr path parameter accepts plain IPs, CIDR notation, or Proxmox aliases — ensure the value matches exactly what was used when the entry was created."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+    "post_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_ipset"
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_firewall_options",
+  "usageNotes": "Use this to enable, disable, or tune the per-VM firewall — including default policies, DHCP/NDP passthrough, IP filtering, and traffic log levels. The VM's firewall must first be enabled at the node/cluster level for these settings to take effect. Requires VM.Config.Network on the VM path; returns null synchronously (no UPID — the change is applied immediately).",
+  "examples": [
+    {
+      "summary": "Enable the firewall with DROP default policies, enable DHCP passthrough, and log inbound warnings",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "enable": true,
+        "policy_in": "DROP",
+        "policy_out": "ACCEPT",
+        "dhcp": true,
+        "ndp": true,
+        "ipfilter": true,
+        "log_level_in": "warning",
+        "log_level_out": "nolog"
+      }
+    }
+  ],
+  "tips": [
+    "The `enable` flag controls whether the VM-level firewall is active at all — rules exist but are unenforced when false.",
+    "Enabling `ipfilter` without any ipfilter-net<id> ipsets implicitly applies sane anti-spoofing defaults per interface; for containers it also whitelists configured IP addresses.",
+    "Use the `delete` param (comma-separated config key names) to revert specific options to their defaults rather than hard-coding the default value, which avoids drift if upstream defaults change.",
+    "Pass `digest` (retrieved from the GET counterpart) to guard against concurrent edits overwriting each other.",
+    "Changing `policy_in` to DROP is a common lockout risk — ensure at least one ACCEPT rule for SSH/management exists before applying."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_options",
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "post_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_firewall_options",
+    "put_cluster_firewall_options"
+  ]
+}

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

@@ -0,0 +1,38 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_firewall_rules_pos",
+  "usageNotes": "Use this to modify an existing firewall rule on a specific VM by its zero-based position index; the caller must hold VM.Config.Network on the VM's path. To reorder a rule without changing its properties, supply only `moveto` — all other body params are ignored in that case. Pass the `digest` from a prior GET to guard against concurrent modifications overwriting each other.",
+  "examples": [
+    {
+      "summary": "Change rule at position 2 to DROP inbound TCP traffic on port 22 from a specific source and add a comment",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110,
+        "pos": 2
+      },
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "proto": "tcp",
+        "source": "203.0.113.0/24",
+        "dport": "22",
+        "comment": "Block SSH from untrusted range",
+        "enable": 1,
+        "log": "warning"
+      }
+    }
+  ],
+  "tips": [
+    "Rules are zero-indexed; use get_nodes_node_qemu_vmid_firewall_rules to confirm the current position before editing.",
+    "When using `moveto`, the API ignores all other body fields — issue a second PUT if you also need to change rule properties.",
+    "The `delete` param accepts a comma-separated list of field names (e.g. 'comment,log') to clear optional fields back to their defaults.",
+    "VM firewall rules are only evaluated when the VM-level firewall is enabled; check the VM firewall options if rule changes appear to have no effect.",
+    "Do not mix IPv4 and IPv6 addresses in `source` or `dest` fields — Proxmox will reject the rule."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_qemu_vmid_firewall_rules_pos",
+    "post_nodes_node_qemu_vmid_firewall_rules",
+    "delete_nodes_node_qemu_vmid_firewall_rules_pos",
+    "get_nodes_node_qemu_vmid_firewall_options"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_resize",
+  "usageNotes": "Use this to grow a QEMU VM disk; it returns a task UPID and executes asynchronously, so poll the task status before assuming completion. Only expansion is supported — shrinking is not allowed and will be rejected. The `size` field accepts an absolute value (e.g. `50G`) or a relative increment prefixed with `+` (e.g. `+10G`); after resizing the disk, the guest OS filesystem still needs to be extended from within the VM.",
+  "examples": [
+    {
+      "summary": "Add 20 GB to the primary virtio disk of VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "disk": "virtio0",
+        "size": "+20G"
+      }
+    }
+  ],
+  "tips": [
+    "Pass `digest` (from the current VM config) to guard against concurrent modifications overwriting each other.",
+    "After resizing, extend the partition and filesystem inside the guest — Proxmox only grows the virtual disk, not the in-guest filesystem.",
+    "Resizing an EFI disk (efidisk0) or TPM state disk (tpmstate0) is rarely needed and may cause boot issues; double-check before targeting those.",
+    "The VM does not need to be powered off for a resize, but live resize visibility inside the guest depends on the guest OS and disk bus type."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_sendkey",
+  "usageNotes": "Injects a raw keypress into a running VM's console via the QEMU monitor — useful for sending keys that the guest OS would otherwise intercept (e.g. Ctrl-Alt-Del, SysRq sequences) or for automating BIOS-level interactions. The VM must be in a running state on the specified node; sending to a stopped or paused VM will error. Key strings use QEMU monitor encoding (e.g. 'ctrl-alt-delete', 'ret', 'shift-f10').",
+  "examples": [
+    {
+      "summary": "Send Ctrl-Alt-Delete to a Windows VM to trigger a graceful restart",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "key": "ctrl-alt-delete"
+      }
+    }
+  ],
+  "tips": [
+    "Key names follow QEMU monitor conventions, not X11 or Windows virtual-key names — use 'ret' for Enter, 'spc' for Space, 'esc' for Escape.",
+    "To send a key chord, join key names with '-' (e.g. 'ctrl-alt-delete'). For individual keys in sequence, make separate API calls.",
+    "Only root (PAM) may use skiplock=true; API tokens for regular users cannot bypass locks even with VM.Console.",
+    "This returns null synchronously — there is no UPID or task to poll; the keypress is delivered immediately or the call fails."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_monitor",
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_start"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_snapshot_snapname_config",
+  "usageNotes": "Use this to update the description/comment on an existing QEMU VM snapshot — the only mutable metadata on a snapshot after it is created. The operation is synchronous and returns null on success (no task UPID). The caller must hold VM.Snapshot on /vms/{vmid}; the target node must be online and the snapshot must already exist.",
+  "examples": [
+    {
+      "summary": "Add a note to a pre-upgrade snapshot on VM 105",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105,
+        "snapname": "pre_upgrade_20260629"
+      },
+      "params": {
+        "description": "Taken before upgrading Ubuntu 22.04 → 24.04 on 2026-06-29. Safe to delete after 30-day soak."
+      }
+    }
+  ],
+  "tips": [
+    "This is the only field editable after snapshot creation — snapshot name and disk state are immutable.",
+    "Returns null (HTTP 200 with empty body), not a UPID; no task polling needed.",
+    "Snapshot names follow pve-configid format (alphanumeric + underscore, max 40 chars) and cannot be renamed via this endpoint.",
+    "To list existing snapshots and their current descriptions, use get_nodes_node_qemu_vmid_snapshot before calling this."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_snapshot_snapname_config",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "delete_nodes_node_qemu_vmid_snapshot_snapname"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_nodes_node_qemu_vmid_unlink",
+  "usageNotes": "Use this to detach or permanently delete one or more disk images from a VM's configuration. Without `force`, disks are moved to `unused[n]` entries rather than deleted — use this safer default when you may need to recover the volume later. To permanently destroy the underlying storage volume, either set `force: true` or run unlink a second time targeting the resulting `unused[n]` entry. The VM does not need to be stopped, but the disk must not be in active use (e.g., avoid unlinking the boot disk while the VM is running).",
+  "examples": [
+    {
+      "summary": "Detach scsi1 from VM 105 without deleting the volume (moves to unused)",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {
+        "idlist": "scsi1",
+        "force": false
+      }
+    }
+  ],
+  "tips": [
+    "Omitting `force` is the safe default — the volume remains on storage as `unused[n]` and can be reattached or deleted later.",
+    "To permanently remove the volume in one step, set `force: true`.",
+    "Unlinking an `unused[n]` entry (e.g., `unused0`) always performs physical removal regardless of the `force` flag.",
+    "`idlist` accepts a comma-separated list (e.g., `scsi1,scsi2`) to unlink multiple disks in a single call.",
+    "This operation returns null synchronously — there is no UPID; the change is applied immediately to the VM config."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "put_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_move_disk"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_nodes_node_storage_storage_content_volume",
+  "usageNotes": "Use this to update metadata on an existing storage volume — specifically its freeform notes or protection flag. The protection flag is only honored for backup volumes (vzdump archives) and prevents deletion when set to true. The call returns null synchronously (no UPID); success means the attribute was applied immediately.",
+  "examples": [
+    {
+      "summary": "Mark a backup volume as protected and add a note",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local",
+        "volume": "backup/vzdump-qemu-101-2024_06_15-02_00_01.vma.zst"
+      },
+      "params": {
+        "notes": "Pre-migration snapshot — do not delete",
+        "protected": true
+      }
+    }
+  ],
+  "tips": [
+    "The 'protected' flag only has effect on backup-type volumes; setting it on a disk image or ISO is accepted but silently ignored.",
+    "To clear protection, send 'protected': false explicitly — omitting the field leaves the existing value unchanged.",
+    "Volume IDs for backups follow the pattern 'backup/vzdump-<type>-<vmid>-<timestamp>.<ext>'; get the exact string from get_nodes_node_storage_storage_content first.",
+    "The storage path param is marked required:false in the spec but is practically required — Proxmox cannot resolve the volume without it."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content",
+    "get_nodes_node_storage_storage_content_volume",
+    "delete_nodes_node_storage_storage_content_volume"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "put_nodes_node_subscription",
+  "usageNotes": "Use this to register or replace the Proxmox VE subscription key on a specific node — typically after purchasing or renewing a license, or when provisioning a new node that requires enterprise repository access. The key must match the pattern pve[1248][cbsp]-<10 hex chars> and is validated server-side against the Proxmox subscription portal. The caller requires Sys.Modify on /nodes/{node}; this operation returns null on success, so check for an HTTP 200 status rather than a response body.",
+  "examples": [
+    {
+      "summary": "Apply a Proxmox VE Basic (8-socket) subscription key to node pve01",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "key": "pve8b-a1b2c3d4e5"
+      }
+    }
+  ],
+  "tips": [
+    "The key pattern encodes socket count (1, 2, 4, or 8) and tier (c=Community, b=Basic, s=Standard, p=Premium); verify you are applying the correct tier key for the node's licensed socket count.",
+    "After updating the key, call GET /nodes/{node}/subscription to confirm the status transitions to 'active' and that the key's server ID matches the node.",
+    "Each subscription key is node-locked; applying the same key to multiple nodes will result in a 'wrong server ID' status on subsequent nodes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_subscription",
+    "delete_nodes_node_subscription"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "put_nodes_node_time",
+  "usageNotes": "Use this to set the system timezone on a specific Proxmox node. The timezone value must be a valid IANA timezone name (e.g. 'America/New_York') — consult /usr/share/zoneinfo/zone.tab on the node for the full list. Requires Sys.Modify on /nodes/{node}; this operation completes synchronously and returns null on success.",
+  "examples": [
+    {
+      "summary": "Set the timezone on node pve1 to US Eastern Time",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "timezone": "America/New_York"
+      }
+    }
+  ],
+  "tips": [
+    "Timezone names are case-sensitive and must exactly match an entry in /usr/share/zoneinfo/zone.tab on the node.",
+    "Changing the timezone affects log timestamps and scheduled tasks on that node; consider restarting time-sensitive services (e.g. cron) after the change.",
+    "Use get_nodes_node_time (GET /nodes/{node}/time) to verify the current timezone before and after setting it."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_time"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_pools",
+  "usageNotes": "Use this to update a pool's comment, or to add/remove VMs and storage resources from an existing pool. The caller must hold Pool.Allocate on /pool/{poolid} and also have the appropriate resource-level permissions (e.g. VM.Allocate) on each guest or storage being added or removed. To move a guest that already belongs to another pool, set allow-move=true; without it the request will be rejected if the guest is already pooled.",
+  "examples": [
+    {
+      "summary": "Add two VMs and a storage volume to pool 'devteam', moving VM 105 from its current pool if needed",
+      "path_params": {},
+      "params": {
+        "poolid": "devteam",
+        "vms": "104,105",
+        "storage": "local-zfs",
+        "allow-move": true,
+        "comment": "Dev team shared resources"
+      }
+    }
+  ],
+  "tips": [
+    "The 'vms' and 'storage' fields accept comma-separated lists (pve-vmid-list / pve-storage-id-list format).",
+    "Set 'delete': true to remove the listed VMs/storage from the pool rather than adding them — the pool itself is not deleted.",
+    "Returns null on success; any error (missing privilege, unknown poolid, guest already in another pool without allow-move) surfaces as an HTTP 4xx/5xx.",
+    "Pool membership controls ACL inheritance: guests in a pool inherit permissions granted at the /pool/{poolid} path."
+  ],
+  "relatedOperations": [
+    "post_pools",
+    "get_pools_poolid",
+    "delete_pools_poolid",
+    "get_pools"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_pools_poolid",
+  "usageNotes": "This is the deprecated path-based variant of pool updates; for environments using nested pools, use PUT /pools/ with a poolid query parameter instead. Use this endpoint to add or remove VMs/storage from a pool, or to update the pool comment. Callers need Pool.Allocate on /pool/{poolid} plus the relevant object permissions for any VMs or storage being added or removed.",
+  "examples": [
+    {
+      "summary": "Add two VMs and a storage to an existing pool",
+      "path_params": {
+        "poolid": "dev-team"
+      },
+      "params": {
+        "vms": "101,102",
+        "storage": "local-lvm",
+        "comment": "Dev team sandbox pool"
+      }
+    }
+  ],
+  "tips": [
+    "Set 'delete': true to remove listed vms/storage from the pool rather than adding them; omitting it (or setting false) performs an add.",
+    "Set 'allow-move': true when a VM is already a member of a different pool and you want to reassign it — without this flag the request will fail if any listed VMID is already pooled elsewhere.",
+    "Returns null on success; treat any non-error response as confirmation.",
+    "Prefer PUT /pools/?poolid={poolid} for any cluster running Proxmox VE 7.3+ nested-pool support."
+  ],
+  "relatedOperations": [
+    "get_pools_poolid",
+    "post_pools",
+    "delete_pools_poolid",
+    "get_pools"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_storage_storage",
+  "usageNotes": "Use this to modify an existing cluster-wide storage definition — changing allowed content types, bandwidth limits, pruning policy, or toggling the storage disabled/enabled. Requires the Datastore.Allocate privilege at /storage. Changes are synchronous and take effect immediately across all nodes that have the storage configured; use the 'digest' param to guard against concurrent modifications when multiple operators may be editing storage config.",
+  "examples": [
+    {
+      "summary": "Update an NFS storage to allow backups and VM images, and set a 500 MiB/s restore bandwidth limit",
+      "path_params": {
+        "storage": "nfs-backups"
+      },
+      "params": {
+        "content": "backup,images",
+        "bwlimit": "restore=512000,default=0",
+        "prune-backups": "keep-daily=7,keep-weekly=4,keep-monthly=3"
+      }
+    }
+  ],
+  "tips": [
+    "Pass 'delete' with a comma-separated list of param names to unset optional fields (e.g. 'delete=bwlimit,nodes' to remove per-storage bandwidth limits and node restrictions).",
+    "Setting 'disable=true' is a safe, reversible way to take a storage offline for maintenance without removing it from the cluster config.",
+    "The 'shared' flag does not replicate data — it only tells PVE that the storage is already shared at the infrastructure level (e.g. a SAN or NFS share). Misusing it on local storage can cause VM scheduling errors.",
+    "For PBS targets, the 'password' field updates the stored credential used for authentication against the Proxmox Backup Server datastore.",
+    "Retrieve the current 'digest' value from get_storage_storage before calling this endpoint if concurrent edits are a concern."
+  ],
+  "relatedOperations": [
+    "get_storage_storage",
+    "get_storage",
+    "post_storage",
+    "delete_storage_storage"
+  ]
+}