docs: warn FIEMAP locations are unstable

doc/bcachefs.5.rst.tmpl

@@ -125,6 +125,21 @@ be used to pin a specific file or directory to a specific device or target:
 Note that if the target specified is full, the write will spill over to the rest
 of the filesystem.
 
+FIEMAP and block-level writes
+-----------------------------
+
+Tools such as ``filefrag`` use the kernel FIEMAP interface to report the
+physical locations of a file's extents. On bcachefs, those locations are an
+observation, not a stable userspace write ABI: background data movement such as
+copygc, rebalance, evacuation, or normal filesystem updates may relocate extents,
+and userspace has no interface to lock those moves out.
+
+Writing directly to the block device locations reported by FIEMAP, for example
+through a manually constructed device-mapper table, is therefore unsafe while
+the filesystem is mounted. This remains true even for preallocated files and
+files using ``nocow``; any block-level write path must be coordinated by the
+filesystem itself.
+
 Data protection
 ---------------