Merge pull request #26230 from mdelapenya/fix/workspace-var-names

docs: distinguish the ${WORKDIR} placeholder from the WORKSPACE_DIR variable

content/manuals/ai/sandboxes/customize/author/_index.md

@@ -176,6 +176,18 @@ for setup examples and the upstream
 [lifecycle definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md)
 for the fields.
 
+### Generated files
+
+In lifecycle `files` content, write `${{ kit.env.NAME }}` to insert a
+container environment variable. For example, write
+`${{ kit.env.WORKSPACE_DIR }}` for the workspace path. Plain `$VAR` and
+`${VAR}` are written unchanged, without substituting their values. In hook
+commands, use shell syntax such as `$WORKSPACE_DIR` instead.
+
+Docker Sandboxes substitutes `${{ kit.env.NAME }}` once, when it creates the
+sandbox. `kit.env` reads the final container environment, independently of a
+hook's `env` list.
+
 ## Set workload compute requirements
 
 Set the workload's default CPU and memory allocation with the

content/manuals/ai/sandboxes/customize/kits-v2.md

@@ -488,7 +488,9 @@ assets from `files/home/`.
 
 ### startup
 
-Runs at every sandbox start. String array, not interpreted by a shell.
+Runs at every sandbox start. String array, not interpreted by a shell. A
+`$WORKSPACE_DIR` reference in the array is passed unchanged. To expand it, run
+the command through a shell, for example `["sh", "-c", "..."]`.
 
 | Field         | Default  | Description                         |
 | ------------- | -------- | ----------------------------------- |
@@ -521,7 +523,7 @@ Files written at sandbox start, with runtime substitution.
 | Field           | Default  | Description                                               |
 | --------------- | -------- | --------------------------------------------------------- |
 | `path`          | —        | Absolute container path.                                  |
-| `content`       | —        | File content. `${WORKDIR}` expands to the workspace path. |
+| `content`       | —        | File content. Write `${WORKDIR}` for the workspace path. |
 | `mode`          | `"0644"` | File permissions in octal.                                |
 | `onlyIfMissing` | `false`  | Skip if the file already exists.                          |
 
@@ -530,6 +532,21 @@ path must be writable by that user. To write to a root-owned path such as
 `/etc`, use an `install` command, which runs as root by default. Set ownership
 in the install command if the agent needs to modify the file later.
 
+Write `${WORKDIR}` in `content` and `$WORKSPACE_DIR` in commands. Three names
+look alike and mean different things:
+
+| Name            | What it is                                                    | Where it applies                                 |
+| --------------- | ------------------------------------------------------------- | ------------------------------------------------ |
+| `${WORKDIR}`    | Placeholder for the workspace path                            | `setup.files[].content` only                     |
+| `WORKSPACE_DIR` | Environment variable set by the runtime to the workspace path | Shell commands, and the agent                    |
+| `WORKDIR`       | The template image's Dockerfile working directory             | Where commands start, see [install](#install)    |
+
+The runtime replaces `${WORKDIR}` when it creates the sandbox, only inside
+`content`, never in `path` or in commands. `WORKSPACE_DIR` is an environment
+variable, so a `$WORKSPACE_DIR` reference expands only when a shell runs the
+command. `install` strings run through `sh -c`. `startup` arrays run without a
+shell. A Dockerfile `WORKDIR` doesn't define an environment variable.
+
 ### Shell initialization and service logs
 
 With Docker templates, append shell initialization to
@@ -792,6 +809,7 @@ content from sandbox initialization, and declare runtime capabilities:
 | Automatic `files/home/` and `files/workspace/` injection | Dockerfile `COPY`, with lifecycle hooks for destinations provided by runtime mounts |
 | `permissions.network` and `credentials` | Network-policy and credential capabilities |
 | `agentInstructions` | Agent-context capability |
+| `${WORKDIR}` in `setup.files[].content` | `${{ kit.env.WORKSPACE_DIR }}` in lifecycle [`files` content](/manuals/ai/sandboxes/customize/author/_index.md#generated-files) |
 
 Follow the [v3 authoring guidance](/manuals/ai/sandboxes/customize/author/_index.md)
 when converting runtime setup and capability declarations.