antigravity-skills-reference/skills/skill-installer/scripts/install_skill.py

#!/usr/bin/env python3
"""
Skill Installer v3.0 - Enterprise-grade installer with 11-step redundant workflow.

Detects, validates, copies, registers, and verifies skills in the ecosystem
with maximum redundancy, safety, auto-repair, rollback, and rich diagnostics.

Usage:
    python install_skill.py --source "C:\\path\\to\\skill"
    python install_skill.py --source "C:\\path" --name "my-skill"
    python install_skill.py --source "C:\\path" --force
    python install_skill.py --source "C:\\path" --dry-run
    python install_skill.py --detect
    python install_skill.py --detect --auto
    python install_skill.py --uninstall "skill-name"
    python install_skill.py --health
    python install_skill.py --health --repair
    python install_skill.py --rollback "skill-name"
    python install_skill.py --reinstall-all
    python install_skill.py --status
    python install_skill.py --log [N]
"""

from __future__ import annotations

import os
import sys
import json
import shutil
import hashlib
import subprocess
import re
from pathlib import Path
from datetime import datetime

# Add scripts directory to path for imports
SCRIPT_DIR = Path(__file__).parent.resolve()
sys.path.insert(0, str(SCRIPT_DIR))

from validate_skill import validate, parse_yaml_frontmatter
from detect_skills import detect

# ── Configuration ──────────────────────────────────────────────────────────

SKILLS_ROOT = Path(r"C:\Users\renat\skills")
CLAUDE_SKILLS = SKILLS_ROOT / ".claude" / "skills"
INSTALLER_DIR = SKILLS_ROOT / "skill-installer"
DATA_DIR = INSTALLER_DIR / "data"
BACKUPS_DIR = DATA_DIR / "backups"
STAGING_DIR = DATA_DIR / "staging"
LOG_PATH = DATA_DIR / "install_log.json"
SCAN_SCRIPT = SKILLS_ROOT / "agent-orchestrator" / "scripts" / "scan_registry.py"
REGISTRY_PATH = SKILLS_ROOT / "agent-orchestrator" / "data" / "registry.json"

MAX_BACKUPS_PER_SKILL = 5
MAX_LOG_ENTRIES = 500  # Log rotation threshold
VERSION = "3.0.0"


# ── Console Colors ─────────────────────────────────────────────────────────

class _C:
    """ANSI color codes for terminal output. Degrades gracefully on Windows."""
    _enabled = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
    # Check if stdout can handle UTF-8 symbols
    _utf8 = False
    try:
        _utf8 = sys.stdout.encoding and sys.stdout.encoding.lower().replace("-", "") in ("utf8", "utf16")
    except Exception:
        pass

    @staticmethod
    def _wrap(code: str, text: str) -> str:
        if _C._enabled:
            return f"\033[{code}m{text}\033[0m"
        return text

    @staticmethod
    def green(t: str) -> str: return _C._wrap("32", t)
    @staticmethod
    def red(t: str) -> str: return _C._wrap("31", t)
    @staticmethod
    def yellow(t: str) -> str: return _C._wrap("33", t)
    @staticmethod
    def cyan(t: str) -> str: return _C._wrap("36", t)
    @staticmethod
    def bold(t: str) -> str: return _C._wrap("1", t)
    @staticmethod
    def dim(t: str) -> str: return _C._wrap("2", t)

    # ASCII-safe symbols for Windows cp1252 compatibility
    OK = "[OK]"
    FAIL = "[FAIL]"
    WARN = "[WARN]"


def _step(n: int, total: int, msg: str):
    """Print a step progress indicator."""
    print(f"  {_C.cyan(f'[{n}/{total}]')} {msg}")


def _ok(msg: str):
    print(f"  {_C.green(_C.OK)} {msg}")


def _warn(msg: str):
    print(f"  {_C.yellow(_C.WARN)} {msg}")


def _fail(msg: str):
    print(f"  {_C.red(_C.FAIL)} {msg}")


# ── Utility Functions ──────────────────────────────────────────────────────

def sanitize_name(name: str) -> str:
    """Sanitize skill name: lowercase, hyphens, no spaces."""
    name = name.strip().lower()
    name = name.replace(" ", "-")
    name = name.replace("_", "-")
    # Remove any chars that aren't alphanumeric or hyphens
    name = "".join(c for c in name if c.isalnum() or c == "-")
    # Remove leading/trailing hyphens and collapse multiples
    while "--" in name:
        name = name.replace("--", "-")
    return name.strip("-")


def md5_dir(path: Path, exclude_dirs: set = None) -> str:
    """Compute combined MD5 hash of all files in a directory.

    Excludes backup/staging dirs and normalizes paths to forward slashes
    for cross-platform consistency.
    """
    if exclude_dirs is None:
        exclude_dirs = {"backups", "staging", ".git", "__pycache__", "node_modules", ".venv"}

    h = hashlib.md5()
    for root, dirs, files in os.walk(path):
        # Filter out excluded directories
        dirs[:] = [d for d in dirs if d not in exclude_dirs]
        for f in sorted(files):
            fp = Path(root) / f
            try:
                # Normalize to forward slashes for consistent hashing
                rel = fp.relative_to(path).as_posix()
                h.update(rel.encode("utf-8"))
                with open(fp, "rb") as fh:
                    for chunk in iter(lambda: fh.read(8192), b""):
                        h.update(chunk)
            except Exception:
                pass
    return h.hexdigest()


def parse_version(ver: str) -> tuple:
    """Parse a semver string into a comparable tuple.

    Examples: '1.0.0' -> (1,0,0), '2.1' -> (2,1,0), '' -> (0,0,0)
    """
    if not ver:
        return (0, 0, 0)
    parts = re.findall(r'\d+', str(ver))
    while len(parts) < 3:
        parts.append("0")
    try:
        return tuple(int(p) for p in parts[:3])
    except (ValueError, TypeError):
        return (0, 0, 0)


def compare_versions(installed: str, source: str) -> str:
    """Compare two version strings.

    Returns: 'same', 'upgrade', 'downgrade', or 'unknown'.
    """
    inst = parse_version(installed)
    src = parse_version(source)

    if inst == (0, 0, 0) or src == (0, 0, 0):
        return "unknown"
    if inst == src:
        return "same"
    if src > inst:
        return "upgrade"
    return "downgrade"


def load_log() -> list:
    """Load install log."""
    if LOG_PATH.exists():
        try:
            data = json.loads(LOG_PATH.read_text(encoding="utf-8"))
            return data.get("operations", [])
        except Exception:
            pass
    return []


def save_log(operations: list):
    """Save install log with rotation (keeps last MAX_LOG_ENTRIES)."""
    DATA_DIR.mkdir(parents=True, exist_ok=True)
    # Rotate: keep only the last N entries
    if len(operations) > MAX_LOG_ENTRIES:
        operations = operations[-MAX_LOG_ENTRIES:]
    data = {
        "version": VERSION,
        "operations": operations,
        "total_operations": len(operations),
        "last_updated": datetime.now().isoformat(),
    }
    LOG_PATH.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")


def append_log(entry: dict):
    """Append entry to install log."""
    ops = load_log()
    ops.append(entry)
    save_log(ops)


def cleanup_old_backups(skill_name: str):
    """Keep only the last N backups for a skill."""
    if not BACKUPS_DIR.exists():
        return

    prefix = f"{skill_name}_"
    backups = sorted(
        [d for d in BACKUPS_DIR.iterdir() if d.is_dir() and d.name.startswith(prefix)],
        key=lambda d: d.stat().st_mtime,
    )

    while len(backups) > MAX_BACKUPS_PER_SKILL:
        old = backups.pop(0)
        try:
            shutil.rmtree(old)
        except Exception:
            pass


def get_all_skill_dirs() -> list:
    """Get all skill directories in the ecosystem (top-level + nested)."""
    dirs = []
    for item in sorted(SKILLS_ROOT.iterdir()):
        if not item.is_dir() or item.name.startswith("."):
            continue
        if item.name == "agent-orchestrator":
            continue
        skill_md = item / "SKILL.md"
        if skill_md.exists():
            dirs.append(item)
        # Check nested (e.g., juntas-comerciais/junta-leiloeiros)
        for child in item.iterdir():
            if child.is_dir() and (child / "SKILL.md").exists():
                if child not in dirs:
                    dirs.append(child)
    return dirs


# ── Installation Steps ─────────────────────────────────────────────────────

def step1_resolve_source(source: str = None, do_detect: bool = False, auto: bool = False) -> dict:
    """STEP 1: Resolve source directory."""
    if source:
        source_path = Path(source).resolve()
        if not source_path.exists():
            return {"success": False, "error": f"Source does not exist: {source_path}"}
        if not (source_path / "SKILL.md").exists():
            return {"success": False, "error": f"No SKILL.md found in {source_path}"}
        return {"success": True, "sources": [str(source_path)]}

    if do_detect:
        result = detect()
        candidates = [c for c in result["candidates"] if not c["already_installed"]]

        if not candidates:
            return {
                "success": False,
                "error": "No uninstalled skills detected",
                "scanned_locations": result.get("scanned_locations", []),
            }

        if auto:
            return {
                "success": True,
                "sources": [c["source_path"] for c in candidates],
                "candidates": candidates,
            }

        # Return candidates for user to choose
        return {
            "success": True,
            "sources": [c["source_path"] for c in candidates],
            "candidates": candidates,
            "interactive": True,
        }

    return {"success": False, "error": "No --source or --detect provided"}


def step2_validate(source_path: Path) -> dict:
    """STEP 2: Validate the skill."""
    result = validate(source_path)
    return result


def step3_determine_name(source_path: Path, name_override: str = None) -> str:
    """STEP 3: Determine skill name."""
    if name_override:
        return sanitize_name(name_override)

    meta = parse_yaml_frontmatter(source_path / "SKILL.md")
    name = meta.get("name", source_path.name)
    return sanitize_name(name)


def step4_check_conflicts(skill_name: str) -> dict:
    """STEP 4: Check for existing skill with same name."""
    dest = SKILLS_ROOT / skill_name
    claude_dest = CLAUDE_SKILLS / skill_name

    conflicts = []
    if dest.exists():
        conflicts.append(str(dest))
    if claude_dest.exists():
        conflicts.append(str(claude_dest))

    return {
        "has_conflicts": len(conflicts) > 0,
        "conflicts": conflicts,
        "destination": str(dest),
        "claude_destination": str(claude_dest),
    }


def _backup_ignore(directory, contents):
    """Ignore function for shutil.copytree to skip backup/staging dirs."""
    ignored = set()
    dir_path = Path(directory)
    for item in contents:
        item_path = dir_path / item
        # Skip backup and staging directories to prevent recursion
        if item in ("backups", "staging") and dir_path.name == "data":
            ignored.add(item)
        # Skip .git and __pycache__
        if item in (".git", "__pycache__", "node_modules", ".venv"):
            ignored.add(item)
    return ignored


def step5_backup(skill_name: str) -> dict:
    """STEP 5: Backup existing skill before overwrite."""
    dest = SKILLS_ROOT / skill_name
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    backup_name = f"{skill_name}_{timestamp}"
    backup_path = BACKUPS_DIR / backup_name

    BACKUPS_DIR.mkdir(parents=True, exist_ok=True)

    backed_up = []

    if dest.exists():
        try:
            shutil.copytree(dest, backup_path, ignore=_backup_ignore, dirs_exist_ok=True)
            backed_up.append(str(dest))
        except Exception as e:
            return {"success": False, "error": f"Backup failed for {dest}: {e}"}

    claude_dest = CLAUDE_SKILLS / skill_name
    if claude_dest.exists():
        claude_backup = backup_path / ".claude-registration"
        claude_backup.mkdir(parents=True, exist_ok=True)
        try:
            shutil.copytree(claude_dest, claude_backup / skill_name, dirs_exist_ok=True)
            backed_up.append(str(claude_dest))
        except Exception as e:
            return {"success": False, "error": f"Backup failed for {claude_dest}: {e}"}

    # Cleanup old backups
    cleanup_old_backups(skill_name)

    return {
        "success": True,
        "backup_path": str(backup_path),
        "backed_up": backed_up,
    }


def step6_copy_to_skills_root(source_path: Path, skill_name: str) -> dict:
    """STEP 6: Copy to skills root via staging area."""
    dest = SKILLS_ROOT / skill_name
    staging = STAGING_DIR / skill_name

    STAGING_DIR.mkdir(parents=True, exist_ok=True)

    # Clean staging
    if staging.exists():
        shutil.rmtree(staging)

    # Copy to staging first (skip backups/staging to prevent recursion)
    try:
        shutil.copytree(source_path, staging, ignore=_backup_ignore, dirs_exist_ok=True)
    except Exception as e:
        return {"success": False, "error": f"Copy to staging failed: {e}"}

    # Validate staging copy
    staging_skill_md = staging / "SKILL.md"
    if not staging_skill_md.exists():
        shutil.rmtree(staging, ignore_errors=True)
        return {"success": False, "error": "SKILL.md missing after copy to staging"}

    # Verify hash matches
    source_hash = md5_dir(source_path)
    staging_hash = md5_dir(staging)
    if source_hash != staging_hash:
        shutil.rmtree(staging, ignore_errors=True)
        return {
            "success": False,
            "error": f"Hash mismatch: source={source_hash} staging={staging_hash}",
        }

    # Remove existing destination if exists
    if dest.exists():
        try:
            shutil.rmtree(dest)
        except Exception as e:
            shutil.rmtree(staging, ignore_errors=True)
            return {"success": False, "error": f"Cannot remove existing destination: {e}"}

    # Move staging to final destination
    try:
        shutil.move(str(staging), str(dest))
    except Exception as e:
        # Try copy + delete as fallback (cross-device moves)
        try:
            shutil.copytree(staging, dest, dirs_exist_ok=True)
            shutil.rmtree(staging, ignore_errors=True)
        except Exception as e2:
            shutil.rmtree(staging, ignore_errors=True)
            return {"success": False, "error": f"Move failed: {e}, copy fallback failed: {e2}"}

    return {
        "success": True,
        "installed_to": str(dest),
        "hash": source_hash,
    }


def step7_register_claude(skill_name: str) -> dict:
    """STEP 7: Register in .claude/skills/ for native Claude Code discovery."""
    source_skill_md = SKILLS_ROOT / skill_name / "SKILL.md"
    claude_dest_dir = CLAUDE_SKILLS / skill_name

    if not source_skill_md.exists():
        return {"success": False, "error": f"SKILL.md not found at {source_skill_md}"}

    claude_dest_dir.mkdir(parents=True, exist_ok=True)

    # Copy SKILL.md
    try:
        shutil.copy2(source_skill_md, claude_dest_dir / "SKILL.md")
    except Exception as e:
        return {"success": False, "error": f"Failed to copy SKILL.md to Claude skills: {e}"}

    # Also copy references/ if it exists (useful for Claude to read)
    refs_dir = SKILLS_ROOT / skill_name / "references"
    if refs_dir.exists():
        claude_refs = claude_dest_dir / "references"
        try:
            if claude_refs.exists():
                shutil.rmtree(claude_refs)
            shutil.copytree(refs_dir, claude_refs)
        except Exception:
            pass  # Non-critical

    return {
        "success": True,
        "registered_at": str(claude_dest_dir),
        "files_registered": ["SKILL.md"] + (
            ["references/"] if refs_dir.exists() else []
        ),
    }


def step8_update_registry() -> dict:
    """STEP 8: Run scan_registry.py to update orchestrator registry."""
    if not SCAN_SCRIPT.exists():
        return {
            "success": False,
            "error": f"scan_registry.py not found at {SCAN_SCRIPT}",
        }

    try:
        result = subprocess.run(
            ["python", str(SCAN_SCRIPT), "--force"],
            capture_output=True,
            text=True,
            timeout=30,
            cwd=str(SKILLS_ROOT),
        )
        if result.returncode == 0:
            try:
                scan_output = json.loads(result.stdout)
            except json.JSONDecodeError:
                scan_output = {"raw": result.stdout[:500]}
            return {"success": True, "scan_output": scan_output}
        else:
            return {
                "success": False,
                "error": f"scan_registry.py failed: {result.stderr[:500]}",
            }
    except subprocess.TimeoutExpired:
        return {"success": False, "error": "scan_registry.py timed out (30s)"}
    except Exception as e:
        return {"success": False, "error": f"Failed to run scan_registry.py: {e}"}


def step9_verify(skill_name: str) -> dict:
    """STEP 9: Verify installation is complete and correct."""
    checks = []

    # Check 1: Skill directory exists
    dest = SKILLS_ROOT / skill_name
    checks.append({
        "check": "skill_dir_exists",
        "pass": dest.exists(),
        "path": str(dest),
    })

    # Check 2: SKILL.md exists and is readable
    skill_md = dest / "SKILL.md"
    skill_md_ok = False
    if skill_md.exists():
        try:
            text = skill_md.read_text(encoding="utf-8")
            skill_md_ok = len(text) > 10
        except Exception:
            pass
    checks.append({
        "check": "skill_md_readable",
        "pass": skill_md_ok,
        "path": str(skill_md),
    })

    # Check 3: Frontmatter parseable
    meta = parse_yaml_frontmatter(skill_md) if skill_md.exists() else {}
    checks.append({
        "check": "frontmatter_parseable",
        "pass": bool(meta.get("name")),
        "name": meta.get("name", ""),
    })

    # Check 4: Claude Code registration
    claude_skill_md = CLAUDE_SKILLS / skill_name / "SKILL.md"
    checks.append({
        "check": "claude_registered",
        "pass": claude_skill_md.exists(),
        "path": str(claude_skill_md),
    })

    # Check 5: Appears in registry
    in_registry = False
    if REGISTRY_PATH.exists():
        try:
            registry = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
            skill_names = [s.get("name", "").lower() for s in registry.get("skills", [])]
            in_registry = skill_name.lower() in skill_names
        except Exception:
            pass
    checks.append({
        "check": "in_registry",
        "pass": in_registry,
    })

    all_passed = all(c["pass"] for c in checks)

    return {
        "success": all_passed,
        "checks": checks,
        "total": len(checks),
        "passed": sum(1 for c in checks if c["pass"]),
        "failed": sum(1 for c in checks if not c["pass"]),
    }


def step10_log(skill_name: str, source: str, result: dict):
    """STEP 10: Log the operation."""
    entry = {
        "timestamp": datetime.now().isoformat(),
        "action": "install",
        "skill_name": skill_name,
        "source": source,
        "destination": str(SKILLS_ROOT / skill_name),
        "registered": result.get("registered", False),
        "registry_updated": result.get("registry_updated", False),
        "backup_path": result.get("backup_path"),
        "success": result.get("success", False),
        "verification": result.get("verification", {}),
        "warnings": result.get("warnings", []),
    }

    try:
        append_log(entry)
    except Exception:
        pass  # Logging failure is non-critical

    return entry


# ── Main Install Workflow ──────────────────────────────────────────────────

def install_single(
    source_path: str,
    name_override: str = None,
    force: bool = False,
    dry_run: bool = False,
    verbose: bool = True,
) -> dict:
    """Install a single skill through the 11-step workflow.

    Args:
        source_path: Path to skill directory containing SKILL.md.
        name_override: Optional name to use instead of frontmatter name.
        force: If True, overwrite existing skill (backup first).
        dry_run: If True, simulate all steps without writing anything.
        verbose: If True, print step-by-step progress to stdout.
    """
    source = Path(source_path).resolve()
    total_steps = 11
    result = {
        "success": False,
        "skill_name": "",
        "installed_to": "",
        "registered": False,
        "registry_updated": False,
        "backup_path": None,
        "warnings": [],
        "steps": {},
        "dry_run": dry_run,
        "installer_version": VERSION,
    }

    if dry_run and verbose:
        print(f"\n{_C.bold(_C.yellow('=== DRY RUN MODE === No changes will be made'))}\n")

    # STEP 1: Already resolved (source is provided)
    if verbose:
        _step(1, total_steps, "Resolving source...")
    if not source.exists() or not (source / "SKILL.md").exists():
        result["error"] = f"Invalid source: {source}"
        if verbose:
            _fail(f"Source invalid: {source}")
        return result

    result["steps"]["1_resolve"] = {"success": True, "source": str(source)}
    if verbose:
        _ok(f"Source: {source}")

    # STEP 2: Validate
    if verbose:
        _step(2, total_steps, "Validating skill...")
    validation = step2_validate(source)
    result["steps"]["2_validate"] = validation

    if not validation["valid"]:
        result["error"] = f"Validation failed: {'; '.join(validation['errors'])}"
        result["warnings"] = validation.get("warnings", [])
        if verbose:
            _fail(f"Validation failed: {len(validation['errors'])} error(s)")
            for e in validation["errors"]:
                _fail(f"  {e}")
        return result

    if verbose:
        _ok(f"Validation passed ({validation['passed']}/{validation['total_checks']} checks)")
        for w in validation.get("warnings", []):
            _warn(f"  {w}")

    result["warnings"].extend(validation.get("warnings", []))

    # STEP 3: Determine name
    if verbose:
        _step(3, total_steps, "Determining skill name...")
    skill_name = step3_determine_name(source, name_override)
    result["skill_name"] = skill_name
    result["steps"]["3_name"] = {"name": skill_name}

    if not skill_name:
        result["error"] = "Could not determine skill name"
        if verbose:
            _fail("Could not determine skill name")
        return result
    if verbose:
        _ok(f"Name: {_C.bold(skill_name)}")

    # Version comparison with installed
    source_meta = parse_yaml_frontmatter(source / "SKILL.md")
    source_version = source_meta.get("version", "")
    dest = SKILLS_ROOT / skill_name
    if dest.exists() and (dest / "SKILL.md").exists():
        installed_meta = parse_yaml_frontmatter(dest / "SKILL.md")
        installed_version = installed_meta.get("version", "")
        ver_cmp = compare_versions(installed_version, source_version)
        result["version_comparison"] = {
            "installed": installed_version,
            "source": source_version,
            "result": ver_cmp,
        }
        if verbose and ver_cmp != "unknown":
            if ver_cmp == "upgrade":
                _ok(f"Version: {installed_version} -> {_C.green(source_version)} (upgrade)")
            elif ver_cmp == "downgrade":
                _warn(f"Version: {installed_version} -> {_C.yellow(source_version)} (downgrade)")
            elif ver_cmp == "same":
                _ok(f"Version: {source_version} (same)")

    # STEP 4: Check conflicts
    if verbose:
        _step(4, total_steps, "Checking conflicts...")
    conflicts = step4_check_conflicts(skill_name)
    result["steps"]["4_conflicts"] = conflicts

    if conflicts["has_conflicts"] and not force:
        result["error"] = (
            f"Skill '{skill_name}' already exists at: {', '.join(conflicts['conflicts'])}. "
            f"Use --force to overwrite."
        )
        if verbose:
            _fail(f"Conflict: skill already exists. Use --force to overwrite.")
        return result
    if verbose:
        if conflicts["has_conflicts"]:
            _warn(f"Conflict detected -- will overwrite (--force)")
        else:
            _ok("No conflicts")

    # STEP 5: Backup (if overwriting)
    if verbose:
        _step(5, total_steps, "Creating backup...")
    backup_result = {"success": True, "backup_path": None}
    if conflicts["has_conflicts"] and force:
        if dry_run:
            backup_result = {"success": True, "backup_path": "(dry-run)", "dry_run": True}
            if verbose:
                _ok("Backup would be created (dry-run)")
        else:
            backup_result = step5_backup(skill_name)
            if not backup_result["success"]:
                result["error"] = f"Backup failed: {backup_result.get('error')}"
                if verbose:
                    _fail(f"Backup failed: {backup_result.get('error')}")
                return result
            result["backup_path"] = backup_result.get("backup_path")
            if verbose:
                _ok(f"Backup saved: {backup_result.get('backup_path', '?')}")
    else:
        if verbose:
            _ok("No backup needed (new install)")

    result["steps"]["5_backup"] = backup_result

    # Check idempotency: same content?
    idempotent = False
    if dest.exists():
        source_hash = md5_dir(source)
        dest_hash = md5_dir(dest)
        if source_hash == dest_hash:
            idempotent = True
            result["idempotent"] = True
            result["installed_to"] = str(dest)
            result["steps"]["6_copy"] = {
                "success": True,
                "installed_to": str(dest),
                "skipped": "identical content already at destination",
                "hash": source_hash,
            }
            if verbose:
                _ok("Content identical -- skipping copy")

    # STEP 6: Copy to skills root (skip if idempotent)
    if not idempotent:
        if verbose:
            _step(6, total_steps, "Copying to skills root via staging...")
        if dry_run:
            result["steps"]["6_copy"] = {
                "success": True,
                "installed_to": str(dest),
                "dry_run": True,
            }
            result["installed_to"] = str(dest)
            if verbose:
                _ok(f"Would copy to: {dest} (dry-run)")
        else:
            copy_result = step6_copy_to_skills_root(source, skill_name)
            result["steps"]["6_copy"] = copy_result

            if not copy_result["success"]:
                result["error"] = f"Copy failed: {copy_result.get('error')}"
                if verbose:
                    _fail(f"Copy failed: {copy_result.get('error')}")
                step10_log(skill_name, str(source), result)
                return result

            result["installed_to"] = copy_result["installed_to"]
            if verbose:
                _ok(f"Copied to: {copy_result['installed_to']}")
    elif verbose and not idempotent:
        _step(6, total_steps, "Copying to skills root...")

    # STEP 7: Register in Claude Code (ALWAYS runs, even if idempotent)
    if verbose:
        _step(7, total_steps, "Registering in Claude Code CLI...")
    if dry_run:
        result["steps"]["7_register"] = {"success": True, "dry_run": True}
        result["registered"] = True
        if verbose:
            _ok("Would register in .claude/skills/ (dry-run)")
    else:
        register_result = step7_register_claude(skill_name)
        result["steps"]["7_register"] = register_result
        result["registered"] = register_result["success"]

        if not register_result["success"]:
            result["warnings"].append(f"Registration warning: {register_result.get('error')}")
            if verbose:
                _warn(f"Registration: {register_result.get('error')}")
        elif verbose:
            _ok(f"Registered at: {register_result.get('registered_at')}")

    # STEP 8: Update orchestrator registry
    if verbose:
        _step(8, total_steps, "Updating orchestrator registry...")
    if dry_run:
        result["steps"]["8_registry"] = {"success": True, "dry_run": True}
        result["registry_updated"] = True
        if verbose:
            _ok("Would update registry (dry-run)")
    else:
        registry_result = step8_update_registry()
        result["steps"]["8_registry"] = registry_result
        result["registry_updated"] = registry_result["success"]

        if not registry_result["success"]:
            result["warnings"].append(f"Registry update warning: {registry_result.get('error')}")
            if verbose:
                _warn(f"Registry: {registry_result.get('error')}")
        elif verbose:
            _ok("Registry updated")

    # STEP 9: Verify installation
    if verbose:
        _step(9, total_steps, "Verifying installation...")
    if dry_run:
        result["steps"]["9_verify"] = {"success": True, "dry_run": True}
        result["verification"] = {"success": True, "dry_run": True}
        if verbose:
            _ok("Verification skipped (dry-run)")
    else:
        verify_result = step9_verify(skill_name)
        result["steps"]["9_verify"] = verify_result
        result["verification"] = verify_result
        if verbose:
            if verify_result["success"]:
                _ok(f"All {verify_result['total']} verification checks passed")
            else:
                failed_checks = [c for c in verify_result["checks"] if not c["pass"]]
                _warn(f"{verify_result['failed']}/{verify_result['total']} checks failed")
                for c in failed_checks:
                    _fail(f"  {c['check']}")

    # STEP 10: Package ZIP for Claude.ai web upload
    if verbose:
        _step(10, total_steps, "Packaging ZIP for Claude.ai...")
    if dry_run:
        result["steps"]["10_package"] = {"success": True, "dry_run": True}
        if verbose:
            _ok("Would create ZIP (dry-run)")
    else:
        zip_result = {"success": False, "skipped": True}
        try:
            from package_skill import package_skill as pkg_skill
            zip_result = pkg_skill(SKILLS_ROOT / skill_name)
            result["steps"]["10_package"] = zip_result
            result["zip_path"] = zip_result.get("zip_path") if zip_result["success"] else None
            if verbose:
                if zip_result["success"]:
                    _ok(f"ZIP: {zip_result.get('zip_path')} ({zip_result.get('zip_size_kb', '?')} KB)")
                else:
                    _warn(f"ZIP: {zip_result.get('error', 'failed')}")
        except Exception as e:
            zip_result = {"success": False, "error": str(e)}
            result["steps"]["10_package"] = zip_result
            result["warnings"].append(f"ZIP packaging warning: {e}")
            if verbose:
                _warn(f"ZIP packaging: {e}")

    # STEP 11: Log
    if verbose:
        _step(11, total_steps, "Logging operation...")
    if dry_run:
        result["success"] = True
        result["steps"]["11_log"] = {"logged": False, "dry_run": True}
        if verbose:
            _ok("Would log operation (dry-run)")
            print(f"\n{_C.bold(_C.green('DRY RUN COMPLETE'))} -- no changes were made.\n")
    else:
        result["success"] = result.get("verification", {}).get("success", False)
        if not result.get("verification", {}).get("success", True):
            failed_checks = [c for c in result.get("verification", {}).get("checks", []) if not c.get("pass")]
            result["warnings"].append(
                f"Verification: {result['verification'].get('failed', 0)} check(s) failed: "
                + ", ".join(c["check"] for c in failed_checks)
            )

        log_entry = step10_log(skill_name, str(source), result)
        result["steps"]["11_log"] = {"logged": True}
        if verbose:
            _ok("Operation logged")
            if result["success"]:
                print(f"\n{_C.bold(_C.green('SUCCESS'))} -- {_C.bold(skill_name)} installed.\n")
            else:
                print(f"\n{_C.bold(_C.red('FAILED'))} -- see warnings above.\n")

    return result


# ── Uninstall ─────────────────────────────────────────────────────────────

def uninstall_skill(skill_name: str, keep_backup: bool = True) -> dict:
    """Uninstall a skill: remove from skills root, .claude/skills/, and registry."""
    skill_name = sanitize_name(skill_name)
    result = {
        "success": False,
        "skill_name": skill_name,
        "removed": [],
        "backup_path": None,
    }

    dest = SKILLS_ROOT / skill_name
    claude_dest = CLAUDE_SKILLS / skill_name

    if not dest.exists() and not claude_dest.exists():
        result["error"] = f"Skill '{skill_name}' not found in any location"
        return result

    # Backup before removing
    if keep_backup and dest.exists():
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        backup_path = BACKUPS_DIR / f"{skill_name}_{timestamp}"
        BACKUPS_DIR.mkdir(parents=True, exist_ok=True)
        try:
            shutil.copytree(dest, backup_path, dirs_exist_ok=True)
            result["backup_path"] = str(backup_path)
        except Exception as e:
            result["error"] = f"Backup failed: {e}"
            return result

    # Remove from skills root
    if dest.exists():
        try:
            shutil.rmtree(dest)
            result["removed"].append(str(dest))
        except Exception as e:
            result["error"] = f"Failed to remove {dest}: {e}"
            return result

    # Remove from .claude/skills/
    if claude_dest.exists():
        try:
            shutil.rmtree(claude_dest)
            result["removed"].append(str(claude_dest))
        except Exception as e:
            result["warnings"] = [f"Failed to remove Claude registration: {e}"]

    # Update registry
    registry_result = step8_update_registry()

    # Remove ZIP from Desktop if exists
    zip_path = Path(os.path.expanduser("~")) / "Desktop" / f"{skill_name}.zip"
    if zip_path.exists():
        try:
            zip_path.unlink()
            result["removed"].append(str(zip_path))
        except Exception:
            pass

    # Log operation
    entry = {
        "timestamp": datetime.now().isoformat(),
        "action": "uninstall",
        "skill_name": skill_name,
        "removed": result["removed"],
        "backup_path": result.get("backup_path"),
        "success": True,
    }
    try:
        append_log(entry)
    except Exception:
        pass

    result["success"] = True
    result["registry_updated"] = registry_result.get("success", False)
    return result


# ── Health Check ──────────────────────────────────────────────────────────

def health_check() -> dict:
    """Run a global health check on all installed skills."""
    results = []

    # Load registry
    registry_skills = []
    if REGISTRY_PATH.exists():
        try:
            registry = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
            registry_skills = registry.get("skills", [])
        except Exception:
            pass

    registry_names = {s.get("name", "").lower() for s in registry_skills}

    # Check all skill directories in skills root
    for item in sorted(SKILLS_ROOT.iterdir()):
        if not item.is_dir():
            continue
        if item.name.startswith("."):
            continue
        if item.name in ("agent-orchestrator", "skill-installer"):
            continue

        skill_md = item / "SKILL.md"
        if not skill_md.exists():
            continue

        meta = parse_yaml_frontmatter(skill_md)
        name = meta.get("name", item.name).lower()

        checks = {
            "name": name,
            "dir": str(item),
            "skill_md_exists": skill_md.exists(),
            "frontmatter_ok": bool(meta.get("name") and meta.get("description")),
            "claude_registered": (CLAUDE_SKILLS / name / "SKILL.md").exists(),
            "in_registry": name in registry_names,
            "has_scripts": (item / "scripts").exists(),
            "has_references": (item / "references").exists(),
        }

        # Count issues
        issues = []
        if not checks["frontmatter_ok"]:
            issues.append("invalid frontmatter (missing name or description)")
        if not checks["claude_registered"]:
            issues.append("not registered in .claude/skills/")
        if not checks["in_registry"]:
            issues.append("not in orchestrator registry")

        checks["healthy"] = len(issues) == 0
        checks["issues"] = issues
        results.append(checks)

    # Also check nested skills (e.g., juntas-comerciais/junta-leiloeiros)
    for parent in SKILLS_ROOT.iterdir():
        if not parent.is_dir() or parent.name.startswith("."):
            continue
        if parent.name in ("agent-orchestrator", "skill-installer"):
            continue
        for child in parent.iterdir():
            if child.is_dir() and (child / "SKILL.md").exists():
                # Skip if already checked at top level
                if any(r["dir"] == str(child) for r in results):
                    continue
                meta = parse_yaml_frontmatter(child / "SKILL.md")
                name = meta.get("name", child.name).lower()
                checks = {
                    "name": name,
                    "dir": str(child),
                    "skill_md_exists": True,
                    "frontmatter_ok": bool(meta.get("name") and meta.get("description")),
                    "claude_registered": (CLAUDE_SKILLS / name / "SKILL.md").exists(),
                    "in_registry": name in registry_names,
                    "has_scripts": (child / "scripts").exists(),
                    "has_references": (child / "references").exists(),
                }
                issues = []
                if not checks["frontmatter_ok"]:
                    issues.append("invalid frontmatter")
                if not checks["claude_registered"]:
                    issues.append("not registered in .claude/skills/")
                if not checks["in_registry"]:
                    issues.append("not in orchestrator registry")
                checks["healthy"] = len(issues) == 0
                checks["issues"] = issues
                results.append(checks)

    healthy = sum(1 for r in results if r["healthy"])
    unhealthy = sum(1 for r in results if not r["healthy"])

    # Check for registry duplicates
    from collections import Counter
    reg_name_counts = Counter(s.get("name", "").lower() for s in registry_skills)
    duplicates = {name: count for name, count in reg_name_counts.items() if count > 1}

    return {
        "total_skills": len(results),
        "healthy": healthy,
        "unhealthy": unhealthy,
        "registry_duplicates": duplicates,
        "skills": results,
    }


# ── Auto-Repair ──────────────────────────────────────────────────────────

def repair_health(verbose: bool = True) -> dict:
    """Run health check and automatically fix all issues found.

    Fixes:
    - Skills not registered in .claude/skills/ -> registers them
    - Skills not in orchestrator registry -> triggers registry scan
    - Registry duplicates -> triggers re-scan with deduplication
    """
    if verbose:
        print(f"\n{_C.bold('=== HEALTH CHECK + AUTO-REPAIR ===')}\n")

    health = health_check()
    repairs = []
    errors = []

    unhealthy_skills = [s for s in health["skills"] if not s["healthy"]]

    if not unhealthy_skills and not health["registry_duplicates"]:
        if verbose:
            _ok(f"All {health['total_skills']} skills are healthy. Nothing to repair.")
        health["repairs"] = []
        return health

    # Fix: register missing skills in .claude/skills/
    for skill in unhealthy_skills:
        if "not registered in .claude/skills/" in "; ".join(skill["issues"]):
            name = skill["name"]
            skill_dir = Path(skill["dir"])
            skill_md = skill_dir / "SKILL.md"
            if skill_md.exists():
                claude_dest = CLAUDE_SKILLS / name
                if verbose:
                    _step(1, 2, f"Registering '{name}' in .claude/skills/...")
                try:
                    claude_dest.mkdir(parents=True, exist_ok=True)
                    shutil.copy2(skill_md, claude_dest / "SKILL.md")
                    # Also copy references/ if present
                    refs = skill_dir / "references"
                    if refs.exists():
                        claude_refs = claude_dest / "references"
                        if claude_refs.exists():
                            shutil.rmtree(claude_refs)
                        shutil.copytree(refs, claude_refs)
                    repairs.append({"skill": name, "action": "registered", "success": True})
                    if verbose:
                        _ok(f"Registered: {name}")
                except Exception as e:
                    errors.append({"skill": name, "action": "register", "error": str(e)})
                    if verbose:
                        _fail(f"Failed to register {name}: {e}")

    # Fix: update registry to pick up missing skills and remove duplicates
    needs_registry_update = (
        any("not in orchestrator registry" in "; ".join(s["issues"]) for s in unhealthy_skills)
        or health["registry_duplicates"]
    )
    if needs_registry_update:
        if verbose:
            _step(2, 2, "Updating orchestrator registry...")
        reg_result = step8_update_registry()
        if reg_result["success"]:
            repairs.append({"action": "registry_update", "success": True})
            if verbose:
                _ok("Registry updated")
        else:
            errors.append({"action": "registry_update", "error": reg_result.get("error")})
            if verbose:
                _fail(f"Registry update failed: {reg_result.get('error')}")

    # Re-run health check to confirm
    health_after = health_check()

    result = {
        "before": {
            "healthy": health["healthy"],
            "unhealthy": health["unhealthy"],
            "duplicates": len(health["registry_duplicates"]),
        },
        "after": {
            "healthy": health_after["healthy"],
            "unhealthy": health_after["unhealthy"],
            "duplicates": len(health_after["registry_duplicates"]),
        },
        "repairs": repairs,
        "errors": errors,
        "skills": health_after["skills"],
    }

    if verbose:
        fixed = health["unhealthy"] - health_after["unhealthy"]
        print(f"\n{_C.bold('Result:')} Fixed {_C.green(str(fixed))} of {health['unhealthy']} issues.")
        if health_after["unhealthy"] > 0:
            _warn(f"{health_after['unhealthy']} issues remaining")
        else:
            _ok("All skills healthy!")
        print()

    return result


# ── Rollback ─────────────────────────────────────────────────────────────

def rollback_skill(skill_name: str, verbose: bool = True) -> dict:
    """Restore a skill from its latest backup.

    Finds the most recent backup for the given skill and restores it
    to the skills root, re-registers, and updates the registry.
    """
    skill_name = sanitize_name(skill_name)
    result = {
        "success": False,
        "skill_name": skill_name,
        "restored_from": None,
    }

    if not BACKUPS_DIR.exists():
        result["error"] = "No backups directory found"
        if verbose:
            _fail("No backups directory found")
        return result

    # Find backups for this skill
    prefix = f"{skill_name}_"
    backups = sorted(
        [d for d in BACKUPS_DIR.iterdir() if d.is_dir() and d.name.startswith(prefix)],
        key=lambda d: d.stat().st_mtime,
        reverse=True,
    )

    if not backups:
        result["error"] = f"No backups found for skill '{skill_name}'"
        if verbose:
            _fail(f"No backups found for '{skill_name}'")
            # Show available backups
            all_backups = [d.name for d in BACKUPS_DIR.iterdir() if d.is_dir()]
            if all_backups:
                print(f"  Available backups: {', '.join(sorted(set(b.rsplit('_', 2)[0] for b in all_backups)))}")
        return result

    latest_backup = backups[0]
    backup_skill_md = latest_backup / "SKILL.md"

    if not backup_skill_md.exists():
        result["error"] = f"Backup is invalid (no SKILL.md): {latest_backup}"
        if verbose:
            _fail(f"Backup invalid: {latest_backup}")
        return result

    if verbose:
        timestamp = latest_backup.name.replace(f"{skill_name}_", "")
        print(f"\n{_C.bold(f'=== ROLLBACK: {skill_name} ===')}")
        print(f"  Backup: {latest_backup.name} ({timestamp})")

    # Restore to skills root
    dest = SKILLS_ROOT / skill_name
    if verbose:
        _step(1, 3, "Restoring from backup...")

    try:
        if dest.exists():
            shutil.rmtree(dest)
        shutil.copytree(latest_backup, dest, ignore=_backup_ignore, dirs_exist_ok=True)
        result["restored_from"] = str(latest_backup)
        if verbose:
            _ok(f"Restored to: {dest}")
    except Exception as e:
        result["error"] = f"Restore failed: {e}"
        if verbose:
            _fail(f"Restore failed: {e}")
        return result

    # Re-register in Claude Code
    if verbose:
        _step(2, 3, "Re-registering...")
    reg = step7_register_claude(skill_name)
    if verbose:
        if reg["success"]:
            _ok("Registered")
        else:
            _warn(f"Registration: {reg.get('error')}")

    # Update registry
    if verbose:
        _step(3, 3, "Updating registry...")
    step8_update_registry()
    if verbose:
        _ok("Registry updated")

    # Log operation
    append_log({
        "timestamp": datetime.now().isoformat(),
        "action": "rollback",
        "skill_name": skill_name,
        "backup_used": str(latest_backup),
        "success": True,
    })

    result["success"] = True
    if verbose:
        print(f"\n{_C.bold(_C.green('ROLLBACK COMPLETE'))}\n")
    return result


# ── Reinstall All ────────────────────────────────────────────────────────

def reinstall_all(force: bool = True, verbose: bool = True) -> dict:
    """Re-register every installed skill in one pass.

    Iterates all skill directories, re-copies SKILL.md to .claude/skills/,
    re-packages ZIPs, and updates the registry.
    """
    if verbose:
        print(f"\n{_C.bold('=== REINSTALL ALL SKILLS ===')}\n")

    skill_dirs = get_all_skill_dirs()
    results_list = []

    for i, skill_dir in enumerate(skill_dirs, 1):
        meta = parse_yaml_frontmatter(skill_dir / "SKILL.md")
        name = meta.get("name", skill_dir.name)
        name = sanitize_name(name)

        if verbose:
            print(f"  [{i}/{len(skill_dirs)}] {_C.bold(name)}...")

        # Re-register in .claude/skills/
        reg = step7_register_claude(name)

        # Re-package ZIP
        zip_result = {"success": False}
        try:
            from package_skill import package_skill as pkg_skill
            zip_result = pkg_skill(skill_dir)
        except Exception:
            pass

        r = {
            "skill": name,
            "registered": reg["success"],
            "zipped": zip_result.get("success", False),
        }
        results_list.append(r)

        if verbose:
            status = _C.green(_C.OK) if reg["success"] else _C.red(_C.FAIL)
            zip_status = _C.green("ZIP-OK") if zip_result.get("success") else _C.yellow("ZIP-WARN")
            print(f"    {status} registered  {zip_status}")

    # Final registry update
    if verbose:
        print(f"\n  Updating registry...")
    step8_update_registry()

    registered_ok = sum(1 for r in results_list if r["registered"])
    zipped_ok = sum(1 for r in results_list if r["zipped"])

    result = {
        "total": len(results_list),
        "registered": registered_ok,
        "zipped": zipped_ok,
        "results": results_list,
    }

    if verbose:
        print(f"\n{_C.bold('Result:')} {registered_ok}/{len(results_list)} registered, {zipped_ok}/{len(results_list)} zipped.")
        print()

    # Log
    append_log({
        "timestamp": datetime.now().isoformat(),
        "action": "reinstall_all",
        "total": len(results_list),
        "registered": registered_ok,
        "zipped": zipped_ok,
        "success": True,
    })

    return result


# ── Status Dashboard ─────────────────────────────────────────────────────

def show_status(verbose: bool = True) -> dict:
    """Rich status dashboard showing all skills, versions, and health."""
    health = health_check()

    # Load registry for version info
    registry_skills = {}
    if REGISTRY_PATH.exists():
        try:
            reg = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
            for s in reg.get("skills", []):
                registry_skills[s.get("name", "").lower()] = s
        except Exception:
            pass

    # Count backups per skill
    backup_counts = {}
    if BACKUPS_DIR.exists():
        for d in BACKUPS_DIR.iterdir():
            if d.is_dir():
                # Extract skill name (everything before last _TIMESTAMP)
                parts = d.name.rsplit("_", 2)
                if len(parts) >= 3:
                    bname = parts[0]
                else:
                    bname = d.name
                backup_counts[bname] = backup_counts.get(bname, 0) + 1

    # Log stats
    log_ops = load_log()
    install_count = sum(1 for o in log_ops if o.get("action") == "install")
    uninstall_count = sum(1 for o in log_ops if o.get("action") == "uninstall")
    rollback_count = sum(1 for o in log_ops if o.get("action") == "rollback")

    if verbose:
        print(f"\n{_C.bold('+' + '='*62 + '+')}")
        print(f"{_C.bold('|')}  {_C.bold(_C.cyan('Skill Installer v' + VERSION + ' -- Status Dashboard'))}              {_C.bold('|')}")
        print(f"{_C.bold('+' + '='*62 + '+')}\n")

        # Skills table header
        print(f"  {'Name':<24} {'Version':<10} {'Health':<10} {'Registered':<12} {'Backups':<8}")
        print(f"  {'-'*24} {'-'*10} {'-'*10} {'-'*12} {'-'*8}")

        for skill in health["skills"]:
            name = skill["name"][:22]
            reg_entry = registry_skills.get(skill["name"], {})
            version = reg_entry.get("version", "-") or "-"
            status = _C.green("OK") if skill["healthy"] else _C.red("ISSUE")
            registered = _C.green("Yes") if skill["claude_registered"] else _C.red("No")
            backups = str(backup_counts.get(skill["name"], 0))
            print(f"  {name:<24} {version:<10} {status:<19} {registered:<21} {backups:<8}")

            if not skill["healthy"]:
                for issue in skill["issues"]:
                    print(f"    {_C.dim(f'  -> {issue}')}")

        print(f"\n  {_C.bold('Summary:')}")
        print(f"    Skills: {_C.bold(str(health['total_skills']))} total, "
              f"{_C.green(str(health['healthy']))} healthy, "
              f"{_C.red(str(health['unhealthy'])) if health['unhealthy'] else '0'} unhealthy")
        if health["registry_duplicates"]:
            print(f"    {_C.yellow('Duplicates:')} {health['registry_duplicates']}")

        print(f"\n  {_C.bold('Operations Log:')}")
        print(f"    Installs: {install_count} | Uninstalls: {uninstall_count} | Rollbacks: {rollback_count}")
        print(f"    Total logged: {len(log_ops)}")
        print()

    return {
        "health": health,
        "backup_counts": backup_counts,
        "log_stats": {
            "total": len(log_ops),
            "installs": install_count,
            "uninstalls": uninstall_count,
            "rollbacks": rollback_count,
        },
    }


# ── Log Viewer ───────────────────────────────────────────────────────────

def show_log(n: int = 20, verbose: bool = True) -> list:
    """Show the last N log entries."""
    ops = load_log()
    recent = ops[-n:] if len(ops) > n else ops

    if verbose:
        print(f"\n{_C.bold(f'=== Last {len(recent)} Operations ===')}\n")
        for op in reversed(recent):
            ts = op.get("timestamp", "?")[:19]
            action = op.get("action", "?")
            name = op.get("skill_name", "?")
            success = op.get("success", False)

            # Color the action
            if action == "install":
                action_str = _C.green("INSTALL")
            elif action == "uninstall":
                action_str = _C.red("UNINSTALL")
            elif action == "rollback":
                action_str = _C.yellow("ROLLBACK")
            elif action == "reinstall_all":
                action_str = _C.cyan("REINSTALL-ALL")
            else:
                action_str = action.upper()

            status = _C.green(_C.OK) if success else _C.red(_C.FAIL)
            print(f"  {_C.dim(ts)}  {action_str:<22} {name:<24} {status}")

        print()

    return recent


# ── CLI Entry Point ───────────────────────────────────────────────────────

def main():
    args = sys.argv[1:]

    source = None
    name_override = None
    force = "--force" in args
    dry_run = "--dry-run" in args
    do_detect = "--detect" in args
    auto = "--auto" in args
    do_uninstall = "--uninstall" in args
    do_health = "--health" in args
    do_repair = "--repair" in args
    do_rollback = "--rollback" in args
    do_reinstall_all = "--reinstall-all" in args
    do_status = "--status" in args
    do_log = "--log" in args
    json_output = "--json" in args

    if "--source" in args:
        idx = args.index("--source")
        if idx + 1 < len(args):
            source = args[idx + 1]

    if "--name" in args:
        idx = args.index("--name")
        if idx + 1 < len(args):
            name_override = args[idx + 1]

    # ── Status dashboard ──
    if do_status:
        result = show_status(verbose=not json_output)
        if json_output:
            print(json.dumps(result, indent=2, ensure_ascii=False))
        sys.exit(0)

    # ── Log viewer ──
    if do_log:
        n = 20
        idx = args.index("--log")
        if idx + 1 < len(args):
            try:
                n = int(args[idx + 1])
            except ValueError:
                pass
        result = show_log(n=n, verbose=not json_output)
        if json_output:
            print(json.dumps(result, indent=2, ensure_ascii=False))
        sys.exit(0)

    # ── Health check (with optional auto-repair) ──
    if do_health:
        if do_repair:
            result = repair_health(verbose=not json_output)
            if json_output:
                print(json.dumps(result, indent=2, ensure_ascii=False))
            remaining = result.get("after", {}).get("unhealthy", 0)
            sys.exit(0 if remaining == 0 else 1)
        else:
            result = health_check()
            if json_output:
                print(json.dumps(result, indent=2, ensure_ascii=False))
            else:
                # Pretty print health
                print(f"\n{_C.bold('=== HEALTH CHECK ===')}\n")
                for s in result["skills"]:
                    if s["healthy"]:
                        _ok(s["name"])
                    else:
                        _fail(f"{s['name']}: {'; '.join(s['issues'])}")
                print(f"\n  {_C.bold(str(result['healthy']))}/{result['total_skills']} healthy")
                if result["unhealthy"] > 0:
                    print(f"  {_C.yellow('Tip:')} run with --repair to auto-fix issues")
                if result["registry_duplicates"]:
                    print(f"  {_C.yellow('Duplicates:')} {result['registry_duplicates']}")
                print()
            sys.exit(0 if result["unhealthy"] == 0 else 1)

    # ── Rollback ──
    if do_rollback:
        idx = args.index("--rollback")
        if idx + 1 >= len(args):
            print(json.dumps({"error": "Usage: --rollback <skill-name>"}, indent=2))
            sys.exit(1)
        skill_name = args[idx + 1]
        result = rollback_skill(skill_name, verbose=not json_output)
        if json_output:
            print(json.dumps(result, indent=2, ensure_ascii=False))
        sys.exit(0 if result["success"] else 1)

    # ── Reinstall all ──
    if do_reinstall_all:
        result = reinstall_all(force=True, verbose=not json_output)
        if json_output:
            print(json.dumps(result, indent=2, ensure_ascii=False))
        sys.exit(0)

    # ── Uninstall ──
    if do_uninstall:
        idx = args.index("--uninstall")
        if idx + 1 >= len(args):
            print(json.dumps({"error": "Usage: --uninstall <skill-name>"}, indent=2))
            sys.exit(1)
        skill_name = args[idx + 1]
        result = uninstall_skill(skill_name)
        print(json.dumps(result, indent=2, ensure_ascii=False))
        sys.exit(0 if result["success"] else 1)

    # ── No arguments: show usage ──
    if not source and not do_detect:
        print(f"\n{_C.bold(_C.cyan('Skill Installer v' + VERSION))}\n")
        print(f"  {_C.bold('Install:')}")
        print(f"    --source <path>                  Install skill from path")
        print(f"    --source <path> --force           Overwrite if exists")
        print(f"    --source <path> --name <name>     Custom name override")
        print(f"    --source <path> --dry-run         Simulate without changes")
        print(f"    --detect                          Auto-detect uninstalled skills")
        print(f"    --detect --auto                   Detect and install all")
        print(f"")
        print(f"  {_C.bold('Manage:')}")
        print(f"    --uninstall <name>               Uninstall (with backup)")
        print(f"    --rollback <name>                Restore from latest backup")
        print(f"    --reinstall-all                  Re-register + re-package all skills")
        print(f"")
        print(f"  {_C.bold('Monitor:')}")
        print(f"    --health                         Health check all skills")
        print(f"    --health --repair                Health check + auto-fix issues")
        print(f"    --status                         Rich status dashboard")
        print(f"    --log [N]                        Show last N operations (default: 20)")
        print(f"")
        print(f"  {_C.bold('Flags:')}")
        print(f"    --json                           Output JSON instead of pretty text")
        print(f"    --force                          Force overwrite")
        print(f"    --dry-run                        Simulate without changes")
        print()
        sys.exit(1)

    # ── Install from source ──
    if source:
        result = install_single(source, name_override, force, dry_run=dry_run, verbose=not json_output)
        if json_output:
            print(json.dumps(result, indent=2, ensure_ascii=False))
        sys.exit(0 if result["success"] else 1)

    # ── Detection mode ──
    elif do_detect:
        resolve = step1_resolve_source(do_detect=True, auto=auto)

        if not resolve["success"]:
            print(json.dumps(resolve, indent=2, ensure_ascii=False))
            sys.exit(1)

        if resolve.get("interactive") and not auto:
            if json_output:
                print(json.dumps({
                    "mode": "interactive",
                    "message": "Skills detected but not installed.",
                    "candidates": resolve["candidates"],
                }, indent=2, ensure_ascii=False))
            else:
                print(f"\n{_C.bold('=== Detected Uninstalled Skills ===')}\n")
                for i, c in enumerate(resolve["candidates"], 1):
                    name = c.get("name", "?")
                    src = c.get("source_path", "?")
                    loc = c.get("location_type", "?")
                    valid = _C.green(_C.OK) if c.get("valid_frontmatter") else _C.red(_C.FAIL)
                    print(f"  {i}. {_C.bold(name)} {valid}")
                    print(f"     {_C.dim(src)} ({loc})")
                print(f"\n  Run with --auto to install all, or --source <path> to install one.\n")
            sys.exit(0)

        # Auto mode: install all candidates
        results = []
        for src in resolve["sources"]:
            r = install_single(src, force=force, dry_run=dry_run, verbose=not json_output)
            results.append(r)

        total = len(results)
        success = sum(1 for r in results if r["success"])
        failed = total - success

        summary = {
            "mode": "auto",
            "total": total,
            "success": success,
            "failed": failed,
            "results": results,
        }

        if json_output:
            print(json.dumps(summary, indent=2, ensure_ascii=False))
        sys.exit(0 if failed == 0 else 1)


if __name__ == "__main__":
    main()