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

[mdelapenya]

Description

Kit authors mix up three names that share a word: the v2 ${WORKDIR} placeholder, the WORKSPACE_DIR environment variable, and the image's Dockerfile WORKDIR. The v2 reference only said that ${WORKDIR} "expands to the workspace path", which reads as if it were a variable, and nothing on the page said where WORKSPACE_DIR is available.

This change, on the Kits v2 page:

• rewords the content row of setup.files so ${WORKDIR} is described as a literal replaced at creation
• adds a short table after files naming the three things and where each applies, and states that there is no WORKDIR environment variable in the sandbox
• notes under install that the workspace path is available as WORKSPACE_DIR

On the "Author kits" page, under "Pass environment variables to hooks", one paragraph says that v3 lifecycle files content reads variables through ${{ kit.env.NAME }} (for example ${{ kit.env.WORKSPACE_DIR }}) and that plain $VAR stays literal, since v3 has no ${WORKDIR} placeholder. That matches the public v3 kit spec.

Verified behaviour from the sbx runtime: the placeholder is replaced only in setup.files[].content; WORKSPACE_DIR is set in the container and visible to install and startup commands and to the agent.

Related issues or tickets

• Inconsistent workspace variable names for kits sbx-releases#570

Reviews

• Technical review
• Editorial review

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	42c38b4
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6abf9e3a1f02f40008537c3e
😎 Deploy Preview	https://deploy-preview-26230--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[dvdksn]

The distinction is useful, but the explanation needs a clearer sequence. Please lead with what authors should write in generated files versus shell commands, then explain when substitution happens.

On the v3 page, give generated files their own subsection and replace “the same variables” with “container environment variables.” kit.env reads the final container environment, independently of a hook’s env list. Replace “stay literal” with “are written unchanged, without substituting their values.”

On the v2 page, consolidate the repeated placeholder explanation, qualify the shell syntax for startup commands, and move the v3 comparison to the migration section. Also replace the absolute claim that no WORKDIR environment variable exists with the narrower explanation that Dockerfile WORKDIR does not define one.

Generated by Codex

[mdelapenya]

Thanks for the pass, all five taken in 42c38b4.

Both pages now open with what to write (${WORKDIR} in v2 content, ${{ kit.env.NAME }} in v3 files, shell syntax such as $WORKSPACE_DIR in commands) and only then say when the substitution happens. The v3 page has a "Generated files" subsection with your wording: container environment variables, kit.env reads the final container environment independently of a hook's env list, and unsubstituted references are written unchanged. I checked that against the spec's kit.env section before writing it.

On the v2 page the placeholder is stated once, the startup section says a $WORKSPACE_DIR reference in the array is passed unchanged unless the command runs through a shell, the WORKDIR claim is narrowed to what a Dockerfile WORKDIR doesn't define, and the v3 comparison moved to the "Move an environment to v3" table as a new row pointing at the new subsection.

One call you may want to check: I dropped the WORKSPACE_DIR sentence under install, since the consolidated text covers it and install already says it runs through sh -c.