@trac3r/oh-my-god 2.2.11

package/hooks/setup_wizard.py

@@ -0,0 +1,1101 @@
+"""OMG Setup Wizard — interactive CLI detection, auth verification, and MCP configuration.
+
+Feature-gated: requires OMG_SETUP_ENABLED=1 (default off).
+"""
+from __future__ import annotations
+
+import json
+import importlib
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+_HOOKS_DIR = Path(__file__).resolve().parent
+_PROJECT_ROOT = _HOOKS_DIR.parent
+_PORTABLE_RUNTIME_ROOT = _PROJECT_ROOT / "omg-runtime"
+for path in (_HOOKS_DIR, _PROJECT_ROOT, _PORTABLE_RUNTIME_ROOT):
+    path_str = str(path)
+    if path_str not in sys.path:
+        sys.path.insert(0, path_str)
+
+from hooks._common import bootstrap_runtime_paths, get_feature_flag
+
+bootstrap_runtime_paths(__file__)
+
+from runtime.cli_provider import get_provider, list_available_providers  # noqa: E402
+
+# Trigger provider auto-registration on import
+import runtime.providers.codex_provider  # noqa: E402, F401
+import runtime.providers.gemini_provider  # noqa: E402, F401
+import runtime.providers.kimi_provider  # noqa: E402, F401
+import runtime.providers.opencode_provider  # noqa: E402, F401
+from runtime.mcp_config_writers import (  # noqa: E402
+    write_claude_mcp_config,
+    write_claude_mcp_stdio_config,
+    write_codex_mcp_config,
+    write_codex_mcp_stdio_config,
+    write_gemini_mcp_config,
+    write_gemini_mcp_stdio_config,
+    write_kimi_mcp_config,
+    write_kimi_mcp_stdio_config,
+)
+from runtime.plugin_interop import discover_host_plugin_state  # noqa: E402
+from runtime.validate import run_validate as _run_post_install_validate  # noqa: E402
+from runtime.adoption import (  # noqa: E402
+    CANONICAL_MODE_NAMES,
+    CANONICAL_VERSION,
+    PRESET_LEVEL,
+    PRESET_ORDER,
+    build_adoption_report,
+    get_mode_profile,
+    get_preset_features,
+    detect_ecosystems,
+    resolve_preset,
+    write_adoption_report,
+)
+
+_logger = logging.getLogger(__name__)
+
+OMG_CONTROL_COMMAND = "python3"
+OMG_CONTROL_ARGS = ["-m", "runtime.omg_mcp_server"]
+OMG_CONTROL_SERVER_NAME = "omg-control"
+
+_INSTALL_HINTS: dict[str, str] = {
+    "codex": "npm install -g @openai/codex",
+    "gemini": "npm install -g @google/gemini-cli",
+    "kimi": "uv tool install --python 3.13 kimi-cli",
+}
+
+BYPASS_ALL_WARNING = (
+    "⚠️  BYPASS-ALL / FULL VIBE-CODE MODE WARNING ⚠️\n\n"
+    "Enabling bypass-all grants Claude Code unrestricted write access to your filesystem "
+    "without asking for confirmation on individual file edits.\n\n"
+    "IMPORTANT DISCLAIMER: The author takes NO responsibility for any data loss, "
+    "unintended file modifications, or system changes that occur while bypass-all is enabled. "
+    "Use at your own risk.\n\n"
+    "Note: Some safety measures remain active even in bypass-all mode:\n"
+    "  • Firewall deny rules still block dangerous commands (rm -rf, sudo, etc.)\n"
+    "  • Secret-guard still protects credentials and API keys\n"
+    "  • You can disable bypass-all at any time via settings.json\n\n"
+    "Do you want to enable bypass-all mode? (y/N): "
+)
+
+_PRESET_LEVEL = PRESET_LEVEL
+
+MCP_CATALOG: list[dict[str, Any]] = [
+    {
+        "id": "context7",
+        "name": "Context7",
+        "description": "Upstash Context7 MCP server for context management",
+        "command": "npx",
+        "args": ["@upstash/context7-mcp@2.1.3"],
+        "default": False,
+        "min_preset": "balanced",
+        "category": "productivity",
+    },
+    {
+        "id": "filesystem",
+        "name": "Filesystem",
+        "description": "ModelContextProtocol filesystem server for file operations",
+        "command": "npx",
+        "args": ["@modelcontextprotocol/server-filesystem@2026.1.14", "."],
+        "default": True,
+        "min_preset": "safe",
+        "category": "system",
+    },
+    {
+        "id": "websearch",
+        "name": "Web Search",
+        "description": "Web search MCP server for internet queries",
+        "command": "npx",
+        "args": ["@zhafron/mcp-web-search@1.2.2"],
+        "default": False,
+        "min_preset": "interop",
+        "category": "search",
+    },
+    {
+        "id": "chrome-devtools",
+        "name": "Chrome DevTools",
+        "description": "Chrome DevTools MCP server for browser automation",
+        "command": "npx",
+        "args": ["chrome-devtools-mcp@0.19.0"],
+        "default": False,
+        "min_preset": "labs",
+        "category": "browser",
+    },
+    {
+        "id": "omg-memory",
+        "name": "OMG Memory",
+        "description": "OMG shared memory server via HTTP",
+        "command": None,
+        "args": [],
+        "type": "http",
+        "url": "http://127.0.0.1:8765/mcp",
+        "default": False,
+        "min_preset": "interop",
+        "category": "memory",
+    },
+    {
+        "id": OMG_CONTROL_SERVER_NAME,
+        "name": "OMG Control",
+        "description": "OMG control plane MCP server via stdio",
+        "command": OMG_CONTROL_COMMAND,
+        "args": OMG_CONTROL_ARGS,
+        "default": True,
+        "min_preset": "safe",
+        "category": "control",
+    },
+    {
+        "id": "github",
+        "name": "GitHub",
+        "description": "ModelContextProtocol GitHub server for repository operations",
+        "command": "npx",
+        "args": ["@modelcontextprotocol/server-github"],
+        "default": False,
+        "category": "vcs",
+    },
+    {
+        "id": "puppeteer",
+        "name": "Puppeteer",
+        "description": "ModelContextProtocol Puppeteer server for browser automation",
+        "command": "npx",
+        "args": ["@modelcontextprotocol/server-puppeteer"],
+        "default": False,
+        "category": "browser",
+    },
+    {
+        "id": "brave-search",
+        "name": "Brave Search",
+        "description": "ModelContextProtocol Brave Search server",
+        "command": "npx",
+        "args": ["@modelcontextprotocol/server-brave-search"],
+        "default": False,
+        "category": "search",
+    },
+    {
+        "id": "sequential-thinking",
+        "name": "Sequential Thinking",
+        "description": "ModelContextProtocol Sequential Thinking server for reasoning",
+        "command": "npx",
+        "args": ["@modelcontextprotocol/server-sequential-thinking"],
+        "default": False,
+        "category": "reasoning",
+    },
+    {
+        "id": "grep-app",
+        "name": "Grep App",
+        "description": "Grep App MCP server for code search",
+        "command": "npx",
+        "args": ["grep-app-mcp"],
+        "default": False,
+        "category": "search",
+    },
+    {
+        "id": "memory-graph",
+        "name": "Memory Graph",
+        "description": "ModelContextProtocol Memory server for knowledge graphs",
+        "command": "npx",
+        "args": ["@modelcontextprotocol/server-memory"],
+        "default": False,
+        "category": "memory",
+    },
+    {
+        "id": "notebooklm",
+        "name": "NotebookLM",
+        "description": "NotebookLM MCP server for AI-powered research and note-taking",
+        "command": "npx",
+        "args": ["-y", "notebooklm-mcp@latest"],
+        "default": False,
+        "category": "productivity",
+        "warning": (
+            "NOTEBOOKLM MCP WARNING\n\n"
+            "NotebookLM requires browser automation and has several important considerations:\n\n"
+            "BROWSER AUTOMATION: NotebookLM uses Puppeteer for browser automation. "
+            "This requires a Chromium/Chrome installation and may consume significant system resources.\n\n"
+            "FIRST-RUN DOWNLOAD: On first run, NotebookLM will download a full browser instance "
+            "(typically 100-300 MB). This is a one-time operation but may take several minutes.\n\n"
+            "DEDICATED ACCOUNT: It is strongly recommended to use a dedicated Google account "
+            "for NotebookLM MCP. Do NOT use your primary account, as the MCP will store credentials locally.\n\n"
+            "AUTH EXPIRY: Google authentication tokens expire periodically. "
+            "You may need to re-authenticate if the MCP fails with auth errors.\n\n"
+            "Enable NotebookLM only if you understand these requirements and accept the risks."
+        ),
+    },
+]
+
+_MCP_ID_ALIASES: dict[str, str] = {
+    "file-system": "filesystem",
+    "file_system": "filesystem",
+    "grep": "grep-app",
+    "grep_app": "grep-app",
+}
+
+
+def get_mcp_catalog() -> list[dict[str, Any]]:
+    """Return the MCP catalog.
+
+    Returns:
+        List of MCP server definitions with id, name, description, command, args, default, and category.
+    """
+    return MCP_CATALOG
+
+
+def get_default_mcps_for_preset(preset: str) -> list[str]:
+    """Return the list of MCP server IDs enabled by default for *preset*.
+
+    Each catalog entry carries a ``min_preset`` field that specifies the
+    lowest preset tier at which the MCP is included.  The preset order is
+    ``safe < balanced < interop < labs``.
+
+    Returns:
+        Sorted list of MCP server IDs whose ``min_preset`` is at or below
+        the requested *preset* level.
+    """
+    level = _PRESET_LEVEL.get(preset, 0)
+    default_ids = [
+        m["id"]
+        for m in MCP_CATALOG
+        if _PRESET_LEVEL.get(m.get("min_preset", ""), -1) <= level
+        and m.get("min_preset") is not None
+    ]
+    if preset == "buffet" and os.environ.get("OMG_SETUP_ENABLED", "0").strip() != "1":
+        default_ids.append("notebooklm")
+    return default_ids
+
+
+def _normalize_mcp_ids(selected_ids: list[str]) -> list[str]:
+    valid_ids = {cast(str, m["id"]) for m in MCP_CATALOG}
+    normalized_ids: list[str] = []
+    seen: set[str] = set()
+    unknown_ids: list[str] = []
+
+    for raw_id in selected_ids:
+        normalized = _MCP_ID_ALIASES.get(raw_id, raw_id)
+        if normalized not in valid_ids:
+            unknown_ids.append(raw_id)
+            continue
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        normalized_ids.append(normalized)
+
+    if unknown_ids:
+        raise ValueError(
+            "Unsupported MCP server IDs: " + ", ".join(unknown_ids)
+        )
+
+    return normalized_ids
+
+
+def build_mcp_config(selected_ids: list[str]) -> dict[str, Any]:
+    """Build .mcp.json configuration from selected MCP server IDs.
+
+    Args:
+        selected_ids: List of MCP server IDs to include in the config.
+
+    Returns:
+        Dict with 'mcpServers' key containing the MCP server configurations.
+    """
+    normalized_ids = _normalize_mcp_ids(selected_ids)
+    mcp_servers: dict[str, Any] = {}
+
+    for mcp in MCP_CATALOG:
+        if mcp["id"] not in normalized_ids:
+            continue
+
+        mcp_id = mcp["id"]
+
+        # HTTP-type MCPs (like omg-memory)
+        if mcp.get("type") == "http":
+            mcp_servers[mcp_id] = {
+                "type": "http",
+                "url": mcp["url"],
+            }
+        # NPX-type MCPs
+        else:
+            mcp_servers[mcp_id] = {
+                "command": mcp["command"],
+                "args": mcp["args"],
+            }
+
+    return {"mcpServers": mcp_servers}
+
+
+def configure_plan_type(plan_type: str) -> dict[str, Any]:
+    """Configure Claude plan type and model routing.
+
+    Args:
+        plan_type: "max" or "pro"
+
+    Returns:
+        dict with plan_type and optionally model_routing
+    """
+    result: dict[str, Any] = {"plan_type": plan_type}
+    if plan_type == "pro":
+        result["model_routing"] = {
+            "planning": "claude-opus-4-5",
+            "coding": "claude-sonnet-4-5",
+            "review": "claude-opus-4-5",
+            "commit": "claude-haiku-4-5",
+        }
+    return result
+
+
+def select_mcps(selected_ids: list[str] | None = None, preset: str = "safe") -> dict[str, Any]:
+    """Build MCP config from selected IDs.
+
+    Args:
+        selected_ids: List of MCP IDs to include. If None, uses preset defaults.
+        preset: Preset tier that controls which MCPs are included by default.
+
+    Returns:
+        dict with mcpServers key (ready to write as .mcp.json)
+    """
+    if selected_ids is None:
+        selected_ids = get_default_mcps_for_preset(preset)
+    else:
+        selected_ids = _normalize_mcp_ids(selected_ids)
+    return build_mcp_config(selected_ids)
+
+
+def configure_bypass_all(enabled: bool) -> dict[str, Any]:
+    """Configure bypass_all mode.
+
+    Args:
+        enabled: True to enable bypass-all, False to disable
+
+    Returns:
+        dict with enabled status and warning_shown flag
+    """
+    result: dict[str, Any] = {"enabled": enabled}
+    if enabled:
+        result["warning_shown"] = True
+    return result
+
+
+def is_setup_enabled() -> bool:
+    """Check if the setup wizard feature is enabled.
+
+    Uses get_feature_flag("SETUP", default=False) — disabled by default.
+    Enable via OMG_SETUP_ENABLED=1 env var or settings.json._omg.features.SETUP: true.
+    """
+    return get_feature_flag("SETUP", default=False)
+
+
+def detect_clis() -> dict[str, Any]:
+    """Detect installed CLI tools using the provider registry.
+
+    Iterates over all registered providers, calling ``detect()`` and
+    ``check_auth()`` on each.  Returns a dict keyed by provider name::
+
+        {
+            "codex": {"detected": True, "auth_ok": True, "message": "..."},
+            "gemini": {"detected": False, "auth_ok": None,
+                       "message": "Not found. Install: npm install -g @google/gemini-cli"},
+            ...
+        }
+    """
+    results: dict[str, Any] = {}
+    host_config_paths = {
+        "codex": Path.home() / ".codex" / "config.toml",
+        "gemini": Path.home() / ".gemini" / "settings.json",
+        "kimi": Path.home() / ".kimi" / "mcp.json",
+    }
+
+    for name in list_available_providers():
+        provider = get_provider(name)
+        if provider is None:
+            continue
+
+        config_path = host_config_paths.get(name)
+        configured = bool(config_path and config_path.exists())
+
+        try:
+            detected = provider.detect()
+        except Exception as exc:
+            _logger.warning("detect() failed for %s: %s", name, exc)
+            detected = False
+
+        auth_ok: bool | None = None
+        message = ""
+
+        if detected:
+            try:
+                auth_ok, message = provider.check_auth()
+            except Exception as exc:
+                _logger.warning("check_auth() failed for %s: %s", name, exc)
+                auth_ok = None
+                message = f"Auth check error: {exc}"
+        else:
+            hint = _INSTALL_HINTS.get(name, f"Install the '{name}' CLI")
+            message = f"Not found. Install: {hint}"
+            if configured and config_path is not None:
+                message = f"{message} (config detected at {config_path})"
+
+        results[name] = {
+            "detected": detected,
+            "configured": configured,
+            "auth_ok": auth_ok,
+            "message": message,
+        }
+
+    return results
+
+
+def get_cli_auth_instructions(provider: str) -> dict[str, str]:
+    """Return install, auth, and verify instructions for a CLI provider.
+
+    This function returns command strings only — it does NOT execute anything
+    or store credentials.
+
+    Args:
+        provider: CLI provider name (e.g. "codex", "gemini", or "kimi").
+
+    Returns:
+        Dict with keys: install, auth, verify, subscription.
+        Unknown providers return placeholder strings.
+    """
+    instructions: dict[str, dict[str, str]] = {
+        "codex": {
+            "install": "npm install -g @openai/codex",
+            "auth": "codex login",
+            "verify": "codex --version",
+            "subscription": "Requires ChatGPT Plus, Team, or Enterprise subscription (or OpenAI API key)",
+        },
+        "gemini": {
+            "install": "npm install -g @google/gemini-cli",
+            "auth": "gemini auth login",
+            "verify": "gemini --version",
+            "subscription": "Requires Google account with Gemini API access (free tier available)",
+        },
+        "kimi": {
+            "install": "uv tool install --python 3.13 kimi-cli",
+            "auth": "Add token to ~/.kimi/config.toml",
+            "verify": "kimi --version",
+            "subscription": "Requires Kimi API key from platform.moonshot.cn",
+        },
+    }
+
+    return instructions.get(provider, {
+        "install": "Unknown provider",
+        "auth": "Unknown provider",
+        "verify": "Unknown provider",
+        "subscription": "Unknown",
+    })
+
+
+def check_auth() -> dict[str, Any]:
+    """Verify authentication for detected CLI tools.
+
+    Stub — returns pending status. T16 will implement real auth checks
+    using each provider's check_auth() method.
+    """
+    return {"status": "pending", "results": {}}
+
+
+_PROFILE_ARCH_REQUEST_MAX = 8
+_PROFILE_TAG_MAX = 12
+_PROFILE_SUMMARY_MAX_CHARS = 240
+_PROFILE_RECENT_UPDATES_MAX = 5
+_PROFILE_GOVERNED_MAX = 24
+
+
+def get_mode_choices() -> list[str]:
+    return list(CANONICAL_MODE_NAMES)
+
+
+def select_setup_mode(mode: str | None) -> str:
+    candidate = (mode or "").strip().lower()
+    if candidate in CANONICAL_MODE_NAMES:
+        return candidate
+    return "focused"
+
+
+def configure_mcp(
+    project_dir: str,
+    detected_clis: dict[str, Any],
+    server_url: str = "http://127.0.0.1:8765/mcp",
+    server_name: str = "omg-memory",
+    control_command: str = OMG_CONTROL_COMMAND,
+    control_args: list[str] | None = None,
+    control_server_name: str = OMG_CONTROL_SERVER_NAME,
+    preset: str = "safe",
+    selected_ids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Configure OMG MCP servers for authenticated CLIs.
+
+    For each CLI in detected_clis where detected_clis[cli]["detected"] == True,
+    calls the appropriate writer from runtime.mcp_config_writers.
+
+    HTTP memory surfaces are only written when the *preset* is at or above
+    ``interop`` level.  ``safe`` and ``balanced`` presets write only the
+    stdio ``omg-control`` surface.
+
+    Args:
+        project_dir: Path to the project directory.
+        detected_clis: Dict of CLI detection results from detect_clis().
+        server_url: MCP server URL (default: http://127.0.0.1:8765/mcp).
+        server_name: MCP server name (default: omg-memory).
+        control_command: stdio command for the OMG control MCP server.
+        control_args: stdio args for the OMG control MCP server.
+        control_server_name: MCP server name for the OMG control surface.
+        preset: Active preset tier (safe, balanced, interop, labs).
+
+    Returns:
+        Dict with keys:
+        - status: "ok" on success
+        - configured: List of CLI names that were successfully configured
+        - errors: Dict of CLI name → error message for failures
+    """
+    resolved_control_args = list(control_args or OMG_CONTROL_ARGS)
+    selected_config = select_mcps(selected_ids=selected_ids, preset=preset)
+    selected_servers = cast(
+        dict[str, dict[str, Any]],
+        selected_config.get("mcpServers", {}),
+    )
+    install_planner = importlib.import_module("runtime.install_planner")
+    plan = install_planner.compute_install_plan(
+        project_dir=project_dir,
+        detected_clis=detected_clis,
+        preset=preset,
+        mode="focused",
+        selected_ids=selected_ids,
+        server_url=server_url,
+        server_name=server_name,
+        control_command=control_command,
+        control_args=resolved_control_args,
+        control_server_name=control_server_name,
+        selected_servers=selected_servers,
+        source_root=_PROJECT_ROOT,
+    )
+    install_result = cast(dict[str, Any], install_planner.execute_plan(plan))
+
+    configured = [action.host for action in plan.actions if action.host != "claude"]
+    errors: dict[str, str] = {}
+    if install_result["errors"]:
+        joined = "; ".join(install_result["errors"])
+        if not configured:
+            errors["claude"] = joined
+        else:
+            for host in configured:
+                errors[host] = joined
+        configured = []
+
+    return {
+        "status": "ok",
+        "configured": configured,
+        "errors": errors,
+    }
+
+
+def set_preferences(project_dir: str, preferences: dict[str, Any]) -> dict[str, Any]:
+    """Set user preferences for CLI routing and save to .omg/state/cli-config.yaml.
+
+    Args:
+        project_dir: Path to the project directory.
+        preferences: Dict with optional 'cli_configs' key. If empty, uses defaults.
+                    Expected structure:
+                    {
+                        "cli_configs": {
+                            "codex": {"subscription": "free", "max_parallel_agents": 1},
+                            "gemini": {"subscription": "free", "max_parallel_agents": 1},
+                            ...
+                        }
+                    }
+
+    Returns:
+        Dict with keys:
+        - status: "ok" on success
+        - path: Full path to saved config file
+        - config: The saved config dict (version + cli_configs)
+    """
+    # Default config structure
+    default_cli_configs: dict[str, Any] = {
+        "codex": {"subscription": "free", "max_parallel_agents": 1},
+        "gemini": {"subscription": "free", "max_parallel_agents": 1},
+        "kimi": {"subscription": "free", "max_parallel_agents": 1},
+    }
+    preset = resolve_preset(cast(str, preferences.get("preset") or "safe"))
+    default_config: dict[str, Any] = {
+        "version": CANONICAL_VERSION,
+        "preset": preset,
+        "resolved_features": get_preset_features(preset),
+        "cli_configs": default_cli_configs,
+        "detected_clis": {},
+        "selected_mcps": get_default_mcps_for_preset(preset),
+        "browser_capability": {"enabled": False},
+    }
+
+    # Merge custom preferences if provided
+    if preferences and isinstance(preferences, dict):
+        cli_configs = preferences.get("cli_configs")
+        if isinstance(cli_configs, dict):
+            default_cli_configs.update(cast(dict[str, Any], cli_configs))
+        selected_mcps = preferences.get("selected_mcps")
+        if isinstance(selected_mcps, list):
+            default_config["selected_mcps"] = _normalize_mcp_ids(
+                [str(item) for item in selected_mcps]
+            )
+        browser_capability = preferences.get("browser_capability")
+        if isinstance(browser_capability, dict):
+            default_config["browser_capability"] = {
+                "enabled": bool(browser_capability.get("enabled", False))
+            }
+        install_planner = importlib.import_module("runtime.install_planner")
+        normalize_detected = cast(
+            Any,
+            getattr(install_planner, "normalize_detected_clis", None),
+        )
+        if callable(normalize_detected):
+            raw_detected_clis = preferences.get("detected_clis")
+            normalized_detected_clis = cast(dict[str, Any], normalize_detected(raw_detected_clis))
+            persisted_detected: dict[str, Any] = {}
+            for host, host_state in normalized_detected_clis.items():
+                if not isinstance(host_state, dict):
+                    continue
+                persisted_detected[host] = {
+                    "installed": bool(host_state.get("detected", False)),
+                    "configured": bool(host_state.get("configured", False)),
+                }
+            default_config["detected_clis"] = persisted_detected
+
+    _write_project_settings_preset(project_dir, preset)
+
+    # Create .omg/state directory if needed
+    state_dir = os.path.join(project_dir, ".omg", "state")
+    os.makedirs(state_dir, exist_ok=True)
+
+    _write_profile_learning_sections(state_dir, preferences)
+
+    # Write config to YAML file
+    config_path = os.path.join(state_dir, "cli-config.yaml")
+    with open(config_path, "w") as f:
+        yaml.dump(default_config, f, default_flow_style=False, sort_keys=False)
+
+    _logger.info("Saved CLI config to %s", config_path)
+
+    return {
+        "status": "ok",
+        "path": config_path,
+        "config": default_config,
+    }
+
+
+def _write_profile_learning_sections(state_dir: str, preferences: dict[str, Any]) -> None:
+    profile_path = os.path.join(state_dir, "profile.yaml")
+    profile_data = _load_profile_yaml(profile_path)
+    _ensure_profile_baseline(profile_data)
+
+    profile_data["preferences"] = _normalize_preferences_block(preferences.get("preferences"))
+    profile_data["user_vector"] = _normalize_user_vector_block(preferences.get("user_vector"))
+    profile_data["profile_provenance"] = _normalize_provenance_block(preferences.get("profile_provenance"))
+    profile_data["governed_preferences"] = _normalize_governed_preferences_block(preferences.get("governed_preferences"))
+
+    from runtime.profile_io import save_profile
+    save_profile(profile_path, profile_data)
+
+
+def _render_explicit_empty_collections(dumped: str) -> str:
+    lines = dumped.splitlines()
+    output: list[str] = []
+
+    def _next_line(start: int) -> str:
+        if start + 1 < len(lines):
+            return lines[start + 1]
+        return ""
+
+    for idx, line in enumerate(lines):
+        next_line = _next_line(idx)
+        stripped = line.strip()
+
+        if stripped == "stack:" and (not next_line or not next_line.startswith("- ")):
+            output.append("stack: []")
+            continue
+        if stripped == "conventions:" and (not next_line or not next_line.startswith("  ")):
+            output.append("conventions: {}")
+            continue
+        if stripped == "ai_behavior:" and (not next_line or not next_line.startswith("  ")):
+            output.append("ai_behavior: {}")
+            continue
+        if stripped == "architecture_requests:" and (not next_line or not next_line.startswith("    - ")):
+            output.append("  architecture_requests: []")
+            continue
+        if stripped == "constraints:" and (not next_line or not next_line.startswith("    ")):
+            output.append("  constraints: {}")
+            continue
+        if stripped == "tags:" and (not next_line or not next_line.startswith("    - ")):
+            output.append("  tags: []")
+            continue
+        if stripped == "recent_updates:" and (not next_line or not next_line.startswith("    - ")):
+            output.append("  recent_updates: []")
+            continue
+
+        output.append(line)
+
+    return "\n".join(output) + "\n"
+
+
+def _load_profile_yaml(profile_path: str) -> dict[str, Any]:
+    from runtime.profile_io import load_profile
+    return load_profile(profile_path)
+
+
+def _ensure_profile_baseline(profile_data: dict[str, Any]) -> None:
+    profile_data.setdefault("name", "omg-project")
+    profile_data.setdefault("description", "initialized by OMG standalone compat bootstrap")
+    profile_data.setdefault("language", "unknown")
+    profile_data.setdefault("framework", "unknown")
+    profile_data.setdefault("stack", [])
+    profile_data.setdefault("conventions", {})
+    profile_data.setdefault("ai_behavior", {})
+    profile_data.setdefault("governed_preferences", {"style": [], "safety": []})
+
+
+def _normalize_preferences_block(raw: Any) -> dict[str, Any]:
+    block = raw if isinstance(raw, dict) else {}
+
+    requests_obj = block.get("architecture_requests")
+    architecture_requests: list[str] = []
+    if isinstance(requests_obj, list):
+        for value in requests_obj:
+            text = str(value).strip()
+            if text:
+                architecture_requests.append(text)
+            if len(architecture_requests) >= _PROFILE_ARCH_REQUEST_MAX:
+                break
+
+    constraints_obj = block.get("constraints")
+    constraints: dict[str, Any] = {}
+    if isinstance(constraints_obj, dict):
+        for key, value in constraints_obj.items():
+            normalized_key = _normalize_constraint_key(str(key))
+            normalized_value = _normalize_constraint_value(value)
+            if normalized_key and normalized_value is not None:
+                constraints[normalized_key] = normalized_value
+
+    routing_obj = block.get("routing")
+    routing_map = routing_obj if isinstance(routing_obj, dict) else {}
+    routing = {
+        "prefer_clarification": bool(routing_map.get("prefer_clarification", False)),
+    }
+
+    return {
+        "architecture_requests": architecture_requests,
+        "constraints": constraints,
+        "routing": routing,
+    }
+
+
+def _normalize_constraint_key(value: str) -> str:
+    normalized = value.strip().lower()
+    normalized = re.sub(r"\s+", "_", normalized)
+    normalized = re.sub(r"[^a-z0-9_]+", "", normalized)
+    return normalized
+
+
+def _normalize_constraint_value(value: Any) -> str | int | float | bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return value
+    if value is None:
+        return None
+    text = str(value).strip().lower()
+    return text if text else None
+
+
+def _normalize_user_vector_block(raw: Any) -> dict[str, Any]:
+    block = raw if isinstance(raw, dict) else {}
+
+    tags_obj = block.get("tags")
+    tags: list[str] = []
+    if isinstance(tags_obj, list):
+        for value in tags_obj:
+            token = _normalize_tag_token(str(value))
+            if token:
+                tags.append(token)
+            if len(tags) >= _PROFILE_TAG_MAX:
+                break
+
+    summary = ""
+    summary_obj = block.get("summary")
+    if isinstance(summary_obj, str):
+        summary = " ".join(summary_obj.strip().split())[:_PROFILE_SUMMARY_MAX_CHARS]
+
+    confidence = 0.0
+    confidence_obj = block.get("confidence")
+    if isinstance(confidence_obj, (int, float, str)):
+        try:
+            confidence = float(confidence_obj)
+        except (TypeError, ValueError):
+            confidence = 0.0
+    confidence = max(0.0, min(1.0, confidence))
+
+    return {
+        "tags": tags,
+        "summary": summary,
+        "confidence": confidence,
+    }
+
+
+def _normalize_tag_token(value: str) -> str:
+    normalized = value.strip().lower()
+    normalized = re.sub(r"\s+", "_", normalized)
+    normalized = re.sub(r"[^a-z0-9_\-]+", "", normalized)
+    return normalized
+
+
+def _normalize_provenance_block(raw: Any) -> dict[str, Any]:
+    block = raw if isinstance(raw, dict) else {}
+    updates_obj = block.get("recent_updates")
+    updates: list[dict[str, str]] = []
+    if isinstance(updates_obj, list):
+        for entry in updates_obj:
+            if not isinstance(entry, dict):
+                continue
+            run_id = str(entry.get("run_id", "")).strip()
+            source = str(entry.get("source", "")).strip()
+            field = str(entry.get("field", "")).strip()
+            updated_at = str(entry.get("updated_at", "")).strip()
+            if not (run_id and source and field and updated_at):
+                continue
+            updates.append(
+                {
+                    "run_id": run_id,
+                    "source": source,
+                    "field": field,
+                    "updated_at": updated_at,
+                }
+            )
+            if len(updates) >= _PROFILE_RECENT_UPDATES_MAX:
+                break
+    return {"recent_updates": updates}
+
+
+def _normalize_governed_preferences_block(raw: Any) -> dict[str, list[dict[str, Any]]]:
+    block = raw if isinstance(raw, dict) else {}
+    style_raw = block.get("style")
+    safety_raw = block.get("safety")
+    return {
+        "style": _normalize_governed_section_entries(style_raw, section="style"),
+        "safety": _normalize_governed_section_entries(safety_raw, section="safety"),
+    }
+
+
+def _normalize_governed_section_entries(raw: Any, *, section: str) -> list[dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    entries: list[dict[str, Any]] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        field = str(item.get("field", "")).strip()
+        value = " ".join(str(item.get("value", "")).strip().split())
+        source = str(item.get("source", "")).strip()
+        learned_at = str(item.get("learned_at", "")).strip()
+        updated_at = str(item.get("updated_at", "")).strip()
+        candidate_section = str(item.get("section", section)).strip().lower()
+        confirmation_state = str(item.get("confirmation_state", "")).strip().lower()
+
+        if not (field and value and source and learned_at and updated_at):
+            continue
+        if candidate_section != section:
+            continue
+        if confirmation_state not in ("confirmed", "pending_confirmation", "inferred"):
+            continue
+
+        entry: dict[str, Any] = {
+            "field": field,
+            "value": value,
+            "source": source,
+            "learned_at": learned_at,
+            "updated_at": updated_at,
+            "section": section,
+            "confirmation_state": confirmation_state,
+        }
+
+        if section == "style" and confirmation_state == "inferred":
+            decay_raw = item.get("decay_metadata")
+            decay = decay_raw if isinstance(decay_raw, dict) else {}
+            try:
+                score = float(decay.get("decay_score", 0.0))
+            except (TypeError, ValueError):
+                score = 0.0
+            entry["decay_metadata"] = {
+                "decay_score": max(0.0, min(1.0, score)),
+                "last_seen_at": str(decay.get("last_seen_at", updated_at)).strip() or updated_at,
+                "decay_reason": str(decay.get("decay_reason", "inferred_signal")).strip() or "inferred_signal",
+            }
+
+        entries.append(entry)
+        if len(entries) >= _PROFILE_GOVERNED_MAX:
+            break
+    return entries
+
+
+def _write_project_settings_preset(project_dir: str, preset: str) -> None:
+    """Persist preset metadata into project settings when settings.json exists."""
+    settings_path = os.path.join(project_dir, "settings.json")
+    if not os.path.exists(settings_path):
+        return
+
+    try:
+        with open(settings_path, "r", encoding="utf-8") as f:
+            settings = json.load(f)
+    except Exception:
+        return
+
+    if not isinstance(settings, dict):
+        return
+
+    omg = settings.get("_omg")
+    if not isinstance(omg, dict):
+        omg = {}
+    features = omg.get("features")
+    if not isinstance(features, dict):
+        features = {}
+
+    features.update(get_preset_features(preset))
+    omg["features"] = features
+    omg["preset"] = preset
+    omg["_version"] = CANONICAL_VERSION
+    settings["_omg"] = omg
+
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=2, ensure_ascii=True)
+        f.write("\n")
+
+
+def run_setup_wizard(
+    project_dir: str,
+    non_interactive: bool = False,
+    *,
+    mode: str | None = None,
+    setup_mode: str | None = None,
+    adopt: str = "auto",
+    preset: str | None = None,
+    selected_mcps: list[str] | None = None,
+    browser_enabled: bool = False,
+) -> dict[str, Any]:
+    """Run the OMG setup wizard.
+
+    Args:
+        project_dir: Path to the project directory.
+        non_interactive: If True, skip prompts and use defaults (for CI).
+        mode: Optional adoption mode override (`omg-only` or `coexist`).
+        adopt: Adoption detection mode (currently only `auto` is meaningful).
+        preset: Optional preset override.
+
+    Returns:
+        Dict with wizard results including status and step outcomes.
+        If feature is disabled, returns {"status": "disabled", "message": "..."}.
+    """
+    if not is_setup_enabled():
+        return {
+            "status": "disabled",
+            "message": "Setup wizard disabled. Set OMG_SETUP_ENABLED=1 to enable.",
+        }
+
+    selected_preset = resolve_preset(preset or ("balanced" if non_interactive else "safe"))
+    selected_setup_mode = select_setup_mode(setup_mode)
+    requested_mode = mode
+    if requested_mode is None and non_interactive:
+        detected = detect_ecosystems(project_dir)
+        if not detected:
+            requested_mode = "omg-only"
+
+    adoption = build_adoption_report(
+        project_dir,
+        requested_mode=requested_mode,
+        preset=selected_preset,
+        adopt=adopt,
+    )
+    foreign_plugins_discovered = 0
+    if adoption.get("selected_mode") == "coexist" or selected_preset == "interop":
+        host_plugin_state = discover_host_plugin_state(project_dir)
+        foreign_plugins_discovered = len(host_plugin_state.records)
+    adoption["foreign_plugins_discovered"] = foreign_plugins_discovered
+
+    clis = detect_clis()
+    auth = check_auth()
+    mcp = configure_mcp(project_dir, clis, preset=selected_preset, selected_ids=selected_mcps)
+    prefs = set_preferences(
+        project_dir,
+        {
+            "preset": selected_preset,
+            "selected_mcps": selected_mcps,
+            "browser_capability": {"enabled": browser_enabled},
+            "detected_clis": clis,
+        },
+    )
+    report_path = write_adoption_report(project_dir, adoption)
+    adoption["report_path"] = report_path
+
+    result: dict[str, Any] = {
+        "status": "complete",
+        "setup_mode": {
+            "choices": get_mode_choices(),
+            "selected": selected_setup_mode,
+            "profile": get_mode_profile(selected_setup_mode),
+        },
+        "clis_detected": clis,
+        "auth_status": auth,
+        "mcp_configured": mcp,
+        "preferences": prefs,
+        "adoption": adoption,
+    }
+
+    # --- Post-install validation (runs AFTER all setup writes are complete) ---
+    try:
+        validation_result = _run_post_install_validate(root_dir=Path(project_dir))
+    except Exception as exc:
+        validation_result = {
+            "schema": "ValidateResult",
+            "status": "fail",
+            "checks": [
+                {
+                    "name": "validation_error",
+                    "status": "blocker",
+                    "message": str(exc),
+                    "required": True,
+                },
+            ],
+            "version": "",
+        }
+
+    # Persist machine-readable validation artifact
+    artifact_dir = os.path.join(project_dir, ".omg", "state")
+    os.makedirs(artifact_dir, exist_ok=True)
+    artifact_path = os.path.join(artifact_dir, "post-install-validation.json")
+    try:
+        with open(artifact_path, "w", encoding="utf-8") as f:
+            json.dump(validation_result, f, indent=2, ensure_ascii=True)
+            f.write("\n")
+    except OSError:
+        artifact_path = ""
+
+    checks = validation_result.get("checks", [])
+    blockers = [
+        c
+        for c in checks
+        if isinstance(c, dict) and c.get("status") == "blocker"
+    ]
+
+    result["post_install_validation"] = {
+        "status": validation_result.get("status", "fail"),
+        "artifact_path": artifact_path,
+        "blockers": [{"name": c["name"], "message": c["message"]} for c in blockers],
+    }
+
+    has_detected_cli = any(bool(v.get("detected", False)) for v in clis.values() if isinstance(v, dict))
+    if blockers and not non_interactive and not has_detected_cli:
+        result["status"] = "validation_failed"
+
+    return result