docs(cds): consolidate cirrus data cloud reference docs

docs/cirrus-data-cloud/esxvm-guide.md

@@ -0,0 +1,53 @@
+# Cirrus Data Cloud 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