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

chsh is blocked on the corp dev VM (PAM-level restriction at user-
provisioning time). Drop the sudo chsh -s call from 20-zsh.sh and
append a guarded `exec zsh -l` block to ~/.bashrc instead — same UX
without needing infra escalation, also matches the legacy WSL setup
pattern in 02-wsl-terminal-setup.md.

The hand-off is guarded by `case $- in *i*)` so non-interactive bash
flows (scp, rsync, cron) are unaffected, and by a ZSH_VERSION absence
check to prevent re-exec loops.

Main doc and README table descriptions updated to match.

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.