The existing docs are pretty clear on the difference: rename is only guaranteed to replace an existing file on unix (which I think means posix in this context), whereas replace always replaces the file, regardless of platform.

I'm actually surprised that rename is even part of the pathlib API, since its cross platform behavior is not consistent.  It also seems as though the replace docs are incorrect, since they imply directories are replaced, but the os docs say they are not.

The "this is a posix requirement" note in os.replace also seems imprecise.  Windows is not posix, so that note leaves me wondering if replace is atomic on Windows or not.  That should be clarified one way or another.

I think adding the cross platform note in the pathlib docs is reasonable, since it addresses the question of why there are two similar functions.