empathy-framework 2.4.0__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_os/cli.py

@@ -1,5 +1,4 @@
-"""
-Command-Line Interface for Empathy Framework
+"""Command-Line Interface for Empathy Framework
 
 Provides CLI commands for:
 - Running interactive REPL (empathy run)
@@ -21,21 +20,274 @@ from importlib.metadata import version as get_version
 from empathy_os import EmpathyConfig, EmpathyOS, load_config
 from empathy_os.cost_tracker import cmd_costs
 from empathy_os.dashboard import cmd_dashboard
+from empathy_os.discovery import show_tip_if_available
 from empathy_os.logging_config import get_logger
 from empathy_os.pattern_library import PatternLibrary
 from empathy_os.persistence import MetricsCollector, PatternPersistence, StateManager
+from empathy_os.platform_utils import setup_asyncio_policy
 from empathy_os.templates import cmd_new
-from empathy_os.workflows import cmd_fix_all, cmd_learn, cmd_morning, cmd_ship
+from empathy_os.wizard_factory_cli import add_wizard_factory_commands
+from empathy_os.workflows import (
+    cmd_fix_all,
+    cmd_learn,
+    cmd_morning,
+    cmd_ship,
+    create_example_config,
+    get_workflow,
+)
+from empathy_os.workflows import list_workflows as get_workflow_list
 
 logger = get_logger(__name__)
 
 
+# =============================================================================
+# CHEATSHEET DATA - Quick reference for all commands
+# =============================================================================
+
+CHEATSHEET = {
+    "Getting Started": [
+        ("empathy init", "Create a new config file"),
+        ("empathy wizard", "Interactive setup wizard"),
+        ("empathy run", "Interactive REPL mode"),
+    ],
+    "Daily Workflow": [
+        ("empathy morning", "Start-of-day briefing"),
+        ("empathy status", "What needs attention now"),
+        ("empathy ship", "Pre-commit validation"),
+    ],
+    "Code Quality": [
+        ("empathy health", "Quick health check"),
+        ("empathy health --deep", "Comprehensive check"),
+        ("empathy health --fix", "Auto-fix issues"),
+        ("empathy fix-all", "Fix all lint/format issues"),
+    ],
+    "Pattern Learning": [
+        ("empathy learn --analyze 20", "Learn from last 20 commits"),
+        ("empathy sync-claude", "Sync patterns to Claude Code"),
+        ("empathy inspect patterns", "View learned patterns"),
+    ],
+    "Code Review": [
+        ("empathy review", "Review recent changes"),
+        ("empathy review --staged", "Review staged changes only"),
+    ],
+    "Memory & State": [
+        ("empathy inspect state", "View saved states"),
+        ("empathy inspect metrics --user-id X", "View user metrics"),
+        ("empathy export patterns.json", "Export patterns"),
+    ],
+    "Advanced": [
+        ("empathy costs", "View API cost tracking"),
+        ("empathy dashboard", "Launch visual dashboard"),
+        ("empathy frameworks", "List agent frameworks"),
+        ("empathy workflow list", "List multi-model workflows"),
+        ("empathy new <template>", "Create project from template"),
+    ],
+}
+
+EXPLAIN_CONTENT = {
+    "morning": """
+HOW 'empathy morning' WORKS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+This command aggregates multiple data sources to give you a prioritized
+start-of-day briefing:
+
+1. PATTERNS ANALYSIS
+   Reads ./patterns/*.json to find:
+   - Unresolved bugs (status: investigating)
+   - Recent security decisions
+   - Tech debt trends
+
+2. GIT CONTEXT
+   Checks your recent git activity:
+   - Commits from yesterday
+   - Uncommitted changes
+   - Branch status
+
+3. HEALTH SNAPSHOT
+   Runs quick health checks:
+   - Lint issues count
+   - Type errors
+   - Test status
+
+4. PRIORITY SCORING
+   Items are scored and sorted by:
+   - Age (older = higher priority)
+   - Severity (critical > high > medium)
+   - Your recent activity patterns
+
+TIPS:
+• Run this first thing each day
+• Use 'empathy morning --verbose' for details
+• Pair with 'empathy status --select N' to dive deeper
+""",
+    "ship": """
+HOW 'empathy ship' WORKS:
+━━━━━━━━━━━━━━━━━━━━━━━━━
+Pre-commit validation pipeline that ensures code quality before shipping:
+
+1. HEALTH CHECKS
+   - Runs lint checks (ruff/flake8)
+   - Validates types (mypy/pyright)
+   - Checks formatting (black/prettier)
+
+2. PATTERN REVIEW
+   - Compares changes against known bug patterns
+   - Flags code that matches historical issues
+   - Suggests fixes based on past resolutions
+
+3. SECURITY SCAN
+   - Checks for hardcoded secrets
+   - Validates against security patterns
+   - Reports potential vulnerabilities
+
+4. PATTERN SYNC (optional)
+   - Updates Claude Code rules
+   - Syncs new patterns discovered
+   - Skip with --skip-sync
+
+EXIT CODES:
+• 0 = All checks passed, safe to commit
+• 1 = Issues found, review before committing
+
+TIPS:
+• Add to pre-commit hook: empathy ship --skip-sync
+• Use 'empathy ship --verbose' to see all checks
+""",
+    "learn": """
+HOW 'empathy learn' WORKS:
+━━━━━━━━━━━━━━━━━━━━━━━━━
+Extracts patterns from your git history to teach Claude about your codebase:
+
+1. COMMIT ANALYSIS
+   Parses commit messages looking for:
+   - fix: Bug fixes → debugging.json
+   - security: decisions → security.json
+   - TODO/FIXME in code → tech_debt.json
+
+2. DIFF INSPECTION
+   Analyzes code changes to:
+   - Identify affected files
+   - Extract error types
+   - Record fix patterns
+
+3. PATTERN STORAGE
+   Saves to ./patterns/:
+   - debugging.json: Bug patterns
+   - security.json: Security decisions
+   - tech_debt.json: Technical debt
+   - inspection.json: Code review findings
+
+4. SUMMARY GENERATION
+   Creates .claude/patterns_summary.md:
+   - Human-readable pattern overview
+   - Loaded by Claude Code automatically
+
+USAGE EXAMPLES:
+• empathy learn --analyze 10    # Last 10 commits
+• empathy learn --analyze 100   # Deeper history
+• empathy sync-claude           # Apply patterns to Claude
+
+TIPS:
+• Run weekly to keep patterns current
+• Use good commit messages (fix:, feat:, etc.)
+• Check ./patterns/ to see what was learned
+""",
+    "health": """
+HOW 'empathy health' WORKS:
+━━━━━━━━━━━━━━━━━━━━━━━━━
+Code health dashboard that runs multiple quality checks:
+
+1. QUICK MODE (default)
+   Fast checks that run in seconds:
+   - Lint: ruff check or flake8
+   - Format: black --check or prettier
+   - Basic type checking
+
+2. DEEP MODE (--deep)
+   Comprehensive checks (slower):
+   - Full type analysis (mypy --strict)
+   - Test suite execution
+   - Security scanning
+   - Dependency audit
+
+3. SCORING
+   Health score 0-100 based on:
+   - Lint issues (×2 penalty each)
+   - Type errors (×5 penalty each)
+   - Test failures (×10 penalty each)
+   - Security issues (×20 penalty each)
+
+4. AUTO-FIX (--fix)
+   Can automatically fix:
+   - Formatting issues
+   - Import sorting
+   - Simple lint errors
+
+USAGE:
+• empathy health              # Quick check
+• empathy health --deep       # Full check
+• empathy health --fix        # Auto-fix issues
+• empathy health --trends 30  # 30-day trend
+
+TIPS:
+• Run quick checks before commits
+• Run deep checks in CI/CD
+• Track trends to catch regressions
+""",
+    "sync-claude": """
+HOW 'empathy sync-claude' WORKS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Converts learned patterns into Claude Code rules:
+
+1. READS PATTERNS
+   Loads from ./patterns/:
+   - debugging.json → Bug fix patterns
+   - security.json → Security decisions
+   - tech_debt.json → Known debt items
+
+2. GENERATES RULES
+   Creates .claude/rules/empathy/:
+   - debugging.md
+   - security.md
+   - tech_debt.md
+
+3. CLAUDE CODE INTEGRATION
+   Rules are automatically loaded when:
+   - Claude Code starts in this directory
+   - Combined with CLAUDE.md instructions
+
+HOW CLAUDE USES THESE:
+• Sees historical bugs before suggesting code
+• Knows about accepted security patterns
+• Understands existing tech debt
+
+FILE STRUCTURE:
+./patterns/             # Your pattern storage
+  debugging.json
+  security.json
+.claude/
+  CLAUDE.md             # Project instructions
+  rules/
+    empathy/            # Generated rules
+      debugging.md
+      security.md
+
+TIPS:
+• Run after 'empathy learn'
+• Commit .claude/rules/ to share with team
+• Weekly sync keeps Claude current
+""",
+}
+
+
 def cmd_version(args):
     """Display version information"""
     logger.info("Displaying version information")
     try:
         version = get_version("empathy")
-    except Exception:
+    except Exception as e:
+        # Package metadata not available or invalid (development install)
+        logger.debug(f"Version not available: {e}")
         version = "unknown"
     logger.info(f"Empathy v{version}")
     logger.info("Copyright 2025 Smart-AI-Memory")
@@ -43,6 +295,314 @@ def cmd_version(args):
     logger.info("\n✨ Built with Claude Code + MemDocs + VS Code transformative stack")
 
 
+def cmd_cheatsheet(args):
+    """Display quick reference cheatsheet for all commands."""
+    category = getattr(args, "category", None)
+    compact = getattr(args, "compact", False)
+
+    print()
+    print("=" * 60)
+    print("  EMPATHY FRAMEWORK - QUICK REFERENCE")
+    print("=" * 60)
+
+    if category:
+        # Show specific category
+        category_title = category.replace("-", " ").title()
+        if category_title in CHEATSHEET:
+            print(f"\n  {category_title}")
+            print("  " + "-" * 40)
+            for cmd, desc in CHEATSHEET[category_title]:
+                if compact:
+                    print(f"  {cmd}")
+                else:
+                    print(f"  {cmd:35} {desc}")
+        else:
+            print(f"\n  Unknown category: {category}")
+            print("  Available: " + ", ".join(k.lower().replace(" ", "-") for k in CHEATSHEET))
+    else:
+        # Show all categories
+        for cat_name, commands in CHEATSHEET.items():
+            print(f"\n  {cat_name}")
+            print("  " + "-" * 40)
+            for cmd, desc in commands:
+                if compact:
+                    print(f"  {cmd}")
+                else:
+                    print(f"  {cmd:35} {desc}")
+
+    print()
+    print("-" * 60)
+    print("  Use: empathy <command> --explain  for detailed explanation")
+    print("  Use: empathy onboard              for interactive tutorial")
+    print("=" * 60)
+    print()
+
+
+def cmd_onboard(args):
+    """Interactive onboarding tutorial for new users."""
+    from empathy_os.discovery import get_engine
+
+    step = getattr(args, "step", None)
+    reset = getattr(args, "reset", False)
+
+    engine = get_engine()
+    stats = engine.get_stats()
+
+    if reset:
+        # Reset onboarding progress
+        engine.state["onboarding_step"] = 0
+        engine.state["onboarding_completed"] = []
+        engine._save()
+        print("Onboarding progress reset.")
+        return
+
+    # Define onboarding steps
+    steps = [
+        {
+            "title": "Welcome to Empathy Framework",
+            "content": """
+Welcome! Empathy Framework helps you build AI systems with 5 levels
+of sophistication, from reactive responses to anticipatory assistance.
+
+This tutorial will walk you through the key features.
+
+Let's check your current setup first...
+""",
+            "check": lambda: True,
+            "action": None,
+        },
+        {
+            "title": "Step 1: Initialize Your Project",
+            "content": """
+First, let's create a configuration file for your project.
+
+Run: empathy init
+
+This creates empathy.config.yaml with sensible defaults.
+Alternatively, use 'empathy wizard' for an interactive setup.
+""",
+            "check": lambda: _file_exists("empathy.config.yaml")
+            or _file_exists("empathy.config.yml"),
+            "action": "empathy init",
+        },
+        {
+            "title": "Step 2: Learn From Your History",
+            "content": """
+Empathy can learn patterns from your git commit history.
+This teaches Claude about your codebase's patterns and past bugs.
+
+Run: empathy learn --analyze 10
+
+This analyzes the last 10 commits and extracts:
+- Bug fix patterns
+- Security decisions
+- Technical debt markers
+""",
+            "check": lambda: _file_exists("patterns/debugging.json"),
+            "action": "empathy learn --analyze 10",
+        },
+        {
+            "title": "Step 3: Sync Patterns to Claude",
+            "content": """
+Now let's share what we learned with Claude Code.
+
+Run: empathy sync-claude
+
+This creates .claude/rules/empathy/ with markdown rules
+that Claude Code automatically loads when you work in this directory.
+""",
+            "check": lambda: _file_exists(".claude/rules/empathy/debugging.md"),
+            "action": "empathy sync-claude",
+        },
+        {
+            "title": "Step 4: Check Code Health",
+            "content": """
+Let's run a quick health check on your codebase.
+
+Run: empathy health
+
+This checks:
+- Linting issues
+- Type errors
+- Formatting problems
+
+Try 'empathy health --fix' to auto-fix what's possible.
+""",
+            "check": lambda: stats.get("command_counts", {}).get("health", 0) > 0,
+            "action": "empathy health",
+        },
+        {
+            "title": "Step 5: Daily Workflow",
+            "content": """
+You're almost there! Here's your recommended daily workflow:
+
+MORNING:
+  empathy morning     - Get your priority briefing
+
+BEFORE COMMITS:
+  empathy ship        - Validate before committing
+
+WEEKLY:
+  empathy learn       - Update patterns from new commits
+  empathy sync-claude - Keep Claude current
+
+You've completed the basics! Run 'empathy cheatsheet' anytime
+for a quick reference of all commands.
+""",
+            "check": lambda: True,
+            "action": None,
+        },
+    ]
+
+    # Determine current step
+    current_step = engine.state.get("onboarding_step", 0)
+    if step is not None:
+        current_step = max(0, min(step - 1, len(steps) - 1))
+
+    step_data = steps[current_step]
+
+    # Display header
+    print()
+    print("=" * 60)
+    print(f"  ONBOARDING ({current_step + 1}/{len(steps)})")
+    print("=" * 60)
+    print()
+    print(f"  {step_data['title']}")
+    print("  " + "-" * 50)
+    print(step_data["content"])
+
+    # Check if step is completed
+    if step_data["check"]():
+        if current_step < len(steps) - 1:
+            print("  [DONE] This step is complete!")
+            print()
+            print(f"  Continue with: empathy onboard --step {current_step + 2}")
+            # Auto-advance
+            engine.state["onboarding_step"] = current_step + 1
+            engine._save()
+        else:
+            print("  Congratulations! You've completed the onboarding!")
+            print()
+            _show_achievements(engine)
+    elif step_data["action"]:
+        print(f"  NEXT: Run '{step_data['action']}'")
+        print("        Then run 'empathy onboard' to continue")
+
+    print()
+    print("-" * 60)
+    print(f"  Progress: {'*' * (current_step + 1)}{'.' * (len(steps) - current_step - 1)}")
+    print("=" * 60)
+    print()
+
+
+def _file_exists(path: str) -> bool:
+    """Check if a file exists."""
+    from pathlib import Path
+
+    return Path(path).exists()
+
+
+def _show_achievements(engine) -> None:
+    """Show user achievements based on usage."""
+    stats = engine.get_stats()
+
+    achievements = []
+    total_cmds = stats.get("total_commands", 0)
+    cmd_counts = stats.get("command_counts", {})
+
+    # Check achievements
+    if total_cmds >= 1:
+        achievements.append(("First Steps", "Ran your first command"))
+    if total_cmds >= 10:
+        achievements.append(("Getting Started", "Ran 10+ commands"))
+    if total_cmds >= 50:
+        achievements.append(("Power User", "Ran 50+ commands"))
+    if total_cmds >= 100:
+        achievements.append(("Expert", "Ran 100+ commands"))
+
+    if cmd_counts.get("learn", 0) >= 1:
+        achievements.append(("Pattern Learner", "Learned from git history"))
+    if cmd_counts.get("sync-claude", 0) >= 1:
+        achievements.append(("Claude Whisperer", "Synced patterns to Claude"))
+    if cmd_counts.get("morning", 0) >= 5:
+        achievements.append(("Early Bird", "Used morning briefing 5+ times"))
+    if cmd_counts.get("ship", 0) >= 10:
+        achievements.append(("Quality Shipper", "Used pre-commit checks 10+ times"))
+    if cmd_counts.get("health", 0) >= 1 and cmd_counts.get("fix-all", 0) >= 1:
+        achievements.append(("Code Doctor", "Used health checks and fixes"))
+
+    if stats.get("patterns_learned", 0) >= 10:
+        achievements.append(("Pattern Master", "Learned 10+ patterns"))
+
+    if stats.get("days_active", 0) >= 7:
+        achievements.append(("Week Warrior", "Active for 7+ days"))
+    if stats.get("days_active", 0) >= 30:
+        achievements.append(("Monthly Maven", "Active for 30+ days"))
+
+    if achievements:
+        print("  ACHIEVEMENTS UNLOCKED")
+        print("  " + "-" * 30)
+        for name, desc in achievements:
+            print(f"  * {name}: {desc}")
+        print()
+
+
+def cmd_explain(args):
+    """Show detailed explanation for a command."""
+    command = args.command
+
+    if command in EXPLAIN_CONTENT:
+        print(EXPLAIN_CONTENT[command])
+    else:
+        available = ", ".join(EXPLAIN_CONTENT.keys())
+        print(f"\nNo detailed explanation available for '{command}'")
+        print(f"Available: {available}")
+        print("\nTry: empathy cheatsheet  for a quick reference")
+        print()
+
+
+def cmd_achievements(args):
+    """Show user achievements and progress."""
+    from empathy_os.discovery import get_engine
+
+    engine = get_engine()
+    stats = engine.get_stats()
+
+    print()
+    print("=" * 60)
+    print("  YOUR EMPATHY FRAMEWORK JOURNEY")
+    print("=" * 60)
+    print()
+
+    # Stats summary
+    print("  STATISTICS")
+    print("  " + "-" * 40)
+    print(f"  Total commands run:    {stats.get('total_commands', 0)}")
+    print(f"  Days active:           {stats.get('days_active', 0)}")
+    print(f"  Patterns learned:      {stats.get('patterns_learned', 0)}")
+    shown = stats.get("tips_shown", 0)
+    total = shown + stats.get("tips_remaining", 0)
+    print(f"  Tips discovered:       {shown}/{total}")
+    print()
+
+    # Command breakdown
+    cmd_counts = stats.get("command_counts", {})
+    if cmd_counts:
+        print("  COMMAND USAGE")
+        print("  " + "-" * 40)
+        sorted_cmds = sorted(cmd_counts.items(), key=lambda x: x[1], reverse=True)
+        for cmd, count in sorted_cmds[:10]:
+            bar = "*" * min(count, 20)
+            print(f"  {cmd:15} {count:4} {bar}")
+        print()
+
+    # Achievements
+    _show_achievements(engine)
+
+    print("=" * 60)
+    print()
+
+
 def cmd_init(args):
     """Initialize a new Empathy Framework project"""
     config_format = args.format
@@ -83,10 +643,21 @@ def cmd_validate(args):
         logger.info(f"  Confidence Threshold: {config.confidence_threshold}")
         logger.info(f"  Persistence Backend: {config.persistence_backend}")
         logger.info(f"  Metrics Enabled: {config.metrics_enabled}")
-    except Exception as e:
+    except (OSError, FileNotFoundError) as e:
+        # Config file not found or cannot be read
+        logger.error(f"Configuration file error: {e}")
+        logger.error(f"✗ Cannot read configuration file: {e}")
+        sys.exit(1)
+    except ValueError as e:
+        # Invalid configuration values
         logger.error(f"Configuration validation failed: {e}")
         logger.error(f"✗ Configuration invalid: {e}")
         sys.exit(1)
+    except Exception as e:
+        # Unexpected errors during config validation
+        logger.exception(f"Unexpected error validating configuration: {e}")
+        logger.error(f"✗ Configuration invalid: {e}")
+        sys.exit(1)
 
 
 def cmd_info(args):
@@ -177,8 +748,19 @@ def cmd_patterns_export(args):
 
         logger.info(f"Loaded {len(library.patterns)} patterns from {input_file}")
         logger.info(f"✓ Loaded {len(library.patterns)} patterns from {input_file}")
+    except (OSError, FileNotFoundError) as e:
+        # Input file not found or cannot be read
+        logger.error(f"Pattern file error: {e}")
+        logger.error(f"✗ Cannot read pattern file: {e}")
+        sys.exit(1)
+    except (ValueError, KeyError) as e:
+        # Invalid pattern data format
+        logger.error(f"Pattern data error: {e}")
+        logger.error(f"✗ Invalid pattern data: {e}")
+        sys.exit(1)
     except Exception as e:
-        logger.error(f"Failed to load patterns: {e}")
+        # Unexpected errors loading patterns
+        logger.exception(f"Unexpected error loading patterns: {e}")
         logger.error(f"✗ Failed to load patterns: {e}")
         sys.exit(1)
 
@@ -191,8 +773,14 @@ def cmd_patterns_export(args):
 
         logger.info(f"Saved {len(library.patterns)} patterns to {output_file}")
         logger.info(f"✓ Saved {len(library.patterns)} patterns to {output_file}")
+    except (OSError, FileNotFoundError, PermissionError) as e:
+        # Cannot write output file
+        logger.error(f"Pattern file write error: {e}")
+        logger.error(f"✗ Cannot write pattern file: {e}")
+        sys.exit(1)
     except Exception as e:
-        logger.error(f"Failed to save patterns: {e}")
+        # Unexpected errors saving patterns
+        logger.exception(f"Unexpected error saving patterns: {e}")
         logger.error(f"✗ Failed to save patterns: {e}")
         sys.exit(1)
 
@@ -224,7 +812,7 @@ def cmd_patterns_resolve(args):
     if not args.root_cause or not args.fix:
         print("✗ --root-cause and --fix are required when resolving a bug")
         print(
-            "  Example: empathy patterns resolve bug_123 --root-cause 'Null check' --fix 'Added ?.'"
+            "  Example: empathy patterns resolve bug_123 --root-cause 'Null check' --fix 'Added ?.'",
         )
         sys.exit(1)
 
@@ -311,8 +899,8 @@ def cmd_review(args):
                 "files": args.files,
                 "staged_only": args.staged,
                 "severity_threshold": args.severity,
-            }
-        )
+            },
+        ),
     )
 
     # Output results
@@ -413,7 +1001,7 @@ def cmd_health(args):
                 print(f"\n⚠ Skipped {len(result['skipped'])} issue(s) (could not auto-fix)")
             else:
                 print(
-                    f"\n⚠ Skipped {len(result['skipped'])} issue(s) (use --interactive to review)"
+                    f"\n⚠ Skipped {len(result['skipped'])} issue(s) (use --interactive to review)",
                 )
 
         if result["failed"]:
@@ -484,8 +1072,19 @@ def cmd_metrics_show(args):
         logger.info(f"  Level 3: {stats.get('level_3_count', 0)} uses")
         logger.info(f"  Level 4: {stats.get('level_4_count', 0)} uses")
         logger.info(f"  Level 5: {stats.get('level_5_count', 0)} uses")
+    except (OSError, FileNotFoundError) as e:
+        # Database file not found
+        logger.error(f"Metrics database error: {e}")
+        logger.error(f"✗ Cannot read metrics database: {e}")
+        sys.exit(1)
+    except KeyError as e:
+        # User not found in database
+        logger.error(f"User not found in metrics: {e}")
+        logger.error(f"✗ User {user_id} not found: {e}")
+        sys.exit(1)
     except Exception as e:
-        logger.error(f"Failed to retrieve metrics for user {user_id}: {e}")
+        # Unexpected errors retrieving metrics
+        logger.exception(f"Unexpected error retrieving metrics for user {user_id}: {e}")
         logger.error(f"✗ Failed to retrieve metrics: {e}")
         sys.exit(1)
 
@@ -539,7 +1138,17 @@ def cmd_run(args):
             persistence_enabled=config.persistence_enabled,
         )
         print("✓ Empathy OS initialized")
+    except ValueError as e:
+        # Invalid configuration parameters
+        print(f"✗ Configuration error: {e}")
+        sys.exit(1)
+    except (OSError, FileNotFoundError, PermissionError) as e:
+        # Cannot access required files/directories
+        print(f"✗ File system error: {e}")
+        sys.exit(1)
     except Exception as e:
+        # Unexpected initialization failure
+        logger.exception(f"Unexpected error initializing Empathy OS: {e}")
         print(f"✗ Failed to initialize Empathy OS: {e}")
         sys.exit(1)
 
@@ -605,9 +1214,8 @@ def cmd_run(args):
                 for pred in response.predictions:
                     print(f"   • {pred}")
 
-            print(
-                f"\n  Level: {response.level} | Confidence: {response.confidence:.0%} | Time: {duration:.0f}ms"
-            )
+            conf = f"{response.confidence:.0%}"
+            print(f"\n  Level: {response.level} | Confidence: {conf} | Time: {duration:.0f}ms")
             print()
 
             # Ask for feedback
@@ -624,7 +1232,12 @@ def cmd_run(args):
         except KeyboardInterrupt:
             print("\n\n👋 Goodbye!")
             break
+        except (ValueError, KeyError) as e:
+            # Invalid input or response structure
+            print(f"\n✗ Input error: {e}\n")
         except Exception as e:
+            # Unexpected errors in interactive loop - log and continue
+            logger.exception(f"Unexpected error in interactive loop: {e}")
             print(f"\n✗ Error: {e}\n")
 
 
@@ -667,7 +1280,13 @@ def cmd_inspect(args):
             print(f"✗ Pattern library not found: {db_path}")
             print("  Tip: Use 'empathy-framework wizard' to set up your first project")
             sys.exit(1)
+        except (ValueError, KeyError) as e:
+            # Invalid pattern data format
+            print(f"✗ Invalid pattern data: {e}")
+            sys.exit(1)
         except Exception as e:
+            # Unexpected errors loading patterns
+            logger.exception(f"Unexpected error loading patterns: {e}")
             print(f"✗ Failed to load patterns: {e}")
             sys.exit(1)
 
@@ -689,7 +1308,17 @@ def cmd_inspect(args):
             for level in range(1, 6):
                 count = stats.get(f"level_{level}_count", 0)
                 print(f"    Level {level}: {count} times")
+        except (OSError, FileNotFoundError) as e:
+            # Database file not found
+            print(f"✗ Metrics database not found: {e}")
+            sys.exit(1)
+        except KeyError as e:
+            # User not found
+            print(f"✗ User {user_id} not found: {e}")
+            sys.exit(1)
         except Exception as e:
+            # Unexpected errors loading metrics
+            logger.exception(f"Unexpected error loading metrics: {e}")
             print(f"✗ Failed to load metrics: {e}")
             sys.exit(1)
 
@@ -706,7 +1335,13 @@ def cmd_inspect(args):
                 print("\n  Users:")
                 for uid in users:
                     print(f"    • {uid}")
+        except (OSError, FileNotFoundError) as e:
+            # State directory not found
+            print(f"✗ State directory not found: {e}")
+            sys.exit(1)
         except Exception as e:
+            # Unexpected errors loading state
+            logger.exception(f"Unexpected error loading state: {e}")
             print(f"✗ Failed to load state: {e}")
             sys.exit(1)
 
@@ -758,7 +1393,17 @@ def cmd_export(args):
         print(f"✗ Source file not found: {db_path}")
         print("  Tip: Patterns are saved automatically when using the framework")
         sys.exit(1)
+    except (OSError, PermissionError) as e:
+        # Cannot write output file
+        print(f"✗ Cannot write to file: {e}")
+        sys.exit(1)
+    except (ValueError, KeyError) as e:
+        # Invalid pattern data
+        print(f"✗ Invalid pattern data: {e}")
+        sys.exit(1)
     except Exception as e:
+        # Unexpected errors during export
+        logger.exception(f"Unexpected error exporting patterns: {e}")
         print(f"✗ Export failed: {e}")
         sys.exit(1)
 
@@ -811,7 +1456,17 @@ def cmd_import(args):
     except FileNotFoundError:
         print(f"✗ Input file not found: {input_file}")
         sys.exit(1)
+    except (ValueError, KeyError) as e:
+        # Invalid pattern data format
+        print(f"✗ Invalid pattern data: {e}")
+        sys.exit(1)
+    except (OSError, PermissionError) as e:
+        # Cannot read input or write to database
+        print(f"✗ File access error: {e}")
+        sys.exit(1)
     except Exception as e:
+        # Unexpected errors during import
+        logger.exception(f"Unexpected error importing patterns: {e}")
         print(f"✗ Import failed: {e}")
         sys.exit(1)
 
@@ -855,13 +1510,29 @@ def cmd_wizard(args):
     print("\n3. Which LLM provider will you use?")
     print("   [1] Anthropic Claude ⭐ Recommended")
     print("   [2] OpenAI GPT-4")
-    print("   [3] Local (Ollama)")
-    print("   [4] Skip (configure later)")
-
-    llm_choice = input("\nYour choice (1-4) [1]: ").strip() or "1"
-    llm_map = {"1": "anthropic", "2": "openai", "3": "ollama", "4": None}
+    print("   [3] Google Gemini (2M context)")
+    print("   [4] Local (Ollama)")
+    print("   [5] Hybrid (mix best models from each provider)")
+    print("   [6] Skip (configure later)")
+
+    llm_choice = input("\nYour choice (1-6) [1]: ").strip() or "1"
+    llm_map = {
+        "1": "anthropic",
+        "2": "openai",
+        "3": "google",
+        "4": "ollama",
+        "5": "hybrid",
+        "6": None,
+    }
     llm_provider = llm_map.get(llm_choice, "anthropic")
 
+    # If hybrid selected, launch interactive tier selection
+    if llm_provider == "hybrid":
+        from empathy_os.models.provider_config import configure_hybrid_interactive
+
+        configure_hybrid_interactive()
+        llm_provider = None  # Already saved by hybrid config
+
     # Step 4: User ID
     print("\n4. What user ID should we use?")
     user_id = input("User ID [default_user]: ").strip() or "default_user"
@@ -922,14 +1593,541 @@ llm_provider: "{llm_provider}"
     print("\nNext steps:")
     print(f"  1. Edit {output_file} to customize settings")
 
-    if llm_provider in ["anthropic", "openai"]:
-        env_var = "ANTHROPIC_API_KEY" if llm_provider == "anthropic" else "OPENAI_API_KEY"
+    if llm_provider in ["anthropic", "openai", "google"]:
+        env_var_map = {
+            "anthropic": "ANTHROPIC_API_KEY",
+            "openai": "OPENAI_API_KEY",
+            "google": "GOOGLE_API_KEY",
+        }
+        env_var = env_var_map.get(llm_provider, "API_KEY")
         print(f"  2. Set {env_var} environment variable")
 
     print("  3. Run: empathy-framework run --config empathy.config.yml")
     print("\nHappy empathizing! 🧠✨\n")
 
 
+def cmd_provider_hybrid(args):
+    """Configure hybrid mode - pick best models for each tier."""
+    from empathy_os.models.provider_config import configure_hybrid_interactive
+
+    configure_hybrid_interactive()
+
+
+def cmd_provider_show(args):
+    """Show current provider configuration."""
+    from empathy_os.models.provider_config import ProviderConfig
+    from empathy_os.workflows.config import WorkflowConfig
+
+    print("\n" + "=" * 60)
+    print("Provider Configuration")
+    print("=" * 60)
+
+    # Detect available providers
+    config = ProviderConfig.auto_detect()
+    print(
+        f"\nDetected API keys for: {', '.join(config.available_providers) if config.available_providers else 'None'}",
+    )
+
+    # Load workflow config
+    wf_config = WorkflowConfig.load()
+    print(f"\nDefault provider: {wf_config.default_provider}")
+
+    # Show effective models
+    print("\nEffective model mapping:")
+    if wf_config.custom_models and "hybrid" in wf_config.custom_models:
+        hybrid = wf_config.custom_models["hybrid"]
+        for tier in ["cheap", "capable", "premium"]:
+            model = hybrid.get(tier, "not configured")
+            print(f"  {tier:8} → {model}")
+    else:
+        from empathy_os.models import MODEL_REGISTRY
+
+        provider = wf_config.default_provider
+        if provider in MODEL_REGISTRY:
+            for tier in ["cheap", "capable", "premium"]:
+                model_info = MODEL_REGISTRY[provider].get(tier)
+                if model_info:
+                    print(f"  {tier:8} → {model_info.id} ({provider})")
+
+    print()
+
+
+def cmd_provider_set(args):
+    """Set default provider."""
+    from pathlib import Path
+
+    import yaml
+
+    provider = args.name
+    workflows_path = Path(".empathy/workflows.yaml")
+
+    # Load existing config or create new
+    if workflows_path.exists():
+        with open(workflows_path) as f:
+            config = yaml.safe_load(f) or {}
+    else:
+        config = {}
+        workflows_path.parent.mkdir(parents=True, exist_ok=True)
+
+    config["default_provider"] = provider
+
+    with open(workflows_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+    print(f"✓ Default provider set to: {provider}")
+    print(f"  Saved to: {workflows_path}")
+
+    if provider == "hybrid":
+        print("\n  Tip: Run 'empathy provider hybrid' to customize tier models")
+
+
+def cmd_sync_claude(args):
+    """Sync patterns to Claude Code rules directory."""
+    import json as json_mod
+    from pathlib import Path
+
+    patterns_dir = Path(args.patterns_dir)
+    output_dir = Path(args.output_dir)
+
+    print("=" * 60)
+    print("  SYNC PATTERNS TO CLAUDE CODE")
+    print("=" * 60 + "\n")
+
+    if not patterns_dir.exists():
+        print(f"✗ Patterns directory not found: {patterns_dir}")
+        print("  Run 'empathy learn --analyze 20' first to learn patterns")
+        return 1
+
+    # Create output directory
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    synced_count = 0
+    pattern_files = ["debugging.json", "security.json", "tech_debt.json", "inspection.json"]
+
+    for pattern_file in pattern_files:
+        source_path = patterns_dir / pattern_file
+        if not source_path.exists():
+            continue
+
+        try:
+            with open(source_path) as f:
+                data = json_mod.load(f)
+
+            patterns = data.get("patterns", data.get("items", []))
+            if not patterns:
+                continue
+
+            # Generate markdown rule file
+            category = pattern_file.replace(".json", "")
+            rule_content = _generate_claude_rule(category, patterns)
+
+            # Write rule file
+            rule_file = output_dir / f"{category}.md"
+            with open(rule_file, "w") as f:
+                f.write(rule_content)
+
+            print(f"  ✓ {category}: {len(patterns)} patterns → {rule_file}")
+            synced_count += len(patterns)
+
+        except (json_mod.JSONDecodeError, OSError) as e:
+            print(f"  ✗ Failed to process {pattern_file}: {e}")
+
+    print(f"\n{'─' * 60}")
+    print(f"  Total: {synced_count} patterns synced to {output_dir}")
+    print("=" * 60 + "\n")
+
+    if synced_count == 0:
+        print("No patterns to sync. Run 'empathy learn' first.")
+        return 1
+
+    return 0
+
+
+def _generate_claude_rule(category: str, patterns: list) -> str:
+    """Generate a Claude Code rule file from patterns."""
+    lines = [
+        f"# {category.replace('_', ' ').title()} Patterns",
+        "",
+        "Auto-generated from Empathy Framework learned patterns.",
+        f"Total patterns: {len(patterns)}",
+        "",
+        "---",
+        "",
+    ]
+
+    if category == "debugging":
+        lines.extend(
+            [
+                "## Bug Fix Patterns",
+                "",
+                "When debugging similar issues, consider these historical fixes:",
+                "",
+            ],
+        )
+        for p in patterns[:20]:  # Limit to 20 most recent
+            bug_type = p.get("bug_type", "unknown")
+            root_cause = p.get("root_cause", "Unknown")
+            fix = p.get("fix", "See commit history")
+            files = p.get("files_affected", [])
+
+            lines.append(f"### {bug_type}")
+            lines.append(f"- **Root cause**: {root_cause}")
+            lines.append(f"- **Fix**: {fix}")
+            if files:
+                lines.append(f"- **Files**: {', '.join(files[:3])}")
+            lines.append("")
+
+    elif category == "security":
+        lines.extend(
+            [
+                "## Security Decisions",
+                "",
+                "Previously reviewed security items:",
+                "",
+            ],
+        )
+        for p in patterns[:20]:
+            decision = p.get("decision", "unknown")
+            reason = p.get("reason", "")
+            lines.append(f"- **{p.get('type', 'unknown')}**: {decision}")
+            if reason:
+                lines.append(f"  - Reason: {reason}")
+            lines.append("")
+
+    elif category == "tech_debt":
+        lines.extend(
+            [
+                "## Tech Debt Tracking",
+                "",
+                "Known technical debt items:",
+                "",
+            ],
+        )
+        for p in patterns[:20]:
+            lines.append(f"- {p.get('description', str(p))}")
+
+    else:
+        lines.extend(
+            [
+                f"## {category.title()} Items",
+                "",
+            ],
+        )
+        for p in patterns[:20]:
+            lines.append(f"- {p.get('description', str(p)[:100])}")
+
+    return "\n".join(lines)
+
+
+def _extract_workflow_content(final_output):
+    """Extract readable content from workflow final_output.
+
+    Workflows return their results in various formats - this extracts
+    the actual content users want to see.
+    """
+    if final_output is None:
+        return None
+
+    # If it's already a string, return it
+    if isinstance(final_output, str):
+        return final_output
+
+    # If it's a dict, try to extract meaningful content
+    if isinstance(final_output, dict):
+        # Common keys that contain the main output
+        # formatted_report is first - preferred for security-audit and other formatted outputs
+        content_keys = [
+            "formatted_report",  # Human-readable formatted output (security-audit, etc.)
+            "answer",
+            "synthesis",
+            "result",
+            "output",
+            "content",
+            "report",
+            "summary",
+            "analysis",
+            "review",
+            "documentation",
+            "response",
+            "recommendations",
+            "findings",
+            "tests",
+            "plan",
+        ]
+        for key in content_keys:
+            if final_output.get(key):
+                val = final_output[key]
+                if isinstance(val, str):
+                    return val
+                if isinstance(val, dict):
+                    # Recursively extract
+                    return _extract_workflow_content(val)
+
+        # If no common key found, try to format the dict nicely
+        # Look for any string value that's substantial
+        for _key, val in final_output.items():
+            if isinstance(val, str) and len(val) > 100:
+                return val
+
+        # Last resort: return a formatted version
+        import json
+
+        return json.dumps(final_output, indent=2)
+
+    # For lists or other types, convert to string
+    return str(final_output)
+
+
+def cmd_workflow(args):
+    """Multi-model workflow management and execution."""
+    import asyncio
+    import json as json_mod
+
+    action = args.action
+
+    if action == "list":
+        # List available workflows
+        workflows = get_workflow_list()
+
+        if args.json:
+            print(json_mod.dumps(workflows, indent=2))
+        else:
+            print("\n" + "=" * 60)
+            print("  MULTI-MODEL WORKFLOWS")
+            print("=" * 60 + "\n")
+
+            for wf in workflows:
+                print(f"  {wf['name']:15} {wf['description']}")
+                stages = " → ".join(f"{s}({wf['tier_map'][s]})" for s in wf["stages"])
+                print(f"    Stages: {stages}")
+                print()
+
+            print("-" * 60)
+            print("  Use: empathy workflow describe <name>")
+            print("  Use: empathy workflow run <name> [--input JSON]")
+            print("=" * 60 + "\n")
+
+    elif action == "describe":
+        # Describe a specific workflow
+        name = args.name
+        if not name:
+            print("Error: workflow name required")
+            print("Usage: empathy workflow describe <name>")
+            return 1
+
+        try:
+            workflow_cls = get_workflow(name)
+            provider = getattr(args, "provider", None)
+            workflow = workflow_cls(provider=provider)
+
+            # Get actual provider from workflow (may come from config)
+            actual_provider = getattr(workflow, "_provider_str", provider or "anthropic")
+
+            if args.json:
+                info = {
+                    "name": workflow.name,
+                    "description": workflow.description,
+                    "provider": actual_provider,
+                    "stages": workflow.stages,
+                    "tier_map": {k: v.value for k, v in workflow.tier_map.items()},
+                    "models": {
+                        stage: workflow.get_model_for_tier(workflow.tier_map[stage])
+                        for stage in workflow.stages
+                    },
+                }
+                print(json_mod.dumps(info, indent=2))
+            else:
+                print(f"Provider: {actual_provider}")
+                print(workflow.describe())
+
+        except KeyError as e:
+            print(f"Error: {e}")
+            return 1
+
+    elif action == "run":
+        # Run a workflow
+        name = args.name
+        if not name:
+            print("Error: workflow name required")
+            print('Usage: empathy workflow run <name> --input \'{"key": "value"}\'')
+            return 1
+
+        try:
+            workflow_cls = get_workflow(name)
+
+            # Get provider from CLI arg, or fall back to config's default_provider
+            if args.provider:
+                provider = args.provider
+            else:
+                from empathy_os.workflows.config import WorkflowConfig
+
+                wf_config = WorkflowConfig.load()
+                provider = wf_config.default_provider
+            workflow = workflow_cls(provider=provider)
+
+            # Parse input
+            input_data = {}
+            if args.input:
+                input_data = json_mod.loads(args.input)
+
+            # Add test-gen specific flags to input_data (only for test-gen workflow)
+            if name == "test-gen":
+                if getattr(args, "write_tests", False):
+                    input_data["write_tests"] = True
+                if getattr(args, "output_dir", None):
+                    input_data["output_dir"] = args.output_dir
+
+            # Only print header when not in JSON mode
+            if not args.json:
+                print(f"\n Running workflow: {name} (provider: {provider})")
+                print("=" * 50)
+
+            # Execute workflow
+            result = asyncio.run(workflow.execute(**input_data))
+
+            # Extract the actual content - handle different result types
+            if hasattr(result, "final_output"):
+                output_content = _extract_workflow_content(result.final_output)
+            elif hasattr(result, "metadata") and isinstance(result.metadata, dict):
+                # Check for formatted_report in metadata (e.g., HealthCheckResult)
+                output_content = result.metadata.get("formatted_report")
+                if not output_content and hasattr(result, "summary"):
+                    output_content = result.summary
+            elif hasattr(result, "summary"):
+                output_content = result.summary
+            else:
+                output_content = str(result)
+
+            # Get timing - handle different attribute names
+            duration_ms = getattr(result, "total_duration_ms", None)
+            if duration_ms is None and hasattr(result, "duration_seconds"):
+                duration_ms = int(result.duration_seconds * 1000)
+
+            # Get cost info if available (check cost_report first, then direct cost attribute)
+            cost_report = getattr(result, "cost_report", None)
+            if cost_report and hasattr(cost_report, "total_cost"):
+                total_cost = cost_report.total_cost
+                savings = getattr(cost_report, "savings", 0.0)
+            else:
+                # Fall back to direct cost attribute (e.g., CodeReviewPipelineResult)
+                total_cost = getattr(result, "cost", 0.0)
+                savings = 0.0
+
+            if args.json:
+                # Extract error from various result types
+                error = getattr(result, "error", None)
+                if not error and not result.success:
+                    blockers = getattr(result, "blockers", [])
+                    if blockers:
+                        error = "; ".join(blockers)
+                    else:
+                        metadata = getattr(result, "metadata", {})
+                        error = metadata.get("error") if isinstance(metadata, dict) else None
+
+                # JSON output includes both content and metadata
+                # Include final_output for programmatic access (VSCode panels, etc.)
+                raw_final_output = getattr(result, "final_output", None)
+                if raw_final_output and isinstance(raw_final_output, dict):
+                    # Make a copy to avoid modifying the original
+                    final_output_serializable = {}
+                    for k, v in raw_final_output.items():
+                        # Skip non-serializable items
+                        if isinstance(v, set):
+                            final_output_serializable[k] = list(v)
+                        elif v is None or isinstance(v, str | int | float | bool | list | dict):
+                            final_output_serializable[k] = v
+                        else:
+                            try:
+                                final_output_serializable[k] = str(v)
+                            except Exception as e:  # noqa: BLE001
+                                # INTENTIONAL: Silently skip any non-serializable objects
+                                # This is a best-effort serialization for JSON output
+                                # We cannot predict all possible object types users might return
+                                logger.debug(f"Cannot serialize field {k}: {e}")
+                                pass
+                else:
+                    final_output_serializable = None
+
+                output = {
+                    "success": result.success,
+                    "output": output_content,
+                    "final_output": final_output_serializable,
+                    "cost": total_cost,
+                    "savings": savings,
+                    "duration_ms": duration_ms or 0,
+                    "error": error,
+                }
+                print(json_mod.dumps(output, indent=2))
+            # Display the actual results - this is what users want to see
+            elif result.success:
+                if output_content:
+                    print(f"\n{output_content}\n")
+                else:
+                    print("\n✓ Workflow completed successfully.\n")
+            else:
+                # Extract error from various result types
+                error_msg = getattr(result, "error", None)
+                if not error_msg:
+                    # Check for blockers (CodeReviewPipelineResult)
+                    blockers = getattr(result, "blockers", [])
+                    if blockers:
+                        error_msg = "; ".join(blockers)
+                    else:
+                        # Check metadata for error
+                        metadata = getattr(result, "metadata", {})
+                        error_msg = metadata.get("error") if isinstance(metadata, dict) else None
+                error_msg = error_msg or "Unknown error"
+                print(f"\n✗ Workflow failed: {error_msg}\n")
+
+        except KeyError as e:
+            print(f"Error: {e}")
+            return 1
+        except json_mod.JSONDecodeError as e:
+            print(f"Error parsing input JSON: {e}")
+            return 1
+
+    elif action == "config":
+        # Generate or show workflow configuration
+        from pathlib import Path
+
+        config_path = Path(".empathy/workflows.yaml")
+
+        if config_path.exists() and not getattr(args, "force", False):
+            print(f"Config already exists: {config_path}")
+            print("Use --force to overwrite")
+            print("\nCurrent configuration:")
+            print("-" * 40)
+            config = WorkflowConfig.load()
+            print(f"  Default provider: {config.default_provider}")
+            if config.workflow_providers:
+                print("  Workflow providers:")
+                for wf, prov in config.workflow_providers.items():
+                    print(f"    {wf}: {prov}")
+            if config.custom_models:
+                print("  Custom models configured")
+            return 0
+
+        # Create config directory and file
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(create_example_config())
+        print(f"✓ Created workflow config: {config_path}")
+        print("\nEdit this file to customize:")
+        print("  - Default provider (anthropic, openai, ollama)")
+        print("  - Per-workflow provider overrides")
+        print("  - Custom model mappings")
+        print("  - Model pricing")
+        print("\nOr use environment variables:")
+        print("  EMPATHY_WORKFLOW_PROVIDER=openai")
+        print("  EMPATHY_MODEL_PREMIUM=gpt-5.2")
+
+    else:
+        print(f"Unknown action: {action}")
+        print("Available: list, describe, run, config")
+        return 1
+
+    return 0
+
+
 def cmd_frameworks(args):
     """List and manage agent frameworks."""
     import json as json_mod
@@ -958,7 +2156,7 @@ def cmd_frameworks(args):
                 json_mod.dumps(
                     {"use_case": recommend_use_case, "recommended": recommended.value, **info},
                     indent=2,
-                )
+                ),
             )
         else:
             print(f"\nRecommended framework for '{recommend_use_case}': {info['name']}")
@@ -985,7 +2183,7 @@ def cmd_frameworks(args):
                     for f in frameworks
                 ],
                 indent=2,
-            )
+            ),
         )
     else:
         print("\n" + "=" * 60)
@@ -1010,6 +2208,9 @@ def cmd_frameworks(args):
 
 def main():
     """Main CLI entry point"""
+    # Configure Windows-compatible asyncio event loop policy
+    setup_asyncio_policy()
+
     parser = argparse.ArgumentParser(
         prog="empathy",
         description="Empathy - Build AI systems with 5 levels of empathy",
@@ -1062,32 +2263,45 @@ def main():
     parser_patterns_export.add_argument("input", help="Input file path")
     parser_patterns_export.add_argument("output", help="Output file path")
     parser_patterns_export.add_argument(
-        "--input-format", choices=["json", "sqlite"], default="json"
+        "--input-format",
+        choices=["json", "sqlite"],
+        default="json",
     )
     parser_patterns_export.add_argument(
-        "--output-format", choices=["json", "sqlite"], default="json"
+        "--output-format",
+        choices=["json", "sqlite"],
+        default="json",
     )
     parser_patterns_export.set_defaults(func=cmd_patterns_export)
 
     # Patterns resolve - mark investigating bugs as resolved
     parser_patterns_resolve = patterns_subparsers.add_parser(
-        "resolve", help="Resolve investigating bug patterns"
+        "resolve",
+        help="Resolve investigating bug patterns",
     )
     parser_patterns_resolve.add_argument(
-        "bug_id", nargs="?", help="Bug ID to resolve (omit to list investigating)"
+        "bug_id",
+        nargs="?",
+        help="Bug ID to resolve (omit to list investigating)",
     )
     parser_patterns_resolve.add_argument("--root-cause", help="Description of the root cause")
     parser_patterns_resolve.add_argument("--fix", help="Description of the fix applied")
     parser_patterns_resolve.add_argument("--fix-code", help="Code snippet of the fix")
     parser_patterns_resolve.add_argument("--time", type=int, help="Resolution time in minutes")
     parser_patterns_resolve.add_argument(
-        "--resolved-by", default="@developer", help="Who resolved it"
+        "--resolved-by",
+        default="@developer",
+        help="Who resolved it",
     )
     parser_patterns_resolve.add_argument(
-        "--patterns-dir", default="./patterns", help="Path to patterns directory"
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
     )
     parser_patterns_resolve.add_argument(
-        "--no-regenerate", action="store_true", help="Skip regenerating summary"
+        "--no-regenerate",
+        action="store_true",
+        help="Skip regenerating summary",
     )
     parser_patterns_resolve.set_defaults(func=cmd_patterns_resolve)
 
@@ -1108,7 +2322,9 @@ def main():
     # State list
     parser_state_list = state_subparsers.add_parser("list", help="List saved states")
     parser_state_list.add_argument(
-        "--state-dir", default="./empathy_state", help="State directory path"
+        "--state-dir",
+        default="./empathy_state",
+        help="State directory path",
     )
     parser_state_list.set_defaults(func=cmd_state_list)
 
@@ -1117,7 +2333,10 @@ def main():
     parser_run.add_argument("--config", "-c", help="Configuration file path")
     parser_run.add_argument("--user-id", help="User ID (default: cli_user)")
     parser_run.add_argument(
-        "--level", type=int, default=4, help="Target empathy level (1-5, default: 4)"
+        "--level",
+        type=int,
+        default=4,
+        help="Target empathy level (1-5, default: 4)",
     )
     parser_run.set_defaults(func=cmd_run)
 
@@ -1131,21 +2350,27 @@ def main():
     parser_inspect.add_argument("--user-id", help="User ID to filter by (optional)")
     parser_inspect.add_argument("--db", help="Database path (default: .empathy/patterns.db)")
     parser_inspect.add_argument(
-        "--state-dir", help="State directory path (default: .empathy/state)"
+        "--state-dir",
+        help="State directory path (default: .empathy/state)",
     )
     parser_inspect.set_defaults(func=cmd_inspect)
 
     # Export command
     parser_export = subparsers.add_parser(
-        "export", help="Export patterns to file for sharing/backup"
+        "export",
+        help="Export patterns to file for sharing/backup",
     )
     parser_export.add_argument("output", help="Output file path")
     parser_export.add_argument(
-        "--user-id", help="User ID to export (optional, exports all if not specified)"
+        "--user-id",
+        help="User ID to export (optional, exports all if not specified)",
     )
     parser_export.add_argument("--db", help="Database path (default: .empathy/patterns.db)")
     parser_export.add_argument(
-        "--format", default="json", choices=["json"], help="Export format (default: json)"
+        "--format",
+        default="json",
+        choices=["json"],
+        help="Export format (default: json)",
     )
     parser_export.set_defaults(func=cmd_export)
 
@@ -1157,20 +2382,59 @@ def main():
 
     # Wizard command (Interactive setup)
     parser_wizard = subparsers.add_parser(
-        "wizard", help="Interactive setup wizard for creating configuration"
+        "wizard",
+        help="Interactive setup wizard for creating configuration",
     )
     parser_wizard.set_defaults(func=cmd_wizard)
 
+    # Provider command (Model provider configuration)
+    parser_provider = subparsers.add_parser(
+        "provider",
+        help="Configure model providers and hybrid mode",
+    )
+    provider_subparsers = parser_provider.add_subparsers(dest="provider_cmd")
+
+    # provider hybrid - Interactive hybrid configuration
+    parser_provider_hybrid = provider_subparsers.add_parser(
+        "hybrid",
+        help="Configure hybrid mode - pick best models for each tier",
+    )
+    parser_provider_hybrid.set_defaults(func=cmd_provider_hybrid)
+
+    # provider show - Show current configuration
+    parser_provider_show = provider_subparsers.add_parser(
+        "show",
+        help="Show current provider configuration",
+    )
+    parser_provider_show.set_defaults(func=cmd_provider_show)
+
+    # provider set - Quick set single provider
+    parser_provider_set = provider_subparsers.add_parser(
+        "set",
+        help="Set default provider (anthropic, openai, google, ollama)",
+    )
+    parser_provider_set.add_argument(
+        "name",
+        choices=["anthropic", "openai", "google", "ollama", "hybrid"],
+        help="Provider name",
+    )
+    parser_provider_set.set_defaults(func=cmd_provider_set)
+
     # Status command (Session status assistant)
     parser_status = subparsers.add_parser(
-        "status", help="Session status - prioritized project status report"
+        "status",
+        help="Session status - prioritized project status report",
     )
     parser_status.add_argument(
-        "--patterns-dir", default="./patterns", help="Path to patterns directory"
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
     )
     parser_status.add_argument("--project-root", default=".", help="Project root directory")
     parser_status.add_argument(
-        "--force", action="store_true", help="Force show status regardless of inactivity"
+        "--force",
+        action="store_true",
+        help="Force show status regardless of inactivity",
     )
     parser_status.add_argument("--full", action="store_true", help="Show all items (no limit)")
     parser_status.add_argument("--json", action="store_true", help="Output as JSON")
@@ -1185,7 +2449,8 @@ def main():
 
     # Review command (Pattern-based code review)
     parser_review = subparsers.add_parser(
-        "review", help="Pattern-based code review against historical bugs"
+        "review",
+        help="Pattern-based code review against historical bugs",
     )
     parser_review.add_argument("files", nargs="*", help="Files to review (default: recent changes)")
     parser_review.add_argument("--staged", action="store_true", help="Review staged changes only")
@@ -1201,10 +2466,13 @@ def main():
 
     # Health command (Code Health Assistant)
     parser_health = subparsers.add_parser(
-        "health", help="Code health assistant - run checks and auto-fix issues"
+        "health",
+        help="Code health assistant - run checks and auto-fix issues",
     )
     parser_health.add_argument(
-        "--deep", action="store_true", help="Run comprehensive checks (slower)"
+        "--deep",
+        action="store_true",
+        help="Run comprehensive checks (slower)",
     )
     parser_health.add_argument(
         "--check",
@@ -1213,20 +2481,31 @@ def main():
     )
     parser_health.add_argument("--fix", action="store_true", help="Auto-fix issues where possible")
     parser_health.add_argument(
-        "--dry-run", action="store_true", help="Show what would be fixed without applying"
+        "--dry-run",
+        action="store_true",
+        help="Show what would be fixed without applying",
     )
     parser_health.add_argument(
-        "--interactive", action="store_true", help="Prompt before applying non-safe fixes"
+        "--interactive",
+        action="store_true",
+        help="Prompt before applying non-safe fixes",
     )
     parser_health.add_argument("--details", action="store_true", help="Show detailed issue list")
     parser_health.add_argument(
-        "--full", action="store_true", help="Show full report with all details"
+        "--full",
+        action="store_true",
+        help="Show full report with all details",
     )
     parser_health.add_argument(
-        "--trends", type=int, metavar="DAYS", help="Show health trends over N days"
+        "--trends",
+        type=int,
+        metavar="DAYS",
+        help="Show health trends over N days",
     )
     parser_health.add_argument(
-        "--project-root", default=".", help="Project root directory (default: current)"
+        "--project-root",
+        default=".",
+        help="Project root directory (default: current)",
     )
     parser_health.add_argument("--json", action="store_true", help="Output as JSON")
     parser_health.set_defaults(func=cmd_health)
@@ -1237,10 +2516,13 @@ def main():
 
     # Morning command (start-of-day briefing)
     parser_morning = subparsers.add_parser(
-        "morning", help="Start-of-day briefing with patterns, debt, and focus areas"
+        "morning",
+        help="Start-of-day briefing with patterns, debt, and focus areas",
     )
     parser_morning.add_argument(
-        "--patterns-dir", default="./patterns", help="Path to patterns directory"
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
     )
     parser_morning.add_argument("--project-root", default=".", help="Project root directory")
     parser_morning.add_argument("--verbose", "-v", action="store_true", help="Show detailed output")
@@ -1249,48 +2531,77 @@ def main():
     # Ship command (pre-commit validation)
     parser_ship = subparsers.add_parser("ship", help="Pre-commit validation pipeline")
     parser_ship.add_argument(
-        "--patterns-dir", default="./patterns", help="Path to patterns directory"
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
     )
     parser_ship.add_argument("--project-root", default=".", help="Project root directory")
     parser_ship.add_argument(
-        "--skip-sync", action="store_true", help="Skip syncing patterns to Claude"
+        "--skip-sync",
+        action="store_true",
+        help="Skip syncing patterns to Claude",
+    )
+    parser_ship.add_argument(
+        "--tests-only",
+        action="store_true",
+        help="Run tests only (skip lint/format checks)",
+    )
+    parser_ship.add_argument(
+        "--security-only",
+        action="store_true",
+        help="Run security checks only",
     )
     parser_ship.add_argument("--verbose", "-v", action="store_true", help="Show detailed output")
     parser_ship.set_defaults(func=cmd_ship)
 
     # Fix-all command (auto-fix everything)
     parser_fix_all = subparsers.add_parser(
-        "fix-all", help="Auto-fix all fixable lint and format issues"
+        "fix-all",
+        help="Auto-fix all fixable lint and format issues",
     )
     parser_fix_all.add_argument("--project-root", default=".", help="Project root directory")
     parser_fix_all.add_argument(
-        "--dry-run", action="store_true", help="Show what would be fixed without applying"
+        "--dry-run",
+        action="store_true",
+        help="Show what would be fixed without applying",
     )
     parser_fix_all.add_argument("--verbose", "-v", action="store_true", help="Show detailed output")
     parser_fix_all.set_defaults(func=cmd_fix_all)
 
     # Learn command (pattern learning from git history)
     parser_learn = subparsers.add_parser(
-        "learn", help="Learn patterns from git history and bug fixes"
+        "learn",
+        help="Learn patterns from git history and bug fixes",
     )
     parser_learn.add_argument(
-        "--patterns-dir", default="./patterns", help="Path to patterns directory"
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
     )
     parser_learn.add_argument(
-        "--analyze", type=int, metavar="N", help="Analyze last N commits (default: 10)"
+        "--analyze",
+        type=int,
+        metavar="N",
+        help="Analyze last N commits (default: 10)",
     )
     parser_learn.add_argument(
-        "--watch", action="store_true", help="Watch for new commits (not yet implemented)"
+        "--watch",
+        action="store_true",
+        help="Watch for new commits (not yet implemented)",
     )
     parser_learn.add_argument("--verbose", "-v", action="store_true", help="Show detailed output")
     parser_learn.set_defaults(func=cmd_learn)
 
     # Costs command (cost tracking dashboard)
     parser_costs = subparsers.add_parser(
-        "costs", help="View API cost tracking and savings from model routing"
+        "costs",
+        help="View API cost tracking and savings from model routing",
     )
     parser_costs.add_argument(
-        "--days", type=int, default=7, help="Number of days to include (default: 7)"
+        "--days",
+        type=int,
+        default=7,
+        help="Number of days to include (default: 7)",
     )
     parser_costs.add_argument("--empathy-dir", default=".empathy", help="Empathy data directory")
     parser_costs.add_argument("--json", action="store_true", help="Output as JSON")
@@ -1312,16 +2623,25 @@ def main():
     # Dashboard command (visual web interface)
     parser_dashboard = subparsers.add_parser("dashboard", help="Launch visual dashboard in browser")
     parser_dashboard.add_argument(
-        "--port", type=int, default=8765, help="Port to run on (default: 8765)"
+        "--port",
+        type=int,
+        default=8765,
+        help="Port to run on (default: 8765)",
     )
     parser_dashboard.add_argument(
-        "--patterns-dir", default="./patterns", help="Path to patterns directory"
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
     )
     parser_dashboard.add_argument(
-        "--empathy-dir", default=".empathy", help="Empathy data directory"
+        "--empathy-dir",
+        default=".empathy",
+        help="Empathy data directory",
     )
     parser_dashboard.add_argument(
-        "--no-browser", action="store_true", help="Don't open browser automatically"
+        "--no-browser",
+        action="store_true",
+        help="Don't open browser automatically",
     )
     parser_dashboard.set_defaults(func=cmd_dashboard)
 
@@ -1331,7 +2651,9 @@ def main():
         help="List and manage agent frameworks (LangChain, LangGraph, AutoGen, Haystack)",
     )
     parser_frameworks.add_argument(
-        "--all", action="store_true", help="Show all frameworks including uninstalled"
+        "--all",
+        action="store_true",
+        help="Show all frameworks including uninstalled",
     )
     parser_frameworks.add_argument(
         "--recommend",
@@ -1341,15 +2663,139 @@ def main():
     parser_frameworks.add_argument("--json", action="store_true", help="Output as JSON")
     parser_frameworks.set_defaults(func=cmd_frameworks)
 
+    # Workflow command (multi-model workflow management)
+    parser_workflow = subparsers.add_parser(
+        "workflow",
+        help="Multi-model workflows for cost-optimized task pipelines",
+    )
+    parser_workflow.add_argument(
+        "action",
+        choices=["list", "describe", "run", "config"],
+        help="Action: list, describe, run, or config",
+    )
+    parser_workflow.add_argument(
+        "name",
+        nargs="?",
+        help="Workflow name (for describe/run)",
+    )
+    parser_workflow.add_argument(
+        "--input",
+        "-i",
+        help="JSON input data for workflow execution",
+    )
+    parser_workflow.add_argument(
+        "--provider",
+        "-p",
+        choices=["anthropic", "openai", "google", "ollama", "hybrid"],
+        default=None,  # None means use config
+        help="Model provider: anthropic, openai, google, ollama, or hybrid (mix of best models)",
+    )
+    parser_workflow.add_argument(
+        "--force",
+        action="store_true",
+        help="Force overwrite existing config file",
+    )
+    parser_workflow.add_argument("--json", action="store_true", help="Output as JSON")
+    parser_workflow.add_argument(
+        "--write-tests",
+        action="store_true",
+        help="(test-gen workflow) Write generated tests to disk",
+    )
+    parser_workflow.add_argument(
+        "--output-dir",
+        default="tests/generated",
+        help="(test-gen workflow) Output directory for generated tests",
+    )
+    parser_workflow.set_defaults(func=cmd_workflow)
+
+    # Sync-claude command (sync patterns to Claude Code)
+    parser_sync_claude = subparsers.add_parser(
+        "sync-claude",
+        help="Sync learned patterns to Claude Code rules",
+    )
+    parser_sync_claude.add_argument(
+        "--patterns-dir",
+        default="./patterns",
+        help="Path to patterns directory",
+    )
+    parser_sync_claude.add_argument(
+        "--output-dir",
+        default=".claude/rules/empathy",
+        help="Output directory for Claude rules (default: .claude/rules/empathy)",
+    )
+    parser_sync_claude.set_defaults(func=cmd_sync_claude)
+
+    # =========================================================================
+    # USER EXPERIENCE COMMANDS (v2.5+)
+    # =========================================================================
+
+    # Cheatsheet command (quick reference)
+    parser_cheatsheet = subparsers.add_parser("cheatsheet", help="Quick reference of all commands")
+    parser_cheatsheet.add_argument(
+        "category",
+        nargs="?",
+        help="Category to show (getting-started, daily-workflow, code-quality, etc.)",
+    )
+    parser_cheatsheet.add_argument(
+        "--compact",
+        action="store_true",
+        help="Show commands only without descriptions",
+    )
+    parser_cheatsheet.set_defaults(func=cmd_cheatsheet)
+
+    # Onboard command (interactive tutorial)
+    parser_onboard = subparsers.add_parser(
+        "onboard",
+        help="Interactive onboarding tutorial for new users",
+    )
+    parser_onboard.add_argument("--step", type=int, help="Jump to a specific step (1-5)")
+    parser_onboard.add_argument("--reset", action="store_true", help="Reset onboarding progress")
+    parser_onboard.set_defaults(func=cmd_onboard)
+
+    # Explain command (detailed command explanations)
+    parser_explain = subparsers.add_parser(
+        "explain",
+        help="Get detailed explanation of how a command works",
+    )
+    parser_explain.add_argument(
+        "command",
+        choices=["morning", "ship", "learn", "health", "sync-claude"],
+        help="Command to explain",
+    )
+    parser_explain.set_defaults(func=cmd_explain)
+
+    # Achievements command (progress tracking)
+    parser_achievements = subparsers.add_parser(
+        "achievements",
+        help="View your usage statistics and achievements",
+    )
+    parser_achievements.set_defaults(func=cmd_achievements)
+
+    # Wizard Factory commands (create wizards 12x faster)
+    add_wizard_factory_commands(subparsers)
+
     # Parse arguments
     args = parser.parse_args()
 
     # Execute command
     if hasattr(args, "func"):
-        args.func(args)
-    else:
-        parser.print_help()
+        result = args.func(args)
+
+        # Show progressive discovery tips after command execution
+        if args.command and args.command not in ("dashboard", "run"):
+            try:
+                show_tip_if_available(args.command)
+            except Exception as e:  # noqa: BLE001
+                # INTENTIONAL: Discovery tips are optional UX enhancements
+                # They should never cause command execution to fail
+                # Cannot predict all possible errors from discovery system
+                logger.debug(f"Discovery tip not available for {args.command}: {e}")
+                pass
+
+        return result if result is not None else 0
+    parser.print_help()
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main() or 0)