diff --git a/uw b/uw
index b21cad879..02b34835f 100755
--- a/uw
+++ b/uw
@@ -903,6 +903,7 @@ run_setup() {
     echo "Usage:"
     echo "  ./uw build          Build underworld3"
     echo "  ./uw test           Run tests"
+    echo "  ./uw shell          Open a shell in this env ($new_env)"
 
     # Show Jupyter info
     case "$new_env" in
@@ -917,6 +918,10 @@ run_setup() {
             ;;
     esac
     echo ""
+    echo "Note: a bare 'pixi shell' / 'pixi run' uses pixi's lightweight 'default'"
+    echo "      env, which lacks dev tools (nodejs, claude, linters, docs)."
+    echo "      Use './uw shell' (or 'pixi shell -e $new_env') to activate this env."
+    echo ""
     echo "For VS Code / IDE Jupyter kernels, set pixi environment to: $new_env"
 }
 
@@ -993,7 +998,7 @@ COMMANDS
       ./uw test --help              Show all test options
 
   Development:
-    shell               Interactive pixi shell
+    shell               Interactive pixi shell in the configured env (avoid bare 'pixi shell')
     jupyter [args]      Run jupyter (add --worktree NAME to open a worktree)
     format              Run black
     type-check          Run mypy
@@ -1584,6 +1589,10 @@ case "${1:-}" in
         echo "Run './uw build' to rebuild underworld3"
         ;;
     shell)
+        # Activate the env stored in .pixi-env, not pixi's literal 'default'.
+        # Bare `pixi shell` ignores .pixi-env and falls back to the env named
+        # 'default' in pixi.toml, which is the lightweight conda-forge PETSc
+        # env without nodejs / dev tools — a common first-timer trap.
         shift
         exec $PIXI shell -e "$(get_env)" "$@"
         ;;