cortexhawk 3.2.0 → 3.3.1

package/scripts/post-merge-cleanup.sh

@@ -0,0 +1,233 @@
+#!/bin/bash
+# post-merge-cleanup.sh — Unified post-merge cleanup for all git workflow strategies
+# Strategies: direct-main, feature-branches, dev-branch, gitflow
+# Called by /cleanup command and post-merge hook
+# Args: --auto (silent mode, no prompts), --dry-run (preview without executing)
+
+set -e
+
+# --- 1. FLAGS ---
+AUTO_MODE=false
+DRY_RUN=false
+[ ! -t 0 ] && AUTO_MODE=true
+for arg in "$@"; do
+    case "$arg" in
+        --auto)    AUTO_MODE=true ;;
+        --dry-run) DRY_RUN=true ;;
+    esac
+done
+
+# --- 2. GIT VALIDATION ---
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "Error: not a git repository"
+    exit 1
+fi
+
+# run_cmd: execute command or print preview in dry-run mode
+run_cmd() {
+    if [ "$DRY_RUN" = true ]; then echo "[dry-run] $*"; else "$@"; fi
+}
+log() { [ "$AUTO_MODE" = false ] && echo "$1" || true; }
+
+# --- 3. STRATEGY DETECTION (layers 1-3) ---
+BRANCHING="direct-main"
+MAIN_BRANCH="main"
+WORK_BRANCH=""
+
+# Layer 1: .claude/git-workflow.conf (safe parsing, no source)
+if [ -f ".claude/git-workflow.conf" ]; then
+    BRANCHING=$(grep -E '^BRANCHING=' ".claude/git-workflow.conf" | head -1 | cut -d= -f2 | tr -d '"' | tr -d "'")
+    WORK_BRANCH=$(grep -E '^WORK_BRANCH=' ".claude/git-workflow.conf" | head -1 | cut -d= -f2 | tr -d '"' | tr -d "'")
+    case "$BRANCHING" in
+        dev-branch)       MAIN_BRANCH="main" ;;
+        gitflow)          MAIN_BRANCH="main"; WORK_BRANCH="${WORK_BRANCH:-develop}" ;;
+        feature-branches|direct-main) MAIN_BRANCH="main" ;;
+    esac
+fi
+
+# Layer 2: Fallback to CLAUDE.md
+if [ ! -f ".claude/git-workflow.conf" ] && [ -f "CLAUDE.md" ]; then
+    if grep -q "^## Git Workflow" "CLAUDE.md"; then
+        DETECTED=$(grep -i "branching:" "CLAUDE.md" | head -1 | sed 's/.*: //' | awk '{print $1}')
+        case "$DETECTED" in
+            dev-branch)
+                BRANCHING="dev-branch"
+                WORK_BRANCH=$(grep -i "working branch:" "CLAUDE.md" | head -1 | sed 's/.*: //' | tr -d ')')
+                MAIN_BRANCH="main"
+                ;;
+            gitflow)          BRANCHING="gitflow"; MAIN_BRANCH="main"; WORK_BRANCH="${WORK_BRANCH:-develop}" ;;
+            feature-branches) BRANCHING="feature-branches"; MAIN_BRANCH="main" ;;
+            direct-main)      BRANCHING="direct-main"; MAIN_BRANCH="main" ;;
+        esac
+    fi
+fi
+
+# Layer 3: verify MAIN_BRANCH exists (main vs master fallback)
+if ! git rev-parse --verify "$MAIN_BRANCH" >/dev/null 2>&1; then
+    if git rev-parse --verify main >/dev/null 2>&1; then
+        MAIN_BRANCH="main"
+    elif git rev-parse --verify master >/dev/null 2>&1; then
+        MAIN_BRANCH="master"
+    else
+        echo "Error: branch $MAIN_BRANCH does not exist"; exit 1
+    fi
+fi
+
+# --- 4. PROTECTED BRANCHES ---
+# Single source of truth — these branches are never deleted
+PROTECTED_BRANCHES="main master dev develop ${WORK_BRANCH}"
+
+is_protected() {
+    local branch="$1"
+    for p in $PROTECTED_BRANCHES; do
+        [ "$branch" = "$p" ] && return 0
+    done
+    # Non-gitflow: protect release/hotfix patterns as safety net
+    # Gitflow: allow deletion of merged release/hotfix branches
+    if [ "$BRANCHING" != "gitflow" ]; then
+        case "$branch" in release/*|hotfix/*) return 0 ;; esac
+    fi
+    return 1
+}
+
+# --- 5. REMOTE CHECK ---
+REMOTE_EXISTS=true
+if ! git remote get-url origin >/dev/null 2>&1; then
+    REMOTE_EXISTS=false
+    log "Warning: no remote 'origin' configured, skipping remote operations"
+fi
+CURRENT_BRANCH=$(git branch --show-current)
+log "Strategy: $BRANCHING | main: $MAIN_BRANCH | work: ${WORK_BRANCH:-(none)}"
+
+# --- 6. HELPERS ---
+
+delete_branch() {
+    local branch="$1"
+    is_protected "$branch" && { log "  Protected, skipping: $branch"; return 0; }
+    if [ "$AUTO_MODE" = true ]; then
+        run_cmd git branch -d "$branch" 2>/dev/null || log "  Could not delete $branch"
+    else
+        read -r -p "Delete local branch '$branch'? [y/N]: " c
+        { [ "$c" = "y" ] || [ "$c" = "Y" ]; } && \
+            { run_cmd git branch -d "$branch" || log "  Failed to delete $branch"; }
+    fi
+    if [ "$AUTO_MODE" = false ] && [ "$REMOTE_EXISTS" = true ]; then
+        if git rev-parse --verify "refs/remotes/origin/$branch" >/dev/null 2>&1; then
+            read -r -p "Delete remote 'origin/$branch'? [y/N]: " cr
+            { [ "$cr" = "y" ] || [ "$cr" = "Y" ]; } && \
+                { run_cmd git push origin --delete "$branch" 2>/dev/null || log "  Failed to delete remote $branch"; }
+        fi
+    fi
+}
+
+delete_merged_branches() {
+    local target="${1:-$MAIN_BRANCH}"
+    local merged
+    merged=$(git branch --merged "$target" 2>/dev/null \
+        | grep -v '^\*' | sed 's/^[[:space:]]*//' || true)
+    if [ -z "$merged" ]; then
+        log "No merged branches to clean up"
+        return 0
+    fi
+    local count; count=$(echo "$merged" | wc -l | tr -d ' ')
+    log "Found $count merged branch(es): $(echo "$merged" | tr '\n' ' ')"
+    while IFS= read -r b; do
+        [ -z "$b" ] && continue
+        delete_branch "$b"
+    done <<< "$merged"
+}
+
+resync_work_branch() {
+    local work="$1" target="$2"
+    { [ -z "$work" ] || [ "$REMOTE_EXISTS" = false ]; } && return 0
+    log "Resyncing $work <- $target..."
+    local saved; saved=$(git branch --show-current)
+    if git rev-parse --verify "refs/heads/$work" >/dev/null 2>&1; then
+        run_cmd git checkout "$work" || { log "Warning: could not checkout $work; skipping resync"; return 0; }
+    elif git rev-parse --verify "refs/remotes/origin/$work" >/dev/null 2>&1; then
+        log "  Creating local branch $work from origin/$work"
+        run_cmd git checkout -b "$work" "origin/$work" || { log "Warning: could not create $work; skipping resync"; return 0; }
+    else
+        log "  Warning: branch $work does not exist locally or on origin; skipping resync"
+        return 0
+    fi
+    if ! run_cmd git pull origin "$target" --ff-only 2>/dev/null; then
+        if [ "$AUTO_MODE" = true ]; then
+            echo "Warning: resync $work <- $target needs non-ff merge. Run manually."
+        else
+            read -r -p "Fast-forward failed. Attempt merge? [y/N]: " c
+            if [ "$c" = "y" ] || [ "$c" = "Y" ]; then
+                run_cmd git merge "origin/$target" 2>/dev/null \
+                    || echo "Error: conflict. Resolve then: git push origin $work"
+            fi
+        fi
+    else
+        if ! run_cmd git push origin "$work" 2>/dev/null; then
+            log "Warning: push $work failed (network?)"
+        fi
+    fi
+    if [ "$saved" != "$work" ]; then
+        run_cmd git checkout "$saved" 2>/dev/null || log "Warning: could not return to branch $saved"
+    fi
+}
+
+prompt_new_feature_branch() {
+    [ "$AUTO_MODE" = true ] && return 0
+    [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ] || return 0
+    read -r -p "Create new feature branch? [y/N]: " c
+    { [ "$c" = "y" ] || [ "$c" = "Y" ]; } || return 0
+    read -r -p "Branch name (default: feat/$(date +%s)): " name
+    name="${name:-feat/$(date +%s)}"
+    run_cmd git checkout -b "$name" || log "Failed to create branch $name"
+}
+
+# --- 7. STRATEGY DISPATCH ---
+
+strategy_direct_main() {
+    delete_merged_branches
+    if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ] && [ "$REMOTE_EXISTS" = true ]; then
+        log "Pulling latest from $MAIN_BRANCH..."
+        run_cmd git pull origin "$MAIN_BRANCH" 2>/dev/null \
+            || log "Failed to pull from $MAIN_BRANCH"
+    fi
+}
+
+strategy_feature_branches() {
+    delete_merged_branches
+    if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ] && [ "$REMOTE_EXISTS" = true ]; then
+        log "Pulling latest from $MAIN_BRANCH..."
+        run_cmd git pull origin "$MAIN_BRANCH" 2>/dev/null \
+            || log "Failed to pull from $MAIN_BRANCH"
+    fi
+    prompt_new_feature_branch
+}
+
+strategy_dev_branch() {
+    delete_merged_branches "$MAIN_BRANCH"
+    delete_merged_branches "$WORK_BRANCH"
+    resync_work_branch "$WORK_BRANCH" "$MAIN_BRANCH"
+}
+
+strategy_gitflow() {
+    # Step 1: feat/* merged into develop → delete
+    if git rev-parse --verify "$WORK_BRANCH" >/dev/null 2>&1; then
+        log "Cleaning branches merged into $WORK_BRANCH..."
+        delete_merged_branches "$WORK_BRANCH"
+    fi
+    # Step 2: release/* and hotfix/* merged into main → delete
+    log "Cleaning branches merged into $MAIN_BRANCH..."
+    delete_merged_branches "$MAIN_BRANCH"
+    # Step 3: resync develop ← main
+    resync_work_branch "$WORK_BRANCH" "$MAIN_BRANCH"
+}
+
+case "$BRANCHING" in
+    direct-main)      strategy_direct_main ;;
+    feature-branches) strategy_feature_branches ;;
+    dev-branch)       strategy_dev_branch ;;
+    gitflow)          strategy_gitflow ;;
+    *)                echo "Unknown branching strategy: $BRANCHING" >&2; exit 1 ;;
+esac
+
+log "Cleanup complete!"
+exit 0

package/scripts/restore.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# restore.sh — CortexHawk snapshot restoration
+# Sourced by install.sh when --restore is used
+# Uses shared functions: get_version, compute_checksum, copy_all_components, write_manifest
+# Uses globals: GLOBAL, PROFILE, PROFILE_FILE, SCRIPT_DIR
+
+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)
+        # Validate archive paths before extraction (reject ../ and absolute paths)
+        while IFS= read -r entry; do
+            case "$entry" in
+                /*|*../*|*/..*|..) echo "Error: archive contains unsafe path: $entry"; rm -rf "$archive_tmp"; exit 1 ;;
+            esac
+        done < <(tar -tzf "$snap_file" 2>/dev/null || { echo "Error: invalid archive"; rm -rf "$archive_tmp"; exit 1; })
+        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 "  CortexHawk 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
+
+    # 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"
+
+    # Warn if restore 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 restore source is v$current_version"
+        echo "  Some file checksums may not match"
+        echo ""
+    fi
+
+    # Reinstall using the standard flow
+    echo "Reinstalling CortexHawk components..."
+
+    # Use portable archive files if available, otherwise use source repo
+    if [ -n "$portable_files" ] && [ -d "$portable_files" ]; then
+        echo "  Using files from portable archive..."
+        copy_all_components "$portable_files" "$TARGET" ""
+    else
+        copy_all_components "$SCRIPT_DIR" "$TARGET" "$PROFILE"
+    fi
+
+    # Restore settings.json from snapshot
+    if command -v python3 >/dev/null 2>&1; then
+        python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    snap = json.load(f)
+settings = snap.get('settings')
+if settings is not None:
+    with open(sys.argv[2], 'w') as f:
+        json.dump(settings, f, indent=2)
+        f.write('\n')
+    print('  Restored settings.json')
+" "$snap_file" "$TARGET/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
+snap_file, target_dir = sys.argv[1], sys.argv[2]
+with open(snap_file) as f:
+    snap = json.load(f)
+contents = snap.get('file_contents', {})
+for filename, b64data in contents.items():
+    try:
+        # Reject path traversal and absolute paths
+        if '..' in filename or filename.startswith('/'):
+            print(f'  Warning: skipping unsafe path: {filename}', file=sys.stderr)
+            continue
+        data = base64.b64decode(b64data).decode('utf-8')
+        if filename == 'CLAUDE.md':
+            target_path = os.path.dirname(target_dir) + '/CLAUDE.md'
+        else:
+            target_path = os.path.normpath(target_dir + '/' + filename)
+            if not target_path.startswith(target_dir + os.sep):
+                print(f'  Warning: skipping path outside target: {filename}', file=sys.stderr)
+                continue
+        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)
+" "$snap_file" "$TARGET"
+    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"
+}

package/scripts/snapshot.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# snapshot.sh — CortexHawk snapshot creation and rotation
+# Sourced by install.sh when --snapshot is used
+# Uses shared functions: sed_inplace, compute_checksum (via manifest)
+# Uses globals: GLOBAL, TARGET, PORTABLE_MODE, PROFILE_FILE, MAX_SNAPSHOTS
+
+# --- 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 (use PROFILE_FILE from current run, never glob /tmp/)
+    local profile_def="null"
+    if [ -n "$PROFILE_FILE" ] && [ -f "$PROFILE_FILE" ]; then
+        profile_def=$(cat "$PROFILE_FILE")
+    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_inplace '$ 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
+}