docs: add shell environment customization to kit examples

Show how to source a tool's init script as part of a kit, using SDKMAN!
as a concrete example for version managers like sdkman and nvm. The
primitives (install commands) already support this, but the pattern
wasn't illustrated anywhere, which made it hard to answer questions
about getting version managers working in a sandbox.

Append to /etc/sandbox-persistent.sh — the sandbox's established
persistent environment file, sourced for both interactive and
non-interactive shells — to match the convention documented in the FAQ
for custom environment variables.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dvdksn

content/manuals/ai/sandboxes/customize/kit-examples.md

@@ -1,7 +1,7 @@
 ---
 title: Kit examples
 linkTitle: Examples
-description: Copy-and-adapt spec.yaml snippets for common mixin and agent kit patterns — static files, install commands, background services, initFiles, Claude Code skills, and agent forks.
+description: Copy-and-adapt spec.yaml snippets for common mixin and agent kit patterns — static files, install commands, shell customization, background services, initFiles, Claude Code skills, and agent forks.
 keywords: sandboxes, sbx, kits, mixins, examples, patterns, skills
 weight: 25
 ---
@@ -72,6 +72,55 @@ step should run as the agent user — for example, `npm install -g`
 against a user-scoped prefix, or anything that writes to
 `/home/agent/`.
 
+## Customize the shell environment
+
+Some tools install into a versioned directory and expect you to source
+an init script from your shell profile so their commands land on `PATH`.
+Version managers like [SDKMAN!](https://sdkman.io/) and
+[nvm](https://github.com/nvm-sh/nvm) follow this pattern. To make the
+tool available in every shell, append the source line to
+`/etc/sandbox-persistent.sh` in an install command.
+
+`/etc/sandbox-persistent.sh` is the sandbox's persistent environment
+file. It's sourced before every bash invocation — interactive shells and
+non-interactive ones, including agents started with `sbx run` and
+commands run with `sbx exec`. Appending here makes the tool available to
+the agent regardless of how its shell is launched. The same file is where
+you'd set a custom environment variable; see the
+[FAQ](../faq.md#how-do-i-set-custom-environment-variables-inside-a-sandbox).
+
+```yaml {title="sdkman/spec.yaml"}
+schemaVersion: "1"
+kind: mixin
+name: sdkman
+displayName: SDKMAN!
+description: Java SDK manager available in every shell
+
+commands:
+  install:
+    - command: "curl -fsSL https://get.sdkman.io | bash"
+      user: "1000"
+      description: Install SDKMAN!
+    - command: |
+        cat >> /etc/sandbox-persistent.sh <<'EOF'
+        export SDKMAN_DIR="$HOME/.sdkman"
+        [ -s "$SDKMAN_DIR/bin/sdkman-init.sh" ] && source "$SDKMAN_DIR/bin/sdkman-init.sh"
+        EOF
+      description: Source SDKMAN! for every shell
+```
+
+The install step runs as `user: "1000"` so the tool lands under
+`/home/agent/`. The append step runs as root (the default), since
+`/etc/sandbox-persistent.sh` is a system file. The `$HOME` in the
+appended lines resolves per user at source time, so the agent user finds
+its own install. Append to the file rather than overwriting it —
+the sandbox relies on its existing contents.
+
+Append only the init script, not the tool's tab-completion script.
+Because `/etc/sandbox-persistent.sh` is sourced before every command,
+completion scripts — which rely on variables that exist only during
+completion — can break non-interactive shells that agents rely on.
+
 ## Install an internal CA certificate
 
 If your organization uses a proxy that inspects HTTPS traffic, install