@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pdm/enrichment/put_config_certificate.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_config_certificate",
+  "usageNotes": "Use this to configure which ACME account and domain(s) the PDM node should use for automatic TLS certificate issuance. Requires System.Modify privilege. The `digest` param should be supplied (read from GET /config first) to prevent a lost-update race if multiple admins could modify config concurrently; omitting it is safe in single-admin environments.",
+  "examples": [
+    {
+      "summary": "Configure ACME with a primary domain using HTTP validation and a secondary domain via DNS plugin",
+      "path_params": {},
+      "params": {
+        "acme": "account=letsencrypt-prod",
+        "acmedomain0": "domain=pdm.example.com",
+        "acmedomain1": "domain=pdm-alt.example.com,plugin=cloudflare-dns"
+      }
+    }
+  ],
+  "tips": [
+    "acmedomain0 through acmedomain4 allow up to five SANs on a single certificate; acmedomain0 typically becomes the CN.",
+    "Omitting the plugin sub-key on a domain entry defaults to standalone HTTP validation — ensure port 80 is reachable from the ACME CA for that challenge to succeed.",
+    "Use the alias sub-key when _acme-challenge DNS records are delegated to a separate zone via CNAME, so the plugin writes the TXT record to the aliased domain instead.",
+    "After updating this config, trigger actual certificate issuance or renewal via the certificate order/renew endpoint; this PUT only saves the configuration, it does not immediately contact the CA.",
+    "Pass the `delete` array to remove individual properties (e.g., remove a previously set acmedomain1) without having to resend all values."
+  ],
+  "relatedOperations": [
+    "get_config",
+    "get_config_acme",
+    "get_config_acme_account",
+    "post_config_acme_account",
+    "get_config_acme_plugins",
+    "get_config_acme_challenge_schema"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_config_notes.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "put_config_notes",
+  "usageNotes": "Use this to set or update the freeform notes text stored in the PDM system configuration — useful for recording maintenance windows, handoff notes, or datacenter context visible to all administrators. Requires the System.Modify privilege on the /system/notes ACL path. Pass the current config digest to guard against concurrent overwrites; omit it only when last-write-wins behavior is acceptable.",
+  "examples": [
+    {
+      "summary": "Update PDM notes with a maintenance reminder, using digest to prevent overwrite conflicts",
+      "path_params": {},
+      "params": {
+        "notes": "Scheduled maintenance window: 2026-07-05 02:00–04:00 UTC. All PDM nodes expected to restart. Contact hello@nightsquawk.tech for emergencies.",
+        "digest": "a3f1c2e4b5d6789012345678abcdef0123456789abcdef0123456789abcdef01"
+      }
+    }
+  ],
+  "tips": [
+    "The endpoint returns null on success — a 200 with no body is the expected success response.",
+    "Supplying 'digest' is strongly recommended in multi-admin environments; PDM will reject the write if the config has changed since the digest was read, preventing silent overwrites.",
+    "Notes are stored in the PDM configuration file and are visible to any user who can read the config — do not store credentials or secrets here.",
+    "To read the current notes (and obtain a fresh digest), use get_config_notes before writing."
+  ],
+  "relatedOperations": [
+    "get_config_notes"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_config_views_id.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_config_views_id",
+  "usageNotes": "Use this to update the filter rules, layout, or include-all flag of an existing PDM view. The caller must hold Resource.Modify on the view's ACL path. Pass `digest` (obtained from a prior GET) to guard against concurrent edits overwriting each other — omit it only in non-contested automation.",
+  "examples": [
+    {
+      "summary": "Narrow a view to only include specific cluster nodes and persist a saved layout",
+      "path_params": {
+        "id": "prod-cluster"
+      },
+      "params": {
+        "include": ["type=node,remote=pve-prod"],
+        "include-all": false,
+        "layout": "{\"columns\":[\"name\",\"status\",\"cpu\",\"mem\"]}",
+        "digest": "a3f1c2d4e5b6a7f8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` array to remove individual properties (e.g., `\"delete\": [\"exclude\"]`) rather than overwriting them with empty values.",
+    "The `layout` field is an opaque JSON string as stored by the PDM UI — capture it from a GET response to avoid format mismatches.",
+    "Setting `include-all: true` makes `include` rules additive exceptions rather than the sole whitelist; combine with `exclude` to blacklist noisy resource types.",
+    "View names are immutable after creation; to rename, create a new view and delete the old one."
+  ],
+  "relatedOperations": [
+    "get_config_views_id",
+    "post_config_views",
+    "delete_config_views_id",
+    "get_config_views"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_nodes_node_apt_repositories.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_nodes_node_apt_repositories",
+  "usageNotes": "Use this endpoint to add or re-enable a standard Proxmox-defined APT repository on a target node by its handle string (e.g. 'pve-no-subscription', 'pbs-enterprise'). If the repository is already present but disabled, calling this re-enables it rather than creating a duplicate entry. Pass the current config digest to guard against concurrent modifications — obtain the digest first via GET /nodes/{node}/apt/repositories.",
+  "examples": [
+    {
+      "summary": "Enable the no-subscription Proxmox Datacenter Manager repository on a node",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "handle": "pdm-no-subscription",
+        "digest": "a3f1e2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
+      }
+    }
+  ],
+  "tips": [
+    "Fetch the current digest with GET /nodes/{node}/apt/repositories before writing, then pass it in the request to prevent race conditions.",
+    "The 'handle' refers to Proxmox-defined standard repository identifiers — it is not a free-form URL or sources.list entry. Only handles recognized by the PDM node are valid.",
+    "After adding or enabling a repository, run GET /nodes/{node}/apt/update (or POST to trigger an apt-get update) so the package index reflects the newly enabled source.",
+    "The node must be online and reachable by PDM; this call operates directly on that node's APT configuration."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_repositories",
+    "post_nodes_node_apt_repositories",
+    "post_nodes_node_apt_update"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_nodes_node_certificates_acme_certificate.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_nodes_node_certificates_acme_certificate",
+  "usageNotes": "Renews the ACME (Let's Encrypt) TLS certificate on a PDM node; by default only proceeds if the certificate expires within 30 days, so pass force=true to renew immediately regardless of expiry. The call returns a UPID — poll the task log with the tasks API to confirm success before relying on the new certificate. Requires System.Modify on the node and a working ACME account/domain config already in place.",
+  "examples": [
+    {
+      "summary": "Force-renew the ACME certificate on node 'pdm1' immediately",
+      "path_params": {
+        "node": "pdm1"
+      },
+      "params": {
+        "force": true
+      }
+    }
+  ],
+  "tips": [
+    "Without force=true, the API is a no-op if the certificate has more than 30 days remaining — check the returned UPID task log to confirm whether renewal actually ran.",
+    "ACME account and domain must be configured on the node before calling this endpoint; use the ACME account/plugin APIs to set those up first.",
+    "API tokens are permitted (allowtoken: true), making this safe to call from automation scripts without interactive credentials.",
+    "After renewal, services using the PDM TLS certificate (web UI, API) will pick up the new cert on the next connection — no manual service restart required."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_certificates_acme_certificate",
+    "delete_nodes_node_certificates_acme_certificate",
+    "get_nodes_node_certificates_acme_account",
+    "get_nodes_node_certificates_info"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_nodes_node_config.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "put_nodes_node_config",
+  "usageNotes": "Use this endpoint to update node-level settings such as the API server's TLS cipher suites, the UI default language, a notification email address, or an outbound HTTP proxy. All parameters are optional and only the fields you supply are changed; omit a field to leave it unchanged or pass it in 'delete' to revert it to the system default. Requires the System.Modify privilege on /system.",
+  "examples": [
+    {
+      "summary": "Set an outbound HTTP proxy and notification email for a node",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "http-proxy": "http://proxy.nightsquawk.tech:3128",
+        "email-from": "alerts@nightsquawk.tech"
+      }
+    }
+  ],
+  "tips": [
+    "Pass the 'digest' field (SHA256 of the current config) to guard against concurrent modifications — the call fails if another process modified the config between your read and write.",
+    "To revert a setting to its default, include the property name in the 'delete' array rather than leaving it blank.",
+    "TLS cipher changes take effect after the PDM API service restarts; they do not apply to already-established connections.",
+    "Use 'localhost' as the node name when calling from the node itself, but always use the actual node name when calling from a remote client to avoid ambiguity."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_config"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_nodes_node_dns.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "put_nodes_node_dns",
+  "usageNotes": "Use this to update the DNS resolver configuration (nameservers and search domain) for a specific PDM node; changes take effect immediately on the node's /etc/resolv.conf without a reboot. The caller must hold System.Modify on the node's system/network/dns ACL path. Pass the digest from get_nodes_node_dns to guard against concurrent modifications — the call will fail if the config has changed since you last read it.",
+  "examples": [
+    {
+      "summary": "Set primary and secondary DNS servers with a search domain on a node",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "dns1": "1.1.1.1",
+        "dns2": "8.8.8.8",
+        "search": "nightsquawk.tech"
+      }
+    }
+  ],
+  "tips": [
+    "All DNS parameters are optional — omit any you do not want to change, or use the 'delete' array to remove dns2/dns3/search without touching the others.",
+    "IPv6 nameserver addresses are accepted; the validation pattern covers both IPv4 and IPv6 formats.",
+    "The 'options' field maps to freeform lines in resolv.conf (e.g. 'timeout:2 attempts:3') — use sparingly and only for content you would manually place in that file.",
+    "Returns null on success; any error (bad IP format, wrong digest, insufficient privilege) surfaces as an HTTP 4xx response."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_dns"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_nodes_node_network",
+  "usageNotes": "Reloads the network configuration on a PDM-managed node by applying any pending interface changes without a full reboot; requires ifupdown2 to be installed on the target node. Returns a UPID (async task identifier) — poll the task status to confirm the reload completed successfully. The caller must hold System.Modify on /system/network/interfaces.",
+  "examples": [
+    {
+      "summary": "Reload network config on node 'pdm1' after editing an interface",
+      "path_params": {
+        "node": "pdm1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "ifupdown2 must be installed on the node; without it the call will fail with an error even though the API accepts the request.",
+    "The returned UPID can be polled via the tasks endpoint to verify the reload finished without errors before assuming connectivity is restored.",
+    "Briefly interrupts active network interfaces during the reload — avoid during maintenance windows that require uninterrupted connectivity.",
+    "Use 'localhost' as the node name only when the API call originates directly on that node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "post_nodes_node_network",
+    "delete_nodes_node_network_iface",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "put_nodes_node_network_iface",
+  "usageNotes": "Use this endpoint to modify an existing network interface configuration on a PDM-managed node — for example, changing the IP address, gateway, MTU, or bridge ports of an already-created interface. Changes are written to the node's network config file but are not applied to the live system until the node is rebooted or the network is reloaded (use the apply endpoint afterward). Supply the `digest` param from a prior GET to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Set a static IPv4 address and gateway on a Linux bridge interface, with VLAN awareness enabled",
+      "path_params": {
+        "node": "pdm-node1",
+        "iface": "vmbr0"
+      },
+      "params": {
+        "type": "bridge",
+        "method": "static",
+        "cidr": "10.10.1.10/24",
+        "gateway": "10.10.1.1",
+        "bridge_ports": "eth0",
+        "bridge_vlan_aware": true,
+        "autostart": true,
+        "mtu": 1500
+      }
+    }
+  ],
+  "tips": [
+    "Changes are staged in the network config file; they do not take effect until the network is reloaded or the node reboots. Follow up with the network apply/reload endpoint if live activation is needed.",
+    "Fetch the current config first (GET /nodes/{node}/network/{iface}) and pass its `digest` value to detect and reject concurrent modifications.",
+    "The `delete` param accepts a list of property names to remove from the config (e.g., removing a gateway or MTU override), avoiding the need to null-out fields individually.",
+    "For bond interfaces, `bond_xmit_hash_policy` is only meaningful when `bond_mode` is `802.3ad` (LACP); setting it on other modes has no effect.",
+    "Interface names are capped at 15 characters — the same AD/hostname constraint that applies to server naming in this environment."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network_iface",
+    "post_nodes_node_network",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "put_nodes_node_time",
+  "usageNotes": "Use this to set or correct the system timezone on a specific PDM node. The timezone value must be a valid IANA timezone name as listed in '/usr/share/zoneinfo/zone.tab' on the node (e.g., 'America/Los_Angeles', 'UTC'). Requires the System.Modify privilege on the node; the change is applied immediately and synchronously (returns null, not a UPID).",
+  "examples": [
+    {
+      "summary": "Set a PDM node's timezone to US Pacific time",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "timezone": "America/Los_Angeles"
+      }
+    }
+  ],
+  "tips": [
+    "Valid timezone names come from the IANA tz database; check '/usr/share/zoneinfo/zone.tab' on the node if unsure of the exact string.",
+    "This endpoint applies the change immediately — no reboot required — but services that cache the system clock offset may need a restart to pick up the new zone.",
+    "Use 'localhost' as the node value when calling this endpoint directly on the node that is running the API."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_time"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_pve_remotes_remote_firewall_options.json

@@ -0,0 +1,34 @@
+{
+  "operationId": "put_pve_remotes_remote_firewall_options",
+  "usageNotes": "Use this to update cluster-wide firewall settings on a remote PVE cluster, such as enabling/disabling the firewall, changing default inbound/outbound/forward policies, or adjusting log rate-limiting. Requires `System.Modify` on the remote resource — API tokens are supported. Always fetch the current digest via the corresponding GET endpoint and pass it in the `digest` field to guard against concurrent modifications.",
+  "examples": [
+    {
+      "summary": "Enable the cluster firewall with DROP inbound/outbound defaults and conservative log rate-limiting",
+      "path_params": {
+        "remote": "pve-hetzner"
+      },
+      "params": {
+        "enable": 1,
+        "ebtables": true,
+        "policy_in": "DROP",
+        "policy_out": "DROP",
+        "policy_forward": "DROP",
+        "log_ratelimit": "enable=1,burst=10,rate=5/second",
+        "digest": "a3f8c21d9b4e7f0612345678abcdef90abcdef01"
+      }
+    }
+  ],
+  "tips": [
+    "Setting `enable` to 0 (the default) disables the cluster firewall entirely — this overrides all per-host and per-VM firewall rules on the remote cluster.",
+    "The `delete` array accepts option key names (e.g. `[\"policy_in\", \"log_ratelimit\"]`) to reset them to their defaults rather than requiring you to know the default value.",
+    "Changing `policy_in` or `policy_out` to DROP without first confirming rule coverage can cut off management access to the remote cluster.",
+    "The endpoint returns null on success — absence of an error is the confirmation.",
+    "Log rate-limiting (`log_ratelimit`) is encoded as a comma-separated key=value string matching the typetext format: `enable=<1|0> [,burst=<integer>] [,rate=<string>]`."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_firewall_options",
+    "get_pve_remotes_remote_firewall_rules",
+    "put_pve_remotes_remote_firewall_rules_pos",
+    "get_pve_remotes_remote_firewall_groups"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_pve_remotes_remote_lxc_vmid_firewall_options.json

@@ -0,0 +1,37 @@
+{
+  "operationId": "put_pve_remotes_remote_lxc_vmid_firewall_options",
+  "usageNotes": "Use this to enable, disable, or tune the per-container firewall for an LXC guest on a remote PVE node via PDM. The firewall is inactive by default (enable=false); you must explicitly set enable=true for rules to take effect. Supply a digest from the current options read to guard against concurrent modifications — omitting it skips the conflict check.",
+  "examples": [
+    {
+      "summary": "Enable the container firewall with DROP default policies, DHCP allowed, and info-level inbound logging",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 110
+      },
+      "params": {
+        "enable": true,
+        "dhcp": true,
+        "policy_in": "DROP",
+        "policy_out": "ACCEPT",
+        "log_level_in": "info",
+        "macfilter": true,
+        "ndp": true,
+        "ipfilter": false
+      }
+    }
+  ],
+  "tips": [
+    "Firewall rules are silently ignored until enable=true is set — verify this flag if traffic is not being filtered as expected.",
+    "ipfilter=true on containers automatically populates ipset entries with the container's configured IP addresses, preventing IP spoofing without manual ipset management.",
+    "macfilter defaults to true; disabling it can allow MAC spoofing from within the container, so only disable for specific bridging or migration scenarios.",
+    "Use the delete array to revert individual settings to their defaults rather than overwriting the entire config — e.g., delete=[\"log_level_in\"] to stop logging without touching other options.",
+    "ndp=true is required for IPv6 neighbor discovery to work in containers; disabling it will break IPv6 connectivity even when rules otherwise permit it."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_firewall_options",
+    "get_pve_remotes_remote_lxc_vmid_firewall_rules",
+    "post_pve_remotes_remote_lxc_vmid_firewall_rules",
+    "get_pve_remotes_remote_lxc_vmid_firewall_ipsets",
+    "put_pve_remotes_remote_qemu_vmid_firewall_options"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_pve_remotes_remote_lxc_vmid_snapshot_snapname_config.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_pve_remotes_remote_lxc_vmid_snapshot_snapname_config",
+  "usageNotes": "Use this to annotate or correct the description on an existing LXC snapshot hosted on a remote PVE node — useful after an ad-hoc snapshot is taken without a description, or when the purpose of a snapshot changes. The operation is synchronous and returns null immediately (no UPID/task to poll). Requires the Resource.Manage privilege on the remote's guest resource path.",
+  "examples": [
+    {
+      "summary": "Add a description to a pre-update snapshot on a remote LXC container",
+      "path_params": {
+        "remote": "hetzner-pve1",
+        "vmid": 102,
+        "snapname": "pre-update-20260629"
+      },
+      "params": {
+        "description": "Snapshot taken before apt upgrade on 2026-06-29. Safe to delete after 7 days if no issues.",
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "The description field accepts free-form text and is the only editable field on a snapshot via this endpoint — snapshot name and content are immutable after creation.",
+    "Omitting the 'node' param lets PDM infer the node; supply it explicitly if the remote has multiple nodes to avoid ambiguity.",
+    "snapname must match an existing snapshot exactly (case-sensitive, same pattern as creation); verify available snapshots first via the corresponding GET endpoint."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_snapshot_snapname_config",
+    "get_pve_remotes_remote_lxc_vmid_snapshot",
+    "post_pve_remotes_remote_lxc_vmid_snapshot",
+    "delete_pve_remotes_remote_lxc_vmid_snapshot_snapname"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_pve_remotes_remote_nodes_node_firewall_options.json

@@ -0,0 +1,36 @@
+{
+  "operationId": "put_pve_remotes_remote_nodes_node_firewall_options",
+  "usageNotes": "Use this to update host-level firewall settings (enable/disable, log levels, conntrack tuning, synflood protection) on a specific PVE node managed through PDM. The caller must hold Resource.Modify on the remote; supply the digest returned by the corresponding GET to prevent overwriting concurrent changes. Returns null synchronously — there is no UPID; the change takes effect immediately on the target node.",
+  "examples": [
+    {
+      "summary": "Enable the node firewall with synflood protection and warning-level inbound logging",
+      "path_params": {
+        "remote": "prod-pve01",
+        "node": "pve-htz-01"
+      },
+      "params": {
+        "enable": true,
+        "protection_synflood": true,
+        "protection_synflood_rate": 200,
+        "protection_synflood_burst": 1000,
+        "log_level_in": "warning",
+        "log_level_out": "nolog",
+        "log_level_forward": "nolog"
+      }
+    }
+  ],
+  "tips": [
+    "Always fetch the current options first (GET firewall/options) and pass the returned digest to guard against concurrent edits.",
+    "Setting enable=false disables ALL host firewall rules on that node — existing VM/CT rules are unaffected but the node itself becomes unprotected.",
+    "nftables is a tech-preview feature; do not enable it on production nodes unless you have tested compatibility with your PVE version.",
+    "Use the delete array to revert individual settings to their defaults rather than explicitly setting them — this avoids stale values persisting in the config file.",
+    "nf_conntrack_max default (262144) can be exhausted on busy hypervisors with many VMs; raise it before seeing 'table full' kernel warnings.",
+    "nf_conntrack_helpers should only list protocols actually in use; enabling unnecessary helpers (e.g., sip, pptp) widens the attack surface."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_firewall_options",
+    "get_pve_remotes_remote_nodes_node_firewall_rules",
+    "post_pve_remotes_remote_nodes_node_firewall_rules",
+    "put_pve_remotes_remote_nodes_node_firewall_rules_pos"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_pve_remotes_remote_qemu_vmid_firewall_options.json

@@ -0,0 +1,35 @@
+{
+  "operationId": "put_pve_remotes_remote_qemu_vmid_firewall_options",
+  "usageNotes": "Use this to enable or adjust the per-VM firewall and its behavior on a PVE remote managed by PDM. The firewall must first be enabled via `enable: true` before any rules take effect; toggling options on a disabled firewall has no live impact. Pass `digest` (retrieved from the corresponding GET) to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Enable the VM firewall with DROP default policies, info-level inbound logging, and IP filters on",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 101
+      },
+      "params": {
+        "enable": true,
+        "policy_in": "DROP",
+        "policy_out": "ACCEPT",
+        "log_level_in": "info",
+        "ipfilter": true,
+        "dhcp": false,
+        "macfilter": true,
+        "ndp": true
+      }
+    }
+  ],
+  "tips": [
+    "Enabling `ipfilter` without adding explicit IP addresses to the corresponding ipfilter-net ipset will still apply sane default restrictions (MAC-derived IPv6 link-local), but no custom allow rules — verify behavior before applying to production VMs.",
+    "The `delete` array accepts field names (e.g. `[\"policy_in\", \"log_level_out\"]`) to reset individual options back to their defaults without sending a full config payload.",
+    "Returns null on success; any non-2xx response indicates failure — check PDM logs for detail since no error body is guaranteed.",
+    "The `node` param is optional; omit it to let PDM resolve the VM's current node automatically via the remote cluster state."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_firewall_options",
+    "get_pve_remotes_remote_qemu_vmid_firewall_rules",
+    "post_pve_remotes_remote_qemu_vmid_firewall_rules",
+    "get_pve_remotes_remote_qemu_vmid_firewall_ipsets"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_pve_remotes_remote_qemu_vmid_snapshot_snapname_config.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_pve_remotes_remote_qemu_vmid_snapshot_snapname_config",
+  "usageNotes": "Use this to update the human-readable description on an existing QEMU VM snapshot managed by a PDM remote. This is one of the few snapshot operations that is fully synchronous — it returns null immediately with no UPID or task to poll. The caller must hold Resource.Manage on the remote/VM resource path.",
+  "examples": [
+    {
+      "summary": "Add a description to a pre-upgrade snapshot on a remote VM",
+      "path_params": {
+        "remote": "hetzner-pve1",
+        "vmid": 105,
+        "snapname": "pre-upgrade-2026-06"
+      },
+      "params": {
+        "description": "Taken before upgrading Ubuntu 22.04 to 24.04 on 2026-06-29.",
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "This endpoint only updates the description field — snapshot content, RAM state, and disk state cannot be changed after creation.",
+    "Omitting the node parameter lets PDM resolve the host automatically; supply it when targeting a specific node in a cluster.",
+    "Snapshot names follow the same alphanumeric-plus-dot-dash-underscore pattern as remote IDs — spaces are not allowed."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_snapshot_snapname_config",
+    "get_pve_remotes_remote_qemu_vmid_snapshot",
+    "post_pve_remotes_remote_qemu_vmid_snapshot",
+    "delete_pve_remotes_remote_qemu_vmid_snapshot_snapname"
+  ]
+}

package/dist/catalog-pdm/enrichment/put_remotes_remote_id.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "put_remotes_remote_id",
+  "usageNotes": "Use this to update an existing PDM remote's configuration — credentials, cluster node addresses, auth token, or web URL — without recreating it. Requires the `Resource.Modify` privilege on the specific remote resource. Pass the `digest` field (from a prior GET) to guard against concurrent modifications overwriting each other; if the stored digest differs from what you submit, the update is rejected.",
+  "examples": [
+    {
+      "summary": "Rotate the API token secret for a managed PVE remote",
+      "path_params": {
+        "id": "pve-prod"
+      },
+      "params": {
+        "authid": "root@pam!automation",
+        "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "digest": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+      }
+    }
+  ],
+  "tips": [
+    "The `delete` array lets you unset optional properties (e.g. `web-url`) without touching the rest of the config.",
+    "Remote IDs are 2–32 characters and must match the pattern [A-Za-z0-9_][A-Za-z0-9._-]*; plan the ID at creation time since renaming requires delete-and-recreate.",
+    "Returns null on success — a 200 with no body is the expected response; treat any non-2xx as a failure.",
+    "The `nodes` array should list the Proxmox cluster node addresses that this remote exposes; keeping it accurate ensures PDM can reach the correct endpoints."
+  ],
+  "relatedOperations": [
+    "get_remotes_remote_id",
+    "post_remotes",
+    "delete_remotes_remote_id"
+  ]
+}