Open the front door, and say what each section is not

.github/workflows/docs.yml

@@ -95,9 +95,10 @@ jobs:
           path: ${{ env.PNPM_STORE }}
           key: pnpm-store-${{ runner.os }}-${{ hashFiles('site/pnpm-lock.yaml') }}
           restore-keys: pnpm-store-${{ runner.os }}-
-      - name: Check the overview mirrors, then regenerate llms.txt
+      - name: Check the overview and glossary mirrors, then regenerate llms.txt
         run: |
           python3 scripts/mirror_overviews.py --check
+          python3 scripts/mirror_glossary.py --check
           python3 scripts/generate_llms.py
       - name: Check the icon sheet is not stale
         # The sheet is the index of the site's own icons and the only place a

Makefile

@@ -103,6 +103,7 @@ brand:
 
 llms:
 	$(PYTHON) scripts/mirror_overviews.py
+	$(PYTHON) scripts/mirror_glossary.py
 	$(PYTHON) scripts/generate_llms.py
 
 # Regenerate README_PYPI.md (the PyPI long description) from README.md:

docs/README.md

@@ -124,6 +124,7 @@ Full documentation for phonometry. Also available as a website:
   - [Environment and transport](reference/theory/environment-transport.md): environmental descriptors, impulsive adjustment, outdoor propagation, occupational exposure, sound power
   - [Vibration](reference/theory/vibration.md): human vibration weightings and metrics, multiple-shock spinal model
 - [Why phonometry](start/why-phonometry.md): IEC compliance vs other libraries
+- [Glossary](reference/glossary.md): every quantity the guides compute, grouped by domain, each with its symbol, a one-sentence definition, its unit, the standard and clause that defines it and the guide that implements it, plus the table of symbols that collide across domains
 - [Bibliography](reference/bibliography.md): the books and papers behind the guides, grouped by domain, every entry with a verified DOI or official publisher link
 - [Conformance report](CONFORMANCE.md): auto-generated numerical validation: every check pins a standard clause's expected value against the library's computed value, regenerated in CI
 - [Standards errata](ERRATA.md): defects found in the published standards themselves during implementation: misprints, examples contradicting their own normative text, ambiguous wording, each with evidence and the library's disposition

docs/aircraft/index.md

@@ -61,10 +61,7 @@ be read first if helicopters are what you came for.
 The three metrics are not interchangeable. EPNL is a *certification* metric of
 one aeroplane at one prescribed point; SEL and LASmax are *single-event*
 assessment metrics at an arbitrary receiver; neither is the long-term index a
-land-use study is finally judged on. And the boundary: this section does not
-compute cumulative multi-event indices, does not synthesise NPD tables from
-engine data, does not model hover, idle or taxi rotorcraft operations, and does
-not touch sonic boom.
+land-use study is finally judged on.
 
 ## Pages in this section
 
@@ -79,3 +76,44 @@ not touch sonic boom.
 - [The ANP fleet database](anp-fleet.md): the EASA tables of
   noise-power-distance curves and default trajectories that run the Doc 29
   chain for a real aircraft type.
+
+## What this section does not cover
+
+**Single events only.** The Doc 29 chain builds single-event contours; it does
+not assemble the cumulative multi-event indices — an Lden-style sum over a full
+flight schedule — that a complete noise-contour study needs on top of them. That
+last step is where a land-use decision is actually made, and it is not here.
+
+**No aircraft is modelled from first principles.** NPD tables and noise
+hemispheres are *inputs*: the library interpolates the tables published for a
+type and does not synthesise them from engine data, and the ANP database is read
+and never written (version 2.3 ships as-is). Of the ANP entries, only those with
+fixed-point profiles have a ready-to-use trajectory, because turning a
+procedural-step departure into a flight path needs the ICAO Doc 9911
+flight-mechanics performance model, which is not implemented.
+
+**Three specific gaps.** Rotorcraft hover, idle and taxi operations are outside
+the hemisphere source model, which assumes a flyover. The measurement-system
+verifier checks IEC 61265:1995 and not the superseding 2018 edition. And sonic
+boom is not touched anywhere in the library.
+
+Finally, the CNOSSOS-EU aircraft source of sections 2.6 and 2.7 is **not**
+implemented: aircraft noise here is the ICAO and ECAC family, which is a
+different set of models from the road and rail sources of [Environmental
+sources](../environment/sources/index.md), and the two must not be mixed inside
+one strategic map without saying so.
+
+## Before and after these pages
+
+Every level on these pages is built from band levels, so the filtering,
+weighting and calibration that produce them are in [Signal
+analysis](../signals/index.md), and [Build a sound level
+meter](../signals/sound-level-meter.md) runs that chain end to end on
+one runnable page. The derivations for aircraft noise are not in the theory
+reference: they stay inside the guides above, beside the flight geometry that
+motivates them.
+
+If you arrived here from a search and want the shape of the whole library,
+[What do you need to measure?](https://jmrplens.github.io/phonometry/start/tasks/) indexes it by the job
+and [All guides](https://jmrplens.github.io/phonometry/start/guides/) lists every page with a line on
+each.

docs/buildings/design/index.md

@@ -25,6 +25,17 @@ laboratory element and junction data are converted to their in-situ values,
 every path is formed per band, and the result shows which path dominates each
 band rather than only whether the room passes.
 
+**Which of the two do you run?** Run the simplified model when what you have is
+catalogue weighted ratings — $R_w$, $\Delta L_w$, a mass per unit area — and the
+question is whether the partition meets a limit. Run the detailed one when you
+have per-band element and junction spectra, or the material properties the
+standard can calculate them from, and the question is *which path to fix in
+which band*. The choice is not about accuracy on the rating: on the standard's
+own worked building the two agree well inside their stated spread, and the
+detailed airborne model carries no bias error and a standard deviation of 1,5 dB
+to 2,5 dB (Clause 5) against about 2 dB for the simplified one. What the
+detailed model buys is the spectrum behind the single number.
+
 [Predicting Panel Sound Insulation](panel-sound-insulation.md)
 goes one level deeper, to where the element $R$ itself comes from: the mass law
 and the coincidence dip of a single panel, the mass-spring-mass behaviour of a
@@ -69,6 +80,19 @@ follow the 2000 text — including the tabulated flanking correction $K$ that th
 follows the 2017 text. Check which edition your regulation calls up before
 quoting a correction from either.
 
+Every prediction here starts from measured data that came from somewhere else,
+and the design report has to say where. The element $R$ and $L_n$ come from
+ISO 10140-2 and -3, together with the laboratory structural reverberation time
+printed in the same report, because the in-situ conversion needs it. The
+junction indices $K_{ij}$ come from an ISO 10848 measurement or from the
+EN 12354-1 Annex E catalogue of junction types. The floor-covering improvement
+$\Delta L_w$ comes from ISO 16251-1 or from a full-size ISO 10140-3 test. The
+resilient layer's $s'$ comes from EN 29052-1. And for service equipment, the
+characteristic structure-borne power comes from the EN 15657 reception plate.
+Two of the pages in this section are themselves such measurements, feeding the
+others; the built result is finally checked against the ISO 16283 field
+measurement in [Sound insulation](../insulation/index.md).
+
 ## Pages in this section
 
 - [Predicting Sound Insulation (EN 12354)](insulation-prediction.md):
@@ -103,3 +127,31 @@ Pages elsewhere on the site that this section leans on:
 - [Dynamic stiffness of resilient materials (EN 29052-1)](../../materials/resilient/dynamic-stiffness.md):
   the load-plate resonance measurement, the enclosed-gas term and the
   floating-floor natural frequency.
+
+## What this section does not cover
+
+**A prediction is only as good as the element data you feed it, and the library
+takes that data as given.** The element ratings, the junction indices, the
+covering improvement and the structure-to-airborne adjustment terms of
+EN 12354-5 Annexes D and F are inputs you supply from measurement or from the
+standards' own annexes; none of them is derived here. The simplified prediction
+page stops at the weighted single numbers by design, and the detailed page is
+where the per-band models live.
+
+Every panel model carries a validity range it does not extend past, and the
+guides flag each: Sharp's single-panel method is not valid below about 1.5
+times the panel's first resonance, Gomperts' slit model holds only while the
+slit is narrow against the wavelength, only Leppington's method no. 1 is
+implemented for radiation efficiency, and the orthotropic routes are
+infinite-panel models that miss the dip real ribbed cladding shows between 2 and
+4 kHz. On the resilient-layer side, the tapping-machine force model assumes a
+frequency-independent driving-point impedance, so a joisted or battened
+lightweight floor is outside it; soft coverings are treated as linear springs;
+there is no per-band prediction of a lining's improvement, because Annex D is a
+single-number method; and heavy impact sources such as the rubber ball are not
+covered by any of these models at all — their rating is
+[Heavy and Soft Impact Sources](../insulation/heavy-impact-sources.md).
+
+Two edition boundaries: only the 2009 edition of EN 12354-5 is implemented, not
+the 2023 revision, and the simplified and detailed pages follow different
+editions of the 12354 family, as the note above says.

docs/buildings/index.md

@@ -24,7 +24,9 @@ and [Room Acoustics](rooms/room-acoustics.md): the impulse response
 the first acquires and the parameters the second derives are the vocabulary
 the rest of the section speaks. If your interest is insulation, read
 [Field Insulation Measurement (ISO 16283)](insulation/insulation-field.md)
-next; if it is design-stage prediction, go to
+next, and note that impact sources other than the tapping machine have their own
+page, since ISO 16283-2 is the clause a field engineer usually arrives with; if
+it is design-stage prediction, go to
 [Reverberation-time prediction (Sabine, Eyring, Arau)](rooms/reverberation-prediction.md)
 and [Predicting Sound Insulation (EN 12354)](design/insulation-prediction.md).
 
@@ -65,6 +67,9 @@ laboratory, and predicted from element data.
   the direct-power route to the same indices when flanking is high.
 - [Sound Insulation Survey Method (ISO 10052)](insulation/insulation-survey.md):
   the octave-band control method and its reverberation index.
+- [Heavy and Soft Impact Sources (ISO 16283-2)](insulation/heavy-impact-sources.md):
+  the rubber ball and the bang machine, the impact force exposure level that
+  specifies them and the ISO 717-2 Annex D single number.
 - [Laboratory Flanking Transmission (ISO 10848)](insulation/flanking-lab.md):
   the measured junction vibration reduction index and the flanking descriptors.
 - [Insulation Ratings (ISO 717)](insulation/insulation-ratings.md): the
@@ -98,3 +103,43 @@ and from the physics of the element itself.
   mobilities.
 - [Dynamic stiffness of resilient materials (EN 29052-1)](../materials/resilient/dynamic-stiffness.md):
   the load-plate resonance measurement behind every floating-floor prediction.
+
+## What this section does not cover
+
+**The library starts after the microphone and stops before the geometry.** On
+the measurement side, every function takes band levels already averaged over
+positions and already corrected for background noise: the position counts, the
+low-frequency procedures, the signal-to-background floors and the test-facility
+qualifications of ISO 16283, ISO 10140 and ISO 3382 are the operator's job, and
+nothing here checks that they were done. On the prediction side, the element
+ratings, the junction indices and the covering improvements are inputs you
+supply from measurement or from a standard's own annex; none is derived from a
+drawing.
+
+**Nothing here is a wave solver or a room model.** There is no geometry
+importer, no material database, no ray tracer and no auralisation: the room
+pages take dimensions, absorption coefficients and impulse responses and give
+back parameters, and the image-source model is specular only. An actual
+low-frequency field in a real shape is [wave
+simulation](../simulation/index.md).
+
+**And a prediction is not a verdict.** The single-number ratings and the
+national indices are computed here, but the limit values they are judged
+against are national — the Spanish code is implemented as a worked example of
+one such framework, not as the rule everywhere — and the requirement always
+comes from your regulation.
+
+## Before and after these pages
+
+Every quantity on these pages starts from band levels or from a filtered
+impulse response, so the calibration, weighting and fractional-octave
+filtering behind them are in [Signal analysis](../signals/index.md), and
+[Build a sound level meter](../signals/sound-level-meter.md) runs that
+chain end to end on one runnable page. The derivations sit in [Rooms and
+buildings theory](../reference/theory/rooms-buildings.md), from the Schroeder integration
+to the EN 12354 path sums.
+
+If you arrived here from a search and want the shape of the whole library,
+[What do you need to measure?](https://jmrplens.github.io/phonometry/start/tasks/) indexes it by the job
+and [All guides](https://jmrplens.github.io/phonometry/start/guides/) lists every page with a line on
+each.

docs/buildings/insulation/index.md

@@ -91,3 +91,34 @@ related EN 12354-5, lives in
 - [Spanish Building Code (CTE DB-HR)](spanish-building-code.md):
   the DB-HR global indices RA, RA,tr, DnT,A and D2m,nT,Atr, the clause 2
   requirements and the window-size correction.
+
+## What this section does not cover
+
+**The library starts after the microphone.** Every function here takes band
+levels that were already energy-averaged over positions and already corrected
+for background noise, and nothing verifies how the measurement was made: not the
+number and placement of source and microphone positions, not the low-frequency
+procedures of ISO 16283-1/-2, not the 6 dB signal-to-background floor, and not
+the test-facility and mounting requirements of ISO 10140-1. Those are the
+operator's responsibility and the report's, and they are what makes the numbers
+here mean something. Two consequences worth naming: the field and laboratory
+background corrections are *different* rules, so a laboratory helper must not be
+applied to field data; and the intensity route takes both the pressure and the
+intensity level as inputs, with the scanning probe and its phase-mismatch
+calibration outside the library.
+
+**Coverage inside the standards is partial in two places.** Of ISO 10848 only
+the Part 1 formulae are implemented generically, plus the Part 4 modal-overlap
+validity check, not the facility-specific setups of Parts 2, 3 and 4. Of the
+Spanish code, only the verification indices are implemented: the simplified
+option's solution tables of clause 3, the execution conditions of clause 5 and
+the maintenance conditions of clause 6 are out of scope, and the general
+option's calculation route is
+[Predicting Sound Insulation](../design/insulation-prediction.md).
+
+**And there is no heavy-impact prediction at all.** A floor construction can be
+carried to a tapping-machine level by the models in [Insulation
+design](../design/index.md); nothing does the same for the rubber
+ball, because the complexity of the input force and the use of a time-weighted
+maximum leave no simple counterpart. The heavy-impact page rates a measurement,
+and only a measurement.