diff --git a/frontend/dockerfile/docs/rules/workdir-relative-path.md b/frontend/dockerfile/docs/rules/workdir-relative-path.md
index 06043ea15..396be3e27 100644
--- a/frontend/dockerfile/docs/rules/workdir-relative-path.md
+++ b/frontend/dockerfile/docs/rules/workdir-relative-path.md
@@ -28,6 +28,12 @@ image built externally is prone to breaking, since working directory may change
 upstream without warning, resulting in a completely different directory
 hierarchy for your build.
 
+> [!NOTE]
+>
+> `WORKDIR` does not perform shell expansion. Paths beginning with `~` or
+> `~username` are treated as literal directory names and are not resolved to a
+> user's home directory.
+
 ## Examples
 
 ❌ Bad: this assumes that `WORKDIR` in the base image is `/`
diff --git a/frontend/dockerfile/linter/docs/WorkdirRelativePath.md b/frontend/dockerfile/linter/docs/WorkdirRelativePath.md
index e40c9a000..7778298a4 100644
--- a/frontend/dockerfile/linter/docs/WorkdirRelativePath.md
+++ b/frontend/dockerfile/linter/docs/WorkdirRelativePath.md
@@ -20,6 +20,12 @@ image built externally is prone to breaking, since working directory may change
 upstream without warning, resulting in a completely different directory
 hierarchy for your build.
 
+> [!NOTE]
+>
+> `WORKDIR` does not perform shell expansion. Paths beginning with `~` or
+> `~username` are treated as literal directory names and are not resolved to a
+> user's home directory.
+
 ## Examples
 
 ❌ Bad: this assumes that `WORKDIR` in the base image is `/`