feat(example): start DSH's folder picker on the persisted workspace (#36)

The directory picker has no start-path setting: it lists $HOME whenever it
opens. With the image default HOME=/home/node the folder explorer started on
a throwaway directory, so point HOME at the PVC-backed /workspace in both
sandbox templates. `~` and $HOME-relative tool caches/config follow; DSH_HOME
stays /home/node/.dsh, so sessions, config and credentials are unaffected.

Document the trade-off in the image contract and both examples, add
troubleshooting for sandboxes whose pod env was stamped before the change,
and assert HOME/~ in the e2e walkthrough.

Co-authored-by: SREDevOpsAgents <agents@sredevops.org>

examples/minimal-single-tenant/README.md

@@ -101,6 +101,25 @@ kubectl -n dsh-demo port-forward "pod/$SB" 18081:3080
 > example or a reachable Service instead; see
 > [optional hardening](../dsh-agents-as-a-service/docs/optional-hardening.md).
 
+## Folder picker and the workspace
+
+The template sets `HOME=/workspace`. DSH's directory picker (the folder explorer
+used to choose a workspace) has no start-path setting: it lists `$HOME` when it
+opens, so with the image default (`/home/node`) it would start on a directory that
+is not persisted. Pointing `HOME` at the PVC-backed workspace makes the picker
+open there (labelled *Home* in its breadcrumbs) and makes `~` in agent commands
+resolve to `/workspace`. The trade-off is that `$HOME`-relative tool caches and
+config (`.cache`, `.config`, `.local`, `.npm`, `.agents`) are written into the
+workspace on the PVC. DSH state is unaffected: `DSH_HOME` stays
+`/home/node/.dsh`. The rationale and the list of affected paths are in
+[`10-sandboxtemplate.yaml`](../dsh-agents-as-a-service/manifests/10-sandboxtemplate.yaml).
+
+Verify inside a running sandbox:
+
+```bash
+kubectl -n dsh-demo exec "$SB" -- printenv HOME   # /workspace
+```
+
 ## Network policy and optional hardening
 
 The template omits `networkPolicyManagement`, so the agent-sandbox controller

examples/minimal-single-tenant/manifests/sandbox-template.yaml

@@ -69,6 +69,21 @@ spec:
                 name: dsh-provider-keys-extra
                 optional: true
           env:
+            # Point the OS home at the persisted agent workspace. DSH's
+            # directory picker (the folder explorer used to choose a workspace)
+            # lists $HOME when it opens and has no start-path setting, so with
+            # the image default (/home/node, not on a volume) it would open on a
+            # throwaway directory. /workspace is the PVC-backed WORKDIR, so the
+            # picker opens on the tree that survives suspend/resume, and `~` in
+            # agent commands resolves there. Trade-off: tools that keep caches
+            # or config under $HOME (npm/pnpm, uv, git, gh, DSH's global
+            # ~/.agents instructions and skills) write dotfiles onto the PVC
+            # inside the agent workspace. DSH_HOME is explicit
+            # (/home/node/.dsh), so sessions, config and credentials are
+            # unaffected. Rationale in full at
+            # examples/dsh-agents-as-a-service/manifests/10-sandboxtemplate.yaml.
+            - name: HOME
+              value: /workspace
             # Empty => DSH derives links from the request Host. Keep it empty
             # when fronting the sandbox with a proxy/gateway.
             - name: DSH_PUBLIC_URL