Add portable ATVM skill and hardware prep docs

atvm/docs/automation/guide.md

@@ -138,6 +138,10 @@ Completed-run verification sequence:
 - When the operator provides an explicit VM list, check vCenter placement for every requested VM before choosing the config file.
 - Before presenting any ATVM run commands for an explicit VM-list request, tell the operator that the next step is a live vCenter placement check for the requested VMs and that the result will determine whether the run must use `gold` or `gold-2`.
 - For vCenter inspection and placement checks, prefer `govc` and raw vCenter REST calls when they are available before reaching for alternate wrappers.
+- Never delete, destroy, remove from inventory, or unregister any ATVM VM from vCenter.
+- Treat a vCenter VM as protected ATVM inventory if its name starts with `atvm`, if it resides on an `AutomatedTest-*` ATVM datastore, or if it is an ATVM platform/controller VM, even when it is not listed in `inventory/vm-inventory.md`.
+- Preserve ATVM vCenter VM inventory records even when power, maintenance, datastore, cleanup, or prep work is requested.
+- For cleanup workflows, only power off, detach/unmount supporting resources, or report the needed manual action; do not remove ATVM VM inventory records.
 - For `govc`-based placement checks, use `govc vm.info -json <vm>` and parse the lowercase JSON keys such as `virtualMachines` and `datastore`.
 - Resolve each returned datastore managed-object reference to a datastore name with `govc object.collect -s <datastore-ref> name` before deciding between `gold` and `gold-2`.
 - Ignore non-boot helper datastores such as install ISO attachments when applying the `gold` vs `gold-2` rule; base the family decision on the ATVM boot datastore membership.

atvm/docs/setup/guide.md

@@ -45,6 +45,57 @@ Rules:
 - If detected hostname does not exactly match expected hostname, stop immediately.
 - If expected IP is not assigned on target, stop immediately.
 
+## Finish ATVM VM Hardware Prep
+When the operator says `finish prepping the ATVM VM hardware for <vm-name>`, perform only the standard vCenter hardware prep for that exact VM name.
+
+Safety rules:
+- Operate only on the exact VM name supplied by the operator.
+- Verify the VM exists and is powered off before changing hardware.
+- Do not delete, destroy, remove from inventory, or unregister the ATVM VM.
+- Do not create replacement disks when the standard shared ATVM data disks are missing; stop and report the missing datastore paths.
+- If the VM already has conflicting data disks, FC passthrough devices, or occupied unit numbers, stop and report instead of adding duplicates.
+
+Standard hardware:
+- Attach the two existing data disks from the VM's current ATVM boot datastore under `atvm-DISKS/`:
+  - `atvm-DISK_1.vmdk` as the first added data disk, normally Hard disk 2 / SCSI unit 1.
+  - `atvm-DISK_2.vmdk` as the second added data disk, normally Hard disk 3 / SCSI unit 2.
+- Add the two FC passthrough ports:
+  - `0000:85:00.0`
+  - `0000:85:00.1`
+- Reserve all guest memory after adding passthrough devices.
+
+Preferred `govc` flow:
+```bash
+source /home/aw/code/cds/.env.credentials.local
+export GOVC_URL="https://${VCENTER_HOST}/sdk"
+export GOVC_USERNAME="$VCENTER_USER"
+export GOVC_PASSWORD="$VCENTER_PASSWORD"
+export GOVC_INSECURE=1
+
+vm="/CDSHQ-Eng/vm/<vm-name>"
+ds="<current-atvm-boot-datastore>"
+
+govc vm.info "$vm"
+govc device.info -vm "$vm"
+govc datastore.ls -ds "$ds" atvm-DISKS
+
+govc vm.disk.attach -vm "$vm" -ds "$ds" -disk atvm-DISKS/atvm-DISK_1.vmdk -link=false
+govc vm.disk.attach -vm "$vm" -ds "$ds" -disk atvm-DISKS/atvm-DISK_2.vmdk -link=false
+
+govc device.pci.ls -vm "$vm"
+govc device.pci.add -vm "$vm" 0000:85:00.0
+govc device.pci.add -vm "$vm" 0000:85:00.1
+
+memory_mb="$(govc object.collect -s "$vm" config.hardware.memoryMB)"
+govc vm.change -vm "$vm" -memory-pin=true -mem.reservation "$memory_mb"
+```
+
+Operational notes:
+- Determine `<current-atvm-boot-datastore>` from live vCenter inventory for the VM.
+- Use `-link=false` for the standard ATVM data disks so the existing datastore disks are attached directly, matching the reference ATVM inventory pattern.
+- Add FC passthrough ports one at a time. Adding both addresses in one `govc device.pci.add` call can fail with duplicate device-key errors.
+- Verify memory reservation by confirming `config.memoryAllocation.reservation` equals `config.hardware.memoryMB`.
+
 ## Canonical Run Order
 1. `parse_args`
 2. `validate_target_host_identity`