moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/core/template/processor.py

@@ -1,85 +1,577 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
-"""Template copy and backup processor (SPEC-INIT-003 v0.3.0: preserve user content)."""
+# # REMOVED_ORPHAN_CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
+"""Enhanced Template copy and backup processor with improved version handling and validation.
+
+SPEC-INIT-003 v0.3.0: preserve user content
+Enhanced with:
+- Comprehensive version field management
+- Template substitution validation
+- Performance optimization
+- Error handling improvements
+- Configuration-driven behavior
+"""
 
 from __future__ import annotations
 
+import json
+import logging
 import re
 import shutil
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Any, Dict, List, Optional
 
 from rich.console import Console
 
 from moai_adk.core.template.backup import TemplateBackup
 from moai_adk.core.template.merger import TemplateMerger
+from moai_adk.statusline.version_reader import VersionConfig, VersionReader
 
 console = Console()
 
 
+@dataclass
+class TemplateProcessorConfig:
+    """Configuration for TemplateProcessor behavior."""
+
+    # Version handling configuration
+    version_cache_ttl_seconds: int = 120
+    version_fallback: str = "unknown"
+    version_format_regex: str = r"^v?(\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?)$"
+    enable_version_validation: bool = True
+    preserve_user_version: bool = True
+
+    # Template substitution configuration
+    validate_template_variables: bool = True
+    max_variable_length: int = 50
+    allowed_variable_pattern: str = r"^[A-Z_]+$"
+    enable_substitution_warnings: bool = True
+
+    # Performance configuration
+    enable_caching: bool = True
+    cache_size: int = 100
+    async_operations: bool = False
+
+    # Error handling configuration
+    graceful_degradation: bool = True
+    verbose_logging: bool = False
+
+    @classmethod
+    def from_dict(cls, config_dict: Dict[str, Any]) -> "TemplateProcessorConfig":
+        """Create config from dictionary."""
+        config_dict = config_dict or {}
+        return cls(
+            version_cache_ttl_seconds=config_dict.get("version_cache_ttl_seconds", 120),
+            version_fallback=config_dict.get("version_fallback", "unknown"),
+            version_format_regex=config_dict.get("version_format_regex", r"^v?(\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?)$"),
+            enable_version_validation=config_dict.get("enable_version_validation", True),
+            preserve_user_version=config_dict.get("preserve_user_version", True),
+            validate_template_variables=config_dict.get("validate_template_variables", True),
+            max_variable_length=config_dict.get("max_variable_length", 50),
+            allowed_variable_pattern=config_dict.get("allowed_variable_pattern", r"^[A-Z_]+$"),
+            enable_substitution_warnings=config_dict.get("enable_substitution_warnings", True),
+            enable_caching=config_dict.get("enable_caching", True),
+            cache_size=config_dict.get("cache_size", 100),
+            async_operations=config_dict.get("async_operations", False),
+            graceful_degradation=config_dict.get("graceful_degradation", True),
+            verbose_logging=config_dict.get("verbose_logging", False),
+        )
+
+
 class TemplateProcessor:
-    """Orchestrate template copying and backups."""
+    """Orchestrate template copying and backups with enhanced version handling and validation."""
 
     # User data protection paths (never touch) - SPEC-INIT-003 v0.3.0
     PROTECTED_PATHS = [
         ".moai/specs/",  # User SPEC documents
         ".moai/reports/",  # User reports
         ".moai/project/",  # User project documents (product/structure/tech.md)
-        # config.json is now FORCE OVERWRITTEN (backup in .moai-backups/)
-        # Merge via /alfred:0-project when optimized=false
+        ".moai/config/sections/",  # User configuration section files (YAML)
+        # config.json/config.yaml is now FORCE OVERWRITTEN (backup in .moai-backups/)
+        # Merge via /moai:0-project when optimized=false
     ]
 
     # Paths excluded from backups
     BACKUP_EXCLUDE = PROTECTED_PATHS
 
-    def __init__(self, target_path: Path) -> None:
-        """Initialize the processor.
+    # Common template variables with validation hints
+    COMMON_TEMPLATE_VARIABLES = {
+        "PROJECT_DIR": "Cross-platform project path (run /moai:0-project to set)",
+        "PROJECT_NAME": "Project name (run /moai:0-project to set)",
+        "AUTHOR": "Project author (run /moai:0-project to set)",
+        "CONVERSATION_LANGUAGE": "Interface language (run /moai:0-project to set)",
+        "MOAI_VERSION": "MoAI-ADK version (should be set automatically)",
+        "MOAI_VERSION_SHORT": "Short MoAI-ADK version (without 'v' prefix)",
+        "MOAI_VERSION_DISPLAY": "Display version with proper formatting",
+        "MOAI_VERSION_TRIMMED": "Trimmed version for UI displays",
+        "MOAI_VERSION_SEMVER": "Semantic version format (major.minor.patch)",
+        "MOAI_VERSION_VALID": "Version validation status",
+        "MOAI_VERSION_SOURCE": "Version source information",
+        "MOAI_VERSION_CACHE_AGE": "Cache age for debugging",
+        "CREATION_TIMESTAMP": "Project creation timestamp",
+        "STATUSLINE_COMMAND": "Cross-platform statusline command (OS-specific)",
+    }
+
+    def __init__(self, target_path: Path, config: Optional[TemplateProcessorConfig] = None) -> None:
+        """Initialize the processor with enhanced configuration.
 
         Args:
             target_path: Project path.
+            config: Optional configuration for processor behavior.
         """
         self.target_path = target_path.resolve()
         self.template_root = self._get_template_root()
         self.backup = TemplateBackup(self.target_path)
         self.merger = TemplateMerger(self.target_path)
         self.context: dict[str, str] = {}  # Template variable substitution context
+        self._version_reader: VersionReader | None = None
+        self.config = config or TemplateProcessorConfig()
+        self._substitution_cache: Dict[
+            int, tuple[str, list[str]]
+        ] = {}  # Cache for substitution results (key: hash, value: (content, warnings))
+        self._variable_validation_cache: Dict[str, bool] = {}  # Cache for variable validation
+        self.logger = logging.getLogger(__name__)
 
-    def _get_template_root(self) -> Path:
-        """Return the template root path."""
-        # src/moai_adk/core/template/processor.py → src/moai_adk/templates/
-        current_file = Path(__file__).resolve()
-        package_root = current_file.parent.parent.parent
-        return package_root / "templates"
+        if self.config.verbose_logging:
+            self.logger.info(f"TemplateProcessor initialized with config: {self.config}")
 
     def set_context(self, context: dict[str, str]) -> None:
-        """Set variable substitution context.
+        """Set variable substitution context with enhanced validation.
 
         Args:
             context: Dictionary of template variables.
         """
         self.context = context
+        self._substitution_cache.clear()  # Clear cache when context changes
+        self._variable_validation_cache.clear()
+
+        if self.config.verbose_logging:
+            self.logger.debug(f"Context set with {len(context)} variables")
+
+        # Validate template variables if enabled
+        if self.config.validate_template_variables:
+            self._validate_template_variables(context)
+
+        # Add deprecation mapping for HOOK_PROJECT_DIR
+        if "PROJECT_DIR" in self.context and "HOOK_PROJECT_DIR" not in self.context:
+            self.context["HOOK_PROJECT_DIR"] = self.context["PROJECT_DIR"]
+
+    def _get_version_reader(self) -> VersionReader:
+        """
+        Get or create version reader instance with enhanced configuration.
+
+        Returns:
+            VersionReader instance
+        """
+        if self._version_reader is None:
+            version_config = VersionConfig(
+                cache_ttl_seconds=self.config.version_cache_ttl_seconds,
+                fallback_version=self.config.version_fallback,
+                version_format_regex=self.config.version_format_regex,
+                debug_mode=self.config.verbose_logging,
+            )
+            self._version_reader = VersionReader(version_config)
+
+            if self.config.verbose_logging:
+                self.logger.info("VersionReader created with enhanced configuration")
+        return self._version_reader
+
+    def _get_current_version(self) -> Optional[str]:
+        """
+        Get the current MoAI-ADK package version.
+
+        Returns:
+            Current version string, or None if version cannot be determined
+        """
+        try:
+            version_reader = self._get_version_reader()
+            version = version_reader.get_version()
+            if version and version != "unknown":
+                return version
+        except Exception as e:
+            self.logger.warning(f"Failed to get current version: {e}")
+
+        # Fallback: try direct import
+        try:
+            from moai_adk import __version__
+
+            return __version__
+        except ImportError:
+            pass
+
+        return None
+
+    def _validate_template_variables(self, context: Dict[str, str]) -> None:
+        """
+        Validate template variables with comprehensive checking.
+
+        Args:
+            context: Dictionary of template variables to validate
+        """
+        import re
+
+        if not self.config.validate_template_variables:
+            return
+
+        validation_errors: List[str] = []
+        warning_messages: List[str] = []
+
+        # Check variable names against pattern
+        variable_pattern = re.compile(self.config.allowed_variable_pattern)
+
+        for var_name, var_value in context.items():
+            # Check variable name format
+            if not variable_pattern.match(var_name):
+                validation_errors.append(f"Invalid variable name format: '{var_name}'")
+                continue
+
+            # Check variable length
+            if len(var_name) > self.config.max_variable_length:
+                warning_messages.append(f"Variable name '{var_name}' exceeds maximum length")
+
+            # Check variable value length
+            if len(var_value) > self.config.max_variable_length * 2:
+                warning_messages.append(f"Variable value '{var_value[:20]}...' is very long")
+
+            # Check for potentially dangerous values
+            if "{{" in var_value or "}}" in var_value:
+                warning_messages.append(f"Variable '{var_name}' contains placeholder patterns")
+
+        # Check for common variables that should be present
+        missing_common_vars = []
+        for common_var in self.COMMON_TEMPLATE_VARIABLES:
+            if common_var not in context:
+                missing_common_vars.append(common_var)
+
+        if missing_common_vars and self.config.enable_substitution_warnings:
+            warning_messages.append(f"Common variables missing: {', '.join(missing_common_vars[:3])}")
+
+        # Report validation results
+        if validation_errors and not self.config.graceful_degradation:
+            raise ValueError(f"Template variable validation failed: {validation_errors}")
+
+        if validation_errors and self.config.graceful_degradation:
+            self.logger.warning(f"Template variable validation warnings: {validation_errors}")
+
+        if warning_messages and self.config.enable_substitution_warnings:
+            self.logger.warning(f"Template variable warnings: {warning_messages}")
+
+        if self.config.verbose_logging:
+            self.logger.debug(f"Template variables validated: {len(context)} variables checked")
+
+    def get_enhanced_version_context(self) -> dict[str, str]:
+        """
+        Get enhanced version context with proper error handling and caching.
+
+        Returns comprehensive version information including multiple format options
+        and debugging information.
+
+        Returns:
+            Dictionary containing enhanced version-related template variables
+        """
+        version_context = {}
+        logger = logging.getLogger(__name__)
+
+        try:
+            version_reader = self._get_version_reader()
+            moai_version = version_reader.get_version()
+
+            # Basic version information
+            version_context["MOAI_VERSION"] = moai_version
+            version_context["MOAI_VERSION_SHORT"] = self._format_short_version(moai_version)
+            version_context["MOAI_VERSION_DISPLAY"] = self._format_display_version(moai_version)
+
+            # Enhanced formatting options
+            version_context["MOAI_VERSION_TRIMMED"] = self._format_trimmed_version(moai_version, max_length=10)
+            version_context["MOAI_VERSION_SEMVER"] = self._format_semver_version(moai_version)
+
+            # Validation and source information
+            version_context["MOAI_VERSION_VALID"] = "true" if moai_version != "unknown" else "false"
+            version_context["MOAI_VERSION_SOURCE"] = self._get_version_source(version_reader)
+
+            # Performance metrics
+            cache_age = version_reader.get_cache_age_seconds()
+            if cache_age is not None:
+                version_context["MOAI_VERSION_CACHE_AGE"] = f"{cache_age:.2f}s"
+            else:
+                version_context["MOAI_VERSION_CACHE_AGE"] = "uncached"
+
+            # Additional metadata
+            if self.config.enable_version_validation:
+                is_valid = self._is_valid_version_format(moai_version)
+                version_context["MOAI_VERSION_FORMAT_VALID"] = "true" if is_valid else "false"
+
+            if self.config.verbose_logging:
+                logger.debug(f"Enhanced version context generated: {version_context}")
+
+        except Exception as e:
+            logger.warning(f"Failed to read version for template context: {e}")
+            # Use fallback version with comprehensive formatting
+            fallback_version = self.config.version_fallback
+            version_context["MOAI_VERSION"] = fallback_version
+            version_context["MOAI_VERSION_SHORT"] = self._format_short_version(fallback_version)
+            version_context["MOAI_VERSION_DISPLAY"] = self._format_display_version(fallback_version)
+            version_context["MOAI_VERSION_TRIMMED"] = self._format_trimmed_version(fallback_version, max_length=10)
+            version_context["MOAI_VERSION_SEMVER"] = self._format_semver_version(fallback_version)
+            version_context["MOAI_VERSION_VALID"] = "false" if fallback_version == "unknown" else "true"
+            version_context["MOAI_VERSION_SOURCE"] = "fallback_config"
+            version_context["MOAI_VERSION_CACHE_AGE"] = "unavailable"
+            version_context["MOAI_VERSION_FORMAT_VALID"] = "false"
+
+        return version_context
+
+    def _is_valid_version_format(self, version: str) -> bool:
+        """
+        Validate version format using configured regex pattern.
+
+        Args:
+            version: Version string to validate
+
+        Returns:
+            True if version format is valid
+        """
+        import re
+
+        try:
+            pattern = re.compile(self.config.version_format_regex)
+            return bool(pattern.match(version))
+        except re.error:
+            # Fallback to default pattern if custom one is invalid
+            default_pattern = re.compile(r"^v?(\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?)$")
+            return bool(default_pattern.match(version))
+
+    def _format_short_version(self, version: str) -> str:
+        """
+        Format short version by removing 'v' prefix if present.
+
+        Args:
+            version: Version string
+
+        Returns:
+            Short version string
+        """
+        return version[1:] if version.startswith("v") else version
+
+    def _format_display_version(self, version: str) -> str:
+        """
+        Format display version with proper formatting.
+
+        Args:
+            version: Version string
+
+        Returns:
+            Display version string
+        """
+        if version == "unknown":
+            return "MoAI-ADK unknown version"
+        elif version.startswith("v"):
+            return f"MoAI-ADK {version}"
+        else:
+            return f"MoAI-ADK v{version}"
+
+    def _format_trimmed_version(self, version: str, max_length: int = 10) -> str:
+        """
+        Format version with maximum length, suitable for UI displays.
+
+        Args:
+            version: Version string
+            max_length: Maximum allowed length for the version string
+
+        Returns:
+            Trimmed version string
+        """
+        if version == "unknown":
+            return "unknown"
+
+        # Remove 'v' prefix for trimming
+        clean_version = version[1:] if version.startswith("v") else version
+
+        # Trim if necessary
+        if len(clean_version) > max_length:
+            return clean_version[:max_length]
+        return clean_version
+
+    def _format_semver_version(self, version: str) -> str:
+        """
+        Format version as semantic version with major.minor.patch structure.
+
+        Args:
+            version: Version string
+
+        Returns:
+            Semantic version string
+        """
+        if version == "unknown":
+            return "0.0.0"
+
+        # Remove 'v' prefix and extract semantic version
+        clean_version = version[1:] if version.startswith("v") else version
+
+        # Extract core semantic version (remove pre-release and build metadata)
+        import re
+
+        semver_match = re.match(r"^(\d+\.\d+\.\d+)", clean_version)
+        if semver_match:
+            return semver_match.group(1)
+        return "0.0.0"
+
+    def _get_version_source(self, version_reader: VersionReader) -> str:
+        """
+        Determine the source of the version information.
+
+        Args:
+            version_reader: VersionReader instance
+
+        Returns:
+            String indicating version source
+        """
+        config = version_reader.get_config()
+        cache_age = version_reader.get_cache_age_seconds()
+
+        if cache_age is not None and cache_age < config.cache_ttl_seconds:
+            return "config_cached"
+        elif cache_age is not None:
+            return "config_stale"
+        else:
+            return config.fallback_source.value
+
+    def _get_template_root(self) -> Path:
+        """Return the template root path."""
+        # src/moai_adk/core/template/processor.py → src/moai_adk/templates/
+        current_file = Path(__file__).resolve()
+        package_root = current_file.parent.parent.parent
+        return package_root / "templates"
 
     def _substitute_variables(self, content: str) -> tuple[str, list[str]]:
-        """Substitute template variables in content.
+        """
+        Substitute template variables in content with enhanced validation and caching.
+
+        Args:
+            content: Content to substitute variables in
 
         Returns:
             Tuple of (substituted_content, warnings_list)
         """
         warnings = []
-
-        # Perform variable substitution
+        logger = logging.getLogger(__name__)
+
+        # Check cache first if enabled
+        cache_key = hash((frozenset(self.context.items()), content[:1000]))
+        if self.config.enable_caching and cache_key in self._substitution_cache:
+            cached_result = self._substitution_cache[cache_key]
+            if self.config.verbose_logging:
+                logger.debug("Using cached substitution result")
+            return cached_result
+
+        # Enhanced variable substitution with validation
+        substitution_count = 0
         for key, value in self.context.items():
             placeholder = f"{{{{{key}}}}}"  # {{KEY}}
             if placeholder in content:
+                if self.config.validate_template_variables:
+                    # Validate variable before substitution
+                    if not self._is_valid_template_variable(key, value):
+                        warnings.append(f"Invalid variable {key} - skipped substitution")
+                        continue
+
                 safe_value = self._sanitize_value(value)
                 content = content.replace(placeholder, safe_value)
+                substitution_count += 1
 
-        # Detect unsubstituted variables
-        remaining = re.findall(r'\{\{([A-Z_]+)\}\}', content)
+                if self.config.verbose_logging:
+                    logger.debug(f"Substituted {key}: {safe_value[:50]}...")
+
+        # Detect unsubstituted variables with enhanced error messages
+        remaining = re.findall(r"\{\{([A-Z_]+)\}\}", content)
         if remaining:
             unique_remaining = sorted(set(remaining))
-            warnings.append(f"Unsubstituted variables: {', '.join(unique_remaining)}")
+
+            # Build detailed warning message with enhanced suggestions
+            warning_parts = []
+            for var in unique_remaining:
+                if var in self.COMMON_TEMPLATE_VARIABLES:
+                    suggestion = self.COMMON_TEMPLATE_VARIABLES[var]
+                    warning_parts.append(f"{{{{{var}}}}} → {suggestion}")
+                else:
+                    warning_parts.append(f"{{{{{var}}}}} → Unknown variable (check template)")
+
+            warnings.append("Template variables not substituted:")
+            warnings.extend(f"  • {part}" for part in warning_parts)
+
+            if self.config.enable_substitution_warnings:
+                warnings.append("💡 Run 'uv run moai-adk update' to fix template variables")
+
+        # Add performance information if verbose logging is enabled
+        if self.config.verbose_logging:
+            warnings.append(f"  📊 Substituted {substitution_count} variables")
+
+        # Cache the result if enabled
+        if self.config.enable_caching:
+            result = (content, warnings)
+            self._substitution_cache[cache_key] = result
+
+            # Manage cache size
+            if len(self._substitution_cache) > self.config.cache_size:
+                # Remove oldest entry (simple FIFO)
+                oldest_key = next(iter(self._substitution_cache))
+                del self._substitution_cache[oldest_key]
+                if self.config.verbose_logging:
+                    logger.debug("Cache size limit reached, removed oldest entry")
 
         return content, warnings
 
+    def _is_valid_template_variable(self, key: str, value: str) -> bool:
+        """
+        Validate a template variable before substitution.
+
+        Args:
+            key: Variable name
+            value: Variable value
+
+        Returns:
+            True if variable is valid
+        """
+        import re
+
+        # Check variable name format
+        if not re.match(self.config.allowed_variable_pattern, key):
+            return False
+
+        # Check variable length
+        if len(key) > self.config.max_variable_length:
+            return False
+
+        # Check value length
+        if len(value) > self.config.max_variable_length * 2:
+            return False
+
+        # Note: {{ }} patterns are handled by sanitization, not validation
+
+        # Check for empty values
+        if not value.strip():
+            return False
+
+        return True
+
+    def clear_substitution_cache(self) -> None:
+        """Clear the substitution cache."""
+        self._substitution_cache.clear()
+        if self.config.verbose_logging:
+            self.logger.debug("Substitution cache cleared")
+
+    def get_cache_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+
+        Returns:
+            Dictionary containing cache statistics
+        """
+        return {
+            "cache_size": len(self._substitution_cache),
+            "max_cache_size": self.config.cache_size,
+            "cache_enabled": self.config.enable_caching,
+            "cache_hit_ratio": 0.0,  # Would need to track hits to implement this
+        }
+
     def _sanitize_value(self, value: str) -> str:
         """Sanitize value to prevent recursive substitution and control characters.
 
@@ -90,9 +582,9 @@ class TemplateProcessor:
             Sanitized value.
         """
         # Remove control characters (keep printable and whitespace)
-        value = ''.join(c for c in value if c.isprintable() or c in '\n\r\t')
+        value = "".join(c for c in value if c.isprintable() or c in "\n\r\t")
         # Prevent recursive substitution by removing placeholder patterns
-        value = value.replace('{{', '').replace('}}', '')
+        value = value.replace("{{", "").replace("}}", "")
         return value
 
     def _is_text_file(self, file_path: Path) -> bool:
@@ -105,8 +597,18 @@ class TemplateProcessor:
             True if file is text-based.
         """
         text_extensions = {
-            '.md', '.json', '.txt', '.py', '.ts', '.js',
-            '.yaml', '.yml', '.toml', '.xml', '.sh', '.bash'
+            ".md",
+            ".json",
+            ".txt",
+            ".py",
+            ".ts",
+            ".js",
+            ".yaml",
+            ".yml",
+            ".toml",
+            ".xml",
+            ".sh",
+            ".bash",
         }
         return file_path.suffix.lower() in text_extensions
 
@@ -127,10 +629,10 @@ class TemplateProcessor:
         Returns:
             Content with localized descriptions.
         """
-        import yaml
+        import yaml  # type: ignore[import-untyped]
 
         # Pattern to match YAML frontmatter
-        frontmatter_pattern = r'^---\n(.*?)\n---'
+        frontmatter_pattern = r"^---\n(.*?)\n---"
         match = re.match(frontmatter_pattern, content, re.DOTALL)
 
         if not match:
@@ -141,18 +643,18 @@ class TemplateProcessor:
             yaml_data = yaml.safe_load(yaml_content)
 
             # Check if description is a dict (multilingual)
-            if isinstance(yaml_data.get('description'), dict):
+            if isinstance(yaml_data.get("description"), dict):
                 # Select language (fallback to English)
-                descriptions = yaml_data['description']
-                selected_desc = descriptions.get(language, descriptions.get('en', ''))
+                descriptions = yaml_data["description"]
+                selected_desc = descriptions.get(language, descriptions.get("en", ""))
 
                 # Replace description with selected language
-                yaml_data['description'] = selected_desc
+                yaml_data["description"] = selected_desc
 
                 # Reconstruct frontmatter
                 new_yaml = yaml.dump(yaml_data, allow_unicode=True, sort_keys=False)
                 # Preserve the rest of the content
-                rest_content = content[match.end():]
+                rest_content = content[match.end() :]
                 return f"---\n{new_yaml}---{rest_content}"
 
         except Exception:
@@ -171,22 +673,22 @@ class TemplateProcessor:
         Returns:
             List of warnings.
         """
+        import stat
+
         warnings = []
 
         # Text files: read, substitute, write
         if self._is_text_file(src) and self.context:
             try:
-                content = src.read_text(encoding='utf-8')
+                content = src.read_text(encoding="utf-8")
                 content, file_warnings = self._substitute_variables(content)
 
                 # Apply description localization for command/output-style files
-                if src.suffix == '.md' and (
-                    'commands/alfred' in str(src) or 'output-styles/alfred' in str(src)
-                ):
-                    lang = self.context.get('CONVERSATION_LANGUAGE', 'en')
+                if src.suffix == ".md" and ("commands/alfred" in str(src) or "output-styles/alfred" in str(src)):
+                    lang = self.context.get("CONVERSATION_LANGUAGE", "en")
                     content = self._localize_yaml_description(content, lang)
 
-                dst.write_text(content, encoding='utf-8')
+                dst.write_text(content, encoding="utf-8")
                 warnings.extend(file_warnings)
             except UnicodeDecodeError:
                 # Binary file fallback
@@ -195,6 +697,12 @@ class TemplateProcessor:
             # Binary file or no context: simple copy
             shutil.copy2(src, dst)
 
+        # Ensure executable permission for shell scripts
+        if src.suffix == ".sh":
+            # Always make shell scripts executable regardless of source permissions
+            dst_mode = dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+            dst.chmod(dst_mode)
+
         return warnings
 
     def _copy_dir_with_substitution(self, src: Path, dst: Path) -> None:
@@ -237,9 +745,11 @@ class TemplateProcessor:
 
         self._copy_claude(silent)
         self._copy_moai(silent)
+        self._sync_new_section_files(silent)  # Add new section files from template
         self._copy_github(silent)
         self._copy_claude_md(silent)
         self._copy_gitignore(silent)
+        self._copy_mcp_json(silent)
 
         if not silent:
             console.print("✅ Templates copied successfully")
@@ -290,9 +800,6 @@ class TemplateProcessor:
     def _copy_claude(self, silent: bool = False) -> None:
         """.claude/ directory copy with variable substitution (selective with alfred folder overwrite).
 
-        @CODE:INIT-004:ALFRED-001 | Copy all 4 Alfred command files from templates
-        @REQ:COMMAND-GENERATION-001 | SPEC-INIT-004: Automatic generation of Alfred command files
-        @SPEC:TEMPLATE-PROCESSING-001 | Template processor integration for Alfred command files
 
         Strategy:
         - Alfred folders (commands/agents/hooks/output-styles/alfred) → copy wholesale (delete & overwrite)
@@ -311,18 +818,21 @@ class TemplateProcessor:
         # Create .claude directory if not exists
         dst.mkdir(parents=True, exist_ok=True)
 
-        # @CODE:INIT-004:ALFRED-002 | Alfred command files must always be overwritten
-        # @CODE:INIT-004:ALFRED-COPY | Copy all 4 Alfred command files from templates
-        # Alfred folders to copy wholesale (overwrite)
-        alfred_folders = [
+        # Alfred and Moai folders to copy wholesale (overwrite)
+        # Including both legacy alfred/ and new moai/ structure
+        alfred_moai_folders = [
             "hooks/alfred",
+            "hooks/moai",
             "commands/alfred",  # Contains 0-project.md, 1-plan.md, 2-run.md, 3-sync.md
-            "output-styles/alfred",
+            "commands/moai",
+            "output-styles/moai",
             "agents/alfred",
+            "agents/moai",
+            # NOTE: "skills" handled by _sync_skills_selective() to preserve custom skills
         ]
 
-        # 1. Copy Alfred folders wholesale (backup before delete & overwrite)
-        for folder in alfred_folders:
+        # 1. Copy Alfred and Moai folders wholesale (backup before delete & overwrite)
+        for folder in alfred_moai_folders:
             src_folder = src / folder
             dst_folder = dst / folder
 
@@ -337,22 +847,71 @@ class TemplateProcessor:
                 if not silent:
                     console.print(f"   ✅ .claude/{folder}/ overwritten")
 
-        # 2. Copy other files/folders individually (smart merge for settings.json)
+        # 1.5 Copy other subdirectories in parent folders (e.g., output-styles/moai, hooks/shared)
+        # This ensures non-alfred subdirectories are also copied
+        parent_folders_with_subdirs = ["output-styles", "hooks", "commands", "agents"]
+        for parent_name in parent_folders_with_subdirs:
+            src_parent = src / parent_name
+            if not src_parent.exists():
+                continue
+
+            for subdir in src_parent.iterdir():
+                if not subdir.is_dir():
+                    continue
+
+                # Skip alfred subdirectories (already handled above)
+                if subdir.name == "alfred":
+                    continue
+
+                rel_subdir = f"{parent_name}/{subdir.name}"
+                dst_subdir = dst / parent_name / subdir.name
+
+                if dst_subdir.exists():
+                    # For non-alfred directories, overwrite with merge if necessary
+                    shutil.rmtree(dst_subdir)
+
+                # Copy the subdirectory
+                shutil.copytree(subdir, dst_subdir)
+                if not silent:
+                    console.print(f"   ✅ .claude/{rel_subdir}/ copied")
+
+        # 1.6 Sync skills selectively (preserve custom skills, update moai-* skills)
+        self._sync_skills_selective(src, dst, silent)
+
+        # 2. Copy other files/folders individually (smart merge for settings.json and config.json)
         all_warnings = []
         for item in src.iterdir():
             rel_path = item.relative_to(src)
             dst_item = dst / rel_path
 
             # Skip Alfred parent folders (already handled above)
-            if item.is_dir() and item.name in ["hooks", "commands", "output-styles", "agents"]:
+            # Also skip "skills" - handled by _sync_skills_selective()
+            if item.is_dir() and item.name in [
+                "hooks",
+                "commands",
+                "output-styles",
+                "agents",
+                "skills",  # Handled by _sync_skills_selective() to preserve custom skills
+            ]:
                 continue
 
             if item.is_file():
                 # Smart merge for settings.json
                 if item.name == "settings.json":
                     self._merge_settings_json(item, dst_item)
+                    # Apply variable substitution to merged settings.json (for cross-platform Hook paths)
+                    if self.context:
+                        content = dst_item.read_text(encoding="utf-8")
+                        content, file_warnings = self._substitute_variables(content)
+                        dst_item.write_text(content, encoding="utf-8")
+                        all_warnings.extend(file_warnings)
+                    if not silent:
+                        console.print("   🔄 settings.json merged (Hook paths configured for your OS)")
+                # Smart merge for config.json
+                elif item.name == "config.json":
+                    self._merge_config_json(item, dst_item)
                     if not silent:
-                        console.print("   🔄 settings.json merged (env variables preserved)")
+                        console.print("   🔄 config.json merged (user preferences preserved)")
                 else:
                     # FORCE OVERWRITE: Always copy other files (no skip)
                     warnings = self._copy_file_with_substitution(item, dst_item)
@@ -370,6 +929,54 @@ class TemplateProcessor:
         if not silent:
             console.print("   ✅ .claude/ copy complete (variables substituted)")
 
+    def _sync_skills_selective(self, src: Path, dst: Path, silent: bool = False) -> None:
+        """Sync only moai-* template skills, preserve custom skills.
+
+        This method ensures that:
+        - Template skills (moai-* prefix) are updated from source
+        - Custom skills (any other prefix) are preserved untouched
+
+        Args:
+            src: Source .claude directory from template
+            dst: Destination .claude directory in project
+            silent: Suppress console output if True
+        """
+        skills_src = src / "skills"
+        skills_dst = dst / "skills"
+
+        if not skills_src.exists():
+            return
+
+        skills_dst.mkdir(parents=True, exist_ok=True)
+
+        # Step 1: Identify template skills in source (moai-* prefix)
+        template_skills = {d.name for d in skills_src.iterdir() if d.is_dir() and d.name.startswith("moai-")}
+
+        # Step 2: Delete only template skills in destination
+        if skills_dst.exists():
+            for skill_dir in list(skills_dst.iterdir()):
+                if skill_dir.is_dir() and skill_dir.name.startswith("moai-"):
+                    shutil.rmtree(skill_dir)
+                    if not silent:
+                        console.print(f"   [dim]Updating template skill: {skill_dir.name}[/dim]")
+
+        # Step 3: Copy template skills from source
+        for skill_name in sorted(template_skills):
+            src_skill = skills_src / skill_name
+            dst_skill = skills_dst / skill_name
+            shutil.copytree(src_skill, dst_skill)
+
+        if not silent and template_skills:
+            console.print(f"   ✅ Synced {len(template_skills)} template skill(s)")
+
+        # Step 4: Report preserved custom skills
+        if skills_dst.exists():
+            custom_skills = [d.name for d in skills_dst.iterdir() if d.is_dir() and not d.name.startswith("moai-")]
+            if custom_skills and not silent:
+                preview = ", ".join(sorted(custom_skills)[:3])
+                suffix = "..." if len(custom_skills) > 3 else ""
+                console.print(f"   ✅ Preserved {len(custom_skills)} custom skill(s): {preview}{suffix}")
+
     def _copy_moai(self, silent: bool = False) -> None:
         """.moai/ directory copy with variable substitution (excludes protected paths)."""
         src = self.template_root / ".moai"
@@ -380,10 +987,11 @@ class TemplateProcessor:
                 console.print("⚠️ .moai/ template not found")
             return
 
-        # Paths excluded from template copying (specs/, reports/)
+        # Paths excluded from template copying (specs/, reports/, sections/)
         template_protected_paths = [
             "specs",
             "reports",
+            "config/sections",  # User section YAML files
         ]
 
         all_warnings = []
@@ -416,8 +1024,134 @@ class TemplateProcessor:
         if not silent:
             console.print("   ✅ .moai/ copy complete (variables substituted)")
 
+    def _deep_merge_dicts(self, base: dict, overlay: dict) -> tuple[dict, list[str]]:
+        """Deep merge two dictionaries, preserving base values and adding new keys from overlay.
+
+        Args:
+            base: User's existing configuration (values to preserve)
+            overlay: Template configuration (new keys to add)
+
+        Returns:
+            Tuple of (merged dict, list of new keys added)
+        """
+        result = base.copy()
+        new_keys = []
+
+        for key, value in overlay.items():
+            if key not in result:
+                # New key: add from template
+                result[key] = value
+                new_keys.append(key)
+            elif isinstance(value, dict) and isinstance(result.get(key), dict):
+                # Both are dicts: recurse
+                merged, nested_new = self._deep_merge_dicts(result[key], value)
+                result[key] = merged
+                new_keys.extend([f"{key}.{k}" for k in nested_new])
+            # else: key exists in base, preserve user's value
+
+        return result, new_keys
+
+    def _sync_new_section_files(self, silent: bool = False) -> None:
+        """Sync section files from template to project with smart merge.
+
+        This method handles section file synchronization with the following logic:
+        - New files (template has, project doesn't): Copy from template
+        - Existing files: Smart merge (preserve user values, add new fields)
+        - system.yaml: Always update moai.version to current package version
+
+        Smart Merge Behavior:
+        - User values are NEVER overwritten
+        - Only new keys/fields from template are added
+        - Nested structures are recursively merged
+        """
+        template_sections = self.template_root / ".moai" / "config" / "sections"
+        project_sections = self.target_path / ".moai" / "config" / "sections"
+
+        if not template_sections.exists():
+            return
+
+        # Ensure project sections directory exists
+        project_sections.mkdir(parents=True, exist_ok=True)
+
+        # Get current package version
+        try:
+            from moai_adk import __version__
+
+            current_version = __version__
+        except ImportError:
+            current_version = None
+
+        new_files_added = []
+        files_updated = []
+
+        import yaml
+
+        for template_file in template_sections.glob("*.yaml"):
+            project_file = project_sections / template_file.name
+
+            if not project_file.exists():
+                # New file: copy with variable substitution
+                self._copy_file_with_substitution(template_file, project_file)
+                new_files_added.append(template_file.name)
+            else:
+                # Existing file: smart merge (add new fields only)
+                try:
+                    # Load template data
+                    template_content = template_file.read_text(encoding="utf-8")
+                    template_data = yaml.safe_load(template_content) or {}
+
+                    # Load project data (user's current values)
+                    project_content = project_file.read_text(encoding="utf-8")
+                    project_data = yaml.safe_load(project_content) or {}
+
+                    # Deep merge: preserve user values, add new template keys
+                    merged_data, new_keys = self._deep_merge_dicts(project_data, template_data)
+
+                    if new_keys:
+                        # Write merged data back
+                        with open(project_file, "w", encoding="utf-8") as f:
+                            yaml.dump(
+                                merged_data,
+                                f,
+                                default_flow_style=False,
+                                allow_unicode=True,
+                                sort_keys=False,
+                            )
+                        files_updated.append(f"{template_file.name} (+{len(new_keys)} fields)")
+
+                except Exception:
+                    pass  # Silently ignore yaml errors for individual files
+
+        # Update system.yaml version (special case: always update version)
+        system_yaml = project_sections / "system.yaml"
+        if system_yaml.exists() and current_version:
+            try:
+                content = system_yaml.read_text(encoding="utf-8")
+                data = yaml.safe_load(content) or {}
+
+                # Update moai.version
+                if "moai" not in data:
+                    data["moai"] = {}
+                if data.get("moai", {}).get("version") != current_version:
+                    data["moai"]["version"] = current_version
+
+                    # Write back
+                    with open(system_yaml, "w", encoding="utf-8") as f:
+                        yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+                    if not silent:
+                        console.print(f"   🔄 system.yaml version updated to {current_version}")
+            except Exception:
+                pass  # Silently ignore yaml errors
+
+        if new_files_added and not silent:
+            console.print(f"   ✨ New section files added: {', '.join(new_files_added)}")
+
+        if files_updated and not silent:
+            console.print(f"   🔀 Section files updated: {', '.join(files_updated)}")
+
     def _copy_github(self, silent: bool = False) -> None:
-        """.github/ directory copy with variable substitution."""
+        """.github/ directory copy with smart merge (preserves user workflows)."""
         src = self.template_root / ".github"
         dst = self.target_path / ".github"
 
@@ -426,17 +1160,39 @@ class TemplateProcessor:
                 console.print("⚠️ .github/ template not found")
             return
 
+        # Smart merge: preserve existing user workflows
         if dst.exists():
-            shutil.rmtree(dst)
-
-        self._copy_dir_with_substitution(src, dst)
+            self._merge_github_workflows(src, dst)
+        else:
+            # First time: just copy
+            self._copy_dir_with_substitution(src, dst)
 
         if not silent:
-            console.print("   ✅ .github/ copy complete (variables substituted)")
+            console.print("   🔄 .github/ merged (user workflows preserved, variables substituted)")
 
     def _copy_claude_md(self, silent: bool = False) -> None:
-        """Copy CLAUDE.md with smart merge (preserves \"## Project Information\" section)."""
-        src = self.template_root / "CLAUDE.md"
+        """Copy CLAUDE.md with complete replacement (no merge).
+
+        Selects language-specific CLAUDE.md based on conversation_language setting:
+        - CLAUDE.ko.md for Korean
+        - CLAUDE.ja.md for Japanese
+        - CLAUDE.zh.md for Chinese
+        - CLAUDE.md for English (default)
+        """
+        # Get language from context (set by set_context())
+        language = self.context.get("CONVERSATION_LANGUAGE", "en") if self.context else "en"
+
+        # Select language-specific file
+        if language and language != "en":
+            lang_specific_src = self.template_root / f"CLAUDE.{language}.md"
+            if lang_specific_src.exists():
+                src = lang_specific_src
+            else:
+                # Fallback to English if language-specific file doesn't exist
+                src = self.template_root / "CLAUDE.md"
+        else:
+            src = self.template_root / "CLAUDE.md"
+
         dst = self.target_path / "CLAUDE.md"
 
         if not src.exists():
@@ -444,16 +1200,11 @@ class TemplateProcessor:
                 console.print("⚠️ CLAUDE.md template not found")
             return
 
-        # Smart merge: preserve existing "## Project Information" section
-        if dst.exists():
-            self._merge_claude_md(src, dst)
-            if not silent:
-                console.print("   🔄 CLAUDE.md merged (project information preserved)")
-        else:
-            # First time: just copy
-            self._copy_file_with_substitution(src, dst)
-            if not silent:
-                console.print("   ✅ CLAUDE.md created")
+        # Simple copy with substitution (no merge)
+        self._copy_file_with_substitution(src, dst)
+
+        if not silent:
+            console.print("   ✅ CLAUDE.md replaced (use CLAUDE.local.md for personal instructions)")
 
     def _merge_claude_md(self, src: Path, dst: Path) -> None:
         """Delegate the smart merge for CLAUDE.md.
@@ -464,6 +1215,15 @@ class TemplateProcessor:
         """
         self.merger.merge_claude_md(src, dst)
 
+    def _merge_github_workflows(self, src: Path, dst: Path) -> None:
+        """Delegate the smart merge for .github/workflows/.
+
+        Args:
+            src: Template .github directory.
+            dst: Project .github directory.
+        """
+        self.merger.merge_github_workflows(src, dst)
+
     def _merge_settings_json(self, src: Path, dst: Path) -> None:
         """Delegate the smart merge for settings.json.
 
@@ -473,15 +1233,215 @@ class TemplateProcessor:
         """
         # Find the latest backup for user settings extraction
         backup_path = None
-        if self.backup.backup_dir.exists():
-            backups = sorted(self.backup.backup_dir.iterdir(), reverse=True)
-            if backups:
-                backup_settings = backups[0] / ".claude" / "settings.json"
-                if backup_settings.exists():
-                    backup_path = backup_settings
+        latest_backup = self.backup.get_latest_backup()
+        if latest_backup:
+            backup_settings = latest_backup / ".claude" / "settings.json"
+            if backup_settings.exists():
+                backup_path = backup_settings
 
         self.merger.merge_settings_json(src, dst, backup_path)
 
+    def _merge_config_json(self, src: Path, dst: Path) -> None:
+        """Smart merge for config using section YAML files with JSON fallback.
+
+        Supports both new section-based YAML files and legacy config.json.
+        Priority: Section YAML files > config.json fallback
+
+        Args:
+            src: Template config file (config.json for legacy projects).
+            dst: Project config file destination.
+        """
+        import json
+        import os
+
+        try:
+            import yaml  # noqa: F401 # pyright: ignore[reportUnusedImport]
+
+            yaml_available = True
+        except ImportError:
+            yaml_available = False
+
+        # Check for section-based YAML configuration (new approach)
+        sections_dir = self.target_path / ".moai" / "config" / "sections"
+
+        if yaml_available and sections_dir.exists() and sections_dir.is_dir():
+            # Use section YAML files - merge each section individually
+            self._merge_section_yaml_files(sections_dir)
+            return
+
+        # Fallback to legacy config.json merging
+        # Load template config
+        try:
+            template_config = json.loads(src.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, FileNotFoundError) as e:
+            console.print(f"⚠️ Warning: Could not read template config.json: {e}")
+            return
+
+        # Find latest backup config.json
+        latest_backup = self.backup.get_latest_backup()
+        if latest_backup:
+            backup_config_path = latest_backup / ".moai" / "config" / "config.json"
+            if backup_config_path.exists():
+                try:
+                    json.loads(backup_config_path.read_text(encoding="utf-8"))
+                except json.JSONDecodeError as e:
+                    console.print(f"⚠️ Warning: Could not read backup config.json: {e}")
+
+        # Load existing project config.json
+        existing_config = {}
+        if dst.exists():
+            try:
+                existing_config = json.loads(dst.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as e:
+                console.print(f"⚠️ Warning: Could not read existing config.json: {e}")
+
+        # Merge with priority system: Environment > Existing User > Template
+        # We'll use LanguageConfigResolver to handle this properly
+        try:
+            # Import LanguageConfigResolver for priority-based merging
+            from moai_adk.core.language_config_resolver import LanguageConfigResolver
+
+            # Create temporary resolver to handle merging
+            temp_project_path = self.target_path / ".moai" / "config"
+            temp_project_path.mkdir(parents=True, exist_ok=True)
+
+            # Start with template config as base
+            merged_config = template_config.copy()
+
+            # Apply existing user config (higher priority than template)
+            for key, value in existing_config.items():
+                if key not in ["config_source"]:  # Skip metadata
+                    if key in merged_config and isinstance(merged_config[key], dict) and isinstance(value, dict):
+                        # Deep merge for nested objects
+                        merged_config[key].update(value)
+                    else:
+                        merged_config[key] = value
+
+            # Apply environment variables (highest priority)
+            env_mappings = {
+                "MOAI_USER_NAME": ("user", "name"),
+                "MOAI_CONVERSATION_LANG": ("language", "conversation_language"),
+                "MOAI_AGENT_PROMPT_LANG": ("language", "agent_prompt_language"),
+                "MOAI_CONVERSATION_LANG_NAME": (
+                    "language",
+                    "conversation_language_name",
+                ),
+                "MOAI_GIT_COMMIT_MESSAGES_LANG": ("language", "git_commit_messages"),
+                "MOAI_CODE_COMMENTS_LANG": ("language", "code_comments"),
+                "MOAI_DOCUMENTATION_LANG": ("language", "documentation"),
+                "MOAI_ERROR_MESSAGES_LANG": ("language", "error_messages"),
+            }
+
+            for env_var, (section, key) in env_mappings.items():
+                env_value = os.getenv(env_var)
+                if env_value:
+                    if section not in merged_config:
+                        merged_config[section] = {}
+                    merged_config[section][key] = env_value
+
+            # Ensure consistency
+            resolver = LanguageConfigResolver(str(self.target_path))
+            merged_config = resolver._ensure_consistency(merged_config)
+
+            # Write merged config
+            dst.write_text(
+                json.dumps(merged_config, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+
+        except ImportError:
+            # Fallback: simple merge without LanguageConfigResolver
+            merged_config = template_config.copy()
+
+            # Apply existing config
+            for key, value in existing_config.items():
+                if key not in ["config_source"]:
+                    merged_config[key] = value
+
+            dst.write_text(
+                json.dumps(merged_config, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+            console.print("   ⚠️ Warning: Using simple merge (LanguageConfigResolver not available)")
+
+    def _merge_section_yaml_files(self, sections_dir: Path) -> None:
+        """Merge section YAML files with user-specific values preserved.
+
+        Args:
+            sections_dir: Path to sections directory (.moai/config/sections/)
+        """
+        import os
+
+        try:
+            import yaml
+        except ImportError:
+            console.print("⚠️ Warning: PyYAML not available, skipping section merge")
+            return
+
+        # Get current package version for system.yaml update
+        current_version = self._get_current_version()
+
+        # Environment variable mappings for each section
+        env_mappings = {
+            "language.yaml": {
+                "MOAI_CONVERSATION_LANG": ["language", "conversation_language"],
+                "MOAI_AGENT_PROMPT_LANG": ["language", "agent_prompt_language"],
+                "MOAI_CONVERSATION_LANG_NAME": ["language", "conversation_language_name"],
+                "MOAI_GIT_COMMIT_MESSAGES_LANG": ["language", "git_commit_messages"],
+                "MOAI_CODE_COMMENTS_LANG": ["language", "code_comments"],
+                "MOAI_DOCUMENTATION_LANG": ["language", "documentation"],
+                "MOAI_ERROR_MESSAGES_LANG": ["language", "error_messages"],
+            },
+            "user.yaml": {
+                "MOAI_USER_NAME": ["user", "name"],
+            },
+        }
+
+        for section_file in sections_dir.glob("*.yaml"):
+            try:
+                # Read existing section content
+                with open(section_file, "r", encoding="utf-8") as f:
+                    section_data = yaml.safe_load(f) or {}
+
+                modified = False
+
+                # Update system.yaml version to current package version
+                if section_file.name == "system.yaml" and current_version:
+                    if "moai" not in section_data:
+                        section_data["moai"] = {}
+                    if section_data.get("moai", {}).get("version") != current_version:
+                        section_data["moai"]["version"] = current_version
+                        modified = True
+
+                # Apply environment variable overrides if applicable
+                if section_file.name in env_mappings:
+                    for env_var, path in env_mappings[section_file.name].items():
+                        env_value = os.getenv(env_var)
+                        if env_value:
+                            # Navigate to the correct nested location
+                            current = section_data
+                            for key in path[:-1]:
+                                if key not in current:
+                                    current[key] = {}
+                                current = current[key]
+                            if current.get(path[-1]) != env_value:
+                                current[path[-1]] = env_value
+                                modified = True
+
+                # Write back only if modifications were made
+                if modified or section_file.name in env_mappings:
+                    with open(section_file, "w", encoding="utf-8") as f:
+                        yaml.safe_dump(
+                            section_data,
+                            f,
+                            default_flow_style=False,
+                            allow_unicode=True,
+                            sort_keys=False,
+                        )
+
+            except Exception as e:
+                console.print(f"⚠️ Warning: Failed to merge {section_file.name}: {e}")
+
     def _copy_gitignore(self, silent: bool = False) -> None:
         """.gitignore copy (optional)."""
         src = self.template_root / ".gitignore"
@@ -509,6 +1469,47 @@ class TemplateProcessor:
         """
         self.merger.merge_gitignore(src, dst)
 
+    def _copy_mcp_json(self, silent: bool = False) -> None:
+        """.mcp.json copy (smart merge with existing MCP server configuration)."""
+        src = self.template_root / ".mcp.json"
+        dst = self.target_path / ".mcp.json"
+
+        if not src.exists():
+            return
+
+        # Merge with existing .mcp.json when present (preserve user-added MCP servers)
+        if dst.exists():
+            self._merge_mcp_json(src, dst)
+            if not silent:
+                console.print("   🔄 .mcp.json merged (user MCP servers preserved)")
+        else:
+            shutil.copy2(src, dst)
+            if not silent:
+                console.print("   ✅ .mcp.json copy complete")
+
+    def _merge_mcp_json(self, src: Path, dst: Path) -> None:
+        """Smart merge for .mcp.json (preserve user-added MCP servers).
+
+        Args:
+            src: Template .mcp.json.
+            dst: Project .mcp.json.
+        """
+        try:
+            src_data = json.loads(src.read_text(encoding="utf-8"))
+            dst_data = json.loads(dst.read_text(encoding="utf-8"))
+
+            # Merge mcpServers: preserve user servers, update template servers
+            if "mcpServers" in src_data:
+                if "mcpServers" not in dst_data:
+                    dst_data["mcpServers"] = {}
+                # Update with template servers (preserves existing user servers)
+                dst_data["mcpServers"].update(src_data["mcpServers"])
+
+            # Write merged result back
+            dst.write_text(json.dumps(dst_data, indent=2, ensure_ascii=False), encoding="utf-8")
+        except json.JSONDecodeError as e:
+            console.print(f"[yellow]⚠️ Failed to merge .mcp.json: {e}[/yellow]")
+
     def merge_config(self, detected_language: str | None = None) -> dict[str, str]:
         """Delegate the smart merge for config.json.