feat: introduce MCP server, cross-platform runtime, and Showcase UI reorganization

- Showcase UI Reorganization:
  * Move web UI dashboard from root directory into apps/showcase_ui/ for cleaner project structure
  * Add 'artemis ui' CLI command (artemis/interfaces/cli/commands/ui.py) and launcher scripts for the interactive showcase console
- Standalone MCP Server & Notifiers (mcp_server/):
  * Implement dedicated MCP server package with mobile automation tools (device_state, inspect_trace, task_manager, task_runner)
  * Add multi-channel notifiers (AgentAPI, Desktop notifications, Webhooks, File output, and Composite routing)
  * Introduce background task runner and trace store for autonomous mobile execution monitoring
- Cross-Platform Runtime & Toolchain Support:
  * Add artemis/platform/ with OS-specific implementations for Linux, macOS (Darwin), and Windows
  * Add artemis/runtime/supervisor.py for resilient process and agent runtime supervision
  * Add artemis/toolchain/ with dependency resolution and SDK descriptors
  * Add cross-platform launcher scripts (start.sh, start.bat) and installer scripts (scripts/install_deps.*)
- Core Enhancements & Diagnostics:
  * Enhance coordinate normalization, OCR API fallback, and perception pipeline
  * Add credential validation (credentials_validator.py) and system diagnostics
  * Update bilingual documentation (README.md, README_CN.md) and architecture diagrams
- Test Suite Expansion:
  * Add integration tests for cloud gateway, remote ADB, and Artemis login
  * Add unit tests covering core diagnostics, platform detection, toolchain, credentials validator, optional OCR, and MCP tools

artemis/config/agent.py

@@ -18,7 +18,7 @@ import os
 from pathlib import Path
 from typing import Any
 
-from pydantic import AliasChoices, BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, model_validator
 
 from artemis.config.constants import (
     AGENT_CONFIG_FILENAME,
@@ -289,7 +289,6 @@ class AgentGlobalConfig(BaseModel):
     denylisted_tools: dict[str, list[str]] = Field(
         default_factory=dict,
         description="List of denylisted tools per agent.",
-        validation_alias=AliasChoices("denylisted_tools", "blocklisted_tools"),
     )
     video_analyzer: VideoAnalyzerConfig = Field(
         default_factory=VideoAnalyzerConfig,

artemis/config/core/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Artemis unified configuration core."""
+
+from artemis.config.core.engine import CascadingConfigEngine, config_engine
+from artemis.config.core.interpolator import interpolate_config_value
+
+__all__ = [
+    "CascadingConfigEngine",
+    "config_engine",
+    "interpolate_config_value",
+]

artemis/config/core/engine.py

@@ -0,0 +1,118 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Multi-source Cascading Configuration Engine."""
+
+import json
+from pathlib import Path
+import re
+from typing import Any
+
+from dotenv import load_dotenv
+
+from artemis.config.core.interpolator import interpolate_config_value
+from artemis.platform import platform
+from artemis.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _strip_json_comments(text: str) -> str:
+    """Strip // and /* */ comments from JSONC text while preserving string literals."""
+    pattern = r'//.*?$|/\*.*?\*/|\'(?:\\.|[^\\\'])*\'|"(?:\\.|[^\\"])*"'
+
+    def replacer(match: re.Match) -> str:
+        s = match.group(0)
+        if s.startswith("/"):
+            return ""
+        return s
+
+    return re.sub(pattern, replacer, text, flags=re.DOTALL | re.MULTILINE)
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively deep merge two dictionaries."""
+    merged = base.copy()
+    for key, value in override.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+class CascadingConfigEngine:
+    """Manages 5-tier configuration hierarchy with automatic cascade and interpolation."""
+
+    def __init__(self, workspace_root: Path | None = None):
+        self.workspace_root = workspace_root or Path.cwd()
+        self._load_environment_files()
+
+    def _load_environment_files(self) -> None:
+        """Load .env files from global config dir and workspace root."""
+        # 1. Global user .env
+        global_env = platform.paths.config_dir / ".env"
+        if global_env.exists():
+            load_dotenv(dotenv_path=global_env, override=False, encoding="utf-8")
+
+        # 2. Legacy ~/.artemis/.env fallback
+        legacy_env = platform.paths.data_dir / ".env"
+        if legacy_env.exists() and legacy_env != global_env:
+            load_dotenv(dotenv_path=legacy_env, override=False, encoding="utf-8")
+
+        # 3. Workspace .env
+        ws_env = self.workspace_root / ".env"
+        if ws_env.exists():
+            load_dotenv(dotenv_path=ws_env, override=True, encoding="utf-8")
+
+    def load_raw_config(
+        self,
+        cli_overrides: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Load and merge all config layers into a unified dictionary."""
+        config: dict[str, Any] = {}
+
+        # Tier 1: Global user configuration ($CONFIG_DIR/artemis.jsonc)
+        global_config_path = platform.paths.config_dir / "artemis.jsonc"
+        if global_config_path.exists():
+            try:
+                raw_text = global_config_path.read_text(encoding="utf-8")
+                cleaned = _strip_json_comments(raw_text)
+                config = _deep_merge(config, json.loads(cleaned))
+            except Exception as e:
+                logger.warning(f"Failed to load global config {global_config_path}: {e}")
+
+        # Tier 2: Workspace project configuration (config/artemis.jsonc)
+        ws_config_path = self.workspace_root / "config" / "artemis.jsonc"
+        if not ws_config_path.exists():
+            ws_config_path = self.workspace_root / "artemis.jsonc"
+
+        if ws_config_path.exists():
+            try:
+                raw_text = ws_config_path.read_text(encoding="utf-8")
+                cleaned = _strip_json_comments(raw_text)
+                config = _deep_merge(config, json.loads(cleaned))
+            except Exception as e:
+                logger.warning(f"Failed to load workspace config {ws_config_path}: {e}")
+
+        # Tier 3: CLI overrides
+        if cli_overrides:
+            config = _deep_merge(config, cli_overrides)
+
+        # Apply variable interpolation across merged dictionary
+        interpolated = interpolate_config_value(config, workspace_root=self.workspace_root)
+        return interpolated
+
+
+config_engine = CascadingConfigEngine()

artemis/config/core/interpolator.py

@@ -0,0 +1,78 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Dynamic configuration variable interpolation engine (${env:VAR}, ${path:NAME})."""
+
+import os
+from pathlib import Path
+import re
+from typing import Any
+
+from artemis.platform import platform
+
+_VAR_PATTERN = re.compile(r"\$\{([^}]+)\}")
+
+
+def _resolve_variable(expr: str, workspace_root: Path | None = None) -> str:
+    """Resolve a single ${namespace:key:-default} expression."""
+    expr = expr.strip()
+    namespace, _, rest = expr.partition(":")
+    if not rest:
+        # Defaults to environment variable lookup
+        return os.getenv(namespace, f"${{{expr}}}")
+
+    key, _, default = rest.partition(":-")
+
+    if namespace == "env":
+        return os.getenv(key, default)
+    elif namespace == "path":
+        paths = platform.paths
+        if key == "config_dir":
+            return str(paths.config_dir)
+        elif key == "data_dir":
+            return str(paths.data_dir)
+        elif key == "cache_dir":
+            return str(paths.cache_dir)
+        elif key == "logs_dir":
+            return str(paths.logs_dir)
+        elif key == "temp_dir":
+            return str(paths.temp_dir())
+        elif key == "workspace_root" or key == "root_dir":
+            return str(workspace_root or Path.cwd())
+        return default or f"${{{expr}}}"
+    elif namespace == "platform":
+        if key == "os_type":
+            return platform.os_type.value
+        elif key == "path_sep":
+            return platform.process.path_separator
+        return default or f"${{{expr}}}"
+
+    return os.getenv(expr, default or f"${{{expr}}}")
+
+
+def interpolate_config_value(val: Any, workspace_root: Path | None = None) -> Any:
+    """Recursively interpolate strings, lists, and dicts containing ${...} variables."""
+    if isinstance(val, str):
+        if "${" not in val:
+            return val
+
+        def replacer(match: re.Match) -> str:
+            return _resolve_variable(match.group(1), workspace_root)
+
+        return _VAR_PATTERN.sub(replacer, val)
+    elif isinstance(val, dict):
+        return {k: interpolate_config_value(v, workspace_root) for k, v in val.items()}
+    elif isinstance(val, list):
+        return [interpolate_config_value(item, workspace_root) for item in val]
+    return val

artemis/config/llm.py

@@ -227,10 +227,10 @@ def _expand_default_into_nodes(config_dict: dict) -> dict:
         "default",
         {
             "provider": "google",
-            "model": "gemini-3.6-flash",
+            "model": "gemini-3.7-flash",
             "fallback": {
                 "provider": "google",
-                "model": "gemini-3.5-flash",
+                "model": "gemini-3.6-flash",
             },
         },
     )

artemis/config/paths.py

@@ -27,6 +27,7 @@ from artemis.config.constants import (
     IPC_PORT_FILENAME,
     LS_ADDRESS_FILENAME,
 )
+from artemis.platform import platform
 
 # Project root directory (3 levels up from artemis/config/paths.py)
 ROOT_DIR = Path(__file__).resolve().parent.parent.parent
@@ -43,22 +44,10 @@ def get_app_dir() -> Path:
 
     Order of precedence:
     1. ARTEMIS_APP_DIR or ANTIGRAVITY_APP_DIR environment variable.
-    2. Legacy ~/.gemini/jetski directory if it exists.
-    3. Default ~/.artemis directory.
+    2. Legacy ~/.gemini/jetski or ~/.artemis directory if it exists.
+    3. OS-standard data directory via Platform Abstraction Layer (PAL).
     """
-    env_dir = os.getenv(ENV_ARTEMIS_APP_DIR) or os.getenv(ENV_ANTIGRAVITY_APP_DIR)
-    if env_dir:
-        path = Path(env_dir)
-        path.mkdir(parents=True, exist_ok=True)
-        return path
-
-    legacy_dir = Path(os.path.expanduser("~/.gemini/jetski"))
-    if legacy_dir.exists():
-        return legacy_dir
-
-    default_dir = Path(os.path.expanduser("~/.artemis"))
-    default_dir.mkdir(parents=True, exist_ok=True)
-    return default_dir
+    return platform.paths.resolve_app_dir()
 
 
 def get_default_traces_path() -> Path:
@@ -97,10 +86,7 @@ def get_temp_dir(subfolder: str | None = None) -> Path:
     Returns:
         Path object pointing to the initialized temporary directory.
     """
-    base_temp = get_app_dir() / "temp"
-    target_dir = base_temp / subfolder if subfolder else base_temp
-    target_dir.mkdir(parents=True, exist_ok=True)
-    return target_dir
+    return platform.paths.temp_dir(subfolder)
 
 
 def get_data_engine_db_path() -> Path:
@@ -132,7 +118,7 @@ def get_config_path(filename: str, default_bundled_path: Path | None = None) ->
     2. Central `config/` directory: `<ROOT_DIR>/config/<filename>`
     3. Project root directory: `<ROOT_DIR>/<filename>`
     4. Custom default bundled path (if provided and exists)
-    5. User application directory: `<APP_DIR>/<filename>`
+    5. User application/config directory via PAL: `<CONFIG_DIR>/<filename>` or `<APP_DIR>/<filename>`
     """
     env_var = f"ARTEMIS_{filename.upper().replace('.', '_').replace('-', '_')}"
     env_path_str = os.getenv(env_var)
@@ -155,6 +141,11 @@ def get_config_path(filename: str, default_bundled_path: Path | None = None) ->
     if default_bundled_path and default_bundled_path.exists():
         return default_bundled_path
 
+    # Check user PAL config directory
+    pal_config_path = platform.paths.config_dir / filename
+    if pal_config_path.exists():
+        return pal_config_path
+
     # Check user app directory
     app_dir_path = get_app_dir() / filename
     if app_dir_path.exists():

artemis/config/settings.py

@@ -27,17 +27,21 @@ from artemis.config.constants import (
     DEFAULT_EXPLORER_VERSION,
     DEFAULT_MODEL,
     DEFAULT_PROFILE,
+    ENV_ANTHROPIC_API_KEY,
     ENV_DATA_ENGINE_DB_PATH,
     ENV_GCP_API_KEY,
     ENV_GEMINI_API_KEY,
     ENV_GOOGLE_API_KEY,
+    ENV_OCR_API_KEY,
     ENV_OPEN_ROUTER_API_KEY,
     ENV_OPENAI_API_KEY,
+    ENV_VISION_API_KEY,
     ENV_XAI_API_KEY,
     ExplorerVersion,
 )
 from artemis.config.paths import (
     GLOBAL_APP_DIR,
+    ROOT_DIR,
     get_app_dir,
     get_data_engine_db_path,
     get_default_traces_path,
@@ -45,16 +49,48 @@ from artemis.config.paths import (
 )
 from artemis.utils.logger import get_logger
 
-# Load environment configuration from app dir if present, else current working dir
+# Load environment configuration from workspace root dir and app dir if present
+load_dotenv(dotenv_path=ROOT_DIR / ".env", verbose=True)
 _global_env = GLOBAL_APP_DIR / ".env"
-if _global_env.exists():
+if _global_env.exists() and _global_env.resolve() != (ROOT_DIR / ".env").resolve():
     load_dotenv(dotenv_path=_global_env, verbose=True)
-else:
-    load_dotenv(verbose=True)
 
 logger = get_logger(__name__)
 
 
+def is_placeholder_key(val: str | SecretStr | None) -> bool:
+    """Check if an API credential is empty or an unconfigured placeholder value."""
+    if val is None:
+        return True
+    raw_str = val.get_secret_value() if isinstance(val, SecretStr) else str(val)
+    raw_str = raw_str.strip().lower()
+    if not raw_str:
+        return True
+    if raw_str in (
+        "api_key",
+        "your_api_key",
+        "your_api_key_here",
+        "your_gemini_api_key_here",
+        "your_google_cloud_vision_api_key_here",
+        "your_openai_api_key_here",
+        "your_anthropic_api_key_here",
+        "your_openrouter_api_key_here",
+        "your_xai_api_key_here",
+        "none",
+        "empty",
+        "null",
+        "undefined",
+    ):
+        return True
+    if (
+        (raw_str.startswith("your_") and raw_str.endswith("_here"))
+        or (raw_str.startswith("<") and raw_str.endswith(">"))
+        or (raw_str.startswith("[") and raw_str.endswith("]"))
+    ):
+        return True
+    return False
+
+
 class Settings(BaseSettings):
     """Centralized ARTEMIS runtime settings loaded from environment and .env files."""
 
@@ -104,7 +140,24 @@ class Settings(BaseSettings):
 
     @model_validator(mode="after")
     def fallback_api_keys(self) -> "Settings":
-        """Normalize Google / Gemini / GCP and OCR API keys for seamless interoperability."""
+        """Normalize Google / Gemini / GCP and OCR API keys and filter placeholders."""
+        # Sanitize any placeholder values loaded from environment or .env
+        for attr in (
+            "OPENAI_API_KEY",
+            "GOOGLE_API_KEY",
+            "GEMINI_API_KEY",
+            "GCP_API_KEY",
+            "ANTHROPIC_API_KEY",
+            "XAI_API_KEY",
+            "OPEN_ROUTER_API_KEY",
+            "OCR_API_KEY",
+            "VISION_API_KEY",
+            "API_KEY",
+        ):
+            val = getattr(self, attr, None)
+            if val and is_placeholder_key(val):
+                setattr(self, attr, None)
+
         if not self.GOOGLE_API_KEY:
             if self.GEMINI_API_KEY:
                 self.GOOGLE_API_KEY = self.GEMINI_API_KEY
@@ -112,13 +165,8 @@ class Settings(BaseSettings):
                 self.GOOGLE_API_KEY = self.GCP_API_KEY
 
         # Fallback for OCR & Vision API keys
-        if not self.OCR_API_KEY:
-            if self.VISION_API_KEY:
-                self.OCR_API_KEY = self.VISION_API_KEY
-            elif self.API_KEY:
-                self.OCR_API_KEY = self.API_KEY
-        if not self.API_KEY and self.OCR_API_KEY:
-            self.API_KEY = self.OCR_API_KEY
+        if not self.OCR_API_KEY and self.VISION_API_KEY:
+            self.OCR_API_KEY = self.VISION_API_KEY
         return self
 
     def get_api_key(self, provider: str) -> SecretStr | None:
@@ -131,18 +179,22 @@ class Settings(BaseSettings):
             SecretStr containing the API key or None if not configured.
         """
         provider_lower = provider.lower()
+        key: SecretStr | None = None
         if provider_lower in ("google", "gemini", "vertexai"):
-            return self.GOOGLE_API_KEY or self.GEMINI_API_KEY or self.GCP_API_KEY
+            key = self.GOOGLE_API_KEY or self.GEMINI_API_KEY or self.GCP_API_KEY
         elif provider_lower in ("ocr", "vision", "google_vision"):
-            return self.OCR_API_KEY or self.VISION_API_KEY or self.API_KEY or self.GOOGLE_API_KEY
+            key = self.OCR_API_KEY or self.VISION_API_KEY
         elif provider_lower == "openai":
-            return self.OPENAI_API_KEY
-        elif provider_lower == "anthropic":
-            return self.ANTHROPIC_API_KEY
+            key = self.OPENAI_API_KEY
+        elif provider_lower in ("anthropic", "claude"):
+            key = self.ANTHROPIC_API_KEY
         elif provider_lower == "openrouter":
-            return self.OPEN_ROUTER_API_KEY
-        elif provider_lower == "xai":
-            return self.XAI_API_KEY
+            key = self.OPEN_ROUTER_API_KEY
+        elif provider_lower in ("xai", "grok"):
+            key = self.XAI_API_KEY
+
+        if key and not is_placeholder_key(key):
+            return key
         return None
 
     def set_api_key(self, provider: str, key: str, persist_to_env: bool = False) -> None:
@@ -161,7 +213,7 @@ class Settings(BaseSettings):
             self.GOOGLE_API_KEY = secret
             self.GEMINI_API_KEY = secret
             self.GCP_API_KEY = secret
-            env_key_name = ENV_GOOGLE_API_KEY
+            env_key_name = ENV_GEMINI_API_KEY
             os.environ[ENV_GOOGLE_API_KEY] = key
             os.environ[ENV_GEMINI_API_KEY] = key
             os.environ[ENV_GCP_API_KEY] = key
@@ -169,6 +221,10 @@ class Settings(BaseSettings):
             self.OPENAI_API_KEY = secret
             env_key_name = ENV_OPENAI_API_KEY
             os.environ[ENV_OPENAI_API_KEY] = key
+        elif provider_lower in ("anthropic", "claude"):
+            self.ANTHROPIC_API_KEY = secret
+            env_key_name = ENV_ANTHROPIC_API_KEY
+            os.environ[ENV_ANTHROPIC_API_KEY] = key
         elif provider_lower == "openrouter":
             self.OPEN_ROUTER_API_KEY = secret
             env_key_name = ENV_OPEN_ROUTER_API_KEY
@@ -177,18 +233,62 @@ class Settings(BaseSettings):
             self.XAI_API_KEY = secret
             env_key_name = ENV_XAI_API_KEY
             os.environ[ENV_XAI_API_KEY] = key
+        elif provider_lower in ("ocr", "vision", "google_vision"):
+            self.OCR_API_KEY = secret
+            self.VISION_API_KEY = secret
+            env_key_name = ENV_OCR_API_KEY
+            os.environ[ENV_OCR_API_KEY] = key
+            os.environ[ENV_VISION_API_KEY] = key
 
         if persist_to_env and env_key_name:
-            try:
-                env_file = get_app_dir() / ".env"
-                lines = []
-                if env_file.exists():
-                    lines = env_file.read_text(encoding="utf-8").splitlines()
-                lines = [line for line in lines if not line.startswith(f"{env_key_name}=")]
-                lines.append(f"{env_key_name}={key}")
-                env_file.write_text("\n".join(lines) + "\n", encoding="utf-8")
-            except Exception as e:
-                logger.warning(f"Could not persist {env_key_name} to .env: {e}")
+            target_env_files = [
+                ROOT_DIR / ".env",
+                get_app_dir() / ".env",
+            ]
+            seen_paths = set()
+            for env_file in target_env_files:
+                try:
+                    resolved = env_file.resolve()
+                    if resolved in seen_paths:
+                        continue
+                    seen_paths.add(resolved)
+
+                    lines = []
+                    if env_file.exists():
+                        lines = env_file.read_text(encoding="utf-8").splitlines()
+
+                    # Determine keys to update
+                    keys_to_update = [env_key_name]
+                    if provider_lower in ("google", "gemini", "vertexai"):
+                        keys_to_update = [ENV_GEMINI_API_KEY, ENV_GOOGLE_API_KEY, ENV_GCP_API_KEY]
+                    elif provider_lower in ("ocr", "vision", "google_vision"):
+                        keys_to_update = [ENV_OCR_API_KEY, ENV_VISION_API_KEY]
+
+                    new_lines = []
+                    updated_set = set()
+                    for line in lines:
+                        replaced = False
+                        for k in keys_to_update:
+                            if (
+                                line.startswith(f"{k}=")
+                                or line.startswith(f"#{k}=")
+                                or line.startswith(f"# {k}=")
+                            ):
+                                new_lines.append(f"{k}={key}")
+                                updated_set.add(k)
+                                replaced = True
+                                break
+                        if not replaced:
+                            new_lines.append(line)
+
+                    # Ensure the primary key is present if not replaced
+                    primary_key = keys_to_update[0]
+                    if primary_key not in updated_set:
+                        new_lines.append(f"{primary_key}={key}")
+
+                    env_file.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+                except Exception as e:
+                    logger.warning(f"Could not persist {env_key_name} to {env_file}: {e}")
 
 
 # Singleton instance