docs: add shell environment customization to kit examples

[dvdksn]

Summary

The kit examples page covered tool installation and credential injection but never showed how to customize the shell environment — sourcing a tool's init script so its command lands on PATH in every shell. This adds a "Customize the shell environment" section, documents install-command gotchas that apply to any download-based kit, and fixes a Vale rule that tripped on product names ending in !.

Two commits:

1. docs: add shell environment customization to kit examples

   • Worked example uses nvm — it installs cleanly in a default sandbox (reachable egress, no extra packages), so the snippet works as copy-pasted. It appends to /etc/sandbox-persistent.sh — the sandbox's persistent environment file, sourced for both interactive and non-interactive shells — matching the FAQ convention for custom env vars, and cross-links it.
   • Install-command caveats added to the "Install a tool" section: deny-by-default egress can silently block downloads; curl … | bash masks those failures (exits 0, sandbox reports success while nothing installed); install steps run under sh, not bash; some tools need base packages such as zip/unzip.
   • The first draft's sdkman snippet was dropped as the primary example because it fails silently in a default sandbox (blocked get.sdkman.io egress + missing zip/unzip). Those failure modes are now documented as general install-command guidance, with sdkman as the illustration.

2. vale: exempt product names ending in '!' from Docker.Exclamation

   • Docker.Exclamation flags any word followed by ! in bare prose, tripping on product names like SDKMAN!. Link text and code were already exempt via IgnoredScopes, but bare prose was not. Added an exceptions list (matched against the word before the !) so genuine exclamations are still caught.

Learnings

• /etc/sandbox-persistent.sh is the canonical persistence point for shell env in sandboxes — sourced before every bash invocation (interactive and non-interactive), so it reaches agents started with both sbx run and sbx exec. A ~/.bashrc edit only covers interactive shells.
• curl … | bash in an install command masks download failures: the pipe's exit status is bash's, and bash exits 0 on empty input, so a domain blocked by the deny-by-default egress policy still produces a "✓ Created" sandbox with nothing installed. Download-then-run (-o file && bash file) surfaces the failure.
• Kit install commands run under sh (dash), not bash — bash builtins like source fail with sh: source: not found unless piped to bash or wrapped in bash -c.
• nvm won't activate while NPM_CONFIG_PREFIX is set (the base image sets it for its system Node); unset NPM_CONFIG_PREFIX before sourcing nvm.sh.
• Vale's exceptions for an existence rule with nonword: true are matched against the word preceding the non-word token, not the full match — so a product name ending in ! is listed without the ! (SDKMAN, not SDKMAN!). Go's RE2 engine also has no lookahead, so token regexes can't use (?=…).

Generated by Claude Code

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	77a349b
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a327b0d0e52b1000841194a
😎 Deploy Preview	https://deploy-preview-25374--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.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION