docs(setup): use ~/.bashrc hand-off instead of chsh for zsh switch (#221)

## Summary

Follow-up fix on [#220](#220). The corp infra locks the default shell at user-provisioning time on the dev VM (`10.100.201.21`) — `chsh` is denied at the PAM level, so the `sudo chsh -s` block in [`20-zsh.sh`](docs/setup/scripts/20-zsh.sh) fails on every fresh VM.

Switch to the `~/.bashrc` exec-zsh hand-off — the same proven pattern used in the legacy [`02-wsl-terminal-setup.md`](docs/setup/02-wsl-terminal-setup.md). UX-identical for the dev, zero infra escalation required.

## What lands

| File | Change |
| --- | --- |
| `docs/setup/scripts/20-zsh.sh` | Drop the `sudo chsh -s` block. Append a guarded `exec zsh -l` block to `~/.bashrc` instead, marked with a managed-by comment for idempotency on re-runs. |
| `docs/setup/01-dev-debian-vm-setup.md` | Table row for `20-zsh.sh` updated — "set as default shell" → "`~/.bashrc` (exec zsh on interactive shells — `chsh` is blocked on the corp VM)". |
| `docs/setup/README.md` | Same descriptor adjustment. |

## The hand-off block

```bash
# Managed by docs/setup/scripts/20-zsh.sh — apf-portal zsh hand-off.
# Hand off to zsh on interactive shells. The `case $-` guard avoids
# breaking non-interactive bash (scp, rsync, cron, …), and the
# ZSH_VERSION check prevents an infinite re-exec loop.
case $- in
  *i*)
    if command -v zsh >/dev/null 2>&1 && [ -z "${ZSH_VERSION-}" ]; then
      exec zsh -l
    fi
    ;;
esac
```

Two safety nets in the block:

- **`case $- in *i*)`** — only runs the hand-off when the shell flag set contains `i` (interactive). `scp` / `rsync` / non-interactive ssh executions go through bash and are not hijacked.
- **`[ -z "${ZSH_VERSION-}" ]`** — `ZSH_VERSION` is set by zsh itself; if it's already set we're already in zsh and a re-exec would loop.

## Test plan

- [ ] On the dev VM, run `20-zsh.sh` on a fresh state: bash, no existing `~/.bashrc` zsh hand-off → script exits without `chsh` error, `~/.bashrc` gets the block appended, `exit` + reconnect lands in zsh.
- [ ] Re-run `20-zsh.sh` → reports `↪ skip zsh hand-off already in ~/.bashrc` (idempotency).
- [ ] `scp some-file vm-dev:/tmp/` from the workstation still works (non-interactive bash not hijacked).
- [x] `pnpm exec prettier --check` clean on the touched markdown files.
- [x] `bash -n docs/setup/scripts/20-zsh.sh` (syntax check) clean.

## Why not amend #220

#220 has already merged. Squash-merge collapsed it to `8a04540` on main; a force-push to amend would rewrite that commit and break anyone who's pulled it. The fix lands as a separate commit on the same setup-doc family.

---------

Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #221

docs/setup/scripts/20-zsh.sh

@@ -9,15 +9,33 @@ require_not_root
 
 apt_install zsh
 
-# Make zsh the default shell for $USER (idempotent).
-current_shell="$(getent passwd "$USER" | cut -d: -f7)"
-zsh_path="$(command -v zsh)"
-if [[ "$current_shell" != "$zsh_path" ]]; then
-  log "Setting zsh as default shell for $USER (sudo will prompt)."
-  sudo chsh -s "$zsh_path" "$USER"
-  ok "Default shell set to $zsh_path. Takes effect on next login."
+# Hand off to zsh from ~/.bashrc rather than `chsh -s`. The corp infra
+# locks the default shell at user-provisioning time and `chsh` is denied
+# (the standard PAM-level restriction). The .bashrc hand-off achieves
+# the same UX without needing infra escalation, and it's compatible with
+# both interactive SSH sessions and VSCode Remote-SSH's bash bootstrap.
+BASHRC="$HOME/.bashrc"
+[[ -f "$BASHRC" ]] || touch "$BASHRC"
+MARKER='# Managed by docs/setup/scripts/20-zsh.sh — apf-portal zsh hand-off.'
+
+if grep -qF "$MARKER" "$BASHRC"; then
+  skip "zsh hand-off already in $BASHRC."
 else
-  skip "zsh already default shell."
+  cat >> "$BASHRC" <<'EOF'
+
+# Managed by docs/setup/scripts/20-zsh.sh — apf-portal zsh hand-off.
+# Hand off to zsh on interactive shells. The `case $-` guard avoids
+# breaking non-interactive bash (scp, rsync, cron, …), and the
+# ZSH_VERSION check prevents an infinite re-exec loop.
+case $- in
+  *i*)
+    if command -v zsh >/dev/null 2>&1 && [ -z "${ZSH_VERSION-}" ]; then
+      exec zsh -l
+    fi
+    ;;
+esac
+EOF
+  ok "Patched $BASHRC to exec zsh on interactive shells."
 fi
 
 # Oh My Zsh — install with RUNZSH=no to avoid spawning zsh during the script.