doc + simplify logic around using mapper modified