@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,44 @@
+{
+  "operationId": "post_subscriptions_bulk_assign",
+  "usageNotes": "Commits the assignment plan produced by `get_subscriptions_auto_assign` — always call that endpoint first and pass its full response as `proposal`. The handler validates two digests (pool-config and live node-status) embedded in the proposal and rejects with HTTP 409 if either has changed since the plan was computed, so callers must re-fetch the proposal and retry after any topology or key-pool change. The caller must hold `PRIV_RESOURCE_MODIFY` on each remote referenced in the proposal in addition to the top-level `System.Modify` privilege; an audit-only caller cannot commit a plan even if they rendered the preview.",
+  "examples": [
+    {
+      "summary": "Commit an auto-assign plan to distribute three subscription keys across two remotes",
+      "path_params": {},
+      "params": {
+        "proposal": {
+          "assignments": [
+            {
+              "key": "pve-enterprise-abc123",
+              "node": "pve-node-01",
+              "remote": "hetzner-pve"
+            },
+            {
+              "key": "pve-enterprise-def456",
+              "node": "pve-node-02",
+              "remote": "hetzner-pve"
+            },
+            {
+              "key": "pdm-enterprise-ghi789",
+              "node": "pdm-host",
+              "remote": "ovh-pdm"
+            }
+          ],
+          "keys_digest": "a3f8c2e1d94b7056",
+          "node_status_digest": "b7e1d0c3a4f29518"
+        }
+      }
+    }
+  ],
+  "tips": [
+    "Always use Content-Type: application/json — the nested proposal object cannot be encoded as form-urlencoded.",
+    "A 409 response means the pool or node topology changed between plan generation and commit; re-call get_subscriptions_auto_assign and resubmit.",
+    "The returned array lists only the assignments actually persisted — compare against your proposal to detect any partial application.",
+    "API tokens are supported (allowtoken: true); scope the token to System.Modify plus per-remote PRIV_RESOURCE_MODIFY."
+  ],
+  "relatedOperations": [
+    "get_subscriptions_auto_assign",
+    "get_subscriptions",
+    "get_nodes"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_subscriptions_check",
+  "usageNotes": "Use this to force an immediate re-validation of a remote node's subscription status against the Proxmox shop, bypassing the normal ~5-minute cache — useful when a subscription has just been purchased, renewed, or was incorrectly marked Invalid/Expired. The call makes an outbound HTTPS request from PDM to shop.proxmox.com, so the target node must be online and reachable. Requires `PRIV_RESOURCE_MODIFY` on the remote in addition to the top-level `System.Modify` privilege; API tokens are permitted.",
+  "examples": [
+    {
+      "summary": "Force a subscription re-check on a Proxmox VE node named 'pve01' registered under the remote 'hetzner-de'",
+      "path_params": {},
+      "params": {
+        "node": "pve01",
+        "remote": "hetzner-de"
+      }
+    }
+  ],
+  "tips": [
+    "The endpoint returns null on success — absence of an error is the success signal.",
+    "After calling this, read the node's subscription status (e.g. via get_nodes_node or equivalent) to confirm the fresh verdict; the cache is invalidated immediately but the UI may need a manual refresh.",
+    "Pass 'localhost' as the node value only when PDM itself is the target node.",
+    "The remote ID must match exactly as registered in PDM (2–32 chars, alphanumeric with dots/dashes/underscores, no leading dot or dash)."
+  ],
+  "relatedOperations": [
+    "get_subscriptions",
+    "get_remotes_remote_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_subscriptions_clear_pending",
+  "usageNotes": "Use this endpoint to discard stuck or unwanted queued subscription changes in bulk without touching the remote nodes — useful when a target node is offline or gone and you want to unblock the pool without first bringing the remote back online. Only entries the caller has `System.Modify` on are affected; entries where the caller only has audit access are silently skipped. Pass the current config `digest` to guard against concurrent admin edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Clear all pending subscription changes with optimistic-lock protection",
+      "path_params": {},
+      "params": {
+        "digest": "a3f1c2e4b5d6789012345678abcdef1234567890abcdef1234567890abcdef12"
+      }
+    }
+  ],
+  "tips": [
+    "The response `cleared` count reflects how many pool entries were actually modified; a result of 0 means no pending changes matched your privilege scope.",
+    "Omit `digest` for a force-clear when you do not have the current config hash at hand, accepting the risk of overwriting a concurrent change.",
+    "This operation is the discard counterpart to `post_subscriptions_apply_pending` — prefer apply-pending when the remote is reachable and you want the changes pushed rather than dropped.",
+    "Entries where the remote is unreachable have their binding returned to the free pool; the live key on the remote is not modified by this call."
+  ],
+  "relatedOperations": [
+    "post_subscriptions_apply_pending",
+    "get_subscriptions",
+    "put_subscriptions_key"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_subscriptions_keys",
+  "usageNotes": "Use this endpoint to register one or more PVE or PBS subscription keys with the PDM subscription pool; PMG/POM keys are not yet supported. The call is all-or-nothing: if any key has an unrecognized prefix or already exists in the pool, the entire request fails and the pool is left untouched. Pass the digest returned by a prior read to guard against concurrent modifications, or chain follow-up mutations directly using the digest included in the response without a separate refetch.",
+  "examples": [
+    {
+      "summary": "Add two PBS subscription keys to the pool",
+      "path_params": {},
+      "params": {
+        "keys": [
+          "pbst-abc123def456ghi7",
+          "pbst-xyz987uvw654rst3"
+        ]
+      }
+    }
+  ],
+  "tips": [
+    "Duplicate keys within a single request are silently collapsed — check the 'deduplicated' field in the response to distinguish accidental double-paste from an actual add.",
+    "A key that already exists in the pool causes a hard CONFLICT error for the whole request; remove existing keys first with the corresponding DELETE endpoint if you need to re-add.",
+    "Keys must match the PRODUCT_KEY_REGEX pattern (PVE or PBS prefix); validate prefixes client-side before submitting to avoid an all-or-nothing failure on a large batch.",
+    "The response includes a fresh digest, allowing you to chain a follow-up write (e.g., delete or update) without an extra GET round-trip."
+  ],
+  "relatedOperations": [
+    "get_subscriptions_keys",
+    "delete_subscriptions_keys"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_subscriptions_keys_key_assignment",
+  "usageNotes": "Use this to bind a subscription pool key to a specific node on a managed remote. The caller must hold `System.Modify` on the PDM system plus `PRIV_RESOURCE_MODIFY` on the target remote — you cannot assign a key to a remote you lack authority on. Returns null on success; check for a 4xx/5xx error response to detect conflicts.",
+  "examples": [
+    {
+      "summary": "Assign a PVE community key to node pve-prod-01 on remote datacenter-hetzner",
+      "path_params": {
+        "key": "pve4c-a1b2c3d4e5"
+      },
+      "params": {
+        "remote": "datacenter-hetzner",
+        "node": "pve-prod-01",
+        "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+      }
+    }
+  ],
+  "tips": [
+    "Supply the optional `digest` param (SHA256 of the current config) to prevent lost-update races when multiple operators manage subscription assignments concurrently.",
+    "Key format is strictly `pve<N><tier>-<10 hex chars>` for PVE keys or `pbs<tier>-<10 hex chars>` for PBS keys — validate client-side before calling to surface format errors early.",
+    "A node value of `localhost` is accepted and refers to the node local to the remote, useful when the remote has a single node.",
+    "This call is synchronous and returns null — no UPID is issued; completion is immediate or an error is returned."
+  ],
+  "relatedOperations": [
+    "get_subscriptions_keys",
+    "post_subscriptions_keys",
+    "delete_subscriptions_keys_key",
+    "get_subscriptions_keys_key_assignment",
+    "delete_subscriptions_keys_key_assignment"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_subscriptions_queue_clear",
+  "usageNotes": "Use this to stage the removal of a subscription key from a specific remote node so the key can be reassigned elsewhere; it sets a `pending_clear` flag on the pool entry but does not immediately DELETE the subscription — a subsequent 'Apply Pending' operation performs the actual removal. The (remote, node) pair must already have a pool entry bound to it; if no binding exists the call will fail, as importing a foreign subscription is handled by the Adopt Key action instead. Callers need `System.Modify` globally plus per-remote `PRIV_RESOURCE_MODIFY` on the target remote.",
+  "examples": [
+    {
+      "summary": "Queue a subscription clear for node 'pve-node1' on remote 'datacenter-eu'",
+      "path_params": {},
+      "params": {
+        "remote": "datacenter-eu",
+        "node": "pve-node1",
+        "digest": "a3f1c2d4e5b6a7f8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
+      }
+    }
+  ],
+  "tips": [
+    "After queueing a clear, use 'Apply Pending' to execute the DELETE on the remote and release the binding; use 'Discard Pending' if you want to cancel without touching the remote.",
+    "Pass the current config digest to guard against concurrent modifications — omit it only in automated scripts where races are acceptable.",
+    "If the call returns an error about no bound pool entry, you must Adopt the key into the pool first before a clear can be queued."
+  ],
+  "relatedOperations": [
+    "post_subscriptions_apply_pending",
+    "post_subscriptions_discard_pending",
+    "post_subscriptions_adopt_key"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_subscriptions_revert_pending_clear",
+  "usageNotes": "Use this to cancel a queued 'Clear Key' action on a specific remote/node pair without discarding all other pending changes in the pool. This is the surgical undo for a misqueued clear — the subscription binding remains intact so the operator can re-queue or leave the live key in place. Pass the current config digest to guard against concurrent modifications racing this reversal.",
+  "examples": [
+    {
+      "summary": "Revert a queued key clear for node 'pve-node1' on remote 'hetzner-prod'",
+      "path_params": {},
+      "params": {
+        "remote": "hetzner-prod",
+        "node": "pve-node1",
+        "digest": "a3f1c2e4b5d6789012345678901234567890abcd1234567890abcdef12345678"
+      }
+    }
+  ],
+  "tips": [
+    "This targets one remote/node pair only — use the global Discard Pending path if you need to roll back all pending changes at once.",
+    "The digest param is optional but recommended in automated workflows to prevent a concurrent operator change from being silently overwritten.",
+    "Returns null on success; treat any non-2xx response as a sign the pending clear was already applied or the binding no longer exists."
+  ],
+  "relatedOperations": [
+    "post_subscriptions_queue_clear",
+    "post_subscriptions_discard_pending"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "put_access_acl",
+  "usageNotes": "Use this to grant or revoke a role on an ACL path for a specific auth-id (user or API token) or group — supply exactly one of `auth-id` or `group`, not both. Set `delete: true` to remove the permission instead of adding it. Use the `digest` parameter when making changes in scripts to guard against concurrent modifications overwriting each other.",
+  "examples": [
+    {
+      "summary": "Grant the Administrator role to a user at the root path with propagation enabled",
+      "path_params": {},
+      "params": {
+        "path": "/",
+        "role": "Administrator",
+        "auth-id": "admin@pam",
+        "propagate": true
+      }
+    }
+  ],
+  "tips": [
+    "Only one of `auth-id` or `group` should be provided per call; supplying neither results in an error.",
+    "The `path` must match the ACL path hierarchy used by PDM (e.g., `/`, `/mapping`, `/remotes/my-remote`); invalid paths are rejected.",
+    "Tokens (auth-id with `!` separator, e.g., `admin@pam!mytoken`) can only be granted roles that are a subset of the owning user's roles — PDM enforces this automatically.",
+    "Returns null on success; no confirmation body is returned, so verify with get_access_acl after making changes.",
+    "Setting `propagate: false` scopes the permission strictly to that path and does not cascade to child paths."
+  ],
+  "relatedOperations": [
+    "get_access_acl"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "put_access_tfa_userid_id",
+  "usageNotes": "Use this to rename or toggle a user's existing TFA entry — for example, to disable a hardware key that is temporarily unavailable or to label entries when a user registers multiple authenticators. The TFA entry ID must already exist; obtain it first via the corresponding GET. An admin with Access.Modify can update any user's entry, while a user can update their own; when acting as the owning user, Proxmox may require the current account password via the `password` field.",
+  "examples": [
+    {
+      "summary": "Disable a TOTP entry for a user and give it a descriptive label",
+      "path_params": {
+        "userid": "jsmith@pve",
+        "id": "totp-7f3a2b1c"
+      },
+      "params": {
+        "description": "Backup TOTP - phone (disabled while traveling)",
+        "enable": false
+      }
+    }
+  ],
+  "tips": [
+    "Returns null on success — absence of an error is the confirmation.",
+    "The `password` param is required when the calling principal is the entry owner (non-admin) on realms that enforce confirmation.",
+    "To find the TFA entry `id`, call the GET /access/tfa/{userid} list endpoint first — IDs are opaque strings like 'totp-<uuid>'.",
+    "Toggling `enable` to false is a safe way to temporarily lock out a second factor without deleting it; re-enable it later without re-enrollment."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "post_access_tfa_userid",
+    "delete_access_tfa_userid_id"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_access_users_userid",
+  "usageNotes": "Use this to update an existing PDM user's profile fields (name, email, comment), enable/disable the account, or set an expiration date. A user can update their own account without elevated privileges; modifying other users requires Access.Modify on /access/users. Use the 'delete' array to clear optional fields (e.g. email or comment) rather than setting them to empty strings.",
+  "examples": [
+    {
+      "summary": "Disable a user account and set an expiration date",
+      "path_params": {
+        "userid": "jdoe@pve"
+      },
+      "params": {
+        "enable": false,
+        "expire": 1751155200,
+        "comment": "Account suspended pending review"
+      }
+    }
+  ],
+  "tips": [
+    "The 'digest' field can be supplied (SHA256 of current config) to guard against concurrent modifications — retrieve it from the corresponding GET /access/users/{userid} response.",
+    "Setting 'expire' to 0 removes any expiration date; omitting the field leaves the existing value unchanged.",
+    "Password changes via this endpoint apply only to users in the 'pve' realm — users authenticated via LDAP/AD must have passwords changed in the upstream directory.",
+    "To clear an optional field entirely, pass its name in the 'delete' array instead of setting it to an empty string."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid",
+    "post_access_users",
+    "delete_access_users_userid",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_access_users_userid_token_token_name",
+  "usageNotes": "Use this to update metadata (comment, expiry, enabled state) on an existing API token, or to rotate the token secret without changing its permissions by setting regenerate=true. The token secret is only returned in the response when regenerate=true — store it immediately, as PDM will not surface it again. A user may update their own tokens without Access.Modify; that privilege is only required to modify tokens belonging to other users.",
+  "examples": [
+    {
+      "summary": "Rotate the secret for an automation token while keeping its current permissions",
+      "path_params": {
+        "userid": "automation@pve",
+        "token-name": "deploy-token"
+      },
+      "params": {
+        "regenerate": true,
+        "comment": "Rotated 2026-06-29 — quarterly rotation"
+      }
+    }
+  ],
+  "tips": [
+    "Setting regenerate=true invalidates the old secret immediately; update any services using the token before or right after the call.",
+    "Use the digest param to guard against concurrent modifications when multiple admins may update the same token.",
+    "To clear the comment or expire fields, include them in the delete array rather than setting them to empty strings.",
+    "Disabling a token (enable=false) is a safe way to temporarily block access without losing the token configuration."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid_token_token_name",
+    "post_access_users_userid_token_token_name",
+    "delete_access_users_userid_token_token_name",
+    "get_access_users_userid_token"
+  ]
+}

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

@@ -0,0 +1,44 @@
+{
+  "operationId": "put_auto_install_prepared_id",
+  "usageNotes": "Use this to update an existing prepared auto-installer answer configuration by its ID — for example, to change network settings, disk selection, root credentials, or target-filter rules after the config was initially created. The operation is synchronous and returns the updated config object immediately (no task UPID). Requires `System.Modify` on the `system/auto-installation` path; pass the `digest` field from a prior GET to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Update a prepared config to use static networking and pin a specific disk",
+      "path_params": {
+        "id": "pve-rack1-node3"
+      },
+      "params": {
+        "cidr": "192.168.10.53/24",
+        "gateway": "192.168.10.1",
+        "dns": "192.168.10.1",
+        "use-dhcp-network": false,
+        "fqdn": "rack1-node3.internal.example.com",
+        "use-dhcp-fqdn": false,
+        "disk-mode": "list",
+        "disk-list": ["sda"],
+        "filesystem": {
+          "filesystem": "zfs",
+          "ashift": 12
+        },
+        "timezone": "America/Los_Angeles",
+        "keyboard": "en-us",
+        "reboot-mode": "reboot",
+        "digest": "a3f1c2e4b5d6789012345678901234567890abcdef1234567890abcdef123456"
+      }
+    }
+  ],
+  "tips": [
+    "Only one config can have `is-default: true`; setting it on this record clears the flag from whichever config previously held it.",
+    "Fields with MiniJinja template support (cidr, gateway, dns, fqdn, mailto) are validated at render time, not at save time — invalid templates will not be caught here.",
+    "Use the `delete` array to remove optional fields (e.g., `[\"target-filter\"]`) rather than sending a null value.",
+    "If `authorized-tokens` is set, only those PDM API token IDs can fetch this answer during installation; omit the field to allow any authenticated requester.",
+    "The `target-filter` field uses RFC6901 JSON Pointers as keys and glob patterns as values; it is ignored when `is-default` is true.",
+    "Setting `root-password-hashed` is preferred over `root-password` for security — the plaintext password is stored in the config on disk."
+  ],
+  "relatedOperations": [
+    "get_auto_install",
+    "post_auto_install_prepared",
+    "delete_auto_install_prepared_id",
+    "post_auto_install_installations"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "put_auto_install_tokens_id",
+  "usageNotes": "Use this to update an existing automated-installer access token — toggle it enabled/disabled, set or clear an expiration date, update its comment, or rotate its secret. Requires the `System.Modify` privilege on `/system/auto-installation`. If you set `regenerate-secret: true`, the response body will include the new plaintext secret — this is the only time it is retrievable, so capture it immediately.",
+  "examples": [
+    {
+      "summary": "Rotate the secret on the 'imaging-lab' token and extend its expiration by one year",
+      "path_params": {
+        "id": "imaging-lab"
+      },
+      "params": {
+        "regenerate-secret": true,
+        "expire-at": 1782000000,
+        "comment": "Rotated 2026-06-29 — annual secret renewal"
+      }
+    }
+  ],
+  "tips": [
+    "Pass `digest` (from a prior GET) to guard against concurrent edits overwriting each other.",
+    "Use the `delete` array to clear optional fields (e.g. `[\"comment\", \"expire-at\"]`) rather than sending an empty string.",
+    "Setting `enabled: false` is a safe, reversible way to disable a token without deleting it while investigating suspected misuse.",
+    "A regenerated secret immediately invalidates the old one — any installer nodes still using the old secret will fail authentication until reconfigured."
+  ],
+  "relatedOperations": [
+    "get_auto_install_tokens",
+    "get_auto_install_tokens_id",
+    "post_auto_install_tokens",
+    "delete_auto_install_tokens_id"
+  ]
+}

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

@@ -0,0 +1,39 @@
+{
+  "operationId": "put_config_access_ad_realm",
+  "usageNotes": "Use this to update an existing Active Directory realm configuration in Proxmox Datacenter Manager — for example, to rotate the bind password, switch to LDAPS, add a fallback server, or adjust user-sync defaults. The realm must already exist (use the POST endpoint to create it). Requires the `Realm.Allocate` privilege on `/access/domains`; pass the `digest` field from the current config to guard against concurrent overwrites.",
+  "examples": [
+    {
+      "summary": "Upgrade an AD realm to LDAPS, add a fallback server, and map LDAP mail/givenName/sn attributes to PDM user fields",
+      "path_params": {
+        "realm": "corp-ad"
+      },
+      "params": {
+        "mode": "ldaps",
+        "server1": "dc1.corp.example.com",
+        "server2": "dc2.corp.example.com",
+        "port": 636,
+        "base-dn": "DC=corp,DC=example,DC=com",
+        "bind-dn": "CN=pdm-bind,OU=ServiceAccounts,DC=corp,DC=example,DC=com",
+        "password": "S3cur3B1ndP@ss!",
+        "verify": true,
+        "sync-attributes": "email=mail,firstname=givenName,lastname=sn",
+        "sync-defaults-options": "enable-new=1,remove-vanished=entry;properties",
+        "user-classes": "user,person",
+        "comment": "Production AD realm — LDAPS enforced"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` array to explicitly clear optional fields (e.g. `[\"server2\",\"comment\"]`) rather than sending an empty string, which may not unset them.",
+    "When switching from `ldap` to `ldaps` or `ldap+starttls`, also set `verify: true` and supply `capath` if the DC cert is signed by an internal CA — otherwise the sync will fail TLS verification.",
+    "The `digest` field (SHA-256 of the current config) enables optimistic locking; retrieve it from `get_config_access_ad_realm` before writing to avoid silently stomping a concurrent change.",
+    "The `password` field is write-only — it does not appear in GET responses; always re-supply it on updates if the bind account credentials have not changed, or the stored password will be cleared on some PDM versions.",
+    "User sync does not run automatically after this call; trigger a sync separately via the sync endpoint if you want immediate attribute propagation."
+  ],
+  "relatedOperations": [
+    "get_config_access_ad_realm",
+    "post_config_access_ad",
+    "delete_config_access_ad_realm",
+    "post_config_access_ad_realm_sync"
+  ]
+}

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

@@ -0,0 +1,41 @@
+{
+  "operationId": "put_config_access_ldap_realm",
+  "usageNotes": "Use this to update an existing LDAP realm's connection settings, bind credentials, sync behavior, or TLS mode in Proxmox Datacenter Manager; the realm must already exist (use the corresponding POST to create it). Requires the `Realm.Allocate` privilege on `/access/domains`. Pass the `digest` field (obtained from the GET) to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Switch an existing LDAP realm to LDAPS with certificate verification, update the bind password, and enable new users on sync",
+      "path_params": {
+        "realm": "corp-ad"
+      },
+      "params": {
+        "server1": "dc1.corp.example.com",
+        "server2": "dc2.corp.example.com",
+        "port": 636,
+        "mode": "ldaps",
+        "verify": true,
+        "capath": "/etc/ssl/certs/corp-ca.pem",
+        "base-dn": "dc=corp,dc=example,dc=com",
+        "bind-dn": "cn=svc-pdm,ou=ServiceAccounts,dc=corp,dc=example,dc=com",
+        "password": "S3cur3B1ndP@ss!",
+        "user-attr": "sAMAccountName",
+        "user-classes": "user,person",
+        "sync-attributes": "email=mail,firstname=givenName,lastname=sn",
+        "sync-defaults-options": "enable-new=1,remove-vanished=entry;properties",
+        "comment": "Corporate Active Directory - LDAPS"
+      }
+    }
+  ],
+  "tips": [
+    "The `delete` param accepts a list of property names to unset (revert to default) in the same request — useful for removing a stale `capath` or `filter` without a separate call.",
+    "Default LDAP port is 389; LDAPS is 636 — set `port` explicitly when changing `mode` to avoid connection failures.",
+    "Setting `default: true` makes this realm pre-selected on the PDM login page; only one realm can be the default at a time.",
+    "The `sync-attributes` mapping uses LDAP attribute names as values (e.g. `email=mail`), not the reverse — easy to mix up.",
+    "When switching from plain `ldap` to `ldaps` or `ldap+starttls`, also set `verify: true` and supply a `capath` unless the server cert is signed by a trusted system CA."
+  ],
+  "relatedOperations": [
+    "get_config_access_ldap_realm",
+    "post_config_access_ldap",
+    "delete_config_access_ldap_realm",
+    "post_config_access_ldap_realm_sync"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "put_config_access_openid_realm",
+  "usageNotes": "Use this to modify an existing OpenID Connect realm in PDM — for example to rotate a client secret, change the issuer URL, or toggle autocreate after initial setup. Requires the `Realm.Allocate` privilege on the `/access/domains` ACL path; API tokens are allowed. Supply the `digest` field (obtained from the read endpoint) to guard against concurrent edits overwriting each other.",
+  "examples": [
+    {
+      "summary": "Update an Azure AD OIDC realm: rotate client key and enable autocreate",
+      "path_params": {
+        "realm": "azure-ad"
+      },
+      "params": {
+        "client-id": "a1b2c3d4-0000-0000-0000-ef5678901234",
+        "client-key": "NEW_CLIENT_SECRET_HERE",
+        "issuer-url": "https://login.microsoftonline.com/TENANT_ID/v2.0",
+        "autocreate": true,
+        "scopes": "email profile",
+        "comment": "Azure AD OIDC - updated client secret 2026-06-29",
+        "digest": "a3f1e2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` array to unset optional fields (e.g. `\"delete\": [\"acr-values\"]`) rather than sending an empty string.",
+    "Setting `default: true` on this realm will deselect any other realm currently marked as default on the PDM login page.",
+    "The `client-key` is write-only; it is not returned by the read endpoint, so keep your own record of the current secret before overwriting it.",
+    "Realm names are immutable after creation — to rename a realm you must delete and recreate it, which will break any existing user mappings."
+  ],
+  "relatedOperations": [
+    "get_config_access_openid_realm",
+    "post_config_access_openid",
+    "delete_config_access_openid_realm",
+    "get_config_access_openid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "put_config_access_tfa_webauthn",
+  "usageNotes": "Use this to configure or update the WebAuthn (FIDO2) relying-party settings for Proxmox Datacenter Manager's two-factor authentication. The `id` (relying party ID) and `origin` fields must match the domain users access PDM on — changing `id` invalidates all existing WebAuthn credentials, and changing `origin` or `rp` may also break them. Pass `digest` from a prior GET to guard against concurrent config changes.",
+  "examples": [
+    {
+      "summary": "Set WebAuthn relying party to match PDM's public HTTPS origin",
+      "path_params": {},
+      "params": {
+        "id": "pdm.example.com",
+        "origin": "https://pdm.example.com",
+        "rp": "Proxmox Datacenter Manager",
+        "allow-subdomains": false
+      }
+    }
+  ],
+  "tips": [
+    "Retrieve the current config and its SHA256 digest via the corresponding GET endpoint before writing, then pass `digest` to prevent race conditions.",
+    "Set `allow-subdomains` to false when PDM is accessed only on one exact hostname to prevent credential reuse from unrelated subdomains.",
+    "Use the `delete` array to unset individual properties (e.g., remove a previously set `origin`) rather than sending a full replacement object.",
+    "Changing `id` is non-recoverable for existing hardware keys — users will need to re-register their security tokens."
+  ],
+  "relatedOperations": [
+    "get_config_access_tfa_webauthn"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "put_config_acme_account_name",
+  "usageNotes": "Use this to update the contact email addresses registered with an existing ACME account on Proxmox Datacenter Manager; the account must already exist (create it first with the POST variant). Requires the 'System.Modify' privilege on the system/certificates path. The call is asynchronous — it returns a UPID that must be polled to confirm the update was applied at the ACME CA.",
+  "examples": [
+    {
+      "summary": "Update the contact email for the default ACME account",
+      "path_params": {
+        "name": "default"
+      },
+      "params": {
+        "contact": "admin@example.com,certs@example.com"
+      }
+    }
+  ],
+  "tips": [
+    "The 'contact' field accepts a comma-separated list of email addresses; most ACME CAs use this for expiry and revocation notices.",
+    "Poll the returned UPID via the task log endpoint to confirm the remote ACME CA accepted the contact update — a local 200 response does not mean the CA has acknowledged it.",
+    "Account names must match the pattern /^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$/ — avoid spaces or special characters.",
+    "Omitting the 'contact' body field sends an empty update; include at least one valid email to ensure renewal notifications are delivered."
+  ],
+  "relatedOperations": [
+    "get_config_acme_account_name",
+    "post_config_acme_account",
+    "delete_config_acme_account_name",
+    "get_config_acme_account"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "put_config_acme_plugins_id",
+  "usageNotes": "Use this to update an existing ACME DNS challenge plugin's configuration — for example, to rotate API credentials, change the DNS provider, or adjust the validation delay. The caller must hold System.Modify on /system/certificates. Pass the current config digest to guard against concurrent overwrites; use the 'delete' array to remove optional fields rather than leaving them stale.",
+  "examples": [
+    {
+      "summary": "Rotate Cloudflare API token for an existing DNS plugin and increase validation delay for a slow-propagating zone",
+      "path_params": {
+        "id": "cf-prod"
+      },
+      "params": {
+        "api": "cf",
+        "data": "Q0ZfVE9LRU49bmV3dG9rZW5oZXJlMTIz",
+        "validation-delay": 120,
+        "digest": "a3f1c2e4b5d6a7e8f9012345678901234567890abcdef1234567890abcdef12"
+      }
+    }
+  ],
+  "tips": [
+    "The 'data' field must be base64-encoded with standard padding (not URL-safe); encode key=value pairs per the DNS plugin's expected format before submitting.",
+    "validation-delay defaults to 30 s but DNS providers with TTLs > 60 s (e.g. Cloudflare's 300 s minimum) typically need 120–300 s to avoid validation failures.",
+    "Use the 'delete' array to explicitly remove fields like 'data' or 'api' — omitting them from the body leaves the existing values intact.",
+    "Set 'disable: true' to temporarily suspend a plugin without deleting it, then re-enable by sending 'disable: false' in a follow-up call.",
+    "This endpoint returns null on success; retrieve updated state with get_config_acme_plugins_id to confirm changes."
+  ],
+  "relatedOperations": [
+    "get_config_acme_plugins_id",
+    "post_config_acme_plugins",
+    "delete_config_acme_plugins_id",
+    "get_config_acme_plugins"
+  ]
+}