docs: update undefined var check reference

frontend/dockerfile/docs/rules/undefined-var.md

@@ -13,24 +13,25 @@ Usage of undefined variable '$foo'
 
 ## Description
 
-Before you reference an environment variable or a build argument in a `RUN`
-instruction, you should ensure that the variable is declared in the Dockerfile,
-using the `ARG` or `ENV` instructions.
+This check ensures that environment variables and build arguments are correctly
+declared before being used. While undeclared variables might not cause an
+immediate build failure, they can lead to unexpected behavior or errors later
+in the build process.
 
-Attempting to access an environment variable without explicitly declaring it
-doesn't necessarily result in a build error, but it may yield an unexpected
-result or an error later on in the build process.
+This check does not evaluate undefined variables for `RUN`, `CMD`, and
+`ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form).
+That's because when you use shell form, variables are resolved by the command
+shell.
 
-This check also attempts to detect if you're accessing a variable with a typo.
-For example, given the following Dockerfile:
+It also detects common mistakes like typos in variable names. For example, in
+the following Dockerfile:
 
 ```dockerfile
 FROM alpine
 ENV PATH=$PAHT:/app/bin
 ```
 
-The check detects that `$PAHT` is undefined, and that it's probably a
-misspelling of `PATH`.
+The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
 
 ```text
 Usage of undefined variable '$PAHT' (did you mean $PATH?)
@@ -53,3 +54,17 @@ ARG foo
 COPY $foo .
 ```
 
+❌ Bad: `$foo` is undefined.
+
+```dockerfile
+FROM alpine AS base
+ARG VERSION=$foo
+```
+
+✅ Good: the base image defines `$PYTHON_VERSION`
+
+```dockerfile
+FROM python AS base
+ARG VERSION=$PYTHON_VERSION
+```
+

frontend/dockerfile/linter/docs/UndefinedVar.md

@@ -6,24 +6,25 @@ Usage of undefined variable '$foo'
 
 ## Description
 
-Before you reference an environment variable or a build argument in a `RUN`
-instruction, you should ensure that the variable is declared in the Dockerfile,
-using the `ARG` or `ENV` instructions.
+This check ensures that environment variables and build arguments are correctly
+declared before being used. While undeclared variables might not cause an
+immediate build failure, they can lead to unexpected behavior or errors later
+in the build process.
 
-Attempting to access an environment variable without explicitly declaring it
-doesn't necessarily result in a build error, but it may yield an unexpected
-result or an error later on in the build process.
+This check does not evaluate undefined variables for `RUN`, `CMD`, and
+`ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form).
+That's because when you use shell form, variables are resolved by the command
+shell.
 
-This check also attempts to detect if you're accessing a variable with a typo.
-For example, given the following Dockerfile:
+It also detects common mistakes like typos in variable names. For example, in
+the following Dockerfile:
 
 ```dockerfile
 FROM alpine
 ENV PATH=$PAHT:/app/bin
 ```
 
-The check detects that `$PAHT` is undefined, and that it's probably a
-misspelling of `PATH`.
+The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
 
 ```text
 Usage of undefined variable '$PAHT' (did you mean $PATH?)
@@ -45,3 +46,17 @@ FROM alpine AS base
 ARG foo
 COPY $foo .
 ```
+
+❌ Bad: `$foo` is undefined.
+
+```dockerfile
+FROM alpine AS base
+ARG VERSION=$foo
+```
+
+✅ Good: the base image defines `$PYTHON_VERSION`
+
+```dockerfile
+FROM python AS base
+ARG VERSION=$PYTHON_VERSION
+```