[StoneyJackson]

Add a guide for textbook authors drawing environment diagrams in PlantUML, with worked examples for V3, V4, V5, SET, REF, NAME, and NEED. Point to it from the general style guide.

[Copilot]

🟡 Changes recommended

The style-guide rule needs a ThunkRef exception to distinguish NAME’s per-access evaluation from NEED’s memoization and avoid incorrectly depicting separate results as one shared value.

1 open issue

• Clarify that NAME reevaluates ThunkRef variables on every access · New

What changed in this PR

Adds guidance for textbook authors to create consistent PlantUML environment diagrams, with worked examples covering scope, references, and parameter passing.

Changes:

• Defines conventions for diagram structure, naming, arrows, evaluation markers, and layout adjustments.
• Adds examples for V3, V4, V5, SET, REF, NAME, and NEED.
• Points authors to the new documentation from the general style guide.

File	Description
style-guide.md	Adds a pointer to the environment diagram guide.
docs/​environment-diagrams/​style-guide.md	Defines diagram conventions and PlantUML guidance.
docs/​environment-diagrams/​diagrams-v5.md	Illustrates recursive bindings and closure calls.
docs/​environment-diagrams/​diagrams-v4.md	Illustrates lexical scope and captured environments.
docs/​environment-diagrams/​diagrams-v3.md	Shows nested bindings and variable shadowing.
docs/​environment-diagrams/​diagrams-set.md	Shows mutation, parameter references, and persistent captured state.
docs/​environment-diagrams/​diagrams-ref.md	Contrasts variable and expression arguments under call-by-reference.
docs/​environment-diagrams/​diagrams-need.md	Shows thunk memoization and read-only argument references.
docs/​environment-diagrams/​diagrams-name.md	Shows argument references and deferred evaluation under call-by-name.

_{Review effort: Balanced}