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

frontend/dockerfile/docs/reference.md

@@ -1871,6 +1871,13 @@ COPY --chmod=g=u config/ /config/
 
 The `--chmod` flag is not supported when building Windows containers.
 
+#### Parent directory permissions
+
+Parent directories will be created with the same mode that is specified by this
+flag. This can be affected by the process umask. This is most common when
+attempting to copy with mode `777` since the common umask of `022` can change
+the created directories to be `755` instead.
+
 ### COPY --chown
 
 ```dockerfile
@@ -1967,6 +1974,22 @@ 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 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