@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/homebrew-prereqs.md

@@ -0,0 +1,785 @@
+# Prerequisite Deep-Dive: Homebrew, Node, & Go
+
+**Type**: Prerequisites (Not a Skill)
+**Category**: Local Foundation
+**Setup Difficulty**: 🟢 Easy (Homebrew) → 🟡 Medium (Node + Go)
+**Time Estimate**: ~10-15 minutes
+**Platform**: macOS primary (Linux supported)
+
+---
+
+## What This Is
+
+This document covers the **foundational tools** that many Nexus skills depend on:
+- **Homebrew**: Package manager for macOS/Linux
+- **Node.js + npm**: JavaScript runtime and package manager
+- **Go**: Programming language (for some CLI tools)
+
+These are **NOT skills** themselves, but prerequisites for installing and running many skills.
+
+---
+
+## Why These Are Needed
+
+### Homebrew (brew)
+
+| What It Does | Why Nexus Needs It | Skills That Use It |
+|--------------|-------------------|-------------------|
+| Package manager for macOS/Linux | Installs CLI tools easily | eve, wacli, peekaboo, 1password-cli, gh, comms |
+| Manages dependencies | Keeps tools updated | Most skills that require binaries |
+| Provides tap repositories | Access to specialized tools | steipete/tap/wacli, Napageneral/tap/eve |
+
+**Without Homebrew**: You'd need to manually download, compile, and install each tool.
+
+### Node.js + npm
+
+| What It Does | Why Nexus Needs It | Skills That Use It |
+|--------------|-------------------|-------------------|
+| JavaScript runtime | Run JavaScript-based tools | qmd, brave-search, nexus-cloud |
+| npm package manager | Install Node packages | Installing global tools |
+| Script execution | Run .mjs and .js files | brave-search scripts |
+
+**Without Node**: JavaScript-based skills won't work at all.
+
+### Go
+
+| What It Does | Why Nexus Needs It | Skills That Use It |
+|--------------|-------------------|-------------------|
+| Programming language | Required to build some tools from source | eve, comms (if installing via `go install`) |
+| Fast compilation | Build tools quickly | Alternative to Homebrew for Go-based tools |
+| Cross-platform | Same code works on macOS/Linux/Windows | Portable skill implementations |
+
+**Without Go**: Can't install tools via `go install` (but Homebrew alternatives often available).
+
+---
+
+## Detection: Check What You Have
+
+### Quick Check Script
+
+```bash
+#!/bin/bash
+# Check for prerequisites
+
+echo "Checking prerequisites..."
+echo ""
+
+# Check Homebrew
+if which brew > /dev/null 2>&1; then
+    echo "✅ Homebrew: $(brew --version | head -1)"
+else
+    echo "❌ Homebrew: Not installed"
+fi
+
+# Check Node.js
+if which node > /dev/null 2>&1; then
+    echo "✅ Node.js: $(node --version)"
+else
+    echo "❌ Node.js: Not installed"
+fi
+
+# Check npm
+if which npm > /dev/null 2>&1; then
+    echo "✅ npm: $(npm --version)"
+else
+    echo "❌ npm: Not installed"
+fi
+
+# Check Go
+if which go > /dev/null 2>&1; then
+    echo "✅ Go: $(go version | awk '{print $3}')"
+else
+    echo "❌ Go: Not installed"
+fi
+
+echo ""
+echo "Summary:"
+echo "--------"
+if which brew > /dev/null 2>&1; then
+    echo "Homebrew: Ready for skills: eve, wacli, peekaboo, etc."
+else
+    echo "Homebrew: NEEDED - Many skills require this"
+fi
+
+if which node > /dev/null 2>&1 && which npm > /dev/null 2>&1; then
+    echo "Node.js/npm: Ready for skills: qmd, brave-search, etc."
+else
+    echo "Node.js/npm: RECOMMENDED - Some skills require this"
+fi
+
+if which go > /dev/null 2>&1; then
+    echo "Go: Ready for alternative installations"
+else
+    echo "Go: OPTIONAL - Can use Homebrew instead"
+fi
+```
+
+### Individual Checks
+
+```bash
+# Check Homebrew
+which brew && brew --version
+
+# Check Node.js
+which node && node --version
+
+# Check npm
+which npm && npm --version
+
+# Check Go
+which go && go version
+
+# Check PATH includes common binary locations
+echo $PATH | grep -q "/usr/local/bin" && echo "✅ /usr/local/bin in PATH"
+echo $PATH | grep -q "/opt/homebrew/bin" && echo "✅ /opt/homebrew/bin in PATH"
+echo $PATH | grep -q "$HOME/.npm-global/bin" && echo "✅ npm global in PATH"
+```
+
+---
+
+## Installation
+
+### Install Homebrew (macOS/Linux)
+
+#### macOS Installation
+
+```bash
+# Install Homebrew
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Follow the instructions to add brew to PATH
+# For Apple Silicon (M1/M2/M3):
+echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
+eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# For Intel Macs:
+echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
+eval "$(/usr/local/bin/brew shellenv)"
+
+# Verify installation
+brew --version
+brew doctor
+```
+
+#### Linux Installation
+
+```bash
+# Install Homebrew on Linux
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Add to PATH (shown after installation)
+echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
+eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+
+# Verify
+brew --version
+```
+
+### Install Node.js + npm
+
+#### Option 1: Via Homebrew (Recommended)
+
+```bash
+# Install Node.js (includes npm)
+brew install node
+
+# Verify installation
+node --version
+npm --version
+
+# Configure npm global directory (optional but recommended)
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+
+# Add to PATH
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+#### Option 2: Via Official Installer
+
+```bash
+# Download from: https://nodejs.org/
+# Install the LTS version
+# Verify installation
+node --version
+npm --version
+```
+
+#### Option 3: Via nvm (Node Version Manager)
+
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+
+# Restart terminal or source profile
+source ~/.zshrc
+
+# Install Node.js LTS
+nvm install --lts
+
+# Verify
+node --version
+npm --version
+
+# Set default
+nvm alias default node
+```
+
+### Install Go
+
+#### Option 1: Via Homebrew (Recommended)
+
+```bash
+# Install Go
+brew install go
+
+# Verify installation
+go version
+
+# Configure GOPATH (optional)
+echo 'export GOPATH="$HOME/go"' >> ~/.zshrc
+echo 'export PATH="$GOPATH/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+#### Option 2: Via Official Installer
+
+```bash
+# Download from: https://go.dev/dl/
+# macOS: Download .pkg installer
+# Linux: Download .tar.gz
+
+# macOS: Run .pkg installer
+
+# Linux: Extract and install
+sudo rm -rf /usr/local/go
+sudo tar -C /usr/local -xzf go1.21.x.linux-amd64.tar.gz
+
+# Add to PATH
+echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
+source ~/.bashrc
+
+# Verify
+go version
+```
+
+---
+
+## Verification
+
+### Complete Verification Script
+
+```bash
+#!/bin/bash
+# Comprehensive prerequisite verification
+
+echo "================================"
+echo "Nexus Prerequisites Verification"
+echo "================================"
+echo ""
+
+ERRORS=0
+
+# Check Homebrew
+echo "1. Homebrew (brew)"
+if which brew > /dev/null 2>&1; then
+    VERSION=$(brew --version | head -1)
+    echo "   ✅ $VERSION"
+
+    # Check brew health
+    echo "   Running brew doctor..."
+    brew doctor > /tmp/brew-doctor.txt 2>&1
+    if [ $? -eq 0 ]; then
+        echo "   ✅ Homebrew is healthy"
+    else
+        echo "   ⚠️  Homebrew has warnings (see /tmp/brew-doctor.txt)"
+    fi
+else
+    echo "   ❌ NOT INSTALLED"
+    ERRORS=$((ERRORS + 1))
+fi
+echo ""
+
+# Check Node.js
+echo "2. Node.js"
+if which node > /dev/null 2>&1; then
+    VERSION=$(node --version)
+    echo "   ✅ $VERSION"
+
+    # Check if version is recent (v16+)
+    MAJOR=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+    if [ "$MAJOR" -ge 16 ]; then
+        echo "   ✅ Version is current"
+    else
+        echo "   ⚠️  Version is old (recommend v18 LTS or newer)"
+    fi
+else
+    echo "   ❌ NOT INSTALLED"
+    ERRORS=$((ERRORS + 1))
+fi
+echo ""
+
+# Check npm
+echo "3. npm"
+if which npm > /dev/null 2>&1; then
+    VERSION=$(npm --version)
+    echo "   ✅ $VERSION"
+
+    # Check global bin directory is in PATH
+    NPM_BIN=$(npm config get prefix)/bin
+    if echo $PATH | grep -q "$NPM_BIN"; then
+        echo "   ✅ npm global bin in PATH"
+    else
+        echo "   ⚠️  npm global bin NOT in PATH: $NPM_BIN"
+        echo "   Add to PATH: export PATH=\"$NPM_BIN:\$PATH\""
+    fi
+else
+    echo "   ❌ NOT INSTALLED"
+    ERRORS=$((ERRORS + 1))
+fi
+echo ""
+
+# Check Go
+echo "4. Go"
+if which go > /dev/null 2>&1; then
+    VERSION=$(go version | awk '{print $3}')
+    echo "   ✅ $VERSION"
+
+    # Check GOPATH
+    if [ -n "$GOPATH" ]; then
+        echo "   ✅ GOPATH set: $GOPATH"
+    else
+        echo "   ⚠️  GOPATH not set (will use default: ~/go)"
+    fi
+
+    # Check GOPATH/bin in PATH
+    GOBIN="${GOPATH:-$HOME/go}/bin"
+    if echo $PATH | grep -q "$GOBIN"; then
+        echo "   ✅ GOPATH/bin in PATH"
+    else
+        echo "   ⚠️  GOPATH/bin NOT in PATH: $GOBIN"
+        echo "   Add to PATH: export PATH=\"$GOBIN:\$PATH\""
+    fi
+else
+    echo "   ℹ️  NOT INSTALLED (optional - Homebrew can substitute)"
+fi
+echo ""
+
+# Summary
+echo "================================"
+echo "Summary"
+echo "================================"
+if [ $ERRORS -eq 0 ]; then
+    echo "✅ All critical prerequisites installed!"
+    echo ""
+    echo "You're ready to install Nexus skills."
+else
+    echo "❌ $ERRORS critical prerequisite(s) missing"
+    echo ""
+    echo "Install missing prerequisites:"
+    which brew > /dev/null || echo "  - Homebrew: /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
+    which node > /dev/null || echo "  - Node.js: brew install node"
+    which npm > /dev/null || echo "  - npm: Included with Node.js"
+fi
+```
+
+---
+
+## Common Failure Points
+
+### Failure: "brew: command not found"
+
+**Symptom**: Shell can't find `brew` command
+
+**Cause**: Homebrew not in PATH
+
+**Recovery**:
+```bash
+# For Apple Silicon (M1/M2/M3):
+echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
+source ~/.zprofile
+
+# For Intel Macs:
+echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
+source ~/.zprofile
+
+# For Linux:
+echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
+source ~/.bashrc
+
+# Verify
+brew --version
+```
+
+**Prevention**: Follow Homebrew installation instructions completely
+
+---
+
+### Failure: "npm: command not found" (but node exists)
+
+**Symptom**: Node works but npm doesn't
+
+**Cause**: npm not installed or not in PATH
+
+**Recovery**:
+```bash
+# Check if npm is actually installed
+ls /usr/local/lib/node_modules/npm
+ls /opt/homebrew/lib/node_modules/npm
+
+# If missing, reinstall Node
+brew reinstall node
+
+# Or install npm separately
+curl -L https://www.npmjs.com/install.sh | sh
+
+# Verify
+npm --version
+```
+
+**Prevention**: Install Node via Homebrew (includes npm)
+
+---
+
+### Failure: "Permission denied" when installing global npm packages
+
+**Symptom**: `npm install -g` fails with EACCES error
+
+**Cause**: npm trying to write to system directory without permissions
+
+**Recovery**:
+```bash
+# Option 1: Configure npm to use user directory (recommended)
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# Option 2: Fix permissions (not recommended)
+sudo chown -R $(whoami) /usr/local/lib/node_modules
+sudo chown -R $(whoami) /usr/local/bin
+```
+
+**Prevention**: Configure npm global directory before installing packages
+
+---
+
+### Failure: "go: command not found"
+
+**Symptom**: Shell can't find `go` command
+
+**Cause**: Go not installed or not in PATH
+
+**Recovery**:
+```bash
+# Check if Go is actually installed
+ls /usr/local/go/bin/go  # Official installer location
+which go  # If in Homebrew
+
+# If missing, install
+brew install go
+
+# Or add to PATH if installed but not in PATH
+echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.zshrc
+echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc
+source ~/.zshrc
+
+# Verify
+go version
+```
+
+**Prevention**: Follow Go installation instructions, add to PATH
+
+---
+
+### Failure: "go install" downloads but binary not found
+
+**Symptom**: `go install` succeeds but can't run the binary
+
+**Cause**: GOPATH/bin not in PATH
+
+**Recovery**:
+```bash
+# Check where Go installed the binary
+ls ~/go/bin/
+
+# Add GOPATH/bin to PATH
+echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# Or if using custom GOPATH
+echo 'export GOPATH="$HOME/your-custom-path"' >> ~/.zshrc
+echo 'export PATH="$GOPATH/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# Verify
+which <binary-name>
+```
+
+**Prevention**: Add GOPATH/bin to PATH before using `go install`
+
+---
+
+## Automation Script: Install All Prerequisites
+
+```bash
+#!/bin/bash
+# Complete prerequisite installation script for macOS
+
+set -e
+
+echo "Installing Nexus Prerequisites..."
+echo ""
+
+# Detect platform
+OS=$(uname -s)
+ARCH=$(uname -m)
+
+echo "Platform: $OS $ARCH"
+echo ""
+
+# Install Homebrew if missing
+if ! which brew > /dev/null 2>&1; then
+    echo "Installing Homebrew..."
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+    # Add to PATH based on architecture
+    if [ "$ARCH" = "arm64" ]; then
+        echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
+        eval "$(/opt/homebrew/bin/brew shellenv)"
+    else
+        echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
+        eval "$(/usr/local/bin/brew shellenv)"
+    fi
+else
+    echo "✅ Homebrew already installed"
+fi
+
+# Update Homebrew
+echo "Updating Homebrew..."
+brew update
+
+# Install Node.js if missing
+if ! which node > /dev/null 2>&1; then
+    echo "Installing Node.js..."
+    brew install node
+
+    # Configure npm global directory
+    mkdir -p ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+else
+    echo "✅ Node.js already installed"
+fi
+
+# Install Go if missing
+if ! which go > /dev/null 2>&1; then
+    echo "Installing Go..."
+    brew install go
+
+    # Configure GOPATH
+    echo 'export GOPATH="$HOME/go"' >> ~/.zshrc
+    echo 'export PATH="$GOPATH/bin:$PATH"' >> ~/.zshrc
+else
+    echo "✅ Go already installed"
+fi
+
+echo ""
+echo "✅ All prerequisites installed!"
+echo ""
+echo "Versions:"
+brew --version | head -1
+node --version
+npm --version
+go version
+
+echo ""
+echo "⚠️  IMPORTANT: Restart your terminal or run:"
+echo "    source ~/.zshrc"
+echo ""
+echo "Then verify with:"
+echo "    brew --version"
+echo "    node --version"
+echo "    npm --version"
+echo "    go version"
+```
+
+---
+
+## Skills That Require Each Tool
+
+### Homebrew Required
+
+- **eve** - `brew install Napageneral/tap/eve`
+- **wacli** - `brew install steipete/tap/wacli`
+- **peekaboo** - `brew install steipete/tap/peekaboo`
+- **1password-cli** - `brew install 1password-cli`
+- **github** - `brew install gh`
+- **comms** - `brew install Napageneral/tap/comms`
+
+### Node.js Required
+
+- **qmd** - `npm install -g https://github.com/tobi/qmd`
+- **brave-search** - Uses `node` to run scripts
+- **nexus-cloud** - Uses `wrangler` (Node-based)
+
+### Go Optional (Homebrew Alternative Available)
+
+- **eve** - `go install github.com/Napageneral/eve/cmd/eve@latest` OR `brew install`
+- **comms** - `go install github.com/Napageneral/comms/cmd/comms@latest` OR `brew install`
+
+---
+
+## Best Practices
+
+### PATH Management
+
+```bash
+# Recommended PATH order in ~/.zshrc:
+export PATH="$HOME/.npm-global/bin:$PATH"     # npm global
+export PATH="$HOME/go/bin:$PATH"              # Go binaries
+export PATH="/opt/homebrew/bin:$PATH"         # Homebrew (M1/M2/M3)
+export PATH="/usr/local/bin:$PATH"            # Homebrew (Intel)
+
+# Then evaluate Homebrew environment
+eval "$(brew shellenv)"
+```
+
+### Regular Maintenance
+
+```bash
+# Weekly maintenance routine
+
+# Update Homebrew and all packages
+brew update
+brew upgrade
+brew cleanup
+
+# Update npm itself
+npm install -g npm@latest
+
+# Update Go (via Homebrew)
+brew upgrade go
+
+# Check for outdated global npm packages
+npm outdated -g
+```
+
+### Security
+
+```bash
+# Verify Homebrew integrity
+brew doctor
+
+# Check npm packages for vulnerabilities
+npm audit
+
+# Keep everything updated
+brew update && brew upgrade
+npm update -g
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Homebrew installed: `which brew`
+- [ ] Homebrew healthy: `brew doctor`
+- [ ] Homebrew in PATH: `echo $PATH | grep brew`
+- [ ] Node.js installed: `which node`
+- [ ] Node.js version current: `node --version` (v18+)
+- [ ] npm installed: `which npm`
+- [ ] npm global in PATH: `echo $PATH | grep npm-global`
+- [ ] Go installed: `which go`
+- [ ] Go version current: `go version` (1.20+)
+- [ ] GOPATH/bin in PATH: `echo $PATH | grep go/bin`
+- [ ] Can install via brew: `brew install --dry-run curl`
+- [ ] Can install global npm: `npm install -g --dry-run cowsay`
+- [ ] Can install via go: `go install --help`
+
+---
+
+## Notes for Onboarding Agent
+
+- **Install order**: Always Homebrew first, then Node, then Go
+- **Platform awareness**: Check OS before recommending (Homebrew is macOS/Linux only)
+- **When to recommend**:
+  - User installing first skill that requires any of these
+  - During initial Nexus onboarding
+  - When installation fails due to missing prerequisite
+- **When NOT to recommend**:
+  - User already has these installed (check first!)
+  - User is on Windows (different prerequisites)
+- **Value proposition**: "Install once, unlock all Nexus skills"
+- **Time estimate**: 10-15 minutes (longer if downloads are slow)
+- **Restart required**: Always remind user to restart terminal after installation
+- **Verification is key**: Always run verification script after installation
+- **Troubleshooting**: Most issues are PATH-related (check PATH first)
+
+---
+
+## Platform-Specific Notes
+
+### macOS
+
+- **Apple Silicon (M1/M2/M3)**: Homebrew installs to `/opt/homebrew`
+- **Intel**: Homebrew installs to `/usr/local`
+- **Both**: Use `brew shellenv` to set PATH automatically
+
+### Linux
+
+- **Homebrew on Linux**: Installs to `/home/linuxbrew/.linuxbrew`
+- **Alternative**: Can use apt/yum for some tools (but Homebrew preferred for consistency)
+- **Permissions**: May need sudo for some operations
+
+### Windows
+
+- **Homebrew**: Not officially supported
+- **Node.js**: Use official installer or nvm-windows
+- **Go**: Use official installer
+- **Alternative package manager**: Consider chocolatey or scoop
+
+---
+
+## Quick Reference Card
+
+```bash
+# Check what you have
+brew --version  # Homebrew
+node --version  # Node.js
+npm --version   # npm
+go version      # Go
+
+# Install Homebrew (macOS/Linux)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Node.js
+brew install node
+
+# Install Go
+brew install go
+
+# Add to PATH (add to ~/.zshrc)
+eval "$(brew shellenv)"
+export PATH="$HOME/.npm-global/bin:$PATH"
+export PATH="$HOME/go/bin:$PATH"
+
+# Verify all
+brew doctor
+node --version
+npm --version
+go version
+```
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial prerequisite deep-dive created |
+
+---
+
+*Template version: 1.0*