[dmccoystephenson]

Summary

• python main.py --help and -h, in any position, now print Usage: python main.py [gridSize] [--exit-after-create] and exit with status 0.
• Previously the flag was read as an unparseable grid size, so the program fell back to 50, created an environment through Viron, wrote environments.json and settings.json, reported usage and entered the render loop.
• The check sits in the __main__ block ahead of parseArgs, so parseArgs and main() are unchanged, and the documented fallback for other unparseable values still applies.
• The README's Running section describes the flag.

Closes #57

Test plan

• python3 -m unittest discover -s tests: 170 tests ran, OK (165 before, plus 5 new)
• python3 -m py_compile on every module listed in the CI workflow passes
• python3 headless_run.py: all three scenarios PASS with the real Pygame on SDL's dummy drivers
• Regression check: with the __main__ guard removed, the new entrypoint test failed in all three subtests, because the run reached main(). Restoring the guard returned the suite to green
• Before the change, a probe of the __main__ block on SDL's dummy drivers with in-memory services showed the side effects quoted in python main.py --help creates an environment instead of printing usage #57
• The interactive anchor (python3 main.py 10 --exit-after-create against a live Viron) is UNVERIFIED-not-applicable: neither main(), the render loop nor any Viron-service call is changed

--help cannot be answered without the Viron submodule or on an interpreter below Python 3.9, because main.py imports Viron at module scope, ahead of the check. Moving those imports was left out as a larger change than #57 calls for.

Deferred issues

• A failed environment creation leaves the window open and shows no error, unlike a failed load #42: its acceptance criteria require an owner decision on whether a failed creation should mirror a failed load.
• The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41: re-pointing the Viron submodule requires explicit authorization.
• Decide whether per-location colours should be stable across frames #24: an open design decision.
• Add text-based UI support to library for users #11 and Support drawing environments with multiple grids #2: too large for one polish-sized cycle.

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 (anchored on CI run 42003869406, which passed at head 8a3ad18, and on a local run of 170 tests, all OK):

• Scope: PASS. Only README.md (+6), main.py (+18) and tests/test_main.py (+41) change, all for python main.py --help creates an environment instead of printing usage #57. Nothing is deleted.
• Tests-new: PASS. wantsUsage has four direct tests, and the __main__ branch has an entrypoint test across three argument vectors.
• Tests-fix: PASS, with one qualification. The guard was removed from main.py with Edit and the entrypoint test failed in all three subtests. Those failures were ERROR results rather than assertion failures: the run fell through into main() and stopped at its first drawText, because Pygame's font module is uninitialised under the mocked window. That still shows the fall-through. The suite was green again after the guard was restored. The git stash form was not used, since the mutation was made before the commit.
• Sibling structure: PASS. wantsUsage follows the docstring form of parseArgs and getEnvironmentKey, and the tests follow the TestParseArgs and TestCliEntrypoint conventions.
• Sibling renames: N/A. Nothing is renamed.
• Docs: PASS. README.md:173 matches the guard. The .bat scripts always pass a numeric size and --exit-after-create, so they never reach the new branch.
• Issue resolution: PASS. Each python main.py --help creates an environment instead of printing usage #57 acceptance criterion is met: usage output and status 0 for both spellings, no window, file or report, the fallback left unchanged, and the README and a test added.
• Manual validation: PASS for py_compile, the unit suite and headless_run.py (all three scenarios). UNVERIFIED-not-applicable for the interactive Viron run, since main(), the render loop and the service calls are unchanged.

Notes:

• main.py:187: --help is only reached after the module-level Viron imports, so it needs the populated submodule and Python 3.9+. The entrypoint test runs against stubs and does not exercise that. This is stated in the PR body and was not changed, since lazy imports would go beyond python main.py --help creates an environment instead of printing usage #57.
• main.py:33: -h and --help are honoured in any position, so python main.py 100 -h creates nothing. A help request winning over a run was judged the safer reading.
• tests/test_main.py:446: no assertion is made on the Viron service classes. Under test discovery tests/test_headless_run.py can import main first, so a class looked up as main.EnvironmentService may not be the one bound by the runpy copy, and such an assertion could pass vacuously. RenderWindow not being called is the signal relied on instead, because main() always creates the window before its first Viron call. Service construction itself is not asserted, though no path reaches it past the guard.
• README.md:256 still says startup is sent once per launch. A --help invocation sends nothing, and README.md:173 says so, so this line was left as it is.

The diff is review-ready. No do-not-auto-merge path is touched, and no file has any lines deleted.

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

---

drafted by Claude on behalf of Daniel Stephenson