@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_pve_remotes_remote_nodes_node_apt_update",
+  "usageNotes": "Triggers an `apt-get update` on the specified remote PVE node to refresh its package index; run this before querying available upgrades or installing packages. The operation is asynchronous — the response is a remote UPID that must be polled for completion status before acting on the updated package list. The caller requires the `Resource.Modify` privilege on the target remote/node/system path.",
+  "examples": [
+    {
+      "summary": "Refresh APT package index on node pve1 of the prod-cluster remote",
+      "path_params": {
+        "remote": "prod-cluster",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned UPID is a 'remote UPID' (minimum 42 chars) — use the appropriate task-status endpoint to poll completion before querying apt/versions or triggering an upgrade.",
+    "Node name accepts 'localhost' as a special value when PDM itself is the target node.",
+    "No body parameters are required; send an empty JSON object ({}) as the request body."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_apt_versions",
+    "post_pve_remotes_remote_nodes_node_apt_upgrade",
+    "get_pve_remotes_remote_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_pve_remotes_remote_nodes_node_termproxy",
+  "usageNotes": "Use this to open a terminal (shell) session to a PVE node managed by PDM. The call returns a short-lived VNC/WebSocket ticket that must be used immediately to upgrade an HTTP connection to a terminal websocket — it is not an async job and returns no UPID. Requires the Sys.Console privilege on the target remote+node combination, so API tokens must be scoped accordingly.",
+  "examples": [
+    {
+      "summary": "Open a terminal session to node 'pve1' on remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned port is always 0 — use the ticket value directly for the WebSocket handshake; no separate port binding is needed.",
+    "Tickets are single-use and short-lived; consume the ticket immediately after receiving it.",
+    "The node value accepts 'localhost' to target the PDM host's local PVE instance."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node",
+    "get_pve_remotes_remote_nodes"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_migrate",
+  "usageNotes": "Triggers an in-cluster live or offline migration of a QEMU VM on the specified PDM-managed remote; the only required body param is `target` (destination node name). Returns a remote UPID string representing the async task — poll that UPID via the task-status endpoint to detect completion or failure. Use `online: true` to migrate a running VM with minimal downtime, and set `with-local-disks: true` plus `target-storage` mappings when the VM has disks on node-local storage that must follow the VM to the target node.",
+  "examples": [
+    {
+      "summary": "Online migrate a running VM (VMID 105) to node pve-node2 on remote prod-cluster, carrying its local disk to the target's local-lvm storage",
+      "path_params": {
+        "remote": "prod-cluster",
+        "vmid": 105
+      },
+      "params": {
+        "target": "pve-node2",
+        "online": true,
+        "with-local-disks": true,
+        "target-storage": ["local-lvm"],
+        "migration-type": "secure",
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "destructiveReason": "Migration moves the VM's runtime state and disk data off the source node; if it fails mid-transfer the VM may be left in a degraded or locked state requiring manual recovery.",
+  "tips": [
+    "The return value is a remote UPID (min 42 chars) — treat it as an opaque task handle and poll task status; do not assume the migration is done when the POST returns.",
+    "Omitting `online` (or setting it false) requires the VM to be stopped before migration; the call will fail on a running VM unless `online: true` is passed.",
+    "Setting `migration-type: insecure` disables SSH tunnel encryption and can significantly increase throughput on isolated internal networks where latency matters.",
+    "`force: true` is needed when the VM has passthrough/local devices (e.g. PCI passthrough); without it the API will reject the request outright.",
+    "Specify `migration-network` as a CIDR (e.g. 10.0.10.0/24) to force migration traffic onto a dedicated storage/migration VLAN instead of the management interface.",
+    "The `node` param identifies the *source* node when the remote is a cluster and the VM's current node is ambiguous; omit it if PDM can infer the source automatically."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_migrate",
+    "get_pve_remotes_remote_qemu",
+    "get_pve_remotes_remote_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_remote_migrate",
+  "usageNotes": "Use this endpoint to migrate a QEMU VM from one PDM-managed remote to another remote cluster. Both the source remote and target remote must be configured and reachable in PDM, and the caller requires Resource.Migrate on the source guest path for both source and target. The operation is asynchronous — it returns a remote UPID string (min 42 chars) that must be polled for completion status; set 'online: true' only when the VM is running and downtime is unacceptable, and always provide explicit target-bridge and target-storage mappings since there is no automatic network/storage name matching across clusters.",
+  "examples": [
+    {
+      "summary": "Offline migrate VM 105 from remote 'pve-hetzner' to remote 'pve-ovh', remapping storage and bridge, with source VM deleted on success",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 105
+      },
+      "params": {
+        "target": "pve-ovh",
+        "target-bridge": ["vmbr0=vmbr0"],
+        "target-storage": ["local-lvm=local-lvm"],
+        "target-vmid": 105,
+        "delete": true,
+        "online": false,
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "tips": [
+    "The returned UPID is a *remote* UPID — poll the source remote's task endpoint, not the local PDM task endpoint.",
+    "target-bridge and target-storage accept array entries in 'source=destination' mapping format; every disk and NIC used by the VM must have a mapping or migration will fail.",
+    "Set bwlimit (KiB/s) during business hours to avoid saturating the WAN link between clusters; 0 means unlimited.",
+    "If target-vmid is omitted, PDM will attempt to preserve the source VMID on the destination cluster — ensure it is not already in use on the target.",
+    "online migration across remote clusters requires SPICE/VNC console sessions to be interrupted briefly during final sync; warn users before triggering."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid",
+    "get_pve_remotes_remote_qemu",
+    "get_pve_remotes",
+    "post_pve_remotes_remote_lxc_vmid_remote_migrate"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_resume",
+  "usageNotes": "Use this to resume a QEMU VM on a remote PVE node that is currently in a paused or suspended (RAM-suspended) state. The operation is asynchronous and returns a remote UPID that should be polled for task completion before assuming the VM is running. The caller must hold Resource.Manage on the remote/VM resource path; the optional 'node' body parameter can pin execution to a specific cluster node if the remote is a cluster.",
+  "examples": [
+    {
+      "summary": "Resume a suspended VM (VMID 105) on remote 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 105
+      },
+      "params": {
+        "node": "pve01"
+      }
+    }
+  ],
+  "tips": [
+    "The returned UPID is scoped to the remote PVE node — use a PDM task-status endpoint (not a local PVE endpoint) to poll it.",
+    "Omit 'node' when the remote is a standalone host; supply it when the remote is a cluster to avoid ambiguous node selection.",
+    "A VM must be in 'paused' or 'suspended' power state for this call to succeed; attempting to resume a running or stopped VM will return an error from the remote."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_qemu_vmid_suspend",
+    "get_pve_remotes_remote_qemu_vmid_status_current",
+    "get_pve_remotes_remote_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_shutdown",
+  "usageNotes": "Sends an ACPI shutdown signal to a remote QEMU VM — equivalent to pressing the power button, allowing the guest OS to shut down gracefully. Returns a remote UPID that must be polled to confirm completion; the call returns immediately and does not wait for the guest to finish shutting down. Requires Resource.Manage privilege on the remote+vmid combination; the VM must be in a running state on the target PVE remote.",
+  "examples": [
+    {
+      "summary": "Gracefully shut down VM 105 on the prod-hetzner remote",
+      "path_params": {
+        "remote": "prod-hetzner",
+        "vmid": 105
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "destructiveReason": "Initiates a guest OS shutdown, which stops all running services and workloads on the VM; if the guest ignores the ACPI signal or hangs, the VM remains in a transitional state until manually killed.",
+  "tips": [
+    "Poll the returned UPID via the task-status endpoint to determine when the shutdown has actually completed before taking follow-up actions (migrate, snapshot, etc.).",
+    "The 'node' body param is optional — omit it to let PDM resolve the node automatically, or supply it to target a specific PVE cluster node when the VM could be on multiple nodes.",
+    "This sends an ACPI signal (graceful); use the stop endpoint instead if the guest is unresponsive and you need a hard power-off.",
+    "Token-based auth is supported (allowtoken: true), making this safe to call from automation without interactive credentials."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_qemu_vmid_stop",
+    "post_pve_remotes_remote_qemu_vmid_start",
+    "post_pve_remotes_remote_qemu_vmid_reboot",
+    "get_pve_remotes_remote_qemu_vmid_status"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_snapshot",
+  "usageNotes": "Use this to take a point-in-time snapshot of a remote QEMU VM via PDM without needing direct PVE API access. The operation is asynchronous — the response is a remote UPID string that must be polled for completion status. Omitting 'vmstate' (default false) produces a disk-only snapshot; set it to true only when you need to resume the VM exactly from its running state, as RAM capture significantly increases snapshot time and disk usage.",
+  "examples": [
+    {
+      "summary": "Create a pre-upgrade disk-only snapshot of VM 105 on the production-pve remote",
+      "path_params": {
+        "remote": "production-pve",
+        "vmid": 105
+      },
+      "params": {
+        "snapname": "pre-upgrade-2026",
+        "description": "Snapshot before OS upgrade on 2026-06-29",
+        "node": "pve01",
+        "vmstate": false
+      }
+    }
+  ],
+  "tips": [
+    "snapname must start with a letter or digit and contain only alphanumeric, dot, underscore, or hyphen characters — max 40 chars.",
+    "If 'node' is omitted, PDM resolves the VM's current node automatically; supply it to be explicit in clusters with live migration.",
+    "RAM-state snapshots (vmstate: true) require the VM to be running and roughly double the storage footprint of the snapshot.",
+    "Poll the returned remote UPID against the task-status endpoint to confirm the snapshot completed before proceeding with destructive operations."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_snapshot",
+    "delete_pve_remotes_remote_qemu_vmid_snapshot_snapname",
+    "post_pve_remotes_remote_qemu_vmid_snapshot_snapname_rollback"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_snapshot_snapname_rollback",
+  "usageNotes": "Rolls back a remote QEMU VM to a named snapshot, reverting its disk, config, and RAM state (if RAM was captured in the snapshot); the guest must be shut down before calling this unless the snapshot includes RAM state. Returns a remote UPID string representing the async task — poll the task status endpoint to confirm completion before treating the rollback as done. Requires Resource.Manage privilege on the remote/VM resource.",
+  "examples": [
+    {
+      "summary": "Roll back VM 105 on remote 'pve-hetzner' to snapshot 'pre-update' and start the guest after",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 105,
+        "snapname": "pre-update"
+      },
+      "params": {
+        "node": "pve1",
+        "start": true
+      }
+    }
+  ],
+  "destructiveReason": "All disk and configuration changes made after the snapshot was taken are permanently discarded; if the snapshot does not include RAM state, any in-memory data at snapshot time is also lost.",
+  "tips": [
+    "Take a fresh snapshot of the current state before rolling back if there is any chance you need to recover post-snapshot changes.",
+    "If 'node' is omitted, PDM selects an appropriate node automatically; specify it explicitly when the VM is on a specific cluster node to avoid ambiguity.",
+    "The returned UPID is scoped to the remote cluster — use the corresponding PDM task-status endpoint (not a local PVE node endpoint) to track it.",
+    "Snapshots with RAM state allow rollback while the VM is running, but this is rare and risky; prefer rolling back with the VM stopped."
+  ],
+  "relatedOperations": [
+    "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/post_pve_remotes_remote_qemu_vmid_start.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_start",
+  "usageNotes": "Use this to power on a stopped or suspended QEMU VM managed by a PDM-registered PVE remote. Requires Resource.Manage privilege on the target remote/VM resource path. Returns a remote UPID string — the VM start is asynchronous, so poll the task status endpoint with that UPID to confirm the VM reached a running state before taking dependent actions.",
+  "examples": [
+    {
+      "summary": "Start VM 101 on the prod-pve remote, pinned to a specific node",
+      "path_params": {
+        "remote": "prod-pve",
+        "vmid": 101
+      },
+      "params": {
+        "node": "pve-node1"
+      }
+    }
+  ],
+  "tips": [
+    "The 'node' body param is optional — omit it to let PDM resolve the VM's current node automatically via the remote cluster.",
+    "The returned UPID is a remote UPID (prefixed for the PDM remote), not a local PVE UPID; use the PDM task-status endpoint, not the PVE node tasks endpoint, to poll it.",
+    "If the VM has a pending snapshot or lock on the source PVE cluster, the start will fail immediately at the PVE side and the UPID will reflect a failed task."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_qemu_vmid_stop",
+    "post_pve_remotes_remote_qemu_vmid_shutdown",
+    "get_pve_remotes_remote_qemu_vmid_status",
+    "get_pve_remotes_remote_qemu"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_pve_remotes_remote_qemu_vmid_stop",
+  "usageNotes": "Performs a hard stop (equivalent to pulling the power cord) on a QEMU VM running on a remote PVE node managed by PDM — all unsaved in-guest state is lost immediately. The caller must hold `Resource.Manage` on the remote/guest ACL path. Returns a remote UPID string; poll the task status endpoint to confirm completion before assuming the VM is fully stopped.",
+  "examples": [
+    {
+      "summary": "Hard-stop VM 105 on remote 'pve-hetzner', letting PDM pick the node",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Immediately cuts power to the VM without a graceful shutdown, discarding any unsaved in-guest data and risking filesystem corruption.",
+  "tips": [
+    "Prefer the shutdown endpoint when the guest OS is responsive — stop is a last resort for hung or unresponsive VMs.",
+    "The returned UPID is scoped to the remote PVE cluster; use the corresponding remote task-status endpoint (not a local PVE endpoint) to poll it.",
+    "If `node` is omitted, PDM resolves the current host node automatically — supply it explicitly if the VM might be in the middle of a migration."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_qemu_vmid_shutdown",
+    "post_pve_remotes_remote_qemu_vmid_start",
+    "post_pve_remotes_remote_qemu_vmid_reset",
+    "get_pve_remotes_remote_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_pve_scan",
+  "usageNotes": "Use this before creating a PVE remote to discover cluster topology and verify connectivity — it returns node addresses and probes each node's TLS so you can confirm whether a fingerprint is required. Requires System.Modify at the root path. If the target PVE uses a self-signed certificate, capture the fingerprint from this response and supply it when calling post_pve_remotes (or the equivalent create endpoint) to avoid TLS verification failures.",
+  "examples": [
+    {
+      "summary": "Scan a two-node PVE cluster using an API token to pre-populate remote config",
+      "path_params": {},
+      "params": {
+        "authid": "root@pam!pdm-scanner",
+        "hostname": "pve1.lab.nightsquawk.tech",
+        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      }
+    }
+  ],
+  "tips": [
+    "The authid format is either 'user@realm' (password auth) or 'user@realm!tokenid' (API token auth); use API token format in automation to avoid embedding passwords.",
+    "The response includes all cluster node addresses — use this list to verify every node is reachable before committing the remote config.",
+    "If TLS probing returns a fingerprint in the response, store it; subsequent PVE remote operations may require it if the cluster uses a self-signed cert.",
+    "This endpoint does not persist any data — it is a read-probe only, safe to call multiple times."
+  ],
+  "relatedOperations": [
+    "post_pve_probe_tls",
+    "get_pve_remotes",
+    "get_pve_remotes_remote"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_remotes_metric_collection_trigger",
+  "usageNotes": "Use this to manually kick off metric collection for one or all registered remotes — useful after adding a new remote or when dashboard metrics appear stale. Omit the `remote` body parameter to collect from every remote simultaneously. Returns null synchronously; there is no UPID to poll — collection happens in the background.",
+  "examples": [
+    {
+      "summary": "Trigger metric collection for a single remote named 'pve-hetzner'",
+      "path_params": {},
+      "params": {
+        "remote": "pve-hetzner"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting the `remote` field triggers collection for all remotes at once — use with care if many remotes are registered, as it may cause a brief spike in API load.",
+    "Remote IDs must be 2–32 characters and match the pattern [A-Za-z0-9_][A-Za-z0-9._-]* — the same ID used when the remote was registered.",
+    "Since the return type is null, success is confirmed by HTTP 200 with an empty body; no task ID is issued."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "post_remotes",
+    "get_remotes_remoteid_metrics"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_remotes_remote",
+  "usageNotes": "Use this endpoint to register a new PVE cluster or PBS instance as a managed remote in Proxmox Datacenter Manager. The caller must hold the Resource.Modify privilege. Supply a pre-created API token via `authid` and `token`, or let PDM create one automatically by providing the `create-token` param — the latter requires the authid credentials to have token-creation rights on the remote.",
+  "examples": [
+    {
+      "summary": "Register a Proxmox VE cluster as a PDM remote using an existing API token",
+      "path_params": {},
+      "params": {
+        "id": "hetzner-pve",
+        "type": "pve",
+        "authid": "root@pam!pdm-monitor",
+        "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "nodes": [
+          "192.168.10.10:8006",
+          "192.168.10.11:8006"
+        ],
+        "web-url": "https://pve.nightsquawk.tech"
+      }
+    }
+  ],
+  "tips": [
+    "The `id` field becomes the stable reference key for this remote across all PDM operations — choose a short, descriptive slug (e.g., 'hetzner-pve', 'ovh-pbs') since it cannot be changed after creation.",
+    "Each entry in `nodes` should be a host:port pair matching the API port of the target cluster node (8006 for PVE, 8007 for PBS).",
+    "If using `create-token`, PDM will call back to the remote to provision the token; the remote must be reachable at registration time and the authid credentials must have the Sys.Audit + User.Modify privileges on the remote.",
+    "Returns null on success (HTTP 200); absence of an error is the confirmation. Use get_remotes_remote to verify the entry was stored."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_remote",
+    "put_remotes_remote",
+    "delete_remotes_remote"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_remotes_remote_id_probe_certificate",
+  "usageNotes": "Use this when a live connection to a remote node fails with an ambiguous TLS error and you suspect the node's certificate has been rotated since the fingerprint was pinned. The probe bypasses the stored fingerprint and returns the current certificate so you can compare it — it never updates the stored pin itself; apply the new fingerprint via update_remote only after explicit user confirmation. Requires Resource.Audit on the remote resource, not a write privilege, so it is safe to run during an outage investigation.",
+  "examples": [
+    {
+      "summary": "Probe the current TLS certificate of a node in a remote named 'hetzner-de'",
+      "path_params": {
+        "id": "hetzner-de"
+      },
+      "params": {
+        "node": "pdm-node01.example.com"
+      }
+    }
+  ],
+  "tips": [
+    "This endpoint returns null — the live certificate data is surfaced in the HTTP response headers or a companion GET; use the result to decide whether to call update_remote with a new fingerprint.",
+    "Run this before concluding a remote is misconfigured; a silently rotated certificate is a common cause of 'connect error' that looks identical to a network failure.",
+    "The remote ID must match the pattern [A-Za-z0-9_][A-Za-z0-9._-]* and be 2–32 characters — validate before calling if building the ID programmatically."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_remote_id",
+    "put_remotes_remote_id"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "post_remotes_tasks_refresh",
+  "usageNotes": "Triggers an async refresh of the cached task list from one or more Proxmox remotes registered in PDM. Returns a UPID string — poll the resulting task to know when the cache is current before querying remote tasks. Omitting the `remotes` body field refreshes all remotes the authenticated user has `Resource.Modify` permission on; supplying a list restricts the refresh to exactly those remotes (each must grant that privilege).",
+  "examples": [
+    {
+      "summary": "Refresh tasks for two specific remotes",
+      "path_params": {},
+      "params": {
+        "remotes": ["pve-hetzner-de1", "pve-ovh-us1"]
+      }
+    }
+  ],
+  "tips": [
+    "With an empty body `{}`, the endpoint silently skips any remote the user lacks Resource.Modify on — no error is raised, those remotes are simply excluded.",
+    "The returned UPID encodes the PDM node, PID, and start time; use it with the PDM task-status endpoint to detect completion before consuming the refreshed data.",
+    "API tokens are supported (allowtoken: true), so automation scripts can trigger refreshes without an interactive session."
+  ],
+  "relatedOperations": [
+    "get_remotes_tasks",
+    "get_resources_tasks"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "post_remotes_updates_refresh",
+  "usageNotes": "Triggers an async re-scan of pending package updates across all configured PDM remotes. Returns a UPID that must be polled for completion before the refreshed data is available. The caller needs Resource.Modify on /resource/{remote} for each remote that should be included in the refresh.",
+  "examples": [
+    {
+      "summary": "Trigger an update-summary refresh for all remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "No body parameters are accepted; send an empty JSON object ({}) or omit the body.",
+    "Poll the returned UPID via the PDM tasks API to determine when the refresh completes before querying update summaries.",
+    "Remotes that are offline or unreachable at refresh time will simply not update; no error is raised for individual failures."
+  ],
+  "relatedOperations": [
+    "get_remotes_updates",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_sdn_vnets",
+  "usageNotes": "Creates a new SDN VNet across one or more PVE remotes managed by PDM; each entry in the `remotes` array specifies the remote and the zone in which the VNet should be provisioned. The operation is asynchronous — the response is a UPID that must be polled to confirm completion before the VNet is usable. If `tag` is supplied it sets the VXLAN VNI (1–16777215); omit it only when the zone assigns VNIs automatically.",
+  "examples": [
+    {
+      "summary": "Create VNet 'prod10' with VXLAN VNI 10010 on two PVE remotes in their respective EVPN zones",
+      "path_params": {},
+      "params": {
+        "vnet": "prod10",
+        "tag": 10010,
+        "remotes": [
+          { "remote": "pve-hetzner", "zone": "evpn-zone" },
+          { "remote": "pve-ovh", "zone": "evpn-zone" }
+        ]
+      }
+    }
+  ],
+  "tips": [
+    "Poll the returned UPID against the PDM tasks API to detect failures before assuming the VNet is live.",
+    "VNet names must satisfy the SDN object naming rules (letters, digits, hyphens; typically ≤8 chars for PVE compatibility).",
+    "Each remote in the array must already be registered in PDM and reachable; an unreachable remote will cause the task to fail for that remote.",
+    "After creation, use get_sdn_vnets with `pending=true` to verify the VNet is in 'new' state and then check the running config once the task completes."
+  ],
+  "relatedOperations": [
+    "get_sdn_vnets",
+    "get_nodes_node_sdn_vnets_vnet",
+    "get_pve_remotes_remote_nodes_node_sdn_vnets_vnet"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_sdn_zones",
+  "usageNotes": "Use this to create an SDN zone that is deployed across one or more Proxmox remotes managed by the Datacenter Manager. The zone name must conform to the SDN object naming rules (alphanumeric, used as an identifier across the fabric). Returns a UPID — poll the task API to confirm completion before creating VNets in the zone.",
+  "examples": [
+    {
+      "summary": "Create a VXLAN-backed zone on two remotes",
+      "path_params": {},
+      "params": {
+        "zone": "vxlan-prod",
+        "remotes": [
+          { "remote": "hetzner-de", "controller": "evpn-ctrl-01" },
+          { "remote": "ovh-us", "controller": "evpn-ctrl-01" }
+        ],
+        "vrf-vxlan": 10001
+      }
+    }
+  ],
+  "tips": [
+    "The returned UPID is asynchronous — wait for task success before creating VNets or subnets in the new zone.",
+    "Zone names are cluster-wide identifiers; choose a name that is unique across all remotes in the fabric to avoid conflicts.",
+    "vrf-vxlan is optional but required when using EVPN/VRF routing; valid range is 1–16777215 (24-bit VNI space).",
+    "Each entry in the remotes array should specify both the remote name and the controller responsible for that remote."
+  ],
+  "relatedOperations": [
+    "get_sdn_zones",
+    "put_sdn_zones_zone",
+    "delete_sdn_zones_zone",
+    "post_sdn_vnets"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_subscriptions_adopt_all",
+  "usageNotes": "Use this to bulk-import all untracked live subscription keys from every auditable remote into the PDM subscription pool in a single transaction. Requires `System.Modify` on the system path; additionally, the caller must hold `PRIV_RESOURCE_MODIFY` on each individual remote for that remote's subscriptions to be adopted — remotes where that privilege is absent are silently skipped rather than treated as errors. Pass a `digest` to guard against concurrent pool modifications racing with the bulk import.",
+  "examples": [
+    {
+      "summary": "Adopt all eligible foreign subscriptions with a concurrency guard",
+      "path_params": {},
+      "params": {
+        "digest": "a3c2e1f4b8d6e0912345678901234567890123456789012345678901234567ab"
+      }
+    }
+  ],
+  "tips": [
+    "Returns only the entries that were newly adopted; already-pooled or skipped keys are not included — a short list does not mean nothing was found.",
+    "Keys already in the pool but bound to a different node are intentionally skipped to prevent silent rebinding; resolve conflicts with the per-subscription update endpoint before retrying.",
+    "Keys that fail pattern validation (prefix unknown or length out of range) are dropped silently — inspect remote node health if expected keys do not appear in the response.",
+    "The operation is synchronous and returns the adopted list directly; no UPID/task polling is needed."
+  ],
+  "relatedOperations": [
+    "get_subscriptions",
+    "post_subscriptions",
+    "put_subscriptions_key",
+    "delete_subscriptions_key"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_subscriptions_adopt_key",
+  "usageNotes": "Use this to pull the active subscription key from a remote node into the PDM subscription pool without modifying the remote itself. The remote node must be reachable and the caller must hold `PRIV_RESOURCE_MODIFY` on that specific remote in addition to the top-level `System.Modify` privilege. The call is refused if that (remote, node) pair is already pool-managed — use Assign or Clear paths first to reconcile any existing binding.",
+  "examples": [
+    {
+      "summary": "Adopt the live subscription key from node 'pve1' on remote 'hetzner-de'",
+      "path_params": {},
+      "params": {
+        "remote": "hetzner-de",
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "If the key is already in the pool but unbound, adoption rebinds it to (remote, node) and preserves its original source label (e.g. 'Manual').",
+    "If the key is already bound to a different (remote, node) pair, the call is rejected — you must clear or reassign that binding before adopting.",
+    "Pass the current pool config `digest` to guard against concurrent modifications when scripting bulk adoptions.",
+    "Returns null on success; errors surface as HTTP 4xx/5xx with a descriptive message."
+  ],
+  "relatedOperations": [
+    "get_subscriptions",
+    "post_subscriptions_assign_key",
+    "delete_subscriptions_key"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_subscriptions_apply_pending",
+  "usageNotes": "Use this to push all subscription pool keys that have not yet reached their assigned nodes — for example after a bulk pool edit, a new node join, or recovery from a previously failed apply. Returns a UPID when there is pending work (poll the task for completion) or null when everything is already in sync, which you can use to show an informational 'nothing to do' message instead of opening a progress dialog. Pass the current pool digest to guard against a stale browser tab submitting an apply based on a plan the operator has since changed.",
+  "examples": [
+    {
+      "summary": "Apply all pending subscription key pushes, guarded by a known pool digest",
+      "path_params": {},
+      "params": {
+        "digest": "a3f1c8e2b47d905f6e3a1c8b2d7e4f09a3f1c8e2b47d905f6e3a1c8b2d7e4f0"
+      }
+    }
+  ],
+  "tips": [
+    "When the return value is null, there is nothing pending — no task is created and no progress dialog is needed.",
+    "Failed pushes do not abort the worker; the worker attempts every pending entry and reports all failures at the end. A subsequent call retries only the entries that remain pending.",
+    "Subscription health states (Invalid, Expired) are never considered pending — re-pushing an already-delivered key will not change the vendor's validity verdict, so the operation skips those entries.",
+    "The digest parameter is optional but recommended in UI workflows: it pins the plan at the moment the user clicked Apply, so a concurrent admin edit does not silently change what gets pushed.",
+    "The worker re-reads the pool when it actually fires, so a legitimate parallel edit made between the API return and worker execution is honoured — the digest only validates the at-call-time plan."
+  ],
+  "relatedOperations": [
+    "get_subscriptions",
+    "post_subscriptions",
+    "put_subscriptions",
+    "delete_subscriptions"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_subscriptions_auto_assign",
+  "usageNotes": "Call this to preview which unused pool subscription keys would be assigned to which unsubscribed nodes — no changes are committed by this call. The returned plan (including `keys-digest` and `node-status-digest` snapshots) must be passed to `post_subscriptions_bulk_assign` to actually apply it; if cluster state drifts between preview and commit, bulk-assign will reject the plan with 409. Requires `System.Modify` at the system path to preview; callers lacking `Resource.Modify` on a specific remote will still see proposals for it but the commit step will silently skip writes to that remote.",
+  "examples": [
+    {
+      "summary": "Preview the auto-assign plan for all nodes in the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The POST body is empty (no params required) — always send an empty JSON object `{}` or an empty body with Content-Type: application/json.",
+    "Store the returned `keys-digest` and `node-status-digest` immediately; they are required inputs for the follow-up bulk-assign call and expire conceptually the moment cluster state changes.",
+    "If `assignments` comes back empty, all nodes already have active subscriptions or the pool has no unused keys — check subscription pool status before troubleshooting.",
+    "The commit step (bulk-assign) uses an application/json body to carry the nested assignment structure; form-urlencoded cannot represent it and will fail.",
+    "An audit-only operator scoped to a subset of remotes can safely call this endpoint to inspect the global plan; unauthorized remotes are filtered at commit time, not preview time."
+  ],
+  "relatedOperations": [
+    "post_subscriptions_bulk_assign",
+    "get_subscriptions",
+    "get_nodes_subscription"
+  ]
+}