# ATVM AGENTS Guide

This file defines how to operate and maintain the ATVM workspace in `/home/aw/code/cds/atvm`.

## Workspace Layout
- `README.md`
  - human entry point for the folder
- `scripts/`
  - executable workflow assets
- `docs/setup/`
  - setup/bootstrap procedure and run learnings
- `docs/automation/`
  - ATVM Cypress automation procedure, examples, and run learnings
- `docs/workflow/`
  - shared conventions for how the docs are maintained
- `inventory/`
  - environment reference, credentials, IP allocations, and inventory indexes
- `archive/imported-notes/`
  - preserved original long-form source material

## Authoritative Sources
- Setup/bootstrap procedure:
  - `docs/setup/guide.md`
- Setup/bootstrap learnings:
  - `docs/setup/run-learnings.md`
- Automation execution procedure:
  - `docs/automation/guide.md`
- Automation command examples:
  - `docs/automation/examples.md`
- Automation run learnings:
  - `docs/automation/run-learnings.md`
- Workspace conventions:
  - `docs/workflow/conventions.md`

## Setup Track Defaults
- ATVM static IP target: `192.168.3.191/22`
- Gateway: `192.168.0.1`
- DNS: `8.8.8.8`, `8.8.4.4`
- Default Linux setup credential source: `/home/aw/code/cds/.env.credentials.local` via `ATVM_TARGET_USER` and `ATVM_TARGET_PASSWORD`
- Client log file: `atvm_setup_script.log`
- Treat `192.168.3.191` as the default ATVM target host reference.
- 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.

## Automation Track Defaults
- Controller host: `atvm-cypres-vm-1`
- Controller IP: `192.168.3.190`
- Controller credential source: `/home/aw/code/cds/.env.credentials.local` via `ATVM_CONTROLLER_USER` and `ATVM_CONTROLLER_PASSWORD`
- Detailed test artifact root on controller: `/root/cdc-e2e-cyp-12.17.4/cypress/cmcReporter`
- Default Mattermost status destination config: `/home/aw/code/cds/.env.credentials.local`
- Default plugin: `--use_specified_plugin iscsi`
- Always include `--ignore_force_shutdown` unless explicitly told not to.
- Default config family: `gold`
- Do not auto-add the maintained `--exclude_partial_match` blacklist when the operator explicitly targets named VMs with `--specify_vms`.
- Even for explicit `--specify_vms` requests, first check whether any requested VM is on the maintained blacklist and stop if it is.

## Required Operating Rules
- Never run setup without operator-provided `--expected-ip` and `--expected-hostname`.
- Keep static IP configuration as the final setup step.
- Before any automation run, always check whether automation is already running.
- Always show exact planned ATVM commands before execution.
- Never execute setup or automation commands that require approval until the operator explicitly approves them.
- For ATVM run approvals, treat `approve` as run-with-watcher and `approve without watcher` as run-without-watcher.
- Treat git/commit requests as a separate approval gate.
- Follow `/home/aw/code/cds/git-guide.md` for commit-request handling, including the rule that phrases such as `create me a git`, `create a git`, `create a git description`, `make me a git`, `make a git`, `make me a git description`, `create me a git description`, and close variations are prepare-only until the operator explicitly approves the displayed commit command.
- After `cmc-templates.py`, always verify that the generated spec files and the config `specPattern` still include every requested VM before starting `run-sorry-cypress.py`.
- If any requested VM is missing after template generation, stop and report the mismatch instead of launching the runner.
- When the watcher is requested, start the watcher before `run-sorry-cypress.py`.
- Do not start the runner before the watcher, because the watcher helper clears stale `/tmp/<build-name>.log` and can delete the fresh live runner log if the runner starts first.
- For host-level test detail and failed-test investigation, use `/root/cdc-e2e-cyp-12.17.4/cypress/cmcReporter`, especially `logs/`, `xml/`, and `mochawesome/`.
- If the operator asks for ATVM run status without mentioning Mattermost, respond locally only and do not post externally.
- If the operator asks to send ATVM run status to Mattermost, use `MATTERMOST_ATVM_WEBHOOK` and `MATTERMOST_ATVM_CHANNEL` from `/home/aw/code/cds/.env.credentials.local` by default and send the final status only after the run has fully completed, whether the run passed or failed.
- Do not call out expected, harmless `systemctl reset-failed ... unit not loaded` output in routine run updates; mention it only if it blocks startup or matters for debugging.
- Treat `docs/automation/examples.md` as reference-only, not default operator intent.
- Put reusable workflow rules in `guide.md` files.
- Put dated lessons only in `run-learnings.md` files.
- Keep durable environment reference in `inventory/`.
- Preserve imported long-form notes in `archive/imported-notes/`; do not treat them as the primary runbook.

## Maintenance Rules
- When changing workflow behavior, update the corresponding `guide.md`.
- When adding a reusable command pattern, update `docs/automation/examples.md`.
- When a run produces a new lesson, update the appropriate `run-learnings.md`.
- Keep filesystem paths in docs aligned with the actual repo layout.
- Do not remove detailed inventory or credential information from this workspace unless explicitly instructed.