From efd88ce368cf821861805e7604b4eded651371e6 Mon Sep 17 00:00:00 2001
From: Grant Wickman <grant.a.wickman@gmail.com>
Date: Thu, 14 May 2026 02:09:29 +0100
Subject: [PATCH] docs: add Environment Notes section to AGENTS.md (IMP-001)

Document that PYTEST_ADDOPTS=--no-cov is invalid and causes test
failures. Explains root cause and fix for contributors who inherit
this env var from another project's shell environment.
---
 AGENTS.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index e2f6b58..c6cb43e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,6 +8,25 @@ auto-dev-test-target-2-python project
 uv sync
 ```
 
+## Environment Notes
+
+**PYTEST_ADDOPTS must not be set to `--no-cov`.**
+
+`--no-cov` is not a valid pytest flag. If `PYTEST_ADDOPTS=--no-cov` is set in your shell environment (e.g., inherited from another project), pytest will fail immediately with:
+
+```
+pytest: error: unrecognized arguments: --no-cov
+```
+
+To fix: clear the variable before running tests.
+
+```bash
+unset PYTEST_ADDOPTS
+uv run pytest
+```
+
+This project does not use `pytest-cov` and does not require any coverage-disabling flags. The `pyproject.toml` pytest configuration is correct as-is.
+
 ## Quality Gates
 
 Before committing, run: