27. Grammar Reference (pocket version)

TL;DR (5 lines)

Grammar is a layered model.
A full valid program is the right teaching unit.
Invalid examples should isolate parse structure failures.
Ambiguity must be explained, not hidden.
The chapter should naturally connect to diagnostics and tests.

Concrete Problem

Grammar pages become unusable when they explain snippets without naming the parser layer or ambiguity they belong to.

Coherent example

space demo/grammar

pick Resp {
  case Ok(value: int)
  case Err(code: int)
}

proc run(x: int) -> int {
  match x {
    case 0 { give 0 }
    otherwise { give x }
  }
}

entry main at core/app {
  return run(1)
}

Global explanation

Grammar should be read by layer: top-level declarations, block statements, expressions, patterns, and ambiguity points. The reader should leave able to say what sort of parser expectation has failed.

Short exercise

Take the valid example and identify one top-level rule, one statement rule, and one expression rule it exercises.

Next best action

Keep the example small, reproduce it locally, then continue to the full chapter if you need the broader context.