mente-agent 0.11.0

package/scripts/install.sh

@@ -0,0 +1,1660 @@
+#!/bin/bash
+# ============================================================================
+# Mente Agent Installer
+# ============================================================================
+# Installation script for Linux, macOS, and Android/Termux.
+# Uses uv for desktop/server installs and Python's stdlib venv + pip on Termux.
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/chemany/Mente/main/scripts/install.sh | bash
+#
+# Or with options:
+#   curl -fsSL ... | bash -s -- --release latest --no-venv --skip-setup
+#
+# ============================================================================
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+MAGENTA='\033[0;35m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+BOLD='\033[1m'
+
+# Configuration
+REPO_URL_SSH="git@github.com:chemany/Mente.git"
+REPO_URL_HTTPS="https://github.com/chemany/Mente.git"
+MENTE_HOME="${MENTE_HOME:-${HERMES_HOME:-$HOME/.mente}}"
+HERMES_HOME="${HERMES_HOME:-$MENTE_HOME}"
+# INSTALL_DIR is resolved AFTER arg parsing and OS detection so we can pick an
+# FHS-style layout for root installs.  Track whether the user gave us an
+# explicit directory — if so we never override it.
+if [ -n "${HERMES_INSTALL_DIR:-}" ]; then
+    INSTALL_DIR="$HERMES_INSTALL_DIR"
+    INSTALL_DIR_EXPLICIT=true
+else
+    INSTALL_DIR=""
+    INSTALL_DIR_EXPLICIT=false
+fi
+PYTHON_VERSION="3.11"
+NODE_VERSION="22"
+
+# FHS-style root install layout (set by resolve_install_layout when applicable):
+#   code at /usr/local/lib/mente-agent, command at /usr/local/bin/mente,
+#   data still at /root/.mente (via HERMES_HOME compatibility bridge).
+#   This keeps Docker bind-mounted /root/ volumes lean.
+ROOT_FHS_LAYOUT=false
+
+# Options
+USE_VENV=true
+RUN_SETUP=true
+INSTALL_MODE="release"
+RELEASE_REF="${HERMES_RELEASE_VERSION:-latest}"
+BRANCH="main"
+RUNTIME_ARTIFACT_MANIFEST=""
+RUNTIME_WHEEL=""
+CURRENT_RELEASE_REF=""
+
+# Detect non-interactive mode (e.g. curl | bash)
+# When stdin is not a terminal, read -p will fail with EOF,
+# causing set -e to silently abort the entire script.
+if [ -t 0 ]; then
+    IS_INTERACTIVE=true
+else
+    IS_INTERACTIVE=false
+fi
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --no-venv)
+            USE_VENV=false
+            shift
+            ;;
+        --skip-setup)
+            RUN_SETUP=false
+            shift
+            ;;
+        --release)
+            INSTALL_MODE="release"
+            RELEASE_REF="$2"
+            shift 2
+            ;;
+        --branch)
+            INSTALL_MODE="source"
+            BRANCH="$2"
+            shift 2
+            ;;
+        --runtime-artifact-manifest)
+            RUNTIME_ARTIFACT_MANIFEST="$2"
+            shift 2
+            ;;
+        --runtime-wheel)
+            RUNTIME_WHEEL="$2"
+            shift 2
+            ;;
+        --dir)
+            INSTALL_DIR="$2"
+            INSTALL_DIR_EXPLICIT=true
+            shift 2
+            ;;
+        --hermes-home)
+            HERMES_HOME="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Mente Agent Installer"
+            echo ""
+            echo "Usage: install.sh [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --no-venv      Don't create virtual environment"
+            echo "  --skip-setup   Skip interactive setup wizard"
+            echo "  --release TAG  Release tag to install (default: latest)"
+            echo "  --branch NAME  Developer/source checkout branch to install (default: main)"
+            echo "  --runtime-artifact-manifest PATH  Local/offline vendored runtime artifact manifest"
+            echo "  --runtime-wheel PATH  Local/offline vendored runtime wheel to bootstrap"
+            echo "  --dir PATH     Installation directory"
+            echo "                   default (non-root):  ~/.mente/mente-agent"
+            echo "                   default (root, Linux): /usr/local/lib/mente-agent"
+            echo "  -h, --help     Show this help"
+            echo ""
+            echo "Notes:"
+            echo "  One-click end-user installs are release-pinned by default."
+            echo "  ./setup-hermes.sh is the developer/source-checkout path."
+            echo "  When running as root on Linux, Mente installs the code under"
+            echo "  /usr/local/lib/mente-agent and links the command into"
+            echo "  /usr/local/bin/mente."
+            echo "  Data, config, sessions, and logs live in \$HERMES_HOME"
+            echo "  (default bridge: /root/.mente). This keeps Docker bind-mounted volumes"
+            echo "  small and ensures the command is on PATH for all shells."
+            echo "  Existing installs at \$HERMES_HOME/mente-agent are preserved in-place."
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# ============================================================================
+# Helper functions
+# ============================================================================
+
+print_banner() {
+    echo ""
+    echo -e "${MAGENTA}${BOLD}"
+    echo "┌─────────────────────────────────────────────────────────┐"
+    echo "│              ⚕ Mente Agent Installer                    │"
+    echo "├─────────────────────────────────────────────────────────┤"
+    echo "│  An open source AI agent by Nous Research.              │"
+    echo "└─────────────────────────────────────────────────────────┘"
+    echo -e "${NC}"
+}
+
+log_info() {
+    echo -e "${CYAN}→${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}✓${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}⚠${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}✗${NC} $1"
+}
+
+prompt_yes_no() {
+    local question="$1"
+    local default="${2:-yes}"
+    local prompt_suffix
+    local answer=""
+
+    # Use case patterns (not ${var,,}) so this works on bash 3.2 (macOS /bin/bash).
+    case "$default" in
+        [yY]|[yY][eE][sS]|[tT][rR][uU][eE]|1) prompt_suffix="[Y/n]" ;;
+        *) prompt_suffix="[y/N]" ;;
+    esac
+
+    if [ "$IS_INTERACTIVE" = true ]; then
+        read -r -p "$question $prompt_suffix " answer || answer=""
+    elif [ -r /dev/tty ] && [ -w /dev/tty ]; then
+        printf "%s %s " "$question" "$prompt_suffix" > /dev/tty
+        IFS= read -r answer < /dev/tty || answer=""
+    else
+        answer=""
+    fi
+
+    answer="${answer#"${answer%%[![:space:]]*}"}"
+    answer="${answer%"${answer##*[![:space:]]}"}"
+
+    if [ -z "$answer" ]; then
+        case "$default" in
+            [yY]|[yY][eE][sS]|[tT][rR][uU][eE]|1) return 0 ;;
+            *) return 1 ;;
+        esac
+    fi
+
+    case "$answer" in
+        [yY]|[yY][eE][sS]) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+is_termux() {
+    [ -n "${TERMUX_VERSION:-}" ] || [[ "${PREFIX:-}" == *"com.termux/files/usr"* ]]
+}
+
+# Decide where the repo checkout + venv live, and where the `mente` command
+# symlink goes.  Called after detect_os so $OS/$DISTRO are known.
+#
+# Defaults:
+#   - Non-root, any OS:       INSTALL_DIR = $HERMES_HOME/mente-agent
+#                             command link in $HOME/.local/bin
+#   - Termux (any uid):       INSTALL_DIR = $HERMES_HOME/mente-agent
+#                             command link in $PREFIX/bin (already on PATH)
+#   - Root on Linux (new):    INSTALL_DIR = /usr/local/lib/mente-agent
+#                             command link in /usr/local/bin
+#                             (unless a legacy install already exists at
+#                              $HERMES_HOME/mente-agent — then preserve it)
+#
+# Always no-op when the user set --dir or $HERMES_INSTALL_DIR.
+resolve_install_layout() {
+    if [ "$INSTALL_DIR_EXPLICIT" = true ]; then
+        log_info "Install directory: $INSTALL_DIR (explicit)"
+        return 0
+    fi
+
+    # Termux: package manager manages /data/data/..., keep code in HERMES_HOME.
+    if is_termux; then
+        INSTALL_DIR="$MENTE_HOME/mente-agent"
+        return 0
+    fi
+
+    # Root on Linux: prefer FHS layout unless a legacy install already exists.
+    # macOS root installs keep the legacy layout because /usr/local/ on macOS
+    # is Homebrew territory and we don't want to fight that.
+    if [ "$OS" = "linux" ] && [ "$(id -u)" -eq 0 ]; then
+        if [ -d "$MENTE_HOME/mente-agent/.git" ]; then
+            INSTALL_DIR="$MENTE_HOME/mente-agent"
+            log_info "Existing install detected at $INSTALL_DIR — keeping legacy layout"
+            log_info "  (new root installs use /usr/local/lib/mente-agent)"
+            return 0
+        fi
+        INSTALL_DIR="/usr/local/lib/mente-agent"
+        ROOT_FHS_LAYOUT=true
+        log_info "Root install on Linux — using FHS layout"
+        log_info "  Code:    $INSTALL_DIR"
+        log_info "  Command: /usr/local/bin/mente"
+        log_info "  Data:    $HERMES_HOME (unchanged)"
+        return 0
+    fi
+
+    # Default: non-root, non-Termux → legacy user-scoped layout.
+    INSTALL_DIR="$MENTE_HOME/mente-agent"
+}
+
+get_command_link_dir() {
+    if is_termux && [ -n "${PREFIX:-}" ]; then
+        echo "$PREFIX/bin"
+    elif [ "$ROOT_FHS_LAYOUT" = true ]; then
+        echo "/usr/local/bin"
+    else
+        echo "$HOME/.local/bin"
+    fi
+}
+
+get_command_link_display_dir() {
+    if is_termux && [ -n "${PREFIX:-}" ]; then
+        echo '$PREFIX/bin'
+    elif [ "$ROOT_FHS_LAYOUT" = true ]; then
+        echo '/usr/local/bin'
+    else
+        echo '~/.local/bin'
+    fi
+}
+
+get_mente_command_path() {
+    local link_dir
+    link_dir="$(get_command_link_dir)"
+    if [ -x "$link_dir/mente" ]; then
+        echo "$link_dir/mente"
+    else
+        echo "mente"
+    fi
+}
+
+# ============================================================================
+# System detection
+# ============================================================================
+
+detect_os() {
+    case "$(uname -s)" in
+        Linux*)
+            if is_termux; then
+                OS="android"
+                DISTRO="termux"
+            else
+                OS="linux"
+                if [ -f /etc/os-release ]; then
+                    . /etc/os-release
+                    DISTRO="$ID"
+                else
+                    DISTRO="unknown"
+                fi
+            fi
+            ;;
+        Darwin*)
+            OS="macos"
+            DISTRO="macos"
+            ;;
+        CYGWIN*|MINGW*|MSYS*)
+            OS="windows"
+            DISTRO="windows"
+            log_error "Windows detected. Please use the PowerShell installer:"
+            log_info "  irm https://raw.githubusercontent.com/chemany/Mente/main/scripts/install.ps1 | iex"
+            exit 1
+            ;;
+        *)
+            OS="unknown"
+            DISTRO="unknown"
+            log_warn "Unknown operating system"
+            ;;
+    esac
+
+    log_success "Detected: $OS ($DISTRO)"
+}
+
+# ============================================================================
+# Dependency checks
+# ============================================================================
+
+install_uv() {
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Termux detected — using Python's stdlib venv + pip instead of uv"
+        UV_CMD=""
+        return 0
+    fi
+
+    log_info "Checking for uv package manager..."
+
+    # Check common locations for uv
+    if command -v uv &> /dev/null; then
+        UV_CMD="uv"
+        UV_VERSION=$($UV_CMD --version 2>/dev/null)
+        log_success "uv found ($UV_VERSION)"
+        return 0
+    fi
+
+    # Check ~/.local/bin (default uv install location) even if not on PATH yet
+    if [ -x "$HOME/.local/bin/uv" ]; then
+        UV_CMD="$HOME/.local/bin/uv"
+        UV_VERSION=$($UV_CMD --version 2>/dev/null)
+        log_success "uv found at ~/.local/bin ($UV_VERSION)"
+        return 0
+    fi
+
+    # Check ~/.cargo/bin (alternative uv install location)
+    if [ -x "$HOME/.cargo/bin/uv" ]; then
+        UV_CMD="$HOME/.cargo/bin/uv"
+        UV_VERSION=$($UV_CMD --version 2>/dev/null)
+        log_success "uv found at ~/.cargo/bin ($UV_VERSION)"
+        return 0
+    fi
+
+    # Install uv
+    log_info "Installing uv (fast Python package manager)..."
+    if curl -LsSf https://astral.sh/uv/install.sh | sh 2>/dev/null; then
+        # uv installs to ~/.local/bin by default
+        if [ -x "$HOME/.local/bin/uv" ]; then
+            UV_CMD="$HOME/.local/bin/uv"
+        elif [ -x "$HOME/.cargo/bin/uv" ]; then
+            UV_CMD="$HOME/.cargo/bin/uv"
+        elif command -v uv &> /dev/null; then
+            UV_CMD="uv"
+        else
+            log_error "uv installed but not found on PATH"
+            log_info "Try adding ~/.local/bin to your PATH and re-running"
+            exit 1
+        fi
+        UV_VERSION=$($UV_CMD --version 2>/dev/null)
+        log_success "uv installed ($UV_VERSION)"
+    else
+        log_error "Failed to install uv"
+        log_info "Install manually: https://docs.astral.sh/uv/getting-started/installation/"
+        exit 1
+    fi
+}
+
+check_python() {
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Checking Termux Python..."
+        if command -v python >/dev/null 2>&1; then
+            PYTHON_PATH="$(command -v python)"
+            if "$PYTHON_PATH" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' 2>/dev/null; then
+                PYTHON_FOUND_VERSION="$("$PYTHON_PATH" --version 2>/dev/null)"
+                log_success "Python found: $PYTHON_FOUND_VERSION"
+                return 0
+            fi
+        fi
+
+        log_info "Installing Python via pkg..."
+        pkg install -y python >/dev/null
+        PYTHON_PATH="$(command -v python)"
+        PYTHON_FOUND_VERSION="$("$PYTHON_PATH" --version 2>/dev/null)"
+        log_success "Python installed: $PYTHON_FOUND_VERSION"
+        return 0
+    fi
+
+    log_info "Checking Python $PYTHON_VERSION..."
+
+    # Let uv handle Python — it can download and manage Python versions
+    # First check if a suitable Python is already available
+    if PYTHON_PATH="$("$UV_CMD" python find "$PYTHON_VERSION" 2>/dev/null)"; then
+        PYTHON_FOUND_VERSION="$("$PYTHON_PATH" --version 2>/dev/null)"
+        log_success "Python found: $PYTHON_FOUND_VERSION"
+        return 0
+    fi
+
+    # Python not found — use uv to install it (no sudo needed!)
+    log_info "Python $PYTHON_VERSION not found, installing via uv..."
+    if "$UV_CMD" python install "$PYTHON_VERSION"; then
+        PYTHON_PATH="$("$UV_CMD" python find "$PYTHON_VERSION")"
+        PYTHON_FOUND_VERSION="$("$PYTHON_PATH" --version 2>/dev/null)"
+        log_success "Python installed: $PYTHON_FOUND_VERSION"
+    else
+        log_error "Failed to install Python $PYTHON_VERSION"
+        log_info "Install Python $PYTHON_VERSION manually, then re-run this script"
+        exit 1
+    fi
+}
+
+check_git() {
+    log_info "Checking Git..."
+
+    if command -v git &> /dev/null; then
+        GIT_VERSION=$(git --version | awk '{print $3}')
+        log_success "Git $GIT_VERSION found"
+        return 0
+    fi
+
+    log_error "Git not found"
+
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Installing Git via pkg..."
+        pkg install -y git >/dev/null
+        if command -v git >/dev/null 2>&1; then
+            GIT_VERSION=$(git --version | awk '{print $3}')
+            log_success "Git $GIT_VERSION installed"
+            return 0
+        fi
+    fi
+
+    log_info "Please install Git:"
+
+    case "$OS" in
+        linux)
+            case "$DISTRO" in
+                ubuntu|debian)
+                    log_info "  sudo apt update && sudo apt install git"
+                    ;;
+                fedora)
+                    log_info "  sudo dnf install git"
+                    ;;
+                arch)
+                    log_info "  sudo pacman -S git"
+                    ;;
+                *)
+                    log_info "  Use your package manager to install git"
+                    ;;
+            esac
+            ;;
+        android)
+            log_info "  pkg install git"
+            ;;
+        macos)
+            log_info "  xcode-select --install"
+            log_info "  Or: brew install git"
+            ;;
+    esac
+
+    exit 1
+}
+
+check_node() {
+    log_info "Checking Node.js (for browser tools)..."
+
+    if command -v node &> /dev/null; then
+        local found_ver=$(node --version)
+        log_success "Node.js $found_ver found"
+        HAS_NODE=true
+        return 0
+    fi
+
+    # Check our own managed install from a previous run
+    if [ -x "$HERMES_HOME/node/bin/node" ]; then
+        export PATH="$HERMES_HOME/node/bin:$PATH"
+        local found_ver=$("$HERMES_HOME/node/bin/node" --version)
+            log_success "Node.js $found_ver found (Mente-managed)"
+        HAS_NODE=true
+        return 0
+    fi
+
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Node.js not found — installing Node.js via pkg..."
+    else
+        log_info "Node.js not found — installing Node.js $NODE_VERSION LTS..."
+    fi
+    install_node
+}
+
+install_node() {
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Installing Node.js via pkg..."
+        if pkg install -y nodejs >/dev/null; then
+            local installed_ver
+            installed_ver=$(node --version 2>/dev/null)
+            log_success "Node.js $installed_ver installed via pkg"
+            HAS_NODE=true
+        else
+            log_warn "Failed to install Node.js via pkg"
+            HAS_NODE=false
+        fi
+        return 0
+    fi
+
+    local arch=$(uname -m)
+    local node_arch
+    case "$arch" in
+        x86_64)        node_arch="x64"    ;;
+        aarch64|arm64) node_arch="arm64"  ;;
+        armv7l)        node_arch="armv7l" ;;
+        *)
+            log_warn "Unsupported architecture ($arch) for Node.js auto-install"
+            log_info "Install manually: https://nodejs.org/en/download/"
+            HAS_NODE=false
+            return 0
+            ;;
+    esac
+
+    local node_os
+    case "$OS" in
+        linux) node_os="linux"  ;;
+        macos) node_os="darwin" ;;
+        *)
+            log_warn "Unsupported OS for Node.js auto-install"
+            HAS_NODE=false
+            return 0
+            ;;
+    esac
+
+    # Resolve the latest v22.x.x tarball name from the index page
+    local index_url="https://nodejs.org/dist/latest-v${NODE_VERSION}.x/"
+    local tarball_name
+    tarball_name=$(curl -fsSL "$index_url" \
+        | grep -oE "node-v${NODE_VERSION}\.[0-9]+\.[0-9]+-${node_os}-${node_arch}\.tar\.xz" \
+        | head -1)
+
+    # Fallback to .tar.gz if .tar.xz not available
+    if [ -z "$tarball_name" ]; then
+        tarball_name=$(curl -fsSL "$index_url" \
+            | grep -oE "node-v${NODE_VERSION}\.[0-9]+\.[0-9]+-${node_os}-${node_arch}\.tar\.gz" \
+            | head -1)
+    fi
+
+    if [ -z "$tarball_name" ]; then
+        log_warn "Could not find Node.js $NODE_VERSION binary for $node_os-$node_arch"
+        log_info "Install manually: https://nodejs.org/en/download/"
+        HAS_NODE=false
+        return 0
+    fi
+
+    local download_url="${index_url}${tarball_name}"
+    local tmp_dir
+    tmp_dir=$(mktemp -d)
+
+    log_info "Downloading $tarball_name..."
+    if ! curl -fsSL "$download_url" -o "$tmp_dir/$tarball_name"; then
+        log_warn "Download failed"
+        rm -rf "$tmp_dir"
+        HAS_NODE=false
+        return 0
+    fi
+
+    log_info "Extracting to ~/.mente/node/..."
+    if [[ "$tarball_name" == *.tar.xz ]]; then
+        tar xf "$tmp_dir/$tarball_name" -C "$tmp_dir"
+    else
+        tar xzf "$tmp_dir/$tarball_name" -C "$tmp_dir"
+    fi
+
+    local extracted_dir
+    extracted_dir=$(ls -d "$tmp_dir"/node-v* 2>/dev/null | head -1)
+
+    if [ ! -d "$extracted_dir" ]; then
+        log_warn "Extraction failed"
+        rm -rf "$tmp_dir"
+        HAS_NODE=false
+        return 0
+    fi
+
+    # Place into ~/.mente/node/ and symlink binaries to ~/.local/bin/
+    rm -rf "$HERMES_HOME/node"
+    mkdir -p "$HERMES_HOME"
+    mv "$extracted_dir" "$HERMES_HOME/node"
+    rm -rf "$tmp_dir"
+
+    mkdir -p "$HOME/.local/bin"
+    ln -sf "$HERMES_HOME/node/bin/node" "$HOME/.local/bin/node"
+    ln -sf "$HERMES_HOME/node/bin/npm"  "$HOME/.local/bin/npm"
+    ln -sf "$HERMES_HOME/node/bin/npx"  "$HOME/.local/bin/npx"
+
+    export PATH="$HERMES_HOME/node/bin:$PATH"
+
+    local installed_ver
+    installed_ver=$("$HERMES_HOME/node/bin/node" --version 2>/dev/null)
+    log_success "Node.js $installed_ver installed to ~/.mente/node/"
+    HAS_NODE=true
+}
+
+install_system_packages() {
+    # Detect what's missing
+    HAS_RIPGREP=false
+    HAS_FFMPEG=false
+    local need_ripgrep=false
+    local need_ffmpeg=false
+
+    log_info "Checking ripgrep (fast file search)..."
+    if command -v rg &> /dev/null; then
+        log_success "$(rg --version | head -1) found"
+        HAS_RIPGREP=true
+    else
+        need_ripgrep=true
+    fi
+
+    log_info "Checking ffmpeg (TTS voice messages)..."
+    if command -v ffmpeg &> /dev/null; then
+        local ffmpeg_ver=$(ffmpeg -version 2>/dev/null | head -1 | awk '{print $3}')
+        log_success "ffmpeg $ffmpeg_ver found"
+        HAS_FFMPEG=true
+    else
+        need_ffmpeg=true
+    fi
+
+    # Termux always needs the Android build toolchain for the tested pip path,
+    # even when ripgrep/ffmpeg are already present.
+    if [ "$DISTRO" = "termux" ]; then
+        local termux_pkgs=(clang rust make pkg-config libffi openssl)
+        if [ "$need_ripgrep" = true ]; then
+            termux_pkgs+=("ripgrep")
+        fi
+        if [ "$need_ffmpeg" = true ]; then
+            termux_pkgs+=("ffmpeg")
+        fi
+
+        log_info "Installing Termux packages: ${termux_pkgs[*]}"
+        if pkg install -y "${termux_pkgs[@]}" >/dev/null; then
+            [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+            [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+            log_success "Termux build dependencies installed"
+            return 0
+        fi
+
+        log_warn "Could not auto-install all Termux packages"
+        log_info "Install manually: pkg install ${termux_pkgs[*]}"
+        return 0
+    fi
+
+    # Nothing to install — done
+    if [ "$need_ripgrep" = false ] && [ "$need_ffmpeg" = false ]; then
+        return 0
+    fi
+
+    # Build a human-readable description + package list
+    local desc_parts=()
+    local pkgs=()
+    if [ "$need_ripgrep" = true ]; then
+        desc_parts+=("ripgrep for faster file search")
+        pkgs+=("ripgrep")
+    fi
+    if [ "$need_ffmpeg" = true ]; then
+        desc_parts+=("ffmpeg for TTS voice messages")
+        pkgs+=("ffmpeg")
+    fi
+    local description
+    description=$(IFS=" and "; echo "${desc_parts[*]}")
+
+    # ── macOS: brew ──
+    if [ "$OS" = "macos" ]; then
+        if command -v brew &> /dev/null; then
+            log_info "Installing ${pkgs[*]} via Homebrew..."
+            if brew install "${pkgs[@]}"; then
+                [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+                [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+                return 0
+            fi
+        fi
+        log_warn "Could not auto-install (brew not found or install failed)"
+        log_info "Install manually: brew install ${pkgs[*]}"
+        return 0
+    fi
+
+    # ── Linux: resolve package manager command ──
+    local pkg_install=""
+    case "$DISTRO" in
+        ubuntu|debian) pkg_install="apt install -y"   ;;
+        fedora)        pkg_install="dnf install -y"   ;;
+        arch)          pkg_install="pacman -S --noconfirm" ;;
+    esac
+
+    if [ -n "$pkg_install" ]; then
+        local install_cmd="$pkg_install ${pkgs[*]}"
+
+        # Prevent needrestart/whiptail dialogs from blocking non-interactive installs
+        case "$DISTRO" in
+            ubuntu|debian) export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a ;;
+        esac
+
+        # Already root — just install
+        if [ "$(id -u)" -eq 0 ]; then
+            log_info "Installing ${pkgs[*]}..."
+            if $install_cmd; then
+                [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+                [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+                return 0
+            fi
+        # Passwordless sudo — just install
+        elif command -v sudo &> /dev/null && sudo -n true 2>/dev/null; then
+            log_info "Installing ${pkgs[*]}..."
+            if sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a $install_cmd; then
+                [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+                [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+                return 0
+            fi
+        # sudo needs password — ask once for everything
+        elif command -v sudo &> /dev/null; then
+            if [ "$IS_INTERACTIVE" = true ]; then
+                echo ""
+                log_info "sudo is needed ONLY to install optional system packages (${pkgs[*]}) via your package manager."
+                log_info "Mente itself does not require or retain root access."
+                if prompt_yes_no "Install ${description}? (requires sudo)" "no"; then
+                    if sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a $install_cmd; then
+                        [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+                        [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+                        return 0
+                    fi
+                fi
+            elif [ -e /dev/tty ]; then
+                # Non-interactive (e.g. curl | bash) but a terminal is available.
+                # Read the prompt from /dev/tty (same approach the setup wizard uses).
+                echo ""
+                log_info "sudo is needed ONLY to install optional system packages (${pkgs[*]}) via your package manager."
+                log_info "Mente itself does not require or retain root access."
+                if prompt_yes_no "Install ${description}?" "yes"; then
+                    if sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a $install_cmd < /dev/tty; then
+                        [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+                        [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+                        return 0
+                    fi
+                fi
+            else
+                log_warn "Non-interactive mode and no terminal available — cannot install system packages"
+                log_info "Install manually after setup completes: sudo $install_cmd"
+            fi
+        fi
+    fi
+
+    # ── Fallback for ripgrep: cargo ──
+    if [ "$need_ripgrep" = true ] && [ "$HAS_RIPGREP" = false ]; then
+        if command -v cargo &> /dev/null; then
+            log_info "Trying cargo install ripgrep (no sudo needed)..."
+            if cargo install ripgrep; then
+                log_success "ripgrep installed via cargo"
+                HAS_RIPGREP=true
+            fi
+        fi
+    fi
+
+    # ── Show manual instructions for anything still missing ──
+    if [ "$HAS_RIPGREP" = false ] && [ "$need_ripgrep" = true ]; then
+        log_warn "ripgrep not installed (file search will use grep fallback)"
+        show_manual_install_hint "ripgrep"
+    fi
+    if [ "$HAS_FFMPEG" = false ] && [ "$need_ffmpeg" = true ]; then
+        log_warn "ffmpeg not installed (TTS voice messages will be limited)"
+        show_manual_install_hint "ffmpeg"
+    fi
+}
+
+show_manual_install_hint() {
+    local pkg="$1"
+    log_info "To install $pkg manually:"
+    case "$OS" in
+        linux)
+            case "$DISTRO" in
+                ubuntu|debian) log_info "  sudo apt install $pkg" ;;
+                fedora)        log_info "  sudo dnf install $pkg" ;;
+                arch)          log_info "  sudo pacman -S $pkg"   ;;
+                *)             log_info "  Use your package manager or visit the project homepage" ;;
+            esac
+            ;;
+        android)
+            log_info "  pkg install $pkg"
+            ;;
+        macos) log_info "  brew install $pkg" ;;
+    esac
+}
+
+# ============================================================================
+# Installation
+# ============================================================================
+
+resolve_target_release_ref() {
+    local requested="${1:-latest}"
+    if [ "$requested" != "latest" ]; then
+        printf '%s\n' "$requested"
+        return 0
+    fi
+
+    local latest_tag
+    latest_tag="$(git tag --sort=-creatordate | head -n 1)"
+    if [ -z "$latest_tag" ]; then
+        return 1
+    fi
+    printf '%s\n' "$latest_tag"
+}
+
+write_install_manifest() {
+    cat > "$INSTALL_DIR/.mente-install.json" <<EOF
+{
+  "install_mode": "$INSTALL_MODE",
+  "release_ref": "${CURRENT_RELEASE_REF:-}",
+  "source_branch": "${BRANCH:-}",
+  "runtime_artifact_manifest": "${RUNTIME_ARTIFACT_MANIFEST:-}",
+  "runtime_wheel": "${RUNTIME_WHEEL:-}",
+  "update_policy": "$( [ "$INSTALL_MODE" = "release" ] && printf 'git_tag_release' || printf 'git_branch_source' )",
+  "runtime_bootstrap_policy": "artifact_manifest_and_runtime_wheel",
+  "developer_setup_path": "./setup-hermes.sh",
+  "one_click_install_policy": "$( [ "$INSTALL_MODE" = "release" ] && printf 'release_pinned' || printf 'source_checkout' )"
+}
+EOF
+}
+
+bootstrap_vendored_runtime() {
+    if [ -z "$RUNTIME_WHEEL" ]; then
+        if [ -n "$RUNTIME_ARTIFACT_MANIFEST" ]; then
+            log_info "Runtime artifact manifest recorded: $RUNTIME_ARTIFACT_MANIFEST"
+        fi
+        return 0
+    fi
+
+    log_info "Bootstrapping vendored Codex runtime wheel..."
+    if [ "$DISTRO" = "termux" ]; then
+        if [ "$USE_VENV" = true ]; then
+            "$INSTALL_DIR/venv/bin/python" -m pip install "$RUNTIME_WHEEL"
+        else
+            "$PYTHON_PATH" -m pip install "$RUNTIME_WHEEL"
+        fi
+    else
+        export VIRTUAL_ENV="$INSTALL_DIR/venv"
+        $UV_CMD pip install "$RUNTIME_WHEEL"
+    fi
+    log_success "Vendored Codex runtime wheel installed"
+}
+
+clone_repo() {
+    log_info "Installing to $INSTALL_DIR..."
+
+    if [ -d "$INSTALL_DIR" ]; then
+        if [ -d "$INSTALL_DIR/.git" ]; then
+            log_info "Existing installation found, updating..."
+            cd "$INSTALL_DIR"
+
+            local autostash_ref=""
+            if [ -n "$(git status --porcelain)" ]; then
+                local stash_name
+                stash_name="mente-install-autostash-$(date -u +%Y%m%d-%H%M%S)"
+                log_info "Local changes detected, stashing before update..."
+                git stash push --include-untracked -m "$stash_name"
+                autostash_ref="$(git rev-parse --verify refs/stash)"
+            fi
+
+            if [ "$INSTALL_MODE" = "release" ]; then
+                git fetch origin --tags
+                CURRENT_RELEASE_REF="$(resolve_target_release_ref "$RELEASE_REF")" || {
+                    log_error "Could not resolve a release tag for install/update"
+                    exit 1
+                }
+                git checkout "$CURRENT_RELEASE_REF"
+            else
+                git fetch origin
+                git checkout "$BRANCH"
+                git pull --ff-only origin "$BRANCH"
+            fi
+
+            if [ -n "$autostash_ref" ]; then
+                local restore_now="yes"
+                if [ -t 0 ] && [ -t 1 ]; then
+                    echo
+                    log_warn "Local changes were stashed before updating."
+                    log_warn "Restoring them may reapply local customizations onto the updated codebase."
+                    printf "Restore local changes now? [Y/n] "
+                    read -r restore_answer
+                    case "$restore_answer" in
+                        ""|y|Y|yes|YES|Yes) restore_now="yes" ;;
+                        *) restore_now="no" ;;
+                    esac
+                fi
+
+                if [ "$restore_now" = "yes" ]; then
+                    log_info "Restoring local changes..."
+                    if git stash apply "$autostash_ref"; then
+                        git stash drop "$autostash_ref" >/dev/null
+                        log_warn "Local changes were restored on top of the updated codebase."
+                        log_warn "Review git diff / git status if Mente behaves unexpectedly."
+                    else
+                        log_error "Update succeeded, but restoring local changes failed. Your changes are still preserved in git stash."
+                        log_info "Resolve manually with: git stash apply $autostash_ref"
+                        exit 1
+                    fi
+                else
+                    log_info "Skipped restoring local changes."
+                    log_info "Your changes are still preserved in git stash."
+                    log_info "Restore manually with: git stash apply $autostash_ref"
+                fi
+            fi
+        else
+            log_error "Directory exists but is not a git repository: $INSTALL_DIR"
+            log_info "Remove it or choose a different directory with --dir"
+            exit 1
+        fi
+    else
+        # Try SSH first (for private repo access), fall back to HTTPS
+        # GIT_SSH_COMMAND disables interactive prompts and sets a short timeout
+        # so SSH fails fast instead of hanging when no key is configured.
+        log_info "Trying SSH clone..."
+        local clone_args=()
+        if [ "$INSTALL_MODE" = "source" ]; then
+            clone_args=(--branch "$BRANCH")
+        fi
+        if GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=5" \
+           git clone "${clone_args[@]}" "$REPO_URL_SSH" "$INSTALL_DIR" 2>/dev/null; then
+            log_success "Cloned via SSH"
+        else
+            rm -rf "$INSTALL_DIR" 2>/dev/null  # Clean up partial SSH clone
+            log_info "SSH failed, trying HTTPS..."
+            if git clone "${clone_args[@]}" "$REPO_URL_HTTPS" "$INSTALL_DIR"; then
+                log_success "Cloned via HTTPS"
+            else
+                log_error "Failed to clone repository"
+                exit 1
+            fi
+        fi
+    fi
+
+    cd "$INSTALL_DIR"
+
+    if [ "$INSTALL_MODE" = "release" ]; then
+        git fetch origin --tags >/dev/null 2>&1 || true
+        CURRENT_RELEASE_REF="$(resolve_target_release_ref "$RELEASE_REF")" || {
+            log_error "Could not resolve a release tag after clone"
+            exit 1
+        }
+        git checkout "$CURRENT_RELEASE_REF" >/dev/null 2>&1 || {
+            log_error "Failed to check out release tag $CURRENT_RELEASE_REF"
+            exit 1
+        }
+    fi
+
+    write_install_manifest
+
+    log_success "Repository ready"
+}
+
+setup_venv() {
+    if [ "$USE_VENV" = false ]; then
+        log_info "Skipping virtual environment (--no-venv)"
+        return 0
+    fi
+
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Creating virtual environment with Termux Python..."
+
+        if [ -d "venv" ]; then
+            log_info "Virtual environment already exists, recreating..."
+            rm -rf venv
+        fi
+
+        "$PYTHON_PATH" -m venv venv
+        log_success "Virtual environment ready ($(./venv/bin/python --version 2>/dev/null))"
+        return 0
+    fi
+
+    log_info "Creating virtual environment with Python $PYTHON_VERSION..."
+
+    if [ -d "venv" ]; then
+        log_info "Virtual environment already exists, recreating..."
+        rm -rf venv
+    fi
+
+    # uv creates the venv and pins the Python version in one step
+    $UV_CMD venv venv --python "$PYTHON_VERSION"
+
+    log_success "Virtual environment ready (Python $PYTHON_VERSION)"
+}
+
+install_deps() {
+    log_info "Installing dependencies..."
+
+    if [ "$DISTRO" = "termux" ]; then
+        if [ "$USE_VENV" = true ]; then
+            export VIRTUAL_ENV="$INSTALL_DIR/venv"
+            PIP_PYTHON="$INSTALL_DIR/venv/bin/python"
+        else
+            PIP_PYTHON="$PYTHON_PATH"
+        fi
+
+        if [ -z "${ANDROID_API_LEVEL:-}" ]; then
+            ANDROID_API_LEVEL="$(getprop ro.build.version.sdk 2>/dev/null || true)"
+            if [ -z "$ANDROID_API_LEVEL" ]; then
+                ANDROID_API_LEVEL=24
+            fi
+            export ANDROID_API_LEVEL
+            log_info "Using ANDROID_API_LEVEL=$ANDROID_API_LEVEL for Android wheel builds"
+        fi
+
+        "$PIP_PYTHON" -m pip install --upgrade pip setuptools wheel >/dev/null
+        if ! "$PIP_PYTHON" -m pip install -e '.[termux]' -c constraints-termux.txt; then
+            log_warn "Termux feature install (.[termux]) failed, trying base install..."
+            if ! "$PIP_PYTHON" -m pip install -e '.' -c constraints-termux.txt; then
+                log_error "Package installation failed on Termux."
+                log_info "Ensure these packages are installed: pkg install clang rust make pkg-config libffi openssl"
+                log_info "Then re-run: cd $INSTALL_DIR && python -m pip install -e '.[termux]' -c constraints-termux.txt"
+                exit 1
+            fi
+        fi
+
+        log_success "Main package installed"
+        log_info "Termux note: browser/WhatsApp tooling is not installed by default; see the Termux guide for optional follow-up steps."
+
+        if [ -d "tinker-atropos" ] && [ -f "tinker-atropos/pyproject.toml" ]; then
+            log_info "tinker-atropos submodule found — skipping install (optional, for RL training)"
+            log_info "  To install later: $PIP_PYTHON -m pip install -e \"./tinker-atropos\""
+        fi
+
+        log_success "All dependencies installed"
+        return 0
+    fi
+
+    if [ "$USE_VENV" = true ]; then
+        # Tell uv to install into our venv (no need to activate)
+        export VIRTUAL_ENV="$INSTALL_DIR/venv"
+    fi
+
+    # On Debian/Ubuntu (including WSL), some Python packages need build tools.
+    # Check and offer to install them if missing.
+    if [ "$DISTRO" = "ubuntu" ] || [ "$DISTRO" = "debian" ]; then
+        local need_build_tools=false
+        for pkg in gcc python3-dev libffi-dev; do
+            if ! dpkg -s "$pkg" &>/dev/null; then
+                need_build_tools=true
+                break
+            fi
+        done
+        if [ "$need_build_tools" = true ]; then
+            log_info "Some build tools may be needed for Python packages..."
+            if command -v sudo &> /dev/null; then
+                if sudo -n true 2>/dev/null; then
+                    sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get update -qq && sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y -qq build-essential python3-dev libffi-dev >/dev/null 2>&1 || true
+                    log_success "Build tools installed"
+                else
+                    log_info "sudo is needed ONLY to install build tools (build-essential, python3-dev, libffi-dev) via apt."
+                    log_info "Mente itself does not require or retain root access."
+                    if prompt_yes_no "Install build tools?" "yes"; then
+                        sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get update -qq && sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y -qq build-essential python3-dev libffi-dev >/dev/null 2>&1 || true
+                        log_success "Build tools installed"
+                    fi
+                fi
+            fi
+        fi
+    fi
+
+    # Install the main package in editable mode with all extras.
+    # Try [all] first, fall back to base install if extras have issues.
+    ALL_INSTALL_LOG=$(mktemp)
+    if ! $UV_CMD pip install -e ".[all]" 2>"$ALL_INSTALL_LOG"; then
+        log_warn "Full install (.[all]) failed, trying base install..."
+        log_info "Reason: $(tail -5 "$ALL_INSTALL_LOG" | head -3)"
+        rm -f "$ALL_INSTALL_LOG"
+        if ! $UV_CMD pip install -e "."; then
+            log_error "Package installation failed."
+            log_info "Check that build tools are installed: sudo apt install build-essential python3-dev"
+            log_info "Then re-run: cd $INSTALL_DIR && uv pip install -e '.[all]'"
+            exit 1
+        fi
+    else
+        rm -f "$ALL_INSTALL_LOG"
+    fi
+
+    log_success "Main package installed"
+
+    # tinker-atropos (RL training) is optional — skip by default.
+    # To enable RL tools: git submodule update --init tinker-atropos && uv pip install -e "./tinker-atropos"
+    if [ -d "tinker-atropos" ] && [ -f "tinker-atropos/pyproject.toml" ]; then
+        log_info "tinker-atropos submodule found — skipping install (optional, for RL training)"
+        log_info "  To install: $UV_CMD pip install -e \"./tinker-atropos\""
+    fi
+
+    log_success "All dependencies installed"
+}
+
+setup_path() {
+    log_info "Setting up mente command..."
+
+    if [ "$USE_VENV" = true ]; then
+        MENTE_BIN="$INSTALL_DIR/venv/bin/mente"
+    else
+        MENTE_BIN="$(which mente 2>/dev/null || echo "")"
+        if [ -z "$MENTE_BIN" ]; then
+            log_warn "mente not found on PATH after install"
+            return 0
+        fi
+    fi
+
+    # Verify the entry point script was actually generated
+    if [ ! -x "$MENTE_BIN" ]; then
+        log_warn "mente entry point not found at $MENTE_BIN"
+        log_info "This usually means the pip install didn't complete successfully."
+        if [ "$DISTRO" = "termux" ]; then
+            log_info "Try: cd $INSTALL_DIR && python -m pip install -e '.[termux]' -c constraints-termux.txt"
+        else
+            log_info "Try: cd $INSTALL_DIR && uv pip install -e '.[all]'"
+        fi
+        return 0
+    fi
+
+    local command_link_dir
+    local command_link_display_dir
+    command_link_dir="$(get_command_link_dir)"
+    command_link_display_dir="$(get_command_link_display_dir)"
+
+    # Create user-facing shim for the primary mente command.
+    mkdir -p "$command_link_dir"
+    ln -sf "$MENTE_BIN" "$command_link_dir/mente"
+    log_success "Symlinked mente → $command_link_display_dir/mente"
+
+    if [ "$DISTRO" = "termux" ]; then
+        export PATH="$command_link_dir:$PATH"
+        log_info "$command_link_display_dir is the native Termux command path"
+        log_success "mente command ready"
+        return 0
+    fi
+
+    # FHS layout: /usr/local/bin is normally on PATH for login shells (via
+    # /etc/profile pathmunge), but on RHEL/CentOS/Rocky/Alma 8+ non-login
+    # interactive root shells (su, sudo -s, tmux panes, some web terminals)
+    # only source /etc/bashrc, which does NOT add /usr/local/bin — and
+    # /root/.bash_profile doesn't either.  So verify with `command -v` and
+    # fall back to writing a PATH guard into /root/.bashrc when needed.
+    if [ "$ROOT_FHS_LAYOUT" = true ]; then
+        export PATH="$command_link_dir:$PATH"
+        # Probe a fresh non-login interactive bash the way the user will use it.
+        # `bash -i -c` sources ~/.bashrc but NOT ~/.bash_profile or /etc/profile,
+        # which is the exact scenario where RHEL root loses /usr/local/bin.
+        if env -i HOME="$HOME" TERM="${TERM:-dumb}" bash -i -c 'command -v mente' \
+                >/dev/null 2>&1; then
+            log_info "/usr/local/bin is already on PATH for all shells"
+            log_success "mente command ready"
+            return 0
+        fi
+
+        log_info "mente not on PATH in non-login shells (common on RHEL-family)"
+        PATH_LINE='export PATH="/usr/local/bin:$PATH"'
+        PATH_COMMENT='# Mente — ensure /usr/local/bin is on PATH (RHEL non-login shells)'
+        for SHELL_CONFIG in "$HOME/.bashrc" "$HOME/.bash_profile"; do
+            [ -f "$SHELL_CONFIG" ] || continue
+            if ! grep -v '^[[:space:]]*#' "$SHELL_CONFIG" 2>/dev/null \
+                    | grep -qE 'PATH=.*(/usr/local/bin|\$command_link_dir)'; then
+                echo "" >> "$SHELL_CONFIG"
+                echo "$PATH_COMMENT" >> "$SHELL_CONFIG"
+                echo "$PATH_LINE" >> "$SHELL_CONFIG"
+                log_success "Added /usr/local/bin to PATH in $SHELL_CONFIG"
+            fi
+        done
+        log_success "mente command ready"
+        return 0
+    fi
+
+    # Check if ~/.local/bin is on PATH; if not, add it to shell config.
+    # Detect the user's actual login shell (not the shell running this script,
+    # which is always bash when piped from curl).
+    if ! echo "$PATH" | tr ':' '\n' | grep -q "^$command_link_dir$"; then
+        SHELL_CONFIGS=()
+        IS_FISH=false
+        LOGIN_SHELL="$(basename "${SHELL:-/bin/bash}")"
+        case "$LOGIN_SHELL" in
+            zsh)
+                [ -f "$HOME/.zshrc" ] && SHELL_CONFIGS+=("$HOME/.zshrc")
+                [ -f "$HOME/.zprofile" ] && SHELL_CONFIGS+=("$HOME/.zprofile")
+                # If neither exists, create ~/.zshrc (common on fresh macOS installs)
+                if [ ${#SHELL_CONFIGS[@]} -eq 0 ]; then
+                    touch "$HOME/.zshrc"
+                    SHELL_CONFIGS+=("$HOME/.zshrc")
+                fi
+                ;;
+            bash)
+                [ -f "$HOME/.bashrc" ] && SHELL_CONFIGS+=("$HOME/.bashrc")
+                [ -f "$HOME/.bash_profile" ] && SHELL_CONFIGS+=("$HOME/.bash_profile")
+                ;;
+            fish)
+                # fish uses ~/.config/fish/config.fish and fish_add_path — not export PATH=
+                IS_FISH=true
+                FISH_CONFIG="$HOME/.config/fish/config.fish"
+                mkdir -p "$(dirname "$FISH_CONFIG")"
+                touch "$FISH_CONFIG"
+                ;;
+            *)
+                [ -f "$HOME/.bashrc" ] && SHELL_CONFIGS+=("$HOME/.bashrc")
+                [ -f "$HOME/.zshrc" ] && SHELL_CONFIGS+=("$HOME/.zshrc")
+                ;;
+        esac
+        # Also ensure ~/.profile has it (sourced by login shells on
+        # Ubuntu/Debian/WSL even when ~/.bashrc is skipped)
+        [ "$IS_FISH" = "false" ] && [ -f "$HOME/.profile" ] && SHELL_CONFIGS+=("$HOME/.profile")
+
+        PATH_LINE='export PATH="$HOME/.local/bin:$PATH"'
+
+        for SHELL_CONFIG in "${SHELL_CONFIGS[@]}"; do
+            if ! grep -v '^[[:space:]]*#' "$SHELL_CONFIG" 2>/dev/null | grep -qE 'PATH=.*\.local/bin'; then
+                echo "" >> "$SHELL_CONFIG"
+                echo "# Mente — ensure ~/.local/bin is on PATH" >> "$SHELL_CONFIG"
+                echo "$PATH_LINE" >> "$SHELL_CONFIG"
+                log_success "Added ~/.local/bin to PATH in $SHELL_CONFIG"
+            fi
+        done
+
+        # fish uses fish_add_path instead of export PATH=...
+        if [ "$IS_FISH" = "true" ]; then
+            if ! grep -q 'fish_add_path.*\.local/bin' "$FISH_CONFIG" 2>/dev/null; then
+                echo "" >> "$FISH_CONFIG"
+                echo "# Mente — ensure ~/.local/bin is on PATH" >> "$FISH_CONFIG"
+                echo 'fish_add_path "$HOME/.local/bin"' >> "$FISH_CONFIG"
+                log_success "Added ~/.local/bin to PATH in $FISH_CONFIG"
+            fi
+        fi
+
+        if [ "$IS_FISH" = "false" ] && [ ${#SHELL_CONFIGS[@]} -eq 0 ]; then
+            log_warn "Could not detect shell config file to add ~/.local/bin to PATH"
+            log_info "Add manually: $PATH_LINE"
+        fi
+    else
+        log_info "~/.local/bin already on PATH"
+    fi
+
+    # Export for current session so mente works immediately
+    export PATH="$command_link_dir:$PATH"
+
+    log_success "mente command ready"
+}
+
+copy_config_templates() {
+    log_info "Setting up configuration files..."
+
+    # Create ~/.mente directory structure (config at top level, code in subdir)
+    mkdir -p "$HERMES_HOME"/{cron,sessions,logs,pairing,hooks,image_cache,audio_cache,memories,skills}
+
+    # Create .env at ~/.mente/.env (top level, easy to find)
+    if [ ! -f "$HERMES_HOME/.env" ]; then
+        if [ -f "$INSTALL_DIR/.env.example" ]; then
+            cp "$INSTALL_DIR/.env.example" "$HERMES_HOME/.env"
+            log_success "Created ~/.mente/.env from template"
+        else
+            touch "$HERMES_HOME/.env"
+            log_success "Created ~/.mente/.env"
+        fi
+    else
+        log_info "~/.mente/.env already exists, keeping it"
+    fi
+
+    # Create config.yaml at ~/.mente/config.yaml (top level, easy to find)
+    if [ ! -f "$HERMES_HOME/config.yaml" ]; then
+        if [ -f "$INSTALL_DIR/cli-config.yaml.example" ]; then
+            cp "$INSTALL_DIR/cli-config.yaml.example" "$HERMES_HOME/config.yaml"
+            log_success "Created ~/.mente/config.yaml from template"
+        fi
+    else
+        log_info "~/.mente/config.yaml already exists, keeping it"
+    fi
+
+    # Create SOUL.md if it doesn't exist (global persona file)
+    if [ ! -f "$HERMES_HOME/SOUL.md" ]; then
+        cat > "$HERMES_HOME/SOUL.md" << 'SOUL_EOF'
+# Mente Agent Persona
+
+<!--
+This file defines the agent's personality and tone.
+The agent will embody whatever you write here.
+Edit this to customize how Mente communicates with you.
+
+Examples:
+  - "You are a warm, playful assistant who uses kaomoji occasionally."
+  - "You are a concise technical expert. No fluff, just facts."
+  - "You speak like a friendly coworker who happens to know everything."
+
+This file is loaded fresh each message -- no restart needed.
+Delete the contents (or this file) to use the default personality.
+-->
+SOUL_EOF
+        log_success "Created ~/.mente/SOUL.md (edit to customize personality)"
+    fi
+
+    log_success "Configuration directory ready: ~/.mente/"
+
+    # Seed bundled skills into ~/.mente/skills/ (manifest-based, one-time per skill)
+    log_info "Syncing bundled skills to ~/.mente/skills/ ..."
+    if "$INSTALL_DIR/venv/bin/python" "$INSTALL_DIR/tools/skills_sync.py" 2>/dev/null; then
+        log_success "Skills synced to ~/.mente/skills/"
+    else
+        # Fallback: simple directory copy if Python sync fails
+        if [ -d "$INSTALL_DIR/skills" ] && [ ! "$(ls -A "$HERMES_HOME/skills/" 2>/dev/null | grep -v '.bundled_manifest')" ]; then
+            cp -r "$INSTALL_DIR/skills/"* "$HERMES_HOME/skills/" 2>/dev/null || true
+            log_success "Skills copied to ~/.mente/skills/"
+        fi
+    fi
+}
+
+install_node_deps() {
+    if [ "$HAS_NODE" = false ]; then
+        log_info "Skipping Node.js dependencies (Node not installed)"
+        return 0
+    fi
+
+    if [ "$DISTRO" = "termux" ]; then
+        log_info "Skipping automatic Node/browser dependency setup on Termux"
+        log_info "Browser automation is not part of the tested Termux install path yet."
+        log_info "If you want to experiment manually later, run: cd $INSTALL_DIR && npm install"
+        return 0
+    fi
+
+    if [ -f "$INSTALL_DIR/package.json" ]; then
+        log_info "Installing Node.js dependencies (browser tools)..."
+        cd "$INSTALL_DIR"
+        npm install --silent 2>/dev/null || {
+            log_warn "npm install failed (browser tools may not work)"
+        }
+        log_success "Node.js dependencies installed"
+
+        # Install Playwright browser + system dependencies.
+        # Playwright's --with-deps only supports apt-based systems natively.
+        # For Arch/Manjaro we install the system libs via pacman first.
+        # Other systems must install Chromium dependencies manually.
+        log_info "Installing browser engine (Playwright Chromium)..."
+        case "$DISTRO" in
+            ubuntu|debian|raspbian|pop|linuxmint|elementary|zorin|kali|parrot)
+                log_info "Playwright may request sudo to install browser system dependencies (shared libraries)."
+                log_info "This is standard Playwright setup — Mente itself does not require root access."
+                cd "$INSTALL_DIR" && npx playwright install --with-deps chromium 2>/dev/null || {
+                    log_warn "Playwright browser installation failed — browser tools will not work."
+                    log_warn "Try running manually: cd $INSTALL_DIR && npx playwright install --with-deps chromium"
+                }
+                ;;
+            arch|manjaro)
+                if command -v pacman &> /dev/null; then
+                    log_info "Arch/Manjaro detected — installing Chromium system dependencies via pacman..."
+                    if command -v sudo &> /dev/null && sudo -n true 2>/dev/null; then
+                        sudo NEEDRESTART_MODE=a pacman -S --noconfirm --needed \
+                            nss atk at-spi2-core cups libdrm libxkbcommon mesa pango cairo alsa-lib >/dev/null 2>&1 || true
+                    elif [ "$(id -u)" -eq 0 ]; then
+                        pacman -S --noconfirm --needed \
+                            nss atk at-spi2-core cups libdrm libxkbcommon mesa pango cairo alsa-lib >/dev/null 2>&1 || true
+                    else
+                        log_warn "Cannot install browser deps without sudo. Run manually:"
+                        log_warn "  sudo pacman -S nss atk at-spi2-core cups libdrm libxkbcommon mesa pango cairo alsa-lib"
+                    fi
+                fi
+                cd "$INSTALL_DIR" && npx playwright install chromium 2>/dev/null || {
+                    log_warn "Playwright browser installation failed — browser tools will not work."
+                }
+                ;;
+            fedora|rhel|centos|rocky|alma)
+                log_warn "Playwright does not support automatic dependency installation on RPM-based systems."
+                log_info "Install Chromium system dependencies manually before using browser tools:"
+                log_info "  sudo dnf install nss atk at-spi2-core cups-libs libdrm libxkbcommon mesa-libgbm pango cairo alsa-lib"
+                cd "$INSTALL_DIR" && npx playwright install chromium 2>/dev/null || {
+                    log_warn "Playwright browser installation failed — install dependencies above and retry."
+                }
+                ;;
+            opensuse*|sles)
+                log_warn "Playwright does not support automatic dependency installation on zypper-based systems."
+                log_info "Install Chromium system dependencies manually before using browser tools:"
+                log_info "  sudo zypper install mozilla-nss libatk-1_0-0 at-spi2-core cups-libs libdrm2 libxkbcommon0 Mesa-libgbm1 pango cairo libasound2"
+                cd "$INSTALL_DIR" && npx playwright install chromium 2>/dev/null || {
+                    log_warn "Playwright browser installation failed — install dependencies above and retry."
+                }
+                ;;
+            *)
+                log_warn "Playwright does not support automatic dependency installation on $DISTRO."
+                log_info "Install Chromium/browser system dependencies for your distribution, then run:"
+                log_info "  cd $INSTALL_DIR && npx playwright install chromium"
+                log_info "Browser tools will not work until dependencies are installed."
+                cd "$INSTALL_DIR" && npx playwright install chromium 2>/dev/null || true
+                ;;
+        esac
+        log_success "Browser engine setup complete"
+    fi
+
+    # Install TUI dependencies
+    if [ -f "$INSTALL_DIR/ui-tui/package.json" ]; then
+        log_info "Installing TUI dependencies..."
+        cd "$INSTALL_DIR/ui-tui"
+        npm install --silent 2>/dev/null || {
+            log_warn "TUI npm install failed (mente --tui may not work)"
+        }
+        log_success "TUI dependencies installed"
+    fi
+
+
+}
+
+run_setup_wizard() {
+    if [ "$RUN_SETUP" = false ]; then
+        log_info "Skipping setup wizard (--skip-setup)"
+        return 0
+    fi
+
+    # The setup wizard reads from /dev/tty, so it works even when the
+    # install script itself is piped (curl | bash). Only skip if no
+    # terminal is available at all (e.g. Docker build, CI).
+    if ! [ -e /dev/tty ]; then
+        log_info "Setup wizard skipped (no terminal available). Run 'mente setup' after install."
+        return 0
+    fi
+
+    echo ""
+    log_info "Starting setup wizard..."
+    echo ""
+
+    cd "$INSTALL_DIR"
+
+    # Run mente setup using the venv Python directly (no activation needed).
+    # Redirect stdin from /dev/tty so interactive prompts work when piped from curl.
+    if [ "$USE_VENV" = true ]; then
+        "$INSTALL_DIR/venv/bin/python" -m hermes_cli.main setup < /dev/tty
+    else
+        python -m hermes_cli.main setup < /dev/tty
+    fi
+}
+
+maybe_start_gateway() {
+    # Check if any messaging platform tokens were configured
+    ENV_FILE="$HERMES_HOME/.env"
+    if [ ! -f "$ENV_FILE" ]; then
+        return 0
+    fi
+
+    HAS_MESSAGING=false
+    for VAR in TELEGRAM_BOT_TOKEN DISCORD_BOT_TOKEN SLACK_BOT_TOKEN SLACK_APP_TOKEN WHATSAPP_ENABLED; do
+        VAL=$(grep "^${VAR}=" "$ENV_FILE" 2>/dev/null | cut -d'=' -f2-)
+        if [ -n "$VAL" ] && [ "$VAL" != "your-token-here" ]; then
+            HAS_MESSAGING=true
+            break
+        fi
+    done
+
+    if [ "$HAS_MESSAGING" = false ]; then
+        return 0
+    fi
+
+    echo ""
+    log_info "Messaging platform token detected!"
+    log_info "The gateway needs to be running for Mente to send/receive messages."
+
+    # If WhatsApp is enabled and no session exists yet, run foreground first for QR scan
+    WHATSAPP_VAL=$(grep "^WHATSAPP_ENABLED=" "$ENV_FILE" 2>/dev/null | cut -d'=' -f2-)
+    WHATSAPP_SESSION="$HERMES_HOME/whatsapp/session/creds.json"
+    if [ "$WHATSAPP_VAL" = "true" ] && [ ! -f "$WHATSAPP_SESSION" ]; then
+        if [ "$IS_INTERACTIVE" = true ]; then
+            echo ""
+            log_info "WhatsApp is enabled but not yet paired."
+            log_info "Running 'mente whatsapp' to pair via QR code..."
+            echo ""
+            if prompt_yes_no "Pair WhatsApp now?" "yes"; then
+                HERMES_CMD="$(get_mente_command_path)"
+                $HERMES_CMD whatsapp || true
+            fi
+        else
+            log_info "WhatsApp pairing skipped (non-interactive). Run 'mente whatsapp' to pair."
+        fi
+    fi
+
+    if ! [ -e /dev/tty ]; then
+        log_info "Gateway setup skipped (no terminal available). Run 'mente gateway install' later."
+        return 0
+    fi
+
+    echo ""
+    local should_install_gateway=false
+    if [ "$DISTRO" = "termux" ]; then
+        if prompt_yes_no "Would you like to start the gateway in the background?" "yes"; then
+            should_install_gateway=true
+        fi
+    else
+        if prompt_yes_no "Would you like to install the gateway as a background service?" "yes"; then
+            should_install_gateway=true
+        fi
+    fi
+
+    if [ "$should_install_gateway" = true ]; then
+        HERMES_CMD="$(get_mente_command_path)"
+
+        if [ "$DISTRO" != "termux" ] && command -v systemctl &> /dev/null; then
+            log_info "Installing systemd service..."
+            if $HERMES_CMD gateway install 2>/dev/null; then
+                log_success "Gateway service installed"
+                if $HERMES_CMD gateway start 2>/dev/null; then
+                    log_success "Gateway started! Your bot is now online."
+                else
+                    log_warn "Service installed but failed to start. Try: mente gateway start"
+                fi
+            else
+                log_warn "Systemd install failed. You can start manually: mente gateway"
+            fi
+        else
+            if [ "$DISTRO" = "termux" ]; then
+                log_info "Termux detected — starting gateway in best-effort background mode..."
+            else
+                log_info "systemd not available — starting gateway in background..."
+            fi
+            nohup $HERMES_CMD gateway > "$HERMES_HOME/logs/gateway.log" 2>&1 &
+            GATEWAY_PID=$!
+            log_success "Gateway started (PID $GATEWAY_PID). Logs: ~/.mente/logs/gateway.log"
+            log_info "To stop: kill $GATEWAY_PID"
+            log_info "To restart later: mente gateway"
+            if [ "$DISTRO" = "termux" ]; then
+                log_warn "Android may stop background processes when Termux is suspended or the system reclaims resources."
+            fi
+        fi
+    else
+        log_info "Skipped. Start the gateway later with: mente gateway"
+    fi
+}
+
+print_success() {
+    echo ""
+    echo -e "${GREEN}${BOLD}"
+    echo "┌─────────────────────────────────────────────────────────┐"
+    echo "│              ✓ Installation Complete!                   │"
+    echo "└─────────────────────────────────────────────────────────┘"
+    echo -e "${NC}"
+    echo ""
+
+    # Show file locations
+    echo -e "${CYAN}${BOLD}📁 Your files:${NC}"
+    echo ""
+    echo -e "   ${YELLOW}Config:${NC}    $HERMES_HOME/config.yaml"
+    echo -e "   ${YELLOW}API Keys:${NC}  $HERMES_HOME/.env"
+    echo -e "   ${YELLOW}Data:${NC}      $HERMES_HOME/cron/, sessions/, logs/"
+    echo -e "   ${YELLOW}Code:${NC}      $INSTALL_DIR"
+    echo ""
+
+    echo -e "${CYAN}─────────────────────────────────────────────────────────${NC}"
+    echo ""
+    echo -e "${CYAN}${BOLD}🚀 Commands:${NC}"
+    echo ""
+    echo -e "   ${GREEN}mente${NC}               Start chatting"
+    echo -e "   ${GREEN}mente setup${NC}         Configure API keys & settings"
+    echo -e "   ${GREEN}mente config${NC}        View/edit configuration"
+    echo -e "   ${GREEN}mente config edit${NC}   Open config in editor"
+    echo -e "   ${GREEN}mente gateway install${NC} Install gateway service (messaging + cron)"
+    echo -e "   ${GREEN}mente update${NC}        Update to latest version"
+    echo ""
+
+    echo -e "${CYAN}─────────────────────────────────────────────────────────${NC}"
+    echo ""
+    if [ "$DISTRO" = "termux" ]; then
+        echo -e "${YELLOW}⚡ 'mente' was linked into $(get_command_link_display_dir), which is already on PATH in Termux.${NC}"
+        echo ""
+    elif [ "$ROOT_FHS_LAYOUT" = true ]; then
+        echo -e "${YELLOW}⚡ 'mente' was linked into /usr/local/bin and is ready to use — no shell reload needed.${NC}"
+        echo ""
+    else
+        echo -e "${YELLOW}⚡ Reload your shell to use 'mente' command:${NC}"
+        echo ""
+        LOGIN_SHELL="$(basename "${SHELL:-/bin/bash}")"
+        if [ "$LOGIN_SHELL" = "zsh" ]; then
+            echo "   source ~/.zshrc"
+        elif [ "$LOGIN_SHELL" = "bash" ]; then
+            echo "   source ~/.bashrc"
+        elif [ "$LOGIN_SHELL" = "fish" ]; then
+            echo "   source ~/.config/fish/config.fish"
+        else
+            echo "   source ~/.bashrc   # or ~/.zshrc"
+        fi
+        echo ""
+    fi
+
+    # Show Node.js warning if auto-install failed
+    if [ "$HAS_NODE" = false ]; then
+        echo -e "${YELLOW}"
+        echo "Note: Node.js could not be installed automatically."
+        echo "Browser tools need Node.js. Install manually:"
+        if [ "$DISTRO" = "termux" ]; then
+            echo "  pkg install nodejs"
+        else
+            echo "  https://nodejs.org/en/download/"
+        fi
+        echo -e "${NC}"
+    fi
+
+    # Show ripgrep note if not installed
+    if [ "$HAS_RIPGREP" = false ]; then
+        echo -e "${YELLOW}"
+        echo "Note: ripgrep (rg) was not found. File search will use"
+        echo "grep as a fallback. For faster search in large codebases,"
+        if [ "$DISTRO" = "termux" ]; then
+            echo "install ripgrep: pkg install ripgrep"
+        else
+            echo "install ripgrep: sudo apt install ripgrep (or brew install ripgrep)"
+        fi
+        echo -e "${NC}"
+    fi
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+main() {
+    print_banner
+
+    detect_os
+    resolve_install_layout
+    install_uv
+    check_python
+    check_git
+    check_node
+    install_system_packages
+
+    clone_repo
+    setup_venv
+    install_deps
+    bootstrap_vendored_runtime
+    install_node_deps
+    setup_path
+    copy_config_templates
+    run_setup_wizard
+    maybe_start_gateway
+
+    print_success
+}
+
+main