diff --git a/docs/known-issues.md b/docs/known-issues.md
index c762b1a..ad06ab0 100644
--- a/docs/known-issues.md
+++ b/docs/known-issues.md
@@ -146,3 +146,26 @@ created with `external=[...]` storage returns
 `FormatError::ExternalDataFilesUnsupported`. Neither is resolved. If support is
 added, file names must be confined to the opened file's directory, as the
 virtual-dataset resolver now does.
+
+---
+
+## Python interop suites skip silently when no interpreter has h5py
+
+**Status:** fixed on `main` in `a29c1b2` (2026-09-19).
+
+On a system where `python3` is a PEP 668 "externally managed" interpreter,
+h5py cannot be installed into it at all, and every interop suite — the h5py
+writer round-trips, the facade suite, netCDF4, and the reference files —
+returned `false` from its availability probe and skipped without failing. CI
+reported `SKIP` and a green run. This is the same class of gap that let the
+compound-datatype v5 bug above reach a release.
+
+The probes now read `CLAWHDF5_PYTHON`, and `scripts/ci-test.sh` picks up
+`.venv/bin/python` automatically. To restore the coverage on a fresh checkout:
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install h5py numpy netCDF4
+```
+
+Set `CLAWHDF5_REQUIRE_INTEROP=1` in any automated runner so a missing
+interpreter is a failure rather than a skip.