cdsmcp: add direct ESX VM hardware workflow guide

Add a dedicated ESX VM guide for read-first hardware change workflows,
including disk creation, datastore VMDK attachment, and PCI passthrough
assignment.

Update the existing lookup/assignment runbook and top-level docs to
reference the new guide and require explicit reporting of VM name
mismatches and missing datastore directories before any change.

cdsmcp/AGENTS.md

@@ -7,6 +7,8 @@ This folder contains the VMware/vCenter + MigrateOps runbook for CDS MCP workflo
   - top-level navigation
 - `docs/vmware-migrateops-guide.md`
   - authoritative VMware compute migration workflow
+- `docs/esxvm-guide.md`
+  - direct vCenter VM hardware review/change workflow
 - `docs/vm-lookup-and-assignment.md`
   - VM lookup, datastore reporting, and FC/disk assignment workflow
 - `docs/cmc-install-reference.md`
@@ -20,6 +22,7 @@ This folder contains the VMware/vCenter + MigrateOps runbook for CDS MCP workflo
 
 ## Source Of Truth
 - Use `docs/vmware-migrateops-guide.md` for how to execute VMware compute migration runs.
+- Use `docs/esxvm-guide.md` for direct vCenter VM hardware changes such as new disks, existing-disk attach, and PCI passthrough assignment.
 - Use `docs/vm-lookup-and-assignment.md` for VM lookup responses and FC/disk assignment requests.
 - Use `docs/cmc-install-reference.md` for CMC install/uninstall commands and fallback reinstall notes.
 - Use `templates/vmw.yaml` as the starting operation template.
@@ -49,6 +52,7 @@ This folder contains the VMware/vCenter + MigrateOps runbook for CDS MCP workflo
 
 ## Update Rules
 - Update `docs/vmware-migrateops-guide.md` only when migration workflow/default behavior changes.
+- Update `docs/esxvm-guide.md` only when direct vCenter hardware workflow/default behavior changes.
 - Update `docs/vm-lookup-and-assignment.md` only when lookup/assignment workflow behavior changes.
 - Update `docs/cmc-install-reference.md` only when install or reinstall reference behavior changes.
 - Update `docs/run-learnings.md` only when a run reveals a new learning/failure pattern/required check.

cdsmcp/README.md

@@ -5,6 +5,8 @@ This folder contains the VMware/vCenter and MigrateOps runbook material used for
 ## Start Here
 - VMware compute migration workflow:
   - `docs/vmware-migrateops-guide.md`
+- Direct vCenter VM hardware review/change workflow:
+  - `docs/esxvm-guide.md`
 - VM lookup and FC/disk assignment workflow:
   - `docs/vm-lookup-and-assignment.md`
 - CMC install and uninstall reference:

cdsmcp/docs/esxvm-guide.md

@@ -0,0 +1,53 @@
+# ESX VM Guide
+
+This file covers read-only review and approval rules for direct vCenter VM hardware changes.
+
+## Scope
+- Use this guide for direct vCenter VM hardware work such as:
+- creating a new VM disk
+- attaching existing datastore VMDKs
+- assigning PCI passthrough devices
+
+## vCenter Access
+- Always log into vCenter `192.168.0.201`.
+- Source `/home/aw/code/cds/.env.credentials.local` and use `VCENTER_USER` plus `VCENTER_PASSWORD`.
+- Standard CLI path: `/home/aw/.local/bin/govc`
+- Default datacenter: `CDSHQ-Eng`
+
+## Review-First Rule
+- Treat direct VM hardware changes as a two-step workflow:
+- first gather and report findings
+- then wait for explicit operator approval before making any change
+- Never create, attach, remove, or reassign hardware until the operator explicitly approves after seeing the summary.
+
+## VM Identification Rule
+- When the requested VM name is not present exactly as given, search for the closest live inventory name and report the mismatch before planning any change.
+- Do not act on a guessed VM silently.
+
+## Host And Datastore Checks
+- Find the specified VM and verify the ESXi host it is currently running on.
+- Default expected ESXi host is `192.168.1.165`, but always verify live placement before planning changes.
+- Always identify and report the datastore where the VM is stored before planning disk work.
+
+## New Disk Creation Rule
+- When asked to create a new disk for a VM:
+- inspect the VM's current controller layout first
+- prefer the existing SCSI controller already backing the VM disks unless the operator explicitly asks for a different controller
+- report the controller label, controller type, and the next free unit number before proposing the change
+- report the target datastore and requested size before proposing the change
+- if the VM has snapshots, include that fact in the review summary before the operator approves
+
+## Existing Disk And FC Assignment Rule
+- For existing-disk and FC-passthrough requests, use the workflow in `vm-lookup-and-assignment.md`.
+- If the specified devices or disk files cannot be found exactly as requested, do nothing.
+
+## Summary Requirement
+- Before any direct VM hardware change, always report:
+- VM name found
+- guest hostname when available
+- ESXi host
+- datastore
+- current controller layout relevant to the request
+- snapshot state when relevant
+- exactly what would be changed
+- any blockers that mean nothing will be changed

cdsmcp/docs/vm-lookup-and-assignment.md

@@ -26,6 +26,7 @@ This file covers vCenter VM lookup responses and the workflow for assigning exis
 - then wait for explicit approval before making any changes
 - Always log into vCenter `192.168.0.201`.
 - Find the specified VM and verify the ESXi host it is currently running on.
+- If the requested VM name is not present exactly as given, search for the closest live inventory name and report the mismatch before planning any change.
 - Default expected ESXi host is `192.168.1.165`, but always verify live placement before planning changes.
 - Always identify and report the datastore where the VM is stored before planning disk attachment.
 - Unless the operator explicitly specifies alternatives, default to these PCI passthrough FC adapters:
@@ -37,8 +38,10 @@ This file covers vCenter VM lookup responses and the workflow for assigning exis
 - `atvm-DISK_2.vmdk`
 - Do not substitute any other disks if either default or operator-specified disk cannot be found.
 - If the specified adapters or specified disks cannot be found, do nothing and report that nothing will be assigned.
+- For these requests, never substitute a different datastore directory when `atvm-DISKS` is missing.
 - Before any assignment action, always provide a summary of:
 - the VM found
+- any name mismatch between requested VM name and live inventory VM name
 - the ESXi host
 - the datastore
 - whether `vmhba7` and `vmhba8` were found and are usable