refactor(paths): Use /opt/qubinode_navigator as canonical installation path

Replace all hardcoded /root/qubinode_navigator paths with dynamic
QUBINODE_HOME environment variable support. This enables:

- Non-root user deployments (e.g., /home/lab-user/qubinode_navigator)
- Custom installation paths (e.g., /opt/qubinode_navigator)
- Automatic migration from $HOME/qubinode_navigator to /opt

Key changes:
- Add QUBINODE_HOME setup with migration logic to deploy-qubinode.sh
- Update all shell scripts with QUBINODE_HOME detection and fallbacks
- Update Python plugins to use os.environ.get('QUBINODE_HOME', '/opt/...')
- Update config files to use /opt/qubinode_navigator default
- Update docker-compose.yml to use ${QUBINODE_HOME:-/opt/...} for mounts
- Update all documentation to reference /opt/qubinode_navigator

Migration behavior:
1. If QUBINODE_HOME env var is set, use that path
2. If /opt/qubinode_navigator doesn't exist but $HOME/qubinode_navigator
   does, automatically migrate (copy) to /opt
3. Fallback to script directory if running from git checkout

Fixes #190

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

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: tosin2013

.env.example

@@ -23,6 +23,20 @@ QUBINODE_ADMIN_USER=admin
 # Used to identify your Qubinode cluster
 QUBINODE_CLUSTER_NAME=qubinode
 
+# =============================================================================
+# INSTALLATION PATH
+# =============================================================================
+
+# Qubinode Navigator installation directory
+# Default: /opt/qubinode_navigator
+#
+# If not set, scripts will:
+#   1. Use /opt/qubinode_navigator as the canonical location
+#   2. Auto-migrate from $HOME/qubinode_navigator if /opt doesn't exist
+#
+# Override only if you need a custom installation path
+# QUBINODE_HOME=/opt/qubinode_navigator
+
 # =============================================================================
 # DEPLOYMENT CONFIGURATION
 # =============================================================================

AGENTS.md

@@ -30,9 +30,9 @@ When starting a session, **automatically detect** the current environment by che
 
 ```bash
 # 1. Check if running on a Qubinode host
-if [ -f "/root/qubinode_navigator/.env" ]; then
+if [ -f "/opt/qubinode_navigator/.env" ]; then
     echo "Running on Qubinode host"
-    source /root/qubinode_navigator/.env
+    source /opt/qubinode_navigator/.env
 fi
 
 # 2. Detect OS
@@ -49,7 +49,7 @@ curl -s localhost:8889/health         # MCP Server running
 
 | Environment          | Indicators                       | Key Paths                             |
 | -------------------- | -------------------------------- | ------------------------------------- |
-| **Development Host** | Has `.env`, libvirtd running     | `/root/qubinode_navigator/`           |
+| **Development Host** | Has `.env`, libvirtd running     | `/opt/qubinode_navigator/`           |
 | **Remote/SSH**       | No local `.env`, SSH connection  | Clone repo first                      |
 | **Container**        | Running inside Airflow container | `/opt/airflow/`, SSH to host for kcli |
 | **CI/CD**            | GitHub Actions context vars      | Use test fixtures                     |
@@ -542,7 +542,7 @@ ______________________________________________________________________
 
 ```bash
 # All services status
-cd /root/qubinode_navigator/airflow
+cd /opt/qubinode_navigator/airflow
 podman-compose ps
 
 # Logs
@@ -837,7 +837,7 @@ export QUBINODE_HOME=/path/to/qubinode_navigator
 
 This allows the same configurations to work whether:
 
-- Running as root (`/root/qubinode_navigator`)
+- Running as root (`/opt/qubinode_navigator`)
 - Running as regular user (`$HOME/qubinode_navigator`)
 - Custom installation path (set `QUBINODE_HOME`)
 

MCP-QUICK-START.md

@@ -115,10 +115,10 @@ ______________________________________________________________________
 podman ps --filter "name=airflow"
 
 # View MCP config
-cat /root/qubinode_navigator/airflow/.env | grep MCP
+cat /opt/qubinode_navigator/airflow/.env | grep MCP
 
 # Restart if needed
-cd /root/qubinode_navigator/airflow && podman-compose restart
+cd /opt/qubinode_navigator/airflow && podman-compose restart
 
 # View logs
 podman logs -f airflow_airflow-webserver_1 | grep MCP

MCP-SERVER-GUIDE.md

@@ -23,7 +23,7 @@ Qubinode Navigator provides two Model Context Protocol (MCP) servers that enable
 
 ```bash
 # Start Airflow with MCP enabled
-cd /root/qubinode_navigator/airflow
+cd /opt/qubinode_navigator/airflow
 podman-compose --profile mcp up -d
 
 # Verify servers are running
@@ -185,14 +185,14 @@ Configure keys in the respective `.env` files or environment variables.
 ### Test Airflow MCP
 
 ```bash
-cd /root/qubinode_navigator
+cd /opt/qubinode_navigator
 ansible-playbook tests/mcp/test_airflow_mcp.yml
 ```
 
 ### Test AI Assistant MCP
 
 ```bash
-cd /root/qubinode_navigator/ai-assistant
+cd /opt/qubinode_navigator/ai-assistant
 ./test-fastmcp-poc.sh
 ```
 
@@ -218,7 +218,7 @@ netstat -tuln | grep 8889
 podman logs airflow-mcp-server
 
 # Restart server
-cd /root/qubinode_navigator/airflow
+cd /opt/qubinode_navigator/airflow
 podman-compose restart airflow-mcp-server
 ```
 

ai-assistant/LLAMA_CPP_FIX.md

@@ -43,7 +43,7 @@ The running container was built from an older version of the code that expected
 ### Option 1: Rebuild Container (Recommended)
 
 ```bash
-cd /root/qubinode_navigator/ai-assistant
+cd /opt/qubinode_navigator/ai-assistant
 ./rebuild-container.sh
 ```
 

ai-assistant/scripts/download-model.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 
 # Configuration
 MODEL_URL="https://huggingface.co/ibm-granite/granite-4.0-micro-GGUF/resolve/main/granite-4.0-micro-Q4_K_M.gguf"
-MODEL_DIR="/root/qubinode_navigator/ai-assistant/models"
+MODEL_DIR="/opt/qubinode_navigator/ai-assistant/models"
 MODEL_FILE="granite-4.0-micro.gguf"
 MODEL_PATH="${MODEL_DIR}/${MODEL_FILE}"
 

ai-assistant/scripts/fetch-kcli-docs.py

@@ -16,7 +16,7 @@
 class KcliDocsFetcher:
     """Fetches and prepares kcli documentation for RAG ingestion"""
 
-    def __init__(self, output_dir: str = "/root/qubinode_navigator/ai-assistant/data/kcli-docs"):
+    def __init__(self, output_dir: str = "/opt/qubinode_navigator/ai-assistant/data/kcli-docs"):
         self.output_dir = Path(output_dir)
         self.output_dir.mkdir(parents=True, exist_ok=True)
 

ai-assistant/scripts/prepare-rag-docs.py

@@ -357,7 +357,7 @@ def get_default_input_dir() -> str:
 
     # Check common locations
     common_paths = [
-        "/root/qubinode_navigator",
+        "/opt/qubinode_navigator",
         "/opt/qubinode_navigator",
         Path.home() / "qubinode_navigator",
     ]

ai-assistant/src/agents/context.py

@@ -68,7 +68,7 @@ def __init__(self):
         self.rag_service = None
         self.lineage_service = None
         self.adrs_loaded = False
-        self.project_root = Path(os.getenv("QUBINODE_ROOT", "/root/qubinode_navigator"))
+        self.project_root = Path(os.getenv("QUBINODE_ROOT", "/opt/qubinode_navigator"))
         self.data_dir = Path(os.getenv("RAG_DATA_DIR", "/app/data"))
 
     async def initialize(

ai-assistant/src/agents/developer.py

@@ -50,7 +50,7 @@ class DeveloperDependencies(AgentDependencies):
     aider_model: str = "claude-sonnet-4-20250514"  # Model for Aider via LiteLLM
 
     # Working directory for code changes
-    working_directory: str = "/root/qubinode_navigator"
+    working_directory: str = "/opt/qubinode_navigator"
 
     # Provider cache for Provider-First Rule checks
     provider_cache: dict = {}