Merge branch 'feat/p2-python-bindings' into feat/p2-perf-coverage

# Conflicts:
#	CHANGELOG.md
#	README.md

docs/QUICKSTART.md

@@ -395,19 +395,22 @@ clawhdf5 --path agent.h5 snapshot backup_2026-03-19.h5
 Read HDF5 files from Python without libhdf5:
 
 ```bash
-pip install clawhdf5  # coming soon — build from source for now
-cd crates/clawhdf5-py && maturin develop
+# Not on PyPI yet: build from source into a virtualenv
+pip install maturin numpy
+cd crates/clawhdf5-py && maturin develop --release
 ```
 
 ```python
 import clawhdf5
 
-# Read
-f = clawhdf5.open("data.h5")
-temps = f.read_f64("temperatures")
-print(temps)  # [22.5, 23.1, 21.8]
+# Read (h5py-style)
+with clawhdf5.File("data.h5", "r") as f:
+    temps = f["temperatures"][:]
+    print(temps)  # [22.5 23.1 21.8]
 ```
 
+See `crates/clawhdf5-py/README.md` for the supported types and indexing.
+
 ---
 
 ## Common Patterns

docs/known-issues.md

@@ -7,6 +7,23 @@ deleting it.
 
 ---
 
+## Selection reads that decode more than the selection
+
+**Status:** open (documented 2026-09-26). `Dataset::read_selection` (and so
+the Python `ds[...]`) materialises only the selection's bounding box when
+that box covers at most half the dataset (`partial_read`). It decodes the
+whole dataset and extracts the selection instead when:
+- the bounding box covers more than half the dataset — which a strided
+  selection across a chunked dataset (`ds[::100]`) always does, although
+  it may touch few chunks;
+- the dataset is compact or virtual, or has no storage;
+- it is chunked with a non-default fill value (the box path does not fill
+  unallocated chunks, so the fill-aware full read is used).
+Values are correct in every case; this is cost only. Selections other than
+`Selection::All` also bypass the file's chunk cache. The bounding-box
+heuristic's other cost is measured under "Concurrent and contiguous read
+performance" below.
+
 ## Concurrent and contiguous read performance (measured 2026-09-26)
 
 **Status:** open for chunked full reads (one cause fixed 2026-09-26); the