init

reference/README.md

@@ -0,0 +1,20 @@
+# Reference — facts worth keeping
+
+Durable information surfaced in conversation that would otherwise be lost: measured numbers, external
+constraints, how a tool actually behaves, links worth having. One file per subject.
+
+Not decisions (`docs/decisions.md`), not proposals (`ideas/`), not the present state of the code
+(`docs/state.md`). A fact only true today belongs in `state.md`; a rule belongs in the doc owning the
+topic.
+
+Each file states **how the fact was established** — measured, read from a spec, or asserted — so a
+later reader knows whether to trust it or re-check it. An unattributed number is a rumour.
+
+Scratch code illustrating a fact is welcome; `verify.sh` ignores `.go` here entirely, so it need not
+compile.
+
+Out of agent context by default, this index included. Opened only when the human names the topic.
+
+## Index
+
+- [agent-session-costs.md](agent-session-costs.md) — how context and token cost accumulate in an agent session