fix(docs): cite files, not line numbers, in the generated env reference (#6538)

website/configuration-reference.md pinned every ODYSSEUS_* read to a
`path:line`, and test_env_reference fails when the committed page differs from
the generator output. So any change that adds or removes a line above an env
read in any scanned file has to regenerate the page, even when no variable
changed. Since the page landed on 2026-09-30, 24 of the 34 commits touching it
changed nothing but line numbers, and all three open PRs that touch it today do
the same - which also makes them conflict with each other on that file.

The Read in column now names the file, and "+N more" counts other files rather
than other read sites. The page still goes stale, and the test still fails,
when a variable is added, removed, moves to another file, or changes default.
check_notes still reports path:line on stderr, where it is useful and never
committed.

tests/test_env_reference.py

@@ -167,10 +167,56 @@ def test_renders_one_table_row_per_variable(generator, fake_tree, monkeypatch):
     page = generator.render(found, generator.naive_line_scan(fake_tree))
 
     assert page.startswith("---\nlayout: default\n---\n")
-    assert "| `ODYSSEUS_VIA_HELPER` | `5 * 1024` | `src/indirect.py:16` | A synthetic limit. |" in page
+    assert "| `ODYSSEUS_VIA_HELPER` | `5 * 1024` | `src/indirect.py` | A synthetic limit. |" in page
     assert "### Search" in page
 
 
+def _render_one(generator, root, name, monkeypatch):
+    monkeypatch.setitem(
+        generator.VARIABLE_NOTES, name, ("Search", generator.USER, "A synthetic flag.")
+    )
+    return generator.render(
+        {name: generator.collect(root)[name]}, generator.naive_line_scan(root)
+    )
+
+
+def test_page_does_not_change_when_an_unrelated_edit_shifts_lines(
+    generator, fake_tree, monkeypatch
+):
+    """An edit that moves a read down a file must not make the page stale.
+
+    The page used to cite `path:line`, so any PR adding a line above a read had
+    to regenerate it and then conflicted with every other PR that had.
+    """
+    before = _render_one(generator, fake_tree, "ODYSSEUS_VIA_HELPER", monkeypatch)
+    source = fake_tree / "src" / "indirect.py"
+    source.write_text("import sys\n\n\n" + source.read_text(encoding="utf-8"), encoding="utf-8")
+
+    after = _render_one(generator, fake_tree, "ODYSSEUS_VIA_HELPER", monkeypatch)
+
+    assert generator.collect(fake_tree)["ODYSSEUS_VIA_HELPER"].primary.lineno == 19
+    assert after == before
+
+
+def test_extra_reads_are_counted_per_file(generator, tmp_path, monkeypatch):
+    monkeypatch.setattr(generator, "SOURCE_ROOTS", ("app.py", "src"))
+    _write(tmp_path, "app.py", """
+import os
+
+FIRST = os.environ.get("ODYSSEUS_READ_OFTEN", "1")
+SECOND = os.environ.get("ODYSSEUS_READ_OFTEN", "1")
+""")
+    _write(tmp_path, "src/elsewhere.py", """
+import os
+
+AGAIN = os.getenv("ODYSSEUS_READ_OFTEN")
+""")
+
+    page = _render_one(generator, tmp_path, "ODYSSEUS_READ_OFTEN", monkeypatch)
+
+    assert "| `app.py` (+1 more) |" in page
+
+
 def test_every_variable_read_in_the_repository_is_documented(built):
     _, variables, problems = built