cortexhawk 3.1.0

package/install.sh

@@ -0,0 +1,3805 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# --- Load .env if present (for SKILLSMP_API_KEY etc.) ---
+if [ -f ".env" ]; then
+    while IFS='=' read -r key value; do
+        [[ -z "$key" || "$key" == \#* ]] && continue
+        value="${value%\"}" && value="${value#\"}"
+        export "$key=$value" 2>/dev/null || true
+    done < .env
+fi
+
+# --- Utility functions ---
+green() { printf "\033[32m%s\033[0m\n" "$1"; }
+yellow() { printf "\033[33m%s\033[0m\n" "$1"; }
+
+get_version() {
+    grep -m1 '## \[' "$SCRIPT_DIR/CHANGELOG.md" | sed 's/.*\[\([^]]*\)\].*/\1/'
+}
+
+compute_checksum() {
+    local file="$1"
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$file" | cut -d' ' -f1
+    elif command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$file" | cut -d' ' -f1
+    else
+        echo "error: no sha256 tool found" >&2
+        return 1
+    fi
+}
+
+detect_source_type() {
+    if [ -d "$SCRIPT_DIR/.git" ]; then
+        echo "git"
+    else
+        echo "release"
+    fi
+}
+
+get_source_url() {
+    if [ -n "${CORTEXHAWK_REPO:-}" ]; then
+        echo "$CORTEXHAWK_REPO"
+        return
+    fi
+    if [ -d "$SCRIPT_DIR/.git" ]; then
+        local url
+        url=$(git -C "$SCRIPT_DIR" remote get-url origin 2>/dev/null || true)
+        if [ -n "$url" ]; then
+            echo "$url" | sed 's|git@github.com:|https://github.com/|' | sed 's|\.git$||'
+            return
+        fi
+    fi
+    echo ""
+}
+
+# --- Usage ---
+print_usage() {
+    echo "Usage: install.sh [--target claude|kimi|codex|auto|all] [--profile fullstack|api|data|autodetect] [--global]"
+    echo ""
+    echo "Targets:"
+    echo "  claude (default)  Install for Claude Code (.claude/) — fully supported"
+    echo "  kimi              Install for Kimi CLI (.kimi/) — experimental"
+    echo "  codex             Install for Codex CLI (.codex/ + .agents/) — experimental"
+    echo "  auto              Auto-detect installed CLIs and install for all found"
+    echo "  all               Install for all supported CLIs simultaneously"
+    echo ""
+    echo "Profiles:"
+    echo "  fullstack         Full-stack web development skills"
+    echo "  api               Backend API development skills"
+    echo "  data              Data engineering and data science skills"
+    echo "  autodetect        Scan project and install relevant skills"
+    echo "  (none)            Install all skills (default)"
+    echo ""
+    echo "Options:"
+    echo "  --init            Interactive setup wizard"
+    echo "  --update          Update existing installation (preserves customizations)"
+    echo "  --force           Force update even if already up to date"
+    echo "  --snapshot        Save current installation state to a snapshot file"
+    echo "  --snapshot --portable  Create portable tar.gz archive (self-contained)"
+    echo "  --snapshots       List all saved snapshots"
+    echo "  --team            Install from .cortexhawk-team.yml team config"
+    echo "  --import-config   Alias for --team (install from config YAML)"
+    echo "  --export-team [file]  Export snapshot/manifest to .cortexhawk-team.yml"
+    echo "  --export-config [file]  Alias for --export-team (export config YAML)"
+    echo "  --diff [file]     Compare current state against snapshot or manifest"
+    echo "  --diff <a> <b>    Semantic diff between two snapshots (metadata, skills, settings)"
+    echo "  --restore <file>  Restore installation from a snapshot file"
+    echo "  --restore --latest  Restore from the most recent snapshot"
+    echo "  --add-skill <url> Install a community skill from GitHub (user/repo or full URL)"
+    echo "  --search <keyword> Search skills (SkillsMP API if SKILLSMP_API_KEY set, else local REGISTRY.md)"
+    echo "  --pack <name>     Install a skill pack bundle (e.g., react-app, python-api, devops-full)"
+    echo "  --list-hooks      List all hooks with type, event, and enabled/disabled status"
+    echo "  --enable-hook <n> Enable a disabled hook in compose.yml and regenerate settings.json"
+    echo "  --disable-hook <n> Disable a hook in compose.yml and regenerate settings.json"
+    echo "  --doctor          Diagnose installation health (hooks, permissions, JSON, symlinks)"
+    echo "  --uninstall       Remove CortexHawk installation (creates snapshot first)"
+    echo "  --global, -g      Install to home directory instead of current project"
+    echo "  --quickstart      Show getting-started guide (5 things to try after install)"
+    echo "  --stats           Show installation stats (version, skills, hooks, agents, etc.)"
+    echo "  --publish-skill <path> Publish a local skill to GitHub (requires gh CLI)"
+    echo "  --check-update    Check if a newer version is available and show what changed"
+    echo "  --demo            Create a sandbox project with CortexHawk pre-installed"
+    echo "  --dry-run         Simulate install/update without writing files"
+    echo "  --test-hooks      Dry-run all hooks with synthetic inputs"
+    echo "  --no-scan         Skip post-install security audit"
+    echo "  --help, -h        Show this help"
+}
+
+# --- Argument parsing ---
+TARGET_CLI="claude"
+PROFILE=""
+PROFILE_FILE=""
+GLOBAL=false
+NO_SCAN=false
+INIT_MODE=false
+UPDATE_MODE=false
+FORCE_MODE=false
+SNAPSHOT_MODE=false
+RESTORE_MODE=false
+SNAPSHOTS_LIST=false
+TEAM_MODE=false
+DIFF_MODE=false
+EXPORT_TEAM=false
+SNAPSHOT_FILE=""
+DIFF_FILE=""
+DIFF_FILE2=""
+EXPORT_TEAM_FILE=""
+PORTABLE_MODE=false
+ADD_SKILL_URL=""
+SEARCH_KEYWORD=""
+PACK_NAME=""
+DOCTOR_MODE=false
+UNINSTALL_MODE=false
+LIST_HOOKS=false
+ENABLE_HOOK=""
+DISABLE_HOOK=""
+DRY_RUN=false
+TEST_HOOKS_MODE=false
+QUICKSTART_MODE=false
+STATS_MODE=false
+PUBLISH_SKILL_PATH=""
+CHECK_UPDATE_MODE=false
+DEMO_MODE=false
+MAX_SNAPSHOTS=10
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --target)
+            TARGET_CLI="$2"
+            shift 2
+            ;;
+        --profile)
+            PROFILE="$2"
+            shift 2
+            ;;
+        --global|-g)
+            GLOBAL=true
+            shift
+            ;;
+        --init)
+            INIT_MODE=true
+            shift
+            ;;
+        --update)
+            UPDATE_MODE=true
+            shift
+            ;;
+        --force)
+            FORCE_MODE=true
+            shift
+            ;;
+        --snapshot)
+            SNAPSHOT_MODE=true
+            shift
+            ;;
+        --portable)
+            PORTABLE_MODE=true
+            shift
+            ;;
+        --snapshots)
+            SNAPSHOTS_LIST=true
+            shift
+            ;;
+        --team)
+            TEAM_MODE=true
+            shift
+            ;;
+        --export-team|--export-config)
+            EXPORT_TEAM=true
+            if [ -n "${2:-}" ] && [[ "$2" != --* ]]; then
+                EXPORT_TEAM_FILE="$2"
+                shift 2
+            else
+                shift
+            fi
+            ;;
+        --import-config)
+            TEAM_MODE=true
+            shift
+            ;;
+        --diff)
+            DIFF_MODE=true
+            # Optional file argument(s): --diff [file1] [file2]
+            if [ -n "${2:-}" ] && [[ "$2" != --* ]]; then
+                DIFF_FILE="$2"
+                if [ -n "${3:-}" ] && [[ "$3" != --* ]]; then
+                    DIFF_FILE2="$3"
+                    shift 3
+                else
+                    shift 2
+                fi
+            else
+                shift
+            fi
+            ;;
+        --restore)
+            RESTORE_MODE=true
+            SNAPSHOT_FILE="$2"
+            if [ "$SNAPSHOT_FILE" = "--latest" ]; then
+                if [ "$GLOBAL" = true ]; then
+                    SNAP_DIR="$HOME/.claude/.cortexhawk-snapshots"
+                else
+                    SNAP_DIR="$(pwd)/.claude/.cortexhawk-snapshots"
+                fi
+                SNAPSHOT_FILE=$(ls -t "$SNAP_DIR"/*.json 2>/dev/null | head -1)
+                if [ -z "$SNAPSHOT_FILE" ]; then
+                    echo "Error: no snapshots found in $SNAP_DIR"
+                    echo "Create one with: install.sh --snapshot"
+                    exit 1
+                fi
+                echo "Using latest snapshot: $(basename "$SNAPSHOT_FILE")"
+            fi
+            shift 2
+            ;;
+        --no-scan)
+            NO_SCAN=true
+            shift
+            ;;
+        --doctor)
+            DOCTOR_MODE=true
+            shift
+            ;;
+        --uninstall)
+            UNINSTALL_MODE=true
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --test-hooks)
+            TEST_HOOKS_MODE=true
+            shift
+            ;;
+        --quickstart)
+            QUICKSTART_MODE=true
+            shift
+            ;;
+        --stats)
+            STATS_MODE=true
+            shift
+            ;;
+        --check-update)
+            CHECK_UPDATE_MODE=true
+            shift
+            ;;
+        --demo)
+            DEMO_MODE=true
+            shift
+            ;;
+        --publish-skill)
+            PUBLISH_SKILL_PATH="$2"
+            if [ -z "$PUBLISH_SKILL_PATH" ]; then
+                echo "Error: --publish-skill requires a path argument"
+                exit 1
+            fi
+            shift 2
+            ;;
+        --list-hooks)
+            LIST_HOOKS=true
+            shift
+            ;;
+        --enable-hook)
+            ENABLE_HOOK="$2"
+            if [ -z "$ENABLE_HOOK" ]; then
+                echo "Error: --enable-hook requires a hook name"
+                exit 1
+            fi
+            shift 2
+            ;;
+        --disable-hook)
+            DISABLE_HOOK="$2"
+            if [ -z "$DISABLE_HOOK" ]; then
+                echo "Error: --disable-hook requires a hook name"
+                exit 1
+            fi
+            shift 2
+            ;;
+        --add-skill)
+            ADD_SKILL_URL="$2"
+            if [ -z "$ADD_SKILL_URL" ]; then
+                echo "Error: --add-skill requires a GitHub URL or user/repo"
+                exit 1
+            fi
+            shift 2
+            ;;
+        --search)
+            SEARCH_KEYWORD="$2"
+            if [ -z "$SEARCH_KEYWORD" ]; then
+                echo "Error: --search requires a keyword"
+                exit 1
+            fi
+            shift 2
+            ;;
+        --pack)
+            PACK_NAME="$2"
+            if [ -z "$PACK_NAME" ]; then
+                echo "Error: --pack requires a pack name (e.g., --pack react-app)"
+                exit 1
+            fi
+            shift 2
+            ;;
+        --help|-h)
+            print_usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            print_usage
+            exit 1
+            ;;
+    esac
+done
+
+# --- Mutual exclusion ---
+if [ "$INIT_MODE" = true ] && [ "$UPDATE_MODE" = true ]; then
+    echo "Error: --init and --update are mutually exclusive"
+    exit 1
+fi
+if [ "$SNAPSHOT_MODE" = true ] && [ "$RESTORE_MODE" = true ]; then
+    echo "Error: --snapshot and --restore are mutually exclusive"
+    exit 1
+fi
+if [ "$SNAPSHOTS_LIST" = true ] && { [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ] || [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ]; }; then
+    echo "Error: --snapshots cannot be combined with other modes"
+    exit 1
+fi
+if [ "$TEAM_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
+    echo "Error: --team cannot be combined with --init, --update, --snapshot, or --restore"
+    exit 1
+fi
+if [ "$DIFF_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
+    echo "Error: --diff cannot be combined with --init, --update, --snapshot, or --restore"
+    exit 1
+fi
+if [ "$EXPORT_TEAM" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
+    echo "Error: --export-team cannot be combined with --init, --update, --snapshot, or --restore"
+    exit 1
+fi
+if [ "$SNAPSHOT_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ]; }; then
+    echo "Error: --snapshot cannot be combined with --init or --update"
+    exit 1
+fi
+if [ "$RESTORE_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ]; }; then
+    echo "Error: --restore cannot be combined with --init or --update"
+    exit 1
+fi
+if [ "$TARGET_CLI" = "all" ] && [ "$INIT_MODE" = true ]; then
+    echo "Error: --target all cannot be combined with --init (run --init per target instead)"
+    exit 1
+fi
+if [ "$TARGET_CLI" = "auto" ] && [ "$INIT_MODE" = true ]; then
+    echo "Error: --target auto cannot be combined with --init (run --init per target instead)"
+    exit 1
+fi
+if [ -n "$ADD_SKILL_URL" ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
+    echo "Error: --add-skill cannot be combined with --init, --update, --snapshot, or --restore"
+    exit 1
+fi
+if [ -n "$PACK_NAME" ] && [ -n "$PROFILE" ]; then
+    echo "Error: --pack cannot be combined with --profile (use one or the other)"
+    exit 1
+fi
+if [ -n "$SEARCH_KEYWORD" ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ -n "$ADD_SKILL_URL" ]; }; then
+    echo "Error: --search cannot be combined with --init, --update, or --add-skill"
+    exit 1
+fi
+if [ "$DOCTOR_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
+    echo "Error: --doctor cannot be combined with --init, --update, --snapshot, or --restore"
+    exit 1
+fi
+if [ "$UNINSTALL_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ] || [ "$DOCTOR_MODE" = true ]; }; then
+    echo "Error: --uninstall cannot be combined with other modes"
+    exit 1
+fi
+if [ "$DRY_RUN" = true ] && { [ "$DOCTOR_MODE" = true ] || [ "$UNINSTALL_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ] || [ "$DIFF_MODE" = true ] || [ "$EXPORT_TEAM" = true ] || [ "$SNAPSHOTS_LIST" = true ] || [ -n "$ADD_SKILL_URL" ] || [ "$TEAM_MODE" = true ]; }; then
+    echo "Error: --dry-run can only be combined with install or --update"
+    exit 1
+fi
+if [ "$TEST_HOOKS_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ] || [ "$DOCTOR_MODE" = true ] || [ "$UNINSTALL_MODE" = true ] || [ "$DRY_RUN" = true ]; }; then
+    echo "Error: --test-hooks cannot be combined with other modes"
+    exit 1
+fi
+
+# --- Interactive mode ---
+if [ "$INIT_MODE" = true ]; then
+    if [ ! -f "$SCRIPT_DIR/scripts/interactive-init.sh" ]; then
+        echo "Error: interactive-init.sh not found"
+        exit 1
+    fi
+    source "$SCRIPT_DIR/scripts/interactive-init.sh"
+fi
+
+# --- Pack resolution ---
+if [ -n "$PACK_NAME" ]; then
+    _packs_file="$SCRIPT_DIR/PACKS.md"
+    if [ ! -f "$_packs_file" ]; then
+        echo "Error: PACKS.md not found at $_packs_file"
+        exit 1
+    fi
+    _row=$(grep "^| ${PACK_NAME} |" "$_packs_file" || true)
+    if [ -z "$_row" ]; then
+        echo "Error: pack '$PACK_NAME' not found in PACKS.md"
+        echo ""
+        echo "Available packs:"
+        grep '^| [a-z]' "$_packs_file" | awk -F'|' '{printf "  %-16s %s\n", $2, $4}'
+        exit 1
+    fi
+    _skills_csv=$(echo "$_row" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+    _description=$(echo "$_row" | awk -F'|' '{print $4}' | sed 's/^ *//;s/ *$//')
+    _tmp_profile=$(mktemp /tmp/cortexhawk-pack-XXXXXX.json)
+    {
+        echo '{'
+        echo "  \"name\": \"pack-${PACK_NAME}\","
+        echo "  \"description\": \"${_description}\","
+        echo '  "skills": ['
+        _first=true
+        for _skill in $(echo "$_skills_csv" | tr ',' '\n' | sed 's/^ *//;s/ *$//'); do
+            [ "$_first" = true ] && _first=false || printf ',\n'
+            printf '    "%s"' "$_skill"
+        done
+        echo ''
+        echo '  ]'
+        echo '}'
+    } > "$_tmp_profile"
+    PROFILE="pack-${PACK_NAME}"
+    PROFILE_FILE="$_tmp_profile"
+    echo "  Pack '$PACK_NAME': $_description"
+fi
+
+# --- Profile validation ---
+if [ "$PROFILE" = "autodetect" ] && [ -z "$PROFILE_FILE" ]; then
+    source "$SCRIPT_DIR/scripts/autodetect-profile.sh"
+fi
+if [ -n "$PROFILE" ]; then
+    if [ -z "$PROFILE_FILE" ]; then
+        PROFILE_FILE="$SCRIPT_DIR/profiles/${PROFILE}.json"
+    fi
+    if [ ! -f "$PROFILE_FILE" ]; then
+        echo "Error: unknown profile '$PROFILE'"
+        echo "Available profiles: fullstack, api, data, autodetect"
+        exit 1
+    fi
+fi
+
+# --- detect_installed_clis() ---
+# Returns space-separated list of installed CLI tools
+detect_installed_clis() {
+    local found=()
+    command -v claude >/dev/null 2>&1 && found+=("claude")
+    command -v kimi >/dev/null 2>&1 && found+=("kimi")
+    command -v codex >/dev/null 2>&1 && found+=("codex")
+    echo "${found[*]}"
+}
+
+# --- copy_skills() ---
+copy_skills() {
+    local target_dir="$1"
+    local profile="$2"
+    if [ -z "$profile" ]; then
+        cp -r "$SCRIPT_DIR/skills/"* "$target_dir/skills/" 2>/dev/null || true
+    else
+        grep '"[a-z]' "$PROFILE_FILE" | sed 's/.*"\([a-z][^"]*\)".*/\1/' | grep '/' | while read -r skill; do
+            local src="$SCRIPT_DIR/skills/$skill"
+            local dest="$target_dir/skills/$skill"
+            mkdir -p "$(dirname "$dest")"
+            cp -r "$src" "$dest" 2>/dev/null || true
+        done
+        echo "  Profile '$profile': installed $(grep '/' "$PROFILE_FILE" | grep -c '"[a-z]') skills (out of 36)"
+    fi
+}
+
+# --- Shared conversion functions ---
+# Used by install_claude(), install_kimi(), and install_codex()
+
+# create_docs_workspace(project_root) — creates docs/ subdirectories for agent outputs
+create_docs_workspace() {
+    local project_root="$1"
+    mkdir -p "$project_root/docs"/{brainstorms,plans,decisions,research,audits,conversations,chains,.context,.metrics}
+    echo "  Created docs/ workspace"
+}
+
+# generate_agents_md(output_file, subtitle [, extra_content])
+# Generates AGENTS.md from CLAUDE.md sections (Agents, Skills, Modes, Conventions)
+# extra_content is inserted between Skills and Modes (e.g. Commands listing for Codex)
+generate_agents_md() {
+    local output_file="$1"
+    local subtitle="$2"
+    local extra_content="${3:-}"
+    {
+        echo "# CortexHawk"
+        echo ""
+        echo "Development toolkit — $subtitle"
+        echo ""
+        awk '/^## Agents$/,/^## [^A]/' "$SCRIPT_DIR/CLAUDE.md" | sed '$d'
+        echo ""
+        awk '/^## Skills$/,/^## [^S]/' "$SCRIPT_DIR/CLAUDE.md" | sed '$d'
+        if [ -n "$extra_content" ]; then
+            echo ""
+            echo "$extra_content"
+        fi
+        echo ""
+        awk '/^## Modes$/,/^## [^M]/' "$SCRIPT_DIR/CLAUDE.md" | sed '$d'
+        echo ""
+        awk '/^## Conventions$/,/^$/' "$SCRIPT_DIR/CLAUDE.md"
+    } > "$output_file"
+}
+
+# convert_modes_to_skills(skills_dir, prefix)
+# Copies modes/*.md into skills dir as SKILL.md
+# prefix: "modes/" for Kimi (→ skills/modes/fast/), "mode-" for Codex (→ skills/mode-fast/)
+convert_modes_to_skills() {
+    local skills_dir="$1"
+    local prefix="$2"
+    echo "  Converting modes to skills..."
+    for mode_file in "$SCRIPT_DIR"/modes/*.md; do
+        [ -f "$mode_file" ] || continue
+        local mode_name
+        mode_name=$(basename "$mode_file" .md)
+        mkdir -p "$skills_dir/${prefix}${mode_name}"
+        cp "$mode_file" "$skills_dir/${prefix}${mode_name}/SKILL.md"
+    done
+}
+
+# merge_mcp_json(output_file) — merges mcp/*.json into single JSON file
+merge_mcp_json() {
+    local output_file="$1"
+    local entries=""
+    for mcp_file in "$SCRIPT_DIR"/mcp/*.json; do
+        [ -f "$mcp_file" ] || continue
+        local server_name command_val args_val entry
+        server_name=$(basename "$mcp_file" .json)
+        command_val=$(grep '"command"' "$mcp_file" | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+        args_val=$(grep '"args"' "$mcp_file" | sed 's/.*"args"[[:space:]]*:[[:space:]]*\(\[.*\]\).*/\1/')
+        entry="    \"$server_name\": {\n      \"command\": \"$command_val\",\n      \"args\": $args_val\n    }"
+        if [ -n "$entries" ]; then
+            entries="$entries,\n$entry"
+        else
+            entries="$entry"
+        fi
+    done
+    printf '{\n  "mcpServers": {\n'"$entries"'\n  }\n}\n' > "$output_file"
+}
+
+# merge_mcp_toml() — outputs TOML [mcp.servers.*] sections to stdout
+merge_mcp_toml() {
+    for mcp_file in "$SCRIPT_DIR"/mcp/*.json; do
+        [ -f "$mcp_file" ] || continue
+        local server_name command_val args_val
+        server_name=$(basename "$mcp_file" .json)
+        command_val=$(grep '"command"' "$mcp_file" | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+        args_val=$(grep '"args"' "$mcp_file" | sed 's/.*"args"[[:space:]]*:[[:space:]]*\(\[.*\]\).*/\1/')
+        echo "[mcp.servers.$server_name]"
+        echo "command = \"$command_val\""
+        echo "args = $args_val"
+        echo ""
+    done
+}
+
+# --- update_gitignore() ---
+# Args: $1=project_root $2=target_dir_name (e.g., .claude, .kimi)
+update_gitignore() {
+    local project_root="$1"
+    local target_dir="$2"
+    local gitignore="$project_root/.gitignore"
+
+    [ "$GLOBAL" = true ] && return
+
+    # Create .gitignore if it doesn't exist
+    if [ ! -f "$gitignore" ]; then
+        touch "$gitignore"
+    fi
+
+    # Auto-add target directory (always)
+    if ! grep -qx "$target_dir/" "$gitignore" 2>/dev/null; then
+        echo "" >> "$gitignore"
+        echo "# CortexHawk" >> "$gitignore"
+        echo "$target_dir/" >> "$gitignore"
+        green "  Added $target_dir/ to .gitignore"
+    fi
+
+    # Ask about docs/ (only if docs/ exists and not already in .gitignore)
+    if [ -d "$project_root/docs" ] && ! grep -qx "docs/" "$gitignore" 2>/dev/null; then
+        echo ""
+        echo "  docs/ contains agent outputs (brainstorms, plans, research)."
+        read -r -p "  Track docs/ in git? [Y/n]: " docs_choice
+        case "$docs_choice" in
+            [nN]*)
+                echo "docs/" >> "$gitignore"
+                green "  Added docs/ to .gitignore"
+                ;;
+            *)
+                green "  docs/ will be tracked in git"
+                ;;
+        esac
+    fi
+}
+
+# --- run_audit() ---
+run_audit() {
+    local project_root="$1"
+    if [ "$NO_SCAN" = true ]; then return 0; fi
+    if [ -f "$SCRIPT_DIR/scripts/post-install-audit.sh" ]; then
+        bash "$SCRIPT_DIR/scripts/post-install-audit.sh" "$project_root" || true
+    fi
+}
+
+# --- generate_hooks_config() ---
+# Parses hooks/compose.yml and generates JSON hooks config for settings.json
+# Args: $1 = compose.yml path, $2 = hooks dir prefix (e.g., .claude/hooks)
+# Outputs JSON to stdout
+generate_hooks_config() {
+    local compose_file="$1"
+    local hooks_dir="$2"
+
+    if [ ! -f "$compose_file" ]; then
+        return 1
+    fi
+
+    if ! command -v python3 >/dev/null 2>&1; then
+        return 1
+    fi
+
+    python3 << PYEOF
+import re, json, sys
+
+def parse_compose(path, hooks_dir):
+    """Parse compose.yml and generate Claude Code hooks JSON."""
+    events = {"SessionStart": [], "PreToolUse": [], "PostToolUse": [], "SessionEnd": []}
+
+    with open(path) as f:
+        content = f.read()
+
+    # Simple YAML parser for our specific format
+    current_comp = None
+    current_event = None
+    current_matcher = None
+
+    for line in content.split('\n'):
+        line = line.rstrip()
+        if not line or line.strip().startswith('#'):
+            continue
+
+        # New composition (2 spaces indent)
+        if re.match(r'^  [a-z]', line) and ':' in line and 'event' not in line:
+            current_comp = line.strip().rstrip(':')
+            current_event = None
+            current_matcher = None
+        # Event
+        elif 'event:' in line:
+            current_event = line.split('event:')[1].strip()
+        # Matcher
+        elif 'matcher:' in line:
+            m = line.split('matcher:')[1].strip().strip('"').strip("'")
+            current_matcher = m
+        # Hook item
+        elif line.strip().startswith('- '):
+            hook_name = line.strip()[2:].strip()
+            hook_path = f"{hooks_dir}/{hook_name}.sh"
+
+            # Build command — hooks read stdin JSON (Claude Code protocol)
+            cmd = f'bash {hook_path}'
+
+            hook_entry = {"type": "command", "command": cmd}
+
+            # Find or create matcher group
+            found = False
+            for group in events[current_event]:
+                if group["matcher"] == current_matcher:
+                    group["hooks"].append(hook_entry)
+                    found = True
+                    break
+            if not found:
+                events[current_event].append({
+                    "matcher": current_matcher,
+                    "hooks": [hook_entry]
+                })
+
+    # Build final structure
+    result = {}
+    for event, groups in events.items():
+        if groups:
+            result[event] = groups
+
+    return result
+
+try:
+    result = parse_compose("$compose_file", "$hooks_dir")
+    print(json.dumps(result, indent=2))
+except Exception as e:
+    print(f"Error: {e}", file=sys.stderr)
+    sys.exit(1)
+PYEOF
+}
+
+# --- write_manifest() ---
+write_manifest() {
+    local target_dir="$1"
+    local profile="$2"
+    local target_cli="$3"
+    local is_update="${4:-false}"
+    local manifest="$target_dir/.cortexhawk-manifest"
+    local version
+    version=$(get_version)
+    local now
+    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local install_date="$now"
+    local source_type
+    source_type=$(detect_source_type)
+    local source_url
+    source_url=$(get_source_url)
+
+    # Preserve install_date on update
+    if [ "$is_update" = true ] && [ -f "$manifest" ]; then
+        local old_date
+        old_date=$(grep '"install_date"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        [ -n "$old_date" ] && install_date="$old_date"
+    fi
+
+    # Build files JSON
+    local files_json=""
+    local first=true
+    while IFS= read -r file; do
+        local relpath="${file#$target_dir/}"
+        case "$relpath" in
+            settings.json|git-workflow.conf|.cortexhawk-manifest) continue ;;
+        esac
+        local checksum
+        checksum=$(compute_checksum "$file")
+        if [ "$first" = true ]; then
+            files_json=$(printf '    "%s": "sha256:%s"' "$relpath" "$checksum")
+            first=false
+        else
+            files_json=$(printf '%s,\n    "%s": "sha256:%s"' "$files_json" "$relpath" "$checksum")
+        fi
+    done < <(find "$target_dir" -type f | sort)
+
+    printf '{\n  "version": "%s",\n  "install_date": "%s",\n  "update_date": "%s",\n  "profile": "%s",\n  "target": "%s",\n  "source": "%s",\n  "source_url": "%s",\n  "source_path": "%s",\n  "files": {\n%s\n  }\n}\n' \
+        "$version" "$install_date" "$now" "${profile:-all}" "$target_cli" \
+        "$source_type" "$source_url" "$SCRIPT_DIR" "$files_json" \
+        > "$manifest"
+}
+
+# --- Update functions ---
+UPDATE_CLEANUP_DIR=""
+
+cleanup_update() {
+    if [ -n "$UPDATE_CLEANUP_DIR" ]; then
+        rm -rf "$UPDATE_CLEANUP_DIR"
+    fi
+}
+
+update_source_git() {
+    local current_branch
+    current_branch=$(git -C "$SCRIPT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    if [ "$current_branch" != "main" ]; then
+        echo "  Warning: source repo is on branch '$current_branch', not 'main'"
+    fi
+    if ! git -C "$SCRIPT_DIR" pull --ff-only 2>&1; then
+        echo "Error: git pull failed. Resolve conflicts in $SCRIPT_DIR and retry."
+        exit 1
+    fi
+}
+
+update_source_release() {
+    local tmp_dir="/tmp/cortexhawk-update-$$"
+    local repo_url
+    repo_url=$(get_source_url)
+    if [ -z "$repo_url" ] && [ -f "$TARGET/.cortexhawk-manifest" ]; then
+        repo_url=$(grep '"source_url"' "$TARGET/.cortexhawk-manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    fi
+    if [ -z "$repo_url" ]; then
+        echo "Error: cannot determine source repository URL"
+        echo "Set CORTEXHAWK_REPO environment variable and retry"
+        exit 1
+    fi
+    mkdir -p "$tmp_dir"
+    echo "  Downloading from $repo_url..."
+    if ! curl -sL "$repo_url/archive/refs/heads/main.tar.gz" | tar xz -C "$tmp_dir" --strip-components=1; then
+        echo "Error: failed to download latest release"
+        rm -rf "$tmp_dir"
+        exit 1
+    fi
+    SCRIPT_DIR="$tmp_dir"
+    UPDATE_CLEANUP_DIR="$tmp_dir"
+}
+
+# Sync counters (global for use across functions)
+SYNC_ADDED=0
+SYNC_UPDATED=0
+SYNC_UNCHANGED=0
+SYNC_SKIPPED=0
+SYNC_CONFLICTS=0
+
+prompt_conflict() {
+    local relpath="$1"
+    local target_file="$2"
+    local source_file="$3"
+
+    SYNC_CONFLICTS=$((SYNC_CONFLICTS + 1))
+
+    # Non-interactive mode — skip conflicts silently
+    if [ ! -e /dev/tty ]; then
+        echo "  CONFLICT: $relpath (skipped — non-interactive)"
+        SYNC_SKIPPED=$((SYNC_SKIPPED + 1))
+        return 0
+    fi
+
+    echo ""
+    echo "  CONFLICT: $relpath"
+    echo "    You have modified this file, and a new version is available."
+    echo ""
+    echo "    [o] Overwrite with new version"
+    echo "    [s] Skip — keep your version"
+    echo "    [d] Show diff"
+    echo ""
+
+    while true; do
+        printf "    Choice [o/s/d] (default: s): "
+        read -r choice </dev/tty
+        case "${choice:-s}" in
+            o)
+                cp "$source_file" "$target_file"
+                SYNC_UPDATED=$((SYNC_UPDATED + 1))
+                return 0
+                ;;
+            s)
+                SYNC_SKIPPED=$((SYNC_SKIPPED + 1))
+                return 0
+                ;;
+            d)
+                echo ""
+                diff "$target_file" "$source_file" || true
+                echo ""
+                ;;
+            *)
+                echo "    Invalid choice. Please enter o, s, or d."
+                ;;
+        esac
+    done
+}
+
+sync_file() {
+    local source_file="$1"
+    local target_file="$2"
+    local manifest="$3"
+    local relpath="$4"
+
+    local source_checksum
+    source_checksum=$(compute_checksum "$source_file")
+
+    # New file — copy directly
+    if [ ! -f "$target_file" ]; then
+        if [ "$DRY_RUN" != true ]; then
+            mkdir -p "$(dirname "$target_file")"
+            cp "$source_file" "$target_file"
+        else
+            echo "  + $relpath"
+        fi
+        SYNC_ADDED=$((SYNC_ADDED + 1))
+        return 0
+    fi
+
+    local current_checksum
+    current_checksum=$(compute_checksum "$target_file")
+
+    # Source identical to current — nothing to do
+    if [ "$current_checksum" = "$source_checksum" ]; then
+        SYNC_UNCHANGED=$((SYNC_UNCHANGED + 1))
+        return 0
+    fi
+
+    # Get manifest checksum (from last install/update)
+    local manifest_checksum=""
+    if [ -f "$manifest" ]; then
+        manifest_checksum=$(grep -F "\"$relpath\": \"sha256:" "$manifest" 2>/dev/null | sed 's/.*"sha256:\([^"]*\)".*/\1/' || true)
+    fi
+
+    # No manifest entry — no baseline, treat as conflict
+    if [ -z "$manifest_checksum" ]; then
+        if [ "$DRY_RUN" = true ]; then
+            echo "  ? $relpath (conflict — no baseline)"
+            SYNC_CONFLICTS=$((SYNC_CONFLICTS + 1))
+        else
+            prompt_conflict "$relpath" "$target_file" "$source_file"
+        fi
+        return 0
+    fi
+
+    local manifest_eq_current=false
+    local manifest_eq_source=false
+    [ "$manifest_checksum" = "$current_checksum" ] && manifest_eq_current=true
+    [ "$manifest_checksum" = "$source_checksum" ] && manifest_eq_source=true
+
+    if [ "$manifest_eq_current" = true ] && [ "$manifest_eq_source" = true ]; then
+        # Nothing changed anywhere
+        SYNC_UNCHANGED=$((SYNC_UNCHANGED + 1))
+    elif [ "$manifest_eq_current" = true ] && [ "$manifest_eq_source" = false ]; then
+        # User didn't touch, source changed — overwrite silently
+        if [ "$DRY_RUN" = true ]; then
+            echo "  ~ $relpath"
+        else
+            cp "$source_file" "$target_file"
+        fi
+        SYNC_UPDATED=$((SYNC_UPDATED + 1))
+    elif [ "$manifest_eq_current" = false ] && [ "$manifest_eq_source" = true ]; then
+        # User modified, source unchanged — skip
+        [ "$DRY_RUN" = true ] && echo "  s $relpath (user modified)"
+        SYNC_SKIPPED=$((SYNC_SKIPPED + 1))
+    else
+        # Both changed — conflict
+        if [ "$DRY_RUN" = true ]; then
+            echo "  ? $relpath (conflict)"
+            SYNC_CONFLICTS=$((SYNC_CONFLICTS + 1))
+        else
+            prompt_conflict "$relpath" "$target_file" "$source_file"
+        fi
+    fi
+}
+
+sync_component() {
+    local component="$1"
+    local source_dir="$SCRIPT_DIR/$component"
+    local target_dir="$TARGET/$component"
+    local manifest="$TARGET/.cortexhawk-manifest"
+
+    [ "$DRY_RUN" != true ] && echo "Syncing $component..."
+
+    [ -d "$source_dir" ] || return 0
+    [ "$DRY_RUN" != true ] && mkdir -p "$target_dir"
+
+    while IFS= read -r source_file; do
+        local relpath="${source_file#$source_dir/}"
+        local target_file="$target_dir/$relpath"
+        sync_file "$source_file" "$target_file" "$manifest" "$component/$relpath"
+    done < <(find "$source_dir" -type f | sort)
+}
+
+sync_skills_update() {
+    local update_profile="$1"
+    local source_dir="$SCRIPT_DIR/skills"
+    local target_dir="$TARGET/skills"
+    local manifest="$TARGET/.cortexhawk-manifest"
+
+    [ "$DRY_RUN" != true ] && echo "Syncing skills..."
+
+    [ "$DRY_RUN" != true ] && mkdir -p "$target_dir"
+
+    if [ -z "$update_profile" ] || [ "$update_profile" = "all" ]; then
+        while IFS= read -r source_file; do
+            local relpath="${source_file#$source_dir/}"
+            local target_file="$target_dir/$relpath"
+            sync_file "$source_file" "$target_file" "$manifest" "skills/$relpath"
+        done < <(find "$source_dir" -type f | sort)
+    else
+        local skill_list
+        skill_list=$(grep '"[a-z]' "$PROFILE_FILE" | sed 's/.*"\([a-z][^"]*\)".*/\1/' | grep '/')
+        while IFS= read -r skill; do
+            [ -z "$skill" ] && continue
+            local src="$source_dir/$skill"
+            [ -e "$src" ] || continue
+            if [ -f "$src" ]; then
+                sync_file "$src" "$target_dir/$skill" "$manifest" "skills/$skill"
+            elif [ -d "$src" ]; then
+                while IFS= read -r source_file; do
+                    local relpath="${source_file#$source_dir/}"
+                    local target_file="$target_dir/$relpath"
+                    sync_file "$source_file" "$target_file" "$manifest" "skills/$relpath"
+                done < <(find "$src" -type f | sort)
+            fi
+        done <<< "$skill_list"
+    fi
+}
+
+do_update() {
+    # 1. Validate target
+    if [ "$TARGET_CLI" != "claude" ]; then
+        echo "Error: --update is currently supported for Claude Code only"
+        echo "For Kimi CLI, re-run: install.sh --target kimi"
+        exit 1
+    fi
+
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    if [ ! -d "$TARGET" ]; then
+        echo "Error: no CortexHawk installation found at $TARGET"
+        echo "Run install.sh without --update for a fresh install"
+        exit 1
+    fi
+
+    # 2. Read manifest
+    local manifest="$TARGET/.cortexhawk-manifest"
+    local current_version="unknown"
+    local current_profile="all"
+    local source_type
+    source_type=$(detect_source_type)
+
+    if [ -f "$manifest" ]; then
+        current_version=$(grep '"version"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        current_profile=$(grep '"profile"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        local manifest_source
+        manifest_source=$(grep '"source"' "$manifest" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+        [ -n "$manifest_source" ] && source_type="$manifest_source"
+    else
+        echo "  No manifest found — treating as pre-update installation"
+    fi
+
+    # 3. Profile override
+    local update_profile="$current_profile"
+    if [ -n "$PROFILE" ]; then
+        update_profile="$PROFILE"
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "CortexHawk Dry Run (update)"
+        echo "============================"
+    else
+        echo "CortexHawk Update"
+        echo "==================="
+    fi
+    echo "  Current version: $current_version"
+    echo "  Profile: $update_profile"
+    echo "  Source: $source_type"
+    echo ""
+
+    # 3b. Auto-snapshot before update (skip in dry-run)
+    if [ "$DRY_RUN" != true ] && [ -f "$manifest" ]; then
+        echo "Creating pre-update snapshot..."
+        do_snapshot 2>/dev/null
+        PRE_UPDATE_SNAP=$(ls -t "$TARGET/.cortexhawk-snapshots"/*.json 2>/dev/null | head -1)
+        [ -n "$PRE_UPDATE_SNAP" ] && echo "  Saved: $(basename "$PRE_UPDATE_SNAP")"
+        echo ""
+    fi
+
+    # 4. Pull source (skip in dry-run — compare against current source)
+    if [ "$DRY_RUN" != true ]; then
+        if [ "$source_type" = "git" ]; then
+            echo "Updating CortexHawk source via git pull..."
+            update_source_git
+        else
+            echo "Updating CortexHawk source via download..."
+            update_source_release
+        fi
+        echo "  Source updated successfully."
+    fi
+
+    # 5. Compare versions
+    local new_version
+    new_version=$(get_version)
+    echo "  New version: $new_version"
+    echo ""
+
+    if [ "$current_version" = "$new_version" ] && [ "$FORCE_MODE" != true ]; then
+        # Same version — check if files actually changed (checksum comparison)
+        local files_changed=0
+        if [ -f "$manifest" ]; then
+            while IFS= read -r line; do
+                local fpath fhash
+                fpath=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:\([^"]*\)".*/\1/')
+                fhash=$(echo "$line" | sed 's/.*"sha256:\([^"]*\)".*/\1/')
+                [ -z "$fpath" ] || [ -z "$fhash" ] && continue
+                local source_file="$SCRIPT_DIR/$fpath"
+                [ -f "$source_file" ] || continue
+                local source_hash
+                source_hash=$(compute_checksum "$source_file")
+                if [ "$fhash" != "$source_hash" ]; then
+                    files_changed=$((files_changed + 1))
+                fi
+            done < <(grep '"sha256:' "$manifest")
+        fi
+
+        if [ "$files_changed" -eq 0 ] && [ "$DRY_RUN" != true ]; then
+            # Still apply install improvements even if no component files changed
+            local target_dir_name=".${TARGET_CLI:-claude}"
+            update_gitignore "$(dirname "$TARGET")" "$target_dir_name"
+            [ "$TARGET_CLI" = "codex" ] && update_gitignore "$(dirname "$TARGET")" ".agents"
+            if [ ! -f "$TARGET/git-workflow.conf" ]; then
+                GIT_BRANCHING="direct-main"
+                GIT_COMMIT_CONVENTION="conventional"
+                GIT_PR_PREFERENCE="on-demand"
+                GIT_AUTO_PUSH="after-commit"
+                GIT_WORK_BRANCH=""
+                source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$(dirname "$TARGET")" "$TARGET"
+            fi
+            echo "Already up to date ($new_version). No component files changed."
+            cleanup_update
+            exit 0
+        elif [ "$files_changed" -gt 0 ]; then
+            echo "  Same version ($new_version) but $files_changed file(s) changed in source."
+        fi
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "  Comparing source $new_version vs installed $current_version"
+    elif [ "$current_version" = "$new_version" ]; then
+        echo "  Syncing changed files ($new_version)..."
+    else
+        echo "  Updating $current_version -> $new_version"
+    fi
+    echo ""
+
+    # Set up profile file for skill filtering
+    if [ -n "$update_profile" ] && [ "$update_profile" != "all" ]; then
+        PROFILE_FILE="$SCRIPT_DIR/profiles/${update_profile}.json"
+        if [ ! -f "$PROFILE_FILE" ]; then
+            echo "  Warning: profile '$update_profile' not found in source — installing all skills"
+            update_profile="all"
+            PROFILE_FILE=""
+        fi
+    fi
+
+    # 6. Reset counters and sync components
+    SYNC_ADDED=0
+    SYNC_UPDATED=0
+    SYNC_UNCHANGED=0
+    SYNC_SKIPPED=0
+    SYNC_CONFLICTS=0
+
+    sync_component "agents"
+    sync_component "commands"
+    sync_skills_update "$update_profile"
+    sync_component "hooks"
+    sync_component "modes"
+    sync_component "mcp"
+
+    # 6b. Sync agent personas from project root
+    local project_root
+    project_root="$(dirname "$TARGET")"
+    if [ -d "$project_root/.cortexhawk-agents" ] && [ "$DRY_RUN" != true ]; then
+        cp -r "$project_root/.cortexhawk-agents/"*.md "$TARGET/agents/" 2>/dev/null || true
+        local pc
+        pc=$(find "$project_root/.cortexhawk-agents" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+        [ "$pc" -gt 0 ] && echo "  Synced $pc agent persona(s) from .cortexhawk-agents/"
+    fi
+
+    # 7. Detect removed upstream files
+    if [ -f "$manifest" ]; then
+        while IFS= read -r line; do
+            local file_relpath
+            file_relpath=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/')
+            [ -z "$file_relpath" ] && continue
+            if [ ! -f "$SCRIPT_DIR/$file_relpath" ] && [ -f "$TARGET/$file_relpath" ]; then
+                echo "  Warning: $file_relpath was removed upstream (kept locally)"
+            fi
+        done < <(grep '"sha256:' "$manifest")
+    fi
+
+    if [ "$DRY_RUN" != true ]; then
+        # Make hooks executable
+        chmod +x "$TARGET/hooks/"*.sh 2>/dev/null || true
+
+        # 7b. Regenerate settings.json hooks section from compose.yml
+        if [ -f "$SCRIPT_DIR/hooks/compose.yml" ]; then
+            local hooks_json
+            hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
+            if [ -n "$hooks_json" ]; then
+                python3 << PYEOF
+import json, sys
+
+# Read current settings.json to preserve permissions
+current = {}
+try:
+    with open('$TARGET/settings.json') as f:
+        current = json.load(f)
+except:
+    pass
+
+# Merge: keep existing permissions, replace hooks
+hooks = json.loads('''$hooks_json''')
+current['hooks'] = hooks
+
+with open('$TARGET/settings.json', 'w') as f:
+    json.dump(current, f, indent=2)
+    f.write('\n')
+PYEOF
+                echo "  Regenerated settings.json hooks from compose.yml"
+            fi
+        fi
+
+        # 8. Write new manifest
+        write_manifest "$TARGET" "$update_profile" "$TARGET_CLI" true
+
+        # 9. Run audit
+        run_audit "$(dirname "$TARGET")"
+
+        # 10. Apply install improvements (gitignore, git-workflow defaults)
+        local target_dir_name=".${TARGET_CLI:-claude}"
+        update_gitignore "$(dirname "$TARGET")" "$target_dir_name"
+        [ "$TARGET_CLI" = "codex" ] && update_gitignore "$(dirname "$TARGET")" ".agents"
+
+        if [ ! -f "$TARGET/git-workflow.conf" ]; then
+            GIT_BRANCHING="direct-main"
+            GIT_COMMIT_CONVENTION="conventional"
+            GIT_PR_PREFERENCE="on-demand"
+            GIT_AUTO_PUSH="after-commit"
+            GIT_WORK_BRANCH=""
+            source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$(dirname "$TARGET")" "$TARGET"
+        fi
+    fi
+
+    # 10. Print summary
+    echo ""
+    if [ "$DRY_RUN" = true ]; then
+        echo "Dry run summary:"
+        echo "  Would add:     $SYNC_ADDED"
+        echo "  Would update:  $SYNC_UPDATED"
+        echo "  Unchanged:     $SYNC_UNCHANGED"
+        echo "  Would skip:    $SYNC_SKIPPED"
+        echo "  Conflicts:     $SYNC_CONFLICTS"
+        echo ""
+        echo "No files were modified (dry run)."
+    else
+        echo "Update complete: $current_version -> $new_version"
+        echo "  Added:     $SYNC_ADDED"
+        echo "  Updated:   $SYNC_UPDATED"
+        echo "  Unchanged: $SYNC_UNCHANGED"
+        echo "  Skipped:   $SYNC_SKIPPED"
+        echo "  Conflicts: $SYNC_CONFLICTS"
+        if [ -n "${PRE_UPDATE_SNAP:-}" ]; then
+            echo "  Rollback: install.sh --restore $PRE_UPDATE_SNAP"
+        fi
+        echo ""
+        echo "  To activate: exit your CLI (ctrl+c) and relaunch in this directory."
+    fi
+
+    cleanup_update
+}
+
+# --- rotate_snapshots() ---
+# Keeps only the N most recent snapshots, deletes the rest
+rotate_snapshots() {
+    local snap_dir="$1"
+    local snaps
+    snaps=$(find "$snap_dir" -maxdepth 1 -name '*.json' -type f 2>/dev/null)
+    [ -z "$snaps" ] && return 0
+    local count
+    count=$(echo "$snaps" | wc -l | tr -d ' ')
+    if [ "$count" -gt "$MAX_SNAPSHOTS" ]; then
+        local to_delete=$((count - MAX_SNAPSHOTS))
+        ls -1t "$snap_dir"/*.json | tail -n "$to_delete" | while read -r old_snap; do
+            rm -f "$old_snap"
+        done
+        echo "  Rotated: removed $to_delete old snapshot(s), keeping $MAX_SNAPSHOTS"
+    fi
+}
+
+# --- do_snapshot() ---
+do_snapshot() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local manifest="$TARGET/.cortexhawk-manifest"
+    if [ ! -f "$manifest" ]; then
+        echo "Error: no CortexHawk manifest found at $manifest"
+        echo "Run install.sh first to create an installation"
+        exit 1
+    fi
+
+    # Read manifest metadata
+    local version
+    version=$(grep '"version"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local profile
+    profile=$(grep '"profile"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local source_type
+    source_type=$(grep '"source"' "$manifest" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local source_url
+    source_url=$(grep '"source_url"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local source_path
+    source_path=$(grep '"source_path"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    # Read settings.json
+    local settings_json="null"
+    if [ -f "$TARGET/settings.json" ]; then
+        settings_json=$(cat "$TARGET/settings.json")
+    fi
+
+    # Read git-workflow.conf
+    local git_branching="" git_commit="" git_pr="" git_push=""
+    if [ -f "$TARGET/git-workflow.conf" ]; then
+        git_branching=$(grep '^BRANCHING=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        git_commit=$(grep '^COMMIT_CONVENTION=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        git_pr=$(grep '^PR_PREFERENCE=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        git_push=$(grep '^AUTO_PUSH=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+    fi
+
+    # Read custom profile if applicable
+    local profile_def="null"
+    local custom_profile
+    custom_profile=$(ls /tmp/cortexhawk-custom-*.json 2>/dev/null | head -1)
+    if [ -n "$custom_profile" ] && [ -f "$custom_profile" ]; then
+        profile_def=$(cat "$custom_profile")
+    fi
+
+    # Build files checksums from manifest
+    local files_json
+    files_json=$(sed -n '/"files"/,/^  }/p' "$manifest" | sed '1d;$d')
+
+    # Collect file contents (base64 encoded for binary safety)
+    local git_workflow_content="" claude_md_content=""
+    if [ -f "$TARGET/git-workflow.conf" ]; then
+        git_workflow_content=$(base64 < "$TARGET/git-workflow.conf" | tr -d '\n')
+    fi
+    if [ -f "$TARGET/../CLAUDE.md" ]; then
+        claude_md_content=$(base64 < "$TARGET/../CLAUDE.md" | tr -d '\n')
+    fi
+
+    # Generate snapshot
+    local now
+    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local snap_name
+    snap_name=$(date -u +"%Y-%m-%d-%H%M%S")
+    local snap_dir="$TARGET/.cortexhawk-snapshots"
+    local snap_file="$snap_dir/${snap_name}.json"
+
+    mkdir -p "$snap_dir"
+
+    # Write snapshot JSON
+    printf '{\n' > "$snap_file"
+    printf '  "snapshot_version": "2",\n' >> "$snap_file"
+    printf '  "snapshot_date": "%s",\n' "$now" >> "$snap_file"
+    printf '  "cortexhawk_version": "%s",\n' "$version" >> "$snap_file"
+    printf '  "target": "claude",\n' >> "$snap_file"
+    printf '  "profile": "%s",\n' "$profile" >> "$snap_file"
+    printf '  "profile_definition": %s,\n' "$profile_def" >> "$snap_file"
+    printf '  "source": "%s",\n' "$source_type" >> "$snap_file"
+    printf '  "source_url": "%s",\n' "$source_url" >> "$snap_file"
+    printf '  "source_path": "%s",\n' "$source_path" >> "$snap_file"
+    printf '  "settings": %s,\n' "$settings_json" >> "$snap_file"
+    printf '  "git_workflow": {\n' >> "$snap_file"
+    printf '    "BRANCHING": "%s",\n' "$git_branching" >> "$snap_file"
+    printf '    "COMMIT_CONVENTION": "%s",\n' "$git_commit" >> "$snap_file"
+    printf '    "PR_PREFERENCE": "%s",\n' "$git_pr" >> "$snap_file"
+    printf '    "AUTO_PUSH": "%s"\n' "$git_push" >> "$snap_file"
+    printf '  },\n' >> "$snap_file"
+    printf '  "files": {\n' >> "$snap_file"
+    printf '%s\n' "$files_json" >> "$snap_file"
+    printf '  },\n' >> "$snap_file"
+    printf '  "file_contents": {\n' >> "$snap_file"
+    [ -n "$git_workflow_content" ] && printf '    "git-workflow.conf": "%s",\n' "$git_workflow_content" >> "$snap_file"
+    [ -n "$claude_md_content" ] && printf '    "CLAUDE.md": "%s",\n' "$claude_md_content" >> "$snap_file"
+    # Remove trailing comma from last entry
+    sed -i '$ s/,$//' "$snap_file"
+    printf '  }\n' >> "$snap_file"
+    printf '}\n' >> "$snap_file"
+
+    echo "CortexHawk Snapshot"
+    echo "====================="
+    echo "  Version:  $version"
+    echo "  Profile:  $profile"
+    echo "  Target:   $TARGET"
+    echo "  Saved to: $snap_file"
+
+    # Create portable archive if requested
+    if [ "$PORTABLE_MODE" = true ]; then
+        local archive_name="${snap_name}.tar.gz"
+        local archive_path="$snap_dir/$archive_name"
+        local tmp_dir
+        tmp_dir=$(mktemp -d)
+
+        # Copy snapshot and files to temp structure
+        cp "$snap_file" "$tmp_dir/snapshot.json"
+        mkdir -p "$tmp_dir/files"
+        cp -r "$TARGET/agents" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/commands" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/skills" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/hooks" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/modes" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/mcp" "$tmp_dir/files/" 2>/dev/null || true
+        cp "$TARGET/settings.json" "$tmp_dir/files/" 2>/dev/null || true
+        cp "$TARGET/git-workflow.conf" "$tmp_dir/files/" 2>/dev/null || true
+
+        # Create archive
+        tar -czf "$archive_path" -C "$tmp_dir" .
+        rm -rf "$tmp_dir"
+
+        echo "  Archive:  $archive_path"
+        echo ""
+        echo "Restore with: install.sh --restore $archive_path"
+    else
+        rotate_snapshots "$snap_dir"
+        echo ""
+        echo "Restore with: install.sh --restore $snap_file"
+    fi
+}
+
+# --- do_snapshots_list() ---
+do_snapshots_list() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local snap_dir="$TARGET/.cortexhawk-snapshots"
+    if [ ! -d "$snap_dir" ] || [ -z "$(ls "$snap_dir"/*.json 2>/dev/null)" ]; then
+        echo "No snapshots found in $snap_dir"
+        echo "Create one with: install.sh --snapshot"
+        exit 0
+    fi
+
+    echo "CortexHawk Snapshots"
+    echo "====================="
+    printf "  %-25s %-10s %-12s %s\n" "DATE" "VERSION" "PROFILE" "FILE"
+    printf "  %-25s %-10s %-12s %s\n" "----" "-------" "-------" "----"
+
+    for snap_file in $(ls -t "$snap_dir"/*.json 2>/dev/null); do
+        local date version profile
+        date=$(grep '"snapshot_date"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        version=$(grep '"cortexhawk_version"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        profile=$(grep '"profile"' "$snap_file" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+        printf "  %-25s %-10s %-12s %s\n" "$date" "$version" "$profile" "$(basename "$snap_file")"
+    done
+
+    echo ""
+    echo "Restore with: install.sh --restore <path-to-snapshot>"
+}
+
+# --- do_diff() ---
+do_diff() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    # Resolve reference file: snapshot or manifest
+    local ref_file="$DIFF_FILE"
+    local ref_label="manifest"
+    if [ -z "$ref_file" ]; then
+        ref_file="$TARGET/.cortexhawk-manifest"
+        ref_label="manifest"
+    else
+        ref_label="snapshot $(basename "$ref_file")"
+    fi
+
+    if [ ! -f "$ref_file" ]; then
+        echo "Error: reference file not found: $ref_file"
+        [ -z "$DIFF_FILE" ] && echo "Run install.sh first to create an installation"
+        exit 1
+    fi
+
+    echo "CortexHawk Diff"
+    echo "================="
+    echo "  Reference: $ref_label"
+    echo "  Target:    $TARGET"
+    echo ""
+
+    local modified=0 missing=0 unchanged=0
+    local tracked_files=""
+
+    # Compare files listed in reference
+    while IFS= read -r line; do
+        local file_relpath
+        file_relpath=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:\([^"]*\)".*/\1/')
+        local expected
+        expected=$(echo "$line" | sed 's/.*"sha256:\([^"]*\)".*/\1/')
+        [ -z "$file_relpath" ] || [ -z "$expected" ] && continue
+
+        tracked_files="$tracked_files|$file_relpath|"
+        local target_file="$TARGET/$file_relpath"
+
+        if [ ! -f "$target_file" ]; then
+            echo "  MISSING   $file_relpath"
+            missing=$((missing + 1))
+        else
+            local actual
+            actual=$(compute_checksum "$target_file")
+            if [ "$actual" = "$expected" ]; then
+                unchanged=$((unchanged + 1))
+            else
+                echo "  MODIFIED  $file_relpath"
+                modified=$((modified + 1))
+            fi
+        fi
+    done < <(grep '"sha256:' "$ref_file")
+
+    # Detect NEW files not in reference
+    local new_count=0
+    if [ -d "$TARGET" ]; then
+        while IFS= read -r file; do
+            local relpath="${file#$TARGET/}"
+            case "$relpath" in
+                .cortexhawk-manifest|.cortexhawk-snapshots/*|settings.json|git-workflow.conf) continue ;;
+            esac
+            if [[ "$tracked_files" != *"|$relpath|"* ]]; then
+                echo "  NEW       $relpath"
+                new_count=$((new_count + 1))
+            fi
+        done < <(find "$TARGET" -type f | sort)
+    fi
+
+    echo ""
+    echo "Summary:"
+    echo "  Unchanged: $unchanged"
+    echo "  Modified:  $modified"
+    echo "  Missing:   $missing"
+    echo "  New:       $new_count"
+}
+
+# --- do_diff_semantic() ---
+# Compares two snapshot files and displays semantic differences
+do_diff_semantic() {
+    local file_a="$1"
+    local file_b="$2"
+
+    if [ ! -f "$file_a" ]; then
+        echo "Error: snapshot not found: $file_a"
+        exit 1
+    fi
+    if [ ! -f "$file_b" ]; then
+        echo "Error: snapshot not found: $file_b"
+        exit 1
+    fi
+
+    echo "CortexHawk Semantic Diff"
+    echo "========================="
+    echo "  A: $(basename "$file_a")"
+    echo "  B: $(basename "$file_b")"
+    echo ""
+
+    local changes=0
+
+    # Helper: extract JSON string value by key (anchored to line start)
+    _sdiff_val() { grep "^[[:space:]]*\"$2\"" "$1" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/'; }
+
+    # 1. Metadata comparison
+    local section_changes=0
+    for key in cortexhawk_version profile target source; do
+        local val_a val_b
+        val_a=$(_sdiff_val "$file_a" "$key")
+        val_b=$(_sdiff_val "$file_b" "$key")
+        if [ "$val_a" != "$val_b" ]; then
+            [ "$section_changes" -eq 0 ] && echo "Metadata:"
+            echo "  $key: $val_a → $val_b"
+            section_changes=$((section_changes + 1))
+            changes=$((changes + 1))
+        fi
+    done
+    [ "$section_changes" -gt 0 ] && echo ""
+
+    # 2. Git workflow comparison
+    section_changes=0
+    for key in BRANCHING COMMIT_CONVENTION PR_PREFERENCE AUTO_PUSH; do
+        local val_a val_b
+        val_a=$(_sdiff_val "$file_a" "$key")
+        val_b=$(_sdiff_val "$file_b" "$key")
+        if [ "$val_a" != "$val_b" ]; then
+            [ "$section_changes" -eq 0 ] && echo "Git Workflow:"
+            echo "  $key: $val_a → $val_b"
+            section_changes=$((section_changes + 1))
+            changes=$((changes + 1))
+        fi
+    done
+    [ "$section_changes" -gt 0 ] && echo ""
+
+    # 3. Skills comparison (extract skill paths from files keys)
+    local skills_a skills_b
+    skills_a=$(grep '"skills/' "$file_a" | sed 's/.*"\(skills\/[^"]*\)".*/\1/' | sort)
+    skills_b=$(grep '"skills/' "$file_b" | sed 's/.*"\(skills\/[^"]*\)".*/\1/' | sort)
+
+    local added removed
+    added=$(comm -13 <(echo "$skills_a") <(echo "$skills_b"))
+    removed=$(comm -23 <(echo "$skills_a") <(echo "$skills_b"))
+
+    if [ -n "$added" ] || [ -n "$removed" ]; then
+        echo "Skills:"
+        while IFS= read -r skill; do
+            [ -n "$skill" ] && echo "  + $skill" && changes=$((changes + 1))
+        done <<< "$added"
+        while IFS= read -r skill; do
+            [ -n "$skill" ] && echo "  - $skill" && changes=$((changes + 1))
+        done <<< "$removed"
+        echo ""
+    fi
+
+    # 4. Files comparison (non-skill files: agents, hooks, commands, modes)
+    local files_a files_b
+    files_a=$(grep '"sha256:' "$file_a" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/' | grep -v '^skills/' | sort)
+    files_b=$(grep '"sha256:' "$file_b" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/' | grep -v '^skills/' | sort)
+
+    local files_added files_removed
+    files_added=$(comm -13 <(echo "$files_a") <(echo "$files_b"))
+    files_removed=$(comm -23 <(echo "$files_a") <(echo "$files_b"))
+
+    # Check for modified files (same path, different checksum)
+    local files_modified=""
+    while IFS= read -r fpath; do
+        [ -z "$fpath" ] && continue
+        local cs_a cs_b
+        cs_a=$(grep "\"$fpath\"" "$file_a" | sed 's/.*"sha256:\([^"]*\)".*/\1/')
+        cs_b=$(grep "\"$fpath\"" "$file_b" | sed 's/.*"sha256:\([^"]*\)".*/\1/')
+        if [ -n "$cs_a" ] && [ -n "$cs_b" ] && [ "$cs_a" != "$cs_b" ]; then
+            files_modified="${files_modified}${fpath}\n"
+        fi
+    done < <(comm -12 <(echo "$files_a") <(echo "$files_b"))
+
+    if [ -n "$files_added" ] || [ -n "$files_removed" ] || [ -n "$files_modified" ]; then
+        echo "Files:"
+        while IFS= read -r f; do
+            [ -n "$f" ] && echo "  + $f" && changes=$((changes + 1))
+        done <<< "$files_added"
+        while IFS= read -r f; do
+            [ -n "$f" ] && echo "  - $f" && changes=$((changes + 1))
+        done <<< "$files_removed"
+        # Use process substitution to avoid subshell (pipe would lose changes counter)
+        while IFS= read -r f; do
+            [ -n "$f" ] && echo "  ~ $f" && changes=$((changes + 1))
+        done < <(printf '%b' "$files_modified")
+        echo ""
+    fi
+
+    if [ "$changes" -eq 0 ]; then
+        echo "No differences found — snapshots are identical."
+    else
+        echo "Total: $changes difference(s)"
+    fi
+
+    unset -f _sdiff_val
+}
+
+# --- do_export_team() ---
+do_export_team() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    # Resolve reference file
+    local ref_file="$EXPORT_TEAM_FILE"
+    if [ -z "$ref_file" ]; then
+        ref_file="$TARGET/.cortexhawk-manifest"
+    fi
+    if [ ! -f "$ref_file" ]; then
+        echo "Error: reference file not found: $ref_file"
+        exit 1
+    fi
+
+    local profile
+    profile=$(grep '"profile"' "$ref_file" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    # Extract skills from file paths
+    local skills=""
+    while IFS= read -r line; do
+        local path
+        path=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/')
+        case "$path" in
+            skills/*/SKILL.md)
+                local skill
+                skill=$(echo "$path" | sed 's|skills/||;s|/SKILL.md||')
+                skills="${skills:+$skills\n}  - $skill"
+                ;;
+        esac
+    done < <(grep '"sha256:' "$ref_file")
+
+    # Extract hooks (only .sh files directly in hooks/)
+    local hooks=""
+    while IFS= read -r line; do
+        local path
+        path=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/')
+        case "$path" in
+            hooks/*.sh)
+                local hook
+                hook=$(basename "$path" .sh)
+                hooks="${hooks:+$hooks\n}  - $hook"
+                ;;
+        esac
+    done < <(grep '"sha256:' "$ref_file")
+
+    # Extract modes (only .md files directly in modes/)
+    local modes=""
+    while IFS= read -r line; do
+        local path
+        path=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/')
+        case "$path" in
+            modes/*.md)
+                local mode
+                mode=$(basename "$path" .md)
+                modes="${modes:+$modes\n}  - $mode"
+                ;;
+        esac
+    done < <(grep '"sha256:' "$ref_file")
+
+    # Read git workflow
+    local gb="" gc="" gp="" ga=""
+    if grep -q '"BRANCHING"' "$ref_file" 2>/dev/null; then
+        gb=$(grep '"BRANCHING"' "$ref_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        gc=$(grep '"COMMIT_CONVENTION"' "$ref_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        gp=$(grep '"PR_PREFERENCE"' "$ref_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        ga=$(grep '"AUTO_PUSH"' "$ref_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    elif [ -f "$TARGET/git-workflow.conf" ]; then
+        gb=$(grep '^BRANCHING=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        gc=$(grep '^COMMIT_CONVENTION=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        gp=$(grep '^PR_PREFERENCE=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        ga=$(grep '^AUTO_PUSH=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+    fi
+
+    # Generate YAML
+    local output=".cortexhawk-team.yml"
+    {
+        echo "# .cortexhawk-team.yml"
+        echo "# Generated from $(basename "$ref_file") by CortexHawk"
+        echo "version: \"1\""
+        echo "profile: ${profile:-all}"
+        if [ -n "$skills" ]; then
+            echo "skills:"
+            printf '%b\n' "$skills"
+        fi
+        if [ -n "$hooks" ]; then
+            echo "hooks:"
+            printf '%b\n' "$hooks"
+        fi
+        if [ -n "$modes" ]; then
+            echo "modes:"
+            printf '%b\n' "$modes"
+        fi
+        if [ -n "$gb" ]; then
+            echo "git_workflow:"
+            echo "  branching: $gb"
+            echo "  commit_convention: $gc"
+            echo "  pr_preference: $gp"
+            echo "  auto_push: $ga"
+        fi
+    } > "$output"
+
+    echo "CortexHawk Export Team"
+    echo "========================"
+    echo "  Source: $(basename "$ref_file")"
+    echo "  Profile: ${profile:-all}"
+    echo "  Output: $output"
+    echo ""
+    echo "Share this file with your team. Install with: install.sh --team"
+}
+
+# --- do_restore() ---
+do_restore() {
+    local snap_file="$1"
+    local archive_tmp=""
+    local portable_files=""
+
+    if [ -z "$snap_file" ] || [ ! -f "$snap_file" ]; then
+        echo "Error: snapshot file not found: $snap_file"
+        exit 1
+    fi
+
+    # Handle portable archive (.tar.gz)
+    if [[ "$snap_file" == *.tar.gz ]]; then
+        archive_tmp=$(mktemp -d)
+        tar -xzf "$snap_file" -C "$archive_tmp"
+        snap_file="$archive_tmp/snapshot.json"
+        portable_files="$archive_tmp/files"
+        if [ ! -f "$snap_file" ]; then
+            echo "Error: invalid archive — snapshot.json not found"
+            rm -rf "$archive_tmp"
+            exit 1
+        fi
+        echo "Extracting portable archive..."
+    fi
+
+    # Extract metadata from snapshot
+    local snap_version
+    snap_version=$(grep '"cortexhawk_version"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local snap_profile
+    snap_profile=$(grep '"profile"' "$snap_file" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local snap_source
+    snap_source=$(grep '"source"' "$snap_file" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local snap_source_url
+    snap_source_url=$(grep '"source_url"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local snap_source_path
+    snap_source_path=$(grep '"source_path"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    echo "CortexHawk Restore"
+    echo "====================="
+    echo "  Snapshot version: $snap_version"
+    echo "  Profile: $snap_profile"
+    echo "  Source: $snap_source"
+    echo ""
+
+    # Determine CortexHawk source
+    local restore_source="$SCRIPT_DIR"
+    if [ "$snap_source" = "git" ] && [ -n "$snap_source_path" ] && [ -d "$snap_source_path" ]; then
+        restore_source="$snap_source_path"
+    fi
+    if [ ! -d "$restore_source/agents" ]; then
+        echo "Error: CortexHawk source not found at $restore_source"
+        echo "Ensure the CortexHawk repo is available or set CORTEXHAWK_REPO"
+        exit 1
+    fi
+
+    # Warn if source version differs from snapshot
+    local current_version
+    current_version=$(get_version)
+    if [ "$snap_version" != "$current_version" ]; then
+        echo "  Warning: snapshot is v$snap_version but source is v$current_version"
+        echo "  Some file checksums may not match"
+        echo ""
+    fi
+
+    # Set profile for reinstall
+    if [ -n "$snap_profile" ] && [ "$snap_profile" != "all" ]; then
+        PROFILE="$snap_profile"
+        PROFILE_FILE="$restore_source/profiles/${snap_profile}.json"
+        if [ ! -f "$PROFILE_FILE" ]; then
+            echo "  Warning: profile '$snap_profile' not found — installing all skills"
+            PROFILE=""
+            PROFILE_FILE=""
+        fi
+    fi
+
+    # Determine target
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    # Save the original SCRIPT_DIR, use snapshot source
+    local orig_script_dir="$SCRIPT_DIR"
+    SCRIPT_DIR="$restore_source"
+
+    # Reinstall using the standard flow
+    echo "Reinstalling CortexHawk components..."
+    mkdir -p "$TARGET"/{agents,commands,skills,hooks,modes,mcp}
+
+    # Use portable archive files if available, otherwise use source repo
+    if [ -n "$portable_files" ] && [ -d "$portable_files" ]; then
+        echo "  Using files from portable archive..."
+        cp -r "$portable_files/agents/"* "$TARGET/agents/" 2>/dev/null || true
+        cp -r "$portable_files/commands/"* "$TARGET/commands/" 2>/dev/null || true
+        cp -r "$portable_files/skills/"* "$TARGET/skills/" 2>/dev/null || true
+        cp -r "$portable_files/hooks/"* "$TARGET/hooks/" 2>/dev/null || true
+        cp -r "$portable_files/modes/"* "$TARGET/modes/" 2>/dev/null || true
+        cp -r "$portable_files/mcp/"* "$TARGET/mcp/" 2>/dev/null || true
+    else
+        cp -r "$SCRIPT_DIR/agents/"* "$TARGET/agents/" 2>/dev/null || true
+        cp -r "$SCRIPT_DIR/commands/"* "$TARGET/commands/" 2>/dev/null || true
+        copy_skills "$TARGET" "$PROFILE"
+        cp -r "$SCRIPT_DIR/hooks/"* "$TARGET/hooks/" 2>/dev/null || true
+        cp -r "$SCRIPT_DIR/modes/"* "$TARGET/modes/" 2>/dev/null || true
+        cp -r "$SCRIPT_DIR/mcp/"* "$TARGET/mcp/" 2>/dev/null || true
+    fi
+    chmod +x "$TARGET/hooks/"*.sh 2>/dev/null || true
+
+    # Restore settings.json from snapshot
+    if command -v python3 >/dev/null 2>&1; then
+        python3 -c "
+import json, sys
+with open('$snap_file') as f:
+    snap = json.load(f)
+settings = snap.get('settings')
+if settings is not None:
+    with open('$TARGET/settings.json', 'w') as f:
+        json.dump(settings, f, indent=2)
+        f.write('\n')
+    print('  Restored settings.json')
+"
+    else
+        echo "  Warning: python3 not found — settings.json not restored from snapshot"
+    fi
+
+    # Restore git-workflow.conf from snapshot
+    local branching commit_conv pr_pref auto_push
+    branching=$(grep '"BRANCHING"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    commit_conv=$(grep '"COMMIT_CONVENTION"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    pr_pref=$(grep '"PR_PREFERENCE"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    auto_push=$(grep '"AUTO_PUSH"' "$snap_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    if [ -n "$branching" ] || [ -n "$commit_conv" ] || [ -n "$pr_pref" ] || [ -n "$auto_push" ]; then
+        {
+            echo "BRANCHING=$branching"
+            echo "COMMIT_CONVENTION=$commit_conv"
+            echo "PR_PREFERENCE=$pr_pref"
+            echo "AUTO_PUSH=$auto_push"
+        } > "$TARGET/git-workflow.conf"
+        echo "  Restored git-workflow.conf (from git_workflow keys)"
+    fi
+
+    # Restore file_contents (snapshot v2) — overwrites git-workflow.conf if present
+    if grep -q '"file_contents"' "$snap_file" && command -v python3 >/dev/null 2>&1; then
+        python3 -c "
+import json, base64, sys, os
+with open('$snap_file') as f:
+    snap = json.load(f)
+contents = snap.get('file_contents', {})
+for filename, b64data in contents.items():
+    try:
+        data = base64.b64decode(b64data).decode('utf-8')
+        if filename == 'CLAUDE.md':
+            target_path = os.path.dirname('$TARGET') + '/CLAUDE.md'
+        else:
+            target_path = '$TARGET/' + filename
+        os.makedirs(os.path.dirname(target_path), exist_ok=True)
+        with open(target_path, 'w') as f:
+            f.write(data)
+        print(f'  Restored {filename} (from file_contents)')
+    except Exception as e:
+        print(f'  Warning: could not restore {filename}: {e}', file=sys.stderr)
+"
+    fi
+
+    # Write new manifest
+    write_manifest "$TARGET" "$PROFILE" "claude" false
+
+    # Verify checksums against snapshot
+    local verified=0 mismatched=0 missing=0
+    while IFS= read -r line; do
+        local file_relpath
+        file_relpath=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:\([^"]*\)".*/\1/')
+        local expected_checksum
+        expected_checksum=$(echo "$line" | sed 's/.*"sha256:\([^"]*\)".*/\1/')
+        [ -z "$file_relpath" ] || [ -z "$expected_checksum" ] && continue
+
+        local target_file="$TARGET/$file_relpath"
+        if [ ! -f "$target_file" ]; then
+            missing=$((missing + 1))
+        else
+            local actual_checksum
+            actual_checksum=$(compute_checksum "$target_file")
+            if [ "$actual_checksum" = "$expected_checksum" ]; then
+                verified=$((verified + 1))
+            else
+                mismatched=$((mismatched + 1))
+            fi
+        fi
+    done < <(grep '"sha256:' "$snap_file")
+
+    SCRIPT_DIR="$orig_script_dir"
+
+    echo ""
+    echo "Restore complete"
+    echo "  Verified:   $verified files match snapshot checksums"
+    [ "$mismatched" -gt 0 ] && echo "  Mismatched: $mismatched files differ (source version may differ from snapshot)"
+    [ "$missing" -gt 0 ] && echo "  Missing:    $missing files not found in source"
+    echo ""
+    echo "  To activate: exit your CLI (ctrl+c) and relaunch in this directory."
+
+    # Cleanup temp dir from portable archive
+    [ -n "$archive_tmp" ] && rm -rf "$archive_tmp"
+}
+
+# --- do_doctor() ---
+# Diagnose installation health
+do_doctor() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local ok=0 warn=0 err=0
+    _doc_ok()   { echo "  [OK]   $1"; ok=$((ok+1)); }
+    _doc_warn() { echo "  [WARN] $1"; warn=$((warn+1)); }
+    _doc_err()  { echo "  [ERR]  $1"; err=$((err+1)); }
+
+    # Header
+    local version="" profile="" target_cli_name=""
+    if [ -f "$TARGET/.cortexhawk-manifest" ]; then
+        version=$(grep -o '"version": "[^"]*"' "$TARGET/.cortexhawk-manifest" | head -1 | cut -d'"' -f4)
+        profile=$(grep -o '"profile": "[^"]*"' "$TARGET/.cortexhawk-manifest" | head -1 | cut -d'"' -f4)
+        target_cli_name=$(grep -o '"target": "[^"]*"' "$TARGET/.cortexhawk-manifest" | head -1 | cut -d'"' -f4)
+    fi
+    echo "CortexHawk Doctor"
+    echo "==================="
+    echo "  Installation: $TARGET"
+    echo "  Version:      ${version:-unknown}"
+    echo "  Profile:      ${profile:-unknown}"
+    echo "  Target:       ${target_cli_name:-claude}"
+    echo ""
+    echo "Checks:"
+
+    # 1. Manifest
+    if [ -f "$TARGET/.cortexhawk-manifest" ]; then
+        _doc_ok "Manifest present"
+    else
+        _doc_err "Manifest missing — run install.sh to create an installation"
+    fi
+
+    # 2. settings.json valid JSON
+    if [ -f "$TARGET/settings.json" ]; then
+        if python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$TARGET/settings.json" 2>/dev/null; then
+            _doc_ok "settings.json valid JSON"
+        else
+            _doc_err "settings.json invalid JSON"
+        fi
+    else
+        _doc_warn "settings.json not found"
+    fi
+
+    # 3. Component counts (compare installed vs source)
+    for comp in agents commands modes; do
+        local installed=0 source_count=0
+        installed=$(find "$TARGET/$comp" -name "*.md" -type f 2>/dev/null | wc -l)
+        source_count=$(find "$SCRIPT_DIR/$comp" -name "*.md" -type f 2>/dev/null | wc -l)
+        if [ "$installed" -eq "$source_count" ] 2>/dev/null; then
+            _doc_ok "$installed/$source_count $comp installed"
+        elif [ "$installed" -gt 0 ] 2>/dev/null; then
+            _doc_warn "$installed/$source_count $comp installed"
+        else
+            _doc_err "0/$source_count $comp installed"
+        fi
+    done
+
+    # 4. Skills (profile-dependent, just count what's there)
+    local skills_installed=0 skills_source=0
+    skills_installed=$(find "$TARGET/skills" -name "*.md" -type f 2>/dev/null | wc -l)
+    skills_source=$(find "$SCRIPT_DIR/skills" -name "*.md" -type f 2>/dev/null | wc -l)
+    if [ "$skills_installed" -gt 0 ] 2>/dev/null; then
+        _doc_ok "$skills_installed/$skills_source skills installed (profile: ${profile:-all})"
+    else
+        _doc_err "No skills installed"
+    fi
+
+    # 5. Hooks executable
+    local hooks_ok=0 hooks_total=0
+    for hook in "$TARGET/hooks/"*.sh; do
+        [ -f "$hook" ] || continue
+        hooks_total=$((hooks_total+1))
+        if [ -x "$hook" ]; then
+            hooks_ok=$((hooks_ok+1))
+        else
+            _doc_warn "Hook not executable: $(basename "$hook")"
+        fi
+    done
+    if [ "$hooks_total" -gt 0 ]; then
+        if [ "$hooks_ok" -eq "$hooks_total" ]; then
+            _doc_ok "$hooks_ok/$hooks_total hooks executable"
+        fi
+    else
+        _doc_warn "No hooks found"
+    fi
+
+    # 6. compose.yml vs settings.json coherence
+    if [ -f "$TARGET/../hooks/compose.yml" ] || [ -f "$SCRIPT_DIR/hooks/compose.yml" ]; then
+        _doc_ok "compose.yml present"
+    fi
+
+    # 7. MCP configs
+    if [ -d "$TARGET/mcp" ] && [ "$(find "$TARGET/mcp" -type f 2>/dev/null | wc -l)" -gt 0 ]; then
+        _doc_ok "MCP configs present"
+    elif [ -d "$TARGET/mcp" ]; then
+        _doc_warn "MCP directory exists but empty"
+    fi
+
+    # 8. docs/ workspace
+    local project_root
+    project_root="$(dirname "$TARGET")"
+    if [ -d "$project_root/docs" ]; then
+        _doc_ok "docs/ workspace exists"
+    else
+        _doc_warn "docs/ workspace missing"
+    fi
+
+    # 9. Broken symlinks in docs/plans/
+    local broken=0
+    if [ -d "$project_root/docs/plans" ]; then
+        while IFS= read -r link; do
+            [ -z "$link" ] && continue
+            _doc_warn "Broken symlink: $link"
+            broken=$((broken+1))
+        done < <(find "$project_root/docs/plans" -type l ! -exec test -e {} \; -print 2>/dev/null)
+        [ "$broken" -eq 0 ] && _doc_ok "No broken symlinks in docs/plans/"
+    fi
+
+    # 10. git-workflow.conf
+    if [ -f "$TARGET/git-workflow.conf" ]; then
+        _doc_ok "git-workflow.conf present"
+    else
+        _doc_warn "git-workflow.conf not found (run --init to configure)"
+    fi
+
+    # 11. CLAUDE.md at project root
+    if [ -f "$project_root/CLAUDE.md" ]; then
+        _doc_ok "CLAUDE.md present at project root"
+    else
+        _doc_warn "CLAUDE.md not found at project root"
+    fi
+
+    # 12. Version match source vs manifest
+    if [ -n "$version" ]; then
+        local source_version
+        source_version=$(get_version)
+        if [ "$version" = "$source_version" ]; then
+            _doc_ok "Version match: source $source_version = manifest $version"
+        else
+            _doc_warn "Version mismatch: source $source_version != manifest $version (run --update)"
+        fi
+    fi
+
+    # Summary
+    echo ""
+    echo "Summary: $ok OK, $warn WARN, $err ERR"
+
+    # Exit code: 1 if any errors
+    [ "$err" -gt 0 ] && exit 1
+    return 0
+}
+
+# --- do_uninstall() ---
+# Remove CortexHawk installation cleanly
+do_uninstall() {
+    local target_cli="${TARGET_CLI:-claude}"
+
+    # Determine target paths
+    local project_root
+    if [ "$GLOBAL" = true ]; then
+        project_root="$HOME"
+    else
+        project_root="$(pwd)"
+    fi
+
+    local target=""
+    local extra_dirs=""
+    case "$target_cli" in
+        claude) target="$project_root/.claude" ;;
+        kimi)   target="$project_root/.kimi" ;;
+        codex)  target="$project_root/.codex"; extra_dirs="$project_root/.agents" ;;
+        *)
+            echo "Error: unknown target '$target_cli'"
+            exit 1
+            ;;
+    esac
+
+    if [ ! -d "$target" ] || [ ! -f "$target/.cortexhawk-manifest" ]; then
+        echo "Error: no CortexHawk installation found at $target"
+        exit 1
+    fi
+
+    # Read manifest info
+    local version="" profile=""
+    version=$(grep -o '"version": "[^"]*"' "$target/.cortexhawk-manifest" 2>/dev/null | head -1 | cut -d'"' -f4)
+    profile=$(grep -o '"profile": "[^"]*"' "$target/.cortexhawk-manifest" 2>/dev/null | head -1 | cut -d'"' -f4)
+
+    echo "CortexHawk Uninstall"
+    echo "======================"
+    echo "  Target:   $target_cli"
+    echo "  Location: $target"
+    echo "  Version:  ${version:-unknown}"
+    echo "  Profile:  ${profile:-unknown}"
+    echo ""
+
+    # Inventory what will be removed
+    echo "Will remove:"
+    local components=(agents commands skills hooks modes mcp)
+    for comp in "${components[@]}"; do
+        if [ -d "$target/$comp" ]; then
+            local count
+            count=$(find "$target/$comp" -type f 2>/dev/null | wc -l | tr -d ' ')
+            echo "  - $target/$comp/ ($count files)"
+        fi
+    done
+    [ -f "$target/settings.json" ] && echo "  - $target/settings.json"
+    [ -f "$target/MCP-SETUP.md" ] && echo "  - $target/MCP-SETUP.md"
+    [ -f "$target/.cortexhawk-manifest" ] && echo "  - $target/.cortexhawk-manifest"
+    [ -f "$target/git-workflow.conf" ] && echo "  - $target/git-workflow.conf"
+    [ -n "$extra_dirs" ] && [ -d "$extra_dirs" ] && echo "  - $extra_dirs/"
+
+    # Check CLAUDE.md — only remove if matches template
+    local claude_md="$project_root/CLAUDE.md"
+    local remove_claude_md=false
+    if [ -f "$claude_md" ] && [ -f "$SCRIPT_DIR/CLAUDE.md" ]; then
+        local current_sum template_sum
+        current_sum=$(compute_checksum "$claude_md")
+        template_sum=$(compute_checksum "$SCRIPT_DIR/CLAUDE.md")
+        if [ "$current_sum" = "$template_sum" ]; then
+            echo "  - CLAUDE.md (matches template)"
+            remove_claude_md=true
+        fi
+    fi
+
+    # Check AGENTS.md — remove if generated by CortexHawk (Kimi/Codex targets)
+    local agents_md="$project_root/AGENTS.md"
+    local remove_agents_md=false
+    if [ -f "$agents_md" ] && grep -q "CortexHawk" "$agents_md" 2>/dev/null; then
+        case "$target_cli" in
+            kimi|codex)
+                echo "  - AGENTS.md (generated by CortexHawk)"
+                remove_agents_md=true
+                ;;
+        esac
+    fi
+
+    echo ""
+    echo "Will NOT remove:"
+    echo "  - $target/.cortexhawk-snapshots/ (preserved for rollback)"
+    echo "  - docs/ (user data)"
+    echo "  - .cortexhawk-team.yml (team config)"
+    echo ""
+
+    # Pre-uninstall snapshot (saved to project root, not inside target)
+    local snap_dir="$project_root/.cortexhawk-snapshots"
+    if [ "$FORCE_MODE" != true ]; then
+        printf "Create snapshot before uninstall? [Y/n] "
+        read -r snap_confirm </dev/tty 2>/dev/null || snap_confirm="y"
+        [ -z "$snap_confirm" ] && snap_confirm="y"
+    else
+        snap_confirm="y"
+    fi
+
+    if [[ "$snap_confirm" =~ ^[Yy] ]]; then
+        mkdir -p "$snap_dir"
+        local snap_name
+        snap_name=$(date +"%Y-%m-%d-%H%M%S")
+        # Copy manifest as snapshot (lightweight)
+        if [ -f "$target/.cortexhawk-manifest" ]; then
+            cp "$target/.cortexhawk-manifest" "$snap_dir/${snap_name}-pre-uninstall.json"
+            echo "  Snapshot saved: $snap_dir/${snap_name}-pre-uninstall.json"
+        fi
+    fi
+
+    # Confirm uninstall
+    if [ "$FORCE_MODE" != true ]; then
+        printf "Proceed with uninstall? [y/N] "
+        read -r confirm </dev/tty 2>/dev/null || confirm="n"
+        if [[ ! "$confirm" =~ ^[Yy] ]]; then
+            echo "Uninstall cancelled."
+            exit 0
+        fi
+    fi
+
+    echo ""
+
+    # Remove CortexHawk components
+    for comp in "${components[@]}"; do
+        if [ -d "$target/$comp" ]; then
+            rm -rf "$target/$comp"
+            echo "  Removed $target/$comp/"
+        fi
+    done
+
+    [ -f "$target/settings.json" ] && rm -f "$target/settings.json" && echo "  Removed $target/settings.json"
+    [ -f "$target/MCP-SETUP.md" ] && rm -f "$target/MCP-SETUP.md" && echo "  Removed $target/MCP-SETUP.md"
+    [ -f "$target/.cortexhawk-manifest" ] && rm -f "$target/.cortexhawk-manifest" && echo "  Removed $target/.cortexhawk-manifest"
+    [ -f "$target/git-workflow.conf" ] && rm -f "$target/git-workflow.conf" && echo "  Removed $target/git-workflow.conf"
+
+    # Extra dirs (codex .agents/)
+    if [ -n "$extra_dirs" ] && [ -d "$extra_dirs" ]; then
+        rm -rf "$extra_dirs"
+        echo "  Removed $extra_dirs/"
+    fi
+
+    # CLAUDE.md if matches template
+    if [ "$remove_claude_md" = true ]; then
+        rm -f "$claude_md"
+        echo "  Removed CLAUDE.md"
+    fi
+
+    # AGENTS.md if generated by CortexHawk
+    if [ "$remove_agents_md" = true ]; then
+        rm -f "$agents_md"
+        echo "  Removed AGENTS.md"
+    fi
+
+    # Clean empty target dir (but keep if snapshots exist inside)
+    if [ -d "$target" ]; then
+        # Keep if .cortexhawk-snapshots exists inside
+        local remaining
+        remaining=$(find "$target" -mindepth 1 -not -path "$target/.cortexhawk-snapshots*" 2>/dev/null | wc -l | tr -d ' ')
+        if [ "$remaining" -eq 0 ]; then
+            # Only snapshots left — keep them
+            echo "  Kept $target/.cortexhawk-snapshots/"
+        fi
+    fi
+
+    echo ""
+    echo "Uninstall complete."
+    if [ -f "$snap_dir/${snap_name}-pre-uninstall.json" ] 2>/dev/null; then
+        echo "  Rollback: bash install.sh --restore $snap_dir/${snap_name}-pre-uninstall.json"
+    fi
+}
+
+# --- do_list_hooks() ---
+do_list_hooks() {
+    local hooks_json="$SCRIPT_DIR/hooks/hooks.json"
+    local compose_file="$SCRIPT_DIR/hooks/compose.yml"
+    if [ ! -f "$hooks_json" ]; then
+        echo "Error: hooks.json not found"
+        exit 1
+    fi
+    echo "CortexHawk Hooks"
+    echo "================"
+    echo ""
+    printf "  %-20s %-14s %-8s %s\n" "Name" "Event" "Status" "Description"
+    printf "  %-20s %-14s %-8s %s\n" "----" "-----" "------" "-----------"
+    # Parse hooks.json with python3 for reliable JSON handling
+    python3 << PYEOF
+import json
+with open("$hooks_json") as f:
+    data = json.load(f)
+# Read compose.yml to detect disabled hooks (commented out)
+disabled = set()
+try:
+    with open("$compose_file") as f:
+        for line in f:
+            stripped = line.strip()
+            if stripped.startswith("# - "):
+                disabled.add(stripped[4:].strip())
+except FileNotFoundError:
+    pass
+for hook in data["hooks"]:
+    name = hook["name"]
+    event = hook["type"]
+    desc = hook["description"]
+    status = "OFF" if name in disabled else "ON"
+    print(f"  {name:<20} {event:<14} {status:<8} {desc}")
+PYEOF
+    echo ""
+    # Also show telemetry hooks not in hooks.json but in compose.yml
+    for extra in agent-analytics session-telemetry; do
+        if ! grep -q "\"$extra\"" "$hooks_json" 2>/dev/null; then
+            local event="PostToolUse"
+            [ "$extra" = "session-telemetry" ] && event="SessionEnd"
+            local status="ON"
+            grep -q "# - $extra" "$compose_file" 2>/dev/null && status="OFF"
+            printf "  %-20s %-14s %-8s %s\n" "$extra" "$event" "$status" "(telemetry hook)"
+        fi
+    done
+    echo ""
+    echo "Toggle: --enable-hook <name> | --disable-hook <name>"
+}
+
+# --- do_toggle_hook() ---
+do_toggle_hook() {
+    local hook_name="$1"
+    local action="$2"  # enable or disable
+    local compose_file="$SCRIPT_DIR/hooks/compose.yml"
+    if [ ! -f "$compose_file" ]; then
+        echo "Error: compose.yml not found"
+        exit 1
+    fi
+    # Verify hook exists in compose.yml (active or commented)
+    if ! grep -qE "^      - ${hook_name}$|^      # - ${hook_name}$" "$compose_file"; then
+        echo "Error: hook '$hook_name' not found in compose.yml"
+        echo "Run --list-hooks to see available hooks"
+        exit 1
+    fi
+    if [ "$action" = "disable" ]; then
+        if grep -q "^      # - ${hook_name}$" "$compose_file"; then
+            echo "Hook '$hook_name' is already disabled"
+            return 0
+        fi
+        sed -i "s/^      - ${hook_name}$/      # - ${hook_name}/" "$compose_file"
+        echo "Disabled hook: $hook_name"
+    else
+        if grep -q "^      - ${hook_name}$" "$compose_file"; then
+            echo "Hook '$hook_name' is already enabled"
+            return 0
+        fi
+        sed -i "s/^      # - ${hook_name}$/      - ${hook_name}/" "$compose_file"
+        echo "Enabled hook: $hook_name"
+    fi
+    # Regenerate settings.json if target exists
+    local target="${TARGET:-.claude}"
+    if [ -d "$target" ] && [ -f "$target/settings.json" ]; then
+        local hooks_json
+        hooks_json=$(generate_hooks_config "$compose_file" ".claude/hooks")
+        if [ -n "$hooks_json" ]; then
+            python3 << PYEOF
+import json
+with open('$target/settings.json') as f:
+    settings = json.load(f)
+settings['hooks'] = json.loads('''$hooks_json''')
+with open('$target/settings.json', 'w') as f:
+    json.dump(settings, f, indent=2)
+    f.write('\n')
+print('  Regenerated settings.json')
+PYEOF
+        fi
+    fi
+}
+
+# --- do_search_skills() ---
+# Search community skill registry for matching skills
+do_search_skills() {
+    local keyword="$1"
+
+    echo "CortexHawk Skill Search"
+    echo "========================"
+    echo "  Query: $keyword"
+    echo ""
+
+    # Strategy: SkillsMP API if key available, else local REGISTRY.md
+    if [ -n "${SKILLSMP_API_KEY:-}" ]; then
+        _search_skillsmp "$keyword"
+    else
+        _search_registry "$keyword"
+    fi
+    return 0
+}
+
+# --- SkillsMP API search (87k+ skills) ---
+_search_skillsmp() {
+    local keyword="$1"
+    local api_url="https://skillsmp.com/api/v1/skills/search"
+    echo "  Source: SkillsMP (87k+ skills)"
+    echo ""
+
+    local tmp_response
+    tmp_response=$(mktemp)
+    local http_code
+    http_code=$(curl -sS --max-time 15 -o "$tmp_response" -w "%{http_code}" \
+        -H "Authorization: Bearer $SKILLSMP_API_KEY" \
+        -H "Accept: application/json" \
+        "${api_url}?q=$(printf '%s' "$keyword" | sed 's/ /%20/g')&limit=15" 2>/dev/null) || http_code="000"
+
+    if [ "$http_code" != "200" ]; then
+        echo "  SkillsMP API error (HTTP $http_code) — falling back to local registry"
+        echo ""
+        rm -f "$tmp_response"
+        _search_registry "$keyword"
+        return 0
+    fi
+
+    # Parse JSON response with python3
+    python3 << PYEOF
+import json, sys
+try:
+    with open("$tmp_response") as f:
+        data = json.load(f)
+    container = data.get("data", {})
+    skills = container.get("skills", [])
+    pagination = container.get("pagination", {})
+    total = pagination.get("total", len(skills))
+    if not skills:
+        print("  No skills found matching '$keyword'")
+        print("")
+        print("  Try broader terms or check https://skillsmp.com")
+        sys.exit(0)
+    print(f"  Found {total} skill(s) (showing {len(skills)}):")
+    print("")
+    print(f"  {'Name':<28} {'Author':<18} {'Stars':<7} {'Description'}")
+    print(f"  {'----':<28} {'------':<18} {'-----':<7} {'-----------'}")
+    for s in skills:
+        name = s.get("name", "unknown")[:27]
+        author = s.get("author", "")[:17]
+        stars = s.get("stars", 0)
+        star_str = str(stars) if stars else "-"
+        desc = s.get("description", "")[:55]
+        print(f"  {name:<28} {author:<18} {star_str:<7} {desc}")
+    print("")
+    for s in skills:
+        url = s.get("githubUrl", "")
+        if url and "github.com" in url:
+            parts = url.replace("https://github.com/", "").split("/")
+            if len(parts) >= 2:
+                print(f"  Install: ./install.sh --add-skill {parts[0]}/{parts[1]}")
+                break
+    print(f"  Browse all: https://skillsmp.com/?q=$keyword")
+except Exception as e:
+    print(f"  Error parsing response: {e}")
+    print("  Falling back to local registry")
+PYEOF
+
+    rm -f "$tmp_response"
+}
+
+# --- Local REGISTRY.md search (fallback) ---
+_search_registry() {
+    local keyword="$1"
+    local registry_url="https://raw.githubusercontent.com/Spechawk94/CortexHawk/main/REGISTRY.md"
+    echo "  Source: local REGISTRY.md"
+    echo "  Tip: export SKILLSMP_API_KEY=sk_live_xxx for 87k+ skills via SkillsMP"
+    echo ""
+
+    local registry_file=""
+    if [ -f "$SCRIPT_DIR/REGISTRY.md" ]; then
+        registry_file="$SCRIPT_DIR/REGISTRY.md"
+    else
+        local tmp_file
+        tmp_file=$(mktemp)
+        if ! curl -sS --max-time 10 "$registry_url" > "$tmp_file" 2>/dev/null; then
+            echo "Error: could not reach skill registry"
+            rm -f "$tmp_file"
+            exit 1
+        fi
+        registry_file="$tmp_file"
+    fi
+
+    local results
+    results=$(grep -i "$keyword" "$registry_file" | grep '^|' | grep -v '^| Name' | grep -v '^|---' || true)
+
+    if [ -z "$results" ]; then
+        echo "  No skills found matching '$keyword'"
+        echo ""
+        echo "  Submit your skill: open a PR adding a row to REGISTRY.md"
+    else
+        local count
+        count=$(echo "$results" | wc -l | tr -d ' ')
+        echo "  Found $count skill(s):"
+        echo ""
+        echo "| Name | Category | Description | Install |"
+        echo "|---|---|---|---|"
+        echo "$results" | while IFS='|' read -r _ name category desc _ url _; do
+            name=$(echo "$name" | xargs)
+            category=$(echo "$category" | xargs)
+            desc=$(echo "$desc" | xargs)
+            url=$(echo "$url" | xargs)
+            printf "| %s | %s | %s | \`--add-skill %s\` |\n" "$name" "$category" "$desc" "$url"
+        done
+        echo ""
+        echo "Install with: ./install.sh --add-skill <url>"
+    fi
+
+    [ -n "${tmp_file:-}" ] && rm -f "$tmp_file" || true
+}
+
+# --- do_add_skill() ---
+# Install a community skill from GitHub
+do_add_skill() {
+    local url="$1"
+
+    # Normalize URL: user/repo → https://github.com/user/repo
+    # Also support file:// and local paths for testing
+    if [[ "$url" =~ ^/ ]]; then
+        # Local path
+        url="file://$url"
+    elif [[ ! "$url" =~ ^(https?|file):// ]]; then
+        url="https://github.com/$url"
+    fi
+
+    # Extract repo name for skill directory
+    local repo_name
+    repo_name=$(basename "$url" .git)
+
+    echo "CortexHawk Add Skill"
+    echo "====================="
+    echo "  Source: $url"
+    echo "  Skill:  $repo_name"
+    echo ""
+
+    # Determine target directory
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local skill_dir="$TARGET/skills/community/$repo_name"
+
+    # Check if already installed
+    if [ -d "$skill_dir" ]; then
+        echo "Error: skill '$repo_name' already installed at $skill_dir"
+        echo "Remove it first with: rm -rf $skill_dir"
+        exit 1
+    fi
+
+    # Clone to temp directory
+    local tmp_dir
+    tmp_dir=$(mktemp -d)
+    echo "  Cloning repository..."
+
+    if ! git clone --depth 1 --quiet "$url" "$tmp_dir/repo" 2>/dev/null; then
+        echo "Error: failed to clone $url"
+        echo "Check that the URL is correct and the repo is public"
+        rm -rf "$tmp_dir"
+        exit 1
+    fi
+
+    # Validate structure: must have SKILL.md
+    if [ ! -f "$tmp_dir/repo/SKILL.md" ]; then
+        echo "Error: invalid skill — SKILL.md not found"
+        echo "A valid CortexHawk skill must have a SKILL.md file"
+        rm -rf "$tmp_dir"
+        exit 1
+    fi
+
+    # Security warning if scripts present
+    if find "$tmp_dir/repo" -name "*.sh" -o -name "*.py" 2>/dev/null | grep -q .; then
+        echo "  Warning: this skill contains executable scripts"
+        echo "  Review them before use: $skill_dir/scripts/"
+    fi
+
+    # Create community directory if needed
+    mkdir -p "$TARGET/skills/community"
+
+    # Copy skill (exclude .git)
+    mkdir -p "$skill_dir"
+    find "$tmp_dir/repo" -mindepth 1 -maxdepth 1 ! -name '.git' -exec cp -r {} "$skill_dir/" \;
+
+    # Cleanup
+    rm -rf "$tmp_dir"
+
+    # Check requires: dependencies
+    local requires
+    requires=$(head -10 "$skill_dir/SKILL.md" | sed -n '/^---$/,/^---$/{ /^requires:/{ s/^requires: //; p; } }')
+    if [ -n "$requires" ]; then
+        local missing=""
+        for dep in $requires; do
+            if [ ! -d "$TARGET/skills/$dep" ]; then
+                missing="${missing:+$missing, }$dep"
+            fi
+        done
+        if [ -n "$missing" ]; then
+            echo "  Warning: missing dependencies: $missing"
+            echo "  Install them with: --add-skill or a profile that includes them"
+        fi
+    fi
+
+    echo ""
+    echo "Skill installed successfully!"
+    echo "  Location: $skill_dir"
+    echo ""
+    echo "Use the skill by referencing it in your prompts."
+}
+
+# --- parse_team_yaml() ---
+parse_team_yaml() {
+    local file="$1"
+    local current_section=""
+    TEAM_VERSION="" TEAM_PROFILE=""
+    TEAM_SKILLS="" TEAM_HOOKS="" TEAM_MODES=""
+    TEAM_GIT_BRANCHING="" TEAM_GIT_COMMIT_CONVENTION="" TEAM_GIT_PR_PREFERENCE="" TEAM_GIT_AUTO_PUSH=""
+
+    while IFS= read -r line; do
+        [[ "$line" =~ ^[[:space:]]*# ]] && continue
+        [[ "$line" =~ ^[[:space:]]*$ ]] && continue
+        # List item
+        if [[ "$line" =~ ^[[:space:]]*-[[:space:]]+(.*) ]]; then
+            local val="${BASH_REMATCH[1]}"
+            case "$current_section" in
+                skills) TEAM_SKILLS="${TEAM_SKILLS:+$TEAM_SKILLS$'\n'}$val" ;;
+                hooks) TEAM_HOOKS="${TEAM_HOOKS:+$TEAM_HOOKS$'\n'}$val" ;;
+                modes) TEAM_MODES="${TEAM_MODES:+$TEAM_MODES$'\n'}$val" ;;
+            esac
+            continue
+        fi
+        # Nested key under git_workflow
+        if [[ "$line" =~ ^[[:space:]]+([a-z_]+):[[:space:]]*(.*) ]] && [ "$current_section" = "git_workflow" ]; then
+            local key="${BASH_REMATCH[1]}" val="${BASH_REMATCH[2]//\"/}"
+            case "$key" in
+                branching) TEAM_GIT_BRANCHING="$val" ;;
+                commit_convention) TEAM_GIT_COMMIT_CONVENTION="$val" ;;
+                pr_preference) TEAM_GIT_PR_PREFERENCE="$val" ;;
+                auto_push) TEAM_GIT_AUTO_PUSH="$val" ;;
+            esac
+            continue
+        fi
+        # Top-level key
+        if [[ "$line" =~ ^([a-z_]+):[[:space:]]*(.*) ]]; then
+            local key="${BASH_REMATCH[1]}" val="${BASH_REMATCH[2]//\"/}"
+            current_section="$key"
+            case "$key" in
+                version) TEAM_VERSION="$val" ;;
+                profile) TEAM_PROFILE="$val" ;;
+            esac
+        fi
+    done < "$file"
+}
+
+# --- do_team_install() ---
+do_team_install() {
+    local team_file=".cortexhawk-team.yml"
+    local local_file=".cortexhawk-local.yml"
+
+    if [ ! -f "$team_file" ]; then
+        echo "Error: $team_file not found in $(pwd)"
+        echo "Create a .cortexhawk-team.yml file or use install.sh without --team"
+        exit 1
+    fi
+
+    echo "CortexHawk Team Install"
+    echo "========================="
+
+    # Parse team config
+    parse_team_yaml "$team_file"
+    echo "  Team config: $team_file (v$TEAM_VERSION)"
+
+    # Parse local overrides if present
+    if [ -f "$local_file" ]; then
+        local saved_profile="$TEAM_PROFILE" saved_skills="$TEAM_SKILLS"
+        local saved_hooks="$TEAM_HOOKS" saved_modes="$TEAM_MODES"
+        local saved_gb="$TEAM_GIT_BRANCHING" saved_gc="$TEAM_GIT_COMMIT_CONVENTION"
+        local saved_gp="$TEAM_GIT_PR_PREFERENCE" saved_ga="$TEAM_GIT_AUTO_PUSH"
+        parse_team_yaml "$local_file"
+        [ -z "$TEAM_PROFILE" ] && TEAM_PROFILE="$saved_profile"
+        [ -z "$TEAM_SKILLS" ] && TEAM_SKILLS="$saved_skills"
+        [ -z "$TEAM_HOOKS" ] && TEAM_HOOKS="$saved_hooks"
+        [ -z "$TEAM_MODES" ] && TEAM_MODES="$saved_modes"
+        [ -z "$TEAM_GIT_BRANCHING" ] && TEAM_GIT_BRANCHING="$saved_gb"
+        [ -z "$TEAM_GIT_COMMIT_CONVENTION" ] && TEAM_GIT_COMMIT_CONVENTION="$saved_gc"
+        [ -z "$TEAM_GIT_PR_PREFERENCE" ] && TEAM_GIT_PR_PREFERENCE="$saved_gp"
+        [ -z "$TEAM_GIT_AUTO_PUSH" ] && TEAM_GIT_AUTO_PUSH="$saved_ga"
+        echo "  Local overrides: $local_file"
+    fi
+
+    echo "  Profile: ${TEAM_PROFILE:-all}"
+    echo ""
+
+    # Generate temporary profile JSON from skills list
+    if [ -n "$TEAM_SKILLS" ]; then
+        local tmp_profile="/tmp/cortexhawk-team-$$.json"
+        printf '{\n  "name": "team",\n  "skills": [\n' > "$tmp_profile"
+        local first=true
+        while IFS= read -r skill; do
+            [ -z "$skill" ] && continue
+            if [ "$first" = true ]; then
+                printf '    "%s"' "$skill" >> "$tmp_profile"
+                first=false
+            else
+                printf ',\n    "%s"' "$skill" >> "$tmp_profile"
+            fi
+        done <<< "$TEAM_SKILLS"
+        printf '\n  ]\n}\n' >> "$tmp_profile"
+        PROFILE="team"
+        PROFILE_FILE="$tmp_profile"
+    elif [ -n "$TEAM_PROFILE" ] && [ "$TEAM_PROFILE" != "all" ]; then
+        PROFILE="$TEAM_PROFILE"
+        PROFILE_FILE="$SCRIPT_DIR/profiles/${TEAM_PROFILE}.json"
+        if [ ! -f "$PROFILE_FILE" ]; then
+            echo "  Warning: profile '$TEAM_PROFILE' not found — installing all skills"
+            PROFILE=""
+            PROFILE_FILE=""
+        fi
+    fi
+
+    # Run standard install
+    install_claude
+
+    # Filter hooks: remove those not in team list
+    if [ -n "$TEAM_HOOKS" ]; then
+        for hook_file in "$TARGET/hooks/"*; do
+            [ -f "$hook_file" ] || continue
+            local hook_name
+            hook_name=$(basename "$hook_file" | sed 's/\.[^.]*$//')
+            if ! echo "$TEAM_HOOKS" | grep -qx "$hook_name"; then
+                rm -f "$hook_file"
+            fi
+        done
+        local hook_count
+        hook_count=$(echo "$TEAM_HOOKS" | wc -l | tr -d ' ')
+        echo "  Hooks: kept $hook_count (team-specified)"
+    fi
+
+    # Filter modes: remove those not in team list
+    if [ -n "$TEAM_MODES" ]; then
+        for mode_file in "$TARGET/modes/"*; do
+            [ -f "$mode_file" ] || continue
+            local mode_name
+            mode_name=$(basename "$mode_file" .md)
+            if ! echo "$TEAM_MODES" | grep -qx "$mode_name"; then
+                rm -f "$mode_file"
+            fi
+        done
+        local mode_count
+        mode_count=$(echo "$TEAM_MODES" | wc -l | tr -d ' ')
+        echo "  Modes: kept $mode_count (team-specified)"
+    fi
+
+    # Write git-workflow.conf from team config
+    if [ -n "$TEAM_GIT_BRANCHING" ] || [ -n "$TEAM_GIT_COMMIT_CONVENTION" ] || [ -n "$TEAM_GIT_PR_PREFERENCE" ] || [ -n "$TEAM_GIT_AUTO_PUSH" ]; then
+        {
+            echo "BRANCHING=${TEAM_GIT_BRANCHING:-direct-main}"
+            echo "COMMIT_CONVENTION=${TEAM_GIT_COMMIT_CONVENTION:-conventional}"
+            echo "PR_PREFERENCE=${TEAM_GIT_PR_PREFERENCE:-never}"
+            echo "AUTO_PUSH=${TEAM_GIT_AUTO_PUSH:-false}"
+        } > "$TARGET/git-workflow.conf"
+        echo "  Git workflow: configured from team preset"
+    fi
+
+    # Update manifest after filtering
+    write_manifest "$TARGET" "${PROFILE:-all}" "claude" false
+
+    echo ""
+    echo "Team install complete."
+}
+
+# --- install_claude() ---
+install_claude() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "CortexHawk Dry Run (install)"
+        echo "=============================="
+        echo "  Target:  $TARGET"
+        echo "  Profile: ${PROFILE:-all}"
+        echo ""
+        echo "Would install:"
+        for comp in agents commands hooks modes mcp; do
+            local c; c=$(find "$SCRIPT_DIR/$comp" -type f 2>/dev/null | wc -l | tr -d ' ')
+            printf "  %-12s %s files\n" "$comp/" "$c"
+        done
+        local sc; sc=$(find "$SCRIPT_DIR/skills" -type f 2>/dev/null | wc -l | tr -d ' ')
+        printf "  %-12s %s files\n" "skills/" "$sc"
+        echo "  settings.json"
+        [ ! -f "$(pwd)/CLAUDE.md" ] && echo "  CLAUDE.md"
+        echo ""
+        echo "No files were modified (dry run)."
+        return
+    fi
+
+    echo "Installing for Claude Code to project: $TARGET"
+
+    mkdir -p "$TARGET"/{agents,commands,skills,hooks,modes,mcp}
+
+    cp -r "$SCRIPT_DIR/agents/"* "$TARGET/agents/" 2>/dev/null || true
+    # Copy agent personas from project root if present
+    local project_root
+    project_root="$(dirname "$TARGET")"
+    if [ -d "$project_root/.cortexhawk-agents" ]; then
+        cp -r "$project_root/.cortexhawk-agents/"*.md "$TARGET/agents/" 2>/dev/null || true
+        local persona_count
+        persona_count=$(find "$project_root/.cortexhawk-agents" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+        [ "$persona_count" -gt 0 ] && echo "  Loaded $persona_count agent persona(s) from .cortexhawk-agents/"
+    fi
+    cp -r "$SCRIPT_DIR/commands/"* "$TARGET/commands/" 2>/dev/null || true
+    copy_skills "$TARGET" "$PROFILE"
+    cp -r "$SCRIPT_DIR/hooks/"* "$TARGET/hooks/" 2>/dev/null || true
+    cp -r "$SCRIPT_DIR/modes/"* "$TARGET/modes/" 2>/dev/null || true
+    cp -r "$SCRIPT_DIR/mcp/"* "$TARGET/mcp/" 2>/dev/null || true
+
+    if [ ! -f "$TARGET/settings.json" ]; then
+        # Generate settings.json with hooks from compose.yml
+        local hooks_json
+        hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
+        if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
+            # Build settings.json with generated hooks
+            python3 -c "
+import json
+permissions = $(cat "$SCRIPT_DIR/settings.json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get('permissions',{})))")
+hooks = $hooks_json
+with open('$TARGET/settings.json', 'w') as f:
+    json.dump({'permissions': permissions, 'hooks': hooks}, f, indent=2)
+    f.write('\n')
+"
+            echo "  Generated settings.json from hooks/compose.yml"
+        else
+            cp "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
+        fi
+    else
+        echo "settings.json already exists — skipping (check manually for updates)"
+    fi
+
+    PROJECT_ROOT="$(dirname "$TARGET")"
+    if [ ! -f "$PROJECT_ROOT/CLAUDE.md" ]; then
+        cp "$SCRIPT_DIR/CLAUDE.md" "$PROJECT_ROOT/CLAUDE.md"
+    else
+        echo "CLAUDE.md already exists — skipping"
+    fi
+
+    # Git workflow config (interactive in --init, defaults otherwise)
+    if [ "$GLOBAL" = false ]; then
+        if [ "$INIT_MODE" = true ]; then
+            source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$PROJECT_ROOT" "$TARGET"
+        elif [ ! -f "$TARGET/git-workflow.conf" ]; then
+            # Apply sensible defaults without asking
+            GIT_BRANCHING="direct-main"
+            GIT_COMMIT_CONVENTION="conventional"
+            GIT_PR_PREFERENCE="on-demand"
+            GIT_AUTO_PUSH="after-commit"
+            GIT_WORK_BRANCH=""
+            source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$PROJECT_ROOT" "$TARGET"
+        fi
+    fi
+
+    chmod +x "$TARGET/hooks/"*.sh 2>/dev/null || true
+
+    # Write manifest for future updates
+    write_manifest "$TARGET" "$PROFILE" "claude" false
+
+    # Create docs/ workspace for agent outputs (local only)
+    if [ "$GLOBAL" = false ]; then
+        create_docs_workspace "$(dirname "$TARGET")"
+    fi
+
+    run_audit "$(dirname "$TARGET")"
+    update_gitignore "$(dirname "$TARGET")" ".claude"
+
+    echo ""
+    echo "CortexHawk installed successfully for Claude Code!"
+    echo ""
+    echo "  32 commands | 20 agents | 36 skills | 9 hooks | 7 modes"
+    echo ""
+    do_quickstart
+    echo ""
+    echo "  To activate: exit Claude Code (ctrl+c) and relaunch 'claude' in this directory."
+}
+
+# --- install_kimi() ---
+install_kimi() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.kimi"
+        echo "Installing for Kimi CLI globally to $TARGET"
+    else
+        TARGET="$(pwd)/.kimi"
+        echo "Installing for Kimi CLI to project: $TARGET"
+    fi
+
+    mkdir -p "$TARGET/skills"
+
+    # 1. Skills — direct copy (Kimi discovers .kimi/skills/ at project level)
+    echo "  Copying skills..."
+    if [ -d "$SCRIPT_DIR/skills" ]; then
+        copy_skills "$TARGET" "$PROFILE"
+    fi
+
+    # 2. Commands → Skills (invocation via /skill:cmd-name)
+    echo "  Converting commands to skills..."
+    for cmd_file in "$SCRIPT_DIR"/commands/*.md; do
+        [ -f "$cmd_file" ] || continue
+        local cmd_name
+        cmd_name=$(basename "$cmd_file" .md)
+        mkdir -p "$TARGET/skills/cmd-$cmd_name"
+        cp "$cmd_file" "$TARGET/skills/cmd-$cmd_name/SKILL.md"
+    done
+    local cmd_count
+    cmd_count=$(find "$TARGET/skills/cmd-"* -maxdepth 0 -type d 2>/dev/null | wc -l | tr -d ' ')
+    echo "  Converted $cmd_count commands to skills (invoke with /skill:cmd-name)"
+
+    # 3. Agents → Skills (full agent definitions, invocable via /skill:agent-name)
+    echo "  Converting agents to skills..."
+    local agent_count=0
+    for agent_file in "$SCRIPT_DIR"/agents/*.md; do
+        [ -f "$agent_file" ] || continue
+        local agent_name
+        agent_name=$(basename "$agent_file" .md)
+        mkdir -p "$TARGET/skills/agent-$agent_name"
+        cp "$agent_file" "$TARGET/skills/agent-$agent_name/SKILL.md"
+        agent_count=$((agent_count + 1))
+    done
+    echo "  Converted $agent_count agents to skills (invoke with /skill:agent-name)"
+
+    # 4. Modes → Skills via shared function
+    convert_modes_to_skills "$TARGET/skills" "modes/"
+
+    # 5. Hooks → Skills (manual invocation — Kimi has no lifecycle hooks)
+    echo "  Converting hooks to skills..."
+    local hooks_count=0
+    convert_hook_to_skill() {
+        local name="$1" desc="$2" content="$3"
+        mkdir -p "$TARGET/skills/hook-$name"
+        {
+            echo "---"
+            echo "name: hook-$name"
+            echo "description: $desc"
+            echo "---"
+            echo ""
+            echo "$content"
+        } > "$TARGET/skills/hook-$name/SKILL.md"
+        hooks_count=$((hooks_count + 1))
+    }
+
+    convert_hook_to_skill "self-review" "Review last changes for TODOs, secrets, debug artifacts" \
+"# Self-Review
+
+Review the files you just modified for:
+
+- [ ] TODO/FIXME/HACK/XXX markers
+- [ ] Hardcoded secrets, API keys, passwords, tokens
+- [ ] Debug statements (console.log, print(), breakpoint())
+- [ ] Temporary test code or commented-out blocks
+
+Flag any issues found and suggest fixes."
+
+    convert_hook_to_skill "file-guard" "Check that sensitive files are not being accessed" \
+"# File Guard
+
+NEVER read, edit, or write these files:
+
+- \`.env\`, \`.env.*\` — environment secrets
+- \`*.pem\`, \`*.key\`, \`*.p12\`, \`*.pfx\`, \`*.keystore\` — certificates/keys
+- \`*credentials*\`, \`*secret*\` — credential files
+- \`id_rsa\`, \`id_ed25519\`, \`.ssh/*\` — SSH keys
+
+If you are about to touch any of these, STOP and warn the user."
+
+    convert_hook_to_skill "commit-guard" "Validate conventional commit format and check for secrets" \
+"# Commit Guard
+
+Before committing, verify:
+
+1. **Commit format**: \`type(scope): description\`
+   - Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+2. **No secrets staged**: check staged files for API keys, passwords, tokens
+3. **No .env files staged**: never commit .env files
+
+If any check fails, warn and suggest a fix."
+
+    convert_hook_to_skill "dependency-check" "Alert when dependency files are modified" \
+"# Dependency Check
+
+If you modified any dependency file (package.json, requirements.txt, Cargo.toml, go.mod, Gemfile, pyproject.toml, pom.xml):
+
+- [ ] Verify the change is intentional
+- [ ] Check for version conflicts
+- [ ] Run the appropriate install command
+- [ ] Update lockfile if needed"
+
+    convert_hook_to_skill "test-reminder" "Remind to update tests for modified source files" \
+"# Test Reminder
+
+For each source file you modified, check:
+
+- [ ] Do tests exist for this file?
+- [ ] Do the tests cover the changes you made?
+- [ ] Should new test cases be added?
+
+If tests are missing or outdated, suggest what to test."
+
+    convert_hook_to_skill "branch-guard" "Check branch before pushing" \
+"# Branch Guard
+
+Before pushing, verify:
+
+- [ ] You are NOT on main/master (unless intended)
+- [ ] The branch name follows conventions
+- [ ] No force-push to protected branches"
+
+    echo "  Converted $hooks_count hooks to skills (invoke with /skill:hook-name)"
+
+    # 6. AGENTS.md — in project root (Kimi auto-injects as KIMI_AGENTS_MD)
+    echo "  Generating AGENTS.md..."
+    local agents_md
+    if [ "$GLOBAL" = true ]; then
+        agents_md="$HOME/AGENTS.md"
+    else
+        agents_md="$(pwd)/AGENTS.md"
+    fi
+    local commands_section
+    commands_section="## Commands"$'\n'$'\n'"Commands are installed as skills. Invoke with /skill:cmd-name:"$'\n'
+    for cmd_file in "$SCRIPT_DIR"/commands/*.md; do
+        [ -f "$cmd_file" ] || continue
+        local name desc
+        name=$(basename "$cmd_file" .md)
+        desc=$(grep '^description:' "$cmd_file" | sed 's/description: *//')
+        commands_section="${commands_section}"$'\n'"- \`/skill:cmd-$name\` — $desc"
+    done
+    generate_agents_md "$agents_md" "optimized agents, skills, commands, and modes for Kimi CLI." "$commands_section"
+
+    # 7. MCP — optional reference (don't install — crashes if servers missing)
+    if command -v npx &>/dev/null; then
+        echo "  MCP: creating setup reference..."
+        {
+            echo "# CortexHawk MCP Servers (Optional)"
+            echo ""
+            echo "Install manually:"
+            echo ""
+            for mcp_file in "$SCRIPT_DIR"/mcp/*.json; do
+                [ -f "$mcp_file" ] || continue
+                local server_name mcp_cmd mcp_args
+                server_name=$(basename "$mcp_file" .json)
+                mcp_cmd=$(grep '"command"' "$mcp_file" | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+                mcp_args=$(grep '"args"' "$mcp_file" | sed 's/.*"args"[[:space:]]*:[[:space:]]*\(\[.*\]\).*/\1/' | tr -d '[]"' | tr ',' ' ')
+                echo "  kimi mcp add --transport stdio $server_name -- $mcp_cmd $mcp_args"
+            done
+            echo ""
+            echo "List installed: kimi mcp list"
+            echo "Remove: kimi mcp remove <name>"
+        } > "$TARGET/MCP-SETUP.md"
+    else
+        echo "  MCP: npx not found — install Node.js for MCP servers (see MCP-SETUP.md)"
+        echo "# CortexHawk MCP Servers — requires Node.js (npx)" > "$TARGET/MCP-SETUP.md"
+    fi
+
+    # 8. Create docs/ workspace (local only)
+    if [ "$GLOBAL" = false ]; then
+        create_docs_workspace "$(dirname "$TARGET")"
+    fi
+
+    # Write manifest
+    write_manifest "$TARGET" "$PROFILE" "kimi" false
+
+    echo ""
+    echo "CortexHawk installed successfully for Kimi CLI!"
+    echo ""
+    echo "Available: $agent_count agents, 36 skills, $cmd_count commands, 7 modes, $hooks_count hooks (all as skills)"
+    echo ""
+    echo "Agents: /skill:agent-planner, /skill:agent-reviewer, etc."
+    echo "Commands: /skill:cmd-plan, /skill:cmd-build, /skill:cmd-test, etc."
+    echo "Modes: /skill:modes/fast, /skill:modes/research, etc."
+    echo "Hooks: /skill:hook-self-review, /skill:hook-file-guard, etc."
+    echo "MCP: see .kimi/MCP-SETUP.md for optional server install"
+
+    run_audit "$(dirname "$TARGET")"
+    update_gitignore "$(dirname "$TARGET")" ".kimi"
+
+    # Local install: auto-configure KIMI_SHARE_DIR for local sessions/config
+    if [ "$GLOBAL" = false ]; then
+        local project_root
+        project_root="$(pwd)"
+        local envrc="$project_root/.envrc"
+        local share_export="export KIMI_SHARE_DIR=\"$project_root/.kimi\""
+
+        echo ""
+        echo "  Skills are auto-discovered from .kimi/skills/ (no action needed)."
+
+        # Check if KIMI_SHARE_DIR already configured
+        if grep -q "KIMI_SHARE_DIR" "$envrc" 2>/dev/null; then
+            green "  KIMI_SHARE_DIR already in .envrc"
+        elif command -v direnv &>/dev/null; then
+            # direnv available — auto-create .envrc
+            echo "$share_export" >> "$envrc"
+            direnv allow "$project_root" 2>/dev/null
+            green "  Created .envrc with KIMI_SHARE_DIR (direnv detected)"
+            # Add .envrc to gitignore if not already there
+            if [ -f "$project_root/.gitignore" ] && ! grep -qx ".envrc" "$project_root/.gitignore" 2>/dev/null; then
+                echo ".envrc" >> "$project_root/.gitignore"
+            fi
+        else
+            # No direnv — create .envrc anyway + suggest manual source
+            echo "$share_export" >> "$envrc"
+            yellow "  Created .envrc with KIMI_SHARE_DIR"
+            echo "  To activate: source .envrc (or install direnv for auto-load)"
+            if [ -f "$project_root/.gitignore" ] && ! grep -qx ".envrc" "$project_root/.gitignore" 2>/dev/null; then
+                echo ".envrc" >> "$project_root/.gitignore"
+            fi
+        fi
+    fi
+
+    echo ""
+    echo "  To activate: exit Kimi (ctrl+d) and relaunch 'kimi' in this directory."
+}
+
+# --- do_test_hooks() ---
+do_test_hooks() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local hooks_dir="$TARGET/hooks"
+    if [ ! -d "$hooks_dir" ]; then
+        echo "Error: no hooks directory at $hooks_dir"
+        exit 1
+    fi
+
+    echo "CortexHawk Hook Test"
+    echo "======================"
+    echo "  Hooks: $hooks_dir"
+    echo ""
+
+    local ok=0 fail=0
+    local tmpfile="/tmp/.cortexhawk-hooktest-$$"
+    echo "test file content" > "$tmpfile"
+
+    for hook in "$hooks_dir"/*.sh; do
+        [ -f "$hook" ] || continue
+        local name
+        name=$(basename "$hook" .sh)
+
+        # Skip non-hook files and codex-dispatcher (requires jq + Codex payload)
+        [ "$name" = "codex-dispatcher" ] && continue
+        case "$name" in compose*|hooks*) continue ;; esac
+
+        # Generate synthetic input based on hook type
+        local input=""
+        case "$name" in
+            file-guard|self-review|dependency-check|test-reminder|agent-analytics)
+                input="{\"session_id\":\"test\",\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"$tmpfile\"}}"
+                ;;
+            branch-guard|commit-guard)
+                input='{"session_id":"test","tool_name":"Bash","tool_input":{"command":"echo test"}}'
+                ;;
+            session-telemetry)
+                input='{"session_id":"test-hook-check"}'
+                ;;
+            session-start)
+                input=""
+                ;;
+            *)
+                input=""
+                ;;
+        esac
+
+        # Execute hook with timeout
+        local output exit_code
+        if [ -n "$input" ]; then
+            output=$(echo "$input" | timeout 10 bash "$hook" 2>&1)
+            exit_code=$?
+        else
+            output=$(timeout 10 bash "$hook" < /dev/null 2>&1)
+            exit_code=$?
+        fi
+
+        # Report — exit 0=OK, exit 2=BLOCK (legitimate), 124=timeout, other=FAIL
+        if [ "$exit_code" -eq 0 ]; then
+            if [ -n "$output" ]; then
+                local first_line
+                first_line=$(echo "$output" | head -1 | cut -c1-60)
+                printf "  [OK]   %-25s %s\n" "$name" "$first_line"
+            else
+                printf "  [OK]   %s\n" "$name"
+            fi
+            ok=$((ok + 1))
+        elif [ "$exit_code" -eq 2 ]; then
+            local block_line
+            block_line=$(echo "$output" | head -1 | cut -c1-60)
+            printf "  [BLOCK] %-24s %s\n" "$name" "$block_line"
+            ok=$((ok + 1))
+        elif [ "$exit_code" -eq 124 ]; then
+            printf "  [FAIL] %-25s timeout (>10s)\n" "$name"
+            fail=$((fail + 1))
+        else
+            local err_line
+            err_line=$(echo "$output" | head -1 | cut -c1-60)
+            printf "  [FAIL] %-25s exit %d: %s\n" "$name" "$exit_code" "$err_line"
+            fail=$((fail + 1))
+        fi
+    done
+
+    rm -f "$tmpfile"
+
+    echo ""
+    echo "Summary: $ok OK, $fail FAIL"
+    [ "$fail" -gt 0 ] && exit 1
+    exit 0
+}
+
+# --- do_quickstart() ---
+do_quickstart() {
+    echo ""
+    echo "CortexHawk Quick Start"
+    echo "========================"
+    echo ""
+    echo "  5 things to try right now:"
+    echo ""
+    echo "  1. /check           — pre-commit quality gate (lint + test + scan → GO/NO-GO)"
+    echo "  2. /chain default   — full pipeline: plan → build → test → review"
+    echo "  3. /pulse           — project health dashboard with agent analytics"
+    echo "  4. /context set db=postgres — share persistent context with all 20 agents"
+    echo "  5. --search react   — discover 87k+ community skills via SkillsMP"
+    echo ""
+    echo "  Other essentials:"
+    echo "    /plan <feature>   — break a feature into tasks"
+    echo "    /scan             — full security audit"
+    echo "    /task #N          — execute a backlog item end-to-end"
+    echo "    /brainstorm <topic> — structured ideation session"
+    echo ""
+    echo "  Full docs: README.md | All commands: /help"
+    echo ""
+}
+
+# --- do_stats() ---
+do_stats() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local manifest="$TARGET/.cortexhawk-manifest"
+    if [ ! -f "$manifest" ]; then
+        echo "Error: no CortexHawk installation found at $TARGET"
+        echo "  Run ./install.sh first."
+        exit 1
+    fi
+
+    local version profile target_cli install_date update_date
+    version=$(grep '"version"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    profile=$(grep '"profile"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    target_cli=$(grep '"target"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    update_date=$(grep '"update_date"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    # Count components from source
+    local skills_count agents_count commands_count modes_count hooks_count packs_count
+    skills_count=$(find "$SCRIPT_DIR/skills" -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+    agents_count=$(find "$SCRIPT_DIR/agents" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    commands_count=$(find "$SCRIPT_DIR/commands" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    modes_count=$(find "$SCRIPT_DIR/modes" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    hooks_count=$(find "$TARGET/hooks" -name "*.sh" ! -name "codex-*" 2>/dev/null | wc -l | tr -d ' ')
+    packs_count=$(grep -c '^| [a-z]' "$SCRIPT_DIR/PACKS.md" 2>/dev/null || echo "0")
+
+    # Count personas
+    local personas_count=0
+    if [ -d ".cortexhawk-agents" ]; then
+        personas_count=$(find ".cortexhawk-agents" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    fi
+
+    # Active hooks from compose.yml
+    local active_hooks=0 disabled_hooks=0
+    local compose="$TARGET/hooks/compose.yml"
+    if [ -f "$compose" ]; then
+        active_hooks=$(grep -c '^ *- ' "$compose" 2>/dev/null || echo "0")
+        disabled_hooks=$(grep -c '^ *# *- ' "$compose" 2>/dev/null || echo "0")
+    fi
+
+    # SkillsMP status
+    local skillsmp_status="not configured"
+    if [ -n "${SKILLSMP_API_KEY:-}" ]; then
+        skillsmp_status="connected (87k+ skills)"
+    fi
+
+    # Snapshots count
+    local snapshots_count=0
+    local snapshots_dir="$TARGET/.cortexhawk-snapshots"
+    if [ -d "$snapshots_dir" ]; then
+        snapshots_count=$(find "$snapshots_dir" -name "*.json" 2>/dev/null | wc -l | tr -d ' ')
+    fi
+
+    echo ""
+    echo "CortexHawk Installation Stats"
+    echo "==============================="
+    printf "  %-14s %s\n" "Version:" "$version"
+    printf "  %-14s %s\n" "Target:" "$target_cli"
+    printf "  %-14s %s\n" "Profile:" "$profile"
+    printf "  %-14s %s\n" "Skills:" "$skills_count installed"
+    printf "  %-14s %s active, %s disabled\n" "Hooks:" "$active_hooks" "$disabled_hooks"
+    printf "  %-14s %s\n" "Agents:" "$agents_count$([ "$personas_count" -gt 0 ] && echo " + $personas_count personas")"
+    printf "  %-14s %s\n" "Commands:" "$commands_count"
+    printf "  %-14s %s\n" "Modes:" "$modes_count"
+    printf "  %-14s %s available\n" "Packs:" "$packs_count"
+    printf "  %-14s %s\n" "SkillsMP:" "$skillsmp_status"
+    printf "  %-14s %s\n" "Last update:" "${update_date%T*}"
+    printf "  %-14s %s saved\n" "Snapshots:" "$snapshots_count"
+    echo ""
+}
+
+# --- do_check_update() ---
+do_check_update() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local manifest="$TARGET/.cortexhawk-manifest"
+    if [ ! -f "$manifest" ]; then
+        echo "Error: no CortexHawk installation found at $TARGET"
+        echo "  Run ./install.sh first."
+        exit 1
+    fi
+
+    local installed_version
+    installed_version=$(grep '"version"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local update_date
+    update_date=$(grep '"update_date"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    echo ""
+    echo "CortexHawk Update Check"
+    echo "========================="
+    echo "  Installed: v$installed_version (updated ${update_date%T*})"
+
+    # Fetch latest version from source
+    local source_type
+    source_type=$(detect_source_type)
+    local latest_version=""
+    local changelog_path="$SCRIPT_DIR/CHANGELOG.md"
+
+    if [ "$source_type" = "git" ]; then
+        echo "  Checking for updates..."
+        git -C "$SCRIPT_DIR" fetch --quiet 2>/dev/null || true
+
+        # Check if local is behind remote
+        local local_hash remote_hash
+        local_hash=$(git -C "$SCRIPT_DIR" rev-parse HEAD 2>/dev/null)
+        remote_hash=$(git -C "$SCRIPT_DIR" rev-parse origin/main 2>/dev/null || echo "$local_hash")
+
+        if [ "$local_hash" = "$remote_hash" ]; then
+            latest_version="$installed_version"
+        else
+            # Get version from remote CHANGELOG
+            latest_version=$(git -C "$SCRIPT_DIR" show origin/main:CHANGELOG.md 2>/dev/null | grep -m1 '## \[' | sed 's/.*\[\([^]]*\)\].*/\1/')
+            [ -z "$latest_version" ] && latest_version="$installed_version"
+        fi
+    else
+        latest_version=$(get_version)
+    fi
+
+    printf "  %-10s v%s\n" "Latest:" "$latest_version"
+    echo ""
+
+    if [ "$installed_version" = "$latest_version" ]; then
+        echo "  You're up to date!"
+        echo ""
+        exit 0
+    fi
+
+    # Show what changed between installed and latest
+    echo "  What's new since v$installed_version:"
+    echo "  ─────────────────────────────────"
+
+    # Extract changelog entries between installed version and latest
+    local in_section=false
+    local stop_pattern="## \\[$installed_version\\]"
+    while IFS= read -r line; do
+        if [ "$in_section" = false ]; then
+            if echo "$line" | grep -q '^## \['; then
+                in_section=true
+            fi
+            [ "$in_section" = false ] && continue
+        fi
+        # Stop when we reach the installed version
+        if echo "$line" | grep -q "$stop_pattern"; then
+            break
+        fi
+        # Skip empty lines at the start
+        [ -z "$line" ] && continue
+        # Print changelog lines with indent
+        echo "  $line"
+    done < "$changelog_path"
+
+    echo ""
+    echo "  To update: ./install.sh --update"
+    echo "  Preview:   ./install.sh --update --dry-run"
+    echo ""
+}
+
+# --- do_publish_skill() ---
+do_publish_skill() {
+    local skill_path="$1"
+
+    # Resolve to absolute path
+    if [[ ! "$skill_path" =~ ^/ ]]; then
+        skill_path="$(pwd)/$skill_path"
+    fi
+
+    # Validate: directory exists
+    if [ ! -d "$skill_path" ]; then
+        echo "Error: directory not found: $skill_path"
+        exit 1
+    fi
+
+    # Validate: SKILL.md exists
+    local skill_md="$skill_path/SKILL.md"
+    if [ ! -f "$skill_md" ]; then
+        echo "Error: no SKILL.md found in $skill_path"
+        echo "  A valid skill must have a SKILL.md with frontmatter (name, description, category)"
+        exit 1
+    fi
+
+    # Extract metadata from SKILL.md frontmatter
+    local skill_name skill_desc skill_category
+    skill_name=$(sed -n '/^---$/,/^---$/{ /^name:/{ s/^name: *//; p; } }' "$skill_md")
+    skill_desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$skill_md")
+    skill_category=$(sed -n '/^---$/,/^---$/{ /^category:/{ s/^category: *//; p; } }' "$skill_md" || true)
+
+    if [ -z "$skill_name" ]; then
+        echo "Error: SKILL.md missing 'name' in frontmatter"
+        exit 1
+    fi
+    if [ -z "$skill_desc" ]; then
+        echo "Error: SKILL.md missing 'description' in frontmatter"
+        exit 1
+    fi
+
+    # Check gh CLI
+    if ! command -v gh &>/dev/null; then
+        echo "Error: GitHub CLI (gh) is required for --publish-skill"
+        echo "  Install: https://cli.github.com/"
+        exit 1
+    fi
+
+    if ! gh auth status &>/dev/null; then
+        echo "Error: not logged in to GitHub"
+        echo "  Run: gh auth login"
+        exit 1
+    fi
+
+    local gh_user
+    gh_user=$(gh api user --jq '.login' 2>/dev/null)
+    local repo_name="cortexhawk-skill-${skill_name}"
+
+    echo ""
+    echo "CortexHawk Publish Skill"
+    echo "========================="
+    echo "  Skill:       $skill_name"
+    echo "  Description: $skill_desc"
+    echo "  Category:    ${skill_category:-unspecified}"
+    echo "  Source:       $skill_path"
+    echo ""
+    echo "  Will create:  github.com/$gh_user/$repo_name"
+    echo ""
+    read -r -p "Proceed? [Y/n]: " confirm
+    case "$confirm" in
+        [nN]*) echo "Cancelled."; exit 0 ;;
+    esac
+
+    # Create GitHub repo
+    echo ""
+    echo "  Creating repository..."
+    if gh repo view "$gh_user/$repo_name" &>/dev/null; then
+        echo "  Repository already exists: $gh_user/$repo_name"
+        echo "  Pushing latest files..."
+    else
+        gh repo create "$repo_name" --public --description "CortexHawk skill: $skill_desc" --clone=false
+    fi
+
+    # Prepare temp directory with git
+    local tmp_dir
+    tmp_dir=$(mktemp -d)
+    cp -r "$skill_path"/* "$tmp_dir/" 2>/dev/null || true
+    cp -r "$skill_path"/.[!.]* "$tmp_dir/" 2>/dev/null || true
+
+    # Add README if not present
+    if [ ! -f "$tmp_dir/README.md" ]; then
+        printf '# %s\n\n%s\n\nA [CortexHawk](https://github.com/Spechawk94/CortexHawk) skill.\n\n## Install\n\n```bash\n./install.sh --add-skill %s/%s\n```\n' \
+            "$skill_name" "$skill_desc" "$gh_user" "$repo_name" > "$tmp_dir/README.md"
+    fi
+
+    # Init git and push
+    cd "$tmp_dir"
+    git init --quiet
+    git add -A
+    git commit --quiet -m "feat: publish $skill_name skill"
+    git branch -M main
+    git remote add origin "https://github.com/$gh_user/$repo_name.git"
+    git push -u origin main --force --quiet 2>/dev/null
+    cd - >/dev/null
+
+    # Cleanup
+    rm -rf "$tmp_dir"
+
+    echo "  Published to: https://github.com/$gh_user/$repo_name"
+    echo ""
+    echo "  Others can install with:"
+    echo "    ./install.sh --add-skill $gh_user/$repo_name"
+    echo ""
+
+    # Notify SkillsMP if API key is available
+    if [ -n "${SKILLSMP_API_KEY:-}" ]; then
+        echo "  Notifying SkillsMP for indexation..."
+        local response
+        response=$(curl -s -w "%{http_code}" -o /dev/null \
+            -X POST "https://skillsmp.com/api/v1/skills/submit" \
+            -H "Authorization: Bearer $SKILLSMP_API_KEY" \
+            -H "Content-Type: application/json" \
+            -d "{\"github_url\": \"https://github.com/$gh_user/$repo_name\", \"name\": \"$skill_name\", \"description\": \"$skill_desc\"}" \
+            2>/dev/null || echo "000")
+        if [ "$response" = "200" ] || [ "$response" = "201" ]; then
+            echo "  SkillsMP: submitted for indexation"
+        else
+            echo "  SkillsMP: notification failed (HTTP $response) — skill is still published on GitHub"
+        fi
+    else
+        echo "  Tip: set SKILLSMP_API_KEY in .env to auto-submit for indexation"
+    fi
+    echo ""
+}
+
+# --- do_demo() ---
+do_demo() {
+    local demo_dir="/tmp/cortexhawk-demo-$$"
+    mkdir -p "$demo_dir"
+
+    echo ""
+    echo "CortexHawk Demo"
+    echo "================="
+    echo "  Creating sandbox project at: $demo_dir"
+    echo ""
+
+    # --- 1. Create a mini Express.js project ---
+    cat > "$demo_dir/package.json" << 'PKGJSON'
+{
+  "name": "demo-app",
+  "version": "1.0.0",
+  "description": "CortexHawk demo project",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "echo \"no tests yet\" && exit 1"
+  },
+  "dependencies": {
+    "express": "^4.18.0"
+  }
+}
+PKGJSON
+
+    mkdir -p "$demo_dir/src"
+
+    # Main server file — has a SQL injection vulnerability (intentional)
+    cat > "$demo_dir/src/index.js" << 'INDEXJS'
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+// BUG: missing error handling on port binding
+const PORT = process.env.PORT || 3000;
+
+// VULN: SQL injection — user input directly in query
+app.get('/users', (req, res) => {
+  const name = req.query.name;
+  const query = `SELECT * FROM users WHERE name = '${name}'`;
+  // db.query(query) would execute here
+  res.json({ query });
+});
+
+// VULN: no input validation
+app.post('/login', (req, res) => {
+  const { username, password } = req.body;
+  if (username === 'admin' && password === 'admin123') {
+    res.json({ token: 'hardcoded-secret-token' });
+  } else {
+    res.status(401).json({ error: 'Invalid credentials' });
+  }
+});
+
+// TODO: add proper authentication middleware
+// TODO: add rate limiting
+
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+INDEXJS
+
+    # A utility with a bug
+    cat > "$demo_dir/src/utils.js" << 'UTILSJS'
+// BUG: off-by-one error in pagination
+function paginate(items, page, perPage) {
+  const start = page * perPage;  // should be (page - 1) * perPage
+  const end = start + perPage;
+  return {
+    data: items.slice(start, end),
+    total: items.length,
+    page,
+    totalPages: Math.ceil(items.length / perPage)
+  };
+}
+
+// BUG: doesn't handle negative numbers
+function formatPrice(cents) {
+  return '$' + (cents / 100).toFixed(2);
+}
+
+module.exports = { paginate, formatPrice };
+UTILSJS
+
+    # --- 2. Git init ---
+    cd "$demo_dir"
+    git init --quiet
+    echo "node_modules/" > .gitignore
+    echo ".env" >> .gitignore
+    git add -A
+    git commit --quiet -m "Initial commit: Express.js demo app"
+    cd - > /dev/null
+
+    # --- 3. Install CortexHawk ---
+    echo "  Installing CortexHawk..."
+    (cd "$demo_dir" && bash "$SCRIPT_DIR/install.sh" --no-scan --profile fullstack 2>&1 | grep -E "^(CortexHawk|  [0-9])" || true)
+
+    echo ""
+    echo "  Demo project ready!"
+    echo ""
+    echo "  ┌─────────────────────────────────────────────────────┐"
+    echo "  │  cd $demo_dir"
+    echo "  │  claude                                             │"
+    echo "  │                                                     │"
+    echo "  │  Then try:                                          │"
+    echo "  │    /scan          — find the SQL injection + vulns  │"
+    echo "  │    /debug         — find the off-by-one bug         │"
+    echo "  │    /check         — pre-commit quality gate         │"
+    echo "  │    /test          — generate missing tests          │"
+    echo "  │    /pulse         — project health dashboard        │"
+    echo "  │    /plan add auth — plan an auth system             │"
+    echo "  │                                                     │"
+    echo "  │  The project has intentional bugs and vulns         │"
+    echo "  │  for you to discover with CortexHawk agents.       │"
+    echo "  └─────────────────────────────────────────────────────┘"
+    echo ""
+    echo "  Cleanup when done: rm -rf $demo_dir"
+    echo ""
+}
+
+# --- Dispatcher ---
+if [ "$DEMO_MODE" = true ]; then
+    do_demo
+    exit 0
+elif [ "$CHECK_UPDATE_MODE" = true ]; then
+    do_check_update
+elif [ -n "$PUBLISH_SKILL_PATH" ]; then
+    do_publish_skill "$PUBLISH_SKILL_PATH"
+    exit 0
+elif [ "$STATS_MODE" = true ]; then
+    do_stats
+    exit 0
+elif [ "$QUICKSTART_MODE" = true ]; then
+    do_quickstart
+    exit 0
+elif [ "$TEST_HOOKS_MODE" = true ]; then
+    do_test_hooks
+elif [ "$UNINSTALL_MODE" = true ]; then
+    do_uninstall
+elif [ "$DOCTOR_MODE" = true ]; then
+    do_doctor
+elif [ "$SNAPSHOTS_LIST" = true ]; then
+    do_snapshots_list
+elif [ "$EXPORT_TEAM" = true ]; then
+    do_export_team
+elif [ "$DIFF_MODE" = true ]; then
+    if [ -n "$DIFF_FILE2" ]; then
+        do_diff_semantic "$DIFF_FILE" "$DIFF_FILE2"
+    else
+        do_diff
+    fi
+elif [ "$SNAPSHOT_MODE" = true ]; then
+    do_snapshot
+elif [ "$RESTORE_MODE" = true ]; then
+    do_restore "$SNAPSHOT_FILE"
+elif [ "$LIST_HOOKS" = true ]; then
+    do_list_hooks
+elif [ -n "$ENABLE_HOOK" ]; then
+    do_toggle_hook "$ENABLE_HOOK" "enable"
+elif [ -n "$DISABLE_HOOK" ]; then
+    do_toggle_hook "$DISABLE_HOOK" "disable"
+elif [ -n "$SEARCH_KEYWORD" ]; then
+    do_search_skills "$SEARCH_KEYWORD"
+elif [ -n "$ADD_SKILL_URL" ]; then
+    do_add_skill "$ADD_SKILL_URL"
+elif [ "$TEAM_MODE" = true ]; then
+    do_team_install
+elif [ "$UPDATE_MODE" = true ]; then
+    do_update
+else
+    echo "CortexHawk Installer"
+    echo "====================="
+
+    case "$TARGET_CLI" in
+        claude)
+            install_claude
+            ;;
+        kimi)
+            install_kimi
+            ;;
+        codex)
+            source "$SCRIPT_DIR/scripts/install-codex.sh"
+            install_codex
+            ;;
+        auto)
+            local detected
+            detected=$(detect_installed_clis)
+            if [ -z "$detected" ]; then
+                echo "Error: no supported CLI found (claude, kimi, codex)"
+                echo "Install at least one CLI tool, or use --target claude"
+                exit 1
+            fi
+            echo "Auto-detected CLIs: $detected"
+            echo ""
+            local auto_count=0
+            for cli in $detected; do
+                [ $auto_count -gt 0 ] && echo "" && echo "---" && echo ""
+                case "$cli" in
+                    claude) install_claude ;;
+                    kimi)   install_kimi ;;
+                    codex)  source "$SCRIPT_DIR/scripts/install-codex.sh"; install_codex ;;
+                esac
+                auto_count=$((auto_count + 1))
+            done
+            echo ""
+            echo "============================="
+            echo "Installed for $auto_count target(s): $detected"
+            echo "  To activate: exit your CLI(s) and relaunch in this directory."
+            ;;
+        all)
+            echo "Installing for all supported CLIs..."
+            echo ""
+            install_claude
+            echo ""
+            echo "---"
+            echo ""
+            install_kimi
+            echo ""
+            echo "---"
+            echo ""
+            source "$SCRIPT_DIR/scripts/install-codex.sh"
+            install_codex
+            echo ""
+            echo "============================="
+            echo "All targets installed: claude, kimi, codex"
+            echo "  To activate: exit your CLI(s) (ctrl+c) and relaunch in this directory."
+            ;;
+        *)
+            echo "Error: unknown target '$TARGET_CLI'"
+            echo "Supported targets: claude, kimi, codex, auto, all"
+            exit 1
+            ;;
+    esac
+fi
+
+# --- Cleanup temp files ---
+if [ -n "$PROFILE_FILE" ] && [[ "$PROFILE_FILE" == /tmp/cortexhawk-* ]]; then
+    rm -f "$PROFILE_FILE" 2>/dev/null || true
+fi