@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_config_acme_plugins",
+  "usageNotes": "Use this to register a new DNS-01 ACME challenge plugin in Proxmox Datacenter Manager so that managed nodes can obtain TLS certificates via Let's Encrypt (or another ACME CA) using DNS validation. The caller must hold the System.Modify privilege on /system/certificates. The `data` field must contain the DNS provider credentials base64-encoded with padding (standard base64, not URL-safe); the correct `api` value is the provider plugin ID supported by the underlying acme.sh DNS API (e.g., 'cloudflare', 'route53').",
+  "examples": [
+    {
+      "summary": "Register a Cloudflare DNS plugin for ACME certificate automation",
+      "path_params": {},
+      "params": {
+        "id": "cf-nightsquawk",
+        "type": "dns",
+        "api": "cloudflare",
+        "data": "Q0ZfVE9LRU49YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=",
+        "disable": false,
+        "validation-delay": 60
+      }
+    }
+  ],
+  "tips": [
+    "The `id` field (1–32 chars, pattern [A-Za-z0-9_][A-Za-z0-9._-]*) becomes the plugin's reference name used when assigning it to a domain order — choose something descriptive like 'cf-prod' or 'r53-acme'.",
+    "If your DNS provider has slow propagation, raise `validation-delay` above the 30 s default (max 172800 s = 48 h) to avoid premature validation failures.",
+    "Credentials in `data` are stored as-is on the PDM node; restrict API token scope to only the DNS zone(s) needed to minimize blast radius if the credential is exposed.",
+    "To verify the plugin was created, follow up with get_config_acme_plugins or list the plugins endpoint."
+  ],
+  "relatedOperations": [
+    "get_config_acme_plugins",
+    "put_config_acme_plugins_id",
+    "delete_config_acme_plugins_id"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_config_views",
+  "usageNotes": "Use this to create a named view in PDM, which acts as a filtered subset of resources visible in the dashboard. The 'id' must be unique across all views; creating a view with a duplicate id will fail. If neither 'include' nor 'exclude' rules are provided, set 'include-all' to true to make the view capture all resources by default.",
+  "examples": [
+    {
+      "summary": "Create a view that includes all resources and scopes it to a named group",
+      "path_params": {},
+      "params": {
+        "id": "prod-nodes",
+        "include-all": true,
+        "layout": "{\"groupBy\":\"node\"}"
+      }
+    }
+  ],
+  "tips": [
+    "Use the 'digest' param (SHA256 of the current config) to guard against concurrent modifications when multiple operators may be updating views simultaneously.",
+    "'include' and 'exclude' take filter rule arrays — fetch an existing view first to understand the expected rule format before constructing them.",
+    "The 'id' field follows a restricted character set (alphanumeric, dots, hyphens, underscores; 2–32 chars); names like 'my view' with spaces will be rejected.",
+    "Returns null on success — verify the view was created by calling GET /config/views/{id} afterward."
+  ],
+  "relatedOperations": [
+    "get_config_views",
+    "get_config_views_id",
+    "put_config_views_id",
+    "delete_config_views_id"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_apt_repositories",
+  "usageNotes": "Use this endpoint to toggle a specific APT repository entry on or off within an existing sources file on a PDM node. The `index` is 0-based and refers to the repository's position within the file at `path`; retrieve these values first via the corresponding GET endpoint. Pass the `digest` returned by the GET call to guard against concurrent modifications — the request will be rejected if the file has changed since you read it.",
+  "examples": [
+    {
+      "summary": "Disable the second repository entry in /etc/apt/sources.list",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "path": "/etc/apt/sources.list",
+        "index": 1,
+        "enabled": false,
+        "digest": "a3c1e2f4b5d6789012345678901234567890abcdef1234567890abcdef123456"
+      }
+    }
+  ],
+  "tips": [
+    "Call GET /nodes/{node}/apt/repositories first to get the current list of repositories, their indices, paths, and the file digest.",
+    "The digest is strongly recommended in production — omitting it risks clobbering a concurrent change made by another admin or automation.",
+    "This endpoint modifies only the enabled/disabled state of an existing repository entry; it cannot add or remove repository lines.",
+    "Returns null on success (HTTP 200 with no body); treat any non-2xx response as a failure requiring investigation."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_repositories",
+    "put_nodes_node_apt_repositories"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_apt_update",
+  "usageNotes": "Triggers an `apt-get update` on the specified PDM node to refresh the local package index; run this before querying available upgrades or installing packages. The operation is asynchronous — the response is a UPID string that should be polled via the task API to confirm completion. Requires `System.Modify` privilege; the node must be online and reachable.",
+  "examples": [
+    {
+      "summary": "Refresh APT package index on node 'pdm01' with email notification enabled",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "notify": true,
+        "quiet": false
+      }
+    }
+  ],
+  "tips": [
+    "Poll the returned UPID using the task-status endpoint to know when the update completes before acting on package data.",
+    "Set quiet=true in automated/cron contexts to suppress progress output and produce cleaner logs.",
+    "notify=true sends mail only to the address configured for root@pam on the PDM instance — verify that address is set before relying on it."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "get_nodes_node_apt_versions",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_certificates_acme_certificate",
+  "usageNotes": "Orders a new ACME (Let's Encrypt) certificate for the specified PDM node; the node must have an ACME account and at least one domain configured before calling this endpoint. Returns a UPID — poll the task log to confirm issuance success before assuming the certificate is live. Use the `force` flag only when you need to replace an unexpired certificate, as it will overwrite the existing cert and key immediately.",
+  "examples": [
+    {
+      "summary": "Order a new ACME certificate for a PDM node (standard, non-forced)",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "force": false
+      }
+    }
+  ],
+  "tips": [
+    "ACME account and domain(s) must be configured on the node via the PDM web UI or API before ordering.",
+    "The returned UPID is asynchronous — use a task-status endpoint to wait for completion before testing the certificate.",
+    "Let's Encrypt rate-limits failed issuance attempts per domain; avoid repeated forced renewals in a short window.",
+    "If the node hostname does not resolve publicly, HTTP-01 challenge will fail; ensure DNS or an appropriate challenge plugin is set up."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates_acme_certificate",
+    "delete_nodes_node_certificates_acme_certificate",
+    "get_nodes_node_certificates_info",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_certificates_custom",
+  "usageNotes": "Use this to install a custom TLS certificate (and optionally its private key) on a PDM node, replacing the self-signed certificate used by the web UI. The `certificates` field must contain the full PEM chain (leaf + intermediates); if a cert already exists, set `force: true` to overwrite. Returns immediately with the new certificate info — there is no async UPID, but the UI will reflect the change on next reload.",
+  "examples": [
+    {
+      "summary": "Upload a Let's Encrypt cert chain and private key to the local PDM node",
+      "path_params": {
+        "node": "localhost"
+      },
+      "params": {
+        "certificates": "-----BEGIN CERTIFICATE-----\nMIIF...leaf cert...==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIF...intermediate...==\n-----END CERTIFICATE-----\n",
+        "key": "-----BEGIN PRIVATE KEY-----\nMIIE...private key...==\n-----END PRIVATE KEY-----\n",
+        "force": true
+      }
+    }
+  ],
+  "tips": [
+    "The `restart` param is documented as a UI compatibility shim and has no effect — omit it.",
+    "If uploading a chain, order matters: leaf certificate first, then intermediates.",
+    "Omitting `key` leaves the existing private key in place, which is valid only when re-uploading a renewed cert for the same key pair.",
+    "Requires the `System.Modify` privilege on the calling token/user — API tokens scoped only to specific nodes will be rejected."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates",
+    "delete_nodes_node_certificates_custom"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_nodes_node_network",
+  "usageNotes": "Use this to create a new network interface definition (bridge, bond, VLAN, static IP, etc.) on a PDM node; the interface is staged in /etc/network/interfaces but does not go live until you apply pending changes via PUT /nodes/{node}/network. Requires System.Modify on the specific interface path, so the token must have that privilege scoped to the target node. Only one interface name (`iface`) may be created per call — for complex topologies (bond + bridge) issue multiple calls in dependency order.",
+  "examples": [
+    {
+      "summary": "Create a VLAN-aware Linux bridge (vmbr1) with a static IP on node pdm01",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "iface": "vmbr1",
+        "type": "bridge",
+        "bridge_ports": "eno2",
+        "bridge_vlan_aware": true,
+        "method": "static",
+        "cidr": "10.10.20.1/24",
+        "autostart": true,
+        "comments": "VM traffic bridge on second NIC"
+      }
+    }
+  ],
+  "tips": [
+    "Changes are staged only — run PUT /nodes/{node}/network (apply) or reload the network service to activate; guests may lose connectivity during the apply step.",
+    "For VLAN interfaces set type=vlan, vlan-id to the tag, and vlan-raw-device to the parent physical interface.",
+    "For 802.3ad bonds set bond_mode=802.3ad and bond_xmit_hash_policy (layer2+3 is the most common choice for balanced hashing).",
+    "Interface names must be 15 characters or fewer — an AD-style hostname constraint also enforced by Proxmox.",
+    "Setting a gateway here makes this the default route for the node; only one interface should carry a gateway to avoid routing conflicts."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_nodes_node_status",
+  "usageNotes": "Use this endpoint to initiate a controlled reboot or shutdown of a PDM-managed node. The caller must hold the Sys.PowerManagement privilege on the /system/status ACL path; API tokens are supported. The API returns null immediately — there is no UPID, so the operation is fire-and-forget; monitor node availability separately to confirm the power action completed.",
+  "examples": [
+    {
+      "summary": "Reboot a PDM node named 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "command": "reboot"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'localhost' as the node name to target the PDM host itself when the API is served from that node.",
+    "Because the return is null, do not poll for a task UPID — instead, watch for the node to go offline and reconnect.",
+    "Prefer 'reboot' over 'shutdown' in automated workflows unless you have a confirmed bring-up path (IPMI, WoL) to recover a shut-down node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "get_nodes"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "post_nodes_node_subscription",
+  "usageNotes": "Triggers a subscription status refresh on the specified PDM node, causing it to re-check its license key validity against the Proxmox subscription server. No request body parameters are accepted — the call itself is the trigger. Requires System.Modify on the system path; API tokens are supported.",
+  "examples": [
+    {
+      "summary": "Refresh subscription status on the local PDM node",
+      "path_params": {
+        "node": "localhost"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null on success — a 200 with no body is the expected response; treat non-200 as failure.",
+    "Use 'localhost' as the node name when targeting the PDM host itself rather than a managed PVE node.",
+    "Run this after applying or changing a subscription key to force an immediate status update without waiting for the scheduled refresh."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_subscription"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_termproxy",
+  "usageNotes": "Use this to open a web-based terminal session on a PDM node; it returns a short-lived ticket and port that the browser-based terminal UI (noVNC/xterm.js) uses to establish the WebSocket connection. The caller must be authenticated as a PAM-realm user with Sys.Console on the system path — API tokens are accepted but the PAM realm restriction still applies. Omit `cmd` for a plain login shell, or pass `cmd=upgrade` to launch an interactive system-upgrade session.",
+  "examples": [
+    {
+      "summary": "Open a login shell terminal on node 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "cmd": "login"
+      }
+    }
+  ],
+  "tips": [
+    "The returned `ticket` and `port` must be passed to the termproxy WebSocket endpoint to actually connect; obtaining them alone does not open a shell.",
+    "Tickets are short-lived — connect immediately after calling this endpoint.",
+    "The `upid` in the response tracks the background termproxy process; it is not a long-running async task UPID in the usual sense — the shell is ready once you receive the response.",
+    "Using 'localhost' as the node value targets the PDM manager node itself, not a managed PVE node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node",
+    "get_nodes"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_pbs_probe_tls",
+  "usageNotes": "Use this before adding or updating a PBS remote to verify its TLS certificate. If the host's certificate is not already trusted (e.g., it is self-signed), the API returns the certificate details so you can capture the fingerprint for use in subsequent remote-add or remote-update calls. Requires the System.Modify privilege at the root path.",
+  "examples": [
+    {
+      "summary": "Probe a self-signed PBS remote to retrieve its certificate fingerprint",
+      "path_params": {},
+      "params": {
+        "hostname": "pbs-offsite.example.com:8007"
+      }
+    }
+  ],
+  "tips": [
+    "If the certificate is already trusted by the system's CA bundle, the response body is null — a non-error empty response is the success case for trusted certs.",
+    "When the cert is untrusted, the returned fingerprint should be copied and passed as the 'fingerprint' field when registering the remote, completing the trust-on-first-use (TOFU) flow.",
+    "The hostname field accepts an optional port (e.g., host:8007); omit the port to default to PBS's standard 8007.",
+    "API tokens are supported (allowtoken: true), so a scoped token with System.Modify is sufficient — no interactive session required."
+  ],
+  "relatedOperations": [
+    "post_pbs_remotes",
+    "put_pbs_remotes_id"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_pbs_remotes_remote_nodes_node_apt_update",
+  "usageNotes": "Triggers an `apt-get update` on the specified PBS remote node, refreshing the local package index so that pending upgrades become visible via the APT changelog/versions endpoints. The operation is asynchronous — it returns a remote UPID string that must be polled for completion. The caller must hold `Resource.Modify` on the remote+node+system path, and the remote node must be reachable from PDM at the time of the call.",
+  "examples": [
+    {
+      "summary": "Refresh the APT package index on node 'pbs-node1' of the remote named 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "node": "pbs-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "No request body parameters are required — send an empty JSON object ({}) as the body.",
+    "The returned UPID is a remote UPID (≥42 chars); use the corresponding task-status endpoint scoped to the same remote+node to poll for completion before querying available upgrades.",
+    "Remote name must be 2–32 characters and match the pattern [A-Za-z0-9_][A-Za-z0-9._-]* — simple alphanumeric names with hyphens or underscores are safe.",
+    "This only refreshes the package index; it does not install or upgrade any packages."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node_apt_update",
+    "get_pbs_remotes_remote_nodes_node_apt_versions",
+    "get_pbs_remotes_remote_nodes_node_apt_changelog",
+    "get_pbs_remotes_remote_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_pbs_remotes_remote_nodes_node_termproxy",
+  "usageNotes": "Use this to open an interactive terminal session on a PBS node accessed through a PDM-configured remote. The endpoint returns a short-lived VNC/WebSocket ticket and user identity — the caller must immediately upgrade the connection to a WebSocket using that ticket before it expires. Requires the Sys.Console privilege on the remote+node ACL path and is restricted to users (API tokens alone may not suffice depending on PDM configuration).",
+  "examples": [
+    {
+      "summary": "Open a terminal proxy session on node 'pbs01' of remote 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "node": "pbs01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'port' is always 0; it is not used for connection routing — the WebSocket upgrade itself carries the session.",
+    "The ticket is short-lived; initiate the WebSocket upgrade immediately after receiving it.",
+    "Node value 'localhost' is accepted and refers to the PDM-local PBS node when the remote is a loopback-style configuration.",
+    "API token access is allowed (allowtoken: true), but the Sys.Console privilege must be explicitly granted to the token's ACL path at /resource/{remote}/node/{node}."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node",
+    "get_pbs_remotes_remote_nodes"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_pbs_scan",
+  "usageNotes": "Use this endpoint to probe a Proxmox Backup Server remote by credentials before committing it as a configured remote — it validates connectivity and login without persisting anything. Requires the `System.Modify` privilege at the root path (`/`). The response echoes back the connection details along with discovered node addresses, making it useful for confirming the correct hostname/authid combination prior to calling the remote-add endpoint.",
+  "examples": [
+    {
+      "summary": "Scan a PBS instance using an API token before adding it as a remote",
+      "path_params": {},
+      "params": {
+        "authid": "backup@pbs!mcp-token",
+        "hostname": "pbs.nightsquawk.tech:8007",
+        "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        "fingerprint": "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78"
+      }
+    }
+  ],
+  "tips": [
+    "The `authid` format is `user@realm` for password auth or `user@realm!tokenid` for API token auth — match the format to whatever `token` value you are supplying.",
+    "Omitting `fingerprint` is allowed but will cause TLS verification to fall back to system trust store; always supply the fingerprint for self-signed PBS certificates to avoid connection failures.",
+    "This call returns synchronously (no UPID); if it returns connection info the credentials are valid — a failed login surfaces as an API error, not a task.",
+    "Port 8007 is the PBS default; include it explicitly in `hostname` if PDM cannot reach the standard PBS port."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes",
+    "post_pbs_remotes",
+    "get_pbs_remote_datastores"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "post_pve_probe_tls",
+  "usageNotes": "Use this before adding a new PVE remote to PDM: it probes the target host's TLS certificate and returns certificate details only when the certificate is untrusted under the supplied parameters, letting you inspect and capture the fingerprint. Requires System.Modify at the root path. If you already have the expected fingerprint, pass it to perform a pinned-trust check instead of relying on the CA chain.",
+  "examples": [
+    {
+      "summary": "Probe a PVE node at a non-default port to retrieve its self-signed certificate fingerprint",
+      "path_params": {},
+      "params": {
+        "hostname": "pve1.example.com:8006"
+      }
+    }
+  ],
+  "tips": [
+    "The hostname field accepts an optional port suffix (e.g. 'host:8006'); omit the port to use the default HTTPS port.",
+    "If the certificate is trusted (valid CA chain and matching fingerprint), the response body is null — a null return is a success indicator, not an error.",
+    "Capture the returned fingerprint from an untrusted cert and supply it as the 'fingerprint' param when subsequently registering the remote, so PDM can pin it instead of relying on CA trust."
+  ],
+  "relatedOperations": [
+    "post_pbs_probe_tls",
+    "get_pve_remotes",
+    "get_pve_remotes_remote"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_migrate",
+  "usageNotes": "Use to move an LXC container to a different node within the same PVE cluster managed by a PDM remote; the caller must hold Resource.Migrate on the guest. The operation is asynchronous — the response is a remote UPID that must be polled for completion. For a running container, set 'online' for live migration (lower downtime) or 'restart' for a stop-start migration (broader storage compatibility); leaving both false will fail if the container is running.",
+  "examples": [
+    {
+      "summary": "Online-migrate a running LXC (VMID 201) from pve-remote to node pve-node-02",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 201
+      },
+      "params": {
+        "target": "pve-node-02",
+        "online": true,
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "destructiveReason": "The container is moved off its current node; if the migration fails mid-transfer the container may be left in a stopped or inconsistent state on the source or target node.",
+  "tips": [
+    "Poll the returned UPID via the PDM task-status endpoint to detect completion or failure before assuming success.",
+    "Use 'target-storage' when source and target nodes do not share the same storage pool names — omitting it may cause the migration to fail if storage IDs differ.",
+    "restart-migration (restart: true) is the safer fallback for containers with local storage that cannot be live-migrated.",
+    "Set bwlimit to avoid saturating cluster links during business hours; 0 means unlimited.",
+    "The 'node' body parameter specifies the current node if PDM cannot infer it; 'target' is the destination and is always required."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_status_current",
+    "get_pve_remotes_remote_tasks_upid_status",
+    "get_pve_remotes_remote_lxc"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_remote_migrate",
+  "usageNotes": "Use this to migrate an LXC container from a source PVE remote to a different PVE remote managed by PDM; both the source and target remotes must be registered in PDM and the caller needs Resource.Migrate on both the source and target guest paths. The operation is asynchronous — it returns a remote UPID that must be polled for completion status. Bridge and storage mappings are required even for simple migrations; omitting or mismatching them will cause the task to fail immediately.",
+  "examples": [
+    {
+      "summary": "Live-migrate a running LXC (VMID 200) from remote 'pve-hetzner' to remote 'pve-ovh', mapping storage and bridge, keeping the source after migration",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 200
+      },
+      "params": {
+        "target": "pve-ovh",
+        "target-bridge": ["vmbr0=vmbr0"],
+        "target-storage": ["local-lvm=local-lvm"],
+        "target-vmid": 200,
+        "online": true,
+        "delete": false,
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "tips": [
+    "Set 'delete': true only when you are certain the migration succeeded; there is no automatic rollback once the source is deleted.",
+    "Use 'restart' + 'timeout' instead of 'online' when live migration is not supported by the container's configuration (e.g., containers with certain mounts).",
+    "Bridge and storage mapping arrays use 'source=target' string format (e.g., 'vmbr0=vmbr0'); every interface and disk must be covered or the task errors.",
+    "Poll the returned remote UPID against the target remote's task API to track progress and detect failures.",
+    "Specify 'target-vmid' explicitly if the VMID is already in use on the target cluster to avoid ID conflicts."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_status",
+    "get_pve_remotes_remote_lxc",
+    "post_pve_remotes_remote_qemu_vmid_remote_migrate"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_shutdown",
+  "usageNotes": "Sends an ACPI shutdown signal to a remote LXC container, allowing it to shut down gracefully rather than being forcibly stopped. The caller must hold `Resource.Manage` on the remote guest resource. Returns a remote UPID — poll the task status endpoint to confirm completion before assuming the container is offline.",
+  "examples": [
+    {
+      "summary": "Gracefully shut down LXC container 201 on remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "vmid": 201
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "destructiveReason": "Shuts down the container, interrupting all running processes and making the container's services unavailable until it is started again.",
+  "tips": [
+    "Omit the `node` body parameter to let PDM resolve the node automatically; supply it only when you know the specific node hosting the container.",
+    "A graceful shutdown depends on the container's init system responding to the ACPI signal — if the container is unresponsive, use the stop (force-kill) endpoint instead.",
+    "The returned UPID is scoped to the remote cluster; use the corresponding remote task-status endpoint to track completion."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_lxc_vmid_stop",
+    "post_pve_remotes_remote_lxc_vmid_start",
+    "post_pve_remotes_remote_lxc_vmid_reboot",
+    "get_pve_remotes_remote_lxc_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_snapshot",
+  "usageNotes": "Creates a point-in-time snapshot of a remote LXC container managed by Proxmox Datacenter Manager; the container does not need to be stopped unless RAM state preservation is required. Returns a remote UPID (task identifier) — poll the task status endpoint to determine when the snapshot completes before depending on the result. The caller must hold Resource.Manage on the remote/guest resource path.",
+  "examples": [
+    {
+      "summary": "Snapshot a running LXC container on a named remote before a software upgrade",
+      "path_params": {
+        "remote": "hetzner-pve1",
+        "vmid": 201
+      },
+      "params": {
+        "snapname": "pre-upgrade-2026-06-29",
+        "description": "Before upgrading Nginx to 1.26 LTS",
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "snapname must be unique per container — creating a snapshot with a duplicate name will fail.",
+    "The returned UPID is scoped to the remote cluster; use the appropriate remote task-status endpoint (not the local PDM one) to track completion.",
+    "Omitting 'node' lets PDM resolve the node automatically, which is reliable when the remote has a single-node cluster; specify it explicitly in multi-node environments to avoid ambiguity.",
+    "Snapshot names are limited to 40 characters and must start with an alphanumeric or underscore character — date-suffixed names like 'pre-upgrade-20260629' are a safe convention."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_snapshot",
+    "delete_pve_remotes_remote_lxc_vmid_snapshot_snapname",
+    "post_pve_remotes_remote_lxc_vmid_snapshot_snapname_rollback"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_snapshot_snapname_rollback",
+  "usageNotes": "Rolls back a remote LXC container to a named snapshot, reverting both disk and configuration to the snapshot state — all changes made after the snapshot was taken are permanently lost. The container must be stopped before rollback (unless `start` is set, which will start it after a successful rollback). Returns a remote UPID; poll that UPID for task completion before assuming the rollback is done. Requires `Resource.Manage` on the remote guest.",
+  "examples": [
+    {
+      "summary": "Roll back LXC 201 on remote 'hetzner-pve' to snapshot 'pre-upgrade' and start it afterward",
+      "path_params": {
+        "remote": "hetzner-pve",
+        "vmid": 201,
+        "snapname": "pre-upgrade"
+      },
+      "params": {
+        "start": true
+      }
+    }
+  ],
+  "destructiveReason": "All disk data and configuration changes made after the snapshot was taken are permanently discarded and cannot be recovered.",
+  "tips": [
+    "Stop the container before initiating rollback; a running container will cause the operation to fail on most storage backends.",
+    "Use `start: true` to atomically start the container after rollback rather than issuing a separate start call.",
+    "The returned UPID is scoped to the remote node — use the appropriate remote task-status endpoint to poll it, not the local PDM task API.",
+    "Snapshot names are case-sensitive and follow the pattern [A-Za-z0-9_][A-Za-z0-9._-]*; verify the exact name via the snapshot list endpoint before calling rollback.",
+    "If the container uses linked clones or external volumes not covered by the snapshot, those volumes are NOT rolled back."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_snapshot",
+    "post_pve_remotes_remote_lxc_vmid_snapshot",
+    "delete_pve_remotes_remote_lxc_vmid_snapshot_snapname",
+    "post_pve_remotes_remote_lxc_vmid_status_start"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_start",
+  "usageNotes": "Use this endpoint to start a stopped or paused LXC container on a remote PVE node managed by Proxmox Datacenter Manager. The caller must hold the Resource.Manage privilege on the remote/guest path. The operation is asynchronous — the response is a remote UPID string; poll the corresponding task endpoint to confirm the container reaches running state before depending on it.",
+  "examples": [
+    {
+      "summary": "Start LXC container 201 on remote 'hetzner-de' (let PDM pick the node)",
+      "path_params": {
+        "remote": "hetzner-de",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the target LXC is on a specific node in the remote cluster, pass 'node' to avoid ambiguity — otherwise PDM resolves the node automatically.",
+    "The returned UPID is scoped to the remote; use the remote task-status endpoint (not the local PVE one) to track completion.",
+    "Starting a container that is already running returns an error — check container status first if your workflow may call this redundantly."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_lxc_vmid_stop",
+    "post_pve_remotes_remote_lxc_vmid_shutdown",
+    "get_pve_remotes_remote_lxc_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_pve_remotes_remote_lxc_vmid_stop",
+  "usageNotes": "Issues an immediate hard stop of a remote LXC container — equivalent to pulling power, with no graceful shutdown sequence. Use this only when a clean shutdown via the 'shutdown' endpoint is not possible (e.g., container is frozen or unresponsive). Returns a remote UPID string; poll the remote task status endpoint to confirm completion. Requires Resource.Manage on the container's resource path.",
+  "examples": [
+    {
+      "summary": "Force-stop LXC container 102 on a named remote",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 102
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "destructiveReason": "Immediately kills the container process without flushing disk buffers or running shutdown hooks, which can cause filesystem corruption or data loss for in-flight writes.",
+  "tips": [
+    "Prefer the 'shutdown' endpoint for any container with active write workloads; use 'stop' only when shutdown is unresponsive.",
+    "The 'node' body param is optional — omit it to let PDM resolve the node automatically from the remote cluster.",
+    "Track the returned UPID against the remote task API to confirm the stop completed before attempting start or migration operations."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_lxc_vmid_shutdown",
+    "post_pve_remotes_remote_lxc_vmid_start",
+    "get_pve_remotes_remote_lxc_vmid_status_current"
+  ]
+}