Severity: low (learnability)
Whether a statement prints is not learnable from the surface:
- Auto-show:
count, combine, standalone keep (and other value-producing expressions)
- Silent:
filter, sort, transform, weakens, assign
- Conditional:
expect (prints only on divergence), require (prints only on failure)
Each is individually defensible (value-producing vs in-place mutation vs metadata attachment), but as a set it's a memorization task. I repeatedly had to test "will this line print?" while building the vocabulary tour.
Recommendation
Add a one-line rule + a small table to docs/language/syntax.md, e.g.:
Expressions that produce a new value auto-show; verbs that mutate a value in place or attach metadata are silent; require/expect are silent on success and speak only on failure/divergence.
Severity: low (learnability)
Whether a statement prints is not learnable from the surface:
count,combine, standalonekeep(and other value-producing expressions)filter,sort,transform,weakens,assignexpect(prints only on divergence),require(prints only on failure)Each is individually defensible (value-producing vs in-place mutation vs metadata attachment), but as a set it's a memorization task. I repeatedly had to test "will this line print?" while building the vocabulary tour.
Recommendation
Add a one-line rule + a small table to
docs/language/syntax.md, e.g.: