[dmccoystephenson]

Summary

Stage A documentation accuracy sweep. Every section of README.md and the three batch scripts was re-checked against main.py, render_window.py, graphik.py, headless_run.py, usage_reporting.py, trace_client.py, .github/workflows/tests.yml and the pinned Viron submodule. Two inaccuracies were found, both in Running the tests:

• "Most tests also mock Pygame" did not hold. Of the 150 tests, the 60 in tests/test_usage_reporting.py and tests/test_trace_client.py never touch Pygame, and the 10 in tests/test_batch_scripts.py only read the .bat files. Only the main.py, render_window.py and graphik.py tests (64) mock it. The sentence now says which tests mock Pygame, which one runs the real Pygame, and which have nothing to do with it.
• "so that main.py and render_window.py are importable" left out four of the six top-level modules that the tests import: graphik.py, headless_run.py, usage_reporting.py and trace_client.py. All six are now listed.

Everything else checked out against the source, including the CLI argument handling, the environments.json format, the load/create failure behaviour, the batch scripts, the headless harness, the CI workflow, the Python 3.9 requirement (the list[Environment] annotation in Viron's environmentService.py) and the usage-reporting opt-outs. No code was changed.

No tracking issue — gap found during triage.

Test plan

• python3 -m unittest discover -s tests: Ran 150 tests, OK (Python 3.8.10, Viron stubbed)
• Test-file counts and Pygame usage re-checked with grep -c "def test" tests/*.py and grep -l pygame tests/*.py
• Manual render validation: UNVERIFIED-not-applicable, since the change touches only README.md

Deferred issues

• A failed environment creation leaves the window open and shows no error, unlike a failed load #42 and The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41 each need an owner decision (whether a failed creation should be handled like a failed load; whether to bump the Viron pin or keep it), so neither can be settled by an autonomous run.
• Decide whether per-location colours should be stable across frames #24 is still waiting on the owner's stable-vs-animated colour decision.
• Add text-based UI support to library for users #11 and Support drawing environments with multiple grids #2 are feature work too large for a polish-sized PR.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (scored against the diff and command output):

• Scope: PASS — only README.md changes (2 lines), both inside Running the tests.
• Tests-new: PASS (not applicable) — no code was added.
• Tests-fix: PASS (not applicable) — documentation only, so there is no fix to stash and re-run.
• Sibling structure: PASS — no new files.
• Sibling renames: PASS — nothing renamed.
• Docs: PASS — the new claims were checked against the source. grep -l pygame tests/*.py matches only test_graphik.py, test_main.py, test_render_window.py and test_headless_run.py. test_usage_reporting.py and test_trace_client.py have no match. The six listed modules are exactly the top-level modules imported by tests/*.py.
• Issue resolution: PASS (not applicable) — no Closes #N; this is a sweep finding.
• Manual validation: PASS — the Tests workflow is green on the PR head (run 40827004194). Locally, python3 -m unittest discover -s tests printed Ran 150 tests and OK. Render validation is UNVERIFIED-not-applicable (no rendering or service-call file changed).

README.md:195 — judgment note: the word "also" in "tests/test_headless_run.py also runs the headless harness … end to end" is meant to say that, besides its mocked FrameCounter unit tests, the file has a TestRun class that drives the real Pygame. Someone could read it as tying back to the mocked tests in the clause before. That is accurate either way, so it is not blocking.

Do-not-auto-merge paths: none touched (no .github/workflows/*, .gitmodules or security/, and no file with more than 50 lines deleted).

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson