From 63fc92244e31077701078c7a0b8cd63a1cbb22bb Mon Sep 17 00:00:00 2001
From: "anthony.wen" <awen01@gmail.com>
Date: Thu, 12 Mar 2026 17:02:49 -0400
Subject: [PATCH] Clarify ATVM automation examples are reference-only

- Treat atvm-automation-examples.md as reference material rather than default operator intent.

- Use only explicitly requested options, plus maintained mandatory blacklist handling.

- Record the rule as a run learning in atvm-automation-runs.md.
---
 atvm/AGENTS.md                | 2 ++
 atvm/atvm-automation-guide.md | 3 +++
 atvm/atvm-automation-runs.md  | 9 +++++++++
 3 files changed, 14 insertions(+)

diff --git a/atvm/AGENTS.md b/atvm/AGENTS.md
index 5199f84..ba558e7 100644
--- a/atvm/AGENTS.md
+++ b/atvm/AGENTS.md
@@ -76,6 +76,8 @@ Use `atvm-setup-script-guide.md` as the procedure source and keep behavior align
 ## Cypress Automation Track: Required Behavior
 Use `atvm-automation-guide.md` as the execution source.
 Use `atvm-automation-examples.md` as the common options/command reference.
+Treat `atvm-automation-examples.md` as reference-only.
+Do not treat example options, excludes, plugins, or filters as default operator intent unless the operator explicitly asks for them.
 
 ### Controller Client
 - Hostname: `atvm-cypres-vm-1`
diff --git a/atvm/atvm-automation-guide.md b/atvm/atvm-automation-guide.md
index e15eeed..a3bba3e 100644
--- a/atvm/atvm-automation-guide.md
+++ b/atvm/atvm-automation-guide.md
@@ -3,6 +3,8 @@
 This file is guide-only documentation for operating ATVM CMC automation.
 Do not put specific run examples here.
 For reusable command examples and common option combinations, use `atvm-automation-examples.md`.
+Treat `atvm-automation-examples.md` as reference-only.
+Do not assume the operator wants the extra options shown in examples unless they explicitly request them.
 
 ## Purpose
 Run ATVM CMC automation tests on the designated automation VM without unintended system or file changes.
@@ -67,6 +69,7 @@ python3 ./run-sorry-cypress.py --config_file <config-file> --build_name <hyphena
 ## Examples Reference
 - Commonly used command examples: `atvm-automation-examples.md`
 - Keep this guide focused on run-control rules and workflow constraints.
+- Use examples as reference material only, not as default intent for new operator requests.
 
 ## Example Option Patterns (Guide-Only)
 - Distro-scoped VM selection:
diff --git a/atvm/atvm-automation-runs.md b/atvm/atvm-automation-runs.md
index d12a183..2290568 100644
--- a/atvm/atvm-automation-runs.md
+++ b/atvm/atvm-automation-runs.md
@@ -99,3 +99,12 @@ This file stores run-specific examples only when a run produced a new learning r
 - Action for future runs:
   - Do not reference `cypress.atvm-config.ts` by default in commands or examples.
   - Default to `cypress.atvm-config-gold.ts` unless the operator explicitly requests another config.
+
+## Run Learning: 2026-03-12 (Examples are reference-only, not default intent)
+- Observed requirement:
+  - Reusable examples may contain extra excludes or options that the operator did not ask for.
+  - Carrying those example details into a new run without confirmation can change the requested scope.
+- Action for future runs:
+  - Treat `atvm-automation-examples.md` as reference-only.
+  - Use only the options the operator explicitly requested, plus maintained mandatory blacklist handling.
+  - Do not assume extra example exclusions such as distro filters are desired unless the operator asks for them.