docs(atvm): add atvm_prep reference and workspace guardrail

AGENTS.md

@@ -10,3 +10,7 @@ Always let the user review the proposed commit scope and commit message first, a
 
 - Never commit or push to the nested `galaxy-complete` repo under `/home/aw/code/cds/galaxy-complete` without the user's explicit approval.
 - Never assume work in `/home/aw/code/cds` should be pushed to `rnd.cdsi.us.com`.
+
+## ATVM Prep Script Guardrail
+
+- Do not run `/root/atvm_prep/atvm_prep.py` unless the operator explicitly asks for an `atvm_prep` task.

atvm/docs/automation/atvm-prep-reference.md

@@ -0,0 +1,98 @@
+# ATVM Prep Script Reference
+
+This document summarizes the behavior of the controller-local prep script:
+- Host: `atvm-cypress-vm-1` (`192.168.3.190`)
+- Path: `/root/atvm_prep/atvm_prep.py`
+
+Use this as a quick runbook when ATVM datastore/lun prep is requested.
+
+## Purpose
+`atvm_prep.py` orchestrates DGS and VMware actions around a target DGS LUN name for ATVM test environments. It handles clone lifecycle cleanup, snapshot clone assignment, datastore mount/unmount operations, and optional VM register/unregister workflows.
+
+## Primary Modes
+The script supports these operation modes:
+
+1. `-A` / `--automated_testing`
+- Prepare environment for automated testing.
+- Cleans up prior assigned clone/lun state, creates a new clone from snapshot, assigns it, and force-mounts unresolved VMFS.
+
+2. `-M` / `--maintenance`
+- Prepare for maintenance against the specified DGS LUN.
+- Cleans clone state, reassigns original/gold volume, rescans storage, and mounts the datastore.
+
+3. `-R` / `--register`
+- Register VMs only for the LUN currently assigned to the target client.
+- Scans VMX files on datastore and registers missing VMs.
+
+4. `-U` / `--unregister`
+- Power off and unregister VMs only for the LUN currently assigned to the target client.
+
+5. `-rvgd` / `--rollback_vm_gold_disk`
+- Roll back target volume to a selected snapshot, then assign/mount for use.
+
+## Main Inputs
+Notable arguments:
+- `-n` / `--dgs_lun_name` (required): target DGS LUN base name
+- `-s` / `--snapshot_name`: optional snapshot name; latest used when omitted
+- `-c` / `--client_name`: defaults to `CDS1-ESX165`
+- `-vi` / `--vcenter_ip`: defaults to `192.168.0.201`
+- `-vu` / `--vcenter_username`
+- `-vp` / `--vcenter_password`
+- `-e` / `--esx_host_ip`: defaults to `192.168.1.165`
+
+## Operational Flow
+High-level behavior across modes:
+
+1. Resolve DGS client and volume/policy IDs.
+2. Resolve currently assigned volume for the target client where relevant.
+3. If cleanup is required:
+- Find datastore from LUN GUID.
+- Power off VMs on that datastore.
+- Unregister VMs.
+- Unmount datastore on ESXi.
+- Unassign and optionally delete clone on DGS.
+4. Execute mode-specific action:
+- create clone and assign (`-A`)
+- assign gold and mount (`-M`)
+- register only (`-R`)
+- power off/unregister only (`-U`)
+- rollback and reassign (`-rvgd`)
+
+## VMware Helpers In Script
+Reusable functions implemented in `atvm_prep.py` include:
+- datastore discovery from DGS LUN GUID
+- force-mount unresolved VMFS volume
+- datastore mount/unmount
+- VM power-off by datastore membership
+- VM unregister by datastore membership
+- VMX discovery on datastore for registration
+
+## Safety Traits
+The script intentionally exits on ambiguous or unsafe states, including:
+- snapshot not found or duplicate snapshot names
+- missing client/volume/datastore
+- multiple datastores matching same GUID
+
+For some operations (`register`, `unregister`, `rollback`) it prompts for explicit confirmation (`[y/n]`) before acting.
+
+## Known Caveats
+1. Default credentials are hardcoded in script arguments.
+- Treat these as legacy behavior and prefer supplying credentials explicitly in runtime usage.
+
+2. `main()` contains this condition:
+- `if not is_register or not is_unregister:`
+- This is effectively true for almost all normal runs and likely intended as `and`.
+- Do not change behavior blindly during operations; patch only with explicit operator approval.
+
+3. Registration steps in `-A`, `-M`, and `-rvgd` paths are currently commented out.
+- Datastore prep/mount occurs, but VM registration is not automatically performed in those paths unless script is modified.
+
+## Logging
+- Script log directory: `/root/atvm_prep/log`
+- Main log file: `/root/atvm_prep/log/atvm_prep.log`
+- Rotating log handler is enabled in script.
+
+## Practical Usage Notes
+- Prefer dry validation of target LUN/client/snapshot before destructive modes.
+- Use `-U` for scoped VM power-off/unregister tied to LUN GUID mapping.
+- Use `-R` after datastore mount when VM registration is required and safe.