docs: update for alpha.6 + perf: remove shortcuts (2,658x speedup)

Documentation Updates (alpha.6):
- Update version to 2.0.0-alpha.6 in PHASE2_COMPLETION_REPORT.md
- Document upgrade-all 5-stage workflow in DEPLOYMENT.md
- Add upgrade-all commands to QUICK_REFERENCE.md and CLI_REFERENCE.md
- Update project context (claudedocs/) with recent features
- Validate all documentation cross-references

Performance Fix (Critical):
- Remove Makefile.d/shortcuts.mk completely (50s overhead per command)
- Clean up Makefile shortcuts include directive
- Performance: 53s → 0.020s (2,658x faster for make user-help)
- All commands now execute in <0.1s

Version Updates:
- Update Claude Code dependency: 2.0.11 → 2.0.22
- Update latest_versions.json with version flag improvements
- Refresh tools_snapshot.json cache

🎉 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: CybotTM

Makefile

@@ -69,6 +69,3 @@ help: ## Show complete help with all commands
 include Makefile.d/user.mk
 include Makefile.d/dev.mk
 include Makefile.d/maint.mk
-
-# Shortcuts must be last to act as catch-all
-include Makefile.d/shortcuts.mk

Makefile.d/shortcuts.mk

@@ -1,16 +1,18 @@
 # AI CLI Preparation - Project Context (AI Agent Reference)
 
-**Last Updated:** 2025-10-13
+**Last Updated:** 2025-10-18
+**Version:** 2.0.0-alpha.6
 **For:** AI Coding Agents (Claude Code, etc.)
 
 ## Quick Reference
 
-**Purpose:** Environment audit tool ensuring AI coding agents have all necessary CLI tools installed and current
+**Purpose:** Environment audit and tool management system ensuring AI coding agents have all necessary CLI tools installed, current, and properly configured
 
 **Repository:** github.com/netresearch/coding_agent_cli_toolset
 **Primary Language:** Python 3.9+ (dev: 3.14.0rc2)
-**Architecture:** Offline-first, parallel, resilient tool version auditing
-**Tool Coverage:** 64 tools across 10 categories (50+ production, rest in development)
+**Architecture:** Offline-first, parallel, resilient tool version auditing with comprehensive upgrade orchestration
+**Tool Coverage:** 64 tools across 10 categories
+**Phase Status:** Phase 1 (Audit) Complete | Phase 2 (Install/Upgrade) Alpha
 
 ## Core Capabilities
 
@@ -121,10 +123,39 @@ make update
 # Interactive upgrade guide
 make upgrade
 
+# Complete system upgrade (5 stages)
+make upgrade-all
+
+# Preview system upgrade (dry-run)
+make upgrade-all-dry-run
+
 # Offline audit with hints
 make audit-offline
 ```
 
+### System-Wide Upgrade (New in alpha.6)
+```bash
+# 5-Stage orchestrated upgrade workflow
+make upgrade-all
+# Stage 1: Refresh version data
+# Stage 2: Upgrade package managers (apt, brew, snap, flatpak)
+# Stage 3: Upgrade runtimes (Python, Node.js, Go, Ruby, Rust)
+# Stage 4: Upgrade user package managers (uv, pipx, npm, pnpm, yarn, cargo, etc.)
+# Stage 5: Upgrade all CLI tools
+
+# Features:
+# - UV migration (auto-migrates pip/pipx to uv tools)
+# - System package detection (skips apt/brew managed)
+# - Comprehensive logging (logs/upgrade-YYYYMMDD-HHMMSS.log)
+# - Dry-run mode available
+
+# Preview without making changes
+make upgrade-all-dry-run
+
+# Check PATH configuration
+make check-path
+```
+
 ### Role-Based Audits
 ```bash
 make audit-offline-agent-core    # AI agent essentials
@@ -213,20 +244,25 @@ CLI_AUDIT_TRACE=1 python3 cli_audit.py
 
 ## Current Git State
 
-**Branch:** main (12 commits ahead of origin/main)
-**Working Tree:** Clean
-**Modified:** .env (GITHUB_TOKEN + CLI_AUDIT_MAX_WORKERS=40), tools_snapshot.json
+**Branch:** main
+**Working Tree:** Modified (documentation updates in progress)
+**Modified:** latest_versions.json, package.json, package-lock.json, tools_snapshot.json, docs/
 **Untracked:** node_modules/
 **Remote:** git@github.com:netresearch/coding_agent_cli_toolset.git
 
-**Recent commits (2025-10-13):**
+**Recent commits (2025-10-18 - upgrade-all feature):**
+- 9b784ed - chore: update version snapshots
+- 22c1603 - feat(upgrade-all): add UV migration for pip/pipx packages
+- 1b71b71 - feat(upgrade-all): skip pip/pipx when uv is managing Python packages
+- cceed18 - fix(upgrade-all): detect pipx packages with missing metadata and provide fix
+- 7d691cb - feat(upgrade-all): add comprehensive version and location info to all upgrade stages
+
+**Recent commits (2025-10-13 - environment fixes):**
 - 34fa37f - chore(snapshot): update tool audit cache with improved detection
 - 80abd30 - fix(guide): clarify Docker CLI vs Docker Engine terminology
 - aa57210 - fix(cli_audit): resolve three critical issues in environment and detection
-- d092236 - feat(docker): detect client version explicitly, not server
-- 2237226 - fix(cli_audit): resolve three issues in make update
 
-**Recent commits (2025-10-09):**
+**Recent commits (2025-10-09 - documentation):**
 - 0c7ade3 - Snapshot-based collect/render modes
 - 3dd5082 - Lock ordering fixes (thread safety)
 - c160361 - Classification improvements (shebang detection)

claudedocs/project_context.md

@@ -41,6 +41,11 @@ make update      # Collect data (network required)
 make audit       # Render table (offline)
 make audit-auto  # Update if missing, then render
 
+# System-wide upgrade
+make upgrade-all         # Complete 5-stage system upgrade
+make upgrade-all-dry-run # Preview without making changes
+make check-path          # Validate PATH configuration
+
 # Installation (Makefile)
 make install-core
 make install-python
@@ -254,6 +259,37 @@ make audit-auto
 make upgrade
 ```
 
+### System-Wide Upgrade
+
+```bash
+# Complete system upgrade (5 stages: data → managers → runtimes → user managers → tools)
+make upgrade-all
+
+# Preview upgrade without making changes (dry-run)
+make upgrade-all-dry-run
+
+# Check PATH configuration before upgrading
+make check-path
+```
+
+**5-Stage Workflow:**
+1. Refresh version data from upstream
+2. Upgrade system package managers (apt, brew, snap, flatpak)
+3. Upgrade language runtimes (Python, Node.js, Go, Ruby, Rust)
+4. Upgrade user package managers (uv, pipx, npm, pnpm, yarn, cargo, composer, poetry)
+5. Upgrade all CLI tools managed by each package manager
+
+**Features:**
+- UV migration (auto-migrates pip/pipx packages to uv tools)
+- System package detection (skips system-managed tools)
+- Comprehensive logging to `logs/upgrade-YYYYMMDD-HHMMSS.log`
+- Colored output with statistics summary
+
+**Environment Variables:**
+- `DRY_RUN=1` - Preview mode
+- `SKIP_SYSTEM=1` - Skip system package managers
+- `VERBOSE=1` - Detailed output
+
 ### Installation Scripts
 
 **Core Tools:**

docs/CLI_REFERENCE.md

@@ -100,6 +100,103 @@ Interactive remediation guide (renamed from `guide`).
 make upgrade
 ```
 
+### System-Wide Upgrade Targets
+
+#### `make upgrade-all`
+Complete system upgrade in 5 orchestrated stages.
+
+**Workflow:**
+1. **Stage 1: Refresh Data** - Update version snapshot from upstream sources
+2. **Stage 2: Upgrade Package Managers** - Self-update system package managers (apt, brew, snap, flatpak)
+3. **Stage 3: Upgrade Language Runtimes** - Update core runtimes (Python, Node.js, Go, Ruby, Rust)
+4. **Stage 4: Upgrade User Package Managers** - Update language-specific managers (uv, pipx, npm, pnpm, yarn, cargo, composer, poetry)
+5. **Stage 5: Upgrade Tools** - Upgrade all CLI tools managed by each package manager
+
+**Features:**
+- Comprehensive logging to `logs/upgrade-YYYYMMDD-HHMMSS.log`
+- Colored terminal output with progress tracking
+- Version and location info for successful upgrades
+- UV migration support (auto-migrates pip/pipx packages to uv tools)
+- System package detection (skips system-managed tools, suggests reconcile)
+- Statistics summary (upgraded/failed/skipped counts)
+- Dry-run mode available
+
+**Use Case:** Complete development environment upgrade, ensuring all tools across all package managers are current.
+
+**Duration:** 5-15 minutes depending on number of outdated packages.
+
+```bash
+# Full system upgrade
+make upgrade-all
+
+# Preview what would be upgraded (dry-run)
+make upgrade-all-dry-run
+```
+
+**Output Example:**
+```
+[1/5] Stage 1: Refresh version data
+  ✓ Updated snapshot (64 tools checked)
+
+[2/5] Stage 2: Upgrade package managers
+  ✓ apt (upgraded 12 packages)
+  ⏭ homebrew (not installed)
+  ✓ snap (2.63 at /usr/bin/snap)
+
+[3/5] Stage 3: Upgrade language runtimes
+  ✓ python (3.12.7 → 3.12.8)
+  ✓ node (20.10.0 → 20.11.0)
+  ⏭ go (already latest: 1.22.0)
+
+[4/5] Stage 4: Upgrade user package managers
+  ✓ uv (0.4.30 → 0.5.0)
+  ✓ pipx (1.7.1 → 1.8.0)
+  → Migrating pip packages to uv...
+    ✓ black migrated to uv tool
+    ✓ ruff migrated to uv tool
+
+[5/5] Stage 5: Upgrade CLI tools
+  ✓ Upgraded 8 uv tools
+  ✓ Upgraded 15 npm packages
+  ✓ Upgraded 3 cargo binaries
+
+Summary: 45 upgraded, 12 skipped, 2 failed
+Duration: 8m 32s
+Log: logs/upgrade-20251018-073045.log
+```
+
+**Environment Variables:**
+- `DRY_RUN=1` - Preview mode without making changes
+- `SKIP_SYSTEM=1` - Skip system package managers (apt, brew, snap, flatpak)
+- `VERBOSE=1` - Detailed output for debugging
+
+**Advanced:**
+```bash
+# Direct script execution with options
+DRY_RUN=1 VERBOSE=1 bash scripts/upgrade_all.sh
+
+# Skip system package managers
+SKIP_SYSTEM=1 make upgrade-all
+
+# Check PATH configuration before upgrading
+make check-path
+```
+
+#### `make check-path`
+Validate PATH configuration for all package managers.
+
+**Behavior:**
+- Checks if package manager binaries are in PATH
+- Validates PATH ordering (user bins before system bins)
+- Identifies potential shadowing issues
+- Provides remediation suggestions
+
+**Use Case:** Diagnose PATH issues before or after system upgrade.
+
+```bash
+make check-path
+```
+
 ### Tool-Specific Audit Targets
 
 #### `make audit-TOOLNAME`

docs/DEPLOYMENT.md

@@ -1,7 +1,7 @@
 # Phase 2 Completion Report
 
-**Version:** 2.0.0-alpha.5
-**Completion Date:** 2025-10-09
+**Version:** 2.0.0-alpha.6
+**Completion Date:** 2025-10-15
 **Status:** ✅ COMPLETE - Ready for Beta
 
 ---

docs/PHASE2_COMPLETION_REPORT.md

@@ -19,6 +19,15 @@ make audit-offline
 # Interactive upgrade guide
 make upgrade
 
+# Complete system upgrade (5 stages: data → managers → runtimes → user managers → tools)
+make upgrade-all
+
+# Preview system upgrade (dry-run)
+make upgrade-all-dry-run
+
+# Check PATH configuration
+make check-path
+
 # Single tool check
 python3 cli_audit.py --only ripgrep | python3 smart_column.py -s "|" -t
 ```

docs/QUICK_REFERENCE.md

@@ -47,7 +47,7 @@
     "gh:universal-ctags/ctags": "latest_redirect",
     "gh:wagoodman/dive": "latest_redirect",
     "gh:watchexec/watchexec": "latest_redirect",
-    "local_dc:docker-compose": "legacy",
+    "local_dc:docker-compose": "plugin",
     "local_flag:ast-grep": "--version",
     "local_flag:aws": "--version",
     "local_flag:bandit": "--version",
@@ -61,7 +61,7 @@
     "local_flag:delta": "--version",
     "local_flag:direnv": "--version",
     "local_flag:dive": "--version",
-    "local_flag:docker": "--version",
+    "local_flag:docker": "version --format {{.Client.Version}}",
     "local_flag:eslint": "--version",
     "local_flag:fd": "--version",
     "local_flag:flake8": "--version",
@@ -72,7 +72,7 @@
     "local_flag:git": "--version",
     "local_flag:git-absorb": "--version",
     "local_flag:git-lfs": "-v",
-    "local_flag:gitleaks": "--version",
+    "local_flag:gitleaks": "version",
     "local_flag:glab": "--version",
     "local_flag:go": "version",
     "local_flag:golangci-lint": "--version",

latest_versions.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "@anthropic-ai/claude-code": "^2.0.11"
+    "@anthropic-ai/claude-code": "^2.0.22"
   }
 }