diff --git a/docs/source/user_guide/attrs_contract.rst b/docs/source/user_guide/attrs_contract.rst
index ba79f4243..c1a04ec11 100644
--- a/docs/source/user_guide/attrs_contract.rst
+++ b/docs/source/user_guide/attrs_contract.rst
@@ -42,20 +42,26 @@ write.
      - EPSG code of the horizontal CRS, when one can be resolved.
    * - ``crs_wkt``
      - str
-     - WKT2 string of the horizontal CRS. Always present on read when
-       any CRS information is available, and treated as the canonical
-       CRS representation when both ``crs`` and ``crs_wkt`` are set.
+     - WKT string of the horizontal CRS. Present on read when any CRS
+       information is available, and treated as the canonical CRS
+       representation when both ``crs`` and ``crs_wkt`` are set. The
+       dialect depends on the source: paths that synthesise a WKT from
+       an EPSG code via pyproj emit WKT2; paths that read a WKT
+       verbatim from the file (e.g. a VRT ``SRS`` tag) carry whatever
+       dialect was stored.
    * - ``transform``
      - tuple
-     - ``(origin_x, pixel_width, 0, origin_y, 0, pixel_height)``
-       affine transform tuple matching the GDAL ordering. Omitted for
-       files with no ``ModelTransformation`` / ``ModelPixelScale`` /
-       ``ModelTiepoint`` tags.
+     - ``(pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y)``
+       affine transform tuple matching the rasterio ``Affine`` ordering.
+       Omitted for files with no ``ModelTransformation`` /
+       ``ModelPixelScale`` / ``ModelTiepoint`` tags.
    * - ``nodata``
      - scalar
      - Numeric NoData sentinel. Emitted by readers when the file
        carries a ``GDAL_NODATA`` tag, and consumed by writers as the
-       primary nodata source.
+       primary nodata source. The read-side precedence chain is
+       ``nodata``, then ``nodatavals``, then ``_FillValue``; see
+       ``_resolve_nodata_attr``.
    * - ``raster_type``
      - str
      - ``'point'`` when the file declares ``RasterPixelIsPoint``;
@@ -176,11 +182,13 @@ must not assume a specific pass-through key survives a round-trip.
      - Raw ``ColorMap`` TIFF tag (tag id 320) values.
    * - ``colormap_rgba``
      - array
-     - Decoded RGBA colormap, when one is present.
+     - Decoded RGBA colormap. Emitted only when the file's photometric
+       interpretation is ``Photometric == 3`` (palette).
    * - ``cmap``
      - ``matplotlib.colors.ListedColormap``
      - Matplotlib colormap built from ``colormap_rgba``. Present only
-       when matplotlib is importable.
+       when matplotlib is importable and the same ``Photometric == 3``
+       gate is satisfied.
 
 
 Round-trip invariants
diff --git a/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py b/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py
index 0ab9c0c0f..ef10eecc5 100644
--- a/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py
+++ b/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py
@@ -29,6 +29,9 @@
 from xrspatial.geotiff._attrs import _resolve_nodata_attr
 
 
+# Arbitrary float-castable sentinel that is distinct from any data value
+# used below. The value itself does not matter; the tests assert it
+# survives the alias resolver and the round-trip.
 _SENTINEL = -9999.0