docs: define compatibility evidence

Document full RTD resistance envelopes for hardware compatibility checks.

Clarify the difference between vendor claims, electrical compatibility, and physical validation so support is not overstated.

Author: GregRR

docs/CHANGELOG.md

@@ -8,6 +8,10 @@ The first public alpha release was `0.1.0a1`.
 
 ### Added
 
+- Define full-characteristic resistance envelopes for all six current
+  `rtd-sensor` built-in RTD families and the evidence needed to distinguish
+  manufacturer support, electrical compatibility, range validation, and real
+  family/hardware validation.
 - Record the TI ADS1220 as a later configurable precision-ADC candidate and the
   PT-100-485/MB as a low-cost raw-resistance Modbus research candidate.
 - Record Atlas Scientific EZO-RTD as an evaluated temperature-output device

docs/DESIGN.md

@@ -1007,18 +1007,67 @@ repeated in every measurement.
 
 Three compatibility claims are distinct:
 
-1. **Manufacturer-supported** — the vendor explicitly documents support.
-2. **Electrically compatible** — the configured acquisition chain can measure
-   the required resistance range/topology even if not advertised for that RTD.
-3. **rtd-acquire validated** — the project has explicit test evidence for the
-   RTD/hardware/configuration combination.
+1. **Manufacturer-supported** — the vendor explicitly documents the relevant RTD
+   family/model or a resistance-input mode that covers the stated use, with the
+   required configuration/topology. The claim applies only to what the vendor
+   actually documents: support for a generic resistance-input mode does not
+   become a vendor claim for an RTD family that the documentation does not name.
+2. **Electrically compatible** — documented device limits plus engineering
+   analysis show that the configured acquisition chain can measure the complete
+   required resistance envelope and wiring/topology without violating relevant
+   reference, excitation, gain, input, or representability limits, even if the
+   vendor does not advertise that RTD family.
+3. **rtd-acquire validated** — the project has reproducible physical test
+   evidence for the hardware/configuration combination. Validation never upgrades
+   an electrically compatible combination into a manufacturer-supported claim.
 
 Compatibility is configuration-specific rather than a simple property of a
 converter chip. Reference resistance, excitation, gain, wiring, input limits,
-and other configuration may determine whether a combination is usable.
-
-The project must not turn an electrical-compatibility analysis into a claim of
-manufacturer support.
+and other configuration may determine whether a combination is usable. A nominal
+`R0` value alone is not enough: compatibility is checked against the complete
+ideal resistance envelope of the companion `rtd-sensor` characteristic.
+
+### 9.1 Evidence required for a compatibility record
+
+A compatibility record should identify enough evidence to reproduce the claim:
+
+- exact acquisition device/module and relevant hardware revision when known;
+- interface/backend used and software version or commit;
+- RTD family/characteristic being assessed;
+- required resistance envelope and its source/provenance;
+- reference resistor/reference network, excitation, gain, wiring mode, channel,
+  and other electrical settings that affect usable range;
+- vendor documentation supporting any manufacturer-support claim;
+- calculations and device limits supporting any electrical-compatibility claim;
+- physical test platform/date, reference equipment, tested resistance points,
+  acceptance limits, and result artifacts for project validation; and
+- explicit limitations, untested regions, and unresolved assumptions.
+
+Absence of one evidence class must remain visible. For example, successful bench
+tests can establish project validation for a configuration but cannot manufacture
+a vendor support statement that the vendor never made.
+
+### 9.2 Validation depth
+
+`rtd-acquire validated` can carry two useful evidence depths without creating
+additional compatibility categories:
+
+- **range-validated** — physical precision-resistance testing covers
+  representative low, middle, and high points spanning the required acquisition
+  envelope for a configuration. This validates resistance acquisition without
+  depending on RTD temperature-model interpretation.
+- **family/hardware validated** — the configured acquisition path is additionally
+  exercised with the intended RTD family on real hardware, with applicable
+  wiring behavior and any native-fault behavior required by the validation plan
+  recorded.
+
+A family/hardware validation does not imply that every resistance across the
+characteristic was physically tested. Conversely, range validation does not prove
+that a particular physical probe is suitable across its mathematical model's
+full temperature range. The validation record must say which evidence exists.
+
+The project must not turn electrical-compatibility analysis, range validation, or
+family testing into a stronger claim than the evidence supports.
 
 ### RTD-model parity goal
 

docs/HARDWARE.md

@@ -89,16 +89,36 @@ public diagnostic vocabulary.
 This table is the canonical `rtd-acquire` list of current `rtd-sensor` parity
 targets. The project should maintain at least one validated acquisition path for
 each listed built-in family and reconcile this table whenever `rtd-sensor` adds
-or removes a supported family:
-
-| RTD model | Nominal R0 | rtd-acquire obligation |
-| --- | ---: | --- |
-| Pt100 | 100 Ω | Required |
-| Pt500 | 500 Ω | Required |
-| Pt1000 | 1000 Ω | Required |
-| Ni120 6720 | 120 Ω | Required |
-| Ni1000 6180 | 1000 Ω | Required |
-| Ni1000 TK5000 | 1000 Ω | Required |
+or removes a supported family.
+
+The resistance envelope is the ideal-element resistance implied by the current
+`rtd-sensor` characteristic over that characteristic's complete supported
+temperature range. It is an **acquisition requirement**, not temperature-model
+logic for a driver. A candidate acquisition chain must be able to measure the
+required resistance interval with the intended wiring/configuration before it can
+be considered electrically compatible with the full characteristic.
+
+| RTD model | Nominal R0 | Characteristic span | Required ideal resistance envelope | rtd-acquire obligation |
+| --- | ---: | ---: | ---: | --- |
+| Pt100 | 100 Ω | -200 to 850 °C | 18.52008 to 390.481125 Ω | Required |
+| Pt500 | 500 Ω | -200 to 850 °C | 92.6004 to 1952.405625 Ω | Required |
+| Pt1000 | 1000 Ω | -200 to 850 °C | 185.2008 to 3904.81125 Ω | Required |
+| Ni120 6720 | 120 Ω | -80 to 260 °C | ~66.6000 to 380.3099 Ω | Required |
+| Ni1000 6180 | 1000 Ω | -60 to 250 °C | 695.202595 to 2891.5625 Ω | Required |
+| Ni1000 TK5000 | 1000 Ω | -60 to 250 °C | 751.79284 to 2517.265625 Ω | Required |
+
+The platinum values are derived from the IEC 60751 PT-385 characteristic used by
+`rtd-sensor`; Pt100, Pt500, and Pt1000 therefore share one normalized curve and
+differ only by scale. The nickel values come from the distinct 6720, 6180, and
+TK5000 characteristics used by `rtd-sensor`. Ni120 is shown rounded because its
+published piecewise coefficients require the small, explicitly bounded continuity
+adjustments documented by the companion project.
+
+These bounds describe the mathematical characteristic, not every physical RTD
+product sold under the same family name. A probe's packaging, construction,
+tolerance class, lead arrangement, or rated operating range may be narrower.
+Hardware validation must record the actual sensor and acquisition configuration
+rather than treating this table as a product-rating claim.
 
 A device need not support all models. Project-wide coverage is the goal. A new
 family first triggers a compatibility/validation review of existing acquisition

docs/REFERENCES.md

@@ -113,11 +113,42 @@ separate physical HERO/MAX31865 validation required by the roadmap.
 Roe, G. (2026). *rtd-sensor* [Python software]. GitHub.
 https://github.com/GregRR/rtd-sensor
 
-**Project use:** Integration-interface reference for the explicit package
-boundary demonstrated by `examples/rtd_sensor_pt100.py`. The example passes a
-trustworthy acquired resistance to `rtd_sensor.pt100.resistance_to_celsius()`;
-`rtd-sensor` remains a separate package rather than an `rtd-acquire` runtime
-dependency.
+**Project use:** Integration-interface and parity reference for the explicit
+package boundary demonstrated by `examples/rtd_sensor_pt100.py` and for the
+current built-in RTD families that `rtd-acquire 0.3` must cover. The companion
+project's source definitions and versioned conformance catalog identify the
+characteristic ranges and coefficients from which `rtd-acquire` derives required
+ideal resistance envelopes; `rtd-sensor` remains a separate package rather than
+an `rtd-acquire` runtime dependency.
+
+## RTD characteristic and resistance-envelope sources
+
+International Electrotechnical Commission. (2022). *IEC 60751:2022 industrial
+platinum resistance thermometers and platinum temperature sensors* (3rd ed.).
+https://webstore.iec.ch/en/publication/63753
+
+**Project use:** Normative scientific source inherited through the companion
+`rtd-sensor` PT-385 characteristic for the Pt100, Pt500, and Pt1000 full-model
+resistance envelopes used in 0.3 acquisition-compatibility planning.
+
+Innovative Sensor Technology AG. (n.d.). *RTD nickel sensors* [Application
+note].
+https://www.ist-ag.com/sites/default/files/downloads/ATN_E.pdf
+
+**Project use:** Scientific source inherited through `rtd-sensor` for the
+former-DIN Ni1000 6178/6180 ppm/K and Nickel NL / Ni1000 TK5000 5000 ppm/K
+characteristics. The resulting resistance envelopes are compatibility inputs,
+not runtime temperature-model logic in `rtd-acquire`.
+
+Minco Products, Inc. (n.d.). *Resistance thermometry: Principles and
+applications of resistance thermometers and thermistors*.
+https://www.minco.com/wp-content/uploads/Resistance-Thermometry.pdf
+
+**Project use:** Scientific source inherited through `rtd-sensor` for the North
+American Ni120 / 6720 ppm/K piecewise characteristic and its -80 °C through
+260 °C model span. The companion project owns the bounded continuity treatment
+of the published rounded segments; `rtd-acquire` consumes only the resulting
+resistance-envelope requirement.
 
 ## Precision ADC and converter research
 

docs/ROADMAP.md

@@ -127,16 +127,25 @@ validate them independently against Python.
 Goal: ensure the project as a whole provides practical acquisition paths for
 all current `rtd-sensor` built-in RTD families.
 
-- [ ] Document resistance requirements for Pt100, Pt500, Pt1000, Ni120,
+- [x] Document resistance requirements for Pt100, Pt500, Pt1000, Ni120,
       Ni1000 6180, and Ni1000 TK5000 without importing temperature-model logic
-      into acquisition drivers.
-- [ ] Classify tested combinations as manufacturer-supported, electrically
-      compatible, and/or `rtd-acquire` validated.
-- [ ] Validate appropriate MAX31865 configurations beyond Pt100 where the
-      electrical range and reference network support them.
-- [ ] Add precision reference-resistance validation across representative
-      low/mid/high operating points.
-- [ ] Document unsupported or unvalidated combinations explicitly.
+      into acquisition drivers; define the compatibility/evidence vocabulary used
+      by later validation records.
+- [ ] Add machine-readable 0.3 compatibility/evidence data after the textual
+      contract is stable enough to avoid freezing accidental schema choices.
+- [ ] Extend shared Python/C MAX31865 conformance and threshold coverage to a
+      representative ~4.3 kΩ reference network/high-scale configuration.
+- [ ] Classify MAX31865/family configurations as manufacturer-supported,
+      electrically compatible, and/or `rtd-acquire` validated, with unsupported
+      and unvalidated combinations explicit.
+- [ ] Publish the compatibility matrix and evidence distinctions in the GitHub
+      Pages documentation with navigation/cross-links and bibliography updates.
+- [ ] Extend the physical validation procedure across representative family
+      resistance envelopes and precision low/mid/high reference points.
+- [ ] Add a reproducible validation-results template and small capture helpers so
+      physical evidence can be recorded without copying ad hoc terminal output.
+- [ ] Record incremental real-hardware evidence as equipment becomes available,
+      while keeping untested combinations visibly unvalidated.
 
 ## 0.4 — Configurable precision ADC: ADS124S08