feat: Enhanced PATH detection for Node.js version managers and improved documentation

- Implemented comprehensive PATH detection with fallback mechanisms
- Added support for asdf, nvm, volta, fnm, and other version managers
- Updated documentation to recommend pipx over pip for CLI installation
- Removed all brainstorm command references (deprecated feature)
- Fixed pipx environment detection and helpful error messages
- Resolved Issues #5, #6, #7

Co-authored-by: GitHub Contributors

Author: hyunjae-labs

CHANGELOG.md

@@ -48,7 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - security-engineer, performance-engineer, quality-engineer, refactoring-expert
   - requirements-analyst, root-cause-analyst, python-expert, technical-writer, learning-guide
 - **NEW BEHAVIORAL MODES**: 5 intelligent workflow adaptation modes
-  - Brainstorming Mode for collaborative discovery and requirements exploration
+  - analysis mode for collaborative discovery and requirements exploration
   - Introspection Mode for meta-cognitive analysis and reasoning optimization
   - Orchestration Mode for intelligent tool selection and resource efficiency
   - Task Management Mode for hierarchical organization with persistent memory

Docs/Developer-Guide/testing-debugging.md

@@ -3352,7 +3352,7 @@ class TestEndToEndWorkflows:
         session_manager = SessionManager()
         session = session_manager.create_session('test-project')
 
-        # 2. Requirements discovery (brainstorming mode)
+        # 2. Requirements discovery (analysis mode)
         brainstorm_task = TaskContext(
             input_text="build e-commerce platform",
             session_id=session.id

Docs/Getting-Started/installation.md

@@ -8,8 +8,16 @@ SuperGemini installs in under 2 minutes with an interactive installer. The proce
 
 ## Quick Start 🚀
 
-**Method 1: Python (Recommended)**
+**Method 1: pipx (Recommended for CLI tools)**
 ```bash
+# Install with pipx for isolated environment
+pipx install SuperGemini
+SuperGemini install
+```
+
+**Method 1b: pip (Traditional Python)**
+```bash
+# Install with pip (may cause dependency conflicts)
 pip install SuperGemini
 SuperGemini install
 ```
@@ -34,7 +42,7 @@ SuperGemini install --dry-run
 |-------------|--------------|--------|----------|
 | **🖥️ Installation** | Terminal/CMD | `SuperGemini [command]` | `SuperGemini install` |
 | **🔧 Configuration** | Terminal/CMD | `python3 -m SuperGemini` | `python3 -m SuperGemini --version` |
-| **💬 Development** | Gemini CLI | `/sg:[command]` | `/sg:brainstorm "idea"` |
+| **💬 Development** | Gemini CLI | `/sg:[command]` | `/sg:analyze "idea"` |
 | **⚡ Workflow** | Gemini CLI | `/sg:[command] --flags` | `/sg:test --coverage` |
 
 > **Important**: Installation commands run in your terminal. Once installed, you'll use `/sg:` commands inside Gemini CLI for development tasks.
@@ -113,8 +121,12 @@ winget install OpenJS.NodeJS
 
 **Choose Your Preferred Method:**
 
-**Python Users:**
+**Python Users (Recommended: pipx):**
 ```bash
+# For CLI tools - isolated environment (recommended)
+pipx install SuperGemini
+
+# Traditional installation
 pip install SuperGemini
 ```
 
@@ -251,7 +263,7 @@ ls ~/.gemini/.gemini.json
 **Try These Commands:**
 ```bash
 # Interactive requirements discovery
-/sg:brainstorm "mobile app idea"
+/sg:analyze "mobile app idea"
 
 # Analyze existing code
 /sg:analyze src/
@@ -264,7 +276,7 @@ ls ~/.gemini/.gemini.json
 ```
 
 **Learning Path:**
-1. Start with `/sg:brainstorm` for project discovery
+1. Start with `/sg:analyze` for project discovery
 2. Use `/sg:analyze` to understand existing code
 3. Try `/sg:implement` for feature development
 4. Explore `/sg:index` for command discovery
@@ -474,7 +486,7 @@ python scripts/validate_pypi_ready.py
 - **Platform**: Linux, macOS, Windows supported
 - **Usage**: Immediate access to 21 commands and 6 behavioral modes
 
-**What's Next**: Your Gemini CLI now has enhanced capabilities. Try `/sg:brainstorm` for your first SuperGemini experience!
+**What's Next**: Your Gemini CLI now has enhanced capabilities. Try `/sg:analyze` for your first SuperGemini experience!
 
 ---
 

Docs/Getting-Started/quick-start.md

@@ -6,19 +6,23 @@
 
 SuperGemini transforms Gemini CLI into a structured development framework with just one installation command. Behind the simple interface, intelligent routing automatically selects the right tools, activates domain experts, and coordinates complex workflows.
 
-**5-Minute Start**: Install → Try `/sg:brainstorm` → Watch the magic happen.
+**5-Minute Start**: Install → Try `/sg:analyze` → Watch the magic happen.
 
 ## Just Start Here
 
 ### 🖥️ Installation (2 minutes) - Run in Terminal
 ```bash
+# Recommended: pipx (isolated environment)
+pipx install SuperGemini && SuperGemini install
+
+# Alternative: pip (traditional)
 pip install SuperGemini && SuperGemini install
 ```
 
 ### 💬 First Commands (3 minutes) - Type in Gemini CLI
 ```
-# Interactive project discovery
-/sg:brainstorm "web app for task management"
+# Interactive project discovery (brainstorm mode)
+/sg:analyze "web app for task management"
 
 # Analyze existing code
 /sg:analyze src/
@@ -39,7 +43,7 @@ pip install SuperGemini && SuperGemini install
 
 SuperGemini is a meta-programming framework that enhances Gemini CLI with:
 
-**21 Slash Commands** for workflow automation (/sg:brainstorm, /sg:implement, /sg:analyze)
+**18 Slash Commands** for workflow automation (/sg:analyze, /sg:implement, /sg:workflow)
 **13 AI Specialists** with domain expertise (architect, security, frontend, backend)
 **6 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration)
 **6 MCP Servers** for enhanced capabilities (Context7, Sequential, Magic, Playwright)
@@ -64,8 +68,8 @@ You type `/sg:implement "user login"` → SuperGemini analyzes requirements →
 
 **First Session Pattern:**
 ```bash
-# 1. Project Discovery
-/sg:brainstorm "e-commerce mobile app"
+# 1. Project Discovery (brainstorm mode)
+/sg:analyze "e-commerce mobile app"
 
 # 2. Load Context (existing projects)
 /sg:load src/
@@ -120,7 +124,7 @@ SuperGemini transforms Gemini CLI from a general-purpose AI assistant into a **s
 
 **Learning Path:**
 
-**Week 1**: Master core commands (`/sg:brainstorm`, `/sg:analyze`, `/sg:implement`)
+**Week 1**: Master core commands (`/sg:analyze`, `/sg:implement`, `/sg:workflow`)
 **Week 2**: Explore behavioral modes and flag combinations
 **Week 3**: Configure MCP servers for enhanced capabilities
 **Week 4**: Create custom workflows and session management patterns

Docs/Reference/README.md

@@ -100,7 +100,7 @@ Advanced Analysis: diagnostic-reference.md
 | `/sg:load` | Restore session context | `/sg:load project_name` |
 | `/sg:save` | Preserve session state | `/sg:save "milestone checkpoint"` |
 | `--think` | Enable structured analysis | `--think analyze performance bottlenecks` |
-| `--brainstorm` | Collaborative requirement discovery | `--brainstorm new authentication system` |
+| `` | Collaborative requirement discovery | ` new authentication system` |
 | `--task-manage` | Multi-step operation orchestration | `--task-manage refactor user module` |
 
 ### Performance & Efficiency Flags

Docs/Reference/advanced-patterns.md

@@ -301,10 +301,10 @@
 
 ### Strategic Mode Usage Patterns
 
-**Brainstorming Mode for Requirements Discovery:**
+**analysis mode for Requirements Discovery:**
 ```bash
 # Activate for: Vague requirements, project planning, creative exploration
-/sg:brainstorm "productivity solution for remote teams"
+/sg:analyze "productivity solution for remote teams"
 # Triggers: uncertainty keywords ("maybe", "thinking about", "not sure")
 
 # Expected behavior:
@@ -368,8 +368,8 @@
 
 **Explicit Mode Activation:**
 ```bash
-# Force brainstorming mode for systematic exploration
-/sg:brainstorm "well-defined requirements" --mode brainstorming
+# Force analysis mode for systematic exploration
+/sg:analyze "well-defined requirements" --mode brainstorming
 # Override automatic mode selection when exploration needed
 
 # Force task management mode for simple tasks requiring tracking
@@ -391,8 +391,8 @@
 
 **Sequential Mode Progression for Complex Projects:**
 ```bash
-# Phase 1: Brainstorming mode for discovery
-Phase 1: /sg:brainstorm "project concept" --requirements-focus
+# Phase 1: analysis mode for discovery
+Phase 1: /sg:analyze "project concept" --requirements-focus
 # Mode: Collaborative discovery, requirements elicitation
 
 # Phase 2: Task management mode for structured development  
@@ -413,14 +413,14 @@ Phase 4: /sg:reflect "project completion" --introspect --lessons-learned
 **Context-Sensitive Mode Selection:**
 ```bash
 # Startup MVP Development Context
-Week 1: /sg:brainstorm "SaaS platform for small businesses" # Discovery mode
+Week 1: /sg:analyze "SaaS platform for small businesses" # Discovery mode
 Week 2-3: /sg:workflow "MVP development plan" --6-week-timeline # Task management
 Week 4-5: /sg:spawn "frontend-backend integration" --orchestrate # Coordination mode
 Week 6: /sg:reflect "MVP development process" --lessons-learned # Introspection
 
 # Enterprise Application Modernization Context
 Discovery: /sg:analyze legacy-system/ --introspect --modernization-assessment
-Planning: /sg:brainstorm "modernization approaches for legacy monolith"  
+Planning: /sg:analyze "modernization approaches for legacy monolith"  
 Implementation: /sg:workflow "microservices extraction roadmap" --enterprise-scale
 Integration: /sg:spawn "microservices deployment with monitoring" --orchestrate
 Optimization: /sg:analyze complete-system/ --uc --performance-focus
@@ -434,7 +434,7 @@ Optimization: /sg:analyze complete-system/ --uc --performance-focus
 Understanding: /sg:load open-source-project/ --introspect --contributor-perspective
 # Deep understanding with transparent reasoning about project patterns
 
-Planning: /sg:brainstorm "feature contribution that benefits community"
+Planning: /sg:analyze "feature contribution that benefits community"
 # Explore contribution opportunities with community value focus
 
 Implementation: /sg:implement "community feature" --orchestrate --comprehensive
@@ -453,7 +453,7 @@ Review: /sg:workflow "pull request preparation" --task-manage --community-standa
 **Project Phase Adaptation:**
 ```bash
 # Early Development (Exploration Phase)
-/sg:brainstorm "new product concept" --exploration-focus
+/sg:analyze "new product concept" --exploration-focus
 # Mode automatically emphasizes:
 # - Creative problem solving
 # - Requirement discovery

Docs/Reference/advanced-workflows.md

@@ -84,7 +84,7 @@
 ### Complete E-Commerce Platform Development
 ```bash
 # Phase 1: Discovery & Planning
-/sg:brainstorm "e-commerce platform for small businesses"
+/sg:analyze "e-commerce platform for small businesses"
 # Expected: Requirements discovery, feature prioritization, technical scope
 
 /sg:save "ecommerce-requirements-complete"
@@ -188,7 +188,7 @@
 # Expected: Architecture understanding, contribution patterns, codebase navigation
 # ✅ Verified: SuperGemini v4.0
 
-/sg:brainstorm "feature proposal for community benefit" --focus community
+/sg:analyze "feature proposal for community benefit" --focus community
 # Expected: Community-oriented feature planning, RFC preparation
 
 # Feature Implementation with Quality Focus
@@ -414,7 +414,7 @@
 ### Startup MVP to Enterprise Scale
 ```bash
 # Week 1-2: MVP Foundation
-/sg:brainstorm "scalable social platform for creators" && /sg:save "mvp-requirements"
+/sg:analyze "scalable social platform for creators" && /sg:save "mvp-requirements"
 
 /sg:load "mvp-requirements" && /sg:implement "MVP core features with scalability considerations"
 # Expected: MVP implementation with enterprise-scale architecture planning

Docs/Reference/basic-examples.md

@@ -22,15 +22,15 @@
 
 ### Core Development Commands
 
-#### Command: /sg:brainstorm
+#### Command: /sg:analyze
 **Purpose**: Interactive project discovery and requirements gathering
-**Syntax**: `/sg:brainstorm "project description"`
+**Syntax**: `/sg:analyze "project description"`
 **Example**:
 ```bash
-/sg:brainstorm "mobile app for fitness tracking"
+/sg:analyze "mobile app for fitness tracking"
 # Expected: Socratic dialogue, requirement elicitation, feasibility analysis
 ```
-**Verification**: Activates brainstorming mode + system-architect + requirements-analyst + Context7
+**Verification**: Activates analysis mode + system-architect + requirements-analyst + Context7
 
 #### Command: /sg:analyze
 **Purpose**: Analyze existing codebase for issues and improvements
@@ -115,7 +115,7 @@
 ### Discovery → Implementation Pattern
 ```bash
 # Step 1: Explore and understand requirements
-/sg:brainstorm "web dashboard for project management"
+/sg:analyze "web dashboard for project management"
 # Expected: Requirements discovery, feature prioritization, technical scope
 
 # Step 2: Analyze technical approach
@@ -183,15 +183,15 @@
 ### Interactive Requirements Discovery
 ```bash
 # Transform vague ideas into concrete requirements
-/sg:brainstorm "productivity app for remote teams"
+/sg:analyze "productivity app for remote teams"
 
 # Expected Interaction:
 # - Socratic questioning about user needs and pain points
 # - Feature prioritization and scope definition
 # - Technical feasibility assessment
 # - Structured requirements document generation
 
-# Activates: Brainstorming mode + system-architect + requirements-analyst
+# Activates: analysis mode + system-architect + requirements-analyst
 # Output: Product Requirements Document (PRD) with clear specifications
 
 # Follow-up commands for progression:
@@ -436,15 +436,15 @@
 /sg:analyze problem-area/ --focus relevant-domain
 
 # Day 5-7: Integration
-/sg:brainstorm "project idea"
+/sg:analyze "project idea"
 /sg:implement "core feature"
 /sg:test --focus quality
 ```
 
 ### Week 2: Patterns
 ```bash
 # Workflow patterns
-/sg:brainstorm → /sg:analyze → /sg:implement → /sg:test
+/sg:analyze → /sg:analyze → /sg:implement → /sg:test
 
 # Problem-solving patterns
 /sg:troubleshoot → /sg:analyze → /sg:implement
@@ -456,7 +456,7 @@
 ### Week 3-4: Integration
 ```bash
 # Multi-step projects
-/sg:brainstorm "larger project"
+/sg:analyze "larger project"
 /sg:implement "phase 1"
 /sg:test --focus quality
 /sg:implement "phase 2"

Docs/Reference/examples-cookbook.md

@@ -75,7 +75,7 @@
 ## Verified Commands Reference
 
 **Core Commands** (all verified SuperGemini v4.0):
-- `/sg:brainstorm` - Interactive requirements discovery
+- `/sg:analyze` - Interactive requirements discovery
 - `/sg:analyze` - Codebase analysis and assessment
 - `/sg:implement` - Feature implementation with best practices
 - `/sg:troubleshoot` - Systematic problem diagnosis

Docs/Reference/quick-start-practices.md

@@ -28,7 +28,7 @@
 **Start Simple, Scale Intelligently:**
 ```bash
 # Week 1: Master these essential commands
-/sg:brainstorm "vague project idea"      # Requirements discovery
+/sg:analyze "vague project idea"      # Requirements discovery
 /sg:analyze existing-code/               # Code understanding  
 /sg:implement "specific feature"         # Feature development
 /sg:test --coverage                      # Quality validation
@@ -48,7 +48,7 @@
 **Phase 1: Command Fundamentals (Days 1-7)**
 ```bash
 # Daily practice routine
-Day 1: /sg:brainstorm "daily coding challenge"
+Day 1: /sg:analyze "daily coding challenge"
 Day 2: /sg:analyze sample-project/ --focus quality
 Day 3: /sg:implement "simple CRUD API"
 Day 4: /sg:test --type unit --coverage
@@ -66,7 +66,7 @@ Day 7: /sg:workflow "week 2 learning plan"
 # Should activate: security-engineer + backend-architect + quality-engineer + technical-writer
 
 # Mode optimization practice
-/sg:brainstorm "complex project requirements"  # Brainstorming mode
+/sg:analyze "complex project requirements"  # analysis mode
 /sg:spawn "multi-service architecture"         # Task management mode
 /sg:analyze performance-issues/ --introspect   # Introspection mode
 
@@ -129,7 +129,7 @@ Day 7: /sg:workflow "week 2 learning plan"
 # Use when: Starting new projects, onboarding, architecture review
 /sg:load project/ --scope project         # Project understanding
 /sg:analyze . --focus architecture        # System design analysis
-/sg:brainstorm "project enhancement"       # Requirements discovery
+/sg:analyze "project enhancement"       # Requirements discovery
 /sg:explain "complex system behavior"     # Concept clarification
 
 # Best practice: Always start projects with discovery commands
@@ -190,7 +190,7 @@ Day 7: /sg:workflow "week 2 learning plan"
 **Context-Aware Command Selection:**
 ```bash
 # For new projects: Discovery-first approach
-/sg:brainstorm → /sg:design → /sg:workflow → /sg:implement
+/sg:analyze → /sg:design → /sg:workflow → /sg:implement
 
 # For existing projects: Analysis-first approach  
 /sg:load → /sg:analyze → /sg:improve → /sg:test
@@ -228,8 +228,8 @@ Day 7: /sg:workflow "week 2 learning plan"
 # --validate: Verify changes before applying
 
 # For learning and exploration
-/sg:explain "complex architecture" --brainstorm
-# --brainstorm: Interactive learning through dialogue
+/sg:explain "complex architecture"
+#: Interactive learning through dialogue
 
 # Development speed: Faster iteration cycles through focused scope
 ```
@@ -268,7 +268,7 @@ Day 7: /sg:workflow "week 2 learning plan"
 **Context-Adaptive Flag Selection:**
 ```bash
 # Early development phase
-/sg:brainstorm "new feature" --scope project
+/sg:analyze "new feature" --scope project
 # Focus on exploration and requirements discovery
 
 # Implementation phase