mcp-ticketer 0.4.11__py3-none-any.whl → 0.12.0__py3-none-any.whl

mcp_ticketer/cli/main.py

@@ -5,6 +5,7 @@ import json
 import os
 from enum import Enum
 from pathlib import Path
+from typing import Any
 
 import typer
 from dotenv import load_dotenv
@@ -23,6 +24,7 @@ from ..queue.ticket_registry import TicketRegistry
 from .configure import configure_wizard, set_adapter_config, show_current_config
 from .diagnostics import run_diagnostics
 from .discover import app as discover_app
+from .instruction_commands import app as instruction_app
 from .migrate_config import migrate_config_command
 from .platform_commands import app as platform_app
 from .queue_commands import app as queue_app
@@ -48,11 +50,11 @@ app = typer.Typer(
 console = Console()
 
 
-def version_callback(value: bool):
+def version_callback(value: bool) -> None:
     """Print version and exit."""
     if value:
         console.print(f"mcp-ticketer version {__version__}")
-        raise typer.Exit()
+        raise typer.Exit() from None
 
 
 @app.callback()
@@ -65,7 +67,7 @@ def main_callback(
         is_eager=True,
         help="Show version and exit",
     ),
-):
+) -> None:
     """MCP Ticketer - Universal ticket management interface."""
     pass
 
@@ -270,7 +272,7 @@ def merge_config(updates: dict) -> dict:
 
 def get_adapter(
     override_adapter: str | None = None, override_config: dict | None = None
-):
+) -> Any:
     """Get configured adapter instance.
 
     Args:
@@ -318,6 +320,416 @@ def get_adapter(
     return AdapterRegistry.get_adapter(adapter_type, adapter_config)
 
 
+async def _validate_adapter_credentials(
+    adapter_type: str, config_file_path: Path
+) -> list[str]:
+    """Validate adapter credentials by performing real connectivity tests.
+
+    Args:
+        adapter_type: Type of adapter to validate
+        config_file_path: Path to config file
+
+    Returns:
+        List of validation issues (empty if valid)
+
+    """
+    import json
+
+    issues = []
+
+    try:
+        # Load config
+        with open(config_file_path) as f:
+            config = json.load(f)
+
+        adapter_config = config.get("adapters", {}).get(adapter_type, {})
+
+        if not adapter_config:
+            issues.append(f"No configuration found for {adapter_type}")
+            return issues
+
+        # Validate based on adapter type
+        if adapter_type == "linear":
+            api_key = adapter_config.get("api_key")
+
+            # Check API key format
+            if not api_key:
+                issues.append("Linear API key is missing")
+                return issues
+
+            if not api_key.startswith("lin_api_"):
+                issues.append(
+                    "Invalid Linear API key format (should start with 'lin_api_')"
+                )
+                return issues
+
+            # Test actual connectivity
+            try:
+                from ..adapters.linear import LinearAdapter
+
+                adapter = LinearAdapter(adapter_config)
+                # Try to list one ticket to verify connectivity
+                await adapter.list(limit=1)
+            except Exception as e:
+                error_msg = str(e)
+                if "401" in error_msg or "Unauthorized" in error_msg:
+                    issues.append(
+                        "Failed to authenticate with Linear API - invalid API key"
+                    )
+                elif "403" in error_msg or "Forbidden" in error_msg:
+                    issues.append("Linear API key lacks required permissions")
+                elif "team" in error_msg.lower():
+                    issues.append(f"Linear team configuration error: {error_msg}")
+                else:
+                    issues.append(f"Failed to connect to Linear API: {error_msg}")
+
+        elif adapter_type == "jira":
+            server = adapter_config.get("server")
+            email = adapter_config.get("email")
+            api_token = adapter_config.get("api_token")
+
+            # Check required fields
+            if not server:
+                issues.append("JIRA server URL is missing")
+            if not email:
+                issues.append("JIRA email is missing")
+            if not api_token:
+                issues.append("JIRA API token is missing")
+
+            if issues:
+                return issues
+
+            # Test actual connectivity
+            try:
+                from ..adapters.jira import JiraAdapter
+
+                adapter = JiraAdapter(adapter_config)
+                await adapter.list(limit=1)
+            except Exception as e:
+                error_msg = str(e)
+                if "401" in error_msg or "Unauthorized" in error_msg:
+                    issues.append(
+                        "Failed to authenticate with JIRA - invalid credentials"
+                    )
+                elif "403" in error_msg or "Forbidden" in error_msg:
+                    issues.append("JIRA credentials lack required permissions")
+                else:
+                    issues.append(f"Failed to connect to JIRA: {error_msg}")
+
+        elif adapter_type == "github":
+            token = adapter_config.get("token") or adapter_config.get("api_key")
+            owner = adapter_config.get("owner")
+            repo = adapter_config.get("repo")
+
+            # Check required fields
+            if not token:
+                issues.append("GitHub token is missing")
+            if not owner:
+                issues.append("GitHub owner is missing")
+            if not repo:
+                issues.append("GitHub repo is missing")
+
+            if issues:
+                return issues
+
+            # Test actual connectivity
+            try:
+                from ..adapters.github import GitHubAdapter
+
+                adapter = GitHubAdapter(adapter_config)
+                await adapter.list(limit=1)
+            except Exception as e:
+                error_msg = str(e)
+                if (
+                    "401" in error_msg
+                    or "Unauthorized" in error_msg
+                    or "Bad credentials" in error_msg
+                ):
+                    issues.append("Failed to authenticate with GitHub - invalid token")
+                elif "404" in error_msg or "Not Found" in error_msg:
+                    issues.append(f"GitHub repository not found: {owner}/{repo}")
+                elif "403" in error_msg or "Forbidden" in error_msg:
+                    issues.append("GitHub token lacks required permissions")
+                else:
+                    issues.append(f"Failed to connect to GitHub: {error_msg}")
+
+        elif adapter_type == "aitrackdown":
+            # AITrackdown doesn't require credentials, just check base_path is set
+            base_path = adapter_config.get("base_path")
+            if not base_path:
+                issues.append("AITrackdown base_path is missing")
+
+    except Exception as e:
+        issues.append(f"Validation error: {str(e)}")
+
+    return issues
+
+
+async def _validate_configuration_with_retry(
+    console: Console, adapter_type: str, config_file_path: Path, proj_path: Path
+) -> bool:
+    """Validate configuration with retry loop for corrections.
+
+    Args:
+        console: Rich console for output
+        adapter_type: Type of adapter configured
+        config_file_path: Path to config file
+        proj_path: Project path
+
+    Returns:
+        True if validation passed or user chose to continue, False if user chose to exit
+
+    """
+    max_retries = 3
+    retry_count = 0
+
+    while retry_count < max_retries:
+        console.print("\n[cyan]🔍 Validating configuration...[/cyan]")
+
+        # Run real adapter validation (suppress verbose output)
+        import io
+        import sys
+
+        # Capture output to suppress verbose diagnostics output
+        old_stdout = sys.stdout
+        old_stderr = sys.stderr
+        sys.stdout = io.StringIO()
+        sys.stderr = io.StringIO()
+
+        try:
+            # Perform real adapter validation using diagnostics
+            validation_issues = await _validate_adapter_credentials(
+                adapter_type, config_file_path
+            )
+        finally:
+            # Restore stdout/stderr
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+
+        # Check if there are issues
+        if not validation_issues:
+            console.print("[green]✓ Configuration validated successfully![/green]")
+            return True
+
+        # Display issues found
+        console.print("[yellow]⚠️  Configuration validation found issues:[/yellow]")
+        for issue in validation_issues:
+            console.print(f"  [red]❌[/red] {issue}")
+
+        # Offer user options
+        console.print("\n[bold]What would you like to do?[/bold]")
+        console.print("1. [cyan]Re-enter configuration values[/cyan] (fix issues)")
+        console.print("2. [yellow]Continue anyway[/yellow] (skip validation)")
+        console.print("3. [red]Exit[/red] (fix manually later)")
+
+        try:
+            choice = typer.prompt("\nSelect option (1-3)", type=int, default=1)
+        except typer.Abort:
+            console.print("[yellow]Cancelled.[/yellow]")
+            return False
+
+        if choice == 1:
+            # Re-enter configuration
+            # Check BEFORE increment to fix off-by-one error
+            if retry_count >= max_retries:
+                console.print(
+                    f"[red]Maximum retry attempts ({max_retries}) reached.[/red]"
+                )
+                console.print(
+                    "[yellow]Please fix configuration manually and run 'mcp-ticketer doctor'[/yellow]"
+                )
+                return False
+            retry_count += 1
+
+            console.print(
+                f"\n[cyan]Retry {retry_count}/{max_retries} - Re-entering configuration...[/cyan]"
+            )
+
+            # Reload current config to get values
+            import json
+
+            with open(config_file_path) as f:
+                current_config = json.load(f)
+
+            # Re-prompt for adapter-specific configuration
+            if adapter_type == "linear":
+                console.print("\n[bold]Linear Configuration[/bold]")
+                console.print(
+                    "[dim]Get your API key at: https://linear.app/settings/api[/dim]\n"
+                )
+
+                linear_api_key = typer.prompt(
+                    "Enter your Linear API key", hide_input=True
+                )
+
+                console.print("\n[bold]Linear Team Configuration[/bold]")
+                console.print("You can provide either:")
+                console.print(
+                    "  1. Team URL (e.g., https://linear.app/workspace/team/TEAMKEY/active)"
+                )
+                console.print("  2. Team key (e.g., 'ENG', 'DESIGN', 'PRODUCT')")
+                console.print("  3. Team ID (UUID)")
+                console.print(
+                    "[dim]Find team URL or key in: Linear → Your Team → Team Issues Page[/dim]\n"
+                )
+
+                team_input = typer.prompt("Team URL, key, or ID")
+
+                # Check if input is a URL
+                linear_team_id = None
+                linear_team_key = None
+
+                if team_input.startswith("https://linear.app/"):
+                    console.print("[cyan]Detected team URL, deriving team ID...[/cyan]")
+                    from .linear_commands import derive_team_from_url
+
+                    derived_team_id, error = await derive_team_from_url(
+                        linear_api_key, team_input
+                    )
+
+                    if derived_team_id:
+                        linear_team_id = derived_team_id
+                        console.print(
+                            "[green]✓[/green] Successfully derived team ID from URL"
+                        )
+                    else:
+                        console.print(f"[red]Error:[/red] {error}")
+                        console.print("Please provide team key or ID manually instead.")
+                        team_input = typer.prompt("Team key or ID")
+
+                        if len(team_input) > 20:  # Likely a UUID
+                            linear_team_id = team_input
+                        else:
+                            linear_team_key = team_input
+                else:
+                    # Input is team key or ID
+                    if len(team_input) > 20:  # Likely a UUID
+                        linear_team_id = team_input
+                    else:
+                        linear_team_key = team_input
+
+                # Update config
+                linear_config = {
+                    "api_key": linear_api_key,
+                    "type": "linear",
+                }
+                if linear_team_key:
+                    linear_config["team_key"] = linear_team_key
+                if linear_team_id:
+                    linear_config["team_id"] = linear_team_id
+
+                current_config["adapters"]["linear"] = linear_config
+
+            elif adapter_type == "jira":
+                console.print("\n[bold]JIRA Configuration[/bold]")
+                console.print("Enter your JIRA server details.\n")
+
+                server = typer.prompt(
+                    "JIRA server URL (e.g., https://company.atlassian.net)"
+                )
+                email = typer.prompt("Your JIRA email address")
+
+                console.print("\nYou need a JIRA API token.")
+                console.print(
+                    "[dim]Generate one at: https://id.atlassian.com/manage/api-tokens[/dim]\n"
+                )
+
+                token = typer.prompt("Enter your JIRA API token", hide_input=True)
+
+                project = typer.prompt(
+                    "Default JIRA project key (optional, press Enter to skip)",
+                    default="",
+                    show_default=False,
+                )
+
+                # Update config
+                jira_config = {
+                    "server": server,
+                    "email": email,
+                    "api_token": token,
+                    "type": "jira",
+                }
+                if project:
+                    jira_config["project_key"] = project
+
+                current_config["adapters"]["jira"] = jira_config
+
+            elif adapter_type == "github":
+                console.print("\n[bold]GitHub Configuration[/bold]")
+                console.print("Enter your GitHub repository details.\n")
+
+                owner = typer.prompt(
+                    "GitHub repository owner (username or organization)"
+                )
+                repo = typer.prompt("GitHub repository name")
+
+                console.print("\nYou need a GitHub Personal Access Token.")
+                console.print(
+                    "[dim]Create one at: https://github.com/settings/tokens/new[/dim]"
+                )
+                console.print(
+                    "[dim]Required scopes: repo (for private repos) or public_repo (for public repos)[/dim]\n"
+                )
+
+                token = typer.prompt(
+                    "Enter your GitHub Personal Access Token", hide_input=True
+                )
+
+                # Update config
+                current_config["adapters"]["github"] = {
+                    "owner": owner,
+                    "repo": repo,
+                    "token": token,
+                    "type": "github",
+                }
+
+            elif adapter_type == "aitrackdown":
+                # AITrackdown doesn't need credentials, but save config before returning
+                # Save updated configuration
+                with open(config_file_path, "w") as f:
+                    json.dump(current_config, f, indent=2)
+
+                console.print(
+                    "[yellow]AITrackdown doesn't require credentials. Continuing...[/yellow]"
+                )
+                console.print("[dim]✓ Configuration updated[/dim]")
+                return True
+
+            else:
+                console.print(f"[red]Unknown adapter type: {adapter_type}[/red]")
+                return False
+
+            # Save updated configuration
+            with open(config_file_path, "w") as f:
+                json.dump(current_config, f, indent=2)
+
+            console.print("[dim]✓ Configuration updated[/dim]")
+            # Loop will retry validation
+
+        elif choice == 2:
+            # Continue anyway
+            console.print(
+                "[yellow]⚠️  Continuing with potentially invalid configuration.[/yellow]"
+            )
+            console.print("[dim]You can validate later with: mcp-ticketer doctor[/dim]")
+            return True
+
+        elif choice == 3:
+            # Exit
+            console.print(
+                "[yellow]Configuration saved but not validated. Run 'mcp-ticketer doctor' to test.[/yellow]"
+            )
+            return False
+
+        else:
+            console.print(
+                f"[red]Invalid choice: {choice}. Please enter 1, 2, or 3.[/red]"
+            )
+            # Continue loop to ask again
+
+    return True
+
+
 def _prompt_for_adapter_selection(console: Console) -> str:
     """Interactive prompt for adapter selection.
 
@@ -381,90 +793,354 @@ def _prompt_for_adapter_selection(console: Console) -> str:
                 )
         except (ValueError, typer.Abort):
             console.print("[yellow]Setup cancelled.[/yellow]")
-            raise typer.Exit(0)
+            raise typer.Exit(0) from None
 
 
 @app.command()
 def setup(
-    adapter: str | None = typer.Option(
-        None,
-        "--adapter",
-        "-a",
-        help="Adapter type to use (interactive prompt if not specified)",
-    ),
     project_path: str | None = typer.Option(
         None, "--path", help="Project path (default: current directory)"
     ),
-    global_config: bool = typer.Option(
+    skip_platforms: bool = typer.Option(
         False,
-        "--global",
-        "-g",
-        help="Save to global config instead of project-specific",
+        "--skip-platforms",
+        help="Skip platform installation (only initialize adapter)",
     ),
-    base_path: str | None = typer.Option(
-        None,
-        "--base-path",
-        "-p",
-        help="Base path for ticket storage (AITrackdown only)",
-    ),
-    api_key: str | None = typer.Option(
-        None, "--api-key", help="API key for Linear or API token for JIRA"
-    ),
-    team_id: str | None = typer.Option(
-        None, "--team-id", help="Linear team ID (required for Linear adapter)"
-    ),
-    jira_server: str | None = typer.Option(
-        None,
-        "--jira-server",
-        help="JIRA server URL (e.g., https://company.atlassian.net)",
-    ),
-    jira_email: str | None = typer.Option(
-        None, "--jira-email", help="JIRA user email for authentication"
-    ),
-    jira_project: str | None = typer.Option(
-        None, "--jira-project", help="Default JIRA project key"
-    ),
-    github_owner: str | None = typer.Option(
-        None, "--github-owner", help="GitHub repository owner"
-    ),
-    github_repo: str | None = typer.Option(
-        None, "--github-repo", help="GitHub repository name"
-    ),
-    github_token: str | None = typer.Option(
-        None, "--github-token", help="GitHub Personal Access Token"
+    force_reinit: bool = typer.Option(
+        False,
+        "--force-reinit",
+        help="Force re-initialization even if config exists",
     ),
 ) -> None:
-    """Interactive setup wizard for MCP Ticketer (alias for init).
+    """Smart setup command - combines init + platform installation.
+
+    This command intelligently detects your current setup state and only
+    performs necessary configuration. It's the recommended way to get started.
 
-    This command provides a user-friendly setup experience with prompts
-    to guide you through configuring MCP Ticketer for your preferred
-    ticket management system. It's identical to 'init' and 'install'.
+    Detection & Smart Actions:
+    - First run: Full setup (init + platform installation)
+    - Existing config: Skip init, offer platform installation
+    - Detects changes: Offers to update configurations
+    - Respects existing: Won't overwrite without confirmation
 
     Examples:
-        # Run interactive setup
+        # Smart setup (recommended for first-time setup)
         mcp-ticketer setup
 
-        # Setup with specific adapter
-        mcp-ticketer setup --adapter linear
-
         # Setup for different project
         mcp-ticketer setup --path /path/to/project
 
+        # Re-initialize configuration
+        mcp-ticketer setup --force-reinit
+
+        # Only init adapter, skip platform installation
+        mcp-ticketer setup --skip-platforms
+
+    Note: For advanced configuration, use 'init' and 'install' separately.
+
     """
-    # Call init with all parameters
-    init(
-        adapter=adapter,
-        project_path=project_path,
-        global_config=global_config,
-        base_path=base_path,
-        api_key=api_key,
-        team_id=team_id,
-        jira_server=jira_server,
-        jira_email=jira_email,
-        jira_project=jira_project,
-        github_owner=github_owner,
-        github_repo=github_repo,
-        github_token=github_token,
+    from .platform_detection import PlatformDetector
+
+    proj_path = Path(project_path) if project_path else Path.cwd()
+    config_path = proj_path / ".mcp-ticketer" / "config.json"
+
+    console.print("[bold cyan]🚀 MCP Ticketer Smart Setup[/bold cyan]\n")
+
+    # Step 1: Detect existing configuration
+    config_exists = config_path.exists()
+    config_valid = False
+    current_adapter = None
+
+    if config_exists and not force_reinit:
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+                current_adapter = config.get("default_adapter")
+                config_valid = bool(current_adapter and config.get("adapters"))
+        except (json.JSONDecodeError, OSError):
+            config_valid = False
+
+    if config_valid:
+        console.print("[green]✓[/green] Configuration detected")
+        console.print(f"[dim]  Adapter: {current_adapter}[/dim]")
+        console.print(f"[dim]  Location: {config_path}[/dim]\n")
+
+        # Offer to reconfigure
+        if not typer.confirm(
+            "Configuration already exists. Keep existing settings?", default=True
+        ):
+            console.print("[cyan]Re-initializing configuration...[/cyan]\n")
+            force_reinit = True
+            config_valid = False
+    else:
+        if config_exists:
+            console.print(
+                "[yellow]⚠[/yellow]  Configuration file exists but is invalid\n"
+            )
+        else:
+            console.print("[yellow]⚠[/yellow]  No configuration found\n")
+
+    # Step 2: Initialize adapter configuration if needed
+    if not config_valid or force_reinit:
+        console.print("[bold]Step 1/2: Adapter Configuration[/bold]\n")
+
+        # Run init command non-interactively through function call
+        # We'll use the discover and prompt flow from init
+        from ..core.env_discovery import discover_config
+
+        discovered = discover_config(proj_path)
+        adapter_type = None
+
+        # Try auto-discovery
+        if discovered and discovered.adapters:
+            primary = discovered.get_primary_adapter()
+            if primary:
+                adapter_type = primary.adapter_type
+                console.print(f"[green]✓ Auto-detected {adapter_type} adapter[/green]")
+                console.print(f"[dim]  Source: {primary.found_in}[/dim]")
+                console.print(f"[dim]  Confidence: {primary.confidence:.0%}[/dim]\n")
+
+                if not typer.confirm(
+                    f"Use detected {adapter_type} adapter?", default=True
+                ):
+                    adapter_type = None
+
+        # If no adapter detected, prompt for selection
+        if not adapter_type:
+            adapter_type = _prompt_for_adapter_selection(console)
+
+        # Now run the full init with the selected adapter
+        console.print(f"\n[cyan]Initializing {adapter_type} adapter...[/cyan]\n")
+
+        # Call init programmatically
+        init(
+            adapter=adapter_type,
+            project_path=str(proj_path),
+            global_config=False,
+        )
+
+        console.print("\n[green]✓ Adapter configuration complete[/green]\n")
+    else:
+        console.print("[green]✓ Step 1/2: Adapter already configured[/green]\n")
+
+    # Step 3: Platform installation
+    if skip_platforms:
+        console.print(
+            "[yellow]⚠[/yellow]  Skipping platform installation (--skip-platforms)\n"
+        )
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    console.print("[bold]Step 2/2: Platform Installation[/bold]\n")
+
+    # Detect available platforms
+    detector = PlatformDetector()
+    detected = detector.detect_all(project_path=proj_path)
+
+    if not detected:
+        console.print("[yellow]No AI platforms detected on this system.[/yellow]")
+        console.print(
+            "\n[dim]Supported platforms: Claude Code, Claude Desktop, Gemini, Codex, Auggie[/dim]"
+        )
+        console.print(
+            "[dim]Install these platforms to use them with mcp-ticketer.[/dim]\n"
+        )
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    # Filter to only installed platforms
+    installed = [p for p in detected if p.is_installed]
+
+    if not installed:
+        console.print(
+            "[yellow]AI platforms detected but have configuration issues.[/yellow]"
+        )
+        console.print(
+            "\n[dim]Run 'mcp-ticketer install --auto-detect' for details.[/dim]\n"
+        )
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    # Show detected platforms
+    console.print(f"[green]✓[/green] Detected {len(installed)} platform(s):\n")
+    for plat in installed:
+        console.print(f"  • {plat.display_name} ({plat.scope})")
+
+    console.print()
+
+    # Check if mcp-ticketer is already configured for these platforms
+    already_configured = _check_existing_platform_configs(installed, proj_path)
+
+    if already_configured:
+        console.print(
+            f"[green]✓[/green] mcp-ticketer already configured for {len(already_configured)} platform(s)\n"
+        )
+        for plat_name in already_configured:
+            console.print(f"  • {plat_name}")
+        console.print()
+
+        if not typer.confirm("Update platform configurations anyway?", default=False):
+            console.print("[yellow]Skipping platform installation[/yellow]\n")
+            _show_setup_complete_message(console, proj_path)
+            return
+
+    # Offer to install for all or select specific
+    console.print("[bold]Platform Installation Options:[/bold]")
+    console.print("1. Install for all detected platforms")
+    console.print("2. Select specific platform")
+    console.print("3. Skip platform installation")
+
+    try:
+        choice = typer.prompt("\nSelect option (1-3)", type=int, default=1)
+    except typer.Abort:
+        console.print("[yellow]Setup cancelled[/yellow]")
+        raise typer.Exit(0) from None
+
+    if choice == 3:
+        console.print("[yellow]Skipping platform installation[/yellow]\n")
+        _show_setup_complete_message(console, proj_path)
+        return
+
+    # Import configuration functions
+    from .auggie_configure import configure_auggie_mcp
+    from .codex_configure import configure_codex_mcp
+    from .gemini_configure import configure_gemini_mcp
+    from .mcp_configure import configure_claude_mcp
+
+    platform_mapping = {
+        "claude-code": lambda: configure_claude_mcp(global_config=False, force=True),
+        "claude-desktop": lambda: configure_claude_mcp(global_config=True, force=True),
+        "auggie": lambda: configure_auggie_mcp(force=True),
+        "gemini": lambda: configure_gemini_mcp(scope="project", force=True),
+        "codex": lambda: configure_codex_mcp(force=True),
+    }
+
+    platforms_to_install = []
+
+    if choice == 1:
+        # Install for all
+        platforms_to_install = installed
+    elif choice == 2:
+        # Select specific platform
+        console.print("\n[bold]Select platform:[/bold]")
+        for idx, plat in enumerate(installed, 1):
+            console.print(f"  {idx}. {plat.display_name} ({plat.scope})")
+
+        try:
+            plat_choice = typer.prompt("\nSelect platform number", type=int)
+            if 1 <= plat_choice <= len(installed):
+                platforms_to_install = [installed[plat_choice - 1]]
+            else:
+                console.print("[red]Invalid selection[/red]")
+                raise typer.Exit(1) from None
+        except typer.Abort:
+            console.print("[yellow]Setup cancelled[/yellow]")
+            raise typer.Exit(0) from None
+
+    # Install for selected platforms
+    console.print()
+    success_count = 0
+    failed = []
+
+    for plat in platforms_to_install:
+        config_func = platform_mapping.get(plat.name)
+        if not config_func:
+            console.print(f"[yellow]⚠[/yellow]  No installer for {plat.display_name}")
+            continue
+
+        try:
+            console.print(f"[cyan]Installing for {plat.display_name}...[/cyan]")
+            config_func()
+            console.print(f"[green]✓[/green] {plat.display_name} configured\n")
+            success_count += 1
+        except Exception as e:
+            console.print(
+                f"[red]✗[/red] Failed to configure {plat.display_name}: {e}\n"
+            )
+            failed.append(plat.display_name)
+
+    # Summary
+    console.print(
+        f"[bold]Platform Installation:[/bold] {success_count}/{len(platforms_to_install)} succeeded"
+    )
+    if failed:
+        console.print(f"[red]Failed:[/red] {', '.join(failed)}")
+
+    console.print()
+    _show_setup_complete_message(console, proj_path)
+
+
+def _check_existing_platform_configs(platforms: list, proj_path: Path) -> list[str]:
+    """Check if mcp-ticketer is already configured for given platforms.
+
+    Args:
+        platforms: List of DetectedPlatform objects
+        proj_path: Project path
+
+    Returns:
+        List of platform display names that are already configured
+
+    """
+    configured = []
+
+    for plat in platforms:
+        try:
+            if plat.name == "claude-code":
+                config_path = Path.home() / ".claude.json"
+                if config_path.exists():
+                    with open(config_path) as f:
+                        config = json.load(f)
+                        projects = config.get("projects", {})
+                        proj_key = str(proj_path)
+                        if proj_key in projects:
+                            mcp_servers = projects[proj_key].get("mcpServers", {})
+                            if "mcp-ticketer" in mcp_servers:
+                                configured.append(plat.display_name)
+
+            elif plat.name == "claude-desktop":
+                if plat.config_path.exists():
+                    with open(plat.config_path) as f:
+                        config = json.load(f)
+                        if "mcp-ticketer" in config.get("mcpServers", {}):
+                            configured.append(plat.display_name)
+
+            elif plat.name in ["auggie", "codex", "gemini"]:
+                if plat.config_path.exists():
+                    # Check if mcp-ticketer is configured
+                    # Implementation depends on each platform's config format
+                    # For now, just check if config exists (simplified)
+                    pass
+
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return configured
+
+
+def _show_setup_complete_message(console: Console, proj_path: Path) -> None:
+    """Show setup complete message with next steps.
+
+    Args:
+        console: Rich console for output
+        proj_path: Project path
+
+    """
+    console.print("[bold green]🎉 Setup Complete![/bold green]\n")
+
+    console.print("[bold]Quick Start:[/bold]")
+    console.print("1. Create a test ticket:")
+    console.print("   [cyan]mcp-ticketer create 'My first ticket'[/cyan]\n")
+
+    console.print("2. List tickets:")
+    console.print("   [cyan]mcp-ticketer list[/cyan]\n")
+
+    console.print("[bold]Useful Commands:[/bold]")
+    console.print("  [cyan]mcp-ticketer doctor[/cyan]        - Validate configuration")
+    console.print("  [cyan]mcp-ticketer install <platform>[/cyan] - Add more platforms")
+    console.print("  [cyan]mcp-ticketer --help[/cyan]        - See all commands\n")
+
+    console.print(
+        f"[dim]Configuration: {proj_path / '.mcp-ticketer' / 'config.json'}[/dim]"
     )
 
 
@@ -518,37 +1194,41 @@ def init(
         None, "--github-token", help="GitHub Personal Access Token"
     ),
 ) -> None:
-    """Initialize mcp-ticketer for the current project (synonymous with 'install' and 'setup').
+    """Initialize adapter configuration only (without platform installation).
+
+    This command sets up adapter configuration with interactive prompts.
+    It auto-detects adapter configuration from .env files or prompts for
+    interactive setup if no configuration is found.
 
-    This command sets up MCP Ticketer configuration with interactive prompts
-    to guide you through the process. It auto-detects adapter configuration
-    from .env files or prompts for interactive setup if no configuration is found.
+    Creates .mcp-ticketer/config.json in the current directory.
 
-    Creates .mcp-ticketer/config.json in the current directory with
-    auto-detected or specified adapter configuration.
+    RECOMMENDED: Use 'mcp-ticketer setup' instead for a complete setup
+    experience that includes both adapter configuration and platform
+    installation in one command.
 
-    Note: 'init', 'install', and 'setup' are all synonyms - use whichever feels natural.
+    The init command automatically validates your configuration after setup:
+    - If validation passes, setup completes
+    - If issues are detected, you can re-enter credentials, continue anyway, or exit
+    - You get up to 3 retry attempts to fix configuration issues
+    - You can always re-validate later with 'mcp-ticketer doctor'
 
     Examples:
-        # Interactive setup (all three commands are identical)
-        mcp-ticketer init
-        mcp-ticketer install
+        # For first-time setup, use 'setup' instead (recommended)
         mcp-ticketer setup
 
+        # Initialize adapter only (advanced usage)
+        mcp-ticketer init
+
         # Force specific adapter
         mcp-ticketer init --adapter linear
 
         # Initialize for different project
         mcp-ticketer init --path /path/to/project
 
-        # Save globally (not recommended)
-        mcp-ticketer init --global
-
     """
     from pathlib import Path
 
     from ..core.env_discovery import discover_config
-    from ..core.project_config import ConfigResolver
 
     # Determine project path
     proj_path = Path(project_path) if project_path else Path.cwd()
@@ -563,7 +1243,7 @@ def init(
                 default=False,
             ):
                 console.print("[yellow]Initialization cancelled.[/yellow]")
-                raise typer.Exit(0)
+                raise typer.Exit(0) from None
 
     # 1. Try auto-discovery if no adapter specified
     discovered = None
@@ -652,11 +1332,9 @@ def init(
     elif adapter_type == "linear":
         # If not auto-discovered, build from CLI params or prompt
         if adapter_type not in config["adapters"]:
-            linear_config = {}
-
             # API Key
             linear_api_key = api_key or os.getenv("LINEAR_API_KEY")
-            if not linear_api_key and not discovered:
+            if not linear_api_key:
                 console.print("\n[bold]Linear Configuration[/bold]")
                 console.print("You need a Linear API key to connect to Linear.")
                 console.print(
@@ -667,22 +1345,74 @@ def init(
                     "Enter your Linear API key", hide_input=True
                 )
 
-            if linear_api_key:
-                linear_config["api_key"] = linear_api_key
-
-            # Team ID or Team Key
+            # Team ID or Team Key or Team URL
             # Try environment variables first
             linear_team_key = os.getenv("LINEAR_TEAM_KEY")
             linear_team_id = team_id or os.getenv("LINEAR_TEAM_ID")
 
-            if not linear_team_key and not linear_team_id and not discovered:
+            if not linear_team_key and not linear_team_id:
                 console.print("\n[bold]Linear Team Configuration[/bold]")
-                console.print("Enter your team key (e.g., 'ENG', 'DESIGN', 'PRODUCT')")
+                console.print("You can provide either:")
+                console.print(
+                    "  1. Team URL (e.g., https://linear.app/workspace/team/TEAMKEY/active)"
+                )
+                console.print("  2. Team key (e.g., 'ENG', 'DESIGN', 'PRODUCT')")
+                console.print("  3. Team ID (UUID)")
                 console.print(
-                    "[dim]Find it in: Linear Settings → Teams → Your Team → Key field[/dim]\n"
+                    "[dim]Find team URL or key in: Linear → Your Team → Team Issues Page[/dim]\n"
                 )
 
-                linear_team_key = typer.prompt("Team key")
+                team_input = typer.prompt("Team URL, key, or ID")
+
+                # Check if input is a URL
+                if team_input.startswith("https://linear.app/"):
+                    console.print("[cyan]Detected team URL, deriving team ID...[/cyan]")
+                    import asyncio
+
+                    from .linear_commands import derive_team_from_url
+
+                    derived_team_id, error = asyncio.run(
+                        derive_team_from_url(linear_api_key, team_input)
+                    )
+
+                    if derived_team_id:
+                        linear_team_id = derived_team_id
+                        console.print(
+                            "[green]✓[/green] Successfully derived team ID from URL"
+                        )
+                    else:
+                        console.print(f"[red]Error:[/red] {error}")
+                        console.print("Please provide team key or ID manually instead.")
+                        team_input = typer.prompt("Team key or ID")
+
+                        # Store as either team_key or team_id based on format
+                        if len(team_input) > 20:  # Likely a UUID
+                            linear_team_id = team_input
+                        else:
+                            linear_team_key = team_input
+                else:
+                    # Input is team key or ID
+                    if len(team_input) > 20:  # Likely a UUID
+                        linear_team_id = team_input
+                    else:
+                        linear_team_key = team_input
+
+            # Validate required fields (following JIRA pattern)
+            if not linear_api_key:
+                console.print("[red]Error:[/red] Linear API key is required")
+                raise typer.Exit(1) from None
+
+            if not linear_team_id and not linear_team_key:
+                console.print(
+                    "[red]Error:[/red] Linear requires either team ID or team key"
+                )
+                raise typer.Exit(1) from None
+
+            # Build configuration
+            linear_config = {
+                "api_key": linear_api_key,
+                "type": "linear",
+            }
 
             # Save whichever was provided
             if linear_team_key:
@@ -690,18 +1420,6 @@ def init(
             if linear_team_id:
                 linear_config["team_id"] = linear_team_id
 
-            if not linear_config.get("api_key") or (
-                not linear_config.get("team_id") and not linear_config.get("team_key")
-            ):
-                console.print(
-                    "[red]Error:[/red] Linear requires both API key and team ID/key"
-                )
-                console.print(
-                    "Run 'mcp-ticketer init --adapter linear' with proper credentials"
-                )
-                raise typer.Exit(1)
-
-            linear_config["type"] = "linear"
             config["adapters"]["linear"] = linear_config
 
     elif adapter_type == "jira":
@@ -713,7 +1431,7 @@ def init(
             project = jira_project or os.getenv("JIRA_PROJECT_KEY")
 
             # Interactive prompts for missing values
-            if not server and not discovered:
+            if not server:
                 console.print("\n[bold]JIRA Configuration[/bold]")
                 console.print("Enter your JIRA server details.\n")
 
@@ -721,10 +1439,10 @@ def init(
                     "JIRA server URL (e.g., https://company.atlassian.net)"
                 )
 
-            if not email and not discovered:
+            if not email:
                 email = typer.prompt("Your JIRA email address")
 
-            if not token and not discovered:
+            if not token:
                 console.print("\nYou need a JIRA API token.")
                 console.print(
                     "[dim]Generate one at: https://id.atlassian.com/manage/api-tokens[/dim]\n"
@@ -732,7 +1450,7 @@ def init(
 
                 token = typer.prompt("Enter your JIRA API token", hide_input=True)
 
-            if not project and not discovered:
+            if not project:
                 project = typer.prompt(
                     "Default JIRA project key (optional, press Enter to skip)",
                     default="",
@@ -742,15 +1460,15 @@ def init(
             # Validate required fields
             if not server:
                 console.print("[red]Error:[/red] JIRA server URL is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not email:
                 console.print("[red]Error:[/red] JIRA email is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not token:
                 console.print("[red]Error:[/red] JIRA API token is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             jira_config = {
                 "server": server,
@@ -772,7 +1490,7 @@ def init(
             token = github_token or os.getenv("GITHUB_TOKEN")
 
             # Interactive prompts for missing values
-            if not owner and not discovered:
+            if not owner:
                 console.print("\n[bold]GitHub Configuration[/bold]")
                 console.print("Enter your GitHub repository details.\n")
 
@@ -780,10 +1498,10 @@ def init(
                     "GitHub repository owner (username or organization)"
                 )
 
-            if not repo and not discovered:
+            if not repo:
                 repo = typer.prompt("GitHub repository name")
 
-            if not token and not discovered:
+            if not token:
                 console.print("\nYou need a GitHub Personal Access Token.")
                 console.print(
                     "[dim]Create one at: https://github.com/settings/tokens/new[/dim]"
@@ -799,17 +1517,17 @@ def init(
             # Validate required fields
             if not owner:
                 console.print("[red]Error:[/red] GitHub repository owner is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not repo:
                 console.print("[red]Error:[/red] GitHub repository name is required")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             if not token:
                 console.print(
                     "[red]Error:[/red] GitHub Personal Access Token is required"
                 )
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             config["adapters"]["github"] = {
                 "owner": owner,
@@ -818,42 +1536,46 @@ def init(
                 "type": "github",
             }
 
-    # 5. Save to appropriate location
-    if global_config:
-        # Save to ~/.mcp-ticketer/config.json
-        resolver = ConfigResolver(project_path=proj_path)
-        config_file_path = resolver.GLOBAL_CONFIG_PATH
-        config_file_path.parent.mkdir(parents=True, exist_ok=True)
+    # 5. Save to project-local config (global config deprecated for security)
+    # Always save to ./.mcp-ticketer/config.json (PROJECT-SPECIFIC)
+    config_file_path = proj_path / ".mcp-ticketer" / "config.json"
+    config_file_path.parent.mkdir(parents=True, exist_ok=True)
 
-        with open(config_file_path, "w") as f:
-            json.dump(config, f, indent=2)
+    with open(config_file_path, "w") as f:
+        json.dump(config, f, indent=2)
+
+    if global_config:
+        console.print(
+            "[yellow]Note: Global config deprecated for security. Saved to project config instead.[/yellow]"
+        )
 
-        console.print(f"[green]✓ Initialized with {adapter_type} adapter[/green]")
-        console.print(f"[dim]Global configuration saved to {config_file_path}[/dim]")
+    console.print(f"[green]✓ Initialized with {adapter_type} adapter[/green]")
+    console.print(f"[dim]Project configuration saved to {config_file_path}[/dim]")
+
+    # Add .mcp-ticketer to .gitignore if not already there
+    gitignore_path = proj_path / ".gitignore"
+    if gitignore_path.exists():
+        gitignore_content = gitignore_path.read_text()
+        if ".mcp-ticketer" not in gitignore_content:
+            with open(gitignore_path, "a") as f:
+                f.write("\n# MCP Ticketer\n.mcp-ticketer/\n")
+            console.print("[dim]✓ Added .mcp-ticketer/ to .gitignore[/dim]")
     else:
-        # Save to ./.mcp-ticketer/config.json (PROJECT-SPECIFIC)
-        config_file_path = proj_path / ".mcp-ticketer" / "config.json"
-        config_file_path.parent.mkdir(parents=True, exist_ok=True)
-
-        with open(config_file_path, "w") as f:
-            json.dump(config, f, indent=2)
-
-        console.print(f"[green]✓ Initialized with {adapter_type} adapter[/green]")
-        console.print(f"[dim]Project configuration saved to {config_file_path}[/dim]")
-
-        # Add .mcp-ticketer to .gitignore if not already there
-        gitignore_path = proj_path / ".gitignore"
-        if gitignore_path.exists():
-            gitignore_content = gitignore_path.read_text()
-            if ".mcp-ticketer" not in gitignore_content:
-                with open(gitignore_path, "a") as f:
-                    f.write("\n# MCP Ticketer\n.mcp-ticketer/\n")
-                console.print("[dim]✓ Added .mcp-ticketer/ to .gitignore[/dim]")
-        else:
-            # Create .gitignore if it doesn't exist
-            with open(gitignore_path, "w") as f:
-                f.write("# MCP Ticketer\n.mcp-ticketer/\n")
-            console.print("[dim]✓ Created .gitignore with .mcp-ticketer/[/dim]")
+        # Create .gitignore if it doesn't exist
+        with open(gitignore_path, "w") as f:
+            f.write("# MCP Ticketer\n.mcp-ticketer/\n")
+        console.print("[dim]✓ Created .gitignore with .mcp-ticketer/[/dim]")
+
+    # Validate configuration with loop for corrections
+    import asyncio
+
+    if not asyncio.run(
+        _validate_configuration_with_retry(
+            console, adapter_type, config_file_path, proj_path
+        )
+    ):
+        # User chose to exit without valid configuration
+        raise typer.Exit(1) from None
 
     # Show next steps
     _show_next_steps(console, adapter_type, config_file_path)
@@ -874,16 +1596,13 @@ def _show_next_steps(
     console.print(f"MCP Ticketer is now configured to use {adapter_type.title()}.\n")
 
     console.print("[bold]Next Steps:[/bold]")
-    console.print("1. [cyan]Test your configuration:[/cyan]")
-    console.print("   mcp-ticketer diagnose")
-    console.print("\n2. [cyan]Create a test ticket:[/cyan]")
+    console.print("1. [cyan]Create a test ticket:[/cyan]")
     console.print("   mcp-ticketer create 'Test ticket from MCP Ticketer'")
 
     if adapter_type != "aitrackdown":
         console.print(
-            f"\n3. [cyan]Verify the ticket appears in {adapter_type.title()}[/cyan]"
+            f"\n2. [cyan]Verify the ticket appears in {adapter_type.title()}[/cyan]"
         )
-
         if adapter_type == "linear":
             console.print("   Check your Linear workspace for the new ticket")
         elif adapter_type == "github":
@@ -891,16 +1610,19 @@ def _show_next_steps(
         elif adapter_type == "jira":
             console.print("   Check your JIRA project for the new ticket")
     else:
-        console.print("\n3. [cyan]Check local ticket storage:[/cyan]")
+        console.print("\n2. [cyan]Check local ticket storage:[/cyan]")
         console.print("   ls .aitrackdown/")
 
-    console.print("\n4. [cyan]Install MCP for AI clients (optional):[/cyan]")
+    console.print("\n3. [cyan]Install MCP for AI clients (optional):[/cyan]")
     console.print("   mcp-ticketer install claude-code     # For Claude Code")
     console.print("   mcp-ticketer install claude-desktop  # For Claude Desktop")
     console.print("   mcp-ticketer install auggie          # For Auggie")
     console.print("   mcp-ticketer install gemini          # For Gemini CLI")
 
     console.print(f"\n[dim]Configuration saved to: {config_file_path}[/dim]")
+    console.print(
+        "[dim]Run 'mcp-ticketer doctor' to re-validate configuration anytime[/dim]"
+    )
     console.print("[dim]Run 'mcp-ticketer --help' for more commands[/dim]")
 
 
@@ -1064,7 +1786,7 @@ def migrate_config(
 
 
 @app.command("queue-status", deprecated=True, hidden=True)
-def old_queue_status_command():
+def old_queue_status_command() -> None:
     """Show queue and worker status.
 
     DEPRECATED: Use 'mcp-ticketer queue status' instead.
@@ -1180,9 +1902,9 @@ def old_queue_health_command(
 
     # Exit with appropriate code
     if health["status"] == HealthStatus.CRITICAL:
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
     elif health["status"] == HealthStatus.WARNING:
-        raise typer.Exit(2)
+        raise typer.Exit(2) from None
 
 
 @app.command(deprecated=True, hidden=True)
@@ -1250,7 +1972,7 @@ def create(
                 console.print(
                     "[red]Cannot safely create ticket. Please check system status.[/red]"
                 )
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
             else:
                 console.print(
                     "[green]✓ Auto-repair successful. Proceeding with ticket creation.[/green]"
@@ -1259,7 +1981,7 @@ def create(
             console.print(
                 "[red]❌ No repair actions available. Manual intervention required.[/red]"
             )
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
     elif health["status"] == HealthStatus.WARNING:
         console.print("[yellow]⚠️  Warning: Queue system has minor issues[/yellow]")
@@ -1438,7 +2160,7 @@ def list_tickets(
         "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket list' instead.[/yellow]\n"
     )
 
-    async def _list():
+    async def _list() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1494,7 +2216,7 @@ def show(
         "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket show' instead.[/yellow]\n"
     )
 
-    async def _show():
+    async def _show() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1508,7 +2230,7 @@ def show(
 
     if not ticket:
         console.print(f"[red]✗[/red] Ticket not found: {ticket_id}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Display ticket details
     console.print(f"\n[bold]Ticket: {ticket.id}[/bold]")
@@ -1550,7 +2272,7 @@ def comment(
         "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket comment' instead.[/yellow]\n"
     )
 
-    async def _comment():
+    async def _comment() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1573,7 +2295,7 @@ def comment(
         console.print(f"Content: {content}")
     except Exception as e:
         console.print(f"[red]✗[/red] Failed to add comment: {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @app.command(deprecated=True, hidden=True)
@@ -1612,7 +2334,7 @@ def update(
 
     if not updates:
         console.print("[yellow]No updates specified[/yellow]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Get the adapter name
     config = load_config()
@@ -1684,7 +2406,7 @@ def transition(
             "  - Flag syntax (recommended): mcp-ticketer transition TICKET-ID --state STATE\n"
             "  - Positional syntax: mcp-ticketer transition TICKET-ID STATE"
         )
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Get the adapter name
     config = load_config()
@@ -1735,7 +2457,7 @@ def search(
         "[yellow]⚠️  This command is deprecated. Use 'mcp-ticketer ticket search' instead.[/yellow]\n"
     )
 
-    async def _search():
+    async def _search() -> None:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
@@ -1777,10 +2499,13 @@ app.add_typer(queue_app, name="queue")
 # Add discover command to main app
 app.add_typer(discover_app, name="discover")
 
+# Add instructions command to main app
+app.add_typer(instruction_app, name="instructions")
+
 
 # Add diagnostics command
-@app.command("diagnose")
-def diagnose_command(
+@app.command("doctor")
+def doctor_command(
     output_file: str | None = typer.Option(
         None, "--output", "-o", help="Save full report to file"
     ),
@@ -1791,7 +2516,7 @@ def diagnose_command(
         False, "--simple", help="Use simple diagnostics (no heavy dependencies)"
     ),
 ) -> None:
-    """Run comprehensive system diagnostics and health check (alias: doctor)."""
+    """Run comprehensive system diagnostics and health check (alias: diagnose)."""
     if simple:
         from .simple_health import simple_diagnose
 
@@ -1807,7 +2532,7 @@ def diagnose_command(
 
             console.print("\n" + json.dumps(report, indent=2))
         if report["issues"]:
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
     else:
         try:
             asyncio.run(
@@ -1823,11 +2548,11 @@ def diagnose_command(
 
             report = simple_diagnose()
             if report["issues"]:
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
 
-@app.command("doctor")
-def doctor_alias(
+@app.command("diagnose", hidden=True)
+def diagnose_alias(
     output_file: str | None = typer.Option(
         None, "--output", "-o", help="Save full report to file"
     ),
@@ -1838,9 +2563,9 @@ def doctor_alias(
         False, "--simple", help="Use simple diagnostics (no heavy dependencies)"
     ),
 ) -> None:
-    """Run comprehensive system diagnostics and health check (alias for diagnose)."""
-    # Call the diagnose_command function with the same parameters
-    diagnose_command(output_file=output_file, json_output=json_output, simple=simple)
+    """Run comprehensive system diagnostics and health check (alias for doctor)."""
+    # Call the doctor_command function with the same parameters
+    doctor_command(output_file=output_file, json_output=json_output, simple=simple)
 
 
 @app.command("status")
@@ -1850,7 +2575,7 @@ def status_command() -> None:
 
     result = simple_health_check()
     if result != 0:
-        raise typer.Exit(result)
+        raise typer.Exit(result) from None
 
 
 @app.command("health")
@@ -1860,7 +2585,7 @@ def health_alias() -> None:
 
     result = simple_health_check()
     if result != 0:
-        raise typer.Exit(result)
+        raise typer.Exit(result) from None
 
 
 # Create MCP configuration command group
@@ -1875,11 +2600,20 @@ mcp_app = typer.Typer(
 @mcp_app.callback()
 def mcp_callback(
     ctx: typer.Context,
-    project_path: str | None = typer.Argument(
-        None, help="Project directory path (optional - uses cwd if not provided)"
+    project_path: str | None = typer.Option(
+        None, "--path", "-p", help="Project directory path (default: current directory)"
     ),
-):
-    """MCP command group - runs MCP server if no subcommand provided."""
+) -> None:
+    """MCP command group - runs MCP server if no subcommand provided.
+
+    Examples:
+        mcp-ticketer mcp              # Start server in current directory
+        mcp-ticketer mcp --path /dir  # Start server in specific directory
+        mcp-ticketer mcp -p /dir      # Start server (short form)
+        mcp-ticketer mcp status       # Check MCP status
+        mcp-ticketer mcp serve        # Explicitly start server
+
+    """
     if ctx.invoked_subcommand is None:
         # No subcommand provided, run the serve command
         # Change to project directory if provided
@@ -1897,6 +2631,17 @@ def install(
         None,
         help="Platform to install (claude-code, claude-desktop, gemini, codex, auggie)",
     ),
+    auto_detect: bool = typer.Option(
+        False,
+        "--auto-detect",
+        "-d",
+        help="Auto-detect and show all installed AI platforms",
+    ),
+    install_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Install for all detected platforms",
+    ),
     adapter: str | None = typer.Option(
         None,
         "--adapter",
@@ -1950,26 +2695,247 @@ def install(
         help="Show what would be done without making changes (for platform installation)",
     ),
 ) -> None:
-    """Install MCP for AI platforms OR initialize adapter setup.
+    """Install MCP server configuration for AI platforms.
+
+    This command configures mcp-ticketer as an MCP server for various AI
+    platforms. It updates platform-specific configuration files to enable
+    mcp-ticketer integration.
+
+    RECOMMENDED: Use 'mcp-ticketer setup' for first-time setup, which
+    handles both adapter configuration and platform installation together.
 
-    With platform argument (new syntax): Install MCP configuration for AI platforms
-    Without platform argument (legacy): Run adapter setup wizard (same as 'init' and 'setup')
+    Platform Installation:
+        # Auto-detect and prompt for platform selection
+        mcp-ticketer install
+
+        # Show all detected platforms
+        mcp-ticketer install --auto-detect
 
-    New Command Structure:
-        # Install MCP for AI platforms
+        # Install for all detected platforms
+        mcp-ticketer install --all
+
+        # Install for specific platform
         mcp-ticketer install claude-code     # Claude Code (project-level)
         mcp-ticketer install claude-desktop  # Claude Desktop (global)
         mcp-ticketer install gemini          # Gemini CLI
         mcp-ticketer install codex           # Codex
         mcp-ticketer install auggie          # Auggie
 
-    Legacy Adapter Setup (still supported):
-        mcp-ticketer install                 # Interactive setup wizard
-        mcp-ticketer install --adapter linear
+    Legacy Usage (adapter setup, deprecated - use 'init' or 'setup' instead):
+        mcp-ticketer install --adapter linear  # Use 'init' or 'setup' instead
 
     """
+    from .platform_detection import PlatformDetector, get_platform_by_name
+
+    detector = PlatformDetector()
+
+    # Handle auto-detect flag (just show detected platforms and exit)
+    if auto_detect:
+        detected = detector.detect_all(
+            project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        if not detected:
+            console.print("[yellow]No AI platforms detected.[/yellow]")
+            console.print("\n[bold]Supported platforms:[/bold]")
+            console.print("  • Claude Code - Project-level configuration")
+            console.print("  • Claude Desktop - Global GUI application")
+            console.print("  • Auggie - CLI tool with global config")
+            console.print("  • Codex - CLI tool with global config")
+            console.print("  • Gemini - CLI tool with project/global config")
+            console.print(
+                "\n[dim]Install these platforms to use them with mcp-ticketer.[/dim]"
+            )
+            return
+
+        console.print("[bold]Detected AI platforms:[/bold]\n")
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Platform", style="green")
+        table.add_column("Status", style="yellow")
+        table.add_column("Scope", style="blue")
+        table.add_column("Config Path", style="dim")
+
+        for plat in detected:
+            status = "✓ Installed" if plat.is_installed else "⚠ Config Issue"
+            table.add_row(plat.display_name, status, plat.scope, str(plat.config_path))
+
+        console.print(table)
+        console.print(
+            "\n[dim]Run 'mcp-ticketer install <platform>' to configure a specific platform[/dim]"
+        )
+        console.print(
+            "[dim]Run 'mcp-ticketer install --all' to configure all detected platforms[/dim]"
+        )
+        return
+
+    # Handle --all flag (install for all detected platforms)
+    if install_all:
+        detected = detector.detect_all(
+            project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        if not detected:
+            console.print("[yellow]No AI platforms detected.[/yellow]")
+            console.print(
+                "Run 'mcp-ticketer install --auto-detect' to see supported platforms."
+            )
+            return
+
+        # Handle dry-run mode - show what would be installed without actually installing
+        if dry_run:
+            console.print(
+                "\n[yellow]DRY RUN - The following platforms would be configured:[/yellow]\n"
+            )
+
+            installable_count = 0
+            for plat in detected:
+                if plat.is_installed:
+                    console.print(f"  ✓ {plat.display_name} ({plat.scope})")
+                    installable_count += 1
+                else:
+                    console.print(
+                        f"  ⚠ {plat.display_name} ({plat.scope}) - would be skipped (configuration issue)"
+                    )
+
+            console.print(
+                f"\n[dim]Would configure {installable_count} platform(s)[/dim]"
+            )
+            return
+
+        console.print(
+            f"[bold]Installing for {len(detected)} detected platform(s)...[/bold]\n"
+        )
+
+        # Import configuration functions
+        from .auggie_configure import configure_auggie_mcp
+        from .codex_configure import configure_codex_mcp
+        from .gemini_configure import configure_gemini_mcp
+        from .mcp_configure import configure_claude_mcp
+
+        # Map platform names to configuration functions
+        platform_mapping = {
+            "claude-code": lambda: configure_claude_mcp(
+                global_config=False, force=True
+            ),
+            "claude-desktop": lambda: configure_claude_mcp(
+                global_config=True, force=True
+            ),
+            "auggie": lambda: configure_auggie_mcp(force=True),
+            "gemini": lambda: configure_gemini_mcp(scope="project", force=True),
+            "codex": lambda: configure_codex_mcp(force=True),
+        }
+
+        success_count = 0
+        failed = []
+
+        for plat in detected:
+            if not plat.is_installed:
+                console.print(
+                    f"[yellow]⚠[/yellow]  Skipping {plat.display_name} (configuration issue)"
+                )
+                continue
+
+            config_func = platform_mapping.get(plat.name)
+            if not config_func:
+                console.print(
+                    f"[yellow]⚠[/yellow]  No installer for {plat.display_name}"
+                )
+                continue
+
+            try:
+                console.print(f"[cyan]Installing for {plat.display_name}...[/cyan]")
+                config_func()
+                success_count += 1
+            except Exception as e:
+                console.print(
+                    f"[red]✗[/red]  Failed to install for {plat.display_name}: {e}"
+                )
+                failed.append(plat.display_name)
+
+        console.print(
+            f"\n[bold]Installation complete:[/bold] {success_count} succeeded"
+        )
+        if failed:
+            console.print(f"[red]Failed:[/red] {', '.join(failed)}")
+        return
+
+    # If no platform argument and no adapter flag, auto-detect and prompt
+    if platform is None and adapter is None:
+        detected = detector.detect_all(
+            project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        # Filter to only installed platforms
+        installed = [p for p in detected if p.is_installed]
+
+        if not installed:
+            console.print("[yellow]No AI platforms detected.[/yellow]")
+            console.print("\n[bold]To see supported platforms:[/bold]")
+            console.print("  mcp-ticketer install --auto-detect")
+            console.print("\n[bold]Or run legacy adapter setup:[/bold]")
+            console.print("  mcp-ticketer install --adapter <adapter-type>")
+            return
+
+        # Show detected platforms and prompt for selection
+        console.print("[bold]Detected AI platforms:[/bold]\n")
+        for idx, plat in enumerate(installed, 1):
+            console.print(f"  {idx}. {plat.display_name} ({plat.scope})")
+
+        console.print(
+            "\n[dim]Enter the number of the platform to configure, or 'q' to quit:[/dim]"
+        )
+        choice = typer.prompt("Select platform")
+
+        if choice.lower() == "q":
+            console.print("Installation cancelled.")
+            return
+
+        try:
+            idx = int(choice) - 1
+            if idx < 0 or idx >= len(installed):
+                console.print("[red]Invalid selection.[/red]")
+                raise typer.Exit(1) from None
+            platform = installed[idx].name
+        except ValueError as e:
+            console.print("[red]Invalid input. Please enter a number.[/red]")
+            raise typer.Exit(1) from e
+
     # If platform argument is provided, handle MCP platform installation (NEW SYNTAX)
     if platform is not None:
+        # Validate that the platform is actually installed
+        platform_info = get_platform_by_name(
+            platform, project_path=Path(project_path) if project_path else Path.cwd()
+        )
+
+        if platform_info and not platform_info.is_installed:
+            console.print(
+                f"[yellow]⚠[/yellow]  {platform_info.display_name} was detected but has a configuration issue."
+            )
+            console.print(f"[dim]Config path: {platform_info.config_path}[/dim]\n")
+
+            proceed = typer.confirm(
+                "Do you want to proceed with installation anyway?", default=False
+            )
+            if not proceed:
+                console.print("Installation cancelled.")
+                return
+
+        elif not platform_info:
+            # Platform not detected at all - warn but allow proceeding
+            console.print(
+                f"[yellow]⚠[/yellow]  Platform '{platform}' not detected on this system."
+            )
+            console.print(
+                "[dim]Run 'mcp-ticketer install --auto-detect' to see detected platforms.[/dim]\n"
+            )
+
+            proceed = typer.confirm(
+                "Do you want to proceed with installation anyway?", default=False
+            )
+            if not proceed:
+                console.print("Installation cancelled.")
+                return
+
         # Import configuration functions
         from .auggie_configure import configure_auggie_mcp
         from .codex_configure import configure_codex_mcp
@@ -2005,7 +2971,7 @@ def install(
             console.print("\n[bold]Available platforms:[/bold]")
             for p in platform_mapping.keys():
                 console.print(f"  • {p}")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
         config = platform_mapping[platform]
 
@@ -2017,7 +2983,7 @@ def install(
             config["func"]()
         except Exception as e:
             console.print(f"[red]Installation failed: {e}[/red]")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from e
         return
 
     # Otherwise, delegate to init for adapter initialization (LEGACY BEHAVIOR)
@@ -2114,7 +3080,7 @@ def remove(
         console.print("\n[bold]Available platforms:[/bold]")
         for p in platform_mapping.keys():
             console.print(f"  • {p}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     config = platform_mapping[platform]
 
@@ -2122,7 +3088,7 @@ def remove(
         config["func"]()
     except Exception as e:
         console.print(f"[red]Removal failed: {e}[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @app.command()
@@ -2161,7 +3127,7 @@ def uninstall(
 
 
 @app.command(deprecated=True, hidden=True)
-def check(queue_id: str = typer.Argument(..., help="Queue ID to check")):
+def check(queue_id: str = typer.Argument(..., help="Queue ID to check")) -> None:
     """Check status of a queued operation.
 
     DEPRECATED: Use 'mcp-ticketer ticket check' instead.
@@ -2174,7 +3140,7 @@ def check(queue_id: str = typer.Argument(..., help="Queue ID to check")):
 
     if not item:
         console.print(f"[red]Queue item not found: {queue_id}[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Display status
     console.print(f"\n[bold]Queue Item: {item.id}[/bold]")
@@ -2216,7 +3182,7 @@ def mcp_serve(
     base_path: str | None = typer.Option(
         None, "--base-path", help="Base path for AITrackdown adapter"
     ),
-):
+) -> None:
     """Start MCP server for JSON-RPC communication over stdio.
 
     This command is used by Claude Code/Desktop when connecting to the MCP server.
@@ -2236,7 +3202,7 @@ def mcp_serve(
     # Load configuration (respects project-specific config in cwd)
     config = load_config()
 
-    # Determine adapter type with priority: CLI arg > .env files > config > default
+    # Determine adapter type with priority: CLI arg > config > .env files > default
     if adapter:
         # Priority 1: Command line argument
         adapter_type = adapter.value
@@ -2244,18 +3210,24 @@ def mcp_serve(
         adapters_config = config.get("adapters", {})
         adapter_config = adapters_config.get(adapter_type, {})
     else:
-        # Priority 2: .env files
-        from ..mcp.server.main import _load_env_configuration
-
-        env_config = _load_env_configuration()
-        if env_config:
-            adapter_type = env_config["adapter_type"]
-            adapter_config = env_config["adapter_config"]
-        else:
-            # Priority 3: Configuration file
-            adapter_type = config.get("default_adapter", "aitrackdown")
+        # Priority 2: Configuration file (project-specific)
+        adapter_type = config.get("default_adapter")
+        if adapter_type:
             adapters_config = config.get("adapters", {})
             adapter_config = adapters_config.get(adapter_type, {})
+        else:
+            # Priority 3: .env files (auto-detection fallback)
+            from ..mcp.server.main import _load_env_configuration
+
+            env_config = _load_env_configuration()
+            if env_config:
+                adapter_type = env_config["adapter_type"]
+                adapter_config = env_config["adapter_config"]
+            else:
+                # Priority 4: Default fallback
+                adapter_type = "aitrackdown"
+                adapters_config = config.get("adapters", {})
+                adapter_config = adapters_config.get(adapter_type, {})
 
     # Override with command line options if provided (highest priority)
     if base_path and adapter_type == "aitrackdown":
@@ -2305,7 +3277,7 @@ def mcp_claude(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Claude Code to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and updates
@@ -2331,7 +3303,7 @@ def mcp_claude(
         configure_claude_mcp(global_config=global_config, force=force)
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="gemini")
@@ -2345,7 +3317,7 @@ def mcp_gemini(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Gemini CLI to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and creates
@@ -2372,13 +3344,13 @@ def mcp_gemini(
         console.print(
             f"[red]✗ Invalid scope:[/red] '{scope}'. Must be 'project' or 'user'"
         )
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     try:
         configure_gemini_mcp(scope=scope, force=force)  # type: ignore
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="codex")
@@ -2386,7 +3358,7 @@ def mcp_codex(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Codex CLI to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and creates
@@ -2410,7 +3382,7 @@ def mcp_codex(
         configure_codex_mcp(force=force)
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="auggie")
@@ -2418,7 +3390,7 @@ def mcp_auggie(
     force: bool = typer.Option(
         False, "--force", "-f", help="Overwrite existing configuration"
     ),
-):
+) -> None:
     """Configure Auggie CLI to use mcp-ticketer MCP server.
 
     Reads configuration from .mcp-ticketer/config.json and creates
@@ -2442,11 +3414,11 @@ def mcp_auggie(
         configure_auggie_mcp(force=force)
     except Exception as e:
         console.print(f"[red]✗ Configuration failed:[/red] {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @mcp_app.command(name="status")
-def mcp_status():
+def mcp_status() -> None:
     """Check MCP server status.
 
     Shows whether the MCP server is configured and running for various platforms.
@@ -2544,7 +3516,7 @@ def mcp_status():
 
 
 @mcp_app.command(name="stop")
-def mcp_stop():
+def mcp_stop() -> None:
     """Stop MCP server (placeholder - MCP runs on-demand via stdio).
 
     Note: The MCP server runs on-demand when AI clients connect via stdio.
@@ -2568,8 +3540,8 @@ def mcp_stop():
 app.add_typer(mcp_app, name="mcp")
 
 
-def main():
-    """Main entry point."""
+def main() -> None:
+    """Execute the main CLI application entry point."""
     app()