Add global installation capability and fix venv accessibility issue

- Add make install-global target with intelligent installation methods
- Support pipx (recommended), pip --user, and fallback options
- Resolve issue where kaizen-agentic was only available in local venv
- Update documentation to clearly explain 4 installation options:
  - Development mode (local venv)
  - Global installation (any directory)
  - Local package testing (local venv)
  - Future PyPI installation
- CLI now available globally from any directory after make install-global

Fixes the core issue where users couldn't access kaizen-agentic from other repos.

🤖 Generated with [Claude Code](https://claude.ai/code)

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

Makefile

@@ -1,6 +1,6 @@
 # Makefile for Kaizen Agentic development tasks
 
-.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish release-finalize release-rollback
+.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish release-finalize release-rollback
 
 # Variables
 VENV = .venv
@@ -25,6 +25,7 @@ help:
 	@echo "  setup-verify    - Verify complete setup functionality"
 	@echo "  install-dev     - Install package in development mode"
 	@echo "  install-local   - Install from locally built package (test PyPI installation)"
+	@echo "  install-global  - Install globally from locally built package"
 	@echo "  venv-status     - Check if venv is active"
 	@echo ""
 	@echo "Standards Compliance:"
@@ -128,6 +129,77 @@ install-local: $(VENV)/bin/activate
 	echo "   source $(VENV)/bin/activate"; \
 	echo "   kaizen-agentic --help"
 
+# Install globally from locally built package
+install-global:
+	@echo "🌍 Installing kaizen-agentic globally from local package..."
+	@if [ ! -d "dist" ] || [ -z "$$(ls dist/*.whl 2>/dev/null)" ]; then \
+		echo "❌ No wheel package found in dist/"; \
+		echo "   Run 'python3 -m build' first to create the package"; \
+		echo "   Or run 'make release-prepare' for full build"; \
+		exit 1; \
+	fi; \
+	WHEEL_FILE=$$(ls dist/*.whl | head -1); \
+	VERSION=$$(basename "$$WHEEL_FILE" | sed 's/kaizen_agentic-\(.*\)-py3.*/\1/'); \
+	echo "   Installing kaizen-agentic v$$VERSION globally..."; \
+	echo ""; \
+	echo "🔧 Trying installation methods in order:"; \
+	echo ""; \
+	if command -v pipx >/dev/null 2>&1; then \
+		echo "   📦 Method 1: Using pipx (recommended)..."; \
+		pipx uninstall kaizen-agentic 2>/dev/null || true; \
+		pipx install "$$WHEEL_FILE" && \
+		echo "   ✅ Installed via pipx" && \
+		INSTALL_SUCCESS=1; \
+	else \
+		echo "   ⚠️  pipx not found, trying pip --user..."; \
+		INSTALL_SUCCESS=0; \
+	fi; \
+	if [ "$$INSTALL_SUCCESS" != "1" ]; then \
+		echo "   📦 Method 2: Using pip --user..."; \
+		python3 -m pip uninstall -y kaizen-agentic 2>/dev/null || true; \
+		if python3 -m pip install --user "$$WHEEL_FILE" --force-reinstall 2>/dev/null; then \
+			echo "   ✅ Installed via pip --user"; \
+			INSTALL_SUCCESS=1; \
+		else \
+			echo "   ⚠️  pip --user failed, trying with --break-system-packages..."; \
+		fi; \
+	fi; \
+	if [ "$$INSTALL_SUCCESS" != "1" ]; then \
+		echo "   📦 Method 3: Using pip --break-system-packages..."; \
+		python3 -m pip install --user "$$WHEEL_FILE" --force-reinstall --break-system-packages && \
+		echo "   ✅ Installed via pip with system override" && \
+		INSTALL_SUCCESS=1; \
+	fi; \
+	echo ""; \
+	if [ "$$INSTALL_SUCCESS" = "1" ]; then \
+		echo "✅ Global installation completed!"; \
+		echo "   Version: $$VERSION"; \
+		echo ""; \
+		echo "🧪 Testing global installation..."; \
+		if command -v kaizen-agentic >/dev/null 2>&1; then \
+			echo "   ✅ CLI command available globally"; \
+			kaizen-agentic --version; \
+		else \
+			echo "   ⚠️  CLI not in PATH. Add to your PATH:"; \
+			if command -v pipx >/dev/null 2>&1; then \
+				echo "   export PATH=\"$$HOME/.local/bin:$$PATH\""; \
+			else \
+				echo "   export PATH=\"$$HOME/.local/bin:$$PATH\""; \
+			fi; \
+			echo "   Add this to your ~/.bashrc or ~/.zshrc for persistence"; \
+		fi; \
+		echo ""; \
+		echo "💡 Usage:"; \
+		echo "   kaizen-agentic --help  # Available from any directory"; \
+		echo "   cd /any/other/project && kaizen-agentic list"; \
+	else \
+		echo "❌ Global installation failed!"; \
+		echo "   Manual installation options:"; \
+		echo "   1. Install pipx: python3 -m pip install --user pipx"; \
+		echo "   2. Or use: python3 -m pip install --user $$WHEEL_FILE --break-system-packages"; \
+		exit 1; \
+	fi
+
 # Ensure proper Python project structure exists
 ensure-project-structure:
 	@echo "🔍 Ensuring proper Python project structure..."

README.md

@@ -14,21 +14,32 @@ git clone https://github.com/kaizen-agentic/kaizen-agentic.git
 cd kaizen-agentic
 make setup-complete
 make agents-install-cli
-source .venv/bin/activate
+source .venv/bin/activate  # Required for each session
 ```
 
-**From Local Package (Test Installation):**
+**Global Installation (Available from any directory):**
+```bash
+git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+cd kaizen-agentic
+make setup-complete
+python3 -m build && make install-global
+# No virtual environment activation needed
+```
+
+**Local Package Testing:**
 ```bash
 git clone https://github.com/kaizen-agentic/kaizen-agentic.git
 cd kaizen-agentic
 make setup-complete
 python3 -m build && make install-local
-source .venv/bin/activate
+source .venv/bin/activate  # Required for each session
 ```
 
 **From PyPI (Coming Soon):**
 ```bash
 pip install kaizen-agentic  # Available after v1.0.0 publication
+# or
+pipx install kaizen-agentic  # Recommended for global CLI tools
 ```
 
 ### Your First Project (New Users)

docs/GETTING_STARTED.md

@@ -8,7 +8,7 @@ This guide walks you through using Kaizen Agentic agents in any project, from in
 
 ### 1. Install the Package
 
-**Option A: From Source (Current - Development Version)**
+**Option A: From Source (Development Mode)**
 
 ```bash
 # Clone the repository
@@ -18,14 +18,14 @@ cd kaizen-agentic
 # Set up development environment
 make setup-complete
 
-# Install CLI tool
+# Install CLI tool (local to project)
 make agents-install-cli
 
-# Activate virtual environment
+# Activate virtual environment (required for each session)
 source .venv/bin/activate
 ```
 
-**Option B: From Local Package (Test PyPI Installation)**
+**Option B: Local Package Testing (PyPI-equivalent)**
 
 ```bash
 # Clone the repository and build package
@@ -33,22 +33,40 @@ git clone https://github.com/kaizen-agentic/kaizen-agentic.git
 cd kaizen-agentic
 make setup-complete
 
-# Build and install from local package
+# Build and install from local package (local to project)
 python3 -m build
 make install-local
 
-# Activate virtual environment
+# Activate virtual environment (required for each session)
 source .venv/bin/activate
 ```
 
-**Option C: From PyPI (Coming Soon)**
+**Option C: Global Installation (Available from any directory)**
+
+```bash
+# Clone the repository and build package
+git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+cd kaizen-agentic
+make setup-complete
+
+# Build and install globally
+python3 -m build
+make install-global
+
+# No virtual environment activation needed
+# CLI available from any directory
+```
+
+**Option D: From PyPI (Coming Soon)**
 
 ```bash
 # Will be available once v1.0.0 is published
 pip install kaizen-agentic
+# or
+pipx install kaizen-agentic  # Recommended for global CLI tools
 ```
 
-> **📦 Release Status**: v1.0.0 is ready for publication. Test local installation with `make install-local` before PyPI publication.
+> **📦 Release Status**: v1.0.0 is ready for publication. Use `make install-global` for system-wide availability.
 
 ### 2. Verify Installation