docs: clarify a caveat with COPY --link and overwriting directory permissions

frontend/dockerfile/docs/reference.md

@@ -1967,6 +1967,23 @@ path, using `--link` is always recommended. The performance of `--link` is
 equivalent or better than the default behavior and, it creates much better
 conditions for cache reuse.
 
+When copying a path into a subdirectory, `--link` will always create the
+parent directories with the default directory creation settings and will always
+copy from the root of the filesystem. When copying a directory, the existing
+mode is overridden with the new mode from the copied path. If you need a specific
+mode for a directory, such as the more permissive `/tmp` directory, you may need
+to either avoid using `--link` or unroll the copy into its base components.
+
+```dockerfile
+FROM scratch AS staging
+COPY a.txt /tmp/a.txt
+
+FROM alpine
+# Avoids overwriting the mode of /tmp but also has the same
+# benefits of using --link=true.
+COPY --from=staging /tmp/ /tmp/
+```
+
 ### COPY --parents
 
 ```dockerfile