Add portable ATVM skill and hardware prep docs

atvm/AGENTS.md

@@ -42,6 +42,8 @@ This file defines how to operate and maintain the ATVM workspace in `/home/aw/co
 - For SSH to `192.168.3.191`, ignore host key mismatch by default with `-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null`.
 - For Linux SSH to `192.168.3.191`, source `/home/aw/code/cds/.env.credentials.local` and use `ATVM_TARGET_USER` plus `ATVM_TARGET_PASSWORD` unless explicitly overridden.
 - Use `ATVM_WINDOWS_TARGET_USER` plus `ATVM_WINDOWS_TARGET_PASSWORD` for Windows guest access to the same ATVM target IP unless explicitly overridden.
+- For `finish prepping the ATVM VM hardware for <vm-name>`, follow `docs/setup/guide.md` section `Finish ATVM VM Hardware Prep`.
+- Standard ATVM VM hardware prep means the two shared `atvm-DISKS` data disks, FC passthrough ports `0000:85:00.0` and `0000:85:00.1`, and full guest-memory reservation.
 
 ## Automation Track Defaults
 - Controller host: `atvm-cypres-vm-1`

atvm/README.md

@@ -11,6 +11,8 @@ This folder contains the ATVM setup workflow, ATVM Cypress automation workflow,
   - `docs/workflow/conventions.md`
 - Environment inventory and credentials:
   - `inventory/overview.md`
+- Portable Codex skill:
+  - `../skills/atvm/`
 
 ## Layout
 - `scripts/`
@@ -25,6 +27,7 @@ This folder contains the ATVM setup workflow, ATVM Cypress automation workflow,
   - environment inventory, credentials, reserved IPs, and reference maps
 - `archive/imported-notes/`
   - preserved original long-form notes that were reorganized into the current structure
+  - includes `README.md` identifying the canonical imported note
 
 ## Practical Guidance
 - Use `guide.md` files for authoritative workflow behavior.
@@ -33,3 +36,4 @@ This folder contains the ATVM setup workflow, ATVM Cypress automation workflow,
 - For detailed ATVM automation test results, especially per-host failures, use `/root/cdc-e2e-cyp-12.17.4/cypress/cmcReporter` on the automation controller.
 - Use `inventory/` for persistent environment information such as hosts, credentials, and IP assignments.
 - Use `archive/imported-notes/` when you need the original full historical notes in their original layout.
+- Keep `../skills/atvm/` aligned when ATVM workflow rules need to be portable outside this workspace.

atvm/archive/imported-notes/README.md

@@ -0,0 +1,13 @@
+# Imported Notes
+
+This directory preserves long-form ATVM source notes in their imported form.
+
+## Files
+
+- `cypress-automation-for-cmc.md`
+  - canonical imported note used by tracked ATVM inventory references
+  - updated from the 2026-07-13 import
+
+## Usage
+
+Use the organized files under `../../inventory/` and `../../docs/` first. Use these imported notes only when the original narrative or detailed historical listing is needed.

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`

atvm/inventory/overview.md

@@ -15,7 +15,7 @@ This directory contains the durable environment reference for the ATVM workspace
   - broad VM reference snapshot; do not use it for current `AutomatedTest-VMBootImg-Gold` / `AutomatedTest-VMBootImg-Gold-2` membership during ATVM run planning
 
 ## Preserved Source
-- Full original notes are preserved at:
+- Full original notes used by tracked inventory references are preserved at:
   - `archive/imported-notes/cypress-automation-for-cmc.md`
 
 Use the inventory files first for organized access, then use the archived source when you need the original full narrative and detailed listings in their original order.