[bot:cli-maxxing] fix multi-shell + mid-script PATH bugs (2026-04-17)

Fresh-install reliability fixes surfaced on marina@Mac install where
modern zsh-default macOS + just-installed brew/nvm couldn't be seen by
downstream curl|bash steps in the pipeline.

BUG A — mid-script PATH not re-sourced: install.sh now defines
reload_path() and refreshes brew shellenv + nvm + ~/.local/bin between
Step 1 and the downstream steps. Every child step + bonus + update.sh
has a defensive source_runtime_path() at the top so they also work
standalone.

BUG B — shell mismatch on modern macOS: step-1 now writes shell
integrations to BOTH .zshrc/.bashrc AND .zprofile/.bash_profile on
macOS, matching Homebrew's own install pattern. SHELL_RCS +
SHELL_PROFILES arrays replace the single SHELL_RC scalar. Linux
behavior preserved via getent passwd detection.

Files changed (14):
- install.sh                        — reload_path() + breadcrumb
                                      mkdir + missing-step reporter
- step-1/step-1-install.sh          — dual-shell integration + crumb
- step-2/step-2-install.sh          — source_runtime_path + crumb
                                      + pipx for xlsx2csv (PEP 668)
- step-3/step-3-install.sh          — source_runtime_path + crumb
                                      + memory self-test probe fix
- step-6/step-6-install.sh          — source_runtime_path + crumb
- step-8/step-8-install.sh          — source_runtime_path + crumb
- step-9/step-9-install.sh          — source_runtime_path + crumb
                                      + claude nvm-glob fallback
- step-final/step-final-install.sh  — source_runtime_path + crumb
                                      + cbrain in Optional section
- bonus-arc/bonus-arc.sh            — source_runtime_path + crumb
- bonus-ghostty/bonus-ghostty.sh    — source_runtime_path + crumb
- update.sh                         — source_runtime_path + refresh
- uninstall.sh                      — multi-shell cleanup (all 4 rcs)
- README.md                         — Troubleshooting section added
- CHEATSHEET.md                     — Reset PATH recovery block

Breadcrumbs land in ~/.cli-maxxing/step-N.done (+ ghostty.done,
arc.done). install.sh reports which expected crumbs are missing and
recommends a terminal-restart + re-run. step-6/step-8 crumbs are
intentionally excluded from the top-level report (those are invoked
separately by users, not direct children of install.sh).

Shellcheck clean at warning+. Security audit: no must-fix findings.

Co-Authored-By: claude-flow <ruv@ruv.net>

Author: fidgetcoding

CHEATSHEET.md

@@ -236,6 +236,44 @@ These are available in your terminal after Step 3 installs the Ruflo CLI.
 
 ---
 
+## Reset PATH (stuck install)
+
+If you ran the installer, opened a fresh terminal, and `claude --version` still says "command not found" — your `~/.zshrc` is probably missing the lines that wire Homebrew, nvm, `~/.local/bin`, and the cli-maxxing aliases together. This is the exact block we used on marina@Mac to unstick her install. Paste it verbatim into your terminal — it creates `~/.zshrc` if it doesn't exist, appends the four things that need to be on PATH, then sources it and verifies `claude` works.
+
+```bash
+cat > ~/.zshrc <<'EOF'
+# Homebrew (Apple Silicon default; also works on Intel via brew --prefix)
+if [ -x /opt/homebrew/bin/brew ]; then
+  eval "$(/opt/homebrew/bin/brew shellenv)"
+elif [ -x /usr/local/bin/brew ]; then
+  eval "$(/usr/local/bin/brew shellenv)"
+fi
+
+# nvm (Node Version Manager)
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
+
+# User-local binaries (cbrain, ctg, cbraintg land here)
+export PATH="$HOME/.local/bin:$PATH"
+
+# cli-maxxing aliases
+alias cskip='claude --dangerously-skip-permissions'
+alias cc='claude'
+alias ccr='claude --resume'
+alias ccc='claude --continue'
+EOF
+
+source ~/.zshrc
+claude --version
+```
+
+**What to expect:** `claude --version` should print something like `2.1.112 (Claude Code)`. If it does, you're unstuck — close this terminal, open a fresh one, and continue from where you left off. If it still errors, the issue is upstream of PATH (Claude Code itself didn't install, or Node is broken) — paste the error into a `cskip` session and Claude can diagnose.
+
+> **Using bash instead of zsh?** Swap `~/.zshrc` for `~/.bashrc` in the block above. Everything else is identical.
+
+---
+
 ## Tips
 
 - Claude remembers context within a session. If it's getting confused, use `/compact` to reset.

README.md

@@ -203,25 +203,21 @@ When Claude is running in any terminal, you can press **Shift+Tab** to switch be
 
 After the script finishes, you need to activate the tools that were just installed. Do these three things in order:
 
-**1. Reload your shell config** — copy and paste this, then hit Enter:
+**1. Close this terminal and open a new one.**
 
-```bash
-source ~/.zshrc
-```
-
-> On Linux or if you use bash, run `source ~/.bashrc` instead.
+This is the most important step. Homebrew, nvm, and the new shell aliases only load when a fresh shell starts. If you skip this, `claude` and `cskip` won't be found even though they're installed. Fully close the Terminal window (Cmd+Q on Mac works too) and open a new one.
 
-**2. Close the terminal window and reopen it.**
-
-**3. Verify Claude is working:**
+**2. Verify Claude is working** — in the new terminal, run:
 
 ```bash
 claude --version
 ```
 
-If you see a version number, you're good. If not, repeat steps 1 and 2.
+You should see a version number like `2.1.112 (Claude Code)`. If you see that, you're good.
+
+> If `claude --version` says "command not found," try `source ~/.zshrc` (or `source ~/.bashrc` if you're on Linux or still using bash). macOS uses zsh by default since Catalina, so `.zshrc` is almost always the right one. If that still doesn't work, see the [Troubleshooting](#troubleshooting) section below — specifically "I ran the installer but `claude` command is not found."
 
-**4. Exit and switch to auto-approve mode:**
+**3. Exit and switch to auto-approve mode:**
 
 Press **Ctrl+C** to exit Claude, then run `cskip` to continue with auto-approve mode (Claude runs without asking permission for each action). This is the recommended way to work through the remaining setup steps.
 
@@ -1009,6 +1005,66 @@ Setup is complete. Head to **[You're Ready](#youre-ready)** below for your daily
 
 [Back to top](#quick-nav)
 
+### I ran the installer but `claude` command is not found
+
+First install has a catch: the installer adds Homebrew, nvm, and the shell aliases to your config files, but those only load when a brand new shell starts. On top of that, the script may have been running in bash while your default shell on modern macOS is zsh — so even `source`-ing the file the script wrote can miss.
+
+**Fix:**
+1. Fully close the terminal window (Cmd+Q on Mac works too).
+2. Open a fresh terminal.
+3. Run `claude --version`. You should see something like `2.1.112 (Claude Code)`.
+
+If it's still missing after a fresh terminal, paste the **Reset PATH (stuck install)** block from [CHEATSHEET.md](CHEATSHEET.md#reset-path-stuck-install) — it rewires `~/.zshrc` with Homebrew shellenv, nvm, `~/.local/bin`, and the four aliases in one shot.
+
+### Some steps say "Homebrew not found" during install
+
+Step 1 installs Homebrew mid-pipeline and the downstream steps in the same shell session don't see it yet — the installer hadn't refreshed PATH for subsequent commands. Known issue, fixed 2026-04-17.
+
+**Fix:** close the terminal, open a fresh one, and re-run the installer:
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main/install.sh)
+```
+It's idempotent — anything already installed gets skipped.
+
+### I see the zsh/bash shell prompt change after install
+
+The installer detects your default shell and writes integrations accordingly. On modern macOS, zsh is the default even if `/etc/passwd` still says bash (Terminal.app overrides passwd with the "default login shell" preference), so you may notice your prompt looks different after a fresh terminal.
+
+**Fix:** confirm which shell you're actually in:
+```bash
+echo $SHELL
+```
+If you want your passwd entry to match what Terminal.app uses, run:
+```bash
+chsh -s /bin/zsh
+```
+This is optional — everything works fine either way. The installer writes to both `~/.zshrc` and `~/.bashrc` so both shells pick up the aliases.
+
+### xlsx2csv failed to install
+
+Python 3.9 (the macOS default) ships with PEP 668 restrictions that block `pip install` into the system Python. The installer now uses `pipx` to work around this.
+
+**Fix:** re-run Step 2:
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main/step-2/step-2-install.sh)
+```
+If it's still failing, install manually:
+```bash
+brew install pipx
+pipx install xlsx2csv
+```
+
+### I want to completely remove everything
+
+Run the uninstall script:
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main/uninstall.sh)
+```
+
+This removes the cli-maxxing aliases (`cskip`, `cc`, `ccr`, `ccc`), the `ctg`/`cbrain`/`cbraintg` scripts in `~/.local/bin/`, all MCP servers, skills, and breadcrumbs this setup dropped. See the [Uninstall](#uninstall) section below for the full list.
+
+It does **not** remove Homebrew, nvm, Node.js, or Claude Code itself — those are general-purpose tools you might use outside of cli-maxxing. The uninstall script will show you how to remove them manually if you want a completely clean machine.
+
 ### Telegram: pressing Enter skips setup
 
 This is intentional. If you press Enter without pasting a token, the script skips Telegram setup and continues. You can always re-run Step 8 later when you have your bot token ready.

bonus-arc/bonus-arc.sh

@@ -19,6 +19,27 @@ success() { echo -e "${GREEN}[OK]${NC} $1"; }
 warn()    { echo -e "${YELLOW}[WARN]${NC} $1"; }
 fail()    { echo -e "${RED}[FAIL]${NC} $1"; exit 1; }
 
+# -----------------------------------------------------------------------------
+# Source runtime PATH (brew, nvm, ~/.local/bin) so a freshly-installed brew
+# from Step 1 is visible without requiring a new shell.
+# Idempotent: multiple brew shellenv evals are safe, nvm re-source is safe,
+# and the PATH guard prevents duplicate $HOME/.local/bin entries.
+# -----------------------------------------------------------------------------
+source_runtime_path() {
+    for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew /home/linuxbrew/.linuxbrew/bin/brew; do
+        if [ -x "$brew_bin" ]; then
+            eval "$("$brew_bin" shellenv)"
+            break
+        fi
+    done
+    export NVM_DIR="$HOME/.nvm"
+    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+    case ":$PATH:" in
+        *":$HOME/.local/bin:"*) ;;
+        *) export PATH="$HOME/.local/bin:$PATH" ;;
+    esac
+}
+
 # -----------------------------------------------------------------------------
 # Detect OS
 # -----------------------------------------------------------------------------
@@ -97,9 +118,13 @@ main() {
     echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
     echo ""
 
+    source_runtime_path
     detect_os
     install_arc
     print_summary
+
+    mkdir -p "$HOME/.cli-maxxing"
+    touch "$HOME/.cli-maxxing/arc.done"
 }
 
 main "$@"

bonus-ghostty/bonus-ghostty.sh

@@ -19,6 +19,27 @@ success() { echo -e "${GREEN}[OK]${NC} $1"; }
 warn()    { echo -e "${YELLOW}[WARN]${NC} $1"; }
 fail()    { echo -e "${RED}[FAIL]${NC} $1"; exit 1; }
 
+# -----------------------------------------------------------------------------
+# Source runtime PATH (brew, nvm, ~/.local/bin) so a freshly-installed brew
+# from Step 1 is visible without requiring a new shell.
+# Idempotent: multiple brew shellenv evals are safe, nvm re-source is safe,
+# and the PATH guard prevents duplicate $HOME/.local/bin entries.
+# -----------------------------------------------------------------------------
+source_runtime_path() {
+    for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew /home/linuxbrew/.linuxbrew/bin/brew; do
+        if [ -x "$brew_bin" ]; then
+            eval "$("$brew_bin" shellenv)"
+            break
+        fi
+    done
+    export NVM_DIR="$HOME/.nvm"
+    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+    case ":$PATH:" in
+        *":$HOME/.local/bin:"*) ;;
+        *) export PATH="$HOME/.local/bin:$PATH" ;;
+    esac
+}
+
 # -----------------------------------------------------------------------------
 # Detect OS
 # -----------------------------------------------------------------------------
@@ -445,13 +466,17 @@ main() {
     echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
     echo ""
 
+    source_runtime_path
     detect_os
     install_ghostty
     install_font
     configure_ghostty
     configure_link_opener
     install_window_tiling
     print_summary
+
+    mkdir -p "$HOME/.cli-maxxing"
+    touch "$HOME/.cli-maxxing/ghostty.done"
 }
 
 main "$@"

install.sh

@@ -16,6 +16,36 @@ NC='\033[0m'
 
 BASE_URL="https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main"
 
+# -----------------------------------------------------------------------------
+# reload_path — re-source brew + nvm into the current shell so chained child
+# steps in this pipeline can find node, npm, brew, etc. Needed because Step 1
+# installs brew/nvm mid-run and the parent shell otherwise never picks them up.
+# -----------------------------------------------------------------------------
+reload_path() {
+  # brew — first found wins
+  local brew_bin
+  for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew /home/linuxbrew/.linuxbrew/bin/brew; do
+    if [ -x "$brew_bin" ]; then
+      eval "$("$brew_bin" shellenv)"
+      break
+    fi
+  done
+
+  # nvm — source if installed
+  export NVM_DIR="$HOME/.nvm"
+  # shellcheck disable=SC1091
+  [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+  # ~/.local/bin — prepend idempotently
+  case ":$PATH:" in
+    *":$HOME/.local/bin:"*) : ;;
+    *) export PATH="$HOME/.local/bin:$PATH" ;;
+  esac
+}
+
+# Breadcrumb dir — child step scripts touch step-N.done here on success.
+mkdir -p "$HOME/.cli-maxxing"
+
 echo ""
 echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo -e "${BLUE}  CLI Maxxing — Install${NC}"
@@ -27,6 +57,9 @@ echo ""
 echo -e "${YELLOW}>>> Step 1 — Get Claude Running${NC}"
 echo ""
 curl -fsSL "$BASE_URL/step-1/step-1-install.sh" | bash
+# BUG A fix: Step 1 installs brew+nvm; re-source them into this shell so the
+# remaining curl|bash steps (Ghostty/Arc/2/3/9/final) can actually find them.
+reload_path
 echo ""
 
 # Bonus — Ghostty Terminal (optional, won't reinstall if already present)
@@ -71,6 +104,26 @@ echo -e "${GREEN}  Core install complete.${NC}"
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""
 
+# Breadcrumb check — list any expected steps that did NOT touch their .done file.
+EXPECTED_CRUMBS=(step-1 step-2 step-3 step-9 step-final ghostty arc)
+MISSING_CRUMBS=()
+for crumb in "${EXPECTED_CRUMBS[@]}"; do
+  if [ ! -f "$HOME/.cli-maxxing/${crumb}.done" ]; then
+    MISSING_CRUMBS+=("$crumb")
+  fi
+done
+
+if [ "${#MISSING_CRUMBS[@]}" -gt 0 ]; then
+  echo -e "${YELLOW}⚠️  Some steps did not complete. This usually happens on the first install${NC}"
+  echo -e "${YELLOW}   when a new terminal hasn't loaded brew + node yet.${NC}"
+  echo -e "${YELLOW}   → Close this terminal, open a new one, and re-run:${NC}"
+  echo -e "${YELLOW}     bash <(curl -fsSL https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main/install.sh)${NC}"
+  echo -e "${YELLOW}   The script is idempotent and will resume.${NC}"
+  echo ""
+  echo -e "${YELLOW}   Missing: ${MISSING_CRUMBS[*]}${NC}"
+  echo ""
+fi
+
 echo "  Available commands: cskip, ctg, cc, ccr, ccc"
 echo "  Available skills:   /rswarm, /rmini, /rhive, /w4w, /safetycheck, /gitfix, get-api-docs (auto-triggered)"
 echo "  Swarm tiers:        /rswarm{1,2,3,max}, /rmini{1,2,3,max} — 1=think, 2=think hard, 3=think harder, max=ultrathink"