diff --git a/docs/architecture.md b/docs/architecture.md
index 9bd18d4..abb2e66 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1144,8 +1144,10 @@ pretending to be a general compute graph.
   and memory-optimal partial-field residency — is a reserved extension (see the
   axis-role contract). The shipped random-crop example (`examples/wb2_dataloader.py`)
   does exactly this — crops in a `batch_transform` over the whole-field cache, so the
-  crop re-randomizes each epoch for free — but its crop is a per-sample Python loop,
-  illustrative rather than vectorized.
+  crop re-randomizes each epoch for free — and its crop is vectorized: one batched RNG
+  draw for every sample's window origin, then a single `sliding_window_view` gather, so
+  each window copies as a block rather than walking the axes element by element. What a
+  whole-field read costs is bytes, not Python — the crop is cheap, the read is not.
 - **Not a compute framework.** No general task graph, no cross-chunk reductions on
   the hot path, no lazy dask-style evaluation — by design (dask on the hot path is
   the thing we route around). Reductions like fitting a scaler run *over the loader*
diff --git a/docs/tuning.md b/docs/tuning.md
index bd2459e..69a956e 100644
--- a/docs/tuning.md
+++ b/docs/tuning.md
@@ -53,6 +53,22 @@ The corollary for the other two axes: **`block_chunks` is a training knob** (it
 quality, and only `.train` shuffles — eval views are deterministic), and the **cross-epoch
 cache is a training knob** (single-pass scoring never reads a chunk twice).
 
+!!! note "`block_chunks` guidance on this page is under revision"
+
+    This page presents `block_chunks` as a shuffle-and-residency knob — the sizing advice
+    below, and the per-regime rows at the end, all follow from that. It also affects
+    **throughput**, by a mechanism the page does not yet describe: a batch may draw from any
+    chunk in its shuffle-block, so the whole block must be co-resident to gather, and on a
+    store whose read latency has a long tail one slow read can hold the concurrency window
+    open for the rest of the block. Wider blocks amortise that; on a pass already saturated
+    downstream of admission they only cost residency.
+
+    Which way it lands is therefore a property of the store and the box, not of the loader,
+    and the guidance here is not yet conditioned on it. Until it is, treat the `block_chunks`
+    sizing advice below as **necessary but not sufficient** — correct about RAM and shuffle
+    quality, silent about read-latency tails — and measure both ends of your range rather
+    than taking a default from this page.
+
 ## The knobs you set
 
 All of these are `InSituDataset(...)` arguments except the last, which is fixed when the