[dmccoystephenson]

Summary

A documentation accuracy sweep (Stage A) of README.md and the batch scripts was carried out against the current source. Each corrected claim below was checked against the code:

• main()'s reportUsage argument. The README said usage reporting is "started only by the CLI entrypoint". In fact main() takes reportUsage (default False), and the __main__ block passes True. The parameter is now documented, and the sentence states the condition under which settings.json is left alone.
• Opt-out environment variables. trace_client.environment_opts_out also accepts DO_NOT_TRACK=true/yes, ignores case and surrounding whitespace, and treats any other value as no opt-out. The README listed only DO_NOT_TRACK=1 and did not mention case.
• Unreadable settings.json. usage_reporting.loadSettings prints a message, does not rewrite the file, and returns None, so nothing is reported for that run. The README did not describe this case.
• Graphik. main.py renders with Graphik, but the README mentioned it by name only. A short section now documents drawRectangle, drawText (bundled freesansbold.ttf font, centred) and drawButton (fires once per press, keyed by its rectangle, and not when a press is dragged onto it). These behaviours are the ones locked in by tests/test_graphik.py.

The rest of the README (CLI arguments, cache behaviour, load/create error paths, create_environments.bat / up.bat / down.bat, the test and headless-harness sections, the CI workflow description) was re-verified and no drift was found.

Only documentation is changed. No code is modified.

Skipped issues

• The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41 (Viron pin predates bearer tokens): needs a project decision between bumping the submodule and keeping the pin. The Viron submodule is also never re-pointed without authorization.
• A failed environment creation leaves the window open and shows no error, unlike a failed load #42 (failed creation leaves the window open): its acceptance criteria start with a recorded owner decision on whether the asymmetry is intended.
• Decide whether per-location colours should be stable across frames #24 (stable per-location colours): needs an owner decision.
• Add text-based UI support to library for users #11 (text-based UI support) and Support drawing environments with multiple grids #2 (multiple grids): both are feature work too large for a sweep-sized PR.

Test plan

• python3 -m py_compile main.py graphik.py __init__.py passes
• python3 -m unittest discover -s tests ran 141 tests, all OK
• The new Graphik example was run against real Pygame 2.1.2 with SDL's dummy drivers. drawRectangle(..., "red") produced a (255, 0, 0) pixel, and drawText/drawButton with colour names ran without error.
• Live Viron anchor (python3 main.py 10 --exit-after-create against a Viron on :9999): UNVERIFIED-not-applicable. This PR is docs-only, and no Viron can run in this environment.

No tracking issue: the gaps were found during triage.

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 the Tests CI run and local commands; scored adversarially):

• Scope: PASS. git diff --name-only origin/main...HEAD lists only README.md. Each hunk corrects or adds a claim that was checked against main.py, graphik.py, usage_reporting.py or trace_client.py.
• Tests-new: PASS (not applicable). No public method or function is added.
• Tests-fix: PASS (not applicable). No bug fix is included, so there is nothing to stash-and-revert.
• Sibling structure: PASS. The new ## Graphik section mirrors ## RenderWindow: an intro paragraph, a Python example, then a description of each method. It sits directly after ## RenderWindow.
• Sibling renames: PASS (not applicable). Nothing is renamed.
• Docs: PASS. README.md was swept in full. create_environments.bat, up.bat and down.bat were re-read against main.py's parseArgs and still match.
• Issue resolution: PASS (not applicable). There is no Closes #N. The skip reasons for Support drawing environments with multiple grids #2, Add text-based UI support to library for users #11, Decide whether per-location colours should be stable across frames #24, The Viron submodule is pinned before Viron required bearer tokens, so Patchwork cannot reach a current Viron #41 and A failed environment creation leaves the window open and shows no error, unlike a failed load #42 are recorded in the PR body.
• Manual validation: PASS for what can run. CI Tests passed on the PR head (py_compile plus 141 unittest tests), and the same 141 tests passed locally. The Graphik example was run against real Pygame 2.1.2 with SDL's dummy drivers from the repository root, where no freesansbold.ttf file exists, which confirms that the bundled font is resolved. The live Viron anchor is UNVERIFIED-not-applicable because the PR is docs-only.

Findings flagged for judgment (none block the merge):

• README.md:96 — the Graphik snippet uses window and on_click without defining them. This matches the partial-snippet style of the RenderWindow examples, so it was left as is.
• README.md:105 — two buttons drawn with an identical position and size share one press state, because the state is keyed only by the rectangle. The sentence "keyed by its position and size" implies this without spelling it out. This is a niche case and was left unexpanded.
• Outside the diff, the ## Features list still does not name Graphik. It was not changed, to keep this PR to accuracy fixes rather than marketing copy.

Every rubric item passes and the anchor is green for a docs-only change.

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

---

drafted by Claude on behalf of Daniel Stephenson