diff --git a/examples/user_guide/25_GLCM_Texture.ipynb b/examples/user_guide/25_GLCM_Texture.ipynb
index 4d196bce..fb8a38bc 100644
--- a/examples/user_guide/25_GLCM_Texture.ipynb
+++ b/examples/user_guide/25_GLCM_Texture.ipynb
@@ -10,6 +10,17 @@
     "Gray-Level Co-occurrence Matrix (GLCM) features capture spatial patterns that spectral bands alone cannot distinguish. They quantify how pixel intensities co-occur within a neighborhood, producing metrics like contrast, homogeneity, and entropy. This notebook covers the six Haralick features available in `glcm_texture`, parameter tuning, and a satellite-based water/land classification example."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Tier note\n",
+    "\n",
+    "The classification section reads a Sentinel-2 Cloud-Optimized GeoTIFF over HTTPS with `open_geotiff`. The HTTP COG reader sits at the `advanced` tier in `xrspatial.geotiff.SUPPORTED_FEATURES` (`reader.http_cog`): range fetching, redirect handling, and cache behaviour are not contracted at the stable bar. Local COG reads (`reader.local_cog`) and the GLCM kernel itself are unrelated to that caveat -- swap the URL for a local path and the rest of the notebook stays inside the stable surface.\n",
+    "\n",
+    "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "7yishbzt21d",
@@ -453,4 +464,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
\ No newline at end of file
+}
diff --git a/examples/user_guide/29_Preview.ipynb b/examples/user_guide/29_Preview.ipynb
index b31f3700..28d80f3a 100644
--- a/examples/user_guide/29_Preview.ipynb
+++ b/examples/user_guide/29_Preview.ipynb
@@ -10,6 +10,15 @@
     "When a raster is backed by dask (e.g., loaded lazily from Zarr or a stack of GeoTIFFs), calling `.compute()` to visualize it can blow up your memory. `xrspatial.preview()` downsamples the data to a target pixel size using block averaging, and the whole operation stays lazy until you ask for the result. Peak memory is bounded by the largest chunk plus the small output array."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### See also\n",
+    "\n",
+    "If you feed `preview` data loaded via `open_geotiff`, `docs/source/reference/geotiff.rst` records which reader paths are `stable`, `advanced`, or `experimental` in `xrspatial.geotiff.SUPPORTED_FEATURES`.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "x11ktiuo2cf",
diff --git a/examples/user_guide/39_GeoTIFF_IO.ipynb b/examples/user_guide/39_GeoTIFF_IO.ipynb
index 7e6746bc..dcbf6687 100644
--- a/examples/user_guide/39_GeoTIFF_IO.ipynb
+++ b/examples/user_guide/39_GeoTIFF_IO.ipynb
@@ -9,6 +9,17 @@
     "GeoTIFF is the standard raster format in geospatial work. xarray-spatial has a pure-Python reader and writer (no GDAL) that follows xarray naming: `open_geotiff` to read, `to_geotiff` to write."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Tier note\n",
+    "\n",
+    "`open_geotiff` and `to_geotiff` against local files, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), and axis-aligned 2D / 3D rasters are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES`. Dask reads (`reader.dask`) and dask streaming writes (covered by `writer.local_file`) are stable too. The VRT mosaic section at the bottom exercises `write_vrt` / `read_vrt`, which sit at the `advanced` tier (`reader.vrt`): the supported subset is a flat mosaic of compatible GeoTIFF tiles, not the full GDAL VRT spec.\n",
+    "\n",
+    "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
diff --git a/examples/user_guide/40_JPEG2000_Compression.ipynb b/examples/user_guide/40_JPEG2000_Compression.ipynb
index 229f5880..81df2ce3 100644
--- a/examples/user_guide/40_JPEG2000_Compression.ipynb
+++ b/examples/user_guide/40_JPEG2000_Compression.ipynb
@@ -6,6 +6,19 @@
    "source": "# Xarray-Spatial I/O: JPEG 2000 compression\n\nSatellite imagery (Sentinel-2, Landsat) often ships in JPEG 2000 format. The `geotiff` module lets you write and read J2K-compressed GeoTIFFs on CPU (via glymur/OpenJPEG) or GPU (via nvJPEG2000).",
    "metadata": {}
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Experimental tier callout\n",
+    "\n",
+    "The `jpeg2000` / `j2k` codec is tagged `experimental` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`codec.jpeg2000`, `codec.j2k`). Cross-backend numerical parity, external GDAL / libtiff interop, and round-trip stability across releases are not contracted yet. Writers require the explicit `allow_experimental_codecs=True` opt-in. The GPU path (`reader.gpu` / `writer.gpu`) is also `experimental` and probes for nvJPEG2000 lazily on the first GPU call -- if `libnvjpeg2k.so` is not on the loader path, the GPU codec is unavailable and the call falls back or fails.\n",
+    "\n",
+    "Treat the recipes below as a working reference for the current code, not a stable API surface. If you need a contracted lossless codec, use `deflate`, `lzw`, `zstd`, or `packbits` from the stable tier instead.\n",
+    "\n",
+    "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "46a72497",
@@ -130,4 +143,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
\ No newline at end of file
+}
diff --git a/examples/user_guide/46_GeoTIFF_Performance.ipynb b/examples/user_guide/46_GeoTIFF_Performance.ipynb
index cacff7c9..02babef6 100644
--- a/examples/user_guide/46_GeoTIFF_Performance.ipynb
+++ b/examples/user_guide/46_GeoTIFF_Performance.ipynb
@@ -11,6 +11,17 @@
     "arrays and chunked Dask arrays alike."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Tier note\n",
+    "\n",
+    "The `dtype` and `compression_level` techniques below ride on the stable local read / write paths (`reader.local_file`, `writer.local_file`) and the stable lossless codecs. The third section (\"VRT tiled output\") drives `to_geotiff(..., vrt=True)`: each per-tile write itself rides on `writer.local_file` (stable), and the round-trip read through the VRT XML uses `reader.vrt`, which sits at the `advanced` tier. The supported VRT subset is a flat mosaic of compatible sibling tiles, not the full GDAL VRT spec.\n",
+    "\n",
+    "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -246,4 +257,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
\ No newline at end of file
+}
diff --git a/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb b/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb
index 4a89a1c2..778e5cdd 100644
--- a/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb
+++ b/examples/user_guide/47_Streaming_GeoTIFF_Write.ipynb
@@ -10,6 +10,17 @@
     "Only one tile-row lives in memory at once, so you can write rasters larger than RAM without switching to VRT output."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Tier note\n",
+    "\n",
+    "The streaming write path itself rides on `writer.local_file` (stable): a dask-backed `to_geotiff` call streams tile-row by tile-row out to a single TIFF using the stable lossless codecs. The \"Stream-write to a VRT mosaic\" section also uses `writer.local_file` for the per-tile writes; the `advanced` tier (`reader.vrt`) only applies on the round-trip read through the VRT XML, where the supported subset is a flat sibling-tile mosaic rather than the full GDAL VRT spec.\n",
+    "\n",
+    "**See also:** the GeoTIFF / COG reference page at `docs/source/reference/geotiff.rst` lists every feature in `xrspatial.geotiff.SUPPORTED_FEATURES` against its tier (`stable`, `advanced`, `experimental`, `internal_only`) and links the release gate that locks each promise.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
diff --git a/examples/user_guide/52_COG_Overview_Generation.ipynb b/examples/user_guide/52_COG_Overview_Generation.ipynb
index 68133e3a..2580cc5d 100644
--- a/examples/user_guide/52_COG_Overview_Generation.ipynb
+++ b/examples/user_guide/52_COG_Overview_Generation.ipynb
@@ -14,7 +14,21 @@
   },
   {
    "cell_type": "markdown",
-   "source": "### Stable COG contract\n\nThe local COG writer and the local COG reader are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`writer.cog` and `reader.local_cog`). Axis-aligned 2D / 3D rasters, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), internal overviews, and normal CRS / transform / nodata round-trip are covered by the parity and compliance suites that gate every CI build, so the examples in this notebook all sit inside the stable contract.\n\nA few combinations stay outside the stable contract and keep their existing `advanced` or `experimental` tier:\n\n- The HTTP COG reader (`reader.http_cog`) -- range fetching, redirect handling, and cache behaviour are not contracted yet. Use with care.\n- GPU COG read / write.\n- Experimental codecs (`lerc`, `jpeg2000` / `j2k`, `lz4`) and the internal-only `jpeg` codec.\n- Rotated transforms, external `.tif.ovr` sidecars, file-like destinations with `cog=True`.\n- BigTIFF COG (tracked separately).\n\nSee the *Stable COG contract* section of the GeoTIFF / COG reference page for the full list.",
+   "source": [
+    "### Stable COG contract\n",
+    "\n",
+    "The local COG writer and the local COG reader are tagged `stable` in `xrspatial.geotiff.SUPPORTED_FEATURES` (`writer.cog` and `reader.local_cog`). Axis-aligned 2D / 3D rasters, the lossless codecs (`none`, `deflate`, `lzw`, `zstd`, `packbits`), internal overviews, and normal CRS / transform / nodata round-trip are covered by the parity and compliance suites that gate every CI build, so the examples in this notebook all sit inside the stable contract.\n",
+    "\n",
+    "A few combinations stay outside the stable contract and keep their existing `advanced` or `experimental` tier:\n",
+    "\n",
+    "- The HTTP COG reader (`reader.http_cog`) -- range fetching, redirect handling, and cache behaviour are not contracted yet. Use with care.\n",
+    "- GPU COG read / write.\n",
+    "- Experimental codecs (`lerc`, `jpeg2000` / `j2k`, `lz4`) and the internal-only `jpeg` codec.\n",
+    "- Rotated transforms, external `.tif.ovr` sidecars, file-like destinations with `cog=True`.\n",
+    "- BigTIFF COG (tracked separately).\n",
+    "\n",
+    "See the *Stable COG contract* section of the GeoTIFF / COG reference page for the full list.\n"
+   ],
    "metadata": {}
   },
   {
@@ -278,4 +292,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
\ No newline at end of file
+}