@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_access_users_userid",
+  "usageNotes": "Use this to update an existing Proxmox user's profile fields — display name, email, group memberships, expiration, or enable/disable status. The caller must hold `User.Modify` on the user or on all groups listed in the `groups` param; changing group membership requires the `groups_param` check to pass as well. This call is synchronous and returns null on success — no UPID is issued.",
+  "examples": [
+    {
+      "summary": "Disable a departing employee account and clear their group memberships",
+      "path_params": {
+        "userid": "jsmith@pve"
+      },
+      "params": {
+        "enable": false,
+        "groups": "",
+        "comment": "Account disabled 2026-06-28 - employee offboarded"
+      }
+    }
+  ],
+  "tips": [
+    "The `groups` param replaces the user's group list entirely unless `append` is set to true — omitting `groups` leaves existing memberships untouched.",
+    "Set `expire` to a Unix epoch timestamp (e.g. 1751155200) to auto-expire an account on a future date; set to 0 to remove an existing expiry.",
+    "The `keys` field is for legacy YubiKey OTP tokens, not TOTP/WebAuthn — most modern MFA is managed separately via /access/users/{userid}/tfa.",
+    "Realm-synced users (e.g. LDAP/AD via `@ldap` or `@ad` realms) may have some fields overwritten on the next sync — local overrides do not persist for synced attributes."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid",
+    "post_access_users",
+    "delete_access_users_userid",
+    "get_access_users_userid_tfa",
+    "put_access_users_userid_tfa"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_access_users_userid_token_tokenid",
+  "usageNotes": "Use this to update metadata or settings on an existing API token — such as adjusting its expiration date, toggling privilege separation, or updating a comment. When 'regenerate' is set, the response is the only opportunity to capture the new token secret; it cannot be retrieved again after this call. Callers must either own the token (self) or hold User.Modify on the user's group.",
+  "examples": [
+    {
+      "summary": "Rotate the secret for a monitoring service account token and extend its expiration by one year",
+      "path_params": {
+        "userid": "monitoring@pve",
+        "tokenid": "grafana-ro"
+      },
+      "params": {
+        "regenerate": true,
+        "expire": 1782000000,
+        "privsep": true,
+        "comment": "Rotated 2026-06-28 — annual rotation"
+      }
+    }
+  ],
+  "tips": [
+    "Capture the 'value' field from the response immediately when 'regenerate' is true — it is returned only once and cannot be retrieved via any subsequent GET.",
+    "The full tokenid string used in Authorization headers is '<userid>!<tokenid>' (e.g., 'monitoring@pve!grafana-ro'); the 'full-tokenid' field in the response provides this when regenerating.",
+    "Setting 'privsep': false grants the token all of the user's own privileges — use only for tightly scoped service accounts where ACL management overhead outweighs risk.",
+    "To clear an optional field (e.g., remove a comment or reset expiration to 'same as user'), pass its name in the 'delete' param as a comma-separated config-id list.",
+    "Regenerating invalidates the old secret immediately; coordinate rotation with all consumers before calling to avoid service interruption."
+  ],
+  "relatedOperations": [
+    "post_access_users_userid_token_tokenid",
+    "get_access_users_userid_token_tokenid",
+    "get_access_users_userid_token",
+    "delete_access_users_userid_token_tokenid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "put_access_users_userid_unlock_tfa",
+  "usageNotes": "Use this to clear a TFA lockout for a user who has been locked out after too many failed two-factor authentication attempts. The caller must hold the `User.Modify` privilege on the user's realm or group. Returns `true` on success; the user can then attempt TFA login again immediately.",
+  "examples": [
+    {
+      "summary": "Unlock TFA for a local Proxmox user who is locked out",
+      "path_params": {
+        "userid": "jsmith@pve"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The userid must use the full `name@realm` format (e.g., `admin@pam`, `jsmith@pve`).",
+    "This only clears the TFA lockout state — it does not remove or modify the user's configured TFA methods.",
+    "If the user is completely locked out of TFA (lost device/keys), remove or reset their TFA via the TFA endpoints after unlocking.",
+    "API tokens are permitted (`allowtoken: true`), so this can be scripted in automated helpdesk workflows."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid_tfa",
+    "put_access_users_userid_tfa",
+    "delete_access_users_userid_tfa_typeid",
+    "get_access_users_userid"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_cluster_acme_account_name",
+  "usageNotes": "Use this to update the contact email address(es) registered with the ACME CA for an existing account, or to force a refresh of the account record from the CA without changing anything (omit the `contact` param). Requires that an ACME account already exists under the given config name; create one first with the corresponding POST endpoint if it does not. Returns a task UPID — poll the task status endpoint to confirm completion.",
+  "examples": [
+    {
+      "summary": "Update the contact email on the default ACME account",
+      "path_params": {
+        "name": "default"
+      },
+      "params": {
+        "contact": "admin@example.com"
+      }
+    }
+  ],
+  "tips": [
+    "Calling this endpoint with no body (or an empty body) acts as a CA refresh — useful to resync account status after CA-side changes without modifying local config.",
+    "The `name` path param defaults to 'default', so omitting it targets the default ACME account.",
+    "The returned string is a UPID; use get_nodes_node_tasks_upid_status to track completion.",
+    "Multiple contact addresses can be supplied as a comma-separated email list in the `contact` field."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_account_name",
+    "post_cluster_acme_account",
+    "delete_cluster_acme_account_name",
+    "get_cluster_acme_account"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_cluster_acme_plugins_id",
+  "usageNotes": "Use this to modify an existing ACME DNS plugin configuration — swap the backing DNS provider API, rotate credentials in the base64-encoded `data` field, or adjust the `validation-delay` if DNS TTLs are causing certificate issuance failures. Requires `Sys.Modify` at the root path; the plugin must already exist (use post_cluster_acme_plugins to create). Pass `digest` (retrieved from get_cluster_acme_plugins_id) to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Update a Cloudflare DNS plugin to increase validation delay and rotate API credentials",
+      "path_params": {
+        "id": "cf-plugin"
+      },
+      "params": {
+        "api": "cf",
+        "data": "Q0ZfVG9rZW49eW91cl9jbG91ZGZsYXJlX2FwaV90b2tlbg==",
+        "validation-delay": 120,
+        "nodes": "pve1,pve2"
+      }
+    }
+  ],
+  "tips": [
+    "The `data` field must be base64-encoded key=value pairs matching the chosen DNS provider's required environment variables (e.g., CF_Token=xxx for Cloudflare).",
+    "Set `validation-delay` higher (e.g. 120-300s) when the DNS provider has slow propagation; the default 30s is often too short for providers with long TTLs.",
+    "Use the `delete` param to remove individual settings (e.g. `nodes`) rather than resending the full config — avoids accidentally clearing fields.",
+    "Use `disable: true` to temporarily take a plugin out of rotation without deleting it, useful when rotating credentials.",
+    "Returns null on success; any error indicates the update was not applied."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_plugins_id",
+    "post_cluster_acme_plugins",
+    "delete_cluster_acme_plugins_id",
+    "get_cluster_acme_plugins"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "put_cluster_backup_id",
+  "usageNotes": "Use this to modify an existing cluster-level vzdump backup job — changing its schedule, target storage, compression, retention policy, or guest scope. Requires 'Sys.Modify' on '/'; the 'tmpdir', 'dumpdir', and 'script' parameters are additionally restricted to root@pam. Returns null synchronously — the updated job takes effect on the next scheduler run, not immediately. To remove individual settings (e.g. strip a node pin), pass their names in the 'delete' field rather than omitting them.",
+  "examples": [
+    {
+      "summary": "Change a nightly backup job to use zstd compression, target PBS storage, and keep the last 7 daily backups",
+      "path_params": {
+        "id": "backup-f3a1c2d4-3e9b"
+      },
+      "params": {
+        "storage": "pbs-main",
+        "compress": "zstd",
+        "zstd": 2,
+        "schedule": "00:00",
+        "prune-backups": "keep-daily=7,keep-weekly=4",
+        "mode": "snapshot",
+        "enabled": true,
+        "comment": "Nightly full cluster backup — zstd, 7-day retention"
+      }
+    }
+  ],
+  "tips": [
+    "Use the 'delete' param to unset fields (e.g. 'delete': 'node') rather than sending an empty string — omitting a field leaves the existing value unchanged.",
+    "Prefer 'schedule' (systemd calendar format) over the deprecated 'starttime'/'dow' combo; Proxmox converts old-style entries automatically but new jobs should use the modern format.",
+    "Setting 'repeat-missed': true is useful for clusters where the node may be offline during the scheduled window — the job will fire as soon as the scheduler comes back up.",
+    "Backup fleecing ('fleecing' param) can significantly reduce guest downtime during VM backups by staging changed blocks to a scratch storage; requires a fast local storage ID.",
+    "To temporarily pause a job without deleting it, set 'enabled': false instead of removing the job."
+  ],
+  "relatedOperations": [
+    "get_cluster_backup_id",
+    "get_cluster_backup",
+    "post_cluster_backup",
+    "delete_cluster_backup_id",
+    "post_cluster_backup_id_included_volumes"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "put_cluster_ceph_flags",
+  "usageNotes": "Use this to atomically set or unset one or more Ceph cluster-wide feature flags (e.g. suspending backfill, scrubbing, or rebalancing) in a single call; omitted flags are left unchanged. Requires Sys.Modify on / (root). The operation runs as a worker task and returns a UPID — poll the task status if you need to confirm completion before proceeding.",
+  "examples": [
+    {
+      "summary": "Suspend backfill and rebalancing during a planned OSD maintenance window, then re-enable them after",
+      "path_params": {},
+      "params": {
+        "nobackfill": true,
+        "norebalance": true
+      }
+    }
+  ],
+  "tips": [
+    "Flags like 'noout' and 'norebalance' are commonly paired during OSD replacement to prevent premature data movement.",
+    "Setting 'pause' halts all Ceph reads and writes cluster-wide — use only in a controlled, coordinated maintenance window.",
+    "After maintenance, call this endpoint again with the same flags set to false to restore normal cluster behavior; do not rely on Proxmox to auto-clear them.",
+    "Check current flag state with get_cluster_ceph_flags before writing to avoid accidentally clearing flags set by another operator."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_flags",
+    "get_cluster_ceph_status",
+    "get_nodes_node_ceph_osd"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "put_cluster_ceph_flags_flag",
+  "usageNotes": "Use this to set or clear a single Ceph cluster flag (e.g., noout, nobackfill) during maintenance windows or incident response. Requires Sys.Modify at the root path and executes synchronously — no UPID is returned, so the change takes effect immediately. Always clear maintenance flags (noout, norebalance) after completing cluster work to restore normal data balancing.",
+  "examples": [
+    {
+      "summary": "Set noout flag to prevent OSDs from being marked out during a planned maintenance window",
+      "path_params": {
+        "flag": "noout"
+      },
+      "params": {
+        "value": true
+      }
+    }
+  ],
+  "tips": [
+    "noout is the most commonly used flag during OSD or host maintenance — it prevents Ceph from triggering data rebalancing when OSDs go offline.",
+    "pause halts both reads and writes cluster-wide; use only in emergencies as it causes full I/O stall.",
+    "This endpoint targets one flag at a time and is synchronous; the bulk PUT /cluster/ceph/flags endpoint sets multiple flags but forks an async worker task.",
+    "Forgetting to clear flags like noout or norebalance after maintenance leaves the cluster in a degraded-but-silent state where failures won't trigger recovery."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_flags_flag",
+    "get_cluster_ceph_flags",
+    "put_cluster_ceph_flags"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "put_cluster_firewall_aliases_name",
+  "usageNotes": "Use this to update the CIDR, comment, or name of an existing cluster-level firewall alias. Requires `Sys.Modify` on `/`. Pass the `digest` field (obtained from the GET alias endpoint) to guard against concurrent edits overwriting each other. To rename an alias, supply the new name in `rename` while the path `{name}` remains the current name.",
+  "examples": [
+    {
+      "summary": "Update alias CIDR and rename it from 'office-net' to 'hq-net'",
+      "path_params": {
+        "name": "office-net"
+      },
+      "params": {
+        "cidr": "203.0.113.0/24",
+        "rename": "hq-net",
+        "comment": "HQ main office subnet"
+      }
+    }
+  ],
+  "tips": [
+    "The `digest` param is the SHA1 of the current config file — fetch it via GET /cluster/firewall/aliases/{name} before updating to enable optimistic concurrency control.",
+    "Alias names must start with a letter and may only contain letters, digits, hyphens, and underscores (pattern: [A-Za-z][A-Za-z0-9\\-\\_]+); the new name in `rename` follows the same constraint.",
+    "This operation is cluster-wide; the updated alias is immediately available to all node and VM firewall rules that reference it."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_aliases_name",
+    "get_cluster_firewall_aliases",
+    "post_cluster_firewall_aliases",
+    "delete_cluster_firewall_aliases_name"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_cluster_firewall_groups_group_pos",
+  "usageNotes": "Use this to modify an existing firewall rule within a cluster-level security group, identified by its zero-based position index. Requires `Sys.Modify` on the root path (`/`). Pass `digest` (obtained from the corresponding GET) to guard against concurrent edits overwriting each other. When `moveto` is supplied, all other body fields are ignored — the rule is repositioned only.",
+  "examples": [
+    {
+      "summary": "Change an ACCEPT rule in the 'web-servers' security group at position 2 to DROP and add a descriptive comment",
+      "path_params": {
+        "group": "web-servers",
+        "pos": 2
+      },
+      "params": {
+        "action": "DROP",
+        "comment": "Temporarily blocking inbound until patch window closes",
+        "enable": 1,
+        "type": "in"
+      }
+    }
+  ],
+  "tips": [
+    "Fetch the current rule with GET /cluster/firewall/groups/{group}/{pos} first — capture the `digest` field and pass it back to prevent lost-update races.",
+    "Use the `delete` param (comma-separated field names) to clear optional fields like `comment` or `source` without touching the rest of the rule.",
+    "To reorder a rule without changing its content, supply only `moveto`; all other params are silently ignored by the API.",
+    "Security group names must start with a letter and be 2–18 characters matching [A-Za-z][A-Za-z0-9\\-\\_]+.",
+    "Changes apply to every VM/container and host that references this security group — verify scope before committing in production."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_groups_group_pos",
+    "get_cluster_firewall_groups_group",
+    "post_cluster_firewall_groups_group",
+    "delete_cluster_firewall_groups_group_pos"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_cluster_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to update the comment or nomatch flag on an existing IP/CIDR entry within a cluster-level firewall IPset. The caller must hold the Sys.Modify privilege at the root path (/). Pass the current config digest to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Set the nomatch flag on a CIDR entry to exclude it from the IPset match",
+      "path_params": {
+        "name": "trusted-offices",
+        "cidr": "10.20.30.0/24"
+      },
+      "params": {
+        "nomatch": true,
+        "comment": "Exclude branch office subnet from trusted-offices set",
+        "digest": "a3f1c2e4b5d6789012345678abcdef01234567890abcdef1234567890abcdef12"
+      }
+    }
+  ],
+  "tips": [
+    "The nomatch flag inverts the entry's match within the IPset — useful for punching exceptions into a broad CIDR without removing the surrounding range.",
+    "Fetch the current digest via get_cluster_firewall_ipset_name before calling this endpoint to avoid overwriting concurrent changes.",
+    "The cidr path param accepts plain IPs, CIDR notation, or IPset aliases — match exactly how the entry was originally created.",
+    "Returns null on success; any error is signalled via HTTP status code, not a response body."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipset_name",
+    "post_cluster_firewall_ipset_name",
+    "delete_cluster_firewall_ipset_name_cidr",
+    "get_cluster_firewall_ipset"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_cluster_firewall_options",
+  "usageNotes": "Use this to enable/disable the cluster-wide firewall or change its default policies and logging behavior. Changes take effect immediately across all nodes without a task UPID — the response is null on success. Pass the `digest` from `get_cluster_firewall_options` to guard against concurrent modifications; omit it only when you are certain no concurrent edits are possible.",
+  "examples": [
+    {
+      "summary": "Enable the cluster firewall with DROP default input policy and rate-limited logging",
+      "path_params": {},
+      "params": {
+        "enable": 1,
+        "policy_in": "DROP",
+        "policy_out": "ACCEPT",
+        "ebtables": true,
+        "log_ratelimit": "enable=1,burst=5,rate=1/second"
+      }
+    }
+  ],
+  "tips": [
+    "The firewall is disabled by default (enable=0); enabling it cluster-wide will enforce policy_in/policy_out on all nodes immediately — verify your rules before setting policy_in to DROP or REJECT to avoid locking yourself out.",
+    "Use the `delete` param (comma-separated config key names) to revert specific settings back to their defaults rather than overwriting with explicit values.",
+    "ebtables controls layer-2 (Ethernet bridge) filtering; leave it enabled (default) unless you have a specific reason to disable it, as disabling it removes bridge-level MAC/ARP filtering across the cluster.",
+    "Fetch the current digest via GET /cluster/firewall/options and echo it back to prevent a lost-update race condition in automation scripts."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_options",
+    "get_cluster_firewall_rules",
+    "post_cluster_firewall_rules",
+    "get_nodes_node_firewall_options"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "put_cluster_firewall_rules_pos",
+  "usageNotes": "Use this endpoint to modify an existing cluster-level firewall rule in-place by its zero-based position index, or to reorder it via `moveto` (when `moveto` is set, all other body fields are ignored). Requires `Sys.Modify` on `/`; changes take effect immediately on the cluster firewall chain without a daemon restart. Pass the `digest` from the current rule read to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Disable an existing ACCEPT rule at position 3 and add a comment",
+      "path_params": {
+        "pos": 3
+      },
+      "params": {
+        "enable": 0,
+        "comment": "Temporarily disabled - maintenance window",
+        "digest": "a3f1c2d4e5b6a7f8c9d0e1f2a3b4c5d6e7f8a9b0"
+      }
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-based; retrieve current positions first with GET /cluster/firewall/rules before updating.",
+    "Use `moveto` alone to reorder a rule without changing any of its properties — all other params are silently ignored when `moveto` is present.",
+    "The `delete` param accepts a comma-separated list of field names (e.g. `dest,sport`) to unset optional fields on the rule.",
+    "Returns null on success; a non-2xx response means the rule was not modified.",
+    "Cluster firewall rules apply to traffic between cluster nodes; they are distinct from per-VM/CT firewall rules."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_rules",
+    "get_cluster_firewall_rules_pos",
+    "post_cluster_firewall_rules",
+    "delete_cluster_firewall_rules_pos"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_cluster_ha_groups_group",
+  "usageNotes": "Use this to modify an existing HA group's node membership, failback behavior, or restricted-placement policy — note the Proxmox API marks this endpoint deprecated in favor of HA rules. The call requires `Sys.Console` on `/` and returns null synchronously (no UPID); changes take effect immediately in the CRM. Pass the `digest` field (obtained from the GET endpoint) to guard against concurrent edits clobbering each other.",
+  "examples": [
+    {
+      "summary": "Update 'prod-ha' group to pin resources to two nodes with priority, disable failback, and restrict placement to those nodes only",
+      "path_params": {
+        "group": "prod-ha"
+      },
+      "params": {
+        "nodes": "pve-node1:100,pve-node2:50",
+        "nofailback": true,
+        "restricted": true,
+        "comment": "Production HA group — no failback, restricted to primary nodes"
+      }
+    }
+  ],
+  "tips": [
+    "Node priority is optional per node; omit it to treat all nodes as equal weight (e.g. 'pve-node1,pve-node2').",
+    "Setting 'restricted: true' without a complete 'nodes' list can leave HA resources with nowhere valid to run — verify all target nodes are online before saving.",
+    "Use the 'delete' param (comma-separated config keys like 'comment,nofailback') to unset fields rather than setting them to empty strings.",
+    "This endpoint is deprecated; prefer HA rules (ha/rules) for new configurations, but this endpoint remains the only way to edit pre-existing groups in-place."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_groups_group",
+    "get_cluster_ha_groups",
+    "post_cluster_ha_groups",
+    "delete_cluster_ha_groups_group",
+    "get_cluster_ha_resources"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "put_cluster_ha_resources_sid",
+  "usageNotes": "Use this to modify an existing HA resource's configuration — changing its target state, HA group membership, restart/relocate retry limits, or failback behavior — without removing and re-adding it. Requires `Sys.Console` on `/` (root), so only cluster administrators can call it. The operation returns null synchronously; state changes (e.g. started → stopped) are enacted by the HA manager asynchronously, so poll the resource's actual state via GET after updating.",
+  "examples": [
+    {
+      "summary": "Move VM 105 into an HA group and cap restart retries, then request it start",
+      "path_params": {
+        "sid": "vm:105"
+      },
+      "params": {
+        "group": "prod-ha-group",
+        "state": "started",
+        "max_restart": 2,
+        "max_relocate": 2,
+        "failback": true,
+        "comment": "Critical web VM - high availability group with failback"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `digest` parameter when scripting to guard against concurrent edits — fetch the current digest via GET first, then pass it on PUT.",
+    "Setting `state` to `ignored` tells the HA manager to leave the resource alone entirely; useful for planned maintenance without removing the resource from HA.",
+    "The `delete` param accepts a comma-separated list of config keys (e.g. `comment,group`) to revert individual fields to their defaults without touching the rest.",
+    "Changing `group` does not immediately migrate the resource; the HA manager will relocate it when it next evaluates the resource placement.",
+    "The shorthand `sid` format (e.g. `100`) resolves to `vm:100` or `ct:100` automatically; use the explicit form when the type matters for clarity."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources_sid",
+    "post_cluster_ha_resources",
+    "delete_cluster_ha_resources_sid",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_groups"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "put_cluster_ha_rules_rule",
+  "usageNotes": "Use this to modify an existing HA rule's affinity type, node list, resource assignments, or enabled/disabled state — changes take effect immediately with no UPID returned. The `type` parameter is required even when you are not changing it; always pass the current type to avoid an API error. Use `digest` to guard against concurrent edits, especially in automated workflows.",
+  "examples": [
+    {
+      "summary": "Switch a node-affinity rule to negative (anti-affinity) and add a second node with lower priority",
+      "path_params": {
+        "rule": "ha-affinity-rule1"
+      },
+      "params": {
+        "type": "node-affinity",
+        "affinity": "negative",
+        "nodes": "pve1:100,pve2:50",
+        "comment": "Keep HA VMs on separate nodes for fault isolation",
+        "strict": false
+      }
+    }
+  ],
+  "tips": [
+    "The `type` field is required on every PUT even if you are only updating other fields like `affinity` or `comment`.",
+    "Use the `delete` param (comma-separated field names, e.g. `delete: 'comment,nodes'`) to clear optional fields rather than setting them to empty strings.",
+    "Fetch the current rule's digest via GET /cluster/ha/rules/{rule} and pass it back to prevent lost-update races.",
+    "Disabling a rule (`disable: true`) keeps the rule definition intact while temporarily suspending enforcement — useful for maintenance windows.",
+    "Node priorities in the `nodes` list are relative integers; higher values are preferred. Omitting `:pri` defaults to priority 0.",
+    "For `resource-affinity` rules the `nodes` field is not applicable; use `resources` to specify vm:<vmid> or ct:<vmid> pairs."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_rules_rule",
+    "post_cluster_ha_rules",
+    "delete_cluster_ha_rules_rule",
+    "get_cluster_ha_rules"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_cluster_jobs_realm_sync_id",
+  "usageNotes": "Use this to update an existing realm-sync job's schedule, scope, vanish policy, or enabled state — the job must already exist (create it first with POST /cluster/jobs/realm-sync). The calling token or user needs both 'Realm.AllocateUser' on the target realm path and 'User.Modify' on /access/groups; lacking either will result in a 403. The operation returns null synchronously — no UPID is issued — but the updated schedule takes effect on the next systemd-calendar trigger.",
+  "examples": [
+    {
+      "summary": "Change an LDAP realm-sync job to run nightly, sync both users and groups, and remove vanished entries plus their ACLs",
+      "path_params": {
+        "id": "ldap-nightly-sync"
+      },
+      "params": {
+        "schedule": "daily",
+        "scope": "both",
+        "remove-vanished": "entry;acl",
+        "enable-new": true,
+        "enabled": true,
+        "comment": "Nightly full sync for corp-ldap realm"
+      }
+    }
+  ],
+  "tips": [
+    "Use the 'delete' param (comma-separated field names) to revert optional fields like 'comment' or 'remove-vanished' back to their defaults rather than explicitly setting them to empty strings.",
+    "The 'remove-vanished' default is 'none', meaning users and groups that disappear from the directory are kept in Proxmox — set 'entry;acl' if you want automated cleanup.",
+    "schedule follows systemd calendar event syntax (e.g., 'daily', 'hourly', 'Mon 03:00') — test the expression with 'systemd-analyze calendar <expr>' on a cluster node before applying.",
+    "Disabling the job via 'enabled: false' is the safest way to pause syncs during directory maintenance without deleting the job definition."
+  ],
+  "relatedOperations": [
+    "post_cluster_jobs_realm_sync",
+    "get_cluster_jobs_realm_sync_id",
+    "delete_cluster_jobs_realm_sync_id",
+    "get_cluster_jobs_realm_sync"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_cluster_mapping_dir_id",
+  "usageNotes": "Use this to modify an existing cluster-wide directory mapping — update its description, change node-to-path mappings via the `map` array, or remove individual settings using the `delete` field. Requires the `Mapping.Modify` privilege on `/mapping/dir/{id}`. Pass the `digest` field (retrieved from a prior GET) to guard against concurrent edits overwriting each other. Returns null on success; any error is signaled via HTTP status.",
+  "examples": [
+    {
+      "summary": "Update a shared-storage directory mapping to add a new node path and refresh its description",
+      "path_params": {
+        "id": "shared-nfs"
+      },
+      "params": {
+        "description": "NFS share mounted on pve01 and pve02 under /mnt/nfs-share",
+        "map": [
+          "node=pve01,path=/mnt/nfs-share",
+          "node=pve02,path=/mnt/nfs-share"
+        ],
+        "digest": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` field (comma-separated configid list) to unset optional fields like `description` without resending the full payload.",
+    "Fetch the current mapping with GET /cluster/mapping/dir/{id} first to obtain a valid `digest` value before modifying.",
+    "The `map` array format is node-keyed; each element typically follows `node=<nodename>,path=<absolute-path>` — verify the exact format against your PVE version's schema.",
+    "Directory mappings are cluster-wide; a change here affects how all nodes resolve the mapping ID to a local path."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_dir_id",
+    "post_cluster_mapping_dir",
+    "delete_cluster_mapping_dir_id",
+    "get_cluster_mapping_dir"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "put_cluster_mapping_pci_id",
+  "usageNotes": "Use this to modify an existing cluster-wide logical PCI mapping — updating which physical PCI devices on each node back the mapping, toggling mdev/live-migration-capable flags, or refreshing the description. Requires the Mapping.Modify privilege on /mapping/pci/{id}. Pass the digest returned from the corresponding GET to prevent overwriting concurrent changes.",
+  "examples": [
+    {
+      "summary": "Add a node entry and enable mdev on an existing GPU mapping",
+      "path_params": {
+        "id": "gpu-a2000"
+      },
+      "params": {
+        "description": "NVIDIA RTX A2000 - mediated device pool",
+        "mdev": true,
+        "map": [
+          "node=pve01,id=0000:03:00",
+          "node=pve02,id=0000:05:00"
+        ]
+      }
+    }
+  ],
+  "tips": [
+    "Fetch the current mapping first (get_cluster_mapping_pci_id) to obtain the digest before writing.",
+    "Use the 'delete' param to remove individual keys (e.g., 'description') without touching the rest of the mapping.",
+    "live-migration-capable is experimental; enabling it without compatible hardware/drivers will cause migration failures.",
+    "The mapping must already exist — use post_cluster_mapping_pci to create a new one."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_pci_id",
+    "post_cluster_mapping_pci",
+    "delete_cluster_mapping_pci_id",
+    "get_cluster_mapping_pci"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "put_cluster_mapping_usb_id",
+  "usageNotes": "Use this to modify an existing cluster-level USB hardware mapping — update which physical USB device each node maps to, change the description, or remove specific fields via 'delete'. Requires 'Mapping.Modify' on '/mapping/usb/{id}'. Pass the 'digest' from the current mapping to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Remap a USB dongle to a different bus/port on node pve2 while clearing the old description",
+      "path_params": {
+        "id": "yubi-key-prod"
+      },
+      "params": {
+        "map": [
+          "node=pve1,path=/dev/bus/usb/001/003",
+          "node=pve2,path=/dev/bus/usb/002/005"
+        ],
+        "description": "YubiKey 5 NFC - production auth dongle",
+        "delete": "description",
+        "digest": "a3f1c29b7e0d4512"
+      }
+    }
+  ],
+  "tips": [
+    "The 'map' array must include an entry for every cluster node that should expose the device; nodes omitted from the list lose access to the mapping.",
+    "Use 'delete' (comma-separated config key names) to remove optional fields such as 'description' rather than setting them to empty strings.",
+    "Read the current mapping first (get_cluster_mapping_usb_id) to obtain the 'digest' value before updating — prevents silent overwrites in multi-admin environments.",
+    "USB mappings are referenced by VMs using the mapped ID; updating path values takes effect on the next VM start, not live."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_usb_id",
+    "post_cluster_mapping_usb",
+    "delete_cluster_mapping_usb_id",
+    "get_cluster_mapping_usb"
+  ]
+}