moai-adk 0.3.12__py3-none-any.whl → 0.4.0__py3-none-any.whl

moai_adk/__init__.py

@@ -4,5 +4,12 @@
 SPEC-First TDD Framework with Alfred SuperAgent
 """
 
-__version__ = "0.3.12"
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("moai-adk")
+except PackageNotFoundError:
+    # Development mode fallback
+    __version__ = "0.4.0-dev"
+
 __all__ = ["__version__"]

moai_adk/__main__.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """MoAI-ADK CLI Entry Point
 
 Implements the CLI entry point:

moai_adk/cli/commands/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """CLI command module
 
 Core commands:

moai_adk/cli/commands/doctor.py

@@ -1,5 +1,5 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_doctor.py
-# @CODE:CLAUDE-COMMANDS-001:CLI | SPEC: SPEC-CLAUDE-COMMANDS-001.md | TEST: tests/unit/test_slash_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_doctor.py
+# @CODE:CLAUDE-COMMANDS-001:CLI | SPEC: SPEC-CLAUDE-COMMANDS-001/spec.md | TEST: tests/unit/test_slash_commands.py
 """MoAI-ADK doctor command
 
 System diagnostics command:

moai_adk/cli/commands/status.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """MoAI-ADK status command
 
 Project status display:

moai_adk/cli/commands/update.py

@@ -1,13 +1,13 @@
-"""Update command"""
+"""Update command - Upgrade moai-adk package to the latest version"""
 import json
-from pathlib import Path
+import subprocess
+import sys
 
 import click
 from packaging import version
 from rich.console import Console
 
 from moai_adk import __version__
-from moai_adk.core.template.processor import TemplateProcessor
 
 console = Console()
 
@@ -21,56 +21,123 @@ def get_latest_version() -> str | None:
     try:
         import urllib.error
         import urllib.request
+        from typing import cast
 
         url = "https://pypi.org/pypi/moai-adk/json"
         with urllib.request.urlopen(url, timeout=5) as response:  # nosec B310 - URL is hardcoded HTTPS to PyPI API, no user input
             data = json.loads(response.read().decode("utf-8"))
-            return data["info"]["version"]
+            version_str: str = cast(str, data["info"]["version"])
+            return version_str
     except (urllib.error.URLError, json.JSONDecodeError, KeyError, TimeoutError):
         # Return None if PyPI check fails
         return None
 
 
+def detect_install_method() -> str:
+    """Detect how moai-adk was installed.
+
+    Returns:
+        'uv-tool', 'uv-pip', or 'pip'
+    """
+    # Check if installed via uv tool
+    try:
+        result = subprocess.run(
+            ["uv", "tool", "list"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False
+        )
+        if result.returncode == 0 and "moai-adk" in result.stdout:
+            return "uv-tool"
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # Check if uv is available (for uv pip)
+    try:
+        subprocess.run(
+            ["uv", "--version"],
+            capture_output=True,
+            timeout=5,
+            check=False
+        )
+        return "uv-pip"
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # Default to pip
+    return "pip"
+
+
+def upgrade_package(install_method: str, target_version: str) -> bool:
+    """Upgrade moai-adk package.
+
+    Args:
+        install_method: 'uv-tool', 'uv-pip', or 'pip'
+        target_version: Target version to upgrade to
+
+    Returns:
+        True if successful, False otherwise
+    """
+    commands = {
+        "uv-tool": ["uv", "tool", "upgrade", "moai-adk"],
+        "uv-pip": ["uv", "pip", "install", "--upgrade", "moai-adk"],
+        "pip": [sys.executable, "-m", "pip", "install", "--upgrade", "moai-adk"],
+    }
+
+    cmd = commands.get(install_method)
+    if not cmd:
+        return False
+
+    try:
+        console.print(f"\n[cyan]📦 Upgrading via {install_method}...[/cyan]")
+        console.print(f"[dim]   Command: {' '.join(cmd)}[/dim]")
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120,
+            check=False
+        )
+
+        if result.returncode == 0:
+            console.print(f"[green]✓ Upgraded to version {target_version}[/green]")
+            return True
+        else:
+            console.print(f"[red]✗ Upgrade failed[/red]")
+            if result.stderr:
+                console.print(f"[dim]{result.stderr.strip()}[/dim]")
+            return False
+
+    except subprocess.TimeoutExpired:
+        console.print("[red]✗ Upgrade timeout[/red]")
+        return False
+    except Exception as e:
+        console.print(f"[red]✗ Upgrade error: {e}[/red]")
+        return False
+
+
 @click.command()
-@click.option(
-    "--path",
-    type=click.Path(exists=True),
-    default=".",
-    help="Project path (default: current directory)"
-)
-@click.option(
-    "--force",
-    is_flag=True,
-    help="Skip backup and force the update"
-)
 @click.option(
     "--check",
     is_flag=True,
-    help="Only check version (do not update)"
+    help="Only check version (do not upgrade)"
 )
-def update(path: str, force: bool, check: bool) -> None:
-    """Update template files to the latest version.
+def update(check: bool) -> None:
+    """Upgrade moai-adk package to the latest version.
 
-    Updates include:
-    - .claude/ (fully replaced)
-    - .moai/ (preserve specs and reports)
-    - CLAUDE.md (merged)
-    - config.json (smart merge)
+    This command automatically detects the installation method
+    (uv tool, uv pip, or pip) and upgrades the package accordingly.
+
+    For template updates, use 'moai-adk init .' instead.
 
     Examples:
-        python -m moai_adk update              # update with backup
-        python -m moai_adk update --force      # update without backup
-        python -m moai_adk update --check      # check version only
+        moai-adk update              # Upgrade to latest version
+        moai-adk update --check      # Check version only
     """
     try:
-        project_path = Path(path).resolve()
-
-        # Verify the project is initialized
-        if not (project_path / ".moai").exists():
-            console.print("[yellow]⚠ Project not initialized[/yellow]")
-            raise click.Abort()
-
-        # Phase 1: check versions
+        # Phase 1: Check versions
         console.print("[cyan]🔍 Checking versions...[/cyan]")
         current_version = __version__
         latest_version = get_latest_version()
@@ -79,74 +146,53 @@ def update(path: str, force: bool, check: bool) -> None:
         if latest_version is None:
             console.print(f"   Current version: {current_version}")
             console.print("   Latest version:  [yellow]Unable to fetch from PyPI[/yellow]")
-            if not force:
-                console.print("[yellow]⚠ Cannot check for updates. Use --force to update anyway.[/yellow]")
-                return
-        else:
-            console.print(f"   Current version: {current_version}")
-            console.print(f"   Latest version:  {latest_version}")
+            console.print("[yellow]⚠ Cannot check for updates[/yellow]")
+            return
+
+        console.print(f"   Current version: {current_version}")
+        console.print(f"   Latest version:  {latest_version}")
 
+        # Parse versions
+        current_ver = version.parse(current_version)
+        latest_ver = version.parse(latest_version)
+
+        # Check mode
         if check:
-            # Exit early when --check is provided
-            if latest_version is None:
-                console.print("[yellow]⚠ Unable to check for updates[/yellow]")
-            elif version.parse(current_version) < version.parse(latest_version):
+            if current_ver < latest_ver:
                 console.print("[yellow]⚠ Update available[/yellow]")
-            elif version.parse(current_version) > version.parse(latest_version):
+            elif current_ver > latest_ver:
                 console.print("[green]✓ Development version (newer than PyPI)[/green]")
             else:
                 console.print("[green]✓ Already up to date[/green]")
             return
 
-        # Check if update is needed (version + optimized status) - skip with --force
-        if not force and latest_version is not None:
-            current_ver = version.parse(current_version)
-            latest_ver = version.parse(latest_version)
-
-            # Don't update if current version is newer or equal
-            if current_ver >= latest_ver:
-                # Check optimized status in config.json
-                config_path = project_path / ".moai" / "config.json"
-                if config_path.exists():
-                    try:
-                        config_data = json.loads(config_path.read_text())
-                        is_optimized = config_data.get("project", {}).get("optimized", False)
-
-                        if is_optimized:
-                            # Already up to date and optimized - exit silently
-                            return
-                        else:
-                            console.print("[yellow]⚠ Optimization needed[/yellow]")
-                            console.print("[dim]Use /alfred:0-project update for template optimization[/dim]")
-                            return
-                    except (json.JSONDecodeError, KeyError):
-                        # If config.json is invalid, proceed with update
-                        pass
-                else:
-                    console.print("[green]✓ Already up to date[/green]")
-                    return
-
-        # Phase 2: create a backup unless --force
-        if not force:
-            console.print("\n[cyan]💾 Creating backup...[/cyan]")
-            processor = TemplateProcessor(project_path)
-            backup_path = processor.create_backup()
-            console.print(f"[green]✓ Backup completed: {backup_path.relative_to(project_path)}[/green]")
-        else:
-            console.print("\n[yellow]⚠ Skipping backup (--force)[/yellow]")
+        # Check if upgrade needed
+        if current_ver >= latest_ver:
+            console.print("[green]✓ Already up to date[/green]")
+            return
 
-        # Phase 3: update templates
-        console.print("\n[cyan]📄 Updating templates...[/cyan]")
-        processor = TemplateProcessor(project_path)
-        processor.copy_templates(backup=False, silent=True)  # Backup already handled
+        # Phase 2: Detect install method
+        install_method = detect_install_method()
+        console.print(f"\n[cyan]🔎 Detected installation method: {install_method}[/cyan]")
 
-        console.print("   [green]✅ .claude/ update complete[/green]")
-        console.print("   [green]✅ .moai/ update complete (specs/reports preserved)[/green]")
-        console.print("   [green]🔄 CLAUDE.md merge complete[/green]")
-        console.print("   [green]🔄 config.json merge complete[/green]")
+        # Phase 3: Upgrade package
+        success = upgrade_package(install_method, latest_version)
 
-        console.print("\n[green]✓ Update complete![/green]")
+        if success:
+            console.print("\n[green]✓ Update complete![/green]")
+            console.print("\n[dim]💡 For template updates, run: moai-adk init .[/dim]")
+        else:
+            console.print("\n[yellow]⚠ Upgrade failed. Please try manually:[/yellow]")
+            if install_method == "uv-tool":
+                console.print("   uv tool upgrade moai-adk")
+            elif install_method == "uv-pip":
+                console.print("   uv pip install --upgrade moai-adk")
+            else:
+                console.print("   pip install --upgrade moai-adk")
+            raise click.Abort()
 
+    except click.Abort:
+        raise
     except Exception as e:
         console.print(f"[red]✗ Update failed: {e}[/red]")
         raise click.ClickException(str(e)) from e

moai_adk/cli/prompts/init_prompts.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-PROMPTS-001 | SPEC: SPEC-CLI-001.md
+# @CODE:CLI-PROMPTS-001 | SPEC: SPEC-CLI-001/spec.md
 """Project initialization prompts
 
 Collect interactive project settings

moai_adk/core/__init__.py

@@ -1,2 +1,2 @@
-# @CODE:PY314-001 | SPEC: SPEC-PY314-001.md | TEST: tests/unit/test_foundation.py
+# @CODE:PY314-001 | SPEC: SPEC-PY314-001/spec.md | TEST: tests/unit/test_foundation.py
 """Core module: primary business logic"""

moai_adk/core/git/branch.py

@@ -1,4 +1,4 @@
-# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001.md | TEST: tests/unit/test_git.py
+# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001/spec.md | TEST: tests/unit/test_git.py
 """
 Branch naming utilities.
 

moai_adk/core/git/manager.py

@@ -1,4 +1,4 @@
-# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001.md | TEST: tests/unit/test_git.py
+# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001/spec.md | TEST: tests/unit/test_git.py
 """
 Git repository management built on GitPython.
 

moai_adk/core/project/detector.py

@@ -1,4 +1,5 @@
 # @CODE:CORE-PROJECT-001 | SPEC: SPEC-CORE-PROJECT-001.md | TEST: tests/unit/test_language_detector.py
+# @CODE:LANG-DETECT-001 | SPEC: SPEC-LANG-DETECT-001.md | TEST: tests/unit/test_detector.py
 """Language detector module.
 
 Automatically detects 20 programming languages.
@@ -8,9 +9,21 @@ from pathlib import Path
 
 
 class LanguageDetector:
-    """Automatically detect up to 20 programming languages."""
+    """Automatically detect up to 20 programming languages.
+
+    Prioritizes framework-specific files (e.g., Laravel, Django) over
+    generic language files to improve accuracy in mixed-language projects.
+    """
 
     LANGUAGE_PATTERNS = {
+        # PHP moved to top for priority (Laravel detection)
+        "php": [
+            "*.php",
+            "composer.json",
+            "artisan",                # Laravel: CLI tool (unique identifier)
+            "app/",                   # Laravel: application directory
+            "bootstrap/laravel.php"   # Laravel: bootstrap file
+        ],
         "python": ["*.py", "pyproject.toml", "requirements.txt", "setup.py"],
         "typescript": ["*.ts", "tsconfig.json"],
         "javascript": ["*.js", "package.json"],
@@ -21,7 +34,6 @@ class LanguageDetector:
         "swift": ["*.swift", "Package.swift"],
         "kotlin": ["*.kt", "build.gradle.kts"],
         "csharp": ["*.cs", "*.csproj"],
-        "php": ["*.php", "composer.json"],
         "ruby": ["*.rb", "Gemfile"],
         "elixir": ["*.ex", "mix.exs"],
         "scala": ["*.scala", "build.sbt"],

moai_adk/core/quality/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:TRUST-001 | SPEC: SPEC-TRUST-001.md | TEST: tests/unit/core/quality/
+# @CODE:TRUST-001 | SPEC: SPEC-TRUST-001/spec.md | TEST: tests/unit/core/quality/
 """TRUST 원칙 자동 검증 시스템"""
 
 from moai_adk.core.quality.trust_checker import TrustChecker

moai_adk/core/quality/trust_checker.py

@@ -1,4 +1,4 @@
-# @CODE:TRUST-001 | SPEC: SPEC-TRUST-001.md | TEST: tests/unit/core/quality/test_trust_checker.py
+# @CODE:TRUST-001 | SPEC: SPEC-TRUST-001/spec.md | TEST: tests/unit/core/quality/test_trust_checker.py
 """
 TRUST 원칙 통합 검증 시스템
 

moai_adk/core/quality/validators/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:TRUST-001 | SPEC: SPEC-TRUST-001.md
+# @CODE:TRUST-001 | SPEC: SPEC-TRUST-001/spec.md
 """TRUST 검증기 패키지"""
 
 from moai_adk.core.quality.validators.base_validator import ValidationResult

moai_adk/core/quality/validators/base_validator.py

@@ -1,4 +1,4 @@
-# @CODE:TRUST-001:VALIDATOR | SPEC: SPEC-TRUST-001.md
+# @CODE:TRUST-001:VALIDATOR | SPEC: SPEC-TRUST-001/spec.md
 """Base validator class and validation result"""
 
 from dataclasses import dataclass

moai_adk/core/template/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003.md | Chain: TEMPLATE-001
+# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
 """Template management module."""
 
 from moai_adk.core.template.backup import TemplateBackup

moai_adk/core/template/backup.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003.md | Chain: TEMPLATE-001
+# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
 """Template backup manager (SPEC-INIT-003 v0.3.0).
 
 Creates and manages backups to protect user data during template updates.
@@ -27,6 +27,7 @@ class TemplateBackup:
             target_path: Project path (absolute).
         """
         self.target_path = target_path.resolve()
+        self.backup_dir = self.target_path / ".moai-backups"
 
     def has_existing_files(self) -> bool:
         """Check whether backup-worthy files already exist.

moai_adk/core/template/config.py

@@ -93,3 +93,27 @@ class ConfigManager:
                 result[key] = value
 
         return result
+
+    @staticmethod
+    def set_optimized(config_path: Path, value: bool) -> None:
+        """Set the optimized field in config.json.
+
+        Args:
+            config_path: Path to config.json.
+            value: Value to set (True or False).
+        """
+        if not config_path.exists():
+            return
+
+        try:
+            with open(config_path, encoding="utf-8") as f:
+                config = json.load(f)
+
+            config.setdefault("project", {})["optimized"] = value
+
+            with open(config_path, "w", encoding="utf-8") as f:
+                json.dump(config, f, ensure_ascii=False, indent=2)
+                f.write("\n")  # Add trailing newline
+        except (json.JSONDecodeError, KeyError, OSError):
+            # Ignore errors if config.json is invalid or inaccessible
+            pass

moai_adk/core/template/languages.py

@@ -1,4 +1,4 @@
-# @CODE:CORE-PROJECT-001 | SPEC: SPEC-CORE-PROJECT-001.md | TEST: tests/unit/test_language_mapping.py
+# @CODE:CORE-PROJECT-001 | SPEC: SPEC-CORE-PROJECT-001/spec.md | TEST: tests/unit/test_language_mapping.py
 """Template mapping by language.
 
 Defines template paths for 20 programming languages.

moai_adk/core/template/merger.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003.md | Chain: TEMPLATE-001
+# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
 """Template file merger (SPEC-INIT-003 v0.3.0).
 
 Intelligently merges existing user files with new templates.
@@ -115,3 +115,60 @@ class TemplateMerger:
         }
 
         return new_config
+
+    def merge_settings_json(self, template_path: Path, existing_path: Path, backup_path: Path | None = None) -> None:
+        """Smart merge for .claude/settings.json.
+
+        Rules:
+        - env: shallow merge (user variables preserved)
+        - permissions.allow: array merge (deduplicated)
+        - permissions.deny: template priority (security)
+        - hooks: template priority
+
+        Args:
+            template_path: Template settings.json.
+            existing_path: Existing settings.json.
+            backup_path: Backup settings.json (optional, for user settings extraction).
+        """
+        # Load template
+        template_data = json.loads(template_path.read_text(encoding="utf-8"))
+
+        # Load backup or existing for user settings
+        user_data: dict[str, Any] = {}
+        if backup_path and backup_path.exists():
+            user_data = json.loads(backup_path.read_text(encoding="utf-8"))
+        elif existing_path.exists():
+            user_data = json.loads(existing_path.read_text(encoding="utf-8"))
+
+        # Merge env (shallow merge, user variables preserved)
+        merged_env = {**template_data.get("env", {}), **user_data.get("env", {})}
+
+        # Merge permissions.allow (deduplicated array merge)
+        template_allow = set(template_data.get("permissions", {}).get("allow", []))
+        user_allow = set(user_data.get("permissions", {}).get("allow", []))
+        merged_allow = sorted(template_allow | user_allow)
+
+        # permissions.deny: template priority (security)
+        merged_deny = template_data.get("permissions", {}).get("deny", [])
+
+        # permissions.ask: template priority + user additions
+        template_ask = set(template_data.get("permissions", {}).get("ask", []))
+        user_ask = set(user_data.get("permissions", {}).get("ask", []))
+        merged_ask = sorted(template_ask | user_ask)
+
+        # Build final merged settings
+        merged = {
+            "env": merged_env,
+            "hooks": template_data.get("hooks", {}),  # Template priority
+            "permissions": {
+                "defaultMode": template_data.get("permissions", {}).get("defaultMode", "default"),
+                "allow": merged_allow,
+                "ask": merged_ask,
+                "deny": merged_deny
+            }
+        }
+
+        existing_path.write_text(
+            json.dumps(merged, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8"
+        )

moai_adk/core/template/processor.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003.md | Chain: TEMPLATE-001
+# @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)."""
 
 from __future__ import annotations
@@ -267,9 +267,8 @@ class TemplateProcessor:
             dst_folder = dst / folder
 
             if src_folder.exists():
-                # Backup this folder before deletion (safety measure)
+                # Remove existing folder (backup is already handled by create_backup() in update.py)
                 if dst_folder.exists():
-                    self._backup_alfred_folder(dst_folder, folder)
                     shutil.rmtree(dst_folder)
 
                 # Create parent directory if needed
@@ -278,7 +277,7 @@ class TemplateProcessor:
                 if not silent:
                     console.print(f"   ✅ .claude/{folder}/ overwritten")
 
-        # 2. Copy other files/folders individually (FORCE OVERWRITE all files)
+        # 2. Copy other files/folders individually (smart merge for settings.json)
         all_warnings = []
         for item in src.iterdir():
             rel_path = item.relative_to(src)
@@ -289,9 +288,15 @@ class TemplateProcessor:
                 continue
 
             if item.is_file():
-                # FORCE OVERWRITE: Always copy files (no skip)
-                warnings = self._copy_file_with_substitution(item, dst_item)
-                all_warnings.extend(warnings)
+                # Smart merge for settings.json
+                if item.name == "settings.json":
+                    self._merge_settings_json(item, dst_item)
+                    if not silent:
+                        console.print("   🔄 settings.json merged (env variables preserved)")
+                else:
+                    # FORCE OVERWRITE: Always copy other files (no skip)
+                    warnings = self._copy_file_with_substitution(item, dst_item)
+                    all_warnings.extend(warnings)
             elif item.is_dir():
                 # FORCE OVERWRITE: Always copy directories (no skip)
                 self._copy_dir_with_substitution(item, dst_item)
@@ -352,7 +357,7 @@ class TemplateProcessor:
             console.print("   ✅ .moai/ copy complete (variables substituted)")
 
     def _copy_claude_md(self, silent: bool = False) -> None:
-        """Copy CLAUDE.md with FORCE OVERWRITE."""
+        """Copy CLAUDE.md with smart merge (preserves "## 프로젝트 정보" section)."""
         src = self.template_root / "CLAUDE.md"
         dst = self.target_path / "CLAUDE.md"
 
@@ -361,10 +366,16 @@ class TemplateProcessor:
                 console.print("⚠️ CLAUDE.md template not found")
             return
 
-        # FORCE OVERWRITE: Always copy template (backup already created in Phase 1)
-        self._copy_file_with_substitution(src, dst)
-        if not silent:
-            console.print("   ✅ CLAUDE.md overwritten (backup available in .moai-backups/)")
+        # Smart merge: preserve existing "## 프로젝트 정보" section
+        if dst.exists():
+            self._merge_claude_md(src, dst)
+            if not silent:
+                console.print("   🔄 CLAUDE.md merged (프로젝트 정보 preserved)")
+        else:
+            # First time: just copy
+            self._copy_file_with_substitution(src, dst)
+            if not silent:
+                console.print("   ✅ CLAUDE.md created")
 
     def _merge_claude_md(self, src: Path, dst: Path) -> None:
         """Delegate the smart merge for CLAUDE.md.
@@ -375,6 +386,24 @@ class TemplateProcessor:
         """
         self.merger.merge_claude_md(src, dst)
 
+    def _merge_settings_json(self, src: Path, dst: Path) -> None:
+        """Delegate the smart merge for settings.json.
+
+        Args:
+            src: Template settings.json.
+            dst: Project settings.json.
+        """
+        # 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
+
+        self.merger.merge_settings_json(src, dst, backup_path)
+
     def _copy_gitignore(self, silent: bool = False) -> None:
         """.gitignore copy (optional)."""
         src = self.template_root / ".gitignore"