bootstrap.py

#!/usr/bin/env python3
"""
Gemini Workspace Framework v1.0.0

Creates, validates, and upgrades self-contained LLM workspaces.

Usage:
    python bootstrap.py                           # Interactive mode
    python bootstrap.py -t 2 -n myproject        # Create Standard workspace
    python bootstrap.py --validate ./myproject   # Validate workspace
    python bootstrap.py --upgrade ./myproject    # Upgrade to next tier
Features:
    - Tiered workspace system (Lite, Standard, Enterprise)
    - Built-in validation and health monitoring
    - Tier upgrades with backup/rollback support
    - Template system for custom workspace types

Build Information:
    Version: 1.0.0
    Built: 2026-03-22 04:32:06 UTC
    Source: Modular architecture (bootstrap_src/)

This file is AUTO-GENERATED from modular source.
DO NOT EDIT THIS FILE DIRECTLY.
Edit files in bootstrap_src/ and rebuild with: python bootstrap_src/build.py
"""

from typing import List
import os
import re
import json
import hashlib
import logging
from pathlib import Path
from datetime import datetime, timezone
from abc import ABC, abstractmethod
from typing import Dict
from typing import Optional
from dataclasses import dataclass, asdict
from typing import Any
import subprocess
import sys
from functools import lru_cache
import shutil
from concurrent.futures import ThreadPoolExecutor, as_completed
import tarfile
import tempfile
import argparse


# ==============================================================================
# Module: config.py
# ==============================================================================

"""
Bootstrap Source Configuration Module

Central configuration and constants for workspace bootstrap.
Defines tier specifications, default structures, and branding.
"""


# Version Information
VERSION = "1.0.1"
DEFAULT_PYTHON_VERSION = "3.11"

# Exit Codes
EXIT_SUCCESS = 0
EXIT_VALIDATION_ERROR = 1
EXIT_CREATION_ERROR = 2
EXIT_UPGRADE_ERROR = 3
EXIT_ROLLBACK_ERROR = 4
EXIT_CONFIG_ERROR = 5
EXIT_WORKSPACE_ERROR = 6
EXIT_INTERRUPT = 130
EXIT_UNEXPECTED_ERROR = 255
SCRIPT_NAME = "Gemini Workspace Framework"

# Supported LLM Providers
SUPPORTED_PROVIDERS = ["gemini"]
DEFAULT_PROVIDER = "gemini"

# Tier Definitions
TIER_NAMES = {"1": "Lite", "2": "Standard", "3": "Enterprise"}

TIER_DESCRIPTIONS = {
    "1": "Lightweight workspace with basic features",
    "2": "Full-featured workspace with testing and quality gates",
    "3": "Enterprise workspace with advanced features and evaluations",
}

# Directory Structure Templates
BASE_DIRECTORIES = [
    "src",
    "tests",
    "docs",
    "logs",
    "scratchpad",
    ".agent/skills",
    ".agent/workflows",
]

TIER_SPECIFIC_DIRECTORIES = {
    "1": [],  # Lite has no additional directories
    "2": ["docs/architecture", "docs/api"],
    "3": ["docs/architecture", "docs/api", "docs/evaluations", "benchmarks"],
}

# Script Organization Patterns
# Maps tier -> category -> list of script names (without .py extension)
SCRIPT_CATEGORIES = {
    "1": {  # Lite: flat structure in scripts/
        "": [
            "run_audit",
            "manage_session",
            "check_status",
            "index_docs",
            "list_skills",
            "manage_skills",
            "explore_skills",
        ]
    },
    "2": {  # Standard: functional categories
        "workspace": ["run_audit", "manage_session", "check_status", "create_snapshot"],
        "skills": ["list_skills", "manage_skills", "explore_skills"],
        "docs": ["index_docs"],
    },
    "3": {  # Enterprise: domain-based (shared is default)
        "shared": ["run_audit", "manage_session", "check_status", "create_snapshot"]
    },
}

# Standard script verbs for verb_noun.py naming convention
SCRIPT_VERBS = [
    "run",  # Execute processes (audit, tests)
    "check",  # Inspections (status, health)
    "manage",  # CRUD operations (session, config, skills)
    "generate",  # Create artifacts (reports, docs)
    "sync",  # Data synchronization
    "index",  # Build search indices
    "list",  # Display collections
    "create",  # Create new items (snapshots)
    "explore",  # Discovery/exploration (skills)
]

# File Permissions (Standard tier paths as reference)
EXECUTABLE_FILES = [
    "scripts/workspace/run_audit.py",
    "scripts/workspace/manage_session.py",
    "scripts/workspace/check_status.py",
    "scripts/workspace/create_snapshot.py",
    "scripts/docs/index_docs.py",
    "scripts/skills/list_skills.py",
    "scripts/skills/manage_skills.py",
    "scripts/skills/explore_skills.py",
]

# Snapshot configuration
SNAPSHOTS_DIR = ".snapshots"

# Color Codes for Terminal Output
COLORS = {
    "BLUE": "\\033[1;34m",
    "GREEN": "\\033[1;32m",
    "YELLOW": "\\033[1;33m",
    "RED": "\\033[1;31m",
    "NC": "\\033[0m",  # No Color
}

# Branding
BRANDING = {
    "emoji": {
        "system": "⚙️",
        "tools": "🔧",
        "branding": "🎨",
        "session": "⏱️",
        "health": "🏥",
        "hygiene": "🧹",
        "security": "🛡️",
        "app": "🚀",
        "test": "🧪",
        "docs": "📚",
        "env": "📦",
        "archive": "🛡️",
    }
}

# Makefile .PHONY targets by tier
PHONY_TARGETS = {
    "1": [
        "run",
        "test",
        "install",
        "context",
        "clean",
        "audit",
        "session-start",
        "session-end",
        "init",
        "list-skills",
        "help",
        "doctor",
        "status",
        "health",
        "lint",
        "format",
        "ci-local",
        "deps-check",
        "security-scan",
        "session-force-end-all",
        "onboard",
        "sync",
        "search",
        "list-todos",
        "index",
        "backup",
        "skill-add",
        "skill-remove",
    ],
    "2": [
        "run",
        "test",
        "test-watch",
        "coverage",
        "typecheck",
        "install",
        "context",
        "clean",
        "audit",
        "session-start",
        "session-end",
        "init",
        "list-skills",
        "help",
        "snapshot",
        "restore",
        "doctor",
        "status",
        "health",
        "format",
        "update",
        "docs",
        "lint",
        "ci-local",
        "deps-check",
        "security-scan",
        "session-force-end-all",
        "onboard",
        "backup",
        "sync",
        "search",
        "list-todos",
        "index",
        "skill-add",
        "skill-remove",
    ],
    "3": [
        "scan",
        "test",
        "test-watch",
        "coverage",
        "typecheck",
        "audit",
        "eval",
        "context",
        "context-frontend",
        "context-backend",
        "install",
        "clean",
        "session-start",
        "session-end",
        "init",
        "list-skills",
        "shift-report",
        "snapshot",
        "restore",
        "doctor",
        "status",
        "health",
        "help",
        "lint",
        "format",
        "update",
        "lock",
        "docs",
        "ci-local",
        "deps-check",
        "security-scan",
        "session-force-end-all",
        "onboard",
        "backup",
        "sync",
        "search",
        "list-todos",
        "index",
        "skill-add",
        "skill-remove",
    ],
}

# Default requirements by tier
DEFAULT_REQUIREMENTS = {
    "1": [
        "# Lite Workspace Dependencies",
        "# Add your project dependencies here",
        "",
        "# Code Quality",
        "ruff>=0.1.0",
    ],
    "2": [
        "# Standard Workspace Dependencies",
        "# Add your project dependencies here",
        "",
        "# Testing",
        "pytest>=7.0.0",
        "pytest-cov>=4.0.0",
        "",
        "# Code Quality",
        "ruff>=0.1.0",
        "mypy>=1.0.0",
    ],
    "3": [
        "# Enterprise Workspace Dependencies",
        "# Add your project dependencies here",
        "",
        "# High-performance package manager (recommended)",
        "uv>=0.1.0",
        "",
        "# Testing & Quality",
        "pytest>=7.0.0",
        "pytest-cov>=4.0.0",
        "pytest-benchmark>=4.0.0",
        "",
        "# Code Quality",
        "ruff>=0.1.0",
        "mypy>=1.0.0",
    ],
}

# Git ignore patterns
GITIGNORE_PATTERNS = [
    "# Python",
    "__pycache__/",
    "*.py[cod]",
    "*$py.class",
    "*.so",
    ".Python",
    "build/",
    "develop-eggs/",
    "dist/",
    "downloads/",
    "eggs/",
    ".eggs/",
    "lib/",
    "lib64/",
    "parts/",
    "sdist/",
    "var/",
    "wheels/",
    "*.egg-info/",
    ".installed.cfg",
    "*.egg",
    "",
    "# Virtual Environment",
    "venv/",
    "ENV/",
    "env/",
    ".venv/",
    "",
    "# IDE",
    ".vscode/",
    ".idea/",
    "*.swp",
    "*.swo",
    "*~",
    "",
    "# Project Specific",
    "logs/*.log",
    "scratchpad/*",
    ".env",
    ".env.local",
    "",
    "# Testing",
    ".pytest_cache/",
    ".coverage",
    "htmlcov/",
    "",
    "# Gemini Cache",
    ".gemini/cache/",
    "",
    "# OS",
    ".DS_Store",
    "Thumbs.db",
]


def get_all_directories(tier: str) -> List[str]:
    """Get complete directory list for a tier."""
    return BASE_DIRECTORIES + TIER_SPECIFIC_DIRECTORIES.get(tier, [])


def get_tier_name(tier: str) -> str:
    """Get human-readable tier name."""
    return TIER_NAMES.get(tier, "Unknown")


def get_phony_targets(tier: str) -> List[str]:
    """Get .PHONY targets for a tier."""
    return PHONY_TARGETS.get(tier, PHONY_TARGETS["1"])


def get_gitignore_for_tier(tier: str) -> List[str]:
    """Get complete .gitignore patterns for a tier including data directories.

    Args:
        tier: Workspace tier ("1" for Lite, "2" for Standard, "3" for Enterprise)

    Returns:
        Complete list of gitignore patterns
    """
    patterns = GITIGNORE_PATTERNS.copy()

    # Add tier-specific data patterns
    if tier in ["1", "2"]:  # Lite/Standard: flat data structure
        patterns.extend(
            [
                "",
                "# Data (Lite/Standard tier pattern)",
                "data/inputs/*",
                "!data/inputs/.gitkeep",
                "data/outputs/*",
            ]
        )
    else:  # Enterprise: domain-based data structure
        patterns.extend(
            [
                "",
                "# Data (Enterprise tier pattern)",
                "data/*/inputs/*",
                "data/*/outputs/*",
                "!data/*/.gitkeep",
            ]
        )

    return patterns


# Tier Metadata
TIERS = {
    "1": {
        "name": "Lite",
        "desc": "Lightweight workspace with basic features",
        "order": 1,
    },
    "2": {
        "name": "Standard",
        "desc": "Full-featured workspace with testing",
        "order": 2,
    },
    "3": {
        "name": "Enterprise",
        "desc": "Enterprise workspace with advanced features",
        "order": 3,
    },
}

# Templates (placeholder - can be extended)
TEMPLATES = {}

# ==============================================================================
# Module: core_utils.py
# ==============================================================================

"""
Core Bootstrap Module

Defines exceptions, utilities, validators, and helper functions.
"""


# Import constants from config (these are available in the monolithic build)


# Version constant
VERSION = "1.0.1"
DEFAULT_PYTHON_VERSION = "3.11"
VALID_PYTHON_VERSION_PATTERN = re.compile(r"^3\.\d+$")

# Global flag for color output
USE_COLOR: bool = os.environ.get("NO_COLOR") is None


class Colors:
    GREEN = "\033[92m"
    RED = "\033[91m"
    YELLOW = "\033[93m"
    BLUE = "\033[94m"
    CYAN = "\033[96m"
    BOLD = "\033[1m"
    DIM = "\033[2m"
    RESET = "\033[0m"


def _c(code: str) -> str:
    """Return color code if colors are enabled, empty string otherwise."""
    return code if USE_COLOR else ""


def show_progress(step: int, total: int, message: str) -> None:
    """Display progress indicator for long-running operations."""
    bar_length = 30
    filled = int(bar_length * step / total)
    bar = "█" * filled + "░" * (bar_length - filled)
    percent = int(100 * step / total)
    print(
        f"\r{_c(Colors.CYAN)}[{bar}] {percent}% {_c(Colors.RESET)} {message}",
        end="",
        flush=True,
    )
    if step == total:
        print()  # New line when complete


def success(msg: str) -> None:
    print(f"{_c(Colors.GREEN)}✅ {msg}{_c(Colors.RESET)}")


def error(msg: str) -> None:
    print(f"{_c(Colors.RED)}❌ {msg}{_c(Colors.RESET)}")


def warning(msg: str) -> None:
    print(f"{_c(Colors.YELLOW)}⚠️  {msg}{_c(Colors.RESET)}")


def info(msg: str) -> None:
    print(f"{_c(Colors.BLUE)}ℹ️  {msg}{_c(Colors.RESET)}")


def header(msg: str) -> None:
    print(f"\n{_c(Colors.BOLD)}{msg}{_c(Colors.RESET)}")


def dim(msg: str) -> None:
    print(f"{_c(Colors.DIM)}{msg}{_c(Colors.RESET)}")


# --- STRUCTURED LOGGING & TELEMETRY ---

# Configure structured logging
logging.basicConfig(
    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)


def validate_project_name(name: str) -> None:
    """Validate project name.

    Args:
        name: Project name to validate

    Raises:
        ValidationError: If project name is invalid
    """
    if not name:
        raise ValidationError("Project name cannot be empty")
    if len(name) > 50:
        raise ValidationError("Project name must be 50 characters or less")
    if not re.match(r"^[a-zA-Z][a-zA-Z0-9_-]*$", name):
        raise ValidationError(
            "Project name must start with a letter and contain only letters, numbers, underscores, and hyphens"
        )
    # Path traversal protection
    if ".." in name or "/" in name or "\\" in name:
        raise ValidationError(
            "Project name cannot contain path separators or parent directory references"
        )
    reserved = {"test", "tests", "src", "lib", "bin", "build", "dist"}
    if name.lower() in reserved:
        raise ValidationError(f"'{name}' is a reserved name, please choose another")


def validate_python_version(version: str) -> None:
    """Validate Python version string format.

    Args:
        version: Expected format like '3.10', '3.11', '3.12'

    Raises:
        ValidationError: If Python version format is invalid
    """
    if not version:
        raise ValidationError("Python version cannot be empty")
    if not VALID_PYTHON_VERSION_PATTERN.match(version):
        raise ValidationError(
            f"Invalid Python version '{version}'. Expected format: 3.10, 3.11, 3.12, etc."
        )


def validate_tier_upgrade(current_tier: str, target_tier: str) -> None:
    """Validate tier upgrade path prevents downgrades.

    Args:
        current_tier: Current workspace tier (1, 2, or 3)
        target_tier: Target tier for upgrade

    Raises:
        ValidationError: If upgrade path is invalid
    """
    try:
        current = int(current_tier)
        target = int(target_tier)

        if target < current:
            raise ValidationError(
                f"Cannot downgrade from Tier {current_tier} ({TIERS[current_tier]['name']}) to Tier {target_tier} ({TIERS[target_tier]['name']})"
            )

        if target == current:
            raise ValidationError(
                f"Workspace is already at Tier {current_tier} ({TIERS[current_tier]['name']})"
            )

        # Validate tier exists
        if target_tier not in TIERS:
            raise ValidationError(
                f"Invalid target tier '{target_tier}'. Must be 1, 2, or 3"
            )

    except (ValueError, KeyError):
        raise ValidationError(
            f"Invalid tier values: current='{current_tier}', target='{target_tier}'"
        )


def validate_template_name(name: str) -> None:
    """Validate template name exists in TEMPLATES.

    Args:
        name: Template name to validate

    Raises:
        ValidationError: If template name is unknown
    """
    if not name:
        raise ValidationError("Template name cannot be empty")

    if name not in TEMPLATES:
        available = ", ".join(sorted(TEMPLATES.keys()))
        raise ValidationError(
            f"Unknown template '{name}'. Available templates: {available}"
        )


def validate_manifest_path(path: str) -> None:
    """Prevent path traversal in context manifests.

    Args:
        path: File path from manifest

    Raises:
        ValidationError: If path contains security vulnerabilities

    Security:
        Prevents loading files outside workspace via path traversal.
    """
    if not path:
        raise ValidationError("Manifest path cannot be empty")

    # Reject absolute paths
    if path.startswith("/") or (
        len(path) > 1 and path[1] == ":"
    ):  # Unix or Windows absolute
        raise ValidationError(f"Manifest paths must be relative, not absolute: {path}")

    # Reject UNC paths (Windows network paths)
    if path.startswith("\\\\"):
        raise ValidationError(f"UNC paths not allowed in manifest: {path}")

    # Reject parent directory references
    if ".." in path.split("/"):
        raise ValidationError(f"Path traversal detected in manifest: {path}")

    # Check for null bytes (security)
    if "\0" in path:
        raise ValidationError(f"Null byte detected in manifest path: {path}")


def validate_rollback_backup(backup_name: str, workspace_path: Path) -> None:
    """Validate backup exists before attempting rollback.

    Args:
        backup_name: Name of backup/snapshot to restore
        workspace_path: Path to workspace

    Raises:
        ValidationError: If backup doesn't exist or is invalid
    """
    if not backup_name:
        raise ValidationError("Backup name cannot be empty")

    backup_dir = workspace_path / SNAPSHOTS_DIR / backup_name

    if not backup_dir.exists():
        # List available backups
        snapshots_path = workspace_path / SNAPSHOTS_DIR
        if snapshots_path.exists():
            available = [d.name for d in snapshots_path.iterdir() if d.is_dir()]
            if available:
                available_str = ", ".join(sorted(available))
                raise ValidationError(
                    f"Backup '{backup_name}' not found. Available: {available_str}"
                )
        raise ValidationError(f"Backup '{backup_name}' not found. No backups exist.")

    if not backup_dir.is_dir():
        raise ValidationError(
            f"Backup path exists but is not a directory: {backup_dir}"
        )


def load_config(config_path: Path | None = None) -> dict:
    """Load config from .gemini-bootstrap.json if it exists.

    Args:
        config_path: Optional explicit path; defaults to cwd/.gemini-bootstrap.json

    Returns:
        Configuration dictionary or empty dict if not found/invalid

    Security:
        Path traversal validation prevents loading config from outside cwd.
    """
    path = config_path or Path.cwd() / ".gemini-bootstrap.json"

    # Security: Validate path doesn't traverse outside expected locations
    try:
        resolved_path = path.resolve()
        cwd_resolved = Path.cwd().resolve()
        # Allow paths within cwd or explicit absolute paths that exist
        if config_path is None and not str(resolved_path).startswith(str(cwd_resolved)):
            warning("Config path traversal detected, ignoring")
            return {}
    except (OSError, ValueError):
        warning("Invalid config path, ignoring")
        return {}

    if path.exists():
        try:
            with open(path) as f:
                return json.load(f)
        except json.JSONDecodeError:
            warning("Invalid .gemini-bootstrap.json (malformed JSON), ignoring")
        except PermissionError:
            warning("Cannot read .gemini-bootstrap.json (permission denied), ignoring")
        except Exception as e:
            warning(f"Unexpected error reading .gemini-bootstrap.json: {e}")
    return {}


def _get_file_cache_key(path: Path) -> str:
    """Generate cache key based on file modification time for cache invalidation.

    Args:
        path: File or directory path to generate cache key for

    Returns:
        Cache key string combining path and mtime, or path:missing if not exists

    Used by @lru_cache decorated functions to automatically invalidate cache
    when the underlying file changes.
    """
    if not path.exists():
        return f"{path}:missing"

    try:
        if path.is_file():
            mtime = path.stat().st_mtime
            return f"{path}:{mtime}"
        else:
            # For directories, hash all file mtimes for comprehensive invalidation
            mtimes = []
            for file in path.rglob("*"):
                if file.is_file():
                    try:
                        mtimes.append(
                            f"{file.relative_to(path)}:{file.stat().st_mtime}"
                        )
                    except (OSError, ValueError):
                        # Skip files we can't stat
                        continue
            if mtimes:
                return (
                    f"{path}:"
                    + hashlib.sha256("".join(sorted(mtimes)).encode()).hexdigest()
                )
            else:
                return f"{path}:empty"
    except (OSError, PermissionError):
        # If we can't access the file, use a timestamp-based key
        return f"{path}:error:{datetime.now(timezone.utc).timestamp()}"


# --- CUSTOM EXCEPTION HIERARCHY ---


class WorkspaceError(Exception):
    """Base exception for all workspace-related errors.

    All workspace operations should raise subclasses of this exception instead
       of using sys.exit(), allowing for proper exception handling and testing.
    """

    pass


class ValidationError(WorkspaceError):
    """Raised when validation fails (project name, tier, template, paths, etc.).

    Examples:
        - Invalid project name format
        - Invalid tier upgrade path (downgrade attempt)
        - Invalid Python version string
        - Path traversal detected in manifest
    """

    pass


class CreationError(WorkspaceError):
    """Raised when workspace creation fails.

    Examples:
        - Directory already exists
        - Insufficient permissions
        - Disk space issues
        - Template application errors
    """

    pass


class UpgradeError(WorkspaceError):
    """Raised when workspace upgrade fails.

    Examples:
        - Invalid upgrade path (downgrade attempt)
        - Missing workspace.json
        - Backup creation fails
        - File conflicts during upgrade
    """

    pass


class RollbackError(WorkspaceError):
    """Raised when rollback/restore operation fails.

    Examples:
        - Backup/snapshot not found
        - Restore operation fails
        - Invalid backup structure
    """

    pass


class ConfigurationError(WorkspaceError):
    """Raised when configuration is invalid or missing.

    Examples:
        - Malformed workspace.json
        - Missing required fields
        - Invalid settings  - Schema validation failures
    """

    pass


# ==============================================================================
# Module: providers/base.py
# ==============================================================================

"""
LLM Provider Base Class

Abstract interface for LLM-specific workspace configurations.
Providers implement templates for config files, MCP settings, and directory structures.
"""


class LLMProvider(ABC):
    """Abstract base class for LLM workspace providers."""

    @property
    @abstractmethod
    def name(self) -> str:
        """Provider name."""
        pass

    @property
    @abstractmethod
    def config_filename(self) -> str:
        """Main configuration file name (e.g., 'GEMINI.md')."""
        pass

    @property
    @abstractmethod
    def config_dirname(self) -> str:
        """Configuration directory name (e.g., '.gemini')."""
        pass

    @abstractmethod
    def get_config_template(self, tier: str, project_name: str) -> str:
        """
        Generate the main configuration file content.

        Args:
            tier: Workspace tier ("1", "2", or "3")
            project_name: Name of the workspace project

        Returns:
            Configuration file content as string
        """
        pass

    @abstractmethod
    def get_readme_template(self, tier: str, project_name: str) -> str:
        """
        Generate README.md content.

        Args:
            tier: Workspace tier
            project_name: Name of the workspace project

        Returns:
            README content as string
        """
        pass

    @abstractmethod
    def get_mcp_config(self) -> Dict:
        """
        Get MCP (Model Context Protocol) server configuration.

        Returns:
            MCP configuration as dictionary
        """
        pass

    @abstractmethod
    def get_settings(self, tier: str) -> Dict:
        """
        Get provider-specific settings.

        Args:
            tier: Workspace tier

        Returns:
            Settings dictionary
        """
        pass

    def get_additional_files(self, tier: str, project_name: str) -> Dict[str, str]:
        """
        Get any additional provider-specific files.

        Args:
            tier: Workspace tier
            project_name: Name of the workspace project

        Returns:
            Dictionary mapping file paths to content
        """
        return {}

    def get_additional_directories(self, tier: str) -> List[str]:
        """
        Get any additional provider-specific directories.

        Args:
            tier: Workspace tier

        Returns:
            List of directory paths
        """
        return []


# ==============================================================================
# Module: providers/gemini.py
# ==============================================================================

"""
Gemini LLM Provider

Concrete implementation of LLMProvider for Google Gemini workspaces.
"""


# Import base class (resolved at build time)
try:
    from providers.base import LLMProvider
except ImportError:
    from .base import LLMProvider

# Version constant (imported from config in final build)
VERSION = "1.0.1"


class GeminiProvider(LLMProvider):
    """Gemini-specific workspace provider."""

    @property
    def name(self) -> str:
        return "gemini"

    @property
    def config_filename(self) -> str:
        return "GEMINI.md"

    @property
    def config_dirname(self) -> str:
        return ".gemini"

    def get_config_template(self, tier: str, project_name: str) -> str:
        """Generate GEMINI.md constitution."""
        base = """# Gemini Native Workspace ({edition} Edition)
**Philosophy:** "{philosophy}"
**Role:** {role}
**Version:** {version}

## 1. The Cognitive Laws
1.  **Skill Check:** Before asking "How?", check `.agent/skills/`.
2.  **Workflow Adherence:** Follow `.agent/workflows/` for complex tasks.
3.  **Pattern Matching:** Code must mimic `.agent/patterns/`.
4.  **Evolution:** Use the "Gardener Protocol" to modify rules.

## 2. The Laws of Physics
1.  **Hygiene:** Write temp files to `scratchpad/`.
2.  **Safety:** **NEVER** print secrets to stdout.
3.  **Continuity:** Update `docs/roadmap.md` every session.
4.  **Interface:** Use `Makefile` targets. Do not run raw shell commands.
5.  **Sessions:** Start with `make session-start`, end with `make session-end`.
"""
        if tier == "1":
            return (
                base.format(
                    edition="Lite",
                    philosophy="Reliable Automation",
                    role="Automation Specialist",
                    version=VERSION,
                )
                + "\n## 3. Architecture\n* **Input:** `data/inputs/`\n* **Logic:** `src/main.py`\n* **Output:** `logs/run.log`"
            )
        elif tier == "2":
            return (
                base.format(
                    edition="Standard",
                    philosophy="The Modular Monolith",
                    role="Lead Software Engineer",
                    version=VERSION,
                )
                + f"\n## 3. Architecture\n* **Modules:** `src/{project_name}/`\n* **Tests:** `tests/unit/`\n* **Context:** Shared Global Context."
            )
        else:
            return (
                base.format(
                    edition="Enterprise",
                    philosophy="Headless Organization",
                    role="CTO / Architect",
                    version=VERSION,
                )
                + f"\n## 3. Architecture\n* **Domains:** `src/{project_name}/domains/` (Strict Isolation)\n* **Contracts:** `outputs/contracts/`\n* **Evals:** `tests/evals/`\n\n## 4. Multi-Agent Protocol\n* Sub-Agents do NOT inherit Root Context.\n* Use `make shift-report` for handoffs.\n* Run `make snapshot` before major changes."
            )

    def get_readme_template(self, tier: str, project_name: str) -> str:
        """Generate README.md content."""
        return f"# {project_name}\n\nGenerated Gemini Workspace (Tier {tier})\n"

    def get_mcp_config(self) -> Dict:
        """Get MCP server configuration for Gemini."""
        return {"mcpServers": {}}

    def get_settings(self, tier: str) -> Dict:
        """Get Gemini-specific settings."""
        base_settings = {
            "codeExecution": {"enabled": True},
            "contextWindow": {"strategy": "auto"},
        }
        if tier == "3":
            base_settings["multiAgent"] = {"enabled": True}
        return base_settings

    def get_additional_directories(self, tier: str) -> List[str]:
        """Get Gemini-specific directories."""
        return []


# ==============================================================================
# Module: providers/__init__.py
# ==============================================================================

"""
LLM Provider Registry

Central registry for all supported LLM providers.
"""


# Supported providers list
SUPPORTED_PROVIDERS = ["gemini"]

# Default provider
DEFAULT_PROVIDER = "gemini"

# Provider instances (lazy initialization)
_provider_instances: Dict[str, LLMProvider] = {}


def get_provider(name: Optional[str] = None) -> LLMProvider:
    """Get a provider instance by name.

    Args:
        name: Provider name. Defaults to DEFAULT_PROVIDER.

    Returns:
        LLMProvider instance

    Raises:
        ValueError: If provider name is not supported
    """
    provider_name = name or DEFAULT_PROVIDER

    if provider_name not in SUPPORTED_PROVIDERS:
        raise ValueError(
            f"Unsupported provider: {provider_name}. "
            f"Supported providers: {', '.join(SUPPORTED_PROVIDERS)}"
        )

    # Lazy initialization
    if provider_name not in _provider_instances:
        if provider_name == "gemini":
            _provider_instances[provider_name] = GeminiProvider()

    return _provider_instances[provider_name]


def get_all_providers() -> Dict[str, LLMProvider]:
    """Get all provider instances.

    Returns:
        Dictionary mapping provider names to instances
    """
    return {name: get_provider(name) for name in SUPPORTED_PROVIDERS}


__all__ = [
    "LLMProvider",
    "GeminiProvider",
    "get_provider",
    "get_all_providers",
    "SUPPORTED_PROVIDERS",
    "DEFAULT_PROVIDER",
]

# ==============================================================================
# Module: core/makefile.py
# ==============================================================================

"""
Makefile Generation Module

Generates tier-specific Makefiles using composition pattern:
Final Makefile = TIER-SPECIFIC + COMMON
"""


def _script_path(tier: str, script_name: str) -> str:
    """Get tier-specific path for a script."""
    if tier == "1":
        return f"scripts/{script_name}.py"
    elif tier == "2":
        for cat, scripts in SCRIPT_CATEGORIES["2"].items():
            if script_name in scripts:
                return f"scripts/{cat}/{script_name}.py"
        return f"scripts/{script_name}.py"
    else:
        for cat, scripts in SCRIPT_CATEGORIES["3"].items():
            if script_name in scripts:
                return f"scripts/{cat}/{script_name}.py"
        return f"scripts/shared/{script_name}.py"


def get_makefile(tier: str, project_name: str, provider: str = "gemini") -> str:
    """
    Generate complete Makefile for specified tier.

    Args:
        tier: Workspace tier ("1" for Lite, "2" for Standard, "3" for Enterprise)
        project_name: Project name used in tier-specific targets
        provider: LLM provider name

    Returns:
        Complete Makefile content
    """
    return _get_makefile_tier_targets(
        tier, project_name, provider
    ) + _get_makefile_common_targets(tier, provider)


def _get_makefile_tier_targets(
    tier: str, project_name: str, provider: str = "gemini"
) -> str:
    """Generate tier-specific Makefile header and targets."""
    # Get provider-specific config directory
    config_dir = f".{provider}"
    provider_title = provider.title()

    if tier == "1":
        return f"""# {provider_title} Lite Workspace
SHELL := /bin/bash
.PHONY: run test install context clean audit session-start session-end init list-skills help doctor status health lint format ci-local deps-check security-scan session-force-end-all onboard sync search list-todos index backup skill-add skill-remove

# ==============================================================================
# 🎨 BRANDING & COLORS
# ==============================================================================
BLUE   := \\033[1;34m
GREEN  := \\033[1;32m
YELLOW := \\033[1;33m
RED    := \\033[1;31m
NC     := \\033[0m # No Color

# ==============================================================================
# 🚀 APPLICATION ENTRY POINT
# ==============================================================================

# PURPOSE: Execute the main logic of your workspace.
# WHEN: Use this to run your actual software.
run: ## Execute the primary script (src/main.py)
	@echo "$(BLUE)🚀 Launching application...$(NC)"
	@python3 src/main.py

# PURPOSE: Run basic tests (Lite tier - basic checks only).
test: ## Run tests (upgrade to Standard tier for full testing)
	@echo "$(YELLOW)⚠️  Lite tier does not include testing. Upgrade to Standard tier:$(NC)"
	@echo "   python bootstrap.py --upgrade ./"

# ==============================================================================
# 📚 DOCUMENTATION & LLM CONTEXT
# ==============================================================================

# PURPOSE: Extract your project's "identity" for a new AI assistant.
# WHEN: Run this at the start of every NEW LLM conversation.
context: ## Export core Rules/Roadmap ({provider_title.upper()}.md, etc.) for a new LLM conversation
	@echo "$(BLUE)📋 Exporting AI context...$(NC)"
	@for file in $$(cat {config_dir}/manifests/core); do \\
		if [ -f "$$file" ]; then \\
			echo "$(GREEN)--- FILE: $$file ---$(NC)"; \\
			cat "$$file"; \\
			echo ""; \\
		fi; \\
	done

# ==============================================================================
# 📦 ENVIRONMENT MANAGEMENT
# ==============================================================================

# PURPOSE: Install simple dependencies.
# WHEN: Run after initial creation or when adding requirements.
install: ## Install dependencies from requirements.txt
	@echo "$(BLUE)📦 Installing project dependencies...$(NC)"
	@pip3 install -r requirements.txt

# PURPOSE: Check local CI status.
ci-local: ## Run local CI audit and lint checks
	@echo "$(BLUE)🔄 Running local CI checks...$(NC)"
	@python3 scripts/run_audit.py
	@ruff check . || true
	@echo "$(GREEN)✅ Local CI complete (Lite tier - no tests)$(NC)"

# PURPOSE: Diagnose environment and structure issues.
doctor: ## Diagnose common issues and check structure
	@echo "$(BLUE)🔍 Checking environment...$(NC)"
	@python3 --version
	@echo "$(BLUE)📦 Checking dependencies...$(NC)"
	@command -v ruff >/dev/null 2>&1 && echo "$(GREEN)✅ ruff available$(NC)" || echo "$(YELLOW)⚠️  ruff not found (run: pip install ruff)$(NC)"
	@echo "$(BLUE)📁 Checking structure...$(NC)"
	@python3 scripts/run_audit.py

# PURPOSE: Refresh the master index of all documents.
index: ## Regenerate the master Table of Contents in WORKSPACE_INDEX.md
	@echo "$(BLUE)🗂️  Indexing documentation...$(NC)"
	@python3 scripts/index_docs.py

# ==============================================================================
# ⏱️ SESSION MANAGEMENT
# ==============================================================================

# PURPOSE: Tell the system you are starting work.
# WHEN: Run this EVERY TIME you begin a new task.
session-start: ## Begin a tracked work session (optional msg="...")
	@python3 scripts/manage_session.py start -- "${{{{msg}}}}"

# PURPOSE: finalize your work, index it, and sync to GitHub (Lite tier - no quality gates).
# WHEN: Run this EVERY TIME you finish a task or want to go home.
session-end: ## Close session: indices docs, commits & pushes (optional msg="...")
	@echo "$(BLUE)📤 Finalizing workspace...$(NC)"
	@python3 scripts/index_docs.py
	@python3 scripts/run_audit.py
	@make clean
	@if [ -d .git ]; then \\
		git add .; \\
		if [ -n "$$(git status --porcelain)" ]; then \\
			git commit -m "session end: ${{{{msg}}}}"; \\
		else \\
			echo "$(GREEN)✨ Workspace clean$(NC)"; \\
		fi; \\
		git push 2>/dev/null || echo "$(YELLOW)⚠️  Push failed$(NC)"; \\
	else \\
		echo "$(YELLOW)⚠️  Not a git repository$(NC)"; \\
	fi
	@python3 scripts/manage_session.py end -- "${{{{msg}}}}"
"""
    elif tier == "2":
        return f"""# {provider_title} Standard Workspace
SHELL := /bin/bash
.PHONY: run test test-watch coverage typecheck install context clean audit session-start session-end init list-skills help snapshot restore doctor status health format update docs lint ci-local deps-check security-scan session-force-end-all onboard backup sync search list-todos index skill-add skill-remove

# ==============================================================================
# 🎨 BRANDING & COLORS
# ==============================================================================
BLUE   := \\033[1;34m
GREEN  := \\033[1;32m
YELLOW := \\033[1;33m
RED    := \\033[1;31m
NC     := \\033[0m # No Color

# ==============================================================================
# 🚀 APPLICATION ENTRY POINT
# ==============================================================================

# PURPOSE: Execute the main logic of your workspace.
# WHEN: Use this to run your actual software.
run: ## Execute the primary application (src/{{project_name}}/main.py)
	@echo "$(BLUE)🚀 Launching application...$(NC)"
	@python3 -m src.{project_name}.main

# ==============================================================================
# 🧪 TESTING & QUALITY
# ==============================================================================

# PURPOSE: Validate that your code is bug-free.
# WHEN: Run before finishing every work session.
test: ## Run the full pytest suite in tests/
	@echo "$(BLUE)🧪 Running tests...$(NC)"
	@PYTHONPATH=. pytest tests/

# PURPOSE: Continuous test feedback during coding.
test-watch: ## Run tests and re-run on file changes (requires pytest-watch)
	@pytest-watch tests/ || echo \\"$(YELLOW)💡 Install pytest-watch: pip install pytest-watch$(NC)\\"

# PURPOSE: Check test coverage of your codebase.
coverage: ## Generate a test coverage report (html + terminal)
	@pytest tests/ --cov=src --cov-report=term-missing --cov-report=html || echo \\"$(YELLOW)💡 Install pytest-cov: pip install pytest-cov$(NC)\\"

# PURPOSE: Lint your code for style and errors.
lint: ## Check for code style and logical errors using ruff
	@echo "$(BLUE)🧹 Linting codebase...$(NC)"
	@ruff check . --fix

# PURPOSE: Automatically format your code.
format: ## Automatically format code (imports, spacing) with ruff
	@echo "$(BLUE)✨ Formatting code...$(NC)"
	@ruff format .

# PURPOSE: Run static type checks to prevent bugs.
typecheck: ## Run static type analysis (mypy or pyright) to catch bugs
	@echo "$(BLUE)🔍 Type checking...$(NC)"
	@command -v mypy >/dev/null 2>&1 && mypy src/ || (command -v pyright >/dev/null 2>&1 && pyright src/ || echo \\"$(YELLOW)💡 Install type checker: pip install mypy or pip install pyright$(NC)\\")

# ==============================================================================
# 📚 DOCUMENTATION & LLM CONTEXT
# ==============================================================================

# PURPOSE: Export your project's "identity" for a new AI assistant.
# WHEN: Run this at the start of every NEW LLM conversation.
context: ## Export core Rules/Roadmap (GEMINI.md, etc.) for a new LLM conversation
	@echo "$(BLUE)📋 Exporting AI context...$(NC)"
	@for file in $$(cat .gemini/manifests/core); do \\
		if [ -f "$$file" ]; then \\
			echo "$(GREEN)--- FILE: $$file ---$(NC)"; \\
			cat "$$file"; \\
			echo ""; \\
		fi; \\
	done

# PURPOSE: Build viewable documentation site.
docs: ## Build static documentation (HTML) if configured with mkdocs
	@echo "$(BLUE)📚 Generating documentation...$(NC)"
	@command -v mkdocs >/dev/null 2>&1 && mkdocs build || echo \\"$(YELLOW)⚠️  mkdocs not found. Install with: pip install mkdocs$(NC)\\"

# PURPOSE: Refresh the master index of all documents.
index: ## Regenerate the master Table of Contents in README.md
	@echo "$(BLUE)🗂️  Indexing documentation...$(NC)"
	@python3 scripts/docs/index_docs.py

# ==============================================================================
# 📦 ENVIRONMENT MANAGEMENT
# ==============================================================================

# PURPOSE: Install project and dependencies.
install: ## Install the project in editable mode with dependencies
	@echo "$(BLUE)📦 Installing project dependencies...$(NC)"
	@pip3 install -e .

# PURPOSE: Update software libraries to latest versions.
update: ## Update all dependencies to their latest compatible versions
	@echo "$(BLUE)🔄 Updating dependencies...$(NC)"
	@pip3 install --upgrade -e \".[dev]\"

# PURPOSE: Diagnose environment health.
doctor: ## Run environmental diagnostics (Python version, dependencies)
	@echo "$(BLUE)🔍 Checking environment...$(NC)"
	@python3 --version
	@echo "$(BLUE)📦 Checking dependencies...$(NC)"
	@command -v ruff >/dev/null 2>&1 && echo "$(GREEN)✅ ruff available$(NC)" || echo "$(YELLOW)⚠️  ruff not found (run: pip install ruff)$(NC)"
	@echo "$(BLUE)📁 Checking structure...$(NC)"
	@python3 scripts/workspace/run_audit.py

# ==============================================================================
# ⏱️ SESSION MANAGEMENT
# ==============================================================================

# PURPOSE: Tell the system you are starting work.
# WHEN: Run this EVERY TIME you begin a new task.
session-start: ## Begin a tracked work session (optional msg="...")
	@python3 scripts/workspace/manage_session.py start -- "${{msg}}"

# PURPOSE: finalize your work, runs quality checks, and sync to GitHub (Standard tier).
# WHEN: Run this EVERY TIME you finish a task or want to go home.
session-end: ## Close session: runs lint/tests, commits & pushes (optional msg="...")
	@echo "$(BLUE)📤 Finalizing workspace...$(NC)"
	@echo "$(BLUE)🧹 Linting...$(NC)"
	@$(MAKE) lint || ( echo "$(RED)❌ Linting failed$(NC)" && exit 1 )
	@echo "$(BLUE)🧪 Testing...$(NC)"
	@$(MAKE) test || ( echo "$(RED)❌ Tests failed$(NC)" && exit 1 )
	@python3 scripts/docs/index_docs.py
	@python3 scripts/workspace/run_audit.py
	@$(MAKE) clean
	@if [ -d .git ]; then \\
		git add .; \\
		if [ -n "$$(git status --porcelain)" ]; then \\
			git commit -m "session end: ${{msg}}"; \\
		else \\
			echo "$(GREEN)✨ Workspace clean$(NC)"; \\
		fi; \\
		git push 2>/dev/null || echo "$(YELLOW)⚠️  Push failed$(NC)"; \\
	else \\
			echo "$(YELLOW)⚠️  Not a git repository$(NC)"; \\
	fi
	@python3 scripts/workspace/manage_session.py end -- "${{msg}}"
	@echo "$(GREEN)✅ Quality checks passed!$(NC)"

# ==============================================================================
# 🛡️ ARCHIVE & BACKUP
# ==============================================================================

# PURPOSE: Create a workspace "Save Point".
# WHEN: Use before major or risky changes.
snapshot: ## Create an immutable local backup of your workspace state
	@if [ -z "$(name)" ]; then echo "$(RED)❌ Error: name=\\"...\\" is required for snapshot$(NC)" && exit 1; fi
	@python3 scripts/workspace/create_snapshot.py create "${{name}}"

# PURPOSE: Revert to a previous "Save Point".
restore: ## Revert workspace to a previous snapshot (use name="...")
	@if [ -z "$(name)" ]; then echo "$(RED)❌ Error: name=\\"...\\" is required for restore$(NC)" && exit 1; fi
	@python3 scripts/workspace/create_snapshot.py restore "${{name}}" $(if $(yes),--yes,)

# PURPOSE: Standard backup.
backup: snapshot ## Alias for snapshot
"""
    else:  # tier == "3"
        return """# Gemini Enterprise Workspace
SHELL := /bin/bash
.PHONY: scan test test-watch coverage typecheck audit eval context context-frontend context-backend install clean session-start session-end init list-skills shift-report snapshot restore doctor status health help lint format update lock docs ci-local deps-check security-scan session-force-end-all onboard backup sync search list-todos index skill-add skill-remove

# ==============================================================================
# 🎨 BRANDING & COLORS
# ==============================================================================
BLUE   := \\033[1;34m
GREEN  := \\033[1;32m
YELLOW := \\033[1;33m
RED    := \\033[1;31m
NC     := \\033[0m # No Color

# ==============================================================================
# 🚀 APPLICATION ENTRY POINT
# ==============================================================================

# PURPOSE: Run the Enterprise CLI scanner.
scan: ## Run the internal CLI scanner (src/cli.py)
	@echo "$(BLUE)🚀 Scanning application...$(NC)"
	@uv run python3 src/cli.py scan || python3 src/cli.py scan

# ==============================================================================
# 🧪 TESTING & QUALITY
# ==============================================================================

# PURPOSE: Run comprehensive Enterprise test suite.
test: ## Run the unit test suite in tests/unit/
	@echo "$(BLUE)🧪 Running Enterprise unit tests...$(NC)"
	@uv run pytest tests/unit/ || PYTHONPATH=. pytest tests/unit/

# PURPOSE: Continuous test feedback.
test-watch: ## Run unit tests and re-run on file changes
	@uv run pytest-watch tests/unit/ || pytest-watch tests/unit/ || echo \\"$(YELLOW)💡 Install pytest-watch: pip install pytest-watch$(NC)\\"

# PURPOSE: In-depth coverage reporting.
coverage: ## Generate detailed unit test coverage report
	@uv run pytest tests/unit/ --cov=src --cov-report=term-missing --cov-report=html || pytest tests/unit/ --cov=src --cov-report=term-missing --cov-report=html || echo \\"$(YELLOW)💡 Install pytest-cov: pip install pytest-cov$(NC)\\"

# PURPOSE: Run advanced performance and capability evaluations.
eval: ## Run agent capability and evaluation tests in tests/evals/
	@echo "$(BLUE)🧠 Running agent evaluations...$(NC)"
	@uv run pytest tests/evals || pytest tests/evals

# PURPOSE: Static type verification.
typecheck: ## Run static type analysis (mypy or pyright) to catch bugs
	@echo "$(BLUE)🔍 Type checking...$(NC)"
	@uv run mypy src/ || (command -v mypy >/dev/null 2>&1 && mypy src/ || (command -v pyright >/dev/null 2>&1 && pyright src/ || echo \\"$(YELLOW)💡 Install type checker: pip install mypy or pip install pyright$(NC)\\"))

# ==============================================================================
# 📚 DOCUMENTATION & LLM CONTEXT
# ==============================================================================

# PURPOSE: Full project context export for new AI agents.
# WHEN: Run this at the start of every NEW LLM conversation.
context: ## Export core Rules/Roadmap (GEMINI.md, etc.) for a new LLM conversation
	@echo "$(BLUE)📋 Exporting AI context...$(NC)"
	@for file in $$(cat .gemini/manifests/core); do \\
		if [ -f "$$file" ]; then \\
			echo "$(GREEN)--- FILE: $$file ---$(NC)"; \\
			cat "$$file"; \\
			echo ""; \\
		fi; \\
	done

# PURPOSE: Frontend-specific context export.
context-frontend: ## Output frontend-specific manifests
	@cat .gemini/manifests/frontend

# PURPOSE: Backend-specific context export.
context-backend: ## Output backend-specific manifests
	@cat .gemini/manifests/backend

# PURPOSE: Build Enterprise documentation site.
docs: ## Generate static documentation site
	@echo "$(BLUE)📚 Generating documentation...$(NC)"
	@command -v mkdocs >/dev/null 2>&1 && mkdocs build || echo \\"$(YELLOW)⚠️  mkdocs not found. Install with: pip install mkdocs$(NC)\\"

# PURPOSE: Refresh the master index of all documents.
index: ## Regenerate the master Table of Contents in WORKSPACE_INDEX.md
	@echo "$(BLUE)🗂️  Indexing documentation...$(NC)"
	@python3 scripts/shared/index_docs.py

# ==============================================================================
# 📦 ENVIRONMENT MANAGEMENT
# ==============================================================================

# PURPOSE: High-performance dependency synchronization.
install: ## Install dependencies using uv sync (or pip fallback)
	@echo "$(BLUE)📦 Installing high-performance dependencies...$(NC)"
	@uv sync || pip3 install -e .

# PURPOSE: Full environment update.
update: ## Update lockfile and all dependencies
	@echo "$(BLUE)🔄 Updating high-performance dependencies...$(NC)"
	@uv lock --upgrade || pip3 install --upgrade -e \".[dev]\"

# PURPOSE: Freeze dependencies for production.
lock: ## Generate/update the production lock file
	@uv lock || echo "$(YELLOW)⚠️  uv not found. Use: pip freeze > requirements.lock$(NC)"

# PURPOSE: Comprehensive environment diagnostic.
doctor: ## Run environmental diagnostics (Python version, dependencies)
	@echo "$(BLUE)🔍 Checking environment...$(NC)"
	@python --version
	@echo "$(BLUE)📦 Checking dependencies...$(NC)"
	@command -v uv >/dev/null 2>&1 && echo "$(GREEN)✅ uv available$(NC)" || echo "$(YELLOW)⚠️  uv not found (using pip fallback)$(NC)"
	@command -v ruff >/dev/null 2>&1 && echo "$(GREEN)✅ ruff available$(NC)" || echo "$(YELLOW)⚠️  ruff not found (run: pip install ruff)$(NC)"
	@echo "$(BLUE)📁 Checking structure...$(NC)"
	@python3 scripts/shared/run_audit.py

# ==============================================================================
# ⏱️ SESSION MANAGEMENT
# ==============================================================================

# PURPOSE: Tell the system you are starting work.
# WHEN: Run this EVERY TIME you begin a new task.
session-start: ## Begin a tracked work session (optional msg="...")
	@python3 scripts/shared/manage_session.py start -- "${msg}"

# PURPOSE: finalize your work, runs all quality checks, and sync to GitHub (Enterprise tier).
# WHEN: Run this EVERY TIME you finish a task or want to go home.
session-end: ## Close session: runs lint/tests/evals, commits & pushes (optional msg="...")
	@echo "$(BLUE)📤 Finalizing workspace...$(NC)"
	@echo "$(BLUE)🧹 Linting...$(NC)"
	@ruff check . --fix || ( echo "$(RED)❌ Linting failed$(NC)" && exit 1 )
	@echo "$(BLUE)🧪 Testing...$(NC)"
	@$(MAKE) test || ( echo "$(RED)❌ Tests failed$(NC)" && exit 1 )
	@echo "$(BLUE)🧠 Evaluating...$(NC)"
	@$(MAKE) eval || ( echo "$(RED)❌ Evals failed$(NC)" && exit 1 )
	@python3 scripts/shared/index_docs.py
	@python3 scripts/shared/run_audit.py
	@$(MAKE) clean
	@if [ -d .git ]; then \\
		git add .; \\
		if [ -n "$$(git status --porcelain)" ]; then \\
			git commit -m "session end: ${msg}"; \\
		else \\
			echo "$(GREEN)✨ Workspace clean$(NC)"; \\
		fi; \\
		git push 2>/dev/null || echo "$(YELLOW)⚠️  Push failed$(NC)"; \\
	else \\
			echo "$(YELLOW)⚠️  Not a git repository$(NC)"; \\
	fi
	@python3 scripts/shared/manage_session.py end -- "${msg}"
	@echo "$(GREEN)✅ All quality checks passed!$(NC)"

# ==============================================================================
# 🛡️ ARCHIVE & BACKUP
# ==============================================================================

# PURPOSE: Generate handoff report for multi-agent workflows.
shift-report: ## Generate handoff report
	@python3 scripts/shift_report.py

# PURPOSE: Enterprise "Save Point".
snapshot: ## Create an immutable local backup of your workspace state
	@if [ -z "$(name)" ]; then echo "$(RED)❌ Error: name=\\"...\\" is required for snapshot$(NC)" && exit 1; fi
	@python3 scripts/shared/create_snapshot.py create "${name}"

# PURPOSE: Revert to "Save Point".
restore: ## Revert workspace to a previous snapshot (use name="...")
	@if [ -z "$(name)" ]; then echo "$(RED)❌ Error: name=\\"...\\" is required for restore$(NC)" && exit 1; fi
	@python3 scripts/shared/create_snapshot.py restore "${name}" $(if $(yes),--yes,)

# PURPOSE: Standard backup.
backup: snapshot ## Alias for snapshot
"""


def _get_makefile_common_targets(tier: str = "1", provider: str = "gemini") -> str:
    """Generate common Makefile targets shared across all tiers."""
    # Build tier-specific script paths
    sp_audit = _script_path(tier, "run_audit")
    sp_session = _script_path(tier, "manage_session")
    sp_status = _script_path(tier, "check_status")
    sp_list_skills = _script_path(tier, "list_skills")
    sp_manage_skills = _script_path(tier, "manage_skills")
    sp_explore_skills = _script_path(tier, "explore_skills")

    # Use string concatenation to avoid f-string backslash issues
    return (
        """
# ==============================================================================
# ⚙️ SYSTEM CONFIGURATION
# ==============================================================================
.DEFAULT_GOAL := help
SHELL         := /bin/bash
.SHELLFLAGS   := -eu -o pipefail -c
MAKEFLAGS     += --warn-undefined-variables
MAKEFLAGS     += --no-builtin-rules

# ==============================================================================
# 🔧 TOOLS & INTERPRETERS
# ==============================================================================
PYTHON := python3
RUFF   := ruff
PYTEST := pytest

# ==============================================================================
# 🏥 WORKSPACE HEALTH & LIFECYCLE
# ==============================================================================

# PURPOSE: Emergency stop for stale tasks.
# WHEN: Use this if you forgot to run 'session-end' and things are hung.
session-force-end-all: ## Emergency: force-close any stale or hung sessions
	@python3 """
        + sp_session
        + """ force-end-all

# PURPOSE: The "Start My Day" command.
# WHEN: Run this as your very first action in a new work day.
init: ## Quickstart: starts a session and exports LLM context manifest
	@python3 scripts/session.py start -- "${{msg}}"
	@echo "\\n$(BLUE)📋 Exporting Context for LLM...$(NC)"
	@make context

# PURPOSE: The "New User" onboarding flow.
# WHEN: Run this once when you first start using this workspace.
onboard: ## First-run experience: runs status, audit, and diagnostic check
	@echo "\\n🚀 Welcome to your Gemini Workspace!"
	@echo "─────────────────────────────────────"
	@python3 """
        + sp_status
        + """
	@echo "📋 Running health check..."
	@make doctor
	@echo "\\n📚 Quick Start:"
	@echo "   1. Run 'make context' and paste output into your LLM"
	@echo "   2. Say: 'I am ready to work on this project'"
	@echo "   3. Run 'make list-skills' to see available capabilities"
	@echo "   4. Check docs/GETTING_STARTED.md for full guide"
	@echo ""

# PURPOSE: Checks that your folders follow the required AI standard.
# WHEN: I run this automatically for you, but you can run it to check health.
audit: ## Validate that workspace structure complies with the standard
	@python3 """
        + sp_audit
        + """

# PURPOSE: See what special "AI Capabilities" I have in this folder.
# WHEN: Use this to discover new workflows or skills I can perform.
list-skills: ## List the cognitive 'Skills' and 'Workflows' available to agents
	@echo "$(BLUE)🧠 Querying AI capabilities...$(NC)"
	@python3 """
        + sp_list_skills
        + """

# PURPOSE: Install a new AI capability from a trusted source.
# WHEN: Use this when you need a specialized skill for a specific task.
skill-add: ## Fetch and install a skill (use source="owner/repo/path")
	@if [ -z "$(source)" ]; then echo "$(RED)❌ Error: source=\\"...\\" is required$(NC)" && exit 1; fi
	@$(PYTHON) """
        + sp_manage_skills
        + """ fetch "$(source)"

# PURPOSE: Remove an AI capability you no longer need.
skill-remove: ## Uninstall a local skill (use name="...")
	@if [ -z "$(name)" ]; then echo "$(RED)❌ Error: name=\\"...\\" is required$(NC)" && exit 1; fi
	@$(PYTHON) """
        + sp_manage_skills
        + """ remove "$(name)"

# PURPOSE: View your current "Health Score" and workspace status.
# WHEN: Use this to see how much progress you've made today.
status: ## Show a high-level health dashboard and git/session status
	@python3 """
        + sp_status
        + """

# PURPOSE: Standard health check (alias for doctor).
health: doctor ## Alias for doctor

# PURPOSE: Show the command manual.
# WHEN: Use this whenever you are unsure what to do next.
help: ## Show categorized help manual
	@echo "\\n$(BLUE)🛠️  Gemini Workspace Command Manual$(NC)"
	@awk '/^# ===+/ { \\
		category = $$0; \\
		gsub(/^# =+/, "", category); \\
		gsub(/=+/, "", category); \\
		if (length(category) > 0) printf "\\n$(YELLOW) %s$(NC)\\n", category; \\
	} \\
	/^[a-zA-Z_-]+:.*?## / { \\
		split($$0, a, ":"); \\
		cmd = a[1]; \\
		split($$0, b, "## "); \\
		msg = b[2]; \\
		printf "  $(GREEN)%-18s$(NC) %s\\n", cmd, msg; \\
	}' $(MAKEFILE_LIST)
	@echo "\\n$(BLUE)Usage Examples:$(NC)"
	@echo "  make session-start [msg='Writing research notes']"
	@echo "  make session-end [msg='Completed Phase 1']"
	@echo "  make snapshot name='pre-refactor'"

# PURPOSE: Sync your local environment with remote changes.
sync: ## Pull latest changes and update dependencies
	@echo "$(BLUE)🔄 Syncing workspace with remote...$(NC)"
	@git pull --rebase 2>/dev/null || echo "$(YELLOW)⚠️  No remote or pull failed$(NC)"
	@$(PYTHON) -m pip install -e .
	@echo "$(GREEN)✅ Sync complete$(NC)"

# PURPOSE: Fast-search the codebase for a query.
search: ## Search codebase for q="term"
	@if [ -z "$(q)" ]; then echo "$(RED)❌ Error: q=\\"...\\" is required$(NC)" && exit 1; fi
	@grep -rnE "$(q)" src/ tests/ docs/ || echo "$(YELLOW)No matches found for '$(q)'$(NC)"

# PURPOSE: Discover new skills from external repositories.
discover: ## Discover external skills (q="topic")
	@python3 """
        + sp_explore_skills
        + """ search "$(q)"

# PURPOSE: List all TODOs and FIXMEs in the codebase.
list-todos: ## List all 'TODO' and 'FIXME' tags in the code
	@echo "$(BLUE)📝 Current Codebase Tasks:$(NC)"
	@grep -rnE "TODO|FIXME" src/ | awk -F: '{printf "  $(YELLOW)%-25s$(NC) %s\\n", $$1":"$$2, $$3}' || echo "$(GREEN)✨ No pending TODOs!$(NC)"

# ==============================================================================
# 🧹 HYGIENE & QUALITY
# ==============================================================================

# PURPOSE: Delete temporary files that clog up your workspace.
# WHEN: Run this if your folders feel "heavy" or if you want to clear caches.
clean: ## Clear out temporary files, caches, and scratchpad drafts
	@echo "$(BLUE)🧹 Cleaning workspace caches...$(NC)"
	@rm -rf scratchpad/* logs/*.log __pycache__ .pytest_cache

# PURPOSE: Run CI tests locally (mirrors GitHub Actions).
# WHEN: Run this before pushing to ensuring your code passes all checks.
ci-local: ## Run CI tests locally (mirrors GitHub Actions)
	@echo "$(BLUE)🔄 Running local CI checks...$(NC)"
	@echo "📋 Step 1: Audit"
	@python3 """
        + sp_audit
        + """
	@echo "📋 Step 2: Lint"
	@ruff check . || true
	@echo "📋 Step 3: Test"
	@pytest tests/ -q || echo "$(YELLOW)⚠️  No tests found or pytest not installed$(NC)"
	@echo "$(GREEN)✅ Local CI complete$(NC)"

# ==============================================================================
# 🛡️ SECURITY & DEPENDENCIES
# ==============================================================================

# PURPOSE: Check for outdated or vulnerable dependencies.
# WHEN: Run this periodically to keep your environment secure.
deps-check: ## Check for outdated/vulnerable dependencies
	@echo "$(BLUE)🔍 Checking dependencies...$(NC)"
	@pip3 list --outdated 2>/dev/null | head -20 || echo "$(YELLOW)⚠️  pip not available$(NC)"
	@echo ""
	@command -v pip-audit >/dev/null 2>&1 && pip-audit || echo "$(YELLOW)💡 Install pip-audit for vulnerability scanning: pip install pip-audit$(NC)"

# PURPOSE: Scan for secrets and vulnerabilities in the codebase.
# WHEN: Run this before publishing or after adding new dependencies.
security-scan: ## Scan for secrets and vulnerabilities
	@echo "$(BLUE)🔐 Running security scan...$(NC)"
	@command -v gitleaks >/dev/null 2>&1 && gitleaks detect --source . --no-git || echo "$(YELLOW)💡 Install gitleaks for secret scanning: brew install gitleaks$(NC)"
	@command -v pip-audit >/dev/null 2>&1 && pip-audit || true
	@echo "$(GREEN)✅ Security scan complete$(NC)"

# PURPOSE: Create a local "Save Point" of the entire workspace.
backup: snapshot ## Alias for snapshot
"""
    )


# ==============================================================================
# Module: core/templates/__init__.py
# ==============================================================================

"""
Template Generation Package

Exports all template generator functions for workspace creation.
Organized into logical modules:
- gemini_md: GEMINI.md constitution
- github_workflow: CI/CD workflows
- scripts_core: audit, session, docs, status
- scripts_snapshot: snapshot/restore functionality
- scripts_skills: skill management tools
- schemas: JSON schemas for validation
- configs: pre-commit and other configs
"""


__all__ = [
    # GEMINI.md
    "get_gemini_md",
    # GitHub
    "get_github_workflow",
    # Core scripts
    "get_run_audit_script",
    "get_manage_session_script",
    "get_index_docs_script",
    "get_check_status_script",
    # Snapshot
    "get_create_snapshot_script",
    # Skills
    "get_list_skills_script",
    "get_skill_discovery_workflow",
    "get_skillsmp_client_script",
    "get_skillsmp_search_script",
    # Schemas
    "get_workspace_schema",
    "get_settings_schema",
    "get_bootstrap_config_schema",
    # Configs
    "get_precommit_config",
]

# ==============================================================================
# Module: core/templates/gemini_md.py
# ==============================================================================

"""
GEMINI.md Constitution Template Generator

Generates tier-specific GEMINI.md constitution files.
"""

# Version constant (imported from config in final build)
VERSION = "1.0.1"


def get_gemini_md(tier: str, project_name: str) -> str:
    """Generate GEMINI.md constitution."""
    base = """# Gemini Native Workspace ({edition} Edition)
**Philosophy:** "{philosophy}"
**Role:** {role}
**Version:** {version}

## 1. The Cognitive Laws
1.  **Skill Check:** Before asking "How?", check `.agent/skills/`.
2.  **Workflow Adherence:** Follow `.agent/workflows/` for complex tasks.
3.  **Pattern Matching:** Code must mimic `.agent/patterns/`.
4.  **Evolution:** Use the "Gardener Protocol" to modify rules.

## 2. The Laws of Physics
1.  **Hygiene:** Write temp files to `scratchpad/`.
2.  **Safety:** **NEVER** print secrets to stdout.
3.  **Continuity:** Update `docs/roadmap.md` every session.
4.  **Interface:** Use `Makefile` targets. Do not run raw shell commands.
5.  **Sessions:** Start with `make session-start`, end with `make session-end`.
"""
    if tier == "1":
        return (
            base.format(
                edition="Lite",
                philosophy="Reliable Automation",
                role="Automation Specialist",
                version=VERSION,
            )
            + "\n## 3. Architecture\n* **Input:** `data/inputs/`\n* **Logic:** `src/main.py`\n* **Output:** `logs/run.log`"
        )
    elif tier == "2":
        return (
            base.format(
                edition="Standard",
                philosophy="The Modular Monolith",
                role="Lead Software Engineer",
                version=VERSION,
            )
            + f"\n## 3. Architecture\n* **Modules:** `src/{project_name}/`\n* **Tests:** `tests/unit/`\n* **Context:** Shared Global Context."
        )
    else:
        return (
            base.format(
                edition="Enterprise",
                philosophy="Headless Organization",
                role="CTO / Architect",
                version=VERSION,
            )
            + f"\n## 3. Architecture\n* **Domains:** `src/{project_name}/domains/` (Strict Isolation)\n* **Contracts:** `outputs/contracts/`\n* **Evals:** `tests/evals/`\n\n## 4. Multi-Agent Protocol\n* Sub-Agents do NOT inherit Root Context.\n* Use `make shift-report` for handoffs.\n* Run `make snapshot` before major changes."
        )


# ==============================================================================
# Module: core/templates/github_workflow.py
# ==============================================================================

"""
GitHub Workflow Template Generator

Generates tier-specific GitHub Actions CI workflows.
"""


def get_github_workflow(tier: str, python_version: str = DEFAULT_PYTHON_VERSION) -> str:
    """Generate GitHub Actions CI workflow with caching and optional matrix testing.

    Args:
        tier: Workspace tier (1, 2, or 3)
        python_version: Primary Python version for CI (also used in matrix)

    Returns:
        YAML content for .github/workflows/ci.yml
    """
    base = f"""name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '{python_version}'
      - name: Audit workspace
        run: python scripts/audit.py
"""
    if tier == "1":
        return (
            base
            + f"""
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '{python_version}'
          cache: 'pip'
      - run: pip install -q -r requirements.txt
      - run: python src/main.py
"""
        )
    elif tier == "2":
        return (
            base
            + f"""
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['{python_version}']
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{{{ matrix.python-version }}}}
          cache: 'pip'
      - name: Install dependencies
        run: pip install -q -e ".[dev]"
      - name: Run tests
        run: pytest tests/ -q
      - name: Run tests with coverage (optional)
        run: |
          pip install -q pytest-cov 2>/dev/null || true
          pytest tests/ --cov=src --cov-report=term-missing --cov-fail-under=0 2>/dev/null || true
        continue-on-error: true
"""
        )
    else:
        return (
            base
            + f"""
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['{python_version}']
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{{{ matrix.python-version }}}}
          cache: 'pip'
      - name: Install uv
        run: pip install -q uv
      - name: Install dependencies
        run: uv sync --quiet
      - name: Run unit tests
        run: uv run pytest tests/unit/ -q

  eval:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '{python_version}'
          cache: 'pip'
      - name: Install uv
        run: pip install -q uv
      - name: Install dependencies
        run: uv sync --quiet
      - name: Run agent evaluations
        run: uv run pytest tests/evals/ -q
"""
        )


# ==============================================================================
# Module: core/templates/scripts_core.py
# ==============================================================================

"""Core Script Generators

Generates workspace audit, session management, document indexing, and status scripts.
"""


def get_run_audit_script() -> str:
    """Generate workspace audit script (run_audit.py)."""
    return '''#!/usr/bin/env python3
"""Workspace structure auditor - validates against Gemini Standard."""
import os
import sys
from pathlib import Path

def main():
    print("🔍 Auditing workspace structure...")
    errors = 0

    # Check core files
    required = ["GEMINI.md", "Makefile", ".gemini/workspace.json"]
    for f in required:
        if not Path(f).exists():
            print(f"❌ Missing core file: {f}")
            errors += 1

    # Check directories
    required_dirs = ["logs", "docs"]
    for d in required_dirs:
        if not Path(d).exists():
            print(f"❌ Missing directory: {d}/")
            errors += 1

    if errors == 0:
        print("✅ Audit passed.")
        sys.exit(0)
    else:
        print(f"❌ Audit failed with {errors} errors.")
        sys.exit(1)

if __name__ == "__main__":
    main()
'''


def get_manage_session_script() -> str:
    """Generate session management script (manage_session.py)."""
    return '''#!/usr/bin/env python3
"""Session management for Gemini workspaces."""
import argparse
import json
import os
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path

def load_sessions():
    log_path = Path("logs/sessions/history.json")
    if log_path.exists():
        try:
            with open(log_path) as f:
                return json.load(f)
        except json.JSONDecodeError:
            pass
    return []

def save_session(entry):
    log_dir = Path("logs/sessions")
    log_dir.mkdir(parents=True, exist_ok=True)

    history = load_sessions()
    history.append(entry)

    with open(log_dir / "history.json", "w") as f:
        json.dump(history, f, indent=2)

    # Also append to human readable log
    with open(log_dir / "session.log", "a") as f:
        f.write(f"[{entry['timestamp']}] {entry['action'].upper()}: {entry['message']}\\n")

def get_git_status():
    try:
        # Get brief stats
        res = subprocess.run(
            ["git", "diff", "--shortstat"],
            capture_output=True, text=True
        )
        if res.stdout.strip():
            return f"Auto-generated: {res.stdout.strip()}"

        # If no diff, maybe staged changes?
        res = subprocess.run(
            ["git", "diff", "--cached", "--shortstat"],
            capture_output=True, text=True
        )
        if res.stdout.strip():
            return f"Auto-generated (staged): {res.stdout.strip()}"

        return "Session ended (no changes detected)"
    except FileNotFoundError:
        return "Session ended (git not available)"

def start_session(msg):
    message = msg if msg else "Session started"
    entry = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "action": "start",
        "message": message
    }
    save_session(entry)
    print(f"🚀 Session started: {message}")

def end_session(msg):
    message = msg if msg else get_git_status()
    entry = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "action": "end",
        "message": message
    }
    save_session(entry)
    print(f"🎬 Session ended: {message}")

def main():
    parser = argparse.ArgumentParser(description="Session Manager")
    parser.add_argument("command", choices=["start", "end", "force-end-all"])
    parser.add_argument("msg", nargs="?", default="", help="Session message")

    args = parser.parse_args()

    if args.command == "start":
        start_session(args.msg)
    elif args.command == "end":
        end_session(args.msg)
    elif args.command == "force-end-all":
        print("Force ending all sessions...")

if __name__ == "__main__":
    main()
'''


def get_index_docs_script() -> str:
    """Generate document indexer script (index_docs.py)."""
    return r"""#!/usr/bin/env python3
import os
from pathlib import Path

def generate_index():
    docs_path = Path("docs")
    if not docs_path.exists():
        print("❌ docs/ directory not found.")
        return

    readme_content = [
        "# Workspace Documentation Index",
        "This file is automatically generated by `make index`. Do not edit manually.",
        "",
        "**Note**: For the main workspace overview and quick start guide, see [`README.md`](README.md).",
        "",
        "## 📁 Directories",
        ""
    ]

    # Define directory descriptions
    descriptions = {
        "standards": "Workspace rules and bootstrap protocols.",
        "projects": "Project-specific deep-dives and documentation.",
        "knowledge": "General research, notes, and shared learning.",
        "decisions": "Architecture Decision Records (ADRs).",
        "archive": "Historical context and deprecated documents.",
        "templates": "Standard document templates."
    }

    folders = sorted([d for d in docs_path.iterdir() if d.is_dir()])

    for folder in folders:
        desc = descriptions.get(folder.name, "")
        header = f"### [{folder.name}](docs/{folder.name}/)"
        if desc:
            header += f" - {desc}"
        readme_content.append(header)

        # List files in folder (top level only)
        files = sorted([f for f in folder.iterdir() if f.is_file() and not f.name.startswith(".")])
        if files:
            for file in files:
                readme_content.append(f"* [{file.name}](docs/{folder.name}/{file.name})")
        else:
            readme_content.append("* (No documents yet)")
        readme_content.append("")

    readme_content.append("## 📝 Latest Changes")
    readme_content.append("Check [docs/roadmap.md](docs/roadmap.md) for the latest project logs.")

    with open("WORKSPACE_INDEX.md", "w") as f:
        f.write("\\n".join(readme_content))

    print("✅ WORKSPACE_INDEX.md updated with latest index.")

if __name__ == "__main__":
    generate_index()
"""


def get_check_status_script() -> str:
    """Generate workspace status script with health dashboard (check_status.py)."""
    return '''#!/usr/bin/env python3
"""Show workspace status with health dashboard."""
import json
import os
import subprocess
from datetime import datetime, timezone
from pathlib import Path

# Respect NO_COLOR environment variable
USE_COLOR = not os.environ.get("NO_COLOR")

def _c(code: str) -> str:
    return code if USE_COLOR else ""

# Pre-define colors to avoid backslashes in f-strings (Py3.11 compatibility)
BLUE = _c('\\033[1;34m')
GREEN = _c('\\033[1;32m')
YELLOW = _c('\\033[1;33m')
RED = _c('\\033[1;31m')
CYAN = _c('\\033[1;36m')
RESET = _c('\\033[0m')

def get_git_info():
    """Get git branch and status info."""
    try:
        branch = subprocess.run(
            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
            capture_output=True, text=True, check=True
        ).stdout.strip()

        # Check for uncommitted changes
        status = subprocess.run(
            ["git", "status", "--porcelain"],
            capture_output=True, text=True, check=True
        ).stdout.strip()

        has_changes = len(status.split("\\n")) if status else 0
        return branch, has_changes
    except (subprocess.CalledProcessError, FileNotFoundError):
        return None, None

def get_dependency_age():
    """Check age of dependency files (timezone-aware)."""
    dep_files = ["pyproject.toml", "requirements.txt"]
    for f in dep_files:
        p = Path(f)
        if p.exists():
            mtime = datetime.fromtimestamp(p.stat().st_mtime, tz=timezone.utc).astimezone()
            days_ago = (datetime.now(timezone.utc).astimezone() - mtime).days
            return f, days_ago
    return None, None


def calculate_health_score():
    """Calculate workspace health score (0-100).

    Returns:
        Tuple of (score, issues_list)
    """
    score = 100
    issues = []

    # Check required files (25 points)
    required_files = ["GEMINI.md", "Makefile", ".gemini/workspace.json", "docs/roadmap.md"]
    for f in required_files:
        if not Path(f).exists():
            score -= 6
            issues.append(f"Missing {f}")

    # Check git status (20 points)
    branch, changes = get_git_info()
    if branch is None:
        score -= 10
        issues.append("No git repository")
    elif changes and changes > 10:
        score -= 10
        issues.append(f"{changes} uncommitted changes")
    elif changes and changes > 0:
        score -= 5

    # Check session tracking (15 points)
    sessions_dir = Path("logs/sessions")
    if not sessions_dir.exists():
        score -= 15
        issues.append("No sessions directory")

    # Check documentation freshness (20 points)
    roadmap = Path("docs/roadmap.md")
    if roadmap.exists():
        mtime = datetime.fromtimestamp(roadmap.stat().st_mtime, tz=timezone.utc).astimezone()
        days_ago = (datetime.now(timezone.utc).astimezone() - mtime).days
        if days_ago > 90:
            score -= 20
            issues.append(f"Roadmap stale ({days_ago} days)")
        elif days_ago > 30:
            score -= 10
            issues.append(f"Roadmap aging ({days_ago} days)")

    # Check dependency freshness (20 points)
    dep_file, dep_age = get_dependency_age()
    if dep_file and dep_age:
        if dep_age > 180:
            score -= 20
            issues.append(f"{dep_file} very old ({dep_age} days)")
        elif dep_age > 90:
            score -= 10
            issues.append(f"{dep_file} aging ({dep_age} days)")

    return max(0, score), issues


if __name__ == "__main__":
    print(f"{CYAN}📊 Workspace Status{RESET}\\n")

    # Workspace metadata
    workspace_file = Path(".gemini/workspace.json")
    if workspace_file.exists():
        with open(workspace_file) as f:
            workspace = json.load(f)
        print(f"Name: {workspace.get('name', 'Unknown')}")
        print(f"Tier: {workspace.get('tier')} ({['Lite', 'Standard', 'Enterprise'][int(workspace.get('tier', '1'))-1]})")
        print(f"Created: {workspace.get('created', 'Unknown')}")
    else:
        print("⚠️  No workspace.json found")

    # Git info
    print()
    branch, changes = get_git_info()
    if branch:
        print(f"Branch: {branch}")
        if changes:
            print(f"Uncommitted changes: {changes}")
        else:
            print("Working tree clean ✓")

    # Health score
    print()
    score, issues = calculate_health_score()
    if score >= 90:
        indicator = f"{GREEN}🟢"
        rating = "Excellent"
    elif score >= 70:
        indicator = f"{YELLOW}🟡"
        rating = "Good"
    elif score >= 50:
        indicator = f"{YELLOW}🟠"
        rating = "Fair"
    else:
        indicator = f"{RED}🔴"
        rating = "Needs Attention"

    print(f"Health: {indicator} {score}/100 ({rating}){RESET}")

    if issues:
        print("\\nIssues:")
        for issue in issues:
            print(f"  • {issue}")
'''


# ==============================================================================
# Module: core/templates/scripts_snapshot.py
# ==============================================================================

"""Snapshot Script Generator

Generates workspace snapshot creation and restore script.
"""


def get_create_snapshot_script() -> str:
    """Generate snapshot creation/restore script (create_snapshot.py)."""
    return '''#!/usr/bin/env python3
"""Create and restore workspace snapshots using git tags and directory backups."""
import argparse
import json
import shutil
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path

SNAPSHOT_DIR = Path(".snapshots")

def get_git_available():
    """Check if git is available and repo is initialized."""
    try:
        subprocess.run(
            ["git", "rev-parse", "--git-dir"],
            capture_output=True, check=True
        )
        return True
    except (subprocess.CalledProcessError, FileNotFoundError):
        return False

def list_snapshots():
    """List all available snapshots."""
    snapshots = []

    # Check git tags
    if get_git_available():
        try:
            result = subprocess.run(
                ["git", "tag", "-l", "snapshot-*"],
                capture_output=True, text=True, check=True
            )
            tags = [line.strip() for line in result.stdout.split("\\\\n") if line.strip()]
            snapshots.extend([(tag, "git") for tag in tags])
        except subprocess.CalledProcessError:
            pass

    # Check directory backups
    if SNAPSHOT_DIR.exists():
        for backup in SNAPSHOT_DIR.iterdir():
            if backup.is_dir():
                snapshots.append((backup.name, "backup"))

    return snapshots

def create_snapshot(name: str):
    """Create a workspace snapshot."""
    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
    snapshot_name = f"snapshot-{name}-{timestamp}" if name else f"snapshot-{timestamp}"

    print(f"📸 Creating snapshot: {snapshot_name}")

    # Create git tag if available
    if get_git_available():
        try:
            subprocess.run(
                ["git", "tag", "-a", snapshot_name, "-m", f"Snapshot: {name or 'unnamed'}"],
                check=True
            )
            print(f"✅ Git tag created: {snapshot_name}")
        except subprocess.CalledProcessError as e:
            print(f"⚠️  Git tag creation failed: {e}")

    # Create directory backup
    backup_path = SNAPSHOT_DIR / snapshot_name
    backup_path.mkdir(parents=True, exist_ok=True)

    # Backup critical files and directories
    critical_items = [
        ".gemini/workspace.json",
        ".gemini/settings.json",
        "GEMINI.md",
        "Makefile",
        "pyproject.toml",
        "src/",
        ".agent/"
    ]

    for item in critical_items:
        src = Path(item)
        if not src.exists():
            continue

        dest = backup_path / item
        try:
            if src.is_dir():
                shutil.copytree(src, dest, dirs_exist_ok=True)
            else:
                dest.parent.mkdir(parents=True, exist_ok=True)
                shutil.copy2(src, dest)
        except Exception as e:
            print(f"⚠️  Failed to backup {item}: {e}")

    # Save snapshot metadata
    metadata = {
        "name": name or "unnamed",
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "git_tag": snapshot_name if get_git_available() else None
    }

    with open(backup_path / "snapshot.json", "w") as f:
        json.dump(metadata, f, indent=2)

    print(f"✅ Backup created: {backup_path}")
    print(f"\\\\n💡 Restore with: make restore name=\\"{snapshot_name}\\"")

def restore_snapshot(name: str):
    """Restore workspace from a snapshot."""
    # Find snapshot
    snapshots = list_snapshots()
    matching = [s for s in snapshots if name in s[0]]

    if not matching:
        print(f"❌ Snapshot '{name}' not found")
        print("\\\\nAvailable snapshots:")
        for snap_name, snap_type in snapshots:
            print(f"  • {snap_name} ({snap_type})")
        sys.exit(1)

    snapshot_name = matching[0][0]
    print(f"🔄 Restoring snapshot: {snapshot_name}")

    # Confirm
    confirm = input("⚠️  This will overwrite current files. Continue? [y/N]: ").strip().lower()
    if confirm != "y":
        print("❌ Restore cancelled")
        sys.exit(0)

    # Restore from directory backup
    backup_path = SNAPSHOT_DIR / snapshot_name
    if not backup_path.exists():
        print(f"❌ Backup directory not found: {backup_path}")
        sys.exit(1)

    # Restore files
    restored_count = 0
    for item in backup_path.rglob("*"):
        if item.is_file() and item.name != "snapshot.json":
            rel_path = item.relative_to(backup_path)
            dest = Path(rel_path)

            try:
                dest.parent.mkdir(parents=True, exist_ok=True)
                shutil.copy2(item, dest)
                restored_count += 1
            except Exception as e:
                print(f"⚠️  Failed to restore {rel_path}: {e}")

    print(f"✅ Restored {restored_count} files from {snapshot_name}")

def main():
    parser = argparse.ArgumentParser(description="Workspace Snapshot Manager")
    subparsers = parser.add_subparsers(dest="command", required=True)

    # Create command
    create_parser = subparsers.add_parser("create", help="Create a snapshot")
    create_parser.add_argument("name", nargs="?", default="", help="Snapshot name")

    # Restore command
    restore_parser = subparsers.add_parser("restore", help="Restore from snapshot")
    restore_parser.add_argument("name", help="Snapshot name (or partial match)")

    # List command
    list_parser = subparsers.add_parser("list", help="List available snapshots")

    args = parser.parse_args()

    if args.command == "create":
        create_snapshot(args.name)
    elif args.command == "restore":
        restore_snapshot(args.name)
    elif args.command == "list":
        snapshots = list_snapshots()
        if snapshots:
            print("Available snapshots:")
            for snap_name, snap_type in snapshots:
                print(f"  • {snap_name} ({snap_type})")
        else:
            print("No snapshots found")

if __name__ == "__main__":
    main()
'''


# ==============================================================================
# Module: core/templates/scripts_skills.py
# ==============================================================================

"""Skill Management Script Generators

Generates SkillsMP API client, search tool, discovery workflow, and list scripts.
"""


def get_skillsmp_client_script() -> str:
    """Generate SkillsMP API client (skillsmp_client.py)."""
    lines = [
        "#!/usr/bin/env python3",
        '"""SkillsMP API Client for skill discovery."""',
        "import os",
        "import requests",
        "from typing import Dict, List, Optional",
        "",
        "",
        "class SkillsMPError(Exception):",
        '    """Custom exception for SkillsMP API errors."""',
        "    ",
        "    def __init__(self, code: str, message: str):",
        "        self.code = code",
        "        self.message = message",
        '        super().__init__(f"{code}: {message}")',
        "",
        "",
        "class SkillsMP:",
        '    """Client for SkillsMP API.',
        "    ",
        "    Provides access to 110,000+ community skills via keyword and AI semantic search.",
        '    """',
        "    ",
        '    BASE_URL = "https://skillsmp.com/api/v1"',
        "    ",
        "    def __init__(self, api_key: Optional[str] = None):",
        '        """Initialize with API key from env or parameter.',
        "        ",
        "        Args:",
        "            api_key: Optional API key. If not provided, reads from SKILLSMP_API_KEY env var.",
        "            ",
        "        Raises:",
        "            ValueError: If no API key is provided or found in environment.",
        '        """',
        '        self.api_key = api_key or os.getenv("SKILLSMP_API_KEY")',
        "        if not self.api_key:",
        "            raise ValueError(",
        '                "API key required. Set SKILLSMP_API_KEY environment variable "',
        '                "or pass api_key to constructor"',
        "            )",
        "        ",
        "        self.headers = {",
        '            "Authorization": f"Bearer {self.api_key}",',
        '            "Content-Type": "application/json"',
        "        }",
        "    ",
        "    def _handle_response(self, response: requests.Response) -> Dict:",
        '        """Handle API response and parse errors.',
        "        ",
        "        Args:",
        "            response: requests Response object",
        "            ",
        "        Returns:",
        "            Parsed JSON response",
        "            ",
        "        Raises:",
        "            SkillsMPError: If API returns an error",
        '        """',
        "        try:",
        "            response.raise_for_status()",
        "            return response.json()",
        "        except requests.HTTPError:",
        "            # Try to parse error response",
        "            try:",
        "                error_data = response.json()",
        "                if not error_data.get('success', True):",
        "                    error_info = error_data.get('error', {})",
        "                    raise SkillsMPError(",
        "                        code=error_info.get('code', 'UNKNOWN_ERROR'),",
        "                        message=error_info.get('message', 'An error occurred')",
        "                    )",
        "            except (ValueError, KeyError):",
        "                # If we can't parse the error, raise original HTTP error",
        "                response.raise_for_status()",
        "    ",
        "    def search(",
        "        self,",
        "        query: str,",
        "        page: int = 1,",
        "        limit: int = 20,",
        '        sort_by: str = "stars"',
        "    ) -> Dict:",
        '        """Search skills by keyword.',
        "        ",
        "        Args:",
        "            query: Search query string",
        "            page: Page number (default: 1)",
        "            limit: Results per page (default: 20, max: 100)",
        "            sort_by: Sort order - 'stars' or 'recent'",
        "            ",
        "        Returns:",
        "            Dict containing results and pagination info",
        "            ",
        "        Raises:",
        "            requests.HTTPError: If API request fails",
        '        """',
        '        url = f"{self.BASE_URL}/skills/search"',
        "        params = {",
        '            "q": query,',
        '            "page": page,',
        '            "limit": min(limit, 100),  # Cap at 100',
        '            "sortBy": sort_by',
        "        }",
        "        ",
        "        response = requests.get(url, headers=self.headers, params=params, timeout=10)",
        "        return self._handle_response(response)",
        "    ",
        "    def ai_search(self, query: str) -> Dict:",
        '        """Search skills using AI semantic search.',
        "        ",
        "        Uses Cloudflare AI to understand natural language queries and return",
        "        semantically relevant results with relevance scores.",
        "        ",
        "        Args:",
        "            query: Natural language search query",
        "            ",
        "        Returns:",
        "            Dict containing AI-ranked results with relevance scores",
        "            ",
        "        Raises:",
        "            requests.HTTPError: If API request fails",
        '        """',
        '        url = f"{self.BASE_URL}/skills/ai-search"',
        '        params = {"q": query}',
        "        ",
        "        response = requests.get(url, headers=self.headers, params=params, timeout=10)",
        "        return self._handle_response(response)",
        "    ",
        "    def download_skill(self, skill_url: str) -> str:",
        '        """Download SKILL.md content from GitHub.',
        "        ",
        "        Args:",
        "            skill_url: Raw GitHub URL to SKILL.md file",
        "            ",
        "        Returns:",
        "            Skill content as string",
        "            ",
        "        Raises:",
        "            requests.HTTPError: If download fails",
        '        """',
        "        response = requests.get(skill_url, timeout=10)",
        "        response.raise_for_status()",
        "        return response.text",
    ]
    return "\n".join(lines)


def get_skillsmp_search_script() -> str:
    """Generate SkillsMP search/install CLI tool (skillsmp_search.py)."""
    # This is a long script, so I'll create it as a raw string template
    return '''#!/usr/bin/env python3
"""Enhanced skill discovery using SkillsMP API.

This script searches the SkillsMP marketplace (110,000+ skills) and allows
interactive installation of discovered skills.

Usage:
    # Keyword search
    python scripts/shared/skillsmp_search.py "email templates"

    # AI semantic search
    python scripts/shared/skillsmp_search.py "help me write professional emails" --ai

    # Search and install
    python scripts/shared/skillsmp_search.py "pdf tools" --install 2
"""
import argparse
import os
import sys
from pathlib import Path
from dotenv import load_dotenv

# Load environment variables from .env
load_dotenv()

# Add project root to path
script_dir = Path(__file__).parent
project_root = script_dir.parent.parent
sys.path.insert(0, str(project_root))

from scripts.shared.skillsmp_client import SkillsMP, SkillsMPError


def main():
    """Main CLI entry point."""
    parser = argparse.ArgumentParser(
        description="Search SkillsMP marketplace for AI skills",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s "email templates"              # Keyword search
  %(prog)s "write resumes" --ai           # AI semantic search
  %(prog)s "pdf" --limit 5                # Limit results
  %(prog)s "data analysis" --install 3    # Install skill #3
        """
    )
    parser.add_argument("query", help="Search query")
    parser.add_argument("--ai", action="store_true", help="Use AI semantic search")
    parser.add_argument("--limit", type=int, default=10, help="Max results (default: 10, max: 100)")
    parser.add_argument("--sort", choices=["stars", "recent"], default="stars", help="Sort order")
    parser.add_argument("--install", type=int, metavar="N", help="Install skill by number (1-N)")

    args = parser.parse_args()

    try:
        client = SkillsMP()

        # Execute search
        if args.ai:
            print(f"\\n🤖 AI Semantic Search: '{args.query}'")
            print("=" * 80)
            results = client.ai_search(args.query)
            # Handle API response structure
            data = results.get('data', {})
            skills = data.get('skills', [])
        else:
            print(f"\\n🔍 Keyword Search: '{args.query}'")
            print("=" * 80)
            results = client.search(args.query, limit=args.limit, sort_by=args.sort)
            # Handle API response structure
            data = results.get('data', {})
            pagination = data.get('pagination', {})
            total = pagination.get('total', 0)
            showing = len(data.get('skills', []))
            print(f"Found {total} skills | Showing {showing}\\n")
            skills = data.get('skills', [])

        if not skills:
            print("\\n❌ No skills found matching your query")
            print("\\n💡 Try:")
            print("  • Different keywords")
            print("  • AI semantic search (--ai flag)")
            print("  • Broader search terms")
            return

        # Display results
        for i, skill in enumerate(skills, 1):
            display_skill(i, skill, args.ai)

        # Installation
        if args.install:
            if 1 <= args.install <= len(skills):
                skill = skills[args.install - 1]
                install_skill(client, skill)
            else:
                print(f"\\n❌ Invalid skill number. Choose 1-{len(skills)}")
                sys.exit(1)
        else:
            print("\\n💡 To install a skill, run with --install N (e.g., --install 1)")

    except SkillsMPError as e:
        print(f"\\n❌ API Error: {e.message}")

        # Provide helpful guidance based on error code
        if e.code == "MISSING_API_KEY":
            print("💡 Add SKILLSMP_API_KEY to your .env file")
        elif e.code == "INVALID_API_KEY":
            print("💡 Check your API key at https://skillsmp.com/settings/api-keys")
        elif e.code == "MISSING_QUERY":
            print("💡 Provide a search query (e.g., make discover q=\\"pdf\\")")
        elif e.code == "INTERNAL_ERROR":
            print("💡 SkillsMP service issue - try again later")

        sys.exit(1)
    except ValueError as e:
        print(f"\\n❌ Configuration Error: {e}")
        print("\\n💡 Make sure SKILLSMP_API_KEY is set in .env")
        sys.exit(1)
    except requests.exceptions.RequestException as e:
        print(f"\\n❌ Network Error: {e}")
        print("\\n💡 Check your internet connection")
        sys.exit(1)
    except Exception as e:
        print(f"\\n❌ Unexpected Error: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)


def display_skill(number: int, skill: dict, is_ai_search: bool = False):
    """Display a skill result in formatted output.

    Args:
        number: Skill number in results
        skill: Skill data dictionary
        is_ai_search: Whether this is from AI search (show relevance score)
    """
    name = skill.get('name', 'Unknown')
    description = skill.get('description', 'No description')
    author = skill.get('author', 'Unknown')
    stars = skill.get('stars', 0)
    url = skill.get('githubUrl', skill.get('url', ''))  # API uses githubUrl

    print(f"{number}. \\033[1;36m{name}\\033[0m")
    print(f"   📝 {description[:100]}{'...' if len(description) > 100 else ''}")
    print(f"   👤 {author}", end="")

    if stars:
        print(f" | ⭐ {stars} stars", end="")

    if is_ai_search and 'relevanceScore' in skill:
        score = skill['relevanceScore']
        print(f" | 🎯 {score:.2%} relevance", end="")

    print(f"\\n   🔗 {url}\\n")


def install_skill(client: SkillsMP, skill: dict):
    """Install a skill to .agent/skills/ directory.

    Args:
        client: SkillsMP API client
        skill: Skill data dictionary
    """
    skill_name = skill['name']
    skill_url = skill.get('skillUrl')

    if not skill_url:
        print(f"\\n❌ No SKILL.md URL found for {skill_name}")
        return

    # Download SKILL.md
    print(f"\\n📥 Downloading {skill_name}...")
    try:
        content = client.download_skill(skill_url)
    except Exception as e:
        print(f"❌ Download failed: {e}")
        return

    # Create skill directory
    skill_dir = Path(".agent/skills") / skill_name
    skill_dir.mkdir(parents=True, exist_ok=True)

    # Save SKILL.md
    skill_file = skill_dir / "SKILL.md"
    skill_file.write_text(content)

    print(f"✅ Installed to: {skill_dir}")
    print(f"\\n📝 SKILL.md: {len(content)} bytes")
    print(f"\\n💡 Next steps:")
    print(f"   1. Review: cat {skill_file}")
    print(f"   2. Commit: git add .agent/skills/{skill_name}")
    print(f"   3. List: make list-skills")


if __name__ == "__main__":
    main()
'''


def get_skill_discovery_workflow() -> str:
    """Generate the SkillsMP Skill Discovery workflow."""
    lines = [
        "---",
        "description: Search and install skills from SkillsMP marketplace (110,000+ skills)",
        "---",
        "",
        "# Skill Discovery Workflow",
        "",
        "This workflow guides you through discovering and installing skills from the SkillsMP marketplace.",
        "",
        "## Prerequisites",
        "",
        "- SKILLSMP_API_KEY configured in `.env` file",
        "- Internet connection for API access",
        "",
        "## Steps",
        "",
        "### 1. Search for Skills",
        "",
        "Search the SkillsMP marketplace by topic or keyword:",
        "",
        "```bash",
        'make discover q="topic"',
        'make discover q="pdf tools"',
        'make discover q="email templates"',
        "```",
        "",
        "The search will return:",
        "- Skill ID (for installation)",
        "- Skill name",
        "- Description",
        "- Author",
        "- Repository URL",
        "",
        "### 2. Review Search Results",
        "",
        "Examine the returned skills. Note the `id` of any skill you want to install.",
        "",
        "Example output:",
        "```",
        "ID: skill-pdf-tools",
        "Name: PDF Tools",
        "Description: Comprehensive PDF manipulation toolkit",
        "Author: anthropics",
        "Repo: https://github.com/anthropics/skills/tree/main/pdf",
        "```",
        "",
        "### 3. Install a Skill",
        "",
        "Install a skill using its ID:",
        "",
        "```bash",
        'make skill-install id="skill-pdf-tools"',
        "```",
        "",
        "This will:",
        "- Download the SKILL.md file",
        "- Create `.agent/skills/skill-name/` directory",
        "- Save the skill for immediate use",
        "",
        "### 4. Verify Installation",
        "",
        "List installed skills to confirm:",
        "",
        "```bash",
        "make list-skills",
        "```",
        "",
        "The newly installed skill should appear in the output.",
        "",
        "## API Reference",
        "",
        "**Search API:**",
        "```bash",
        'make discover q="<search_query>"',
        "```",
        "",
        "**Install API:**",
        "```bash",
        'make skill-install id="<skill-id>"',
        "```",
        "",
        "## Error Handling",
        "",
        "Common errors:",
        "",
        "- **Missing API Key:** Add `SKILLSMP_API_KEY` to `.env` file",
        "- **Invalid API Key:** Check your key at skillsmp.com/settings",
        "- **Network Error:** Check internet connection",
        "- **Skill Not Found:** Verify the skill ID from search results",
    ]
    return "\n".join(lines)


def get_list_skills_script() -> str:
    """Generate cross-platform list-skills script."""
    return '''#!/usr/bin/env python3
"""List available skills and workflows (cross-platform)."""
from pathlib import Path

def list_items(directory: str, label: str, emoji: str):
    """List markdown files in a directory."""
    path = Path(directory)
    if not path.exists():
        return

    items = sorted([f.stem for f in path.glob("*.md")])
    if items:
        print(f"\\n{emoji} {label}:")
        for item in items:
            print(f"   - {item}")

if __name__ == "__main__":
    list_items(".agent/skills", "Available Skills", "📚")
    list_items(".agent/workflows", "Available Workflows", "📋")
    list_items(".agent/patterns", "Available Patterns", "🎨")
    print()
'''


# ==============================================================================
# Module: core/templates/schemas.py
# ==============================================================================

"""
JSON Schema Template Generators

Generates JSON schemas for workspace validation and IDE autocomplete.
"""


def get_workspace_schema() -> str:
    """Generate JSON schema for workspace.json validation and IDE autocomplete."""
    return json.dumps(
        {
            "$schema": "http://json-schema.org/draft-07/schema#",
            "title": "Gemini Workspace Configuration",
            "description": "Metadata for Gemini Native Workspace Standard",
            "type": "object",
            "required": ["version", "tier", "name", "created", "standard"],
            "properties": {
                "version": {
                    "type": "string",
                    "description": "Standard version used to create workspace",
                    "pattern": "^\\d{4}\\.\\d+$",
                },
                "tier": {
                    "type": "string",
                    "enum": ["1", "2", "3"],
                    "description": "Workspace tier: 1=Lite, 2=Standard, 3=Enterprise",
                },
                "name": {
                    "type": "string",
                    "description": "Project name",
                    "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
                },
                "created": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO 8601 timestamp of workspace creation",
                },
                "standard": {
                    "type": "string",
                    "const": "Gemini Native Workspace Standard",
                },
                "parent_workspace": {
                    "type": "string",
                    "description": "Path to parent workspace (for monorepos)",
                },
                "status": {
                    "type": "string",
                    "enum": ["active", "archived"],
                    "default": "active",
                },
                "upgraded": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Timestamp of last tier upgrade",
                },
                "previous_tier": {
                    "type": "string",
                    "enum": ["1", "2"],
                    "description": "Tier before last upgrade",
                },
                "scripts_updated": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Timestamp of last script update",
                },
            },
        },
        indent=2,
    )


def get_settings_schema() -> str:
    """Generate JSON schema for settings.json validation and IDE autocomplete."""
    return json.dumps(
        {
            "$schema": "http://json-schema.org/draft-07/schema#",
            "title": "Gemini Workspace Settings",
            "description": "Permissions and behavior settings for Gemini workspace",
            "type": "object",
            "properties": {
                "permissions": {
                    "type": "object",
                    "properties": {
                        "filesystem": {
                            "type": "object",
                            "properties": {
                                "read": {"type": "array", "items": {"type": "string"}},
                                "edit": {"type": "array", "items": {"type": "string"}},
                                "ignore": {
                                    "type": "array",
                                    "items": {"type": "string"},
                                },
                            },
                        },
                        "terminal": {
                            "type": "object",
                            "properties": {
                                "execution_policy": {
                                    "type": "string",
                                    "enum": ["safe-only", "hybrid", "unrestricted"],
                                },
                                "allowed_commands": {
                                    "type": "array",
                                    "items": {"type": "string"},
                                },
                            },
                        },
                    },
                },
                "behavior": {
                    "type": "object",
                    "properties": {
                        "auto_context_refresh": {"type": "boolean", "default": True}
                    },
                },
                "parent_workspace": {"type": "string"},
            },
        },
        indent=2,
    )


def get_bootstrap_config_schema() -> str:
    """Generate JSON schema for .gemini-bootstrap.json validation and documentation."""
    return json.dumps(
        {
            "$schema": "http://json-schema.org/draft-07/schema#",
            "title": "Gemini Bootstrap Configuration",
            "description": "Team defaults for the Gemini workspace bootstrap script",
            "type": "object",
            "properties": {
                "default_tier": {
                    "type": "string",
                    "enum": ["1", "2", "3"],
                    "description": "Default tier for new workspaces (1=Lite, 2=Standard, 3=Enterprise)",
                },
                "shared_agent_path": {
                    "type": "string",
                    "description": "Path to shared .agent/ directory for team-wide skills/workflows",
                },
                "templates_path": {
                    "type": "string",
                    "description": "Path to custom templates directory",
                },
                "default_git": {
                    "type": "boolean",
                    "default": False,
                    "description": "Initialize git repository by default",
                },
                "python_version": {
                    "type": "string",
                    "pattern": "^3\\.\\d+$",
                    "default": "3.11",
                    "description": "Python version for CI workflows",
                },
            },
        },
        indent=2,
    )


# ==============================================================================
# Module: core/templates/configs.py
# ==============================================================================

"""
Configuration File Template Generators

Generates pre-commit and other config file templates.
"""


def get_precommit_config() -> str:
    """Generate .pre-commit-config.yaml template."""
    return """# Pre-commit hooks configuration
# Install: pip install pre-commit && pre-commit install
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  # Uncomment for conventional commits
  # - repo: https://github.com/compilerla/conventional-pre-commit
  #   rev: v3.2.0
  #   hooks:
  #     - id: conventional-pre-commit
  #       stages: [commit-msg]
"""


# ==============================================================================
# Module: content_generators.py
# ==============================================================================

"""
Content Generators Module

Generates workspace.json, README, getting started guides, etc.
"""


# Version constant (imported from config in final build)
VERSION = "1.0.0"


def get_workspace_json(tier: str, name: str, parent: str | None = None) -> str:
    """Generate workspace.json metadata with timezone-aware timestamp."""
    data = {
        "version": VERSION,
        "tier": tier,
        "name": name,
        "created": datetime.now(timezone.utc).astimezone().isoformat(),
        "standard": "Gemini Native Workspace Standard",
    }
    if parent:
        data["parent_workspace"] = parent
    return json.dumps(data, indent=2)


def get_getting_started(tier: str, pkg_name: str) -> str:
    """Generate tier-specific getting started guide for onboarding."""
    common = """# Getting Started

Welcome to your Gemini Native Workspace!

## First Steps

1. **Load Context:** Run `make context` and paste into your LLM
2. **Say:** "I am ready to work on this project."
3. **Check Skills:** Run `make list-skills` to see available capabilities

## Essential Commands

| Command | Description |
|---------|-------------|
| `make context` | Load workspace context for LLM |
| `make list-skills` | Show available skills and workflows |
| `make audit` | Validate workspace structure |
| `make session-start` | Begin a work session |
| `make session-end` | End session with summary |

"""
    if tier == "1":
        return (
            common
            + """## Lite Tier Commands

| Command | Description |
|---------|-------------|
| `make run` | Execute main script |
| `make install` | Install dependencies |
| `make clean` | Clear temp files and logs |

## Quick Start

```bash
make install
make run
```
"""
        )
    elif tier == "2":
        return (
            common
            + f"""## Standard Tier Commands

| Command | Description |
|---------|-------------|
| `make run` | Run the application |
| `make test` | Run pytest suite |
| `make install` | Install in dev mode |

## Quick Start

```bash
make install
make test
make run
```

## Development Workflow

1. Plan changes in `scratchpad/current_plan.md`
2. Write tests in `tests/unit/`
3. Implement in `src/{pkg_name}/`
4. Run `make test` until green
5. Update `docs/roadmap.md`
"""
        )
    else:
        return (
            common
            + f"""## Enterprise Tier Commands

| Command | Description |
|---------|-------------|
| `make scan` | Run CLI scanner |
| `make eval` | Run agent capability tests |
| `make context-frontend` | Load frontend domain context |
| `make shift-report` | Generate shift handoff report |
| `make snapshot` | Create workspace snapshot |
| `make restore` | Restore from snapshot |

## Domain Structure

- `src/{pkg_name}/domains/frontend/` - UI context
- `src/{pkg_name}/domains/backend/` - API context
- `outputs/contracts/` - Inter-domain schemas

## Multi-Agent Workflow

1. Load domain-specific context: `make context-frontend`
2. Work within domain boundaries
3. Use contracts for cross-domain communication
4. Run `make eval` before merging
"""
        )


def get_archive_workflow() -> str:
    """Generate archive/deprecation workflow."""
    return """# Workflow: Archive Workspace
**Objective:** Safely deprecate and archive a workspace.
**Trigger:** Project end-of-life or migration complete.

## Pre-Requisites
- [ ] All work committed and pushed
- [ ] No active sessions
- [ ] Stakeholders notified

## Stages

### 1. Export
1. Run `make snapshot` to capture final state
2. Export critical docs to long-term storage
3. Document final architecture in `docs/architecture.md`

### 2. Secure
1. Rotate or revoke all secrets in `.env`
2. Remove credentials from CI/CD:
   - GitHub Actions: Settings -> Secrets -> Delete all repository secrets
   - Cloud providers: Revoke service account keys (AWS/GCP/Azure)
   - Third-party APIs: Regenerate or delete API keys
3. Check and clean common credential locations:
   - `~/.aws/credentials` - AWS CLI credentials
   - `~/.config/gcloud/` - GCP credentials
   - `~/.azure/` - Azure CLI credentials
   - `~/.npmrc` - npm auth tokens
   - `~/.docker/config.json` - Docker registry auth
   - `~/.ssh/` - Deploy keys specific to this project
4. Update access permissions
5. Remove deploy keys and webhooks

### 3. Archive
1. Update `workspace.json`: set `"status": "archived"`
2. Create final git tag: `git tag -a archive-YYYY-MM-DD`
3. Move to archive location or set repo to read-only

### 4. Notify
1. Update project documentation
2. Send archive notice to stakeholders
3. Update any dependent projects

## Post-Archive
- Workspace should not be modified
- Read access only for reference
- Delete after retention period (if applicable)
"""


def get_lite_test_example() -> str:
    """Generate example test for Lite tier (optional, for learning)."""
    return """#!/usr/bin/env python3
\"\"\"Example test for reference - Lite tier doesn't require testing.
To enable testing, upgrade to Standard tier with: python bootstrap.py --upgrade ./
\"\"\"
import sys
sys.path.insert(0, 'src')

from main import main

def test_main_runs():
    \"\"\"Verify main function executes without errors.\"\"\"
    try:
        main()
        assert True
    except Exception as e:
        assert False, f"Main function raised: {e}"

if __name__ == "__main__":
    test_main_runs()
    print("✅ Basic test passed")
"""


def get_standard_unit_test_example(pkg_name: str) -> str:
    """Generate example unit test for Standard tier."""
    return f"""\"\"\"Test suite for {pkg_name}.

Run with: pytest tests/unit/
\"\"\"
import pytest
from src.{pkg_name}.main import main

def test_main_function_exists():
    pass

def test_main_runs():
    \"\"\"Verify main function executes without errors.\"\"\"
    try:
        result = main()
        assert result is not None or result is None  # Just verify it runs
    except Exception as e:
        pytest.fail(f"main() raised {{e}}")

# Add more tests as your code grows
# Example:
# def test_specific_function():
#     assert my_function(input) == expected_output
"""


def get_standard_integration_test_example(pkg_name: str) -> str:
    """Generate example integration test for Standard tier."""
    return f"""\"\"\"Integration tests for {pkg_name}.

Tests that verify multiple components work together.
Run with: pytest tests/integration/
\"\"\"
import pytest

def test_end_to_end_flow():
    \"\"\"Test complete workflow from input to output.\"\"\"
    # Example: Test file processing pipeline
    # 1. Create test input
    # 2. Run processing
    # 3. Verify output
    pass  # Replace with actual integration test

@pytest.mark.slow
def test_external_api_integration():
    \"\"\"Test integration with external services.

    Mark as slow to skip in fast test runs: pytest -m "not slow"
    \"\"\"

    pass  # Replace with actual API integration test
"""


def get_enterprise_eval_test_example(pkg_name: str) -> str:
    """Generate example eval test for Enterprise tier."""
    return f"""\"\"\"Agent capability evaluation tests for {pkg_name}.

Tests multi-agent coordination and domain isolation.
Run with: pytest tests/evals/
\"\"\"
import pytest
import json
from pathlib import Path

def test_contract_validation():
    \"\"\"Verify inter-domain contracts are valid JSON schemas.\"\"\"
    contracts_dir = Path("outputs/contracts")
    if contracts_dir.exists():
        for contract_file in contracts_dir.glob("*.schema.json"):
            with open(contract_file) as f:
                schema = json.load(f)
            assert "$schema" in schema or "type" in schema

def test_domain_isolation():
    \"\"\"Verify domains don't have circular imports.\"\"\"
    # Check frontend doesn't import backend directly
    frontend_files = Path(f"src/{pkg_name}/domains/frontend").glob("**/*.py")
    for file in frontend_files:
        content = file.read_text()
        assert "from ..backend" not in content, \\
            f"{{file}} imports backend directly - use contracts instead"

def test_agent_handoff():
    \"\"\"Verify shift reports contain required information.\"\"\"
    # This would test the shift_report.py output
    pass  # Implement based on shift report spec
"""


def get_adr_template() -> str:
    """Generate ADR template for Enterprise tier."""
    return """# ADR-XXXX: [Title]

**Date:** YYYY-MM-DD
**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-YYYY]
**Deciders:** [List decision makers]

## Context

[Describe the forces at play, including technological, political, social, and project constraints. You may want to include:
- The issue we're trying to solve
- Why this decision is important
- What alternatives were considered]

## Decision

[Clearly state the decision that was made.
"We will..." format works well.]

## Consequences

### Positive

- [What improves]
- [What becomes easier]
- [What new capabilities we gain]

### Negative

- [What becomes harder]
- [What we give up]
- [Technical debt or trade-offs]

### Neutral

- [Things that change but aren't strictly better or worse]

## Notes

[Optional: Additional context, links to discussions, related ADRs, implementation notes]
"""


def get_gitleaks_config() -> str:
    """Generate .gitleaks.toml configuration for secret scanning."""
    return """# Gitleaks configuration for Gemini Workspace
# Scans for hardcoded secrets, API keys, and credentials

title = "Gitleaks Config"

[[rules]]
id = "generic-api-key"
description = "Generic API Key"
regex = '(?i)(api[_-]?key|apikey)[\\s]*[=:][\\s]*['"\\"`]?[a-z0-9]{20,}['"\\"`]?'
tags = ["api", "key"]

[[rules]]
id = "aws-access-key"
description = "AWS Access Key"
regex = '(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}'
tags = ["aws", "access-key"]

[[rules]]
id = "github-token"
description = "GitHub Token"
regex = 'ghp_[0-9a-zA-Z]{36}'
tags = ["github", "token"]

[[rules]]
id = "generic-secret"
description = "Generic Secret"
regex = '(?i)(secret|password|passwd|pwd)[\\s]*[=:][\\s]*['"\\"`][^'"\\"`]{8,}['"\\"`]'
tags = ["secret", "password"]

[[rules]]
id = "private-key"
description = "Private Key"
regex = '-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----'
tags = ["key", "private"]

# Allowlist for test fixtures and examples
[allowlist]
paths = [
  "tests/fixtures/*",
  "**/test_*.py",
  "**/*_test.py",
]

regexes = [
  "example|fake|mock|dummy|test",
]
"""


# ==============================================================================
# Module: operations/output.py
# ==============================================================================

"""Output formatting for workspace operations.

Provides structured data classes and formatters for both JSON and
human-readable output formats.
"""


try:
    from core_utils import success, info, warning, error, dim
except ImportError:
    from ..core_utils import success, info, error, dim


@dataclass
class WorkspaceInfo:
    """Information about a workspace."""

    name: str
    path: str
    tier: str
    tier_name: str
    template: Optional[str]
    git_initialized: bool
    provider: str
    python_version: str


@dataclass
class CreationResult:
    """Result of workspace creation operation."""

    success: bool
    workspace: WorkspaceInfo
    stats: Dict[str, Any]
    next_steps: List[str]
    timestamp: str
    dry_run: bool = False
    error_message: Optional[str] = None


@dataclass
class ValidationResult:
    """Result of workspace validation operation."""

    valid: bool
    path: str
    issues: List[str]
    timestamp: str
    tier: Optional[str] = None
    tier_name: Optional[str] = None


@dataclass
class UpgradeResult:
    """Result of workspace upgrade operation."""

    success: bool
    path: str
    from_tier: str
    to_tier: str
    changes: List[str]
    timestamp: str
    backup_created: bool = False
    error_message: Optional[str] = None


@dataclass
class RollbackResult:
    """Result of workspace rollback operation."""

    success: bool
    path: str
    snapshot_id: str
    restored_tier: Optional[str]
    timestamp: str
    error_message: Optional[str] = None


class OutputFormatter:
    """Format operation results as JSON or human-readable text."""

    def __init__(self, json_mode: bool = False):
        """Initialize formatter.

        Args:
            json_mode: If True, output JSON; otherwise output human-readable text
        """
        self.json_mode = json_mode

    def format_creation(self, result: CreationResult) -> str:
        """Format workspace creation result.

        Args:
            result: Creation result data

        Returns:
            Formatted output string
        """
        if self.json_mode:
            return json.dumps(asdict(result), indent=2)
        else:
            return self._format_creation_human(result)

    def _format_creation_human(self, result: CreationResult) -> str:
        """Format creation result as human-readable text.

        Args:
            result: Creation result data

        Returns:
            Human-readable formatted string
        """
        lines = []

        if result.dry_run:
            lines.append(info(" [DRY RUN MODE - No files created]"))
            lines.append("")

        if result.success:
            workspace = result.workspace
            lines.append(success(f"Created '{workspace.name}' ({workspace.tier_name})"))
            lines.append("")
            lines.append(dim(f"  📁 Location: {workspace.path}"))
            lines.append(dim(f"  🔧 Provider: {workspace.provider}"))
            lines.append(dim(f"  🐍 Python: {workspace.python_version}"))

            if workspace.git_initialized:
                lines.append(dim("  📦 Git: initialized"))

            if workspace.template:
                lines.append(dim(f"  📋 Template: {workspace.template}"))

            stats = result.stats
            if "files_created" in stats:
                lines.append(dim(f"  📝 Files: {stats['files_created']} created"))
            if "dirs_created" in stats:
                lines.append(dim(f"  📂 Directories: {stats['dirs_created']} created"))
            if "duration_seconds" in stats:
                lines.append(dim(f"  ⏱️  Duration: {stats['duration_seconds']:.2f}s"))

            lines.append("")
            lines.append("Next steps:")
            for step in result.next_steps:
                lines.append(f"  👉 {step}")
        else:
            lines.append(error(f"Failed to create workspace: {result.error_message}"))

        return "\n".join(lines)

    def format_validation(self, result: ValidationResult) -> str:
        """Format workspace validation result.

        Args:
            result: Validation result data

        Returns:
            Formatted output string
        """
        if self.json_mode:
            return json.dumps(asdict(result), indent=2)
        else:
            return self._format_validation_human(result)

    def _format_validation_human(self, result: ValidationResult) -> str:
        """Format validation result as human-readable text.

        Args:
            result: Validation result data

        Returns:
            Human-readable formatted string
        """
        lines = []

        if result.valid:
            lines.append(success(f"Workspace '{result.path}' is valid"))
            if result.tier and result.tier_name:
                lines.append(dim(f"  Tier: {result.tier_name}"))
        else:
            lines.append(error(f"Workspace '{result.path}' has issues:"))
            for issue in result.issues:
                lines.append(f"  ❌ {issue}")

        return "\n".join(lines)

    def format_upgrade(self, result: UpgradeResult) -> str:
        """Format workspace upgrade result.

        Args:
            result: Upgrade result data

        Returns:
            Formatted output string
        """
        if self.json_mode:
            return json.dumps(asdict(result), indent=2)
        else:
            return self._format_upgrade_human(result)

    def _format_upgrade_human(self, result: UpgradeResult) -> str:
        """Format upgrade result as human-readable text.

        Args:
            result: Upgrade result data

        Returns:
            Human-readable formatted string
        """
        lines = []

        if result.success:
            lines.append(
                success(
                    f"Upgraded workspace from Tier {result.from_tier} → {result.to_tier}"
                )
            )
            lines.append(dim(f"  📁 Path: {result.path}"))

            if result.backup_created:
                lines.append(dim("  💾 Backup: created"))

            if result.changes:
                lines.append("")
                lines.append("Changes:")
                for change in result.changes:
                    lines.append(f"  • {change}")
        else:
            lines.append(error(f"Upgrade failed: {result.error_message}"))

        return "\n".join(lines)

    def format_rollback(self, result: RollbackResult) -> str:
        """Format workspace rollback result.

        Args:
            result: Rollback result data

        Returns:
            Formatted output string
        """
        if self.json_mode:
            return json.dumps(asdict(result), indent=2)
        else:
            return self._format_rollback_human(result)

    def _format_rollback_human(self, result: RollbackResult) -> str:
        """Format rollback result as human-readable text.

        Args:
            result: Rollback result data

        Returns:
            Human-readable formatted string
        """
        lines = []

        if result.success:
            lines.append(
                success(f"Rolled back workspace to snapshot {result.snapshot_id}")
            )
            lines.append(dim(f"  📁 Path: {result.path}"))
            if result.restored_tier:
                lines.append(dim(f"  📊 Tier: {result.restored_tier}"))
        else:
            lines.append(error(f"Rollback failed: {result.error_message}"))

        return "\n".join(lines)


# ==============================================================================
# Module: operations/utils.py
# ==============================================================================

"""Utility functions for workspace operations.

Shared helper functions used by creation, upgrade, and rollback operations.
"""


try:
    from config import (
        TIERS,
        VERSION,
        SCRIPT_CATEGORIES,
        EXECUTABLE_FILES,
        DEFAULT_REQUIREMENTS,
        get_all_directories,
        get_gitignore_for_tier,
    )
    from core_utils import header
    from core.makefile import get_makefile
    from core.templates import (
        get_github_workflow,
        get_run_audit_script,
        get_manage_session_script,
        get_index_docs_script,
        get_check_status_script,
        get_list_skills_script,
        get_create_snapshot_script,
        get_skillsmp_client_script,
        get_skillsmp_search_script,
        get_skill_discovery_workflow,
    )
    from content_generators import (
        get_standard_unit_test_example,
        get_standard_integration_test_example,
        get_enterprise_eval_test_example,
    )
except ImportError:
    # During build, imports are flat
    from ..config import (
        TIERS,
        VERSION,
        SCRIPT_CATEGORIES,
        EXECUTABLE_FILES,
        DEFAULT_REQUIREMENTS,
        get_all_directories,
        get_gitignore_for_tier,
    )
    from ..core import header
    from ..core.makefile import get_makefile
    from ..core.templates import (
        get_github_workflow,
        get_run_audit_script,
        get_manage_session_script,
        get_index_docs_script,
        get_check_status_script,
        get_list_skills_script,
        get_create_snapshot_script,
        get_skillsmp_client_script,
        get_skillsmp_search_script,
        get_skill_discovery_workflow,
    )
    from ..content_generators import (
        get_standard_unit_test_example,
        get_standard_integration_test_example,
        get_enterprise_eval_test_example,
    )


def _get_script_path(tier: str, script_name: str) -> str:
    """Get tier-specific path for a script.

    Args:
        tier: Workspace tier ("1", "2", or "3")
        script_name: Script name without extension (e.g., "run_audit")

    Returns:
        Full path relative to workspace root (e.g., "scripts/workspace/run_audit.py")
    """
    if tier == "1":  # Lite: flat structure
        return f"scripts/{script_name}.py"
    elif tier == "2":  # Standard: categorized
        # Find which category this script belongs to
        for category, scripts in SCRIPT_CATEGORIES["2"].items():
            if script_name in scripts:
                return f"scripts/{category}/{script_name}.py"
        # Fallback
        return f"scripts/{script_name}.py"
    else:  # Enterprise: domain-based
        # Default to shared for standard scripts
        for category, scripts in SCRIPT_CATEGORIES["3"].items():
            if script_name in scripts:
                return f"scripts/{category}/{script_name}.py"
        # Fallback
        return f"scripts/shared/{script_name}.py"


def _build_workspace_directories(
    tier: str, pkg_name: str, provider: str = "gemini", domain: str = "core"
) -> List[str]:
    """Build list of directories to create.

    Args:
        tier: Workspace tier ("1", "2", or "3")
        pkg_name: Package name (for src directory)
        provider: LLM provider name
        domain: Enterprise domain name (used for tier 3)

    Returns:
        Sorted list of directory paths to create
    """
    # Import provider to get config_dirname
    from providers import get_provider

    provider_obj = get_provider(provider)

    dirs = get_all_directories(tier).copy()

    # Add provider config directory
    dirs.append(provider_obj.config_dirname.lstrip("."))

    # Add script category directories based on tier
    if tier == "2":  # Standard: categorized structure
        for category in SCRIPT_CATEGORIES["2"].keys():
            if category:  # Skip empty key (flat dirs)
                dirs.append(f"scripts/{category}")
    elif tier == "3":  # Enterprise: domain-based structure
        for category in SCRIPT_CATEGORIES["3"].keys():
            if category:  # Skip empty key
                dirs.append(f"scripts/{category}")

    # Add data directories based on tier (Tiered Data Pattern)
    if tier in ["1", "2"]:  # Lite/Standard: flat data structure
        dirs.extend(["data/inputs", "data/outputs"])
    else:  # Enterprise: domain-based data structure
        dirs.extend([f"data/{domain}/inputs", f"data/{domain}/outputs", "data/shared"])

    if tier != "1":
        dirs.append(f"src/{pkg_name}")

    return sorted(list(set(dirs)))


def _build_workspace_files(
    tier: str,
    name: str,
    pkg_name: str,
    parent: str | None,
    python_version: str,
    template_files: dict | None,
    template_deps: list | None,
    provider: str = "gemini",
    domain: str = "core",
) -> Dict[str, str]:
    """Build dictionary of {path: content} for all workspace files.

    Args:
        tier: Workspace tier
        name: Workspace name
        pkg_name: Package name
        parent: Parent workspace path (for monorepos)
        python_version: Python version for CI
        template_files: Optional template file overrides
        template_deps: Optional template dependencies
        provider: LLM provider
        domain: Enterprise domain name

    Returns:
        Dictionary mapping file paths to their contents
    """
    from providers import get_provider

    provider_obj = get_provider(provider)

    files = {}

    # Core - use provider-specific config filename
    files[provider_obj.config_filename] = provider_obj.get_config_template(
        tier, pkg_name
    )
    files["Makefile"] = get_makefile(tier, pkg_name, provider)
    files["README.md"] = (
        f"# {name}\n\nGenerated {provider_obj.name.title()} Workspace ({TIERS[tier]['name']})\n"
    )
    files[".gitignore"] = "\n".join(get_gitignore_for_tier(tier))

    # Provider-specific configuration directory
    config_dir = provider_obj.config_dirname
    files[f"{config_dir}/workspace.json"] = json.dumps(
        {
            "version": VERSION,
            "tier": tier,
            "name": name,
            "provider": provider,
            "created": datetime.now(timezone.utc).astimezone().isoformat(),
            "standard": "Gemini Workspace Framework",
            "parent_workspace": parent,
        },
        indent=2,
    )

    # Scripts - use tier-specific paths
    files[_get_script_path(tier, "run_audit")] = get_run_audit_script()
    files[_get_script_path(tier, "manage_session")] = get_manage_session_script()
    files[_get_script_path(tier, "index_docs")] = get_index_docs_script()
    files[_get_script_path(tier, "check_status")] = get_check_status_script()
    files[_get_script_path(tier, "list_skills")] = get_list_skills_script()

    # Snapshot script for Standard and Enterprise tiers
    if tier in ["2", "3"]:
        files[_get_script_path(tier, "create_snapshot")] = get_create_snapshot_script()

    # SkillsMP Discovery (Standard & Enterprise only)
    if tier != "1":
        # Add SkillsMP client and search script to scripts/shared/
        files["scripts/shared/skillsmp_client.py"] = get_skillsmp_client_script()
        files["scripts/shared/skillsmp_search.py"] = get_skillsmp_search_script()
        files[".agent/workflows/shared/discover_skills.md"] = (
            get_skill_discovery_workflow()
        )

    # Documentation
    files["docs/roadmap.md"] = f"# Roadmap: {name}\n\n- [ ] Initial Setup"

    # CI/CD
    files[".github/workflows/ci.yml"] = get_github_workflow(tier, python_version)

    # Python files for Tier 2+
    if tier != "1":
        files["pyproject.toml"] = (
            f'[project]\nname = "{pkg_name}"\nversion = "0.1.0"\nrequires-python = ">={python_version}"\ndependencies = []'
        )
        files[f"src/{pkg_name}/__init__.py"] = ""
        files[f"src/{pkg_name}/main.py"] = """def main():
    print("Hello World")

if __name__ == "__main__":
    main()
"""

        # Tests
        if tier == "2":
            files[f"tests/unit/test_{pkg_name}.py"] = get_standard_unit_test_example(
                pkg_name
            )
            files["tests/integration/test_integration.py"] = (
                get_standard_integration_test_example(pkg_name)
            )
        elif tier == "3":
            files[f"tests/unit/test_{pkg_name}.py"] = get_standard_unit_test_example(
                pkg_name
            )
            files["tests/integration/test_integration.py"] = (
                get_standard_integration_test_example(pkg_name)
            )
            files["tests/evals/test_evals.py"] = get_enterprise_eval_test_example(
                pkg_name
            )
    else:
        files["src/main.py"] = 'print("Hello World")'
        files["requirements.txt"] = "\n".join(DEFAULT_REQUIREMENTS["1"])

    # Add .gitkeep files for hygiene and data directories
    files["logs/.gitkeep"] = ""
    files["scratchpad/.gitkeep"] = ""

    # Add .gitkeep for data directories based on tier
    if tier in ["1", "2"]:  # Lite/Standard: flat data structure
        files["data/inputs/.gitkeep"] = ""
    else:  # Enterprise: domain-based data structure
        files[f"data/{domain}/inputs/.gitkeep"] = ""
        files["data/shared/.gitkeep"] = ""

    return files


def _write_file_safe(base: Path, path_str: str, content: str):
    """Write file safely with error handling (for thread pool).

    Args:
        base: Base directory path
        path_str: Relative file path
        content: File content

    Returns:
        Tuple of (path_str, error_message or None)
    """
    target = base / path_str
    try:
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content, encoding="utf-8")
        if path_str in EXECUTABLE_FILES:
            target.chmod(0o755)
        return path_str, None
    except Exception as e:
        return path_str, str(e)


def _safe_tar_extract(tar, path):
    """Safely extract tar archive with path traversal protection.

    Args:
        tar: TarFile object
        path: Destination path

    Raises:
        ValueError: If archive contains unsafe paths
    """
    dest_path = Path(path).resolve()

    for member in tar.getmembers():
        # Resolve member path
        member_path = (dest_path / member.name).resolve()

        # Ensure member path is within destination
        if not str(member_path).startswith(str(dest_path)):
            raise ValueError(
                f"Unsafe tar member: {member.name} (path traversal attempt)"
            )

    # Extract after validation
    tar.extractall(path)  # nosec B202 - validated above


def show_dry_run_summary(tier: str, name: str, template_name: str | None, cwd: str):
    """Show dry run summary.

    Args:
        tier: Workspace tier
        name: Workspace name
        template_name: Template name (if used)
        cwd: Current working directory
    """
    header(f"Dry Run: Creating {name}")
    print(f"Tier: {tier} ({TIERS[tier]['name']})")
    print(f"Path: {cwd}/{name}")


def log_bootstrap_event(*args, **kwargs):
    """Telemetry placeholder (not implemented)."""
    pass


def get_shift_report_script():
    """Get shift report script content (placeholder).

    Returns:
        Script content string
    """
    return "# Shift Report\n"


def get_vscode_settings():
    """Get VSCode settings content (placeholder).

    Returns:
        JSON settings string
    """
    return "{}"


def get_settings(tier: str):
    """Get workspace settings content (placeholder).

    Args:
        tier: Workspace tier

    Returns:
        JSON settings string
    """
    return "{}"


# ==============================================================================
# Module: operations/enterprise.py
# ==============================================================================

"""Enterprise tier domain-based workspace organization.

Implements domain detection and inference for Enterprise workspaces.
"""


def get_enterprise_domain(name: str, template_files: Optional[Dict] = None) -> str:
    """Determine enterprise domain for data organization.

    Common domains: core, ml, data, api, analytics

    Args:
        name: Workspace project name
        template_files: Optional template metadata with explicit domain

    Returns:
        Domain name for directory structure (e.g., "ml", "data", "core")

    Examples:
        >>> get_enterprise_domain("ml-pipeline")
        'ml'
        >>> get_enterprise_domain("customer-api")
        'api'
        >>> get_enterprise_domain("my-project")
        'core'
    """
    # Check template for explicit domain
    if template_files and "domain" in template_files:
        return template_files["domain"]

    # Infer from project name
    name_lower = name.lower()
    domain_keywords = {
        "ml": ["ml", "machine-learning", "ai", "model", "training"],
        "data": ["data", "etl", "pipeline", "warehouse"],
        "api": ["api", "service", "gateway", "rest", "graphql"],
        "analytics": ["analytics", "reporting", "dashboard", "bi"],
    }

    for domain, keywords in domain_keywords.items():
        if any(kw in name_lower for kw in keywords):
            return domain

    return "core"  # default


# ==============================================================================
# Module: operations/validation.py
# ==============================================================================

"""Workspace validation operations.

Validates existing workspaces against the Gemini Workspace Framework standard.
"""


try:
    from core_utils import (
        success,
        error,
        info,
        header,
        ValidationError,
        _get_file_cache_key,
    )
except ImportError:
    # During build, imports are flat
    from ..core_utils import (
        success,
        error,
        info,
        header,
        ValidationError,
        _get_file_cache_key,
    )


@lru_cache(maxsize=128)
def _validate_workspace_impl(base_path: str, cache_key: str) -> tuple[dict, list]:
    """Internal implementation for workspace validation (cached).

    Args:
        base_path: Path to workspace
        cache_key: Cache invalidation key (based on workspace.json mtime)

    Returns:
        Tuple of (workspace_dict, issues_list)
    """
    base = Path(base_path)
    issues = []

    ws_file = base / ".gemini/workspace.json"
    if not ws_file.exists():
        return {}, ["Missing .gemini/workspace.json"]

    try:
        with open(ws_file) as f:
            ws = json.load(f)
    except json.JSONDecodeError as e:
        return {}, [f"Invalid workspace.json: {e}"]
    except PermissionError:
        return {}, ["Cannot read workspace.json (permission denied)"]

    # Basic validation checks
    if "tier" not in ws:
        issues.append("Missing 'tier' in workspace.json")
    if "version" not in ws:
        issues.append("Missing 'version' in workspace.json")

    return ws, issues


@lru_cache(maxsize=128)
def validate_workspace(path: str) -> None:
    """Validate an existing workspace against the standard.

    Args:
        path: Path to workspace to validate

    Raises:
        ValidationError: If workspace fails validation checks
        ConfigurationError: If workspace.json is malformed

    Note:
        This function uses caching to avoid redundant validation checks.
        Cache is automatically invalidated when workspace.json is modified.
    """
    base = Path(path).resolve()

    header(f"Validating: {base.name}")

    # Generate cache key based on workspace.json modification time
    ws_file = base / ".gemini/workspace.json"
    cache_key = _get_file_cache_key(ws_file) if ws_file.exists() else "missing"

    # Use cached validation
    ws, issues = _validate_workspace_impl(str(base), cache_key)

    info(f"Workspace version: {ws.get('version', 'unknown')}")
    info(f"Tier: {ws.get('tier', 'unknown')}")

    # Run audit script if exists (not cached due to external execution)
    audit_script = base / "scripts/audit.py"
    if audit_script.exists():
        result = subprocess.run(
            [sys.executable, str(audit_script)], cwd=base, timeout=30
        )
        if result.returncode != 0:
            raise ValidationError(
                f"Audit script failed with exit code {result.returncode}"
            )
    elif issues:
        # Report cached validation issues
        error("Validation failed:")
        for i in issues:
            print(f"   - {i}")
        raise ValidationError(f"Validation failed: {len(issues)} issues found")
    else:
        success("Validation passed")


# ==============================================================================
# Module: operations/creation.py
# ==============================================================================

"""Workspace creation operations.

Handles creation of new workspaces with tier-specific configurations.
"""


try:
    from config import (
        TIERS,
        TEMPLATES,
        DEFAULT_PYTHON_VERSION,
        DEFAULT_PROVIDER,
    )
    from core_utils import (
        validate_project_name,
        success,
        error,
        warning,
        info,
        header,
        dim,
        CreationError,
    )
    from operations.utils import (
        _build_workspace_directories,
        _build_workspace_files,
        _write_file_safe,
        show_dry_run_summary,
        log_bootstrap_event,
    )
    from operations.enterprise import get_enterprise_domain
except ImportError:
    # During build, imports are flat
    from ..config import (
        TIERS,
        TEMPLATES,
        DEFAULT_PYTHON_VERSION,
        DEFAULT_PROVIDER,
    )
    from ..core_utils import (
        validate_project_name,
        success,
        error,
        warning,
        info,
        header,
        dim,
        CreationError,
    )
    from .utils import (
        _build_workspace_directories,
        _build_workspace_files,
        _write_file_safe,
        show_dry_run_summary,
        log_bootstrap_event,
    )
    from .enterprise import get_enterprise_domain


def create_workspace(
    tier: str,
    name: str,
    dry_run: bool = False,
    init_git: bool = False,
    shared_agent: str | None = None,
    parent: str | None = None,
    template_files: dict | None = None,
    template_deps: list | None = None,
    force: bool = False,
    quiet: bool = False,
    verbose: bool = False,
    python_version: str = DEFAULT_PYTHON_VERSION,
    provider: str = DEFAULT_PROVIDER,
) -> None:
    """Create a new workspace with specified configuration.

    Creates a complete workspace directory structure based on the selected tier,
    with all necessary configuration files, scripts, and cognitive layer components.

    Args:
        tier: Workspace tier ('1'=Lite, '2'=Standard, '3'=Enterprise)
        name: Project name (used for directory and package naming)
        dry_run: If True, preview what would be created without writing files
        init_git: If True, initialize a git repository in the workspace
        shared_agent: Path to shared .agent/ directory (creates symlink)
        parent: Path to parent workspace (for monorepo child projects)
        template_files: Dict of {path: content} for template-specific files
        template_deps: List of additional dependencies from template
        force: If True, overwrite existing directory
        quiet: If True, minimal output
        verbose: If True, detailed output
        python_version: Python version for CI workflows (e.g., '3.11')
        provider: LLM provider name

    Raises:
        CreationError: On workspace creation failure
        ValidationError: On invalid project name

    Note:
        On partial failure during creation, attempts cleanup of created directory.
    """
    # Validate FIRST before any destructive operations
    validate_project_name(name)

    # Check for existing git repo in target location
    target_path = Path.cwd() / name
    if (target_path / ".git").exists() and not force:
        warning(f"Directory '{name}' contains an existing git repository")
        info(
            "Use --force to overwrite, or manually add workspace files to the existing project"
        )

    pkg_name = name.replace("-", "_").replace(" ", "_").replace(".", "_").lower()
    base = Path(parent) / name if parent else Path.cwd() / name

    # Ensure parent directory exists if specified
    if parent:
        parent_path = Path(parent)
        if not parent_path.exists():
            try:
                parent_path.mkdir(parents=True, exist_ok=True)
            except (PermissionError, OSError) as e:
                raise CreationError(
                    f"Cannot create parent directory {parent}: {e}"
                ) from e

    # Pre-flight writability check
    if not dry_run:
        target_dir = Path(parent) if parent else Path.cwd()
        try:
            test_path = target_dir / f".{provider}_preflight_{name}"
            test_path.mkdir()
            test_path.rmdir()
        except PermissionError as e:
            raise CreationError(f"Cannot write to directory: {target_dir}") from e
        except OSError as e:
            raise CreationError(f"Filesystem error during pre-flight check: {e}") from e

    if base.exists() and not dry_run:
        if force:
            if not quiet:
                warning(f"Removing existing directory '{name}'")
            shutil.rmtree(base)
        else:
            raise CreationError(
                f"Directory '{name}' already exists. Use --force to overwrite."
            )

    # Get domain for enterprise tier
    domain = "core"  # default
    if tier == "3":
        domain = get_enterprise_domain(name, template_files)

    # Use helper functions to build structure
    dirs = _build_workspace_directories(tier, pkg_name, provider, domain)
    files = _build_workspace_files(
        tier,
        name,
        pkg_name,
        parent,
        python_version,
        template_files,
        template_deps,
        provider,
        domain,
    )

    # --- DRY RUN ---
    if dry_run:
        # NEW: Use enhanced dry-run summary
        template_name = None
        if template_files:
            # Try to determine template name from files
            for tmpl_name, tmpl_config in TEMPLATES.items():
                if tmpl_config.get("files") == template_files:
                    template_name = tmpl_name
                    break

        show_dry_run_summary(tier, name, template_name, Path.cwd())

        # Still show detailed file/dir list for reference
        header("Detailed Structure Preview")
        print(f"\n📁 {name}/")
        for d in sorted(dirs):
            print(f"   📂 {d}/")
        print()
        for f in sorted(list(files.keys())[:20]):  # Show first 20 files
            print(f"   📄 {f}")
        if len(files) > 20:
            print(f"   ... and {len(files) - 20} more files")

        return

    # --- CREATE WITH ROLLBACK ---
    try:
        total_steps = len(dirs) + len(files)
        current = 0

        # Create directories sequentially (fast and avoids race conditions)
        for d in dirs:
            (base / d).mkdir(parents=True, exist_ok=True)
            current += 1
            if not quiet and current % 10 == 0:
                print(f"Progress: {current}/{total_steps} (Creating directories...)")
            if verbose:
                dim(f"  Created directory: {d}")

        # Write files in parallel for improved performance
        errors = []
        max_workers = min(32, len(files) if files else 1)

        with ThreadPoolExecutor(max_workers=max_workers) as executor:
            # Submit all file writes to thread pool
            future_to_path = {
                executor.submit(_write_file_safe, base, path_str, content): path_str
                for path_str, content in files.items()
            }

            # Collect results as they complete
            for future in as_completed(future_to_path):
                path_str, err = future.result()
                current += 1

                if err:
                    errors.append((path_str, err))
                else:
                    if not quiet and current % 10 == 0:
                        print(f"Progress: {current}/{total_steps} (Writing files...)")
                    if verbose:
                        dim(f"  Created file: {path_str}")

        # Check for any errors during parallel writes
        if errors:
            error_summary = "; ".join([f"{p}: {e}" for p, e in errors[:3]])
            if len(errors) > 3:
                error_summary += f" (+{len(errors) - 3} more)"
            raise CreationError(
                f"Failed to write {len(errors)} file(s): {error_summary}"
            )

        (base / ".env").touch()
        if verbose:
            dim("  Created file: .env")

    except CreationError:
        # Re-raise CreationError from parallel writes
        if base.exists():
            warning("Rolling back partial workspace creation...")
            try:
                shutil.rmtree(base)
            except Exception as cleanup_err:
                warning(f"Failed to clean up partial workspace: {cleanup_err}")
        raise
    except (OSError, IOError, UnicodeEncodeError) as e:
        if base.exists():
            warning("Rolling back partial workspace creation...")
            try:
                shutil.rmtree(base)
            except Exception as cleanup_err:
                warning(f"Failed to clean up partial workspace: {cleanup_err}")
        raise CreationError(f"Failed to create workspace: {e}") from e

    # Shared agent symlink (with copy fallback for Windows)
    if shared_agent:
        shared_path = Path(shared_agent).resolve()
        if shared_path.exists():
            local_agent = base / ".agent"
            try:
                if local_agent.exists():
                    shutil.rmtree(local_agent)
                local_agent.symlink_to(shared_path)
                success(f"Linked .agent/ to {shared_agent}")
            except OSError as e:
                # Symlink failed (common on Windows without admin) - fall back to copy
                warning(f"Symlink failed ({e}), copying instead...")
                try:
                    shutil.copytree(shared_path, local_agent)
                    success(f"Copied .agent/ from {shared_agent} (symlink unavailable)")
                    info(
                        "Note: Changes to shared agent won't sync. Consider re-running with admin privileges."
                    )
                except Exception as copy_err:
                    error(f"Failed to copy shared agent: {copy_err}")
        else:
            warning(f"Shared agent path not found: {shared_agent}")

    # Git init
    if init_git:
        try:
            subprocess.run(
                ["git", "init", str(base)], check=True, capture_output=True, timeout=10
            )
            success("Initialized git repository")
        except (subprocess.CalledProcessError, FileNotFoundError):
            warning("Failed to initialize git repository")

    success(f"Created '{name}' ({TIERS[tier]['name']})")

    # NEW: Log successful creation (opt-in telemetry)
    template_name = None
    if template_files:
        for tmpl_name, tmpl_config in TEMPLATES.items():
            if tmpl_config.get("files") == template_files:
                template_name = tmpl_name
                break

    log_bootstrap_event(
        "workspace_created",
        tier=tier,
        template=template_name if template_name else "none",
        has_git=init_git,
        has_parent=bool(parent),
        files_count=len(files),
        dirs_count=len(dirs),
    )

    print(f"\n   👉 cd {name}")
    print("   👉 cat docs/GETTING_STARTED.md")


# ==============================================================================
# Module: operations/upgrade.py
# ==============================================================================

"""Workspace upgrade operations.

Handles upgrading workspaces to higher tiers.
"""


try:
    from config import TIERS
    from core_utils import (
        success,
        warning,
        info,
        header,
        _c,
        Colors,
        ValidationError,
        ConfigurationError,
        UpgradeError,
    )
    from core.templates import get_gemini_md, get_github_workflow
    from core.makefile import get_makefile
    from operations.utils import (
        get_shift_report_script,
        get_vscode_settings,
        get_settings,
    )
except ImportError:
    # During build, imports are flat
    from ..config import TIERS
    from ..core_utils import (
        success,
        warning,
        info,
        header,
        _c,
        Colors,
        ValidationError,
        ConfigurationError,
        UpgradeError,
    )
    from ..core.templates import get_gemini_md, get_github_workflow
    from ..core.makefile import get_makefile
    from .utils import get_shift_report_script, get_vscode_settings, get_settings


def upgrade_workspace(
    path: str, target_tier: str | None = None, yes: bool = False
) -> None:
    """Upgrade a workspace to a higher tier.

    Args:
        path: Path to workspace to upgrade
        target_tier: Target tier to upgrade to (optional, defaults to next tier)
        yes: If True, skip confirmation prompts (for CI/CD automation)

    Raises:
        UpgradeError: If upgrade fails or target tier is lower than current (downgrade)
        ValidationError: If workspace doesn't exist or is invalid
        ConfigurationError: If workspace.json is malformed
    """
    base = Path(path).resolve()

    if not base.exists():
        raise ValidationError(f"Path does not exist: {path}")

    ws_file = base / ".gemini/workspace.json"
    if not ws_file.exists():
        raise ValidationError("Not a Gemini workspace")

    try:
        with open(ws_file) as f:
            ws = json.load(f)
    except json.JSONDecodeError as e:
        raise ConfigurationError(f"Invalid workspace.json (malformed JSON): {e}") from e
    except PermissionError as e:
        raise ConfigurationError(
            "Cannot read workspace.json (permission denied)"
        ) from e

    current_tier = ws.get("tier", "1")
    current_order = TIERS[current_tier]["order"]

    header(f"Current: {TIERS[current_tier]['name']}")

    # Determine target tier
    if target_tier:
        # Validate it's an upgrade, not a downgrade
        target_order = TIERS[target_tier]["order"]
        if target_order < current_order:
            raise UpgradeError(
                f"Cannot downgrade from tier {current_tier} to tier {target_tier}. "
                f"Use rollback instead if you need to restore a previous state."
            )
        if target_order == current_order:
            info(f"Already at tier {current_tier} - no upgrade needed")
            return
        final_target = target_tier
    else:
        # Default to next tier
        if current_order >= 3:
            info("Already at Enterprise tier - no upgrade available")
            return
        final_target = str(current_order + 1)
    pkg_name = (
        ws.get("name", base.name)
        .replace("-", "_")
        .replace(" ", "_")
        .replace(".", "_")
        .lower()
    )

    # Build detailed change preview
    print(
        f"\n{_c(Colors.BOLD)}Upgrading to: {TIERS[final_target]['name']}{_c(Colors.RESET)}\n"
    )

    if final_target == "2":
        print(f"{_c(Colors.GREEN)}✅ Will Add:{_c(Colors.RESET)}")
        print(f"   📂 src/{pkg_name}/ - Modular package structure")
        print("   📂 tests/unit/ - Unit test directory")
        print("   📂 tests/integration/ - Integration test directory")
        print("   📂 .snapshots/ - Snapshot/restore support")
        print("   📄 pyproject.toml - Python package metadata")
        print("   📄 .agent/skills/debug.md - Debug protocol")
        print("   📄 .agent/workflows/feature.md - Feature workflow")
        print(f"\n{_c(Colors.YELLOW)}⚠️  Will Modify:{_c(Colors.RESET)}")
        print("   📄 GEMINI.md - Role: 'Lead Software Engineer'")
        print("   📄 Makefile - Add: test, snapshot, typecheck targets")
        print("   📄 .gemini/settings.json - Update permissions")
        print(f"\n{_c(Colors.RED)}🗑️  Will Remove:{_c(Colors.RESET)}")
        print("   📄 requirements.txt - replaced by pyproject.toml")
    elif final_target == "3":
        print(f"{_c(Colors.GREEN)}✅ Will Add:{_c(Colors.RESET)}")
        print(f"   📂 src/{pkg_name}/domains/frontend/ - Frontend domain")
        print(f"   📂 src/{pkg_name}/domains/backend/ - Backend domain")
        print("   📂 outputs/contracts/ - Inter-domain schemas")
        print("   📂 tests/evals/ - Agent capability tests")
        print("   📂 docs/decisions/ - Architecture Decision Records")
        print("   📂 inputs/ - Read-only data directory")
        print("   📄 scripts/shift_report.py - Handoff reports")
        print(f"\n{_c(Colors.YELLOW)}⚠️  Will Modify:{_c(Colors.RESET)}")
        print("   📄 GEMINI.md - Role: 'CTO / Architect'")
        print("   📄 Makefile - Add: scan, eval, shift-report, lock targets")
        print("   📄 .gemini/settings.json - Update permissions")

    print(f"\n{_c(Colors.BLUE)}📦 Backup:{_c(Colors.RESET)}")
    print("   Modified files are saved to .gemini/backups/pre_upgrade_<TIMESTAMP>/")

    # Confirmation unless --yes is passed
    if not yes:
        response = (
            input(f"\n{_c(Colors.BOLD)}Proceed with upgrade? [y/N]{_c(Colors.RESET)} ")
            .strip()
            .lower()
        )
        if response != "y":
            print("Upgrade cancelled.")
            return

    # Add missing structure
    # When upgrading multiple tiers (e.g., 1->3), apply all intermediate structures
    if int(final_target) >= 2 and int(current_tier) < 2:
        # Apply Standard tier structure (needed for tier 2 and above)
        (base / f"src/{pkg_name}").mkdir(parents=True, exist_ok=True)
        (base / "tests/unit").mkdir(parents=True, exist_ok=True)
        (base / "tests/integration").mkdir(parents=True, exist_ok=True)

        if not (base / f"src/{pkg_name}/__init__.py").exists():
            (base / f"src/{pkg_name}/__init__.py").write_text("")

        if not (base / "pyproject.toml").exists():
            (base / "pyproject.toml").write_text(
                f'[project]\nname = "{pkg_name}"\nversion = "0.1.0"'
            )

        if not (base / ".agent/skills/debug.md").exists():
            (base / ".agent/skills/debug.md").write_text(
                "# Debug Skill\n\nDebug protocol skill."
            )

        if not (base / ".agent/workflows/feature.md").exists():
            (base / ".agent/workflows/feature.md").write_text(
                "# Feature Workflow\n\nFeature implementation workflow."
            )

        # Clean up Lite tier artifacts
        if (base / "requirements.txt").exists():
            (base / "requirements.txt").unlink()
            warning("removed obsolete requirements.txt")

    if int(final_target) >= 3 and int(current_tier) < 3:
        # Apply Enterprise tier structure (needed for tier 3)
        (base / f"src/{pkg_name}/domains/frontend").mkdir(parents=True, exist_ok=True)
        (base / f"src/{pkg_name}/domains/backend").mkdir(parents=True, exist_ok=True)
        (base / "outputs/contracts").mkdir(parents=True, exist_ok=True)
        (base / "tests/evals").mkdir(parents=True, exist_ok=True)
        (base / "docs/decisions").mkdir(parents=True, exist_ok=True)
        (base / "inputs").mkdir(
            parents=True, exist_ok=True
        )  # Enterprise-specific input directory

        if not (base / f"src/{pkg_name}/domains/frontend/GEMINI.md").exists():
            (base / f"src/{pkg_name}/domains/frontend/GEMINI.md").write_text(
                "# Domain: Frontend\nContext: UI Only."
            )

        if not (base / f"src/{pkg_name}/domains/backend/GEMINI.md").exists():
            (base / f"src/{pkg_name}/domains/backend/GEMINI.md").write_text(
                "# Domain: Backend\nContext: API Only."
            )

        if not (base / "scripts/shift_report.py").exists():
            (base / "scripts/shift_report.py").write_text(get_shift_report_script())

    # Update workspace.json
    ws["tier"] = final_target
    ws["upgraded"] = datetime.now(timezone.utc).astimezone().isoformat()
    ws["previous_tier"] = current_tier

    with open(ws_file, "w") as f:
        json.dump(ws, f, indent=2)

    # Backup existing config files before overwriting
    backup_files = [
        "GEMINI.md",
        "Makefile",
        ".gemini/settings.json",
        ".vscode/settings.json",
        ".github/workflows/ci.yml",
    ]
    backup_dir = (
        base
        / ".gemini/backups"
        / f"pre_upgrade_{datetime.now(timezone.utc).astimezone().strftime('%Y%m%d_%H%M%S')}"
    )
    backup_dir.mkdir(parents=True, exist_ok=True)

    for fname in backup_files:
        fpath = base / fname
        if fpath.exists():
            # Handle nested files by flattening or keeping structure relative to backup_dir?
            # Simple flatten for these specific files is usually okay, but let's be safe
            dest = backup_dir / fname
            dest.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(fpath, dest)
            info(f"Backed up {fname} to {dest}")

    # Update GEMINI.md
    (base / "GEMINI.md").write_text(get_gemini_md(final_target, pkg_name))

    # Update Makefile
    (base / "Makefile").write_text(get_makefile(final_target, pkg_name))

    # Update CI/CD
    (base / ".github/workflows/ci.yml").write_text(get_github_workflow(final_target))

    # Update VS Code settings
    (base / ".vscode/settings.json").write_text(get_vscode_settings())

    # Update settings.json for new tier permissions
    (base / ".gemini/settings.json").write_text(get_settings(final_target))

    success(f"Upgraded to {TIERS[final_target]['name']}")


# ==============================================================================
# Module: operations/rollback.py
# ==============================================================================

"""Workspace rollback operations.

Handles restoring workspaces from backups or snapshots.
"""


try:
    from config import SNAPSHOTS_DIR
    from core_utils import (
        success,
        warning,
        info,
        header,
        _c,
        Colors,
        ValidationError,
        RollbackError,
    )
except ImportError:
    # During build, imports are flat
    from ..config import SNAPSHOTS_DIR
    from ..core_utils import (
        success,
        warning,
        info,
        header,
        _c,
        Colors,
        ValidationError,
        RollbackError,
    )


def _safe_tar_extract(tar: tarfile.TarFile, path: str) -> None:
    """Safely extract tar archive with path traversal protection.

    Args:
        tar: TarFile object
        path: Destination path

    Raises:
        ValueError: If archive contains unsafe paths
    """
    dest_path = Path(path).resolve()

    for member in tar.getmembers():
        # Resolve member path
        member_path = (dest_path / member.name).resolve()

        # Ensure member path is within destination
        if not str(member_path).startswith(str(dest_path)):
            raise ValueError(
                f"Unsafe tar member: {member.name} (path traversal attempt)"
            )

    # Extract after validation
    tar.extractall(path)  # nosec B202 - validated above


def rollback_workspace(
    path: str, backup_name: str | None = None, yes: bool = False
) -> None:
    """Rollback workspace to a previous state from backup or snapshot.

    Args:
        path: Path to workspace
        backup_name: Specific backup/snapshot name (e.g., 'pre_upgrade_20260126_143022' or 'my_snapshot')
                    If None, uses most recent backup
        yes: If True, skip confirmation prompt

    Raises:
        RollbackError: If rollback operation fails
        ValidationError: If workspace or backup doesn't exist
    """
    base = Path(path).resolve()

    if not base.exists():
        raise ValidationError(f"Path does not exist: {path}")

    # Check for snapshots first (tar.gz format)
    snapshots_dir = base / SNAPSHOTS_DIR
    snapshot_file = None
    if backup_name and snapshots_dir.exists():
        snapshot_file = snapshots_dir / f"{backup_name}.tar.gz"
        if snapshot_file.exists():
            # Restore from tar.gz snapshot
            header(f"Restoring from snapshot: {backup_name}")

            if not yes:
                response = (
                    input(
                        f"\n{_c(Colors.BOLD)}Proceed with restore? [y/N]{_c(Colors.RESET)} "
                    )
                    .strip()
                    .lower()
                )
                if response != "y":
                    print("Restore cancelled.")
                    return

            try:
                # Extract to temp directory first
                with tempfile.TemporaryDirectory() as temp_dir:
                    with tarfile.open(snapshot_file, "r:gz") as tar:
                        # Python 3.12+ security: use filter to prevent path traversal
                        if sys.version_info >= (3, 12):
                            tar.extractall(temp_dir, filter="data")
                        else:
                            # Python 3.11: manual validation
                            _safe_tar_extract(tar, temp_dir)

                    # Copy files from temp to workspace
                    temp_path = Path(temp_dir)
                    restored_count = 0
                    removed_count = 0

                    # Track files that are in the snapshot
                    snapshot_files = set()
                    for item in temp_path.rglob("*"):
                        if item.is_file():
                            rel_path = str(item.relative_to(temp_path))
                            snapshot_files.add(rel_path)
                            target = base / rel_path
                            target.parent.mkdir(parents=True, exist_ok=True)
                            shutil.copy2(item, target)
                            restored_count += 1

                    # Remove files not in snapshot (added after snapshot was taken)
                    # Skip protected directories
                    protected_prefixes = (".snapshots", ".gemini/backups", ".git")
                    for item in base.rglob("*"):
                        if item.is_file():
                            rel = str(item.relative_to(base))
                            if any(rel.startswith(p) for p in protected_prefixes):
                                continue
                            if rel not in snapshot_files:
                                item.unlink()
                                removed_count += 1

                    success(
                        f"Restored {restored_count} file(s), removed {removed_count} file(s) from snapshot {backup_name}"
                    )
                    return

            except (tarfile.TarError, OSError, PermissionError) as e:
                raise RollbackError(f"Failed to restore from snapshot: {e}") from e

    # Fall back to directory-based backups (.gemini/backups)
    backups_dir = base / ".gemini/backups"
    if not backups_dir.exists():
        # Check if we have any snapshots at all
        if snapshots_dir.exists():
            available_snapshots = list(snapshots_dir.glob("*.tar.gz"))
            if available_snapshots:
                snapshot_names = ", ".join([s.stem for s in available_snapshots[:5]])
                raise RollbackError(
                    f"No upgrade backups found, but snapshots exist: {snapshot_names}. "
                    f"Use --backup <name> to specify which snapshot to restore."
                )

        raise RollbackError(
            "No backups directory found (.gemini/backups/). Backups are created automatically during upgrades."
        )

    # Find available backups
    available_backups = sorted(
        [b for b in backups_dir.iterdir() if b.is_dir()], reverse=True
    )

    if not available_backups:
        raise RollbackError("No backups found in .gemini/backups/")

    # Select backup
    if backup_name:
        backup_dir = backups_dir / backup_name
        if not backup_dir.exists():
            available_names = ", ".join([b.name for b in available_backups[:5]])
            raise RollbackError(
                f"Backup not found: {backup_name}. Available backups: {available_names}"
            )
    else:
        # Use most recent
        backup_dir = available_backups[0]
        info(f"Using most recent backup: {backup_dir.name}")

    header(f"Rolling back from: {backup_dir.name}")

    # List files in backup
    backup_files = list(backup_dir.rglob("*"))
    backup_files = [f for f in backup_files if f.is_file()]

    if not backup_files:
        raise RollbackError("Backup directory is empty")

    print(
        f"\n{_c(Colors.YELLOW)}⚠️  Will restore {len(backup_files)} file(s):{_c(Colors.RESET)}"
    )
    for f in backup_files[:10]:  # Show first 10
        rel_path = f.relative_to(backup_dir)
        print(f"   📄 {rel_path}")
    if len(backup_files) > 10:
        print(f"   ... and {len(backup_files) - 10} more files")

    # Confirmation
    if not yes:
        response = (
            input(f"\n{_c(Colors.BOLD)}Proceed with rollback? [y/N]{_c(Colors.RESET)} ")
            .strip()
            .lower()
        )
        if response != "y":
            print("Rollback cancelled.")
            return

    # Perform rollback
    restored_count = 0
    for backup_file in backup_files:
        rel_path = backup_file.relative_to(backup_dir)
        target = base / rel_path

        try:
            target.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(backup_file, target)
            restored_count += 1
        except (PermissionError, IOError) as e:
            warning(f"Failed to restore {rel_path}: {e}")

    success(f"Rolled back {restored_count} file(s) from {backup_dir.name}")
    warning("Rollback complete - verify workspace with 'make audit' and 'make doctor'")


# ==============================================================================
# Module: operations/__init__.py
# ==============================================================================

"""Operations module public API.

This module provides the main operations for workspace management:
- create_workspace: Create a new workspace
- validate_workspace: Validate an existing workspace
- upgrade_workspace: Upgrade workspace to next tier
- rollback_workspace: Rollback workspace from backup
- get_enterprise_domain: Get enterprise domain configuration
- OutputFormatter: Format operation results
- CreationResult: Data class for creation results
- ValidationResult: Data class for validation results
"""


__all__ = [
    "create_workspace",
    "validate_workspace",
    "upgrade_workspace",
    "rollback_workspace",
    "get_enterprise_domain",
    "OutputFormatter",
    "CreationResult",
    "ValidationResult",
]

# ==============================================================================
# Module: __main__.py
# ==============================================================================

"""
Bootstrap CLI Entry Point

Handles command-line argument parsing and main() function.

NOTE: This module contains forward references to symbols from other modules
(TIERS, TEMPLATES, ValidationError, error(), etc.) that are resolved during
the build process when all modules are concatenated. Lint errors for these
are expected and suppressed with # noqa: F821 comments.
"""
# ruff: noqa: F821  # Forward references resolved at build time


# Version constant (imported from config in final build)
VERSION = "1.0.1"
DEFAULT_PYTHON_VERSION = "3.11"

# Exit codes
EXIT_SUCCESS = 0
EXIT_VALIDATION_ERROR = 1
EXIT_CREATION_ERROR = 2
EXIT_UPGRADE_ERROR = 3
EXIT_ROLLBACK_ERROR = 4
EXIT_CONFIG_ERROR = 5
EXIT_WORKSPACE_ERROR = 6
EXIT_INTERRUPT = 130
EXIT_UNEXPECTED_ERROR = 255


# Global USE_COLOR flag (imported from core in final build)
USE_COLOR = True


def run_self_tests():
    """Run internal self-tests for the bootstrap script.

    Tests core functionality without external dependencies.
    Returns exit code 0 on success, 1 on failure.
    """
    print("🧪 Running Bootstrap Self-Tests...\n")

    passed = 0
    failed = 0

    def test(name, condition):
        nonlocal passed, failed
        if condition:
            print(f"  ✅ {name}")
            passed += 1
        else:
            print(f"  ❌ {name}")
            failed += 1

    # Test 1: Version format
    test(
        "VERSION format (YYYY.NN)",
        len(VERSION.split(".")) == 2 and VERSION.split(".")[0].isdigit(),
    )

    # Test 2: Tier definitions exist
    test(
        "TIERS defined with 3 tiers",
        len(TIERS) == 3 and all(k in TIERS for k in ["1", "2", "3"]),
    )  # noqa: F821 - TIERS imported from config in build

    # Test 3: Each tier has required keys
    for tier_id, tier_data in TIERS.items():  # noqa: F821
        test(f"Tier {tier_id} has 'name' key", "name" in tier_data)

    # Test 4: Exit codes defined
    test("EXIT_SUCCESS is 0", EXIT_SUCCESS == 0)
    test("EXIT_VALIDATION_ERROR is non-zero", EXIT_VALIDATION_ERROR != 0)

    # Test 5: Project name validation (if available)
    try:
        # Valid names should pass
        validate_project_name("my-project")
        test("validate_project_name accepts valid name", True)
    except NameError:
        test("validate_project_name available", False)
    except ValidationError:  # noqa: F821 - ValidationError imported from core in build
        test("validate_project_name accepts valid name", False)

    try:
        # Invalid names should fail
        validate_project_name("123-invalid")
        test("validate_project_name rejects invalid name", False)
    except NameError:
        pass  # Already reported above
    except ValidationError:  # noqa: F821
        test("validate_project_name rejects invalid name", True)

    # Test 6: Template consistency
    for tmpl_name, tmpl_config in TEMPLATES.items():  # noqa: F821 - TEMPLATES imported from config in build
        test(f"Template '{tmpl_name}' has tier", "tier" in tmpl_config)

    # Summary
    print(f"\n{'=' * 50}")
    print(f"Results: {passed} passed, {failed} failed")

    if failed > 0:
        print("\n❌ Self-tests FAILED")
        sys.exit(1)
    else:
        print("\n✅ All self-tests passed")
        sys.exit(0)


def main():
    try:
        _main_impl()
    except ValidationError as e:  # noqa: F821
        error(f"Validation failed: {e}")
        sys.exit(EXIT_VALIDATION_ERROR)
    except CreationError as e:  # noqa: F821
        error(f"Workspace creation failed: {e}")
        sys.exit(EXIT_CREATION_ERROR)
    except UpgradeError as e:  # noqa: F821
        error(f"Upgrade failed: {e}")
        sys.exit(EXIT_UPGRADE_ERROR)
    except RollbackError as e:  # noqa: F821
        error(f"Rollback failed: {e}")
        sys.exit(EXIT_ROLLBACK_ERROR)
    except ConfigurationError as e:  # noqa: F821
        error(f"Configuration error: {e}")
        sys.exit(EXIT_CONFIG_ERROR)
    except WorkspaceError as e:  # noqa: F821
        error(f"Workspace operation failed: {e}")
        sys.exit(EXIT_WORKSPACE_ERROR)
    except KeyboardInterrupt:
        print("\n\nInterrupted by user")
        sys.exit(EXIT_INTERRUPT)
    except Exception as e:
        import traceback

        traceback.print_exc()
        error(f"Unexpected error: {e}")
        sys.exit(EXIT_UNEXPECTED_ERROR)


def _main_impl():
    parser = argparse.ArgumentParser(
        description=f"Gemini Workspace Framework v{VERSION}",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""Examples:
  python bootstrap.py                            Interactive mode
  python bootstrap.py -t 2 -n myapp              Create Standard workspace
  python bootstrap.py -t 3 -n platform --git     Create with git init
  python bootstrap.py -t 2 -n myapp --force -v   Overwrite with verbose output
  python bootstrap.py --from-template fastapi -n myapi  Use template
  python bootstrap.py --list-templates           Show available templates
  python bootstrap.py --validate ./myapp         Validate existing workspace
  python bootstrap.py --upgrade ./myapp          Upgrade workspace tier
  python bootstrap.py --update-scripts ./myapp   Update scripts only
  python bootstrap.py --dry-run -t 2 -n myapp    Preview without creating
  python bootstrap.py -t 2 -n child --parent ..  Create child in monorepo
  python bootstrap.py --config ./my-config.json  Use custom config file

After creation:
  cd myapp && make onboard                       First-run experience
        """,
    )

    # Create mode
    parser.add_argument(
        "-t",
        "--tier",
        choices=["1", "2", "3"],
        help="Tier: 1=Lite, 2=Standard, 3=Enterprise",
    )
    parser.add_argument(
        "-V",
        "--version",
        action="version",
        version=f"Gemini Workspace Framework v{VERSION}",
    )
    parser.add_argument("-n", "--name", help="Project name")
    parser.add_argument(
        "--dry-run", action="store_true", help="Preview without creating files"
    )
    parser.add_argument(
        "--force", action="store_true", help="Overwrite existing directory"
    )
    parser.add_argument("--git", action="store_true", help="Initialize git repository")
    parser.add_argument("-q", "--quiet", action="store_true", help="Minimal output")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    parser.add_argument(
        "--no-color",
        action="store_true",
        help="Disable colored output (for CI/logging)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output results in JSON format for machine parsing",
    )
    parser.add_argument(
        "--shared-agent", help="Path to shared .agent/ directory (symlink)"
    )
    parser.add_argument("--parent", help="Parent workspace path (for monorepos)")
    parser.add_argument(
        "--provider",
        choices=["gemini"],
        default="gemini",
        help="LLM provider (default: gemini)",
    )

    # Validate/Upgrade/Update mode
    parser.add_argument(
        "--validate", metavar="PATH", help="Validate existing workspace"
    )
    parser.add_argument(
        "--upgrade", metavar="PATH", help="Upgrade workspace to next tier"
    )
    parser.add_argument(
        "-y",
        "--yes",
        action="store_true",
        help="Skip confirmation prompts (for CI/CD automation)",
    )
    parser.add_argument(
        "--update-scripts",
        metavar="PATH",
        help="Update management scripts without full upgrade",
    )
    parser.add_argument(
        "--rollback", metavar="PATH", help="Rollback workspace from upgrade backup"
    )
    parser.add_argument(
        "--backup",
        metavar="NAME",
        help="Specific backup to restore (use with --rollback)",
    )
    parser.add_argument(
        "--export-template",
        metavar="PATH",
        help="Export an existing workspace as a template",
    )
    parser.add_argument(
        "--template-name",
        metavar="NAME",
        help="Name for exported template (use with --export-template)",
    )

    parser.add_argument(
        "--config",
        metavar="PATH",
        help="Path to config file (default: .gemini-bootstrap.json)",
    )
    parser.add_argument(
        "--validate-schemas",
        metavar="PATH",
        help="Validate workspace JSON files against schemas",
    )
    parser.add_argument(
        "--python-version",
        metavar="VERSION",
        default=None,
        help="Python version for CI workflows (default: 3.11)",
    )

    # Template mode
    parser.add_argument(
        "--from-template",
        metavar="NAME",
        help=f"Use template: {', '.join(TEMPLATES.keys())}",
    )
    parser.add_argument(
        "--list-templates", action="store_true", help="List available templates"
    )
    parser.add_argument(
        "--show-telemetry-info",
        action="store_true",
        help="Show what data is collected by telemetry (transparency)",
    )
    parser.add_argument(
        "--run-self-tests",
        action="store_true",
        help="Run internal unit tests for the bootstrap script",
    )

    args = parser.parse_args()

    # Handle --no-color flag
    global USE_COLOR
    if args.no_color:
        USE_COLOR = False

    # Load config file (from --config flag or default location)
    if args.config:
        config_path = Path(args.config)
        if config_path.exists():
            try:
                with open(config_path) as f:
                    config = json.load(f)
                info(f"Using config: {args.config}")
            except (json.JSONDecodeError, PermissionError) as e:
                warning(f"Failed to load config: {e}")
                config = {}
        else:
            error(f"Config file not found: {args.config}")
            sys.exit(1)
    else:
        config = load_config()

    # Handle list-templates
    if args.list_templates:
        header("Available Templates")
        for name, tmpl in TEMPLATES.items():
            print(f"  {name:12} - Tier {tmpl['tier']}, deps: {', '.join(tmpl['deps'])}")
        return

    # Handle show-telemetry-info
    if args.show_telemetry_info:
        show_telemetry_info()  # noqa: F821 - Function defined in operations module
        return

    # Handle self-tests
    if args.run_self_tests:
        run_self_tests()
        return

    # Handle validate mode
    if args.validate:
        validate_workspace(args.validate)
        return

    # Handle upgrade mode
    if args.upgrade:
        upgrade_workspace(args.upgrade, target_tier=args.tier, yes=args.yes)
        return

    # Handle update-scripts mode
    if args.update_scripts:
        update_scripts(args.update_scripts)
        return

    # Handle standalone snapshot creation (--backup NAME --parent PATH)
    if args.backup and args.parent and not args.rollback:
        create_snapshot(args.parent, args.backup)
        return

    # Handle rollback mode
    if args.rollback:
        backup_name = args.backup if hasattr(args, "backup") and args.backup else None
        rollback_workspace(args.rollback, backup_name, yes=args.yes)
        return

    # Handle export-template mode
    if args.export_template:
        if not args.template_name:
            error("Please specify a template name with --template-name")
            sys.exit(1)
        export_workspace_as_template(args.export_template, args.template_name)
        return

    # Handle validate-schemas mode
    if args.validate_schemas:
        validate_schemas(args.validate_schemas)
        return

    # Handle template mode
    template_files = None
    template_deps = None
    if args.from_template:
        # Validation now raises ValidationError
        validate_template_name(args.from_template)
        tmpl = TEMPLATES[args.from_template]
        args.tier = tmpl["tier"]
        template_files = tmpl["files"]
        template_deps = tmpl.get("deps", [])
        info(f"Using template '{args.from_template}' (Tier {args.tier})")

    # Interactive mode for create
    if args.tier is None:
        header(f"MULTI-LLM DEVELOPMENT FRAMEWORK (v{VERSION})")
        print("\nSelect Tier:")
        for k, v in TIERS.items():
            print(f"  [{k}] {v['name']}")

        while True:
            default_tier = config.get("default_tier", "")
            prompt = (
                "\nChoice (1-3)" + (f" [{default_tier}]" if default_tier else "") + ": "
            )
            choice = input(prompt).strip() or default_tier
            if choice in TIERS:
                args.tier = choice
                break
            error("Invalid choice. Please enter 1, 2, or 3.")

    if args.name is None:
        while True:
            args.name = input("Project Name: ").strip() or "gemini_workspace"
            try:
                validate_project_name(args.name)
                break
            except ValidationError as e:  # noqa: F821
                error(str(e))

    # Apply config defaults
    if not args.shared_agent and config.get("shared_agent_path"):
        args.shared_agent = config["shared_agent_path"]

    # Get python_version from args or config and validate
    py_version = args.python_version or config.get(
        "python_version", DEFAULT_PYTHON_VERSION
    )
    validate_python_version(py_version)

    create_workspace(
        args.tier,
        args.name,
        args.dry_run,
        args.git,
        args.shared_agent,
        args.parent,
        template_files,
        template_deps,
        args.force,
        args.quiet,
        args.verbose,
        py_version,
        args.provider,
    )


if __name__ == "__main__":
    main()