merge main into work/line-tables

1 files changed, 2 insertions, 0 deletions

diff --git a/ONBOARD.md b/ONBOARD.md
index 47e1cba..35d5e35 100644
--- a/ONBOARD.md
+++ b/ONBOARD.md
@@ -130,6 +130,8 @@ read in this order:
 to see the compiler as one text, as the bootstrap does, run
 `cat $(sed 's|^|src/compiler/|' src/compiler/parts)`.
 
+the state is mostly global arrays and scalars that distant functions read and write: run `make xref` before changing compiler state, and read `build/xref/report.txt` for who writes the global and who only reads it (`make xref XREF_ARGS=--check` compares with `tests/xref.baseline`).
+
 you should be able to say where a new keyword is registered, how a keyword
 works at the top level and inside a function, and how the compiler emits a
 byte-string literal into the code stream.