diff --git a/docs/source/user_guide/attrs_contract.rst b/docs/source/user_guide/attrs_contract.rst
index a309c0c31..25e161640 100644
--- a/docs/source/user_guide/attrs_contract.rst
+++ b/docs/source/user_guide/attrs_contract.rst
@@ -63,6 +63,13 @@ write.
        primary nodata source. The read-side precedence chain is
        ``nodata``, then ``nodatavals``, then ``_FillValue``; see
        ``_resolve_nodata_attr``.
+   * - ``masked_nodata``
+     - bool
+     - Paired with ``nodata``. ``True`` when the in-memory array is
+       float dtype and the reader's sentinel-to-NaN step ran;
+       ``False`` when the array still carries the literal integer
+       sentinel. Only set when ``nodata`` is set; absence means no
+       declared sentinel.
    * - ``raster_type``
      - str
      - ``'point'`` when the file declares ``RasterPixelIsPoint``;
diff --git a/xrspatial/geotiff/_attrs.py b/xrspatial/geotiff/_attrs.py
index 2d6752026..d0da7c148 100644
--- a/xrspatial/geotiff/_attrs.py
+++ b/xrspatial/geotiff/_attrs.py
@@ -37,9 +37,15 @@
   ``(pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y)``. Omitted
   for files with no GeoTIFF transform tags (ModelTransformation,
   ModelPixelScale, or ModelTiepoint).
-- ``nodata``: declared file sentinel as stored in the GDAL_NODATA tag. The
-  declared-vs-masked split is tracked in issue #1988; the canonical
-  semantics here describe the intended behaviour once #1988 lands.
+- ``nodata``: declared file sentinel as stored in the GDAL_NODATA tag.
+  Set whenever the source declares one, as a scalar of the source
+  dtype, regardless of whether the in-memory array is float-with-NaN
+  or int-with-sentinels.
+- ``masked_nodata``: boolean flag paired with ``nodata``. ``True`` iff
+  the in-memory array is float dtype and the reader's sentinel-to-NaN
+  step ran; ``False`` iff the array still carries the literal integer
+  sentinel. Only emitted when ``nodata`` is set; absence is the
+  "no declared sentinel" signal. See ``_set_nodata_attrs``.
 - ``raster_type``: ``'area'`` (implicit / RasterPixelIsArea) or ``'point'``
   (explicit / RasterPixelIsPoint).
 - ``extra_tags``: list of ``(tag_id, type_id, count, value)`` tuples for