@hitechclaw/clawspark 2.0.0

package/clawspark

@@ -0,0 +1,2715 @@
+#!/usr/bin/env bash
+# clawspark - CLI management tool for the clawspark installation.
+# Installed to /usr/local/bin/clawspark by install.sh.
+set -euo pipefail
+
+CLAWSPARK_DEFAULT_HOME="${HOME}/.clawspark"
+CLAWSPARK_V2_HOME="${HOME}/.clawspark-v2"
+
+_detect_clawspark_home() {
+    if [[ -n "${CLAWSPARK_HOME:-}" ]]; then
+        printf '%s' "${CLAWSPARK_HOME}"
+        return 0
+    fi
+
+    case "${CLAWSPARK_PROFILE:-}" in
+        v2)
+            printf '%s' "${CLAWSPARK_V2_HOME}"
+            return 0
+            ;;
+        standard|v1)
+            printf '%s' "${CLAWSPARK_DEFAULT_HOME}"
+            return 0
+            ;;
+    esac
+
+    if [[ -d "${CLAWSPARK_V2_HOME}" && ! -d "${CLAWSPARK_DEFAULT_HOME}" ]]; then
+        printf '%s' "${CLAWSPARK_V2_HOME}"
+    else
+        printf '%s' "${CLAWSPARK_DEFAULT_HOME}"
+    fi
+}
+
+CLAWSPARK_DIR="$(_detect_clawspark_home)"
+CLAWSPARK_LOG="${CLAWSPARK_DIR}/install.log"
+CLAWSPARK_DEFAULTS="${CLAWSPARK_DEFAULTS:-false}"
+CLAWSPARK_PROFILE_NAME="standard"
+[[ "${CLAWSPARK_DIR}" == "${CLAWSPARK_V2_HOME}" ]] && CLAWSPARK_PROFILE_NAME="v2"
+
+# ── Source common helpers ───────────────────────────────────────────────────
+_load_common() {
+    local lib_dir="${CLAWSPARK_DIR}/lib"
+    if [[ -f "${lib_dir}/common.sh" ]]; then
+        # shellcheck source=/dev/null
+        source "${lib_dir}/common.sh"
+    else
+        # Minimal fallback if lib is missing
+        RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'
+        BLUE=$'\033[0;34m'; CYAN=$'\033[0;36m'; BOLD=$'\033[1m'; RESET=$'\033[0m'
+        log_info()    { printf '[INFO] %s\n' "$*"; }
+        log_warn()    { printf '[WARN] %s\n' "$*" >&2; }
+        log_error()   { printf '[ERROR] %s\n' "$*" >&2; }
+        log_success() { printf '[OK] %s\n' "$*"; }
+        check_command() { command -v "$1" &>/dev/null; }
+        hr() { printf '%*s\n' "$(tput cols 2>/dev/null || echo 60)" '' | tr ' ' '-'; }
+        print_box() { for l in "$@"; do printf '  %s\n' "$l"; done; }
+    fi
+}
+
+_load_common
+
+_read_openclaw_json_value() {
+    local json_path="$1"
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    [[ -f "${config_file}" ]] || return 1
+
+    python3 -c '
+import json, sys
+
+config_file = sys.argv[1]
+json_path = sys.argv[2].split(".")
+
+with open(config_file, "r", encoding="utf-8") as fh:
+    value = json.load(fh)
+
+for part in json_path:
+    if not isinstance(value, dict) or part not in value:
+        print("")
+        raise SystemExit(0)
+    value = value[part]
+
+if value is None:
+    print("")
+elif isinstance(value, (dict, list)):
+    print(json.dumps(value))
+else:
+    print(value)
+' "${config_file}" "${json_path}" 2>/dev/null || true
+}
+
+_current_model_ref() {
+    local model_ref
+    model_ref="$(openclaw config get agents.defaults.model 2>/dev/null | tr -d '"' || true)"
+    if [[ -n "${model_ref}" ]]; then
+        printf '%s' "${model_ref}"
+        return 0
+    fi
+
+    _read_openclaw_json_value agents.defaults.model
+}
+
+_current_v2_provider_from_config() {
+    _read_openclaw_json_value clawsparkV2.primaryProvider
+}
+
+_current_custom_provider_label() {
+    if [[ -n "${CUSTOM_AI_PROVIDER_NAME:-}" ]]; then
+        printf '%s' "${CUSTOM_AI_PROVIDER_NAME}"
+        return 0
+    fi
+
+    _read_openclaw_json_value clawsparkV2.customProviderName
+}
+
+_current_provider_base_url() {
+    local env_name
+    env_name="$(_provider_base_url_env_name "$(_current_provider)")" || return 1
+    printf '%s' "${!env_name:-}"
+}
+
+_probe_remote_endpoint_status() {
+    local endpoint="$1"
+
+    if [[ -z "${endpoint}" ]]; then
+        printf 'not configured'
+        return 0
+    fi
+
+    if [[ "${CLAWSPARK_SKIP_REMOTE_HEALTHCHECK:-false}" == "true" ]]; then
+        printf 'skipped'
+        return 0
+    fi
+
+    if ! check_command curl; then
+        printf 'curl unavailable'
+        return 0
+    fi
+
+    local http_code
+    http_code=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 3 "${endpoint}" 2>/dev/null || printf '000')
+
+    if [[ "${http_code}" == "000" ]]; then
+        printf 'unreachable'
+    else
+        printf 'responding (HTTP %s)' "${http_code}"
+    fi
+}
+
+_current_provider_display() {
+    local provider
+    provider="$(_current_provider)"
+
+    if [[ "${provider}" == "custom" ]]; then
+        local custom_label
+        custom_label="$(_current_custom_provider_label)"
+        if [[ -n "${custom_label}" ]]; then
+            printf 'custom (%s)' "${custom_label}"
+            return 0
+        fi
+    fi
+
+    printf '%s' "${provider}"
+}
+
+_provider_api_key_env_name() {
+    local provider="${1:-$(_current_provider)}"
+    case "${provider}" in
+        openai) printf 'OPENAI_API_KEY' ;;
+        anthropic) printf 'ANTHROPIC_API_KEY' ;;
+        openrouter) printf 'OPENROUTER_API_KEY' ;;
+        google) printf 'GOOGLE_API_KEY' ;;
+        custom) printf 'CUSTOM_AI_API_KEY' ;;
+        ollama) printf 'OLLAMA_API_KEY' ;;
+        *) return 1 ;;
+    esac
+}
+
+_provider_base_url_env_name() {
+    local provider="$1"
+    case "${provider}" in
+        ollama) printf 'OLLAMA_BASE_URL' ;;
+        openai) printf 'OPENAI_BASE_URL' ;;
+        anthropic) printf 'ANTHROPIC_BASE_URL' ;;
+        openrouter) printf 'OPENROUTER_BASE_URL' ;;
+        google) printf 'GOOGLE_BASE_URL' ;;
+        custom) printf 'CUSTOM_AI_BASE_URL' ;;
+        *) return 1 ;;
+    esac
+}
+
+_provider_display() {
+    local provider="$1"
+    local custom_label="${2:-}"
+
+    if [[ "${provider}" == "custom" && -n "${custom_label}" ]]; then
+        printf 'custom (%s)' "${custom_label}"
+        return 0
+    fi
+
+    printf '%s' "${provider}"
+}
+
+_join_by() {
+    local delimiter="$1"
+    shift || true
+
+    local first=1
+    local item
+    for item in "$@"; do
+        if [[ ${first} -eq 1 ]]; then
+            printf '%s' "${item}"
+            first=0
+        else
+            printf '%s%s' "${delimiter}" "${item}"
+        fi
+    done
+}
+
+_provider_catalog_rows() {
+    cat <<'EOF'
+ollama|local|local-gpu,local-cpu,hybrid|http://127.0.0.1:11434/v1|Local Ollama runtime
+openai|api|api-only,hybrid|https://api.openai.com/v1|OpenAI hosted API
+anthropic|api|api-only,hybrid|https://api.anthropic.com|Anthropic hosted API
+openrouter|api|api-only,hybrid|https://openrouter.ai/api/v1|OpenRouter aggregator
+google|api|api-only,hybrid|https://generativelanguage.googleapis.com/v1beta/openai|Google OpenAI-compatible endpoint
+custom|api|api-only,hybrid|https://your-provider.example.com/v1|OpenAI-compatible custom endpoint
+EOF
+}
+
+_provider_default_base_url() {
+    local provider="$1"
+    while IFS='|' read -r row_provider _row_type _row_modes row_base_url _row_notes; do
+        if [[ "${row_provider}" == "${provider}" ]]; then
+            printf '%s' "${row_base_url}"
+            return 0
+        fi
+    done < <(_provider_catalog_rows)
+    return 1
+}
+
+_provider_default_index() {
+    if [[ "${CLAWSPARK_DEFAULTS}" == "true" ]]; then
+        printf '%s' "$(_provider_default_index_from_current)"
+        return 0
+    fi
+
+    _provider_default_index_from_current
+}
+
+_provider_default_index_from_current() {
+    local provider="${1:-$(_current_provider)}"
+    local options=("ollama" "openai" "anthropic" "openrouter" "google" "custom")
+    local i
+
+    for i in $(seq 0 $(( ${#options[@]} - 1 ))); do
+        if [[ "${options[$i]}" == "${provider}" ]]; then
+            printf '%s' "${i}"
+            return 0
+        fi
+    done
+
+    printf '0'
+}
+
+_prompt_text_value() {
+    local question="$1"
+    local default_value="${2:-}"
+    local value=""
+
+    if [[ "${CLAWSPARK_DEFAULTS}" == "true" ]]; then
+        printf '%s' "${default_value}"
+        return 0
+    fi
+
+    if [[ -n "${default_value}" ]]; then
+        printf '\n%s%s [%s]:%s ' "${BOLD}" "${question}" "${default_value}" "${RESET}" >/dev/tty
+    else
+        printf '\n%s%s:%s ' "${BOLD}" "${question}" "${RESET}" >/dev/tty
+    fi
+
+    read -r value </dev/tty || value=""
+    if [[ -z "${value}" ]]; then
+        value="${default_value}"
+    fi
+    printf '%s' "${value}"
+}
+
+_current_provider() {
+    if [[ -n "${CLAWSPARK_V2_PRIMARY_PROVIDER:-}" ]]; then
+        printf '%s' "${CLAWSPARK_V2_PRIMARY_PROVIDER}"
+        return 0
+    fi
+
+    local v2_provider
+    v2_provider="$(_current_v2_provider_from_config)"
+    if [[ -n "${v2_provider}" ]]; then
+        printf '%s' "${v2_provider}"
+        return 0
+    fi
+
+    local model_ref
+    model_ref="$(_current_model_ref)"
+    case "${model_ref}" in
+        ollama/*) printf 'ollama' ;;
+        anthropic/*) printf 'anthropic' ;;
+        openai/*) printf 'openai' ;;
+        custom/*) printf 'custom' ;;
+        *) printf 'ollama' ;;
+    esac
+}
+
+_uses_local_ollama() {
+    [[ "$(_current_provider)" == "ollama" ]]
+}
+
+_normalize_model_ref() {
+    local model="$1"
+    local provider="${2:-$(_current_provider)}"
+
+    if [[ "${model}" == */* ]]; then
+        printf '%s' "${model}"
+        return 0
+    fi
+
+    case "${provider}" in
+        openrouter|google|openai) printf 'openai/%s' "${model}" ;;
+        custom) printf 'openai/%s' "${model}" ;;
+        anthropic) printf 'anthropic/%s' "${model}" ;;
+        *) printf 'ollama/%s' "${model}" ;;
+    esac
+}
+
+_gateway_env_file() {
+    printf '%s' "${HOME}/.openclaw/gateway.env"
+}
+
+_ensure_openclaw_dir() {
+    mkdir -p "${HOME}/.openclaw"
+}
+
+_upsert_gateway_env_var() {
+    local key="$1"
+    local value="$2"
+    local env_file
+    env_file="$(_gateway_env_file)"
+
+    _ensure_openclaw_dir
+    touch "${env_file}"
+
+    python3 -c '
+import pathlib, sys
+
+path = pathlib.Path(sys.argv[1])
+key = sys.argv[2]
+value = sys.argv[3]
+line = f"{key}={value}"
+
+lines = []
+found = False
+if path.exists():
+    lines = path.read_text(encoding="utf-8").splitlines()
+
+updated = []
+for existing in lines:
+    if existing.startswith(f"{key}="):
+        if not found:
+            updated.append(line)
+            found = True
+    else:
+        updated.append(existing)
+
+if not found:
+    updated.append(line)
+
+path.write_text("\n".join(updated) + "\n", encoding="utf-8")
+' "${env_file}" "${key}" "${value}" 2>> "${CLAWSPARK_LOG}" || {
+        log_error "Failed to update ${key} in ${env_file}."
+        exit 1
+    }
+
+    chmod 600 "${env_file}" 2>/dev/null || true
+    export "${key}=${value}"
+}
+
+_update_v2_provider_metadata() {
+    local provider="$1"
+    local custom_name="${2:-}"
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    if [[ ! -f "${config_file}" ]]; then
+        log_error "Config not found at ${config_file}. Run install.sh first."
+        exit 1
+    fi
+
+    python3 -c '
+import json, sys
+
+path = sys.argv[1]
+provider = sys.argv[2]
+custom_name = sys.argv[3]
+
+with open(path, "r", encoding="utf-8") as fh:
+    cfg = json.load(fh)
+
+v2 = cfg.setdefault("clawsparkV2", {})
+v2["primaryProvider"] = provider
+if custom_name:
+    v2["customProviderName"] = custom_name
+elif provider != "custom":
+    v2.pop("customProviderName", None)
+
+with open(path, "w", encoding="utf-8") as fh:
+    json.dump(cfg, fh, indent=2)
+' "${config_file}" "${provider}" "${custom_name}" 2>> "${CLAWSPARK_LOG}" || {
+        log_error "Failed to update provider metadata in ${config_file}."
+        exit 1
+    }
+}
+
+_cmd_provider_show() {
+    local provider_display provider base_url api_key_env
+    provider_display="$(_current_provider_display)"
+    provider="$(_current_provider)"
+    base_url="$(_current_provider_base_url 2>/dev/null || true)"
+    api_key_env="$(_provider_api_key_env_name "${provider}" 2>/dev/null || true)"
+
+    printf '\n%s%s clawspark provider%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+    printf '  %-22s %s\n' "Profile" "${CLAWSPARK_PROFILE_NAME}"
+    printf '  %-22s %s\n' "Provider" "${provider_display}"
+
+    if [[ -n "${base_url}" ]]; then
+        printf '  %-22s %s\n' "Base URL" "${base_url}"
+    else
+        printf '  %-22s %s\n' "Base URL" "(not configured)"
+    fi
+
+    if [[ -n "${api_key_env}" ]]; then
+        if [[ -n "${!api_key_env:-}" ]]; then
+            printf '  %-22s %s\n' "API key" "configured via ${api_key_env}"
+        else
+            printf '  %-22s %s\n' "API key" "missing (${api_key_env})"
+        fi
+    fi
+
+    if [[ "${provider}" == "custom" ]]; then
+        printf '\n  Update custom provider:\n'
+        printf '    clawspark provider set custom --name <label> --base-url <url> [--api-key <key>]\n'
+    elif [[ "${provider}" != "ollama" ]]; then
+        printf '\n  Update remote provider:\n'
+        printf '    clawspark provider set %s --base-url <url> [--api-key <key>]\n' "${provider}"
+    fi
+    printf '\n'
+}
+
+_cmd_provider_list() {
+    local current_provider current_base_url
+    current_provider="$(_current_provider)"
+    current_base_url="$(_current_provider_base_url 2>/dev/null || true)"
+
+    printf '\n%s%s clawspark provider catalog%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+    printf '  %-10s %-8s %-23s %-58s %s\n' "Provider" "Type" "Runtime Modes" "Default Base URL" "Notes"
+    printf '  %-10s %-8s %-23s %-58s %s\n' "--------" "----" "-------------" "----------------" "-----"
+
+    while IFS='|' read -r provider provider_type runtime_modes default_base_url notes; do
+        local marker=" "
+        if [[ "${provider}" == "${current_provider}" ]]; then
+            marker="*"
+        fi
+        printf '%s %-10s %-8s %-23s %-58s %s\n' "${marker}" "${provider}" "${provider_type}" "${runtime_modes}" "${default_base_url}" "${notes}"
+    done < <(_provider_catalog_rows)
+
+    if [[ -n "${current_base_url}" ]]; then
+        printf '\n  Active provider URL: %s\n' "${current_base_url}"
+    fi
+    printf '  Use %sclawspark provider set <provider> ...%s to switch providers.\n\n' "${CYAN}" "${RESET}"
+}
+
+_cmd_provider_doctor() {
+    local output_format="text"
+    local provider provider_display base_url api_key_env api_key_value model_ref endpoint_state custom_label
+    local has_issue=0
+    local -a issues=()
+    local -a suggestions=()
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --json)
+                output_format="json"
+                shift
+                ;;
+            *)
+                log_error "Unknown provider doctor option: $1"
+                printf '  Usage: clawspark provider doctor [--json]\n'
+                exit 1
+                ;;
+        esac
+    done
+
+    provider="$(_current_provider)"
+    provider_display="$(_current_provider_display)"
+    base_url="$(_current_provider_base_url 2>/dev/null || true)"
+    api_key_env="$(_provider_api_key_env_name "${provider}" 2>/dev/null || true)"
+    model_ref="$(_current_model_ref)"
+    custom_label="$(_current_custom_provider_label 2>/dev/null || true)"
+
+    if [[ -n "${api_key_env}" ]]; then
+        api_key_value="${!api_key_env:-}"
+    else
+        api_key_value=""
+    fi
+
+    if [[ -n "${base_url}" ]]; then
+        :
+    else
+        issues+=("Base URL is not configured")
+        suggestions+=("Run clawspark provider set ${provider} --base-url <url> to configure the endpoint")
+        has_issue=1
+    fi
+
+    if [[ "${provider}" == "custom" ]]; then
+        if [[ -n "${custom_label}" ]]; then
+            :
+        else
+            issues+=("Custom provider label is missing")
+            suggestions+=("Run clawspark provider set custom --name <label> --base-url <url>")
+            has_issue=1
+        fi
+    fi
+
+    if [[ -n "${api_key_env}" ]]; then
+        if [[ -n "${api_key_value}" ]]; then
+            :
+        elif [[ "${provider}" == "ollama" ]]; then
+            suggestions+=("Set OLLAMA_API_KEY=ollama in ~/.openclaw/gateway.env for local compatibility")
+        else
+            issues+=("API key is missing (${api_key_env})")
+            suggestions+=("Export ${api_key_env} in ~/.openclaw/gateway.env or rerun clawspark provider set ${provider} --api-key <key>")
+            has_issue=1
+        fi
+    fi
+
+    case "${provider}" in
+        ollama)
+            if [[ -n "${model_ref}" && "${model_ref}" != ollama/* ]]; then
+                issues+=("Model ref does not match provider. Expected ollama/* but found ${model_ref}")
+                suggestions+=("Switch to an Ollama model with clawspark model switch <model>")
+                has_issue=1
+            fi
+            ;;
+        anthropic)
+            if [[ -n "${model_ref}" && "${model_ref}" != anthropic/* ]]; then
+                issues+=("Model ref does not match provider. Expected anthropic/* but found ${model_ref}")
+                suggestions+=("Update the default model to anthropic/<model> in OpenClaw config")
+                has_issue=1
+            fi
+            ;;
+        openai|openrouter|google|custom)
+            if [[ -n "${model_ref}" && "${model_ref}" != openai/* ]]; then
+                issues+=("Model ref does not match provider. Expected openai/* but found ${model_ref}")
+                suggestions+=("Update the default model to openai/<model> in OpenClaw config")
+                has_issue=1
+            fi
+            ;;
+    esac
+
+    if [[ "${provider}" != "ollama" ]]; then
+        endpoint_state="$(_probe_remote_endpoint_status "${base_url}")"
+        case "${endpoint_state}" in
+            responding*|skipped|curl\ unavailable)
+                ;;
+            *)
+                issues+=("Endpoint probe reported: ${endpoint_state}")
+                suggestions+=("Verify network reachability and confirm the configured base URL: ${base_url}")
+                has_issue=1
+                ;;
+        esac
+    else
+        endpoint_state="local"
+    fi
+
+    if [[ "${output_format}" == "json" ]]; then
+        local issues_joined suggestions_joined
+        issues_joined="$(_join_by '||' "${issues[@]}")"
+        suggestions_joined="$(_join_by '||' "${suggestions[@]}")"
+
+        python3 - <<'PY' "${provider}" "${provider_display}" "${model_ref}" "${base_url}" "${api_key_env}" "${api_key_value}" "${custom_label}" "${endpoint_state}" "${has_issue}" "${issues_joined}" "${suggestions_joined}"
+import json, sys
+
+provider, provider_display, model_ref, base_url, api_key_env, api_key_value, custom_label, endpoint_state, has_issue, issues_raw, suggestions_raw = sys.argv[1:]
+
+payload = {
+    "provider": provider,
+    "providerDisplay": provider_display,
+    "model": model_ref,
+    "baseUrl": base_url,
+    "apiKeyEnv": api_key_env,
+    "apiKeyConfigured": bool(api_key_value),
+    "customProviderName": custom_label,
+    "endpointProbe": endpoint_state,
+    "status": "issues" if has_issue == "1" else "ok",
+    "issues": [item for item in issues_raw.split("||") if item],
+    "suggestions": [item for item in suggestions_raw.split("||") if item],
+}
+
+print(json.dumps(payload, indent=2))
+PY
+
+        if [[ ${has_issue} -eq 0 ]]; then
+            return 0
+        fi
+        return 1
+    fi
+
+    printf '\n%s%s clawspark provider doctor%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+    printf '  %-22s %s\n' "Provider" "${provider_display}"
+    printf '  %-22s %s\n' "Model" "${model_ref:-not configured}"
+    printf '  %-22s %s\n' "Base URL" "${base_url:-missing}"
+    if [[ "${provider}" == "custom" ]]; then
+        printf '  %-22s %s\n' "Custom label" "${custom_label:-missing}"
+    fi
+    if [[ -n "${api_key_env}" ]]; then
+        if [[ -n "${api_key_value}" ]]; then
+            printf '  %-22s configured via %s\n' "API key" "${api_key_env}"
+        else
+            printf '  %-22s missing (%s)\n' "API key" "${api_key_env}"
+        fi
+    fi
+    printf '  %-22s %s\n' "Endpoint probe" "${endpoint_state}"
+
+    if [[ -n "${base_url}" ]]; then
+        log_success "Base URL is configured"
+    else
+        log_warn "Base URL is not configured"
+    fi
+    if [[ "${provider}" == "custom" ]]; then
+        if [[ -n "${custom_label}" ]]; then
+            log_success "Custom provider label is set: ${custom_label}"
+        else
+            log_warn "Custom provider label is missing"
+        fi
+    fi
+    if [[ -n "${api_key_env}" ]]; then
+        if [[ -n "${api_key_value}" ]]; then
+            log_success "API key is configured via ${api_key_env}"
+        elif [[ "${provider}" == "ollama" ]]; then
+            log_warn "OLLAMA_API_KEY is missing; local mode usually works best with OLLAMA_API_KEY=ollama"
+        else
+            log_warn "API key is missing (${api_key_env})"
+        fi
+    fi
+    if [[ ${#issues[@]} -eq 0 ]]; then
+        log_success "Model ref matches provider"
+        if [[ "${provider}" != "ollama" ]]; then
+            log_success "Endpoint probe completed: ${endpoint_state}"
+        fi
+    else
+        local issue
+        for issue in "${issues[@]}"; do
+            log_warn "${issue}"
+        done
+    fi
+
+    if [[ ${#suggestions[@]} -gt 0 ]]; then
+        local suggestion
+        printf '\n  Suggestions:\n'
+        for suggestion in "${suggestions[@]}"; do
+            printf '    - %s\n' "${suggestion}"
+        done
+    fi
+
+    printf '\n'
+    if [[ ${has_issue} -eq 0 ]]; then
+        log_success "Provider diagnostics passed"
+        return 0
+    fi
+
+    log_warn "Provider diagnostics found issues"
+    return 1
+}
+
+_cmd_provider_set_remote() {
+    local provider="$1"
+    shift || true
+
+    local base_url=""
+    local api_key=""
+    local provider_name=""
+    local api_key_env=""
+    local base_url_env=""
+
+    case "${provider}" in
+        ollama|openai|anthropic|openrouter|google|custom)
+            ;;
+        *)
+            log_error "Unsupported remote provider: ${provider}"
+            printf '  Usage: clawspark provider set <ollama|openai|anthropic|openrouter|google|custom> [options]\n'
+            exit 1
+            ;;
+    esac
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --name)
+                provider_name="${2:-}"
+                shift 2
+                ;;
+            --base-url)
+                base_url="${2:-}"
+                shift 2
+                ;;
+            --api-key)
+                api_key="${2:-}"
+                shift 2
+                ;;
+            *)
+                log_error "Unknown provider option: $1"
+                if [[ "${provider}" == "custom" ]]; then
+                    printf '  Usage: clawspark provider set custom --name <label> --base-url <url> [--api-key <key>]\n'
+                elif [[ "${provider}" == "ollama" ]]; then
+                    printf '  Usage: clawspark provider set ollama [--base-url <url>]\n'
+                else
+                    printf '  Usage: clawspark provider set %s --base-url <url> [--api-key <key>]\n' "${provider}"
+                fi
+                exit 1
+                ;;
+        esac
+    done
+
+    [[ -z "${base_url}" ]] && {
+        if [[ "${provider}" == "custom" ]]; then
+            log_error "Usage: clawspark provider set custom --name <label> --base-url <url> [--api-key <key>]"
+        elif [[ "${provider}" == "ollama" ]]; then
+            log_error "Usage: clawspark provider set ollama [--base-url <url>]"
+        else
+            log_error "Usage: clawspark provider set ${provider} --base-url <url> [--api-key <key>]"
+        fi
+        exit 1
+    }
+
+    if [[ ! "${base_url}" =~ ^https?:// ]]; then
+        log_error "Provider base URL must start with http:// or https://"
+        exit 1
+    fi
+
+    if [[ "${provider}" == "custom" && -z "${provider_name}" ]]; then
+        log_error "Usage: clawspark provider set custom --name <label> --base-url <url> [--api-key <key>]"
+        exit 1
+    fi
+
+    base_url_env="$(_provider_base_url_env_name "${provider}")"
+    api_key_env="$(_provider_api_key_env_name "${provider}")"
+
+    _upsert_gateway_env_var "CLAWSPARK_V2_PRIMARY_PROVIDER" "${provider}"
+    _upsert_gateway_env_var "${base_url_env}" "${base_url}"
+    if [[ -n "${api_key}" ]]; then
+        _upsert_gateway_env_var "${api_key_env}" "${api_key}"
+    fi
+
+    if [[ "${provider}" == "custom" ]]; then
+        _upsert_gateway_env_var "CUSTOM_AI_PROVIDER_NAME" "${provider_name}"
+        _update_v2_provider_metadata "custom" "${provider_name}"
+    else
+        _update_v2_provider_metadata "${provider}"
+    fi
+
+    CLAWSPARK_PROFILE_NAME="v2"
+
+    if [[ "${provider}" == "custom" && "${CLAWSPARK_PROVIDER_SET_ALIAS:-}" == "set-custom" ]]; then
+        log_success "Custom provider updated: ${provider_name}"
+    else
+        log_success "Provider updated: $(_provider_display "${provider}" "${provider_name}")"
+    fi
+    log_info "Provider base URL: ${base_url}"
+    if [[ -n "${api_key}" ]]; then
+        log_info "API key saved to ${api_key_env}"
+    fi
+    log_info "Restart to apply: clawspark restart"
+}
+
+_cmd_provider_use() {
+    local provider="${1:-}"
+    shift || true
+
+    local base_url=""
+    local api_key=""
+    local provider_name=""
+    local set_args=()
+
+    if [[ -z "${provider}" ]]; then
+        local provider_options=("ollama" "openai" "anthropic" "openrouter" "google" "custom")
+        local default_idx
+        default_idx="$(_provider_default_index)"
+        provider=$(prompt_choice "Choose provider" provider_options "${default_idx}")
+    fi
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --base-url)
+                base_url="${2:-}"
+                shift 2
+                ;;
+            --api-key)
+                api_key="${2:-}"
+                shift 2
+                ;;
+            --name)
+                provider_name="${2:-}"
+                shift 2
+                ;;
+            *)
+                log_error "Unknown provider option: $1"
+                printf '  Usage: clawspark provider use <ollama|openai|anthropic|openrouter|google|custom> [--base-url <url>] [--api-key <key>] [--name <label>]\n'
+                exit 1
+                ;;
+        esac
+    done
+
+    case "${provider}" in
+        ollama|openai|anthropic|openrouter|google|custom)
+            ;;
+        *)
+            log_error "Unsupported provider: ${provider}"
+            exit 1
+            ;;
+    esac
+
+    if [[ -z "${base_url}" ]]; then
+        if [[ "${provider}" == "custom" ]]; then
+            base_url="$(_prompt_text_value "Enter custom provider base URL" "$(_current_provider_base_url 2>/dev/null || _provider_default_base_url custom || true)")"
+        else
+            base_url="$(_provider_default_base_url "${provider}" 2>/dev/null || true)"
+        fi
+    fi
+
+    if [[ -z "${base_url}" ]]; then
+        log_error "No default base URL is available for provider: ${provider}"
+        exit 1
+    fi
+
+    if [[ "${provider}" == "custom" && -z "${provider_name}" ]]; then
+        provider_name="$(_prompt_text_value "Enter custom provider name" "$(_current_custom_provider_label 2>/dev/null || true)")"
+        if [[ -z "${provider_name}" ]]; then
+            log_error "Custom provider requires --name with clawspark provider use custom"
+            exit 1
+        fi
+    fi
+
+    if [[ "${provider}" == "custom" && ! "${base_url}" =~ ^https?:// ]]; then
+        log_error "Custom provider requires a valid http:// or https:// base URL"
+        exit 1
+    fi
+
+    if [[ "${provider}" == "ollama" && -z "${api_key}" && -z "${OLLAMA_API_KEY:-}" ]]; then
+        api_key="ollama"
+    fi
+
+    set_args=(--base-url "${base_url}")
+    if [[ -n "${api_key}" ]]; then
+        set_args+=(--api-key "${api_key}")
+    fi
+    if [[ -n "${provider_name}" ]]; then
+        set_args+=(--name "${provider_name}")
+    fi
+
+    _cmd_provider_set_remote "${provider}" "${set_args[@]}"
+
+    if [[ -n "${api_key}" ]]; then
+        :
+    else
+        local api_key_env
+        api_key_env="$(_provider_api_key_env_name "${provider}" 2>/dev/null || true)"
+        if [[ -n "${api_key_env}" && -z "${!api_key_env:-}" && "${provider}" != "ollama" ]]; then
+            log_warn "No API key was provided. Set ${api_key_env} before using remote inference."
+        fi
+    fi
+}
+
+_cmd_provider_set_custom() {
+    local CLAWSPARK_PROVIDER_SET_ALIAS="set-custom"
+    _cmd_provider_set_remote custom "$@"
+}
+
+_cmd_provider() {
+    local subcmd="${1:-show}"
+    shift || true
+
+    case "${subcmd}" in
+        list)
+            _cmd_provider_list
+            ;;
+        doctor)
+            _cmd_provider_doctor "$@"
+            ;;
+        show)
+            _cmd_provider_show
+            ;;
+        set)
+            local provider_name="${1:-}"
+            [[ -z "${provider_name}" ]] && {
+                log_error "Usage: clawspark provider set <ollama|openai|anthropic|openrouter|google|custom> [options]"
+                exit 1
+            }
+            shift || true
+            _cmd_provider_set_remote "${provider_name}" "$@"
+            ;;
+        use)
+            _cmd_provider_use "$@"
+            ;;
+        set-custom)
+            _cmd_provider_set_custom "$@"
+            ;;
+        *)
+            log_error "Unknown provider subcommand: ${subcmd}"
+            printf '  Usage: clawspark provider [show|list|doctor [--json]|set <provider> [options]|use [provider] [options]|set-custom --name <label> --base-url <url> [--api-key <key>]]\n'
+            exit 1
+            ;;
+    esac
+}
+
+# ── Source sandbox commands ────────────────────────────────────────────────
+_load_sandbox_commands() {
+    local lib_dir="${CLAWSPARK_DIR}/lib"
+    if [[ -f "${lib_dir}/sandbox-commands.sh" ]]; then
+        # shellcheck source=/dev/null
+        source "${lib_dir}/sandbox-commands.sh"
+    fi
+}
+
+_load_sandbox_commands
+
+# ── Source diagnose module ────────────────────────────────────────────────
+_load_diagnose() {
+    local lib_dir="${CLAWSPARK_DIR}/lib"
+    if [[ -f "${lib_dir}/diagnose.sh" ]]; then
+        # shellcheck source=/dev/null
+        source "${lib_dir}/diagnose.sh"
+    fi
+}
+
+# ── Source skill audit module ─────────────────────────────────────────────
+_load_skill_audit() {
+    local lib_dir="${CLAWSPARK_DIR}/lib"
+    if [[ -f "${lib_dir}/skill-audit.sh" ]]; then
+        # shellcheck source=/dev/null
+        source "${lib_dir}/skill-audit.sh"
+    fi
+}
+
+# ── Version ─────────────────────────────────────────────────────────────────
+CLAWSPARK_VERSION="2.0.0"
+
+# ── Usage ───────────────────────────────────────────────────────────────────
+_usage() {
+    cat <<USAGE
+${BOLD}clawspark${RESET} v${CLAWSPARK_VERSION} - manage your OpenClaw AI agent
+
+${BOLD}Usage:${RESET}
+  clawspark <command> [options]
+
+${BOLD}Commands:${RESET}
+  ${GREEN}status${RESET}              Show status of all components
+  ${GREEN}skills sync${RESET}         Re-read skills.yaml and install/remove skills
+  ${GREEN}skills add <name>${RESET}   Add a skill and install it
+  ${GREEN}skills remove <name>${RESET} Remove a skill
+  ${GREEN}skills pack [name]${RESET}  Install a curated skill pack (or list available packs)
+  ${GREEN}skills audit${RESET}        Scan installed skills for security issues
+  ${GREEN}benchmark${RESET}           Run a performance benchmark
+  ${GREEN}update${RESET}              Update OpenClaw and re-sync skills
+  ${GREEN}dashboard${RESET}           Show dashboard URLs and start ClawMetry if needed
+  ${GREEN}tailscale setup${RESET}    Configure Tailscale remote access
+  ${GREEN}tailscale status${RESET}   Show Tailscale connection status and URLs
+  ${GREEN}airgap on|off${RESET}       Toggle air-gap mode
+  ${GREEN}logs${RESET}                Tail gateway logs
+  ${GREEN}start${RESET}               Start all services (Ollama, gateway, node host, dashboard)
+  ${GREEN}stop${RESET}                Stop services (add --all to also stop Ollama)
+  ${GREEN}restart${RESET}             Restart Ollama, gateway, node host, and dashboard
+  ${GREEN}uninstall${RESET}           Remove everything (with confirmation)
+  ${GREEN}model list${RESET}           Show available and active models
+  ${GREEN}model switch <model>${RESET} Change the primary chat model
+  ${GREEN}model vision${RESET}         Set or show the vision model
+    ${GREEN}provider${RESET}            Show current provider configuration
+    ${GREEN}provider list${RESET}       Show supported provider catalog
+    ${GREEN}provider doctor${RESET}     Validate current provider setup
+    ${GREEN}provider doctor --json${RESET} Output diagnostics as JSON
+    ${GREEN}provider set <p> ...${RESET} Update remote provider settings
+    ${GREEN}provider use [p]${RESET}  Switch provider using default endpoints
+    ${GREEN}provider set-custom ...${RESET} Update custom provider settings
+  ${GREEN}tools${RESET}               List agent tools and their status
+  ${GREEN}tools enable <name>${RESET}  Enable an additional tool (e.g. email, browser)
+  ${GREEN}tools disable <name>${RESET} Disable a tool for the personal agent
+  ${GREEN}sandbox${RESET}             Show sandbox status
+  ${GREEN}sandbox on${RESET}          Enable Docker sandbox for code execution
+  ${GREEN}sandbox off${RESET}         Disable sandbox (run code on host)
+  ${GREEN}sandbox test${RESET}        Verify sandbox isolation with test suite
+  ${GREEN}mcp list${RESET}            List configured MCP servers
+  ${GREEN}mcp setup${RESET}           Install default MCP servers (diagrams, memory, etc.)
+  ${GREEN}mcp add <n> <cmd>${RESET}   Add a custom MCP server
+  ${GREEN}mcp remove <n>${RESET}      Remove an MCP server
+  ${GREEN}diagnose${RESET}            Run full system diagnostics (alias: doctor)
+  ${GREEN}help${RESET}                Show this help message
+
+USAGE
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  HELPERS
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Kill a process from a PID file, then remove the file
+_kill_pid_file() {
+    local pid_file="$1"
+    if [[ -f "${pid_file}" ]]; then
+        local pid
+        pid=$(cat "${pid_file}" 2>/dev/null || echo "")
+        if [[ -n "${pid}" ]] && [[ "${pid}" =~ ^[0-9]+$ ]]; then
+            kill "${pid}" 2>/dev/null || true
+        fi
+        rm -f "${pid_file}"
+    fi
+}
+
+# Also kill by process name pattern as a fallback
+_kill_by_name() {
+    local pattern="$1"
+    pkill -f "${pattern}" 2>/dev/null || true
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  SHARED HELPERS
+# ═══════════════════════════════════════════════════════════════════════════
+
+# _check_service_running LABEL SYSTEMD_UNIT PID_FILE
+#   Prints the status line for a service, checking systemd first then PID file.
+_check_service_running() {
+    local label="$1"
+    local unit="$2"
+    local pid_file="$3"
+    if [[ -f "/etc/systemd/system/${unit}" ]] && \
+       systemctl is-active --quiet "${unit}" 2>/dev/null; then
+        printf '  %s✓%s %-17s running (systemd)\n' "${GREEN}" "${RESET}" "${label}"
+    elif [[ -f "${pid_file}" ]]; then
+        local pid
+        pid=$(cat "${pid_file}" 2>/dev/null || echo "")
+        if [[ -n "${pid}" ]] && kill -0 "${pid}" 2>/dev/null; then
+            printf '  %s✓%s %-17s running (PID %s)\n' "${GREEN}" "${RESET}" "${label}" "${pid}"
+        else
+            printf '  %s✗%s %-17s not running (stale PID)\n' "${YELLOW}" "${RESET}" "${label}"
+        fi
+    else
+        printf '  %s-%s %-17s not started\n' "${YELLOW}" "${RESET}" "${label}"
+    fi
+}
+
+_source_gateway_env() {
+    local env_file="${HOME}/.openclaw/gateway.env"
+    if [[ -f "${env_file}" ]]; then
+        local line key val
+        while IFS= read -r line || [[ -n "${line}" ]]; do
+            [[ "${line}" =~ ^[[:space:]]*# ]] && continue
+            [[ -z "${line// }" ]] && continue
+            if [[ "${line}" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*) ]]; then
+                key="${BASH_REMATCH[1]}"
+                val="${BASH_REMATCH[2]}"
+                val="${val%\"}" ; val="${val#\"}"
+                val="${val%\'}" ; val="${val#\'}"
+                export "${key}=${val}"
+            fi
+        done < "${env_file}"
+    fi
+
+    if [[ -z "${CLAWSPARK_PROFILE:-}" && -n "${CLAWSPARK_V2_RUNTIME_MODE:-}" ]]; then
+        CLAWSPARK_PROFILE_NAME="v2"
+    fi
+}
+
+_source_gateway_env
+
+_wait_for_ollama() {
+    local attempts=0
+    while (( attempts < 15 )); do
+        if curl -sf http://127.0.0.1:11434/ &>/dev/null; then return 0; fi
+        attempts=$(( attempts + 1 ))
+        sleep 1
+    done
+    log_error "Ollama failed to become ready after 15 seconds."
+    return 1
+}
+
+_detect_systemd() {
+    if ! check_command systemctl; then
+        echo "false"; return
+    fi
+    if systemctl cat clawspark-gateway.service &>/dev/null; then
+        echo "true"; return
+    fi
+    echo "false"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  COMMANDS
+# ═══════════════════════════════════════════════════════════════════════════
+
+# ── status ──────────────────────────────────────────────────────────────────
+_cmd_status() {
+    printf '\n%s%s clawspark status%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    printf '  %s-%s Profile           %s\n' "${CYAN}" "${RESET}" "${CLAWSPARK_PROFILE_NAME}"
+
+    local provider
+    provider="$(_current_provider)"
+    local provider_display
+    provider_display="$(_current_provider_display)"
+    printf '  %s-%s Provider          %s\n' "${CYAN}" "${RESET}" "${provider_display}"
+
+    # Ollama
+    if _uses_local_ollama; then
+        if curl -sf http://127.0.0.1:11434/ &>/dev/null; then
+            printf '  %s✓%s Ollama            running\n' "${GREEN}" "${RESET}"
+        else
+            printf '  %s✗%s Ollama            not running\n' "${RED}" "${RESET}"
+        fi
+
+        # Models
+        if check_command ollama; then
+            local model_count
+            model_count=$(ollama list 2>/dev/null | tail -n +2 | wc -l | tr -d ' ')
+            printf '  %s✓%s Models            %s loaded\n' "${GREEN}" "${RESET}" "${model_count}"
+        else
+            printf '  %s✗%s Models            ollama not found\n' "${RED}" "${RESET}"
+        fi
+    else
+        printf '  %s-%s Ollama            not required for %s\n' "${CYAN}" "${RESET}" "${provider}"
+
+        local endpoint endpoint_state
+        endpoint="$(_current_provider_base_url)"
+        endpoint_state="$(_probe_remote_endpoint_status "${endpoint}")"
+        printf '  %s-%s Remote endpoint   %s\n' "${CYAN}" "${RESET}" "${endpoint_state}"
+        if [[ -n "${endpoint}" ]]; then
+            printf '  %s-%s Base URL          %s\n' "${CYAN}" "${RESET}" "${endpoint}"
+        fi
+    fi
+
+    # OpenClaw
+    if check_command openclaw; then
+        local oc_ver
+        oc_ver=$(openclaw --version 2>/dev/null || echo "unknown")
+        printf '  %s✓%s OpenClaw          %s\n' "${GREEN}" "${RESET}" "${oc_ver}"
+    else
+        printf '  %s✗%s OpenClaw          not installed\n' "${RED}" "${RESET}"
+    fi
+
+    _check_service_running "Gateway" "clawspark-gateway.service" "${CLAWSPARK_DIR}/gateway.pid"
+    _check_service_running "Node host" "clawspark-nodehost.service" "${CLAWSPARK_DIR}/node.pid"
+    _check_service_running "Dashboard" "clawspark-dashboard.service" "${CLAWSPARK_DIR}/dashboard.pid"
+
+    # Skills
+    local skill_count=0
+    if [[ -f "${CLAWSPARK_DIR}/skills.yaml" ]]; then
+        skill_count=$(grep -c '^ *- ' "${CLAWSPARK_DIR}/skills.yaml" 2>/dev/null || echo 0)
+    fi
+    printf '  %s✓%s Skills            %s configured\n' "${GREEN}" "${RESET}" "${skill_count}"
+
+    # Air-gap
+    local ag_state="off"
+    if [[ -f "${CLAWSPARK_DIR}/airgap.state" ]]; then
+        ag_state=$(cat "${CLAWSPARK_DIR}/airgap.state")
+        [[ "${ag_state}" == "true" ]] && ag_state="ON" || ag_state="off"
+    fi
+    printf '  %s-%s Air-gap           %s\n' "${CYAN}" "${RESET}" "${ag_state}"
+
+    # Sandbox
+    local sb_state="off"
+    if [[ -f "${CLAWSPARK_DIR}/sandbox.state" ]]; then
+        sb_state=$(cat "${CLAWSPARK_DIR}/sandbox.state")
+        [[ "${sb_state}" == "true" ]] && sb_state="ON" || sb_state="off"
+    fi
+    if check_command docker && docker image inspect clawspark-sandbox:latest &>/dev/null 2>&1; then
+        printf '  %s✓%s Sandbox           %s (image ready)\n' "${GREEN}" "${RESET}" "${sb_state}"
+    else
+        printf '  %s-%s Sandbox           %s\n' "${CYAN}" "${RESET}" "${sb_state}"
+    fi
+
+    # Token
+    if [[ -f "${CLAWSPARK_DIR}/token" ]]; then
+        printf '  %s✓%s Token             present\n' "${GREEN}" "${RESET}"
+    else
+        printf '  %s-%s Token             not generated\n' "${YELLOW}" "${RESET}"
+    fi
+
+    printf '\n'
+}
+
+# ── skills ──────────────────────────────────────────────────────────────────
+_cmd_skills() {
+    local subcmd="${1:-}"
+    shift || true
+
+    case "${subcmd}" in
+        sync)
+            _skills_sync
+            ;;
+        add)
+            local name="${1:-}"
+            [[ -z "${name}" ]] && { log_error "Usage: clawspark skills add <name>"; exit 1; }
+            _skills_add "${name}"
+            ;;
+        remove)
+            local name="${1:-}"
+            [[ -z "${name}" ]] && { log_error "Usage: clawspark skills remove <name>"; exit 1; }
+            _skills_remove "${name}"
+            ;;
+        pack)
+            local pack_name="${1:-}"
+            [[ -z "${pack_name}" ]] && { _skills_list_packs; return 0; }
+            _skills_install_pack "${pack_name}"
+            ;;
+        audit)
+            _load_skill_audit
+            if command -v audit_skills &>/dev/null; then
+                audit_skills
+            else
+                log_error "Skill audit module not found. Re-install clawspark."
+                exit 1
+            fi
+            ;;
+        *)
+            log_error "Unknown skills subcommand: ${subcmd}"
+            printf '  Usage: clawspark skills [sync|add <name>|remove <name>|pack [name]|audit]\n'
+            exit 1
+            ;;
+    esac
+}
+
+_skills_sync() {
+    local skills_file="${CLAWSPARK_DIR}/skills.yaml"
+    if [[ ! -f "${skills_file}" ]]; then
+        log_error "No skills.yaml found at ${skills_file}"
+        exit 1
+    fi
+
+    log_info "Syncing skills from ${skills_file}..."
+
+    local -a skills=()
+    while IFS= read -r slug; do
+        skills+=("${slug}")
+    done < <(_parse_enabled_skills "${skills_file}")
+
+    log_info "Found ${#skills[@]} skill(s). Installing..."
+    local installed=0 failed=0
+    for skill in "${skills[@]}"; do
+        printf '  %s→%s %s ... ' "${CYAN}" "${RESET}" "${skill}"
+        if npx --yes clawhub@latest install --force "${skill}" >> "${CLAWSPARK_LOG}" 2>&1; then
+            printf '%s✓%s\n' "${GREEN}" "${RESET}"
+            installed=$(( installed + 1 ))
+        else
+            printf '%s✗%s\n' "${YELLOW}" "${RESET}"
+            failed=$(( failed + 1 ))
+        fi
+    done
+    log_success "Sync complete: ${installed} installed, ${failed} failed."
+}
+
+_skills_add() {
+    local name="$1"
+    local skills_file="${CLAWSPARK_DIR}/skills.yaml"
+
+    # Check if already present
+    if grep -q "name: ${name}" "${skills_file}" 2>/dev/null || \
+       grep -q "^  *- ${name}$" "${skills_file}" 2>/dev/null; then
+        log_info "Skill '${name}' is already in skills.yaml."
+    else
+        # Append under enabled section
+        # Find the last "- name:" line and add after it
+        local tmpfile
+        tmpfile=$(mktemp)
+        awk -v skill="${name}" '
+            /enabled:/ { in_enabled=1 }
+            in_enabled && /^[[:space:]]*custom:/ {
+                printf "    - name: %s\n      description: User-added skill\n", skill
+                in_enabled=0
+            }
+            { print }
+        ' "${skills_file}" > "${tmpfile}"
+        mv "${tmpfile}" "${skills_file}"
+        log_success "Added '${name}' to skills.yaml."
+    fi
+
+    log_info "Installing '${name}'..."
+    if npx --yes clawhub@latest install --force "${name}" >> "${CLAWSPARK_LOG}" 2>&1; then
+        log_success "Skill '${name}' installed."
+    else
+        log_error "Failed to install '${name}'. Check ${CLAWSPARK_LOG}."
+    fi
+}
+
+_skills_remove() {
+    local name="$1"
+    local skills_file="${CLAWSPARK_DIR}/skills.yaml"
+
+    # Remove from YAML (handles both "- name: slug" multiline and "- slug" single line)
+    local tmpfile
+    tmpfile=$(mktemp)
+    awk -v skill="${name}" '
+        /^[[:space:]]*- name:/ && $0 ~ skill { skip=1; next }
+        skip && /^[[:space:]]+description:/ { skip=0; next }
+        skip { skip=0 }
+        /^[[:space:]]*-[[:space:]]+/ && $0 ~ skill { next }
+        { print }
+    ' "${skills_file}" > "${tmpfile}"
+    mv "${tmpfile}" "${skills_file}"
+
+    log_success "Removed '${name}' from skills.yaml."
+    log_info "Note: The skill package may still be cached locally."
+}
+
+_skills_list_packs() {
+    local packs_file="${CLAWSPARK_DIR}/configs/skill-packs.yaml"
+    if [[ ! -f "${packs_file}" ]]; then
+        packs_file="$(cd "$(dirname "$0")" && pwd)/configs/skill-packs.yaml"
+    fi
+    if [[ ! -f "${packs_file}" ]]; then
+        log_error "No skill-packs.yaml found."
+        exit 1
+    fi
+
+    printf '\n%s%sAvailable skill packs%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    local current_pack="" current_desc="" skill_count=0
+    while IFS= read -r line; do
+        [[ "${line}" =~ ^[[:space:]]*# ]] && continue
+        [[ -z "${line// }" ]] && continue
+
+        # Detect pack name (indented exactly 2 spaces, ends with colon)
+        if [[ "${line}" =~ ^[[:space:]]{2}([a-zA-Z][a-zA-Z0-9_-]*):[[:space:]]*$ ]]; then
+            # Print previous pack if we had one
+            if [[ -n "${current_pack}" ]]; then
+                printf '  %-14s %s (%d skills)\n' "${current_pack}" "${current_desc}" "${skill_count}"
+            fi
+            current_pack="${BASH_REMATCH[1]}"
+            current_desc=""
+            skill_count=0
+            continue
+        fi
+
+        # Detect description line
+        if [[ "${line}" =~ ^[[:space:]]+description:[[:space:]]*\"?([^\"]*)\"? ]]; then
+            current_desc="${BASH_REMATCH[1]}"
+            continue
+        fi
+
+        # Count skill entries
+        if [[ "${line}" =~ ^[[:space:]]*-[[:space:]]+ ]] && [[ -n "${current_pack}" ]]; then
+            skill_count=$(( skill_count + 1 ))
+        fi
+    done < "${packs_file}"
+
+    # Print the last pack
+    if [[ -n "${current_pack}" ]]; then
+        printf '  %-14s %s (%d skills)\n' "${current_pack}" "${current_desc}" "${skill_count}"
+    fi
+
+    printf '\nInstall a pack: clawspark skills pack <name>\n\n'
+}
+
+_skills_install_pack() {
+    local pack_name="$1"
+    local packs_file="${CLAWSPARK_DIR}/configs/skill-packs.yaml"
+    if [[ ! -f "${packs_file}" ]]; then
+        packs_file="$(cd "$(dirname "$0")" && pwd)/configs/skill-packs.yaml"
+    fi
+    if [[ ! -f "${packs_file}" ]]; then
+        log_error "No skill-packs.yaml found."
+        exit 1
+    fi
+
+    # Parse skills for the requested pack
+    local -a skills=()
+    local in_pack=false in_skills=false
+
+    while IFS= read -r line; do
+        [[ "${line}" =~ ^[[:space:]]*# ]] && continue
+        [[ -z "${line// }" ]] && continue
+
+        # Detect pack name line
+        if [[ "${line}" =~ ^[[:space:]]{2}([a-zA-Z][a-zA-Z0-9_-]*):[[:space:]]*$ ]]; then
+            if [[ "${BASH_REMATCH[1]}" == "${pack_name}" ]]; then
+                in_pack=true
+            elif ${in_pack}; then
+                break
+            fi
+            in_skills=false
+            continue
+        fi
+
+        if ${in_pack}; then
+            if [[ "${line}" =~ ^[[:space:]]+skills:[[:space:]]*$ ]]; then
+                in_skills=true
+                continue
+            fi
+            # Another key under this pack (not skills list) -- stop reading skills
+            if [[ "${line}" =~ ^[[:space:]]{4}[a-zA-Z] ]] && [[ ! "${line}" =~ ^[[:space:]]*- ]]; then
+                in_skills=false
+                continue
+            fi
+            if ${in_skills} && [[ "${line}" =~ ^[[:space:]]*-[[:space:]]+(.*) ]]; then
+                local slug="${BASH_REMATCH[1]}"
+                slug="${slug## }"; slug="${slug%% }"
+                skills+=("${slug}")
+            fi
+        fi
+    done < "${packs_file}"
+
+    if [[ ${#skills[@]} -eq 0 ]]; then
+        log_error "Pack '${pack_name}' not found. Run 'clawspark skills pack' to see available packs."
+        exit 1
+    fi
+
+    printf '\n%s%sInstalling skill pack: %s%s (%d skills)\n\n' "${BOLD}" "${BLUE}" "${pack_name}" "${RESET}" "${#skills[@]}"
+
+    local installed=0 failed=0
+    for skill in "${skills[@]}"; do
+        printf '  %s->%s %s ... ' "${CYAN}" "${RESET}" "${skill}"
+        if npx --yes clawhub@latest install --force "${skill}" >> "${CLAWSPARK_LOG}" 2>&1; then
+            printf '%sdone%s\n' "${GREEN}" "${RESET}"
+            installed=$(( installed + 1 ))
+        else
+            printf '%sfailed%s\n' "${YELLOW}" "${RESET}"
+            failed=$(( failed + 1 ))
+        fi
+    done
+
+    printf '\n'
+    log_success "Pack '${pack_name}' complete: ${installed} installed, ${failed} failed."
+}
+
+# ── benchmark ───────────────────────────────────────────────────────────────
+_cmd_benchmark() {
+    printf '\n%s%s clawspark benchmark%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    if ! _uses_local_ollama; then
+        log_error "Benchmark currently supports local Ollama profiles only."
+        exit 1
+    fi
+
+    if ! curl -sf http://127.0.0.1:11434/ &>/dev/null; then
+        log_error "Ollama is not running. Start it first: clawspark restart"
+        exit 1
+    fi
+
+    # Determine model from config
+    local model_id=""
+    model_id=$(openclaw config get agents.defaults.model 2>/dev/null | tr -d '"' || echo "")
+    # Strip the "ollama/" provider prefix for Ollama API calls
+    model_id="${model_id#ollama/}"
+    if [[ -z "${model_id}" ]]; then
+        model_id=$(ollama list 2>/dev/null | tail -n +2 | head -1 | awk '{print $1}')
+    fi
+    if [[ -z "${model_id}" ]]; then
+        log_error "No model found. Pull one with: ollama pull <model>"
+        exit 1
+    fi
+
+    log_info "Benchmarking model: ${model_id}"
+
+    local prompts=(
+        "Explain quantum computing in one sentence."
+        "Write a haiku about artificial intelligence."
+        "Count from 1 to 20."
+    )
+
+    local total_tokens=0
+    local total_duration_ns=0
+
+    for prompt in "${prompts[@]}"; do
+        printf '  %s→%s "%s" ... ' "${CYAN}" "${RESET}" "${prompt}"
+        local response
+        response=$(curl -sf --max-time 60 http://127.0.0.1:11434/api/generate \
+            -d "{\"model\":\"${model_id}\",\"prompt\":\"${prompt}\",\"stream\":false,\"options\":{\"num_predict\":50}}" 2>/dev/null || echo "")
+
+        if [[ -z "${response}" ]]; then
+            printf '%sfailed%s\n' "${RED}" "${RESET}"
+            continue
+        fi
+
+        local eval_count eval_duration_ns
+        eval_count=$(echo "${response}" | grep -o '"eval_count":[0-9]*' | cut -d: -f2 || echo 0)
+        eval_duration_ns=$(echo "${response}" | grep -o '"eval_duration":[0-9]*' | cut -d: -f2 || echo 0)
+
+        if [[ -n "${eval_count}" && "${eval_count}" -gt 0 && -n "${eval_duration_ns}" && "${eval_duration_ns}" -gt 0 ]]; then
+            local tps
+            tps=$(awk "BEGIN {printf \"%.1f\", ${eval_count} / (${eval_duration_ns} / 1000000000)}")
+            printf '%s%s tok/s%s (%s tokens)\n' "${GREEN}" "${tps}" "${RESET}" "${eval_count}"
+            total_tokens=$(( total_tokens + eval_count ))
+            total_duration_ns=$(( total_duration_ns + eval_duration_ns ))
+        else
+            printf '%sdone%s\n' "${GREEN}" "${RESET}"
+        fi
+    done
+
+    printf '\n'
+    if (( total_duration_ns > 0 )); then
+        local avg_tps
+        avg_tps=$(awk "BEGIN {printf \"%.1f\", ${total_tokens} / (${total_duration_ns} / 1000000000)}")
+        print_box \
+            "${BOLD}Benchmark Results${RESET}" \
+            "" \
+            "Model       : ${model_id}" \
+            "Total tokens: ${total_tokens}" \
+            "Average     : ${CYAN}${avg_tps} tok/s${RESET}"
+    else
+        log_warn "Could not compute benchmark results."
+    fi
+    printf '\n'
+}
+
+# ── update ──────────────────────────────────────────────────────────────────
+_cmd_update() {
+    log_info "Updating OpenClaw..."
+    sudo npm install -g openclaw@latest 2>&1 | tee -a "${CLAWSPARK_LOG}"
+    log_success "OpenClaw updated to $(openclaw --version 2>/dev/null || echo 'latest')."
+
+    # Re-apply patches and dual-agent config (npm update overwrites dist files)
+    log_info "Re-applying patches and config..."
+    local lib_dir="${CLAWSPARK_DIR}/lib"
+    if [[ -f "${lib_dir}/setup-openclaw.sh" ]]; then
+        source "${lib_dir}/setup-openclaw.sh"
+        _patch_sync_full_history
+        _patch_baileys_browser
+        _patch_mention_detection
+        _setup_agent_config
+    else
+        log_warn "lib/setup-openclaw.sh not found -- patches not re-applied."
+        log_warn "Re-run install.sh to apply patches."
+    fi
+
+    # Restart gateway with correct env
+    log_info "Restarting gateway..."
+    _cmd_restart
+
+    log_info "Syncing skills..."
+    _skills_sync
+}
+
+# ── airgap ──────────────────────────────────────────────────────────────────
+_cmd_airgap() {
+    local mode="${1:-}"
+    local toggle_script="${CLAWSPARK_DIR}/airgap-toggle.sh"
+
+    case "${mode}" in
+        on|off)
+            if [[ -x "${toggle_script}" ]]; then
+                bash "${toggle_script}" "${mode}"
+            else
+                if ! check_command ufw; then
+                    log_error "UFW is not installed. Cannot toggle air-gap."
+                    exit 1
+                fi
+                if [[ "${mode}" == "on" ]]; then
+                    sudo ufw default deny outgoing
+                    sudo ufw allow out to 10.0.0.0/8
+                    sudo ufw allow out to 172.16.0.0/12
+                    sudo ufw allow out to 192.168.0.0/16
+                    sudo ufw allow out to 127.0.0.0/8
+                    sudo ufw allow out 53
+                    echo "true" > "${CLAWSPARK_DIR}/airgap.state"
+                    log_success "Air-gap mode ENABLED."
+                else
+                    sudo ufw default allow outgoing
+                    echo "false" > "${CLAWSPARK_DIR}/airgap.state"
+                    log_success "Air-gap mode DISABLED."
+                fi
+            fi
+            ;;
+        *)
+            local current="off"
+            [[ -f "${CLAWSPARK_DIR}/airgap.state" && "$(cat "${CLAWSPARK_DIR}/airgap.state")" == "true" ]] && current="ON"
+            printf '  Air-gap mode is currently: %s%s%s\n' "${BOLD}" "${current}" "${RESET}"
+            printf '  Usage: clawspark airgap [on|off]\n'
+            ;;
+    esac
+}
+
+# ── dashboard ──────────────────────────────────────────────────────────
+_cmd_dashboard() {
+    printf '\n%s%s clawspark dashboard%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    # Check if ClawMetry is running
+    local clawmetry_running=false
+    local clawmetry_pid_file="${CLAWSPARK_DIR}/dashboard.pid"
+
+    if [[ -f "${clawmetry_pid_file}" ]]; then
+        local cm_pid
+        cm_pid=$(cat "${clawmetry_pid_file}")
+        if kill -0 "${cm_pid}" 2>/dev/null; then
+            clawmetry_running=true
+        fi
+    fi
+
+    # Fallback: check via HTTP
+    if ! ${clawmetry_running}; then
+        if curl -sf http://127.0.0.1:8900/ &>/dev/null; then
+            clawmetry_running=true
+        fi
+    fi
+
+    # Start ClawMetry if not running
+    if ! ${clawmetry_running}; then
+        log_info "ClawMetry is not running. Starting it..."
+        if [[ -x "${CLAWSPARK_DIR}/clawmetry/start.sh" ]]; then
+            bash "${CLAWSPARK_DIR}/clawmetry/start.sh" >> "${CLAWSPARK_LOG}" 2>&1
+            log_success "ClawMetry started."
+        elif python3 -m clawmetry --help &>/dev/null; then
+            nohup python3 -m clawmetry --port 8900 --host 127.0.0.1 >> "${CLAWSPARK_DIR}/dashboard.log" 2>&1 &
+            echo $! > "${clawmetry_pid_file}"
+            log_success "ClawMetry started (PID $!)."
+        elif check_command clawmetry; then
+            nohup clawmetry serve >> "${CLAWSPARK_DIR}/dashboard.log" 2>&1 &
+            echo $! > "${clawmetry_pid_file}"
+            log_success "ClawMetry started (PID $!)."
+        else
+            log_warn "ClawMetry is not installed. Metrics dashboard unavailable."
+        fi
+    fi
+
+    printf '  %s%sChat UI:%s  http://localhost:18789/__openclaw__/canvas/\n' "${BOLD}" "${GREEN}" "${RESET}"
+    printf '  %s%sMetrics:%s  http://localhost:8900\n' "${BOLD}" "${GREEN}" "${RESET}"
+
+    # Show Tailscale URLs if connected
+    if check_command tailscale; then
+        local ts_ip
+        ts_ip=$(tailscale ip -4 2>/dev/null || true)
+        if [[ -n "${ts_ip}" ]]; then
+            printf '\n  %s%sTailscale (remote access):%s\n' "${BOLD}" "${CYAN}" "${RESET}"
+            printf '  Chat UI:  http://%s:18789\n' "${ts_ip}"
+            printf '  Metrics:  http://%s:8900\n' "${ts_ip}"
+        fi
+    fi
+
+    printf '\n'
+}
+
+# ── tailscale ──────────────────────────────────────────────────────────
+_cmd_tailscale() {
+    local subcmd="${1:-}"
+    shift || true
+
+    case "${subcmd}" in
+        setup)
+            _tailscale_setup
+            ;;
+        status)
+            _tailscale_status
+            ;;
+        *)
+            printf '  Usage: clawspark tailscale [setup|status]\n'
+            exit 1
+            ;;
+    esac
+}
+
+_tailscale_setup() {
+    printf '\n%s%s clawspark tailscale setup%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    # Check if Tailscale is installed
+    if ! check_command tailscale; then
+        log_info "Tailscale is not installed. Installing..."
+        if [[ "$(uname)" == "Linux" ]]; then
+            curl -fsSL https://tailscale.com/install.sh | sh 2>&1 | tee -a "${CLAWSPARK_LOG}"
+        elif [[ "$(uname)" == "Darwin" ]]; then
+            if check_command brew; then
+                brew install --cask tailscale 2>&1 | tee -a "${CLAWSPARK_LOG}"
+            else
+                log_error "Please install Tailscale manually: https://tailscale.com/download"
+                exit 1
+            fi
+        else
+            log_error "Unsupported platform. Please install Tailscale manually: https://tailscale.com/download"
+            exit 1
+        fi
+    fi
+
+    if ! check_command tailscale; then
+        log_error "Tailscale installation failed. Please install manually: https://tailscale.com/download"
+        exit 1
+    fi
+
+    log_info "Starting Tailscale..."
+    sudo tailscale up 2>&1
+
+    # Configure Tailscale to expose the gateway ports
+    local ts_ip
+    ts_ip=$(tailscale ip -4 2>/dev/null || true)
+    if [[ -n "${ts_ip}" ]]; then
+        log_success "Tailscale is connected."
+        printf '\n  Tailscale IP: %s%s%s\n' "${CYAN}" "${ts_ip}" "${RESET}"
+        printf '  Chat UI:     http://%s:18789\n' "${ts_ip}"
+        printf '  Metrics:     http://%s:8900\n' "${ts_ip}"
+        printf '\n'
+        log_info "Make sure your Tailscale ACLs allow access to ports 18789 and 8900."
+    else
+        log_warn "Tailscale is running but no IPv4 address was found. Check 'tailscale status'."
+    fi
+}
+
+_tailscale_status() {
+    printf '\n%s%s clawspark tailscale status%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    if ! check_command tailscale; then
+        printf '  %s✗%s Tailscale is not installed.\n' "${RED}" "${RESET}"
+        printf '  Run: clawspark tailscale setup\n\n'
+        return
+    fi
+
+    local ts_status
+    ts_status=$(tailscale status --json 2>/dev/null || true)
+
+    if [[ -z "${ts_status}" ]]; then
+        printf '  %s✗%s Tailscale is not running.\n' "${RED}" "${RESET}"
+        printf '  Run: clawspark tailscale setup\n\n'
+        return
+    fi
+
+    local ts_ip
+    ts_ip=$(tailscale ip -4 2>/dev/null || true)
+
+    if [[ -n "${ts_ip}" ]]; then
+        printf '  %s✓%s Tailscale          connected\n' "${GREEN}" "${RESET}"
+        printf '  %s-%s Tailscale IP       %s\n' "${CYAN}" "${RESET}" "${ts_ip}"
+        printf '  %s-%s Chat UI            http://%s:18789\n' "${CYAN}" "${RESET}" "${ts_ip}"
+        printf '  %s-%s Metrics            http://%s:8900\n' "${CYAN}" "${RESET}" "${ts_ip}"
+    else
+        printf '  %s✗%s Tailscale          not connected\n' "${YELLOW}" "${RESET}"
+        printf '  Run: clawspark tailscale setup\n'
+    fi
+
+    printf '\n'
+}
+
+# ── logs ────────────────────────────────────────────────────────────────────
+_cmd_logs() {
+    local gateway_log="${CLAWSPARK_DIR}/gateway.log"
+    if [[ -f "${gateway_log}" ]]; then
+        tail -f "${gateway_log}"
+    else
+        log_warn "Gateway log not found at ${gateway_log}"
+        log_info "Try: clawspark restart"
+    fi
+}
+
+# ── restart ─────────────────────────────────────────────────────────────────
+_cmd_restart() {
+    log_info "Restarting services..."
+    _source_gateway_env
+    local use_systemd
+    use_systemd=$(_detect_systemd)
+
+    # Restart Ollama when using local inference
+    if _uses_local_ollama; then
+        if check_command systemctl && systemctl is-enabled ollama &>/dev/null; then
+            if sudo -n systemctl restart ollama 2>/dev/null; then
+                log_success "Ollama restarted via systemctl."
+            elif curl -sf http://127.0.0.1:11434/ &>/dev/null; then
+                log_info "Ollama already running (systemd-managed, no sudo available)."
+            else
+                log_warn "Ollama needs sudo to restart. Run: sudo systemctl restart ollama"
+            fi
+        elif [[ -f "${CLAWSPARK_DIR}/ollama.pid" ]]; then
+            _kill_pid_file "${CLAWSPARK_DIR}/ollama.pid"
+            sleep 1
+            nohup ollama serve >> "${CLAWSPARK_DIR}/ollama.log" 2>&1 &
+            echo $! > "${CLAWSPARK_DIR}/ollama.pid"
+            log_success "Ollama restarted (PID $!)."
+        else
+            nohup ollama serve >> "${CLAWSPARK_DIR}/ollama.log" 2>&1 &
+            echo $! > "${CLAWSPARK_DIR}/ollama.pid"
+            log_success "Ollama started (PID $!)."
+        fi
+
+        if ! _wait_for_ollama; then
+            log_error "Aborting: Ollama backend is not ready."
+            return 1
+        fi
+    else
+        log_info "Remote/API provider detected; skipping Ollama restart."
+    fi
+
+    if [[ "${use_systemd}" == "true" ]]; then
+        sudo -n systemctl restart clawspark-gateway.service 2>/dev/null || {
+            log_warn "Gateway needs sudo to restart. Run: sudo systemctl restart clawspark-gateway"
+        }
+        sleep 3
+        sudo -n systemctl restart clawspark-nodehost.service 2>/dev/null || {
+            log_warn "Node host needs sudo to restart. Run: sudo systemctl restart clawspark-nodehost"
+        }
+        if systemctl is-enabled --quiet clawspark-dashboard.service 2>/dev/null; then
+            sudo -n systemctl restart clawspark-dashboard.service 2>/dev/null || true
+        fi
+        sleep 2
+        # Verify
+        systemctl is-active --quiet clawspark-gateway.service 2>/dev/null && log_success "Gateway restarted (systemd)." || log_warn "Gateway may not have restarted."
+        systemctl is-active --quiet clawspark-nodehost.service 2>/dev/null && log_success "Node host restarted (systemd)." || log_warn "Node host may not have restarted."
+    else
+        # PID-based management
+        _kill_pid_file "${CLAWSPARK_DIR}/gateway.pid"
+        _kill_pid_file "${CLAWSPARK_DIR}/node.pid"
+        _kill_pid_file "${CLAWSPARK_DIR}/dashboard.pid"
+        _kill_by_name "openclaw gateway"
+        _kill_by_name "openclaw node"
+        sleep 2
+
+        if check_command openclaw; then
+            nohup openclaw gateway run --bind loopback > "${CLAWSPARK_DIR}/gateway.log" 2>&1 &
+            echo $! > "${CLAWSPARK_DIR}/gateway.pid"
+            log_success "Gateway started (PID $!)."
+        else
+            log_warn "openclaw not found, gateway not started."
+            return 1
+        fi
+
+        sleep 3
+
+        nohup openclaw node run --host 127.0.0.1 --port 18789 > "${CLAWSPARK_DIR}/node.log" 2>&1 &
+        echo $! > "${CLAWSPARK_DIR}/node.pid"
+        log_success "Node host started (PID $!)."
+
+        _start_dashboard
+    fi
+
+    sleep 2
+    log_success "All services restarted."
+}
+
+# ── start ──────────────────────────────────────────────────────────────────
+_cmd_start() {
+    log_info "Starting services..."
+    _source_gateway_env
+    local use_systemd
+    use_systemd=$(_detect_systemd)
+
+    # Start Ollama when required
+    if _uses_local_ollama; then
+        if curl -sf http://127.0.0.1:11434/ &>/dev/null; then
+            log_info "Ollama already running."
+        elif check_command systemctl && systemctl is-enabled ollama &>/dev/null; then
+            sudo -n systemctl start ollama 2>/dev/null || log_warn "Ollama needs sudo to start. Run: sudo systemctl start ollama"
+        else
+            nohup ollama serve >> "${CLAWSPARK_DIR}/ollama.log" 2>&1 &
+            echo $! > "${CLAWSPARK_DIR}/ollama.pid"
+            log_success "Ollama started (PID $!)."
+        fi
+
+        if ! _wait_for_ollama; then
+            log_error "Aborting: Ollama backend is not ready."
+            return 1
+        fi
+    else
+        log_info "Remote/API provider detected; skipping Ollama startup."
+    fi
+
+    if [[ "${use_systemd}" == "true" ]]; then
+        if systemctl is-active --quiet clawspark-gateway.service 2>/dev/null; then
+            log_info "Gateway already running (systemd)."
+        else
+            sudo -n systemctl start clawspark-gateway.service 2>/dev/null || log_warn "Gateway needs sudo. Run: sudo systemctl start clawspark-gateway"
+        fi
+        sleep 2
+        if systemctl is-active --quiet clawspark-nodehost.service 2>/dev/null; then
+            log_info "Node host already running (systemd)."
+        else
+            sudo -n systemctl start clawspark-nodehost.service 2>/dev/null || log_warn "Node host needs sudo. Run: sudo systemctl start clawspark-nodehost"
+        fi
+        if systemctl is-enabled --quiet clawspark-dashboard.service 2>/dev/null; then
+            if ! systemctl is-active --quiet clawspark-dashboard.service 2>/dev/null; then
+                sudo -n systemctl start clawspark-dashboard.service 2>/dev/null || true
+            fi
+        fi
+    else
+        # PID-based management
+        if [[ -f "${CLAWSPARK_DIR}/gateway.pid" ]] && kill -0 "$(cat "${CLAWSPARK_DIR}/gateway.pid" 2>/dev/null)" 2>/dev/null; then
+            log_info "Gateway already running."
+        elif check_command openclaw; then
+            nohup openclaw gateway run --bind loopback > "${CLAWSPARK_DIR}/gateway.log" 2>&1 &
+            echo $! > "${CLAWSPARK_DIR}/gateway.pid"
+            log_success "Gateway started (PID $!)."
+            sleep 3
+        else
+            log_warn "openclaw not found, gateway not started."
+            return 1
+        fi
+
+        if [[ -f "${CLAWSPARK_DIR}/node.pid" ]] && kill -0 "$(cat "${CLAWSPARK_DIR}/node.pid" 2>/dev/null)" 2>/dev/null; then
+            log_info "Node host already running."
+        elif check_command openclaw; then
+            nohup openclaw node run --host 127.0.0.1 --port 18789 > "${CLAWSPARK_DIR}/node.log" 2>&1 &
+            echo $! > "${CLAWSPARK_DIR}/node.pid"
+            log_success "Node host started (PID $!)."
+        fi
+
+        if [[ -f "${CLAWSPARK_DIR}/dashboard.pid" ]] && kill -0 "$(cat "${CLAWSPARK_DIR}/dashboard.pid" 2>/dev/null)" 2>/dev/null; then
+            log_info "Dashboard already running."
+        else
+            _start_dashboard
+        fi
+    fi
+}
+
+# ── stop ───────────────────────────────────────────────────────────────────
+_cmd_stop() {
+    local stop_all=false
+    for arg in "$@"; do
+        [[ "${arg}" == "--all" ]] && stop_all=true
+    done
+
+    log_info "Stopping services..."
+
+    # Detect systemd management
+    local use_systemd=false
+    if check_command systemctl && systemctl is-enabled --quiet clawspark-gateway.service 2>/dev/null; then
+        use_systemd=true
+    fi
+
+    if [[ "${use_systemd}" == "true" ]]; then
+        # Stop via systemd
+        if systemctl is-enabled --quiet clawspark-dashboard.service 2>/dev/null; then
+            sudo -n systemctl stop clawspark-dashboard.service 2>/dev/null || true
+            log_success "Dashboard stopped (systemd)."
+        fi
+        sudo -n systemctl stop clawspark-nodehost.service 2>/dev/null || true
+        log_success "Node host stopped (systemd)."
+        sudo -n systemctl stop clawspark-gateway.service 2>/dev/null || true
+        log_success "Gateway stopped (systemd)."
+    else
+        # PID-based stop
+        _kill_pid_file "${CLAWSPARK_DIR}/dashboard.pid"
+        _kill_by_name "clawmetry"
+        log_success "Dashboard stopped."
+
+        _kill_pid_file "${CLAWSPARK_DIR}/node.pid"
+        _kill_by_name "openclaw node"
+        log_success "Node host stopped."
+
+        _kill_pid_file "${CLAWSPARK_DIR}/gateway.pid"
+        _kill_by_name "openclaw gateway"
+        log_success "Gateway stopped."
+    fi
+
+    # Stop Ollama only with --all flag
+    if ${stop_all} && _uses_local_ollama; then
+        if check_command systemctl && systemctl is-enabled ollama &>/dev/null; then
+            sudo -n systemctl stop ollama 2>/dev/null || log_warn "Ollama needs sudo to stop. Run: sudo systemctl stop ollama"
+        else
+            _kill_pid_file "${CLAWSPARK_DIR}/ollama.pid"
+            log_success "Ollama stopped."
+        fi
+    else
+        log_info "Ollama left unchanged. Use --all on local profiles to also stop Ollama."
+    fi
+}
+
+# ── _start_dashboard (helper) ─────────────────────────────────────────────
+_start_dashboard() {
+    # Method 1: clawmetry CLI in PATH
+    if check_command clawmetry; then
+        nohup clawmetry --port 8900 --host 127.0.0.1 >> "${CLAWSPARK_DIR}/dashboard.log" 2>&1 &
+        echo $! > "${CLAWSPARK_DIR}/dashboard.pid"
+        log_success "Dashboard started via clawmetry (PID $!)."
+        return
+    fi
+
+    # Method 2: clawmetry in ~/.local/bin
+    if [[ -x "${HOME}/.local/bin/clawmetry" ]]; then
+        nohup "${HOME}/.local/bin/clawmetry" --port 8900 --host 127.0.0.1 >> "${CLAWSPARK_DIR}/dashboard.log" 2>&1 &
+        echo $! > "${CLAWSPARK_DIR}/dashboard.pid"
+        log_success "Dashboard started via ~/.local/bin/clawmetry (PID $!)."
+        return
+    fi
+
+    # Method 3: waitress + clawmetry Python module
+    if python3 -c "from clawmetry import create_app; from waitress import serve" 2>/dev/null; then
+        nohup python3 -c "from clawmetry import create_app; from waitress import serve; serve(create_app(), host='127.0.0.1', port=8900)" >> "${CLAWSPARK_DIR}/dashboard.log" 2>&1 &
+        echo $! > "${CLAWSPARK_DIR}/dashboard.pid"
+        log_success "Dashboard started via waitress (PID $!)."
+        return
+    fi
+
+    # Method 4: Flask dev server
+    if python3 -c "from clawmetry import create_app" 2>/dev/null; then
+        nohup python3 -c "from clawmetry import create_app; app = create_app(); app.run(host='127.0.0.1', port=8900)" >> "${CLAWSPARK_DIR}/dashboard.log" 2>&1 &
+        echo $! > "${CLAWSPARK_DIR}/dashboard.pid"
+        log_success "Dashboard started via Flask dev server (PID $!)."
+        return
+    fi
+
+    log_warn "ClawMetry is not installed. Dashboard not started."
+}
+
+# ── model ──────────────────────────────────────────────────────────────────
+_cmd_model() {
+    local subcmd="${1:-list}"
+    shift || true
+
+    case "${subcmd}" in
+        list)
+            _model_list
+            ;;
+        switch)
+            local name="${1:-}"
+            [[ -z "${name}" ]] && { log_error "Usage: clawspark model switch <model>"; exit 1; }
+            _model_switch "${name}"
+            ;;
+        vision)
+            local name="${1:-}"
+            if [[ -z "${name}" ]]; then
+                _model_vision_show
+            else
+                _model_vision_set "${name}"
+            fi
+            ;;
+        *)
+            log_error "Unknown model subcommand: ${subcmd}"
+            printf '  Usage: clawspark model [list|switch <model>|vision [model]]\n'
+            exit 1
+            ;;
+    esac
+}
+
+_model_list() {
+    printf '\n%s%s clawspark models%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    local config_file="${HOME}/.openclaw/openclaw.json"
+    local primary_model="" vision_model="" imagegen_model=""
+
+    if [[ -f "${config_file}" ]]; then
+        local models_output
+        models_output=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    d = json.load(f).get('agents', {}).get('defaults', {})
+print(d.get('model', ''))
+print(d.get('imageModel', ''))
+print(d.get('imageGenerationModel', ''))
+" "${config_file}" 2>/dev/null || echo "")
+        if [[ -n "${models_output}" ]]; then
+            primary_model=$(echo "${models_output}" | sed -n '1p')
+            vision_model=$(echo "${models_output}" | sed -n '2p')
+            imagegen_model=$(echo "${models_output}" | sed -n '3p')
+        fi
+    fi
+
+    printf '  %s%sActive Models:%s\n\n' "${BOLD}" "${GREEN}" "${RESET}"
+    if [[ -n "${primary_model}" ]]; then
+        printf '    %s✓%s Primary (chat)     : %s%s%s\n' "${GREEN}" "${RESET}" "${CYAN}" "${primary_model}" "${RESET}"
+    else
+        printf '    %s-%s Primary (chat)     : %snot set%s\n' "${YELLOW}" "${RESET}" "${YELLOW}" "${RESET}"
+    fi
+    if [[ -n "${vision_model}" ]]; then
+        printf '    %s✓%s Vision (images)    : %s%s%s\n' "${GREEN}" "${RESET}" "${CYAN}" "${vision_model}" "${RESET}"
+    else
+        printf '    %s-%s Vision (images)    : %snot configured%s\n' "${YELLOW}" "${RESET}" "${YELLOW}" "${RESET}"
+    fi
+    if [[ -n "${imagegen_model}" ]]; then
+        printf '    %s✓%s Image generation   : %s%s%s\n' "${GREEN}" "${RESET}" "${CYAN}" "${imagegen_model}" "${RESET}"
+    else
+        printf '    %s-%s Image generation   : %snot configured%s\n' "${YELLOW}" "${RESET}" "${YELLOW}" "${RESET}"
+    fi
+
+    if _uses_local_ollama; then
+        printf '\n  %s%sOllama Models (pulled):%s\n\n' "${BOLD}" "${GREEN}" "${RESET}"
+        if check_command ollama; then
+            local model_output
+            model_output=$(ollama list 2>/dev/null || echo "")
+            if [[ -n "${model_output}" ]]; then
+                echo "${model_output}" | tail -n +2 | while IFS= read -r line; do
+                    local mname
+                    mname=$(echo "${line}" | awk '{print $1}')
+                    local msize
+                    msize=$(echo "${line}" | awk '{print $3, $4}')
+                    local marker=""
+                    if [[ "ollama/${mname}" == "${primary_model}" ]]; then
+                        marker=" ${GREEN}(primary)${RESET}"
+                    elif [[ "ollama/${mname}" == "${vision_model}" ]]; then
+                        marker=" ${CYAN}(vision)${RESET}"
+                    fi
+                    printf '    %-35s %s%s\n' "${mname}" "${msize}" "${marker}"
+                done
+            else
+                printf '    %s(no models pulled)%s\n' "${YELLOW}" "${RESET}"
+            fi
+        else
+            printf '    %s(ollama not found)%s\n' "${RED}" "${RESET}"
+        fi
+
+        printf '\n  Switch model:  clawspark model switch <model>\n'
+        printf '  Set vision:    clawspark model vision <model>\n'
+        printf '  Pull a model:  ollama pull <model>\n\n'
+    else
+        local provider_display endpoint
+        provider_display="$(_current_provider_display)"
+        endpoint="$(_current_provider_base_url)"
+
+        printf '\n  %s%sRemote/API Provider:%s\n\n' "${BOLD}" "${GREEN}" "${RESET}"
+        printf '    %-35s %s\n' "Provider" "${provider_display}"
+        if [[ -n "${endpoint}" ]]; then
+            printf '    %-35s %s\n' "Base URL" "${endpoint}"
+        else
+            printf '    %-35s %s\n' "Base URL" "(not exported in current environment)"
+        fi
+        printf '    %-35s %s\n' "Model switching" "No local pull required"
+
+        printf '\n  Switch model:  clawspark model switch <model>\n'
+        printf '  Set vision:    clawspark model vision <model>\n'
+        printf '  Example:       clawspark model switch openai/gpt-4.1-mini\n\n'
+    fi
+}
+
+_model_switch() {
+    local model="$1"
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    if [[ ! -f "${config_file}" ]]; then
+        log_error "Config not found at ${config_file}. Run install.sh first."
+        exit 1
+    fi
+
+    local model_id
+    model_id=$(_normalize_model_ref "${model}")
+
+    # Check if the model is pulled in Ollama
+    if [[ "${model_id}" == ollama/* ]] && check_command ollama; then
+        if ! ollama list 2>/dev/null | grep -qi "^${model}"; then
+            log_warn "Model '${model}' does not appear in ollama list."
+            log_warn "Pull it first: ollama pull ${model}"
+            log_warn "Setting config anyway in case the model name is correct."
+        fi
+    fi
+
+    # Update the config
+    python3 -c "
+import json, sys
+
+path = sys.argv[1]
+model = sys.argv[2]
+
+with open(path, 'r') as f:
+    cfg = json.load(f)
+
+cfg.setdefault('agents', {}).setdefault('defaults', {})
+cfg['agents']['defaults']['model'] = model
+
+with open(path, 'w') as f:
+    json.dump(cfg, f, indent=2)
+print('ok')
+" "${config_file}" "${model_id}" 2>> "${CLAWSPARK_LOG}" || {
+        log_error "Failed to update config."
+        exit 1
+    }
+
+    log_success "Primary model set to: ${model_id}"
+    log_info "Restarting gateway to apply..."
+    _cmd_restart
+}
+
+_model_vision_show() {
+    local config_file="${HOME}/.openclaw/openclaw.json"
+    local vision_model=""
+
+    if [[ -f "${config_file}" ]]; then
+        vision_model=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    cfg = json.load(f)
+print(cfg.get('agents', {}).get('defaults', {}).get('imageModel', ''))
+" "${config_file}" 2>/dev/null || echo "")
+    fi
+
+    if [[ -n "${vision_model}" ]]; then
+        printf '  Vision model: %s%s%s\n' "${CYAN}" "${vision_model}" "${RESET}"
+    else
+        printf '  Vision model: %snot configured%s\n' "${YELLOW}" "${RESET}"
+        printf '  Set one with: clawspark model vision <model>\n'
+        printf '  Example: clawspark model vision qwen2.5-vl:7b\n'
+    fi
+}
+
+_model_vision_set() {
+    local model="$1"
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    if [[ ! -f "${config_file}" ]]; then
+        log_error "Config not found at ${config_file}. Run install.sh first."
+        exit 1
+    fi
+
+    local model_id
+    model_id=$(_normalize_model_ref "${model}")
+
+    # Check if the model is pulled
+    if [[ "${model_id}" == ollama/* ]] && check_command ollama; then
+        if ! ollama list 2>/dev/null | grep -qi "^${model}"; then
+            log_warn "Model '${model}' does not appear in ollama list."
+            log_warn "Pull it first: ollama pull ${model}"
+            log_warn "Setting config anyway in case the model name is correct."
+        fi
+    fi
+
+    python3 -c "
+import json, sys
+
+path = sys.argv[1]
+model = sys.argv[2]
+
+with open(path, 'r') as f:
+    cfg = json.load(f)
+
+cfg.setdefault('agents', {}).setdefault('defaults', {})
+cfg['agents']['defaults']['imageModel'] = model
+
+# Register inline model with vision capability and openai-completions api
+# so OpenClaw's image analysis path can find the right streaming provider.
+if model.startswith('ollama/'):
+    raw_id = model.replace('ollama/', '', 1)
+    prov = cfg.setdefault('models', {}).setdefault('providers', {}).setdefault('ollama', {})
+    prov.setdefault('baseUrl', 'http://127.0.0.1:11434/v1')
+    prov['api'] = 'openai-completions'
+    prov['models'] = [
+        {
+            'id': raw_id,
+            'name': raw_id.replace(':', ' ').title(),
+            'api': 'openai-completions',
+            'input': ['text', 'image'],
+            'contextWindow': 32768,
+            'maxTokens': 8192
+        }
+    ]
+
+with open(path, 'w') as f:
+    json.dump(cfg, f, indent=2)
+print('ok')
+" "${config_file}" "${model_id}" 2>> "${CLAWSPARK_LOG}" || {
+        log_error "Failed to update config."
+        exit 1
+    }
+
+    log_success "Vision model set to: ${model_id}"
+    log_info "Restart to apply: clawspark restart"
+}
+
+# ── mcp ─────────────────────────────────────────────────────────────────────
+_cmd_mcp() {
+    local subcmd="${1:-list}"
+    shift || true
+
+    local mcporter_config="${HOME}/.mcporter/mcporter.json"
+
+    case "${subcmd}" in
+        list|ls)
+            if ! check_command mcporter; then
+                log_error "mcporter not installed. Run: npm install -g mcporter"
+                return 1
+            fi
+            printf '\n  %s%sMCP Servers:%s\n\n' "${BOLD}" "${CYAN}" "${RESET}"
+            if [[ -f "${mcporter_config}" ]]; then
+                python3 -c "
+import json
+with open('${mcporter_config}') as f:
+    cfg = json.load(f)
+servers = cfg.get('mcpServers', {})
+if not servers:
+    print('  No MCP servers configured.')
+else:
+    for name, conf in servers.items():
+        cmd = conf.get('command', conf.get('baseUrl', '?'))
+        args = ' '.join(conf.get('args', []))
+        print(f'  \033[32m*\033[0m {name:20s} {cmd} {args}')
+" 2>/dev/null || log_warn "Could not read mcporter config."
+            else
+                log_info "No mcporter config found. Run: clawspark mcp setup"
+            fi
+            printf '\n'
+            ;;
+        setup)
+            if [[ -f "${CLAWSPARK_DIR}/lib/setup-mcp.sh" ]]; then
+                source "${CLAWSPARK_DIR}/lib/setup-mcp.sh"
+                setup_mcp
+            else
+                log_error "setup-mcp.sh not found. Reinstall clawspark."
+            fi
+            ;;
+        add)
+            local server_name="${1:-}"
+            local server_cmd="${2:-}"
+            [[ -z "${server_name}" ]] && { log_error "Usage: clawspark mcp add <name> <command> [args...]"; return 1; }
+            [[ -z "${server_cmd}" ]] && { log_error "Usage: clawspark mcp add <name> <command> [args...]"; return 1; }
+            shift 2 || true
+            local server_args=("$@")
+
+            mkdir -p "$(dirname "${mcporter_config}")"
+            python3 -c "
+import json, sys, os
+config_path = sys.argv[1]
+name = sys.argv[2]
+cmd = sys.argv[3]
+args = sys.argv[4:]
+
+cfg = {}
+if os.path.exists(config_path):
+    with open(config_path) as f:
+        cfg = json.load(f)
+
+cfg.setdefault('mcpServers', {})[name] = {
+    'command': cmd,
+    'args': args,
+    'env': {}
+}
+
+with open(config_path, 'w') as f:
+    json.dump(cfg, f, indent=2)
+print('ok')
+" "${mcporter_config}" "${server_name}" "${server_cmd}" "${server_args[@]}" 2>> "${CLAWSPARK_LOG}" || {
+                log_error "Failed to add MCP server."
+                return 1
+            }
+            log_success "Added MCP server: ${server_name}"
+            ;;
+        remove|rm)
+            local server_name="${1:-}"
+            [[ -z "${server_name}" ]] && { log_error "Usage: clawspark mcp remove <name>"; return 1; }
+            python3 -c "
+import json, sys, os
+config_path = sys.argv[1]
+name = sys.argv[2]
+if not os.path.exists(config_path):
+    print('no config')
+    sys.exit(0)
+with open(config_path) as f:
+    cfg = json.load(f)
+servers = cfg.get('mcpServers', {})
+if name in servers:
+    del servers[name]
+    with open(config_path, 'w') as f:
+        json.dump(cfg, f, indent=2)
+    print('removed')
+else:
+    print('not found')
+" "${mcporter_config}" "${server_name}" 2>> "${CLAWSPARK_LOG}"
+            log_success "Removed MCP server: ${server_name}"
+            ;;
+        *)
+            printf 'Usage: clawspark mcp <command>\n\n'
+            printf 'Commands:\n'
+            printf '  list          List configured MCP servers\n'
+            printf '  setup         Run MCP setup (install defaults)\n'
+            printf '  add <n> <cmd> Add a custom MCP server\n'
+            printf '  remove <n>    Remove an MCP server\n'
+            ;;
+    esac
+}
+
+# ── tools ───────────────────────────────────────────────────────────────────
+_cmd_tools() {
+    local subcmd="${1:-}"
+    shift || true
+
+    case "${subcmd}" in
+        enable)
+            local name="${1:-}"
+            [[ -z "${name}" ]] && { log_error "Usage: clawspark tools enable <tool>"; exit 1; }
+            _tools_enable "${name}"
+            ;;
+        disable)
+            local name="${1:-}"
+            [[ -z "${name}" ]] && { log_error "Usage: clawspark tools disable <tool>"; exit 1; }
+            _tools_disable "${name}"
+            ;;
+        *)
+            _tools_list
+            ;;
+    esac
+}
+
+_tools_list() {
+    printf '\n%s%s clawspark tools%s\n\n' "${BOLD}" "${BLUE}" "${RESET}"
+
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    # Built-in tools that work out of the box
+    local -a builtin_tools=(
+        "exec:Shell commands (bash, docker, kubectl):yes"
+        "web_fetch:HTTP requests and web search via DDG:yes"
+        "read:Read files on the host:yes"
+        "write:Write and create files:yes"
+        "edit:Edit files in place:yes"
+        "message:WhatsApp / Telegram replies:yes"
+        "canvas:Interactive web UI:yes"
+        "process:List, monitor, kill processes:yes"
+        "cron:Scheduled tasks:yes"
+        "sessions_spawn:Sub-agent sessions:yes"
+        "nodes:Remote/paired node execution:yes"
+        "memory_search:Search stored context:yes"
+        "memory_store:Save info across sessions:yes"
+        "transcribe:Audio transcription (local Whisper):yes"
+        "vision:Image analysis (model-dependent):yes"
+    )
+
+    # Optional tools that need configuration
+    local -a optional_tools=(
+        "browser:Browser automation:needs chromium/chrome installed"
+        "email:Send and read emails:needs email account config"
+        "calendar:Calendar management:needs calendar integration"
+        "contacts:Contact lookup:needs contacts provider"
+        "image_generate:Text-to-image:needs image generation API"
+        "code_interpret:Sandboxed code runner:needs sandbox/Docker"
+        "webhook:Webhook management:needs webhook endpoints"
+    )
+
+    # Check which optional tools are currently enabled (not in deny list)
+    local personal_deny=""
+    if [[ -f "${config_file}" ]]; then
+        personal_deny=$(python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    cfg = json.load(f)
+agents = cfg.get('agents', {}).get('list', [])
+for a in agents:
+    if a.get('id') == 'personal':
+        deny = a.get('tools', {}).get('deny', [])
+        print(' '.join(deny))
+        break
+" "${config_file}" 2>/dev/null || echo "")
+    fi
+
+    printf '  %s%sBuilt-in (work out of the box):%s\n\n' "${BOLD}" "${GREEN}" "${RESET}"
+    for entry in "${builtin_tools[@]}"; do
+        IFS=: read -r name desc status <<< "${entry}"
+        if [[ " ${personal_deny} " == *" ${name} "* ]]; then
+            printf '    %s✗%s %-18s %s %s(disabled)%s\n' "${RED}" "${RESET}" "${name}" "${desc}" "${RED}" "${RESET}"
+        else
+            printf '    %s✓%s %-18s %s\n' "${GREEN}" "${RESET}" "${name}" "${desc}"
+        fi
+    done
+
+    printf '\n  %s%sOptional (need extra setup):%s\n\n' "${BOLD}" "${YELLOW}" "${RESET}"
+    for entry in "${optional_tools[@]}"; do
+        IFS=: read -r name desc requirement <<< "${entry}"
+        if [[ " ${personal_deny} " == *" ${name} "* ]]; then
+            printf '    %s✗%s %-18s %s %s(disabled)%s\n' "${RED}" "${RESET}" "${name}" "${desc}" "${RED}" "${RESET}"
+        else
+            printf '    %s-%s %-18s %s -- %s%s%s\n' "${YELLOW}" "${RESET}" "${name}" "${desc}" "${CYAN}" "${requirement}" "${RESET}"
+        fi
+    done
+
+    printf '\n  Enable:  clawspark tools enable <name>\n'
+    printf '  Disable: clawspark tools disable <name>\n\n'
+}
+
+_tools_enable() {
+    local tool="$1"
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    if [[ ! -f "${config_file}" ]]; then
+        log_error "Config not found at ${config_file}. Run install.sh first."
+        exit 1
+    fi
+
+    # Setup instructions for optional tools
+    case "${tool}" in
+        browser)
+            log_info "Enabling browser tool..."
+            log_info "Requirement: Chromium or Chrome must be installed."
+            if check_command chromium-browser || check_command chromium || check_command google-chrome; then
+                log_success "Browser binary found."
+            else
+                log_warn "No browser binary found. Install with: sudo apt install chromium-browser"
+                log_warn "Enabling anyway -- install a browser before using the tool."
+            fi
+            ;;
+        web_search)
+            log_info "Enabling web_search tool..."
+            printf '  This requires a Brave Search API key.\n'
+            printf '  Get one at: https://brave.com/search/api/\n\n'
+            printf '  %sEnter your Brave API key (or press Enter to skip):%s ' "${CYAN}" "${RESET}"
+            local api_key
+            read -r api_key
+            if [[ -n "${api_key}" ]]; then
+                local env_file="${HOME}/.openclaw/gateway.env"
+                if ! grep -q 'BRAVE_API_KEY' "${env_file}" 2>/dev/null; then
+                    echo "BRAVE_API_KEY=${api_key}" >> "${env_file}"
+                else
+                    sed -i "s/BRAVE_API_KEY=.*/BRAVE_API_KEY=${api_key}/" "${env_file}"
+                fi
+                chmod 600 "${env_file}"
+                log_success "Brave API key saved to ${env_file}"
+                log_info "Restart the gateway: clawspark restart"
+            else
+                log_warn "No API key provided. web_search will not work without it."
+                log_warn "Enabling the tool config anyway."
+            fi
+            ;;
+        email)
+            log_info "Enabling email tool..."
+            printf '  Email requires IMAP/SMTP configuration in OpenClaw.\n'
+            printf '  After enabling, configure via the OpenClaw control UI:\n'
+            printf '    http://localhost:18789 -> Settings -> Integrations -> Email\n\n'
+            ;;
+        calendar)
+            log_info "Enabling calendar tool..."
+            printf '  Calendar requires Google or Outlook integration.\n'
+            printf '  After enabling, configure via the OpenClaw control UI:\n'
+            printf '    http://localhost:18789 -> Settings -> Integrations -> Calendar\n\n'
+            ;;
+        contacts)
+            log_info "Enabling contacts tool..."
+            printf '  After enabling, configure via the OpenClaw control UI:\n'
+            printf '    http://localhost:18789 -> Settings -> Integrations -> Contacts\n\n'
+            ;;
+        image_generate)
+            log_info "Enabling image_generate tool..."
+            printf '  Image generation requires an API (e.g. DALL-E, Stable Diffusion).\n'
+            printf '  After enabling, configure the provider in OpenClaw settings.\n\n'
+            ;;
+        code_interpret)
+            log_info "Enabling code_interpret tool..."
+            if check_command docker; then
+                log_success "Docker is available for sandboxed execution."
+            else
+                log_warn "Docker not found. code_interpret may run unsandboxed."
+            fi
+            ;;
+        webhook)
+            log_info "Enabling webhook tool..."
+            printf '  Configure webhook endpoints in OpenClaw settings after enabling.\n\n'
+            ;;
+        *)
+            # For built-in tools, just remove from deny list if present
+            log_info "Enabling ${tool}..."
+            ;;
+    esac
+
+    # Remove tool from personal agent's deny list (if present)
+    python3 -c "
+import json, sys
+
+tool_name = sys.argv[1]
+path = sys.argv[2]
+
+with open(path, 'r') as f:
+    cfg = json.load(f)
+
+agents = cfg.get('agents', {}).get('list', [])
+changed = False
+
+for agent in agents:
+    if agent.get('id') == 'personal':
+        deny = agent.get('tools', {}).get('deny', [])
+        if tool_name in deny:
+            deny.remove(tool_name)
+            if not deny:
+                agent['tools'].pop('deny', None)
+            changed = True
+        break
+
+if changed:
+    with open(path, 'w') as f:
+        json.dump(cfg, f, indent=2)
+    print('removed_from_deny')
+else:
+    print('not_in_deny')
+" "${tool}" "${config_file}" 2>> "${CLAWSPARK_LOG}" || true
+
+    log_success "Tool '${tool}' enabled for personal agent (DMs)."
+    log_info "Note: Group agent remains restricted (messaging-only). This is by design."
+    log_info "Restart to apply: clawspark restart"
+}
+
+_tools_disable() {
+    local tool="$1"
+    local config_file="${HOME}/.openclaw/openclaw.json"
+
+    if [[ ! -f "${config_file}" ]]; then
+        log_error "Config not found at ${config_file}. Run install.sh first."
+        exit 1
+    fi
+
+    # Don't allow disabling message tool
+    if [[ "${tool}" == "message" ]]; then
+        log_error "Cannot disable 'message' -- it's required for WhatsApp/Telegram."
+        exit 1
+    fi
+
+    log_info "Disabling ${tool} for personal agent..."
+
+    # Add tool to personal agent's deny list
+    python3 -c "
+import json, sys
+
+tool_name = sys.argv[1]
+path = sys.argv[2]
+
+with open(path, 'r') as f:
+    cfg = json.load(f)
+
+agents = cfg.get('agents', {}).get('list', [])
+
+for agent in agents:
+    if agent.get('id') == 'personal':
+        if 'tools' not in agent:
+            agent['tools'] = {}
+        deny = agent['tools'].get('deny', [])
+        if tool_name not in deny:
+            deny.append(tool_name)
+            agent['tools']['deny'] = deny
+        break
+
+with open(path, 'w') as f:
+    json.dump(cfg, f, indent=2)
+print('ok')
+" "${tool}" "${config_file}" 2>> "${CLAWSPARK_LOG}" || {
+        log_error "Failed to update config."
+        exit 1
+    }
+
+    log_success "Tool '${tool}' disabled for personal agent."
+    log_info "Restart to apply: clawspark restart"
+}
+
+# ── uninstall ───────────────────────────────────────────────────────────────
+_cmd_uninstall() {
+    printf '\n%s%s clawspark uninstall%s\n\n' "${BOLD}" "${RED}" "${RESET}"
+    printf '  This will remove OpenClaw, clawspark, and all configuration.\n\n'
+
+    printf '  %sAre you sure? (type YES to confirm):%s ' "${RED}" "${RESET}"
+    local confirm
+    read -r confirm
+    if [[ "${confirm}" != "YES" ]]; then
+        log_info "Uninstall cancelled."
+        exit 0
+    fi
+
+    # Check if the full uninstall.sh exists
+    local uninstall_script="${CLAWSPARK_DIR}/lib/../uninstall.sh"
+    if [[ -f "${uninstall_script}" ]]; then
+        bash "${uninstall_script}" --confirmed
+    else
+        # Inline uninstall
+        _inline_uninstall
+    fi
+}
+
+_inline_uninstall() {
+    # Stop all services
+    _kill_pid_file "${CLAWSPARK_DIR}/gateway.pid"
+    _kill_pid_file "${CLAWSPARK_DIR}/node.pid"
+    _kill_pid_file "${CLAWSPARK_DIR}/dashboard.pid"
+    _kill_pid_file "${CLAWSPARK_DIR}/ollama.pid"
+    _kill_by_name "openclaw-gateway"
+    _kill_by_name "openclaw-node"
+    _kill_by_name "clawmetry"
+    sleep 2
+
+    # Uninstall OpenClaw
+    if check_command openclaw; then
+        npm uninstall -g openclaw 2>/dev/null || true
+        log_info "OpenClaw removed."
+    fi
+
+    # Remove configs
+    rm -rf "${HOME}/.openclaw"
+    rm -rf "${CLAWSPARK_DIR}"
+    sudo -n rm -f /usr/local/bin/clawspark 2>/dev/null || rm -f "${HOME}/.local/bin/clawspark" 2>/dev/null || true
+
+    log_success "clawspark has been fully removed."
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  MAIN DISPATCH
+# ═══════════════════════════════════════════════════════════════════════════
+
+cmd="${1:-help}"
+shift || true
+
+case "${cmd}" in
+    status)     _cmd_status ;;
+    skills)     _cmd_skills "$@" ;;
+    tools)      _cmd_tools "$@" ;;
+    mcp)        _cmd_mcp "$@" ;;
+    model)      _cmd_model "$@" ;;
+    provider)   _cmd_provider "$@" ;;
+    benchmark)  _cmd_benchmark ;;
+    update)     _cmd_update ;;
+    dashboard)  _cmd_dashboard ;;
+    tailscale)  _cmd_tailscale "$@" ;;
+    airgap)     _cmd_airgap "$@" ;;
+    sandbox)    _cmd_sandbox "$@" ;;
+    logs)       _cmd_logs ;;
+    start)      _cmd_start ;;
+    stop)       _cmd_stop "$@" ;;
+    restart)    _cmd_restart ;;
+    uninstall)  _cmd_uninstall ;;
+    diagnose|doctor)
+        _load_diagnose
+        if command -v diagnose_system &>/dev/null; then
+            diagnose_system
+        else
+            log_error "Diagnose module not found. Re-install clawspark."
+            exit 1
+        fi
+        ;;
+    help|-h|--help) _usage ;;
+    version|--version|-v) echo "clawspark v${CLAWSPARK_VERSION}" ;;
+    *)
+        log_error "Unknown command: ${cmd}"
+        _usage
+        exit 1
+        ;;
+esac