From a7dde5c9fa3c445b4382f27a5f93328604024be0 Mon Sep 17 00:00:00 2001
From: Nikholas Pcenicni <82239765+nikpcenicni@users.noreply.github.com>
Date: Mon, 19 Jan 2026 02:03:01 -0500
Subject: [PATCH] docs: Add documentation for the `manage_vm.yml` playbook.

---
 ansible/README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/ansible/README.md b/ansible/README.md
index d59d5b8..b5dc59a 100644
--- a/ansible/README.md
+++ b/ansible/README.md
@@ -48,3 +48,37 @@ Example overriding variables:
 ```bash
 ansible-playbook playbooks/create_ubuntu_template.yml -e "template_id=9001 template_name=my-custom-template"
 ```
+
+### Manage VM Playbook (`playbooks/manage_vm.yml`)
+
+This unified playbook allows you to manage VMs (create from template, delete, backup, create template) across your Proxmox hosts.
+
+**Usage:**
+
+The playbook target defaults to the `proxmox` group, but you should usually specify a specific host using `target_host` variable or `-l` limit.
+
+1.  **Create a New Template**:
+    ```bash
+    ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_template vmid=9003 template_name=my-ubuntu-template"
+    ```
+
+2.  **Create a VM from Template**:
+    ```bash
+    ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_vm vmid=9002 new_vmid=105 new_vm_name=my-new-vm"
+    ```
+
+3.  **Delete a VM**:
+    ```bash
+    ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=delete_vm vmid=105"
+    ```
+
+4.  **Backup a VM**:
+    ```bash
+    ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=backup_vm vmid=105"
+    ```
+
+**Variables:**
+-   `proxmox_action`: One of `create_template`, `create_vm`, `delete_vm`, `backup_vm` (Default: `create_vm`)
+-   `target_host`: The host to run on (Default: `proxmox` group). Example: `-e "target_host=mercury"`
+
+*See `roles/proxmox_vm/defaults/main.yml` for all available configuration options.*