@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_storage",
+  "usageNotes": "Use this to inspect storage availability, capacity, and enabled content types on a specific node of a PVE remote — useful before provisioning VMs, containers, or backups to confirm a target storage is active and has sufficient space. Requires Resource.Audit on the remote node path; if 'target' is also specified, that privilege is additionally required on the target node path. Storages where 'active' is false are configured but currently unreachable from the node.",
+  "examples": [
+    {
+      "summary": "List all enabled backup-capable storages on a node, including format details",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "node": "pve1"
+      },
+      "params": {
+        "enabled": true,
+        "content": ["backup"],
+        "format": true
+      }
+    }
+  ],
+  "tips": [
+    "Check 'active' (not just 'enabled') — a storage can be enabled in config but unreachable at runtime.",
+    "Pass 'format: true' only when you need disk-image format support details; it adds response weight.",
+    "Use the 'target' param when planning a live migration: it filters to only storages accessible by both the source node and the target node.",
+    "avail, used, and total are in bytes — divide by 1073741824 for GiB.",
+    "The 'storage' query param narrows the response to a single named datastore, which is faster than fetching all and filtering client-side."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node",
+    "get_pve_remotes_remote_nodes_node_storage_storage_content",
+    "get_pve_remotes"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_storage_storage",
+  "usageNotes": "Returns the directory index for a specific storage on a remote PVE node — useful for discovering what sub-resources or actions are available under that storage path before drilling into content or status calls. The remote must be reachable from PDM and the node must be online; if either is unavailable the call will fail. The response schema is null in the spec, meaning this is a navigation/index endpoint and not a data-bearing call.",
+  "examples": [
+    {
+      "summary": "List the index for the 'local-zfs' storage on node 'pve1' of remote 'hetzner-prod'",
+      "path_params": {
+        "remote": "hetzner-prod",
+        "node": "pve1",
+        "storage": "local-zfs"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use this endpoint to confirm a storage name is valid on a given node before issuing storage-content or status calls.",
+    "The 'remote' value must match a remote name registered in PDM, not a hostname or IP.",
+    "Because permissions are 'user: all', any authenticated PDM user can call this — no special privilege required."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_storage",
+    "get_pve_remotes_remote_nodes_node_storage_storage_content",
+    "get_pve_remotes_remote_nodes_node_storage_storage_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_storage_storage_rrddata",
+  "usageNotes": "Use this to retrieve historical disk usage time-series data for a specific storage pool on a PVE remote node — useful for trending capacity utilization over time. Requires the `Resource.Audit` privilege on the `resource/{remote}/storage/{storage}` ACL path in PDM. Both `cf` and `timeframe` are required; choose `AVERAGE` for smooth trend graphs and `MAX` to catch utilization spikes.",
+  "examples": [
+    {
+      "summary": "Get hourly average disk usage for the 'local-lvm' storage on node 'pve1' of remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1",
+        "storage": "local-lvm"
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "hour"
+      }
+    }
+  ],
+  "tips": [
+    "Data points may be sparse or omitted near the current time — RRD rounds data into fixed-width buckets, so the most recent bucket is often incomplete.",
+    "Use 'timeframe=decade' only for long-term capacity planning; resolution is very coarse and individual data points may span months.",
+    "Both 'disk-total' and 'disk-used' are optional per data point — expect nulls during periods when the storage was offline or unreported.",
+    "The node value accepts 'localhost' as a special alias when PDM and PVE are co-located, but using the actual hostname is more portable."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_storage_storage_status",
+    "get_pve_remotes_remote_nodes_node_rrddata",
+    "get_pve_remotes_remote_nodes_node_storage"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_storage_storage_status",
+  "usageNotes": "Use this endpoint to check the live capacity and accessibility of a specific storage pool on a remote PVE node — useful for pre-flight checks before migrations or backups. The `active` and `enabled` fields are distinct: `enabled` reflects the configuration state while `active` indicates the storage is currently reachable and mounted. Requires `Resource.Audit` privilege on the remote's storage path; the target node must be online and the remote must be configured in PDM.",
+  "examples": [
+    {
+      "summary": "Check status of local-lvm storage on pve-node1 of the hetzner remote",
+      "path_params": {
+        "remote": "hetzner",
+        "node": "pve-node1",
+        "storage": "local-lvm"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If `active` is false but `enabled` is true, the storage backend is configured but currently unreachable (e.g. NFS mount dropped, disk offline) — investigate at the PVE node level.",
+    "Capacity fields (`avail`, `total`, `used`) are in bytes; divide by 1073741824 for GiB.",
+    "The `content` field lists what the storage is allowed to hold (images, backup, iso, etc.) — not what it currently contains.",
+    "The description mentions QEMU VMs but this endpoint applies to storage status, not VM status; node auto-detection noted in the description does not apply to the storage path variant."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_storage",
+    "get_pve_remotes_remote_nodes_node_storage_storage_content",
+    "get_pve_remotes_remote_nodes_node"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_subscription",
+  "usageNotes": "Use this to retrieve the Proxmox subscription status and node health details (CPU, memory, rootfs, kernel, PVE version) for a specific node on a managed PVE remote. The caller must have Resource.Audit privilege on the target remote/node path. Note: despite the endpoint name referencing 'subscription', the response schema returns node system status fields rather than a subscription key or tier — treat the response as a combined node-status object and check additionalProperties for any subscription-specific fields.",
+  "examples": [
+    {
+      "summary": "Get subscription/status details for node 'pve1' on remote 'hetzner-prod'",
+      "path_params": {
+        "remote": "hetzner-prod",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The remote name must match the exact ID registered in PDM (2–32 chars, alphanumeric/dash/dot/underscore).",
+    "Use 'localhost' as the node value only when PDM itself is the target node.",
+    "The returns schema includes additionalProperties:true — subscription-tier fields (e.g., status, level, key) may appear beyond what is documented in the spec.",
+    "Cross-reference with the node status endpoint if you need real-time metrics; this endpoint's primary intent is the subscription record."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node",
+    "get_pve_remotes_remote_nodes",
+    "get_pve_remotes_remote"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_vncwebsocket",
+  "usageNotes": "This endpoint upgrades an HTTP connection to a WebSocket for VNC console access to a specific node managed by a PDM remote. It must be preceded by a ticket-acquisition step — call the node's VNC ticket endpoint first to obtain `port` and `vncticket`, then immediately open this WebSocket connection before the ticket expires (typically a short TTL). Requires `Sys.Console` on `/resource/{remote}/node/{node}`; API tokens are permitted but the authenticated principal must hold that privilege.",
+  "examples": [
+    {
+      "summary": "Open VNC WebSocket to node 'pve01' on remote 'hetzner-dc1' using a previously obtained ticket",
+      "path_params": {
+        "remote": "hetzner-dc1",
+        "node": "pve01"
+      },
+      "params": {
+        "port": 5900,
+        "vncticket": "PVEVNC:65a3f2c1::abcdef1234567890abcdef1234567890"
+      }
+    }
+  ],
+  "tips": [
+    "The `port` and `vncticket` values come from a prior VNC ticket creation call (e.g. POST to the node's vncproxy endpoint); do not reuse them across sessions.",
+    "The HTTP response will be a 101 Switching Protocols — standard HTTP clients cannot handle this; use a WebSocket client (browser WebSocket API, wscat, or noVNC).",
+    "Returns null in the JSON schema because the actual data flows over the upgraded WebSocket channel, not an HTTP response body.",
+    "Ticket TTL is short; initiate the WebSocket upgrade within a few seconds of obtaining the ticket to avoid authentication failure."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_nodes_node_vncproxy"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_options",
+  "usageNotes": "Use this to retrieve the cluster-level options (e.g. migration settings, HA preferences) for a specific PVE remote registered in PDM. Requires the `Resource.Audit` privilege on the remote resource; API tokens are supported. The return schema is not fully typed in the spec (`null`) — inspect the raw response body for the actual option fields returned by the target cluster's version.",
+  "examples": [
+    {
+      "summary": "Fetch cluster options for the remote named 'pve-prod'",
+      "path_params": {
+        "remote": "pve-prod"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The remote name must match the ID registered in PDM (2–32 chars, alphanumeric with . _ - allowed after the first char).",
+    "A `null` return type in the spec means no schema is enforced client-side — the actual response is a JSON object with cluster option fields; log or pretty-print it to discover available keys.",
+    "This is a read-only, non-destructive call safe to run in production at any time."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes",
+    "get_pve_remotes_remote",
+    "get_pve_remotes_remote_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu",
+  "usageNotes": "Use this to list all QEMU VMs across a registered PDM remote (or on a specific node within that remote). Omitting the `node` parameter queries every node in the cluster, which is the preferred way to get a full inventory. The caller must hold `Resource.Audit` on the remote resource path; live runtime fields (cpu, mem, disk I/O, pressure stats) are only populated for running VMs.",
+  "examples": [
+    {
+      "summary": "List all QEMU VMs across every node on the 'hetzner-pve' remote",
+      "path_params": {
+        "remote": "hetzner-pve"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Filter by `status` in the response to quickly isolate stopped vs. running VMs without a separate call.",
+    "The `template` boolean field lets you exclude template VMs from inventory counts.",
+    "Pressure stall fields (pressurecpufull, pressureiofull, pressurememoryfull) are Linux PSI metrics — only present on kernels that expose /proc/pressure.",
+    "Use the `node` query param to scope results to a single node if the cluster is large, reducing response size and remote API load."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc",
+    "get_pve_remotes",
+    "get_pve_remotes_remote_nodes"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid",
+  "usageNotes": "Returns the directory index of available sub-resources and actions for a specific QEMU VM on a PDM-registered PVE remote. Use this as a discovery call to enumerate what child endpoints exist under a given VM before calling more specific operations (e.g., status, config, migration). The remote must be reachable and the vmid must exist on that remote; both are inherited path parameters with no server-side format enforcement, so invalid values return an error rather than an empty list.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for VM 101 on the 'pve-hetzner' remote",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": "101"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint is a directory index (returns null per the spec); its primary value is confirming that the remote+vmid path is valid and discoverable before chaining deeper calls.",
+    "Because permissions are set to 'user: all', any authenticated PDM user or API token can call this — no specific PVE privilege is required at the PDM layer.",
+    "API tokens (allowtoken: true) work here; prefer scoped tokens over user credentials in automation."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu",
+    "get_pve_remotes_remote"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_config",
+  "usageNotes": "Use this to retrieve the full QEMU VM configuration from a remote PVE node managed by PDM. The `state` parameter controls whether you get the pending (unapplied) or active (currently running) config — `pending` is the default and reflects the next-boot config. If you omit `node`, PDM resolves it automatically; supply it only when you know the VM's node to avoid an extra lookup. Requires `Resource.Audit` on the remote/vmid resource path.",
+  "examples": [
+    {
+      "summary": "Fetch the active running config of VM 101 on remote 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 101
+      },
+      "params": {
+        "state": "active"
+      }
+    }
+  ],
+  "tips": [
+    "Use state=active when you need to inspect what the VM is currently running (e.g., after a live config change that hasn't been persisted).",
+    "Use state=pending (default) to see what config will be applied on next reboot — useful before migrating or snapshotting.",
+    "Pass `snapshot` to inspect the config frozen at a specific snapshot point rather than the current config.",
+    "Node auto-detection works well for healthy clusters; supply `node` explicitly if the cluster is partially degraded or you need deterministic routing."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_status_current",
+    "get_pve_remotes_remote_qemu_vmid_snapshot",
+    "get_pve_remotes_remote_qemu"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_firewall",
+  "usageNotes": "Returns the firewall directory index for a specific QEMU VM on a PDM-managed PVE remote — use it to discover which firewall sub-resources are available (e.g., rules, aliases, ipsets, options, refs) before drilling into them. No query parameters are required and no privilege beyond basic authentication is needed. The return payload is a directory listing, not the actual firewall ruleset, so follow up with the appropriate child endpoint to read or modify firewall configuration.",
+  "examples": [
+    {
+      "summary": "List firewall sub-resources for VM 101 on the 'hetzner-pve1' remote",
+      "path_params": {
+        "remote": "hetzner-pve1",
+        "vmid": "101"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The vmid path parameter must match a VM that actually exists on the target PVE remote; an invalid vmid typically returns a 404 from the proxied PVE node.",
+    "This endpoint is a directory index only — it does not return firewall rules, options, or aliases directly. Use child endpoints such as .../firewall/rules or .../firewall/options for actionable data.",
+    "The remote name must match exactly the remote identifier registered in PDM; check /pve/remotes for valid names."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_firewall_rules",
+    "get_pve_remotes_remote_qemu_vmid_firewall_options",
+    "get_pve_remotes_remote_qemu_vmid_firewall_aliases",
+    "get_pve_remotes_remote_qemu_vmid_firewall_ipsets",
+    "get_pve_remotes_remote_qemu_vmid_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_firewall_options",
+  "usageNotes": "Use this to read the current firewall configuration (enabled state, default policies, logging levels, and protocol-level options such as DHCP, NDP, MAC filtering, and IP filters) for a specific QEMU VM on a remote PVE cluster. The caller must hold the Resource.Audit privilege on the remote/vmid resource. If the VM spans multiple nodes, pass the optional 'node' query parameter to target the correct host; omitting it lets PDM resolve the node automatically.",
+  "examples": [
+    {
+      "summary": "Read firewall options for VM 101 on remote 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 101
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "All returned fields are optional — a field absent from the response means the cluster is using the documented default (e.g., macfilter defaults to true, enable defaults to false).",
+    "policy_in and policy_out have no documented default; if omitted the effective policy is determined by the cluster-level firewall configuration.",
+    "log_level_in and log_level_out default to 'nolog', so firewall hits are silent unless explicitly set to a syslog severity level.",
+    "ipfilter=true implicitly creates empty ipfilter-net ipsets per interface, which restrict IPv6 link-local addresses — useful hardening for multi-tenant environments.",
+    "This endpoint is read-only; use the corresponding PUT/POST endpoint to change options."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_firewall_rules",
+    "get_pve_remotes_remote_qemu_vmid_firewall_ipsets",
+    "get_pve_remotes_remote_qemu_vmid_firewall_aliases",
+    "get_pve_remotes_remote_qemu_vmid_firewall_log"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_firewall_rules",
+  "usageNotes": "Use this endpoint to audit or display the ordered firewall ruleset for a specific QEMU VM on a PDM-managed PVE remote. The caller must hold the Resource.Audit privilege on the remote/VM path. If the VM lives on a specific cluster node, pass the optional `node` parameter to route the request directly; omitting it lets PDM auto-resolve but may fail if the VM is not found cluster-wide.",
+  "examples": [
+    {
+      "summary": "List all firewall rules for VM 101 on remote 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 101
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "Rules are returned in positional order (pos field); the first matching rule wins at enforcement time.",
+    "A rule with enable=0 is defined but inactive — it still appears in this list.",
+    "The action field may be a security group name rather than ACCEPT/DROP/REJECT when the rule references a group.",
+    "This reflects the VM-level ruleset only; datacenter-level and cluster-level rules are evaluated separately."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_firewall_rules_pos",
+    "get_pve_remotes_remote_qemu_vmid_firewall_options",
+    "get_pve_remotes_remote_qemu_vmid_firewall_refs",
+    "get_pve_remotes_remote_qemu_vmid_firewall_log"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_migrate",
+  "usageNotes": "Call this before initiating a QEMU VM migration to check whether the migration is feasible — it returns local disks, local resources that block migration, allowed/disallowed target nodes, and HA affinity dependencies. If `local_resources` is non-empty the migration will be blocked; resolve those passthrough devices first. Supply `target` to get node-specific blocking details such as unavailable storages or HA conflicts.",
+  "examples": [
+    {
+      "summary": "Check migration preconditions for VM 105 on remote 'pve-hetzner', targeting node 'pve2'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 105
+      },
+      "params": {
+        "node": "pve1",
+        "target": "pve2"
+      }
+    }
+  ],
+  "tips": [
+    "A non-empty `local_resources` array means the VM cannot be live-migrated without detaching those resources (e.g. USB passthrough, PCIe devices).",
+    "`local_disks` lists CD-ROM ISOs and unused volumes that must be accounted for; ISOs on local storage are not automatically transferred and will block migration unless the target has the same ISO available.",
+    "`dependent-ha-resources` will be moved to the same target node automatically — confirm the target can host them before proceeding.",
+    "If `has-dbus-vmstate` is false, connection-tracking state (conntrack) will not survive the migration; plan for brief session drops on stateful services.",
+    "`allowed_nodes` is omitted when `target` is not specified — pass `target` to get the full node-specific feasibility breakdown in `not_allowed_nodes`."
+  ],
+  "relatedOperations": [
+    "post_pve_remotes_remote_qemu_vmid_migrate",
+    "get_pve_remotes_remote_lxc_vmid_migrate",
+    "get_pve_remotes_remote_qemu_vmid_status_current",
+    "get_pve_remotes_remote_nodes"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_pending",
+  "usageNotes": "Use this to retrieve configuration changes that have been applied but require a VM reboot to take effect on a remote PVE node. The `node` query parameter is optional — PDM resolves the VM's host automatically if omitted, but supplying it avoids an extra lookup and is preferred when the node is already known. Requires `Resource.Audit` privilege on the remote resource path; the remote must be reachable from PDM at call time.",
+  "examples": [
+    {
+      "summary": "Get pending config for VM 110 on remote 'pve-prod', letting PDM auto-resolve the node",
+      "path_params": {
+        "remote": "pve-prod",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If a pending config exists, the VM needs a reboot before those settings go live — use this before live-migrating or snapshotting to confirm no unapplied changes are waiting.",
+    "An empty or null result means no pending changes; the running config matches the stored config.",
+    "Supplying 'node' prevents PDM from doing a cluster-wide VM lookup, which matters on large clusters with many VMs."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_config",
+    "get_pve_remotes_remote_qemu_vmid_status_current",
+    "get_pve_remotes_remote_qemu"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_rrddata",
+  "usageNotes": "Fetches historical RRD time-series data for a QEMU VM on a PDM-managed PVE remote, useful for trending CPU, memory, disk I/O, and network utilization over time. Requires the `Resource.Audit` privilege on the remote+vmid path; the remote must be reachable and the VM must have existing RRD data (freshly created VMs may return sparse results). Use `AVERAGE` consolidation for trend analysis and `MAX` to surface peak spikes within the chosen timeframe.",
+  "examples": [
+    {
+      "summary": "Fetch last 24 hours of average stats for VM 101 on the 'hetzner-pve' remote",
+      "path_params": {
+        "remote": "hetzner-pve",
+        "vmid": 101
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "day"
+      }
+    }
+  ],
+  "tips": [
+    "Data resolution decreases for longer timeframes (e.g., 'decade' returns very coarse points); use 'hour' or 'day' when fine-grained data is needed.",
+    "All numeric metric fields (cpu-current, mem-used, disk-read, etc.) are optional per data point — gaps appear when the VM was stopped or data was not recorded.",
+    "cpu-max represents the number of vCPUs allocated, not a percentage; divide cpu-current by cpu-max to get utilization ratio.",
+    "Disk and network values are rates (bytes/sec), not cumulative totals — factor in the RRD step interval if computing total throughput."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_status",
+    "get_pve_remotes_remote_lxc_vmid_rrddata",
+    "get_pve_remotes_remote_nodes_node_rrddata"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_snapshot",
+  "usageNotes": "Use this to enumerate all snapshots for a QEMU VM on a remote PVE node managed by PDM, including the live 'current' pseudo-entry that represents the running state. The optional 'node' query parameter narrows the request to a specific node in a clustered remote; omit it to let PDM resolve the VM's host automatically. Requires Resource.Audit on the remote/guest path — read-only and safe to call at any time regardless of VM power state.",
+  "examples": [
+    {
+      "summary": "List all snapshots for VM 101 on the remote named 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 101
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "The response always includes a 'current' entry (name: 'current') that represents the live VM state — filter it out if you only need historical snapshots.",
+    "The 'snaptime' field is a Unix timestamp; convert to a human-readable date when displaying snapshot age.",
+    "The 'vmstate' field indicates whether RAM was included in the snapshot — RAM snapshots are larger and take longer to restore.",
+    "If the remote has multiple nodes, specifying 'node' avoids an extra lookup and can reduce latency.",
+    "The 'parent' field lets you reconstruct the snapshot tree/chain — useful before deciding which snapshot to roll back to."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_snapshot_snapname_config",
+    "post_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/get_pve_remotes_remote_qemu_vmid_status.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pve_remotes_remote_qemu_vmid_status",
+  "usageNotes": "Use this to poll the live run-state and resource metrics of a QEMU VM on a PDM-registered remote PVE cluster. The remote must already be configured in PDM and the caller needs Resource.Audit on the remote/VM path. If you omit the optional 'node' query parameter, PDM resolves the hosting node automatically; supply it only when you already know the node and want to enforce placement validation.",
+  "examples": [
+    {
+      "summary": "Get status of VM 101 on remote 'pve-hetzner', letting PDM resolve the node automatically",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'status' field returns only 'running' or 'stopped'; check 'qmpstatus' for finer-grained QEMU states such as 'paused' or 'prelaunch'.",
+    "Memory fields 'mem' vs 'memhost' differ: 'mem' is balloon-reported guest usage, 'memhost' is actual host-side allocation — use 'memhost' for capacity planning.",
+    "Disk I/O counters ('diskread'/'diskwrite') are cumulative since VM start and may be absent for some storage backends (e.g., NFS without block stats).",
+    "The 'pid' field is only present when the VM is running; its absence is a reliable programmatic signal that the VM is stopped.",
+    "Pressure stall fields (pressurecpufull, pressureiofull, etc.) require Linux PSI support on the PVE host and are absent on older kernels."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu",
+    "get_pve_remotes_remote_qemu_vmid_config",
+    "post_pve_remotes_remote_qemu_vmid_status_start",
+    "post_pve_remotes_remote_qemu_vmid_status_stop",
+    "get_pve_remotes"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pve_remotes_remote_resources",
+  "usageNotes": "Use this endpoint to get a live snapshot of all resources across a PVE cluster registered as a PDM remote — VMs, LXC containers, nodes, storage pools, and SDN objects. The remote must be reachable from PDM and the caller must hold Resource.Audit on the remote; offline remotes will return an error rather than stale data. Omit the 'kind' filter to retrieve everything in one call, or pass a specific kind (vm, node, storage, sdn) to reduce payload size when only one resource type is needed.",
+  "examples": [
+    {
+      "summary": "List all running VMs on the 'pve-hetzner' remote",
+      "path_params": {
+        "remote": "pve-hetzner"
+      },
+      "params": {
+        "kind": "vm"
+      }
+    }
+  ],
+  "tips": [
+    "The 'kind' value 'vm' returns both QEMU and LXC guests; discriminate by the 'type' property on each returned item ('qemu' vs 'lxc').",
+    "CPU values are fractional utilization ratios (e.g. 0.42 = 42%), not core counts — use 'maxcpu' for the core count.",
+    "Memory and disk fields are raw bytes; divide by 1073741824 for GiB display.",
+    "SDN resources (zones and fabrics) are only present when SDN is configured on the cluster; expect an empty list otherwise.",
+    "The 'node' field on guest resources reflects placement, not cluster membership — useful for identifying which physical host a VM is running on."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes",
+    "get_pve_remotes_remote",
+    "get_pve_remotes_remote_nodes",
+    "get_pve_remotes_remote_node_vms"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_tasks",
+  "usageNotes": "Use this to audit recent or in-progress tasks on a managed PVE remote — either across the entire cluster (omit `node`) or scoped to a single node. Requires `Resource.Audit` privilege on the target remote. Each returned item includes a UPID that can be passed to task-log or task-status endpoints to retrieve full output.",
+  "examples": [
+    {
+      "summary": "List all tasks on a specific node of a managed PVE remote",
+      "path_params": {
+        "remote": "pve-prod"
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting `node` returns tasks across all nodes in the remote cluster — useful for a global view but may return a large result set.",
+    "The `status` field is optional in responses; a missing status typically means the task is still running.",
+    "Use the `upid` from each result with a task-log or task-status call to inspect output or wait for completion.",
+    "The `remote` identifier must match a configured PDM remote name exactly (2–32 chars, alphanumeric/dot/dash/underscore)."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes",
+    "get_pve_remotes_remote_nodes"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_tasks_upid",
+  "usageNotes": "This is a directory-index endpoint that returns the list of sub-resources available under a specific task UPID on a named PVE remote managed by PDM. Use it to discover what task-related actions are accessible (e.g., status, log) before calling a more specific child endpoint. The remote must already be registered in PDM and the UPID must correspond to a task that exists on that remote's PVE node.",
+  "examples": [
+    {
+      "summary": "Enumerate sub-resources for a known task UPID on the 'pve-prod' remote",
+      "path_params": {
+        "remote": "pve-prod",
+        "upid": "UPID:pve-prod:00001A2B:012F3E4A:67A1B2C3:qmstart:101:root@pam:"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The return type is documented as null, meaning the API returns a bare array of child endpoint names — treat the response as a navigation manifest, not task data.",
+    "UPIDs are generated by PVE when an async task is started; obtain them from task-creating endpoints such as VM start, stop, migrate, or backup.",
+    "The 'remote' value must match the remote name exactly as registered in PDM — it is case-sensitive."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_tasks",
+    "get_pve_remotes_remote_tasks_upid_status",
+    "get_pve_remotes_remote_tasks_upid_log"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_pve_remotes_remote_tasks_upid_log",
+  "usageNotes": "Use this endpoint to read the task log of an async operation running on a PVE remote — for example, after triggering a migration, backup, or snapshot task that returned a UPID. The caller must have Resource.Audit on the remote resource path; the UPID must be at least 42 characters and refer to a task on the named remote. Use start+limit together to page through long logs without loading the entire file at once; set limit=0 only when you need the complete log.",
+  "examples": [
+    {
+      "summary": "Fetch the first 100 lines of a migration task log from remote 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "upid": "UPID:pve-hetzner:00001A2B:5F3C4D00:67AB12EF:qmmigrate:101:root@pam:"
+      },
+      "params": {
+        "start": 0,
+        "limit": 100
+      }
+    }
+  ],
+  "tips": [
+    "Poll this endpoint repeatedly (incrementing 'start' by your last 'limit') to stream a running task's log in near-real-time until 'status' changes to 'stopped'.",
+    "When 'status' is 'stopped', check 'exitstatus' for the final outcome (e.g. 'OK' or an error message).",
+    "Setting 'download=true' returns the raw log file for download and is mutually exclusive with 'start' and 'limit' — use it only when you need the full log as a file rather than paged JSON.",
+    "UPIDs are returned by task-launching endpoints (e.g. migrations, backups); capture the UPID from those responses before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_tasks_upid_status",
+    "get_pve_remotes_remote_tasks"
+  ]
+}