Update installation documentation with custom directory support and bash 5.x fix

- Rewrite installation.md as comprehensive installation guide
  - Add custom installation directory documentation (--install-dir, OPENCODE_INSTALL_DIR)
  - Document interactive location selection (Local/Global/Custom)
  - Add platform-specific installation examples
  - Include all installation methods and profiles
  - Add troubleshooting and advanced usage sections

- Update platform-compatibility.md with bash 5.x fix details
  - Add Ubuntu 24.04 (bash 5.2.21) to tested configurations
  - Document set -e compatibility fix
  - Add troubleshooting section for bash 5.x issues
  - Update cross-platform features list

Documentation now synced with installer v1.1.0 features

docs/getting-started/installation.md

@@ -1,335 +1,674 @@
-# Install Script - Collision Handling
+# OpenAgents Installation Guide
 
-## Overview
+Complete guide to installing OpenAgents components using the automated installer script.
 
-The install script now intelligently detects and handles file collisions when installing OpenCode components into an existing `.opencode/` directory.
+---
+
+## Quick Start
 
-## How It Works
+### Default Installation (Local Directory)
 
-### 1. Collision Detection
+```bash
+# Interactive mode - choose components
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh)
 
-Before installing any files, the script:
-- Scans all components you've selected to install
-- Checks if any files already exist in your `.opencode/` directory
-- Groups collisions by type (agents, subagents, commands, tools, etc.)
-- Presents a clear report of what would be overwritten
+# Quick install with profile
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) developer
+```
 
-### 2. Installation Strategies
+Installs to `.opencode/` in your current directory.
 
-When collisions are detected, you get **4 options**:
+---
 
-#### Option 1: Skip Existing (Recommended for Updates)
-```
-✅ Only install new files
-✅ Keep ALL existing files unchanged
-✅ Your customizations are preserved
-✅ Safe for incremental updates
+## Installation Methods
+
+### 1. Interactive Installation (Recommended for First-Time Users)
+
+Run the installer without arguments to get an interactive experience:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh | bash
 ```
 
-**Use when:**
-- You've customized existing agents/commands
-- You only want to add new components
-- You're updating and want to keep your changes
+**Interactive Flow:**
+1. **Choose Installation Location**
+   - Local (`.opencode/` in current directory)
+   - Global (`~/.config/opencode/`)
+   - Custom (enter any path)
+
+2. **Choose Installation Mode**
+   - Quick Install (select a profile)
+   - Custom Install (pick individual components)
+   - List Available Components
+
+3. **Select Components** (if custom mode)
+   - Choose from agents, subagents, commands, tools, contexts, config
 
-**Example:**
+4. **Review & Confirm**
+   - See what will be installed
+   - Confirm installation directory
+   - Proceed or cancel
+
+### 2. Profile-Based Installation (Quick Setup)
+
+Install a pre-configured set of components:
+
+```bash
+# Essential - Minimal setup with core agents
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) essential
+
+# Developer - Code-focused development tools
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) developer
+
+# Business - Content and business-focused tools
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) business
+
+# Full - Everything except system-builder
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) full
+
+# Advanced - Complete system with all components
+bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) advanced
 ```
-Selected: 10 components
-Existing: 5 files
-Result: 5 new files installed, 5 existing files untouched
+
+### 3. Download & Run (For Offline or Repeated Use)
+
+```bash
+# Download the installer
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh -o install.sh
+
+# Make it executable
+chmod +x install.sh
+
+# Run interactively
+./install.sh
+
+# Or with a profile
+./install.sh developer
 ```
 
 ---
 
-#### Option 2: Overwrite All (Use with Caution)
+## Installation Locations
+
+### Local Installation (Default)
+
+Installs to `.opencode/` in your current directory.
+
+**Best for:**
+- Project-specific agents
+- Testing and development
+- Multiple isolated installations
+
+```bash
+# Default behavior
+./install.sh developer
+
+# Explicit local installation
+./install.sh developer --install-dir .opencode
+```
+
+**Result:**
 ```
-⚠️  Replace ALL existing files with new versions
-⚠️  Your customizations will be LOST
-⚠️  Requires confirmation (type 'yes')
+your-project/
+├── .opencode/
+│   ├── agent/
+│   ├── command/
+│   ├── context/
+│   └── tool/
+└── your-project-files...
 ```
 
-**Use when:**
-- You want the latest versions of everything
-- You haven't made customizations
-- You want to reset to defaults
+### Global Installation
+
+Installs to `~/.config/opencode/` for user-wide access.
+
+**Best for:**
+- System-wide agent availability
+- Single installation for all projects
+- Consistent agent versions
 
-**Example:**
+```bash
+# Using CLI argument
+./install.sh developer --install-dir ~/.config/opencode
+
+# Using environment variable
+export OPENCODE_INSTALL_DIR=~/.config/opencode
+./install.sh developer
+```
+
+**Result:**
+```
+~/.config/
+└── opencode/
+    ├── agent/
+    ├── command/
+    ├── context/
+    └── tool/
 ```
-Selected: 10 components
-Existing: 5 files
-Result: All 10 files installed (5 overwritten, 5 new)
+
+### Custom Installation
+
+Install to any directory you choose.
+
+**Best for:**
+- Custom organizational structures
+- Shared team installations
+- Non-standard setups
+
+```bash
+# Custom path
+./install.sh developer --install-dir ~/my-agents
+
+# Path with spaces (use quotes)
+./install.sh developer --install-dir "~/My Agents/opencode"
+
+# Absolute path
+./install.sh developer --install-dir /opt/opencode
 ```
 
 ---
 
-#### Option 3: Backup & Overwrite (Safe Update)
+## Installation Directory Options
+
+### CLI Argument
+
+Use `--install-dir` to specify installation directory:
+
+```bash
+# Format 1: --install-dir=PATH
+./install.sh developer --install-dir=~/.config/opencode
+
+# Format 2: --install-dir PATH
+./install.sh developer --install-dir ~/.config/opencode
+```
+
+### Environment Variable
+
+Set `OPENCODE_INSTALL_DIR` for persistent configuration:
+
+```bash
+# Set once, use multiple times
+export OPENCODE_INSTALL_DIR=~/.config/opencode
+
+# Now all installations use this directory
+./install.sh developer
+./install.sh --list
 ```
-✅ Backs up existing files to .opencode.backup.{timestamp}/
-✅ Then installs new versions
-✅ You can restore from backup if needed
-✅ Best of both worlds
+
+**Add to your shell profile for persistence:**
+```bash
+# ~/.bashrc or ~/.zshrc
+export OPENCODE_INSTALL_DIR=~/.config/opencode
 ```
 
-**Use when:**
-- You want new versions but want to keep a backup
-- You're not sure if you've customized files
-- You want the ability to restore
+### Interactive Selection
+
+When running in interactive mode, you'll be prompted to choose:
 
-**Example:**
 ```
-Selected: 10 components
-Existing: 5 files
-Result: 
-  - 5 files backed up to .opencode.backup.20251118-143022/
-  - All 10 files installed (5 updated, 5 new)
+Choose installation location:
+
+  1) Local - Install to .opencode/ in current directory
+     (Best for project-specific agents)
+     
+  2) Global - Install to ~/.config/opencode/
+     (Best for user-wide agents available everywhere)
+     
+  3) Custom - Enter exact path
+     Examples:
+       Linux/Mac:  /home/user/my-agents or ~/my-agents
+       Windows:    C:/Users/user/my-agents or ~/my-agents
+     
+Enter your choice [1-3]:
 ```
 
-**Restore from backup:**
+### Priority Order
+
+Installation directory is determined by (highest to lowest priority):
+
+1. `--install-dir` CLI argument
+2. `OPENCODE_INSTALL_DIR` environment variable
+3. Interactive selection (if in interactive mode)
+4. Default: `.opencode`
+
+---
+
+## Platform-Specific Installation
+
+### Linux
+
 ```bash
-# View backup
-ls -la .opencode.backup.*/
+# Standard installation
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh | bash -s developer
 
-# Restore specific file
-cp .opencode.backup.20251118-143022/.opencode/agent/my-agent.md .opencode/agent/
+# Global installation
+./install.sh developer --install-dir ~/.config/opencode
 
-# Restore all
-rm -rf .opencode
-mv .opencode.backup.20251118-143022/.opencode .opencode
+# System-wide (requires sudo)
+sudo ./install.sh developer --install-dir /opt/opencode
 ```
 
----
+### macOS
+
+```bash
+# Standard installation
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh | bash -s developer
 
-#### Option 4: Cancel
+# Global installation (XDG standard)
+./install.sh developer --install-dir ~/.config/opencode
+
+# macOS native location
+./install.sh developer --install-dir ~/Library/Application\ Support/opencode
 ```
-❌ Exit without making any changes
+
+### Windows (Git Bash)
+
+```bash
+# Standard installation
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh | bash -s developer
+
+# Global installation
+./install.sh developer --install-dir ~/.config/opencode
+
+# Windows-style path
+./install.sh developer --install-dir C:/Users/username/opencode
 ```
 
-**Use when:**
-- You need to review what would be changed
-- You want to manually backup first
-- You're not ready to proceed
+### Windows (WSL)
+
+```bash
+# Same as Linux
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh | bash -s developer
+
+# Global installation
+./install.sh developer --install-dir ~/.config/opencode
+```
 
 ---
 
-## Example Session
+## Available Profiles
+
+### Essential
+**Minimal setup with core agents**
+
+Components:
+- Core agents: openagent
+- Essential contexts
+- Basic configuration
 
 ```bash
-$ bash <(curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh) --developer
+./install.sh essential
+```
+
+### Developer
+**Code-focused development tools**
+
+Components:
+- Development agents: codebase-agent, task-manager
+- Code subagents: reviewer, tester, coder-agent, build-agent
+- Development commands: test, commit, context
+- Development tools and contexts
 
-╔════════════════════════════════════════════════════════════════╗
-║                                                                ║
-║           OpenAgents Installer v1.0.0                    ║
-║                                                                ║
-╚════════════════════════════════════════════════════════════════╝
+```bash
+./install.sh developer
+```
 
-▶ Checking dependencies...
-✓ All dependencies found
+### Business
+**Content and business-focused tools**
 
-▶ Fetching component registry...
-✓ Registry fetched successfully
+Components:
+- Business agents
+- Content creation tools
+- Documentation agents
+- Business contexts
 
-▶ Installation Preview
+```bash
+./install.sh business
+```
 
-Profile: developer
+### Full
+**Everything except system-builder**
 
-Components to install (22 total):
+Components:
+- All agents and subagents
+- All commands
+- All tools
+- All contexts
+- All configuration
 
-Agents (4): task-manager codebase-agent image-specialist workflow-orchestrator
-Subagents (6): reviewer tester documentation coder-agent build-agent codebase-pattern-analyst
-Commands (6): test commit context clean optimize prompt-enhancer
-Tools (2): env gemini
-Contexts (2): essential-patterns project-context
-Config (2): env-example readme
+```bash
+./install.sh full
+```
 
-Proceed with installation? [Y/n]: y
+### Advanced
+**Complete system with all components**
 
-▶ Preparing installation...
+Components:
+- Everything in Full profile
+- System-builder agents
+- Advanced configuration
+- Complete toolset
 
-▶ Checking for file collisions...
+```bash
+./install.sh advanced
+```
 
-⚠ Found 8 file collision(s):
+---
 
-  Agents (2):
-    .opencode/agent/task-manager.md
-    .opencode/agent/codebase-agent.md
-  Subagents (3):
-    .opencode/agent/subagents/reviewer.md
-    .opencode/agent/subagents/tester.md
-    .opencode/agent/subagents/coder-agent.md
-  Commands (2):
-    .opencode/command/test.md
-    .opencode/command/commit.md
-  Context (1):
-    .opencode/context/core/essential-patterns.md
+## Post-Installation
 
-How would you like to proceed?
+### 1. Verify Installation
 
-  1) Skip existing - Only install new files, keep all existing files unchanged
-  2) Overwrite all - Replace existing files with new versions (your changes will be lost)
-  3) Backup & overwrite - Backup existing files, then install new versions
-  4) Cancel - Exit without making changes
+```bash
+# Check installed files
+ls -la .opencode/
 
-Enter your choice [1-4]: 1
+# Or for global installation
+ls -la ~/.config/opencode/
+```
 
-▶ Installing components...
+### 2. Configure Environment
 
-✓ Installed agent: image-specialist
-✓ Installed agent: workflow-orchestrator
-ℹ Skipped existing: agent:task-manager
-ℹ Skipped existing: agent:codebase-agent
-ℹ Skipped existing: subagent:reviewer
-ℹ Skipped existing: subagent:tester
-✓ Installed subagent: documentation
-ℹ Skipped existing: subagent:coder-agent
-✓ Installed subagent: build-agent
-✓ Installed subagent: codebase-pattern-analyst
-ℹ Skipped existing: command:test
-ℹ Skipped existing: command:commit
-✓ Installed command: context
-✓ Installed command: clean
-✓ Installed command: optimize
-✓ Installed command: prompt-enhancer
-✓ Installed tool: env
-✓ Installed tool: gemini
-ℹ Skipped existing: context:essential-patterns
-✓ Installed context: project-context
-✓ Installed config: env-example
-✓ Installed config: readme
+```bash
+# Copy example environment file
+cp env.example .env
 
-✓ Installation complete!
-  Installed: 14
-  Skipped: 8
+# Edit with your settings
+nano .env
+```
 
-▶ Next Steps
+### 3. Start Using OpenCode
 
-1. Review the installed components in .opencode/
-2. Copy env.example to .env and configure:
-   cp env.example .env
-3. Start using OpenCode agents:
-   opencode
+```bash
+# Run OpenCode CLI
+opencode
 
-ℹ Documentation: https://github.com/darrenhinde/OpenAgents
+# Or use specific agents/commands
+# (depends on your OpenCode CLI setup)
 ```
 
 ---
 
-## Collision Report Details
+## Collision Handling
+
+When installing into an existing directory, the installer detects file collisions and offers 4 options:
+
+### Option 1: Skip Existing (Safest)
+- Only install new files
+- Keep all existing files unchanged
+- Your customizations are preserved
+
+### Option 2: Overwrite All (Destructive)
+- Replace all existing files with new versions
+- Your customizations will be lost
+- Requires confirmation
+
+### Option 3: Backup & Overwrite (Recommended)
+- Backs up existing files to `.opencode.backup.{timestamp}/`
+- Then installs new versions
+- You can restore from backup if needed
 
-The collision report groups files by type for easy review:
+### Option 4: Cancel
+- Exit without making changes
 
-| Category | Location | Description |
-|----------|----------|-------------|
-| **Agents** | `.opencode/agent/*.md` | Main orchestrator agents |
-| **Subagents** | `.opencode/agent/subagents/*.md` | Specialized worker agents |
-| **Commands** | `.opencode/command/*.md` | Slash commands |
-| **Tools** | `.opencode/tool/*/` | Tool implementations |
-| **Plugins** | `.opencode/plugin/*.ts` | Plugin integrations |
-| **Context** | `.opencode/context/**/*.md` | Context files |
-| **Config** | Root level files | Configuration files |
+**See [Collision Handling Guide](collision-handling.md) for detailed information.**
 
 ---
 
-## Best Practices
+## Updating Installations
 
-### For First-Time Installation
-- No collisions will be detected
-- All files install cleanly
-- No strategy selection needed
+### Add New Components
 
-### For Updates (Adding New Components)
-- **Use Option 1 (Skip existing)** - Safest choice
-- Only new components are added
-- Your customizations are preserved
+```bash
+# Run installer again with "Skip existing" option
+./install.sh developer
+
+# When prompted for collision handling, choose:
+# Option 1: Skip existing
+```
 
-### For Full Refresh
-- **Use Option 3 (Backup & overwrite)** - Safest for updates
-- Get latest versions of everything
-- Keep backup just in case
+Only new components will be installed, existing files remain unchanged.
 
-### For Clean Slate
-- **Use Option 2 (Overwrite all)** - Only if you're sure
-- Resets everything to defaults
-- Requires explicit confirmation
+### Update All Components
 
----
+```bash
+# Run installer with "Backup & overwrite" option
+./install.sh developer
 
-## Technical Details
+# When prompted for collision handling, choose:
+# Option 3: Backup & overwrite
+```
+
+All components updated, backup created for safety.
 
-### What Gets Checked
-- All files in the selected components list
-- Paths are resolved from `registry.json`
-- Only actual file existence is checked (not content)
+### Migrate to Different Location
 
-### What Gets Backed Up (Option 3)
-- Only files that would be overwritten
-- Preserves directory structure
-- Timestamped folder: `.opencode.backup.YYYYMMDD-HHMMSS/`
+```bash
+# Option 1: Move existing installation
+mv .opencode ~/.config/opencode
 
-### What Gets Skipped (Option 1)
-- Any file that already exists
-- Reported in "Skipped" count
-- Logged with component type and ID
+# Option 2: Fresh install to new location
+./install.sh developer --install-dir ~/.config/opencode
+```
 
 ---
 
 ## Troubleshooting
 
-### "I chose skip but want to update one file"
+### Dependencies Missing
+
+**Error:** `curl: command not found` or `jq: command not found`
+
+**Solution:**
+```bash
+# macOS
+brew install curl jq
+
+# Ubuntu/Debian
+sudo apt-get install curl jq
+
+# Fedora/RHEL
+sudo dnf install curl jq
+
+# Arch Linux
+sudo pacman -S curl jq
+```
+
+### Permission Denied
+
+**Error:** `Permission denied` when creating directories
+
+**Solution:**
+```bash
+# Install to a directory you own
+./install.sh developer --install-dir ~/opencode
+
+# Or create parent directory first
+mkdir -p ~/.config
+./install.sh developer --install-dir ~/.config/opencode
+```
+
+### Path with Spaces
+
+**Error:** Installation fails with paths containing spaces
+
+**Solution:**
+```bash
+# Quote the path
+./install.sh developer --install-dir "~/My Agents/opencode"
+```
+
+### Parent Directory Doesn't Exist
+
+**Error:** `Parent directory does not exist`
+
+**Solution:**
+```bash
+# Create parent directory first
+mkdir -p ~/.config
+
+# Then install
+./install.sh developer --install-dir ~/.config/opencode
+```
+
+### Bash Version Too Old
+
+**Error:** `This script requires Bash 3.2 or higher`
+
+**Solution:**
+```bash
+# Check your bash version
+bash --version
+
+# macOS: Install newer bash via Homebrew
+brew install bash
+
+# Linux: Update bash via package manager
+sudo apt-get update && sudo apt-get upgrade bash
+```
+
+---
+
+## Advanced Usage
+
+### View Available Components
+
+```bash
+# List all components without installing
+./install.sh --list
+```
+
+### Get Help
+
+```bash
+# Show all options and examples
+./install.sh --help
+```
+
+### Specify Git Branch
+
+```bash
+# Install from a different branch
+export OPENCODE_BRANCH=develop
+./install.sh developer
+```
+
+### Non-Interactive Installation (CI/CD)
+
+```bash
+# Set environment variables for automation
+export OPENCODE_INSTALL_DIR=/opt/opencode
+export OPENCODE_BRANCH=main
+
+# Run with profile (no prompts)
+./install.sh developer
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `OPENCODE_INSTALL_DIR` | Installation directory | `.opencode` | `~/.config/opencode` |
+| `OPENCODE_BRANCH` | Git branch to install from | `main` | `develop` |
+
+---
+
+## Examples
+
+### Example 1: First-Time Local Installation
+```bash
+# Download and run installer
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh | bash -s developer
+
+# Result: Installs to .opencode/ in current directory
+```
+
+### Example 2: Global Installation for All Projects
 ```bash
-# Delete the specific file first
-rm .opencode/agent/task-manager.md
+# Install to global config directory
+./install.sh developer --install-dir ~/.config/opencode
 
-# Run installer again with skip mode
-# Only the deleted file will be reinstalled
+# Now available to all projects
 ```
 
-### "I chose overwrite by accident"
+### Example 3: Team Shared Installation
 ```bash
-# If you chose Option 3 (backup), restore from backup:
-cp .opencode.backup.*/path/to/file .opencode/path/to/file
+# Install to shared directory
+sudo ./install.sh full --install-dir /opt/opencode
 
-# If you chose Option 2 (overwrite), check git history:
-git checkout HEAD -- .opencode/
+# Team members can access from /opt/opencode
 ```
 
-### "I want to see what changed"
+### Example 4: Multiple Installations
 ```bash
-# If you have a backup:
-diff .opencode/agent/my-agent.md .opencode.backup.*/agent/my-agent.md
+# Project A - local installation
+cd ~/projects/project-a
+./install.sh developer
+
+# Project B - different local installation
+cd ~/projects/project-b
+./install.sh business
 
-# If you have git:
-git diff .opencode/
+# Each project has its own .opencode/ directory
 ```
 
-### "I want to merge changes manually"
+### Example 5: Update Existing Installation
 ```bash
-# Use Option 3 to create backup
-# Then manually merge:
-vimdiff .opencode/agent/my-agent.md .opencode.backup.*/agent/my-agent.md
+# Run installer again
+./install.sh developer
+
+# Choose "Skip existing" to add only new components
+# Or "Backup & overwrite" to update everything
 ```
 
 ---
 
-## Future Enhancements
+## Next Steps
+
+After installation:
+
+1. **Review Components**
+   ```bash
+   ls -la .opencode/
+   ```
+
+2. **Configure Environment**
+   ```bash
+   cp env.example .env
+   nano .env
+   ```
+
+3. **Read Documentation**
+   - [Collision Handling](collision-handling.md)
+   - [Platform Compatibility](platform-compatibility.md)
+   - [Building with OpenCode](../guides/building-with-opencode.md)
+
+4. **Start Using OpenCode**
+   ```bash
+   opencode
+   ```
+
+---
 
-Potential improvements for future versions:
+## Getting Help
 
-- [ ] Per-file selection (interactive mode)
-- [ ] Diff preview before overwriting
-- [ ] Smart merge for specific file types
-- [ ] Version detection and upgrade paths
-- [ ] Rollback command
-- [ ] Dry-run mode (show what would happen)
+- **View installer help:** `./install.sh --help`
+- **List components:** `./install.sh --list`
+- **Documentation:** [GitHub Repository](https://github.com/darrenhinde/OpenAgents)
+- **Report issues:** [GitHub Issues](https://github.com/darrenhinde/OpenAgents/issues)
 
 ---
 
 ## Summary
 
-The collision handling system provides:
+The OpenAgents installer provides:
 
-✅ **Safety** - Never overwrites without asking  
-✅ **Flexibility** - Multiple strategies for different needs  
-✅ **Transparency** - Clear reporting of what will change  
-✅ **Recoverability** - Backup option for peace of mind  
-✅ **Simplicity** - Easy to understand and use  
+✅ **Flexible installation locations** - Local, global, or custom  
+✅ **Multiple installation methods** - Interactive, profile-based, or custom  
+✅ **Cross-platform support** - Linux, macOS, Windows  
+✅ **Safe updates** - Collision detection and backup options  
+✅ **Easy to use** - Simple commands, clear prompts  
 
-Choose the strategy that fits your situation, and install with confidence!
+Choose the installation method that fits your needs and get started with OpenAgents!

docs/getting-started/platform-compatibility.md

@@ -151,6 +151,7 @@ wsl bash install.sh core
 |----------|--------------|--------|-------|
 | macOS 13+ | 3.2.57 | ✅ Pass | Default system bash |
 | macOS 13+ | 5.2 (Homebrew) | ✅ Pass | Upgraded bash |
+| Ubuntu 24.04 | 5.2.21 | ✅ Pass | Fixed in v1.1.0 |
 | Ubuntu 22.04 | 5.1.16 | ✅ Pass | Default |
 | Ubuntu 20.04 | 5.0.17 | ✅ Pass | Default |
 | Debian 11 | 5.1.4 | ✅ Pass | Default |
@@ -172,11 +173,24 @@ The installer is specifically designed to work with bash 3.2 (macOS default):
 ✅ **POSIX-compliant** - Avoids bash 4+ specific features  
 ✅ **Array operations** - Uses bash 3.2 compatible syntax  
 
+### Bash 5.x Compatibility (Fixed in v1.1.0)
+The installer now works correctly with bash 5.x (Ubuntu 24.04, modern Linux):
+
+✅ **set -e compatible arithmetic** - Uses `variable=$((variable + 1))` instead of `((variable++))`  
+✅ **No premature exits** - Fixed issue where counters starting at 0 caused script exit  
+✅ **Tested on bash 5.2.21** - Fully compatible with Ubuntu 24.04 and newer systems  
+
+**What was fixed:**
+- Changed all arithmetic increment operations from `((variable++))` to `variable=$((variable + 1))`
+- This prevents `set -e` from triggering exit when variables start at 0
+- Maintains error detection while ensuring compatibility across all bash versions
+
 ### Cross-Platform Features
 ✅ **Platform detection** - Automatically detects macOS/Linux/Windows  
 ✅ **Color support detection** - Disables colors on unsupported terminals  
-✅ **Path handling** - Works with Unix and Windows paths  
+✅ **Path handling** - Works with Unix and Windows paths (tilde expansion, backslash conversion)  
 ✅ **Line endings** - Handles both LF and CRLF  
+✅ **Custom install directories** - Supports local, global, and custom installation paths  
 
 ---
 
@@ -213,12 +227,27 @@ The test checks:
 
 ## Troubleshooting
 
+### Script exits immediately on Ubuntu 24.04 / bash 5.x
+**Cause:** Older versions of the installer had a `set -e` compatibility issue with bash 5.x  
+**Status:** ✅ **FIXED in v1.1.0**  
+**Solution:** Update to the latest installer:
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh > install.sh
+bash install.sh developer
+```
+
+**Technical Details:**
+- Issue: `((variable++))` returns 0 when variable is 0, triggering `set -e` exit in bash 5.x
+- Fix: Changed to `variable=$((variable + 1))` which is safe with `set -e`
+- Affected: Ubuntu 24.04 (bash 5.2.21) and other modern Linux distributions
+- All arithmetic operations now use the safe pattern
+
 ### "mapfile: command not found"
 **Cause:** Using bash version < 4.0  
 **Solution:** This should be fixed in the latest version. Update the installer:
 ```bash
 curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/install.sh > install.sh
-bash install.sh core
+bash install.sh developer
 ```
 
 ### "curl: command not found"