docs(#294) disambiguate n̂ / surface_normal / azimuthal_reference and unify reference-vector terminology

[prjemian]

• closes Questions about nHat #294

Issue #294 asked three connected questions about the reference vector
n̂:

1. What does nHat = 0 mean as a default?
2. How do I provide a new value of nHat?
3. The term is hard to search — it goes by nHat, n_hat,
   \hat{n}, surface_normal, azimuthal_reference …

… plus a request to disambiguate nHat, azimuthal reference vector,
and ψ. The worst part of the search-collision was that
nHat (camelCase) was reused in the codebase for a completely
different concept — the per-stage rotation-axis vector — so a
search for nHat returned matches that meant two different things.

This PR delivers the answer in five coordinated parts on a single
issue, per the operator's standing batched-fix preference.

Code

F2 — AdHocDiffractometer.required_reference_vector

New property that returns 'surface_normal', 'azimuthal_reference',
or None based on the active mode's
ReferenceConstraint. Lets a caller skip the table:

g.mode_name = "fixed_alpha_i_fixed_chi_fixed_phi"
attr = g.required_reference_vector       # → 'surface_normal'
setattr(g, attr, (0, 0, 1))

F1 — warning on extras['n_hat'] assignment

ConstraintSet.extras is now a _ExtrasDict subclass that emits a
UserWarning when a non-sentinel, non-None value is assigned to
the 'n_hat' placeholder key, directing the caller at the correct
geometry attribute. Construction-time fast-path values (sentinels
from the YAML loader, dict-init copies, from_dict round-trips)
remain silent — the warning fires only on explicit user
__setitem__.

Source rename: nHat → n_axis

rotation.py and stage.py docstrings now use n_axis (snake_case)
for the per-stage rotation-axis vector. The three documentation
files that referenced nHat were updated in lockstep. Search
grep -r 'nHat' src/ docs/ tests/ now returns zero results.

Documentation

Glossary (docs/source/glossary.md)

New entries:

• n̂ (reference vector) — the canonical disambiguation entry with
  a full surface-form table mapping every spelling (n̂, \hat{n},
  n_hat, surface_normal, azimuthal_reference) to what each
  refers to and where it appears.
• Azimuthal reference vector
• Surface normal
• Stage rotation axis (with explicit "not to be confused with n̂"
  cross-reference).

The existing ψ (psi) angle entry was extended to cross-link the
azimuthal reference vector and to spell out that ψ is a scalar angle,
distinct from the vector it is measured from.

The existing Stage entry was updated to use a {term} link to
Stage rotation axis instead of introducing a new "axis direction"
phrasing — keeping the term vocabulary minimal per the operator's
guidance. All italic *Term* cross-refs throughout the new entries
were replaced with {term} links for consistency.

How-to (docs/source/howto/surface.md)

Opens with a quick-reference table mapping constraint name → geometry
attribute → recipe, plus a new section explaining why
extras['n_hat'] is a documentation placeholder, with the
WRONG / RIGHT recipe pair the new warning points to. Also
explicitly addresses the "what does n̂ = 0 mean?" question (it does
not exist as a state — (0, 0, 0) is rejected, default is None).

Per-geometry pages (10 files)

All 21 Extras (input) rows that reference n̂ unified to the form

n̂ → set g.surface_normal = (h, k, l)

or

n̂ → set g.azimuthal_reference = (h, k, l); ψ target via with_constraint_values(psi=...)

so the answer is right where users land in the reference docs.

Cross-reference notes in code-facing docs

concepts.md, howto/custom_geometry.md, and
reference/declarative_geometry_schema.md now carry a one-paragraph
"not to be confused with n̂ (the reference vector)" note next to
their n_axis references.

CHANGES.md

### Added
- `AdHocDiffractometer.required_reference_vector` property. (#294)
- Warn on `extras['n_hat']` assignment. (#294)

### Changed
- Disambiguate n̂ / surface_normal / azimuthal_reference / n_axis. (#294)

Verification on wow.xray.aps.anl.gov (Python 3.14.4, NumPy 2.4)

• pytest: 2623 passed, 2 skipped, 3 deselected — 100.00 % coverage (17 new tests: 10 for required_reference_vector, 7 for the placeholder-key warning)
• pre-commit run --all-files: clean
• make -C docs clean html: clean build, no warnings
• Both AGENTS.md RST-leak grep patterns: clean
• US-English spelling check on every changed file: clean
• grep -r 'nHat' src/ docs/ tests/: zero matches — search-collision eliminated

Contributed by: OpenCode (argo/claudeopus47)